feat(runs): report a live phase for every automation run

[aartem1]

HUMAN:

I checked this by hand on a local stack. First the cases in the screenshots on
the frontend PR (OpenHands/OpenHands#16740) — the phase on the automations
list, on the activity-log rows, and the full label on hover — all driven by
this service. On top of that I ran a real but mocked scenario: a mock
automation whose entrypoint does no real work but reports its phases through
the new endpoint. I watched the phases arrive in order as the run progressed,
and saw a failed run keep the phase it stopped at.

AGENT:

Verified beyond unit tests: pre-commit and the full pytest suite, plus the
end-to-end local dispatch described under "Testing" below.

---

Why

An automation run reports one thing for its entire lifetime: RUNNING. A run
that takes minutes looks identical at second 5 and second 300, and a run that
fails tells you that it failed, never where it stopped — provisioning, the
bundle upload, the entrypoint, or somewhere inside the automation's own code.

This adds a current phase to a run: a short machine code, a human label, and
the moment it was written. The service records its own preparation milestones;
code running inside the sandbox reports the rest through a new endpoint.

Relates to OpenHands/OpenHands#16572. Frontend side: OpenHands/OpenHands#16740

What changed

• Storage — three nullable columns on automation_runs (phase_code,
  phase_label, phase_updated_at) plus migration 016. Nullable with no
  backfill: an existing run simply has no phase, which is the truth.
• Endpoint — POST /v1/runs/{run_id}/phase, authenticated like the
  existing completion callback, 404 for an unknown run and 403 for someone
  else's automation. Every write replaces the whole (code, label) pair —
  last write wins, only the current phase is kept, so there is no history
  table to retain or prune. At least one of code/label is required.
• Service phases — the dispatcher records queued,
  sandbox_provisioning, bundle_upload and entrypoint_start as it
  prepares a run. A failed phase write never fails the run: a phase is
  telemetry, not control flow.
• Preset phases — the prompt and plugin templates report preparing
  and running_agent from inside the sandbox, using the same endpoint any
  custom automation can use.
• Docs — docs/run-phase-reporting.md is the recipe for custom
  entrypoints, including which credential to use.

The credential subtlety worth a reviewer's attention

The sandbox holds two keys. SESSION_API_KEY authenticates to the agent
server; the automation service rejects it. Phase reports must use
AUTOMATION_CALLBACK_API_KEY (local mode) or OPENHANDS_API_KEY (cloud).
Getting this wrong is silent — the POST 401s, the caller swallows it because a
phase must never break a run, and phases simply never appear while every test
stays green. The preset templates and the docs both spell this out.

Testing

• uv run pre-commit run --all-files — clean (yamlfmt, ruff format, ruff
  lint, pycodestyle, pyright).
• uv run pytest tests/ — 1337 passed. 36 of those are new: the endpoint's
  contract (auth, ownership, validation, replacement semantics), the
  dispatcher milestones against a real DB seam, and AST assertions that both
  preset templates emit the phases with the right credential.
• End-to-end on a local stack, not only unit tests: a custom automation
  whose entrypoint is a shell script that does no real work but reports real
  phases through the endpoint. Dispatching it walks
  queued → sandbox_provisioning → bundle_upload → entrypoint_start → preparing → … and finishes COMPLETED in ~56s; a second variant that
  reports FAILED through the completion callback keeps its last phase
  visible on the failed run, which is the point of the feature.

[all-hands-bot]

👋 This PR needs a couple of things fixed before OpenHands can review it:

• the PR description's HUMAN: section needs at least 20 characters describing what you tested, not just the template placeholder

Push an update once this is addressed and this check re-runs automatically.

This is an automated check - no AI was used to generate this comment.