feat(daemon): expose per-run failure diagnostics — od run inspect + endpoint (slice 1 of #5489)

[tomsen02]

Refs #5489. Draft — a concrete reference implementation of the slice-1 shape @lefarcen and I converged on in the proposal, posted to make the product-direction review easier. Not asking to merge ahead of that direction.

Why

Per #5489: the daemon already computes the full failure classification at finalize-time (for retry-policy + telemetry), but the API surface only carried failureCategory / failureDetail. failureStage, retryable, and user_action were telemetry-only — so a self-hoster, or an external agent driving Open Design through od, could not see why a run failed, whether it is safe to retry, or what action to take without reading PostHog/Langfuse. That breaks the UI+CLI dual-track rule and the CLI-as-embeddability-contract principle in AGENTS.md.

What this slice does (backbone: contracts + daemon + CLI + test)

• Carries failureStage / failureRetryable / failureUserAction on the run (same source object as the existing category/detail, server.ts).
• GET /api/runs/:id/diagnostics — a dedicated sub-resource so GET /api/runs/:id stays lean; returns RunDiagnosticsResponse with the full classification (failure is null for a run that did not fail).
• od run inspect <runId> [--json].
• Contracts: RunDiagnosticsResponse + re-export RunFailureStage / RunFailureUserAction (mirrors the existing RunFailureCategory / RunFailureDetail re-exports).

$ od run inspect run_abc
run_abc — failed
failure: auth / invalid_api_key   (stage: first_token_wait)
retryable: no
suggested action: login

The 2/5 → 5/5 split (per the proposal thread)

This carries the bounded failure classification only. Availability matches GET /api/runs/:id (the live run registry), so it sidesteps the persistence seam entirely. The heavier timing-segment + token/cache breakdown — which is fire-and-forget into telemetry today and needs the storage decision (persist to SQLite under the RUNTIME_DATA_DIR contract vs in-memory only) — is deliberately not in this slice.

Deliberately deferred (call these out for review)

• Web diagnostics panel (+ its i18n across 18 locales): held until the shape is blessed, so the panel and the timing/token fields land together rather than churning the UI twice. The dual-track intent is met by od run inspect here + the panel in the follow-up.
• Durable / timing / token slice: separate PR, gated on the storage decision.

Scope boundaries

Pure exposure — no new computation, no change to classification logic (stays out of the accuracy-tuning lane #4966 / #5223 / #5356). Complementary to #5321 (which surfaces category/detail as chat guidance), not a duplicate.

Validation

• pnpm --filter @open-design/daemon typecheck (both tsconfigs) — clean
• pnpm guard — 78/78
• apps/daemon/tests/run-diagnostics-endpoint.test.ts — green 3/3: fails a run through a fake claude over the production HTTP API, asserts /diagnostics now carries stage / retryable / userAction (control: the plain status endpoint does not).

Happy to adjust the endpoint shape, field names, or the persistence/UI phasing once the product direction lands.

Surface area

• CLI — od run inspect
• API / contract — GET /api/runs/:id/diagnostics + RunDiagnosticsResponse
• UI — deferred to the follow-up (see above)