feat: surface OpenCode provider limit errors (#2167)

This commit is contained in:
Carlos Florêncio
2026-08-02 21:48:14 +01:00
committed by GitHub
parent e68d3f1d8f
commit b5631da7ee
48 changed files with 2218 additions and 101 deletions
@@ -0,0 +1,267 @@
---
spec: docs/specs/agent-stall-recovery/spec.md
decision: docs/decisions/2026-08-02-agent-terminal-diagnostics-over-stderr.md
created: 2026-08-02
status: done
---
# Implementation Plan: OpenCode Terminal Error Surfacing
## Overview
Enable OpenCode's error-only stderr output, normalize only session-correlated
foreground `stream error` records inside agentctl, and use that terminal signal
to release a prompt whose ACP request never returns. Carry a bounded safe
provider-error record through the existing lifecycle, classify usage-limit
messages, and render a localized recovery card with collapsed technical details
on desktop and mobile. Ambiguous silence continues to use the shipped advisory
stall notice.
---
## Backend
### Managed OpenCode diagnostic output
- Change `OpenCodeACP.ManagedNPMRuntime` in
`apps/backend/internal/agent/agents/opencode_acp.go` so every managed OpenCode
ACP entry point uses `acp --print-logs --log-level ERROR`. Because normal
launch, capability probes, and one-shot inference all consume this shared
runtime spec, none may construct a divergent OpenCode command.
- Update the command contracts in
`apps/backend/internal/agent/agents/opencode_acp_test.go`,
`apps/backend/internal/agent/agents/managed_npm_runtime_test.go`,
`apps/backend/internal/agent/runtime/lifecycle/manager_launch_test.go`, and
`apps/backend/internal/agent/agents/ACP_BRIDGE_VERSIONS.md`.
### Non-blocking stderr observation
- Add an optional `StderrLineConsumer` interface beside `StderrProvider` in
`apps/backend/internal/agentctl/server/adapter/adapter.go`. The interface
receives an ANSI-stripped line as it is appended to the existing bounded
stderr ring; it is not a browser API and does not expose historical files.
- Update `Manager.readStderr` in
`apps/backend/internal/agentctl/server/process/manager.go` to deliver each
cleaned line to an installed consumer without allowing parsing or channel
backpressure to block draining the child process. For OpenCode, apply a
protocol-specific safe projection before generic logging, the recent-stderr
ring, or process-exit events; malformed or unrelated records are excluded.
Other managed agents retain their existing stderr behavior.
- Add focused process-manager regressions proving delivery, ANSI stripping,
non-consumer behavior, and that a nonzero OpenCode exit cannot expose raw
workspace URLs or identifiers through logs or exit events.
### OpenCode diagnostic normalization and prompt correlation
- Add `apps/backend/internal/agentctl/server/adapter/transport/acp/opencode_stderr.go`
with a narrow key/value parser for OpenCode's emitted error records. Accept a
record only when `level=ERROR`, `message="stream error"`, `small` is not
`true`, `session.id` is present, and `error.error` is non-empty. Parse the
timestamp, provider ID, and model ID; strip URLs and identifier-bearing
suffixes from the error text before constructing the normalized record.
- Add a protocol-neutral safe record in
`apps/backend/internal/agentctl/types/streams/provider_error.go` and attach it
optionally to `streams.AgentEvent`. Fields are limited to `source`,
`provider_id`, `model_id`, `message`, `occurred_at`, and `reset_at`.
- Let the ACP adapter implement `StderrLineConsumer` only for
`agentID == "opencode-acp"`. Route a validated diagnostic to the current
prompt only when its provider session ID equals the adapter's active ACP
session and a foreground prompt turn is still pending. The delivery path must
be non-blocking and must discard stale lines after the prompt settles.
- Extend the prompt-turn wait in
`apps/backend/internal/agentctl/server/adapter/transport/acp/adapter_prompt.go`
so a correlated terminal diagnostic competes with the ACP RPC and user
cancellation. Whichever terminal path claims the prompt first cancels the
losing operation, preserves generation ownership, and emits one outcome.
- Return a typed prompt error carrying the safe provider-error record. Update
`handleWSPrompt` and `Manager.SendErrorEvent` in
`apps/backend/internal/agentctl/server/api/agent.go` and
`apps/backend/internal/agentctl/server/process/manager.go` so the existing
error event includes those structured details. Do not send a second error if
the ACP RPC loses the race after the diagnostic has settled the prompt.
### Lifecycle propagation and quota classification
- Add the optional safe provider-error record to `AgentExecution`,
`AgentEventPayload`, and `watcher.AgentEventData` in
`apps/backend/internal/agent/runtime/lifecycle/types.go`,
`apps/backend/internal/agent/runtime/lifecycle/event_types.go`,
`apps/backend/internal/agent/runtime/lifecycle/events.go`, and
`apps/backend/internal/orchestrator/watcher/watcher.go`. Also add `AgentID` to
the lifecycle payload so downstream classification uses `opencode-acp`
rather than inferring an agent from prose.
- In `manager_events.go`, copy structured details from the winning generation's
error event before `MarkCompleted` publishes `agent.failed`. Do not retain
details from a stale generation or a later duplicate terminal event.
- Extend `apps/backend/internal/agent/runtime/routingerr/rules.go` so OpenCode's
exact `usage limit reached` signature classifies as high-confidence
`quota_limited`. Preserve the existing sanitizer and ensure account/workspace
URLs and long identifiers never enter `RawExcerpt`.
- In `createRecoveryStatusMessage` in
`apps/backend/internal/orchestrator/event_handlers_agent.go`, classify the
failure using the event's `AgentID`, validate the structured provider record,
and persist the existing recovery actions with metadata:
`failure_kind: provider_quota_limited`, safe `provider_name`, optional
`model_id`, optional RFC3339 `reset_at`, and bounded sanitized `error_output`.
Fall back to the generic recoverable-error card when classification or
structured correlation is absent.
- Continue using the current `MarkCompleted` -> `agent.failed` ->
`handleRecoverableFailure` path. Non-Office sessions become
`WAITING_FOR_INPUT`; Office sessions keep their existing `FAILED` behavior.
This feature does not invent a second lifecycle state or retry loop.
---
## Frontend
### Localized provider-limit recovery
- Extend `ActionMeta` / `MessageAction` metadata typing in
`apps/web/components/task/chat/types.ts` and
`apps/web/components/task/chat/messages/action-message.tsx` for the safe
provider-limit fields.
- Add a `ProviderQuotaRecovery` branch beside `MissingBranchRecovery`. It uses
`failure_kind`, not string matching, to render a localized heading naming the
model when available, localized reset guidance when `reset_at` is present,
the existing recovery actions, and the existing collapsed **Technical
details** disclosure for sanitized `error_output`.
- Add all new copy to `apps/web/src/locales/en/chat.json` and
`apps/web/src/locales/pseudo/chat.json`; resolve chat keys through
`useTranslation` at render time. Do not translate tokens that are compared
in control flow.
- Keep the generic settled-error behavior unchanged for unknown provider
failures and keep the existing neutral running-stall notice unchanged.
### Mobile design contract
- **Desktop outcome:** the active spinner disappears when the correlated error
settles the turn. A compact error card identifies the affected model and
reset timing, keeps sanitized technical details collapsed, and exposes the
existing recovery actions.
- **Mobile entry point and outcome:** the same card appears inline in the task
chat. No drawer or route is added; quota recovery is short, contextual
content already owned by the chat transcript.
- **Nearest shipped exemplars:** `MissingBranchRecovery` supplies the localized
alert-card/details composition, while
`mobile-transient-retry.spec.ts` and
`mobile-pause-resume-recovery.spec.ts` supply the phone recovery-action and
geometry patterns.
- **Hierarchy and geometry:** heading, reset guidance, collapsed details, then
recovery actions. Chat remains the single scroll owner; technical output has
its own bounded vertical overflow only when expanded. Mobile actions retain
the existing full-width 44px touch geometry, and the page gains no horizontal
overflow.
- **Shared logic:** metadata interpretation, reset-time formatting, details,
and action handlers are shared across viewports; only responsive classes
control layout.
---
## Tests
- **What:** every managed OpenCode ACP command enables error-only stderr while
other managed agents remain unchanged.
**Files:** `apps/backend/internal/agent/agents/opencode_acp_test.go`,
`managed_npm_runtime_test.go`, and lifecycle launch tests.
**How:** exact argv assertions across runtime, probe, and inference builders.
- **What:** process stderr reaches an optional consumer as cleaned live lines
without changing the bounded recent-stderr contract.
**File:** `apps/backend/internal/agentctl/server/process/manager_test.go` or a
focused sibling test.
**How:** fixture process writes ANSI stderr; assertions cover ordered delivery,
no consumer, bounded ring behavior, a backlogged diagnostic channel that does
not block the drain loop, and a nonzero OpenCode exit whose log, ring, and
exit event contain only the safe projection.
- **What:** only a main-session OpenCode stream error is normalized.
**File:** `apps/backend/internal/agentctl/server/adapter/transport/acp/opencode_stderr_test.go`.
**How:** table tests cover the observed quota line, quoted fields, URL
sanitization, `small=true`, wrong level/message, missing fields, malformed
input, and unrelated session IDs.
- **What:** a correlated diagnostic releases a held prompt exactly once while
stale/background/wrong-session diagnostics do not.
**File:** `apps/backend/internal/agentctl/server/adapter/transport/acp/adapter_prompt_test.go`.
**How:** fake ACP agent holds `session/prompt`; inject stderr through the
consumer and race it against RPC completion and cancellation.
- **What:** structured provider details survive the lifecycle event boundary
only for the winning prompt generation.
**Files:** lifecycle `manager_events_test.go`, event publisher tests, and
orchestrator watcher tests.
**How:** direct error events with matching and stale generations.
- **What:** `usage limit reached` becomes high-confidence `quota_limited`, raw
excerpts are sanitized, and recovery metadata contains only safe model/reset
fields plus existing actions.
**Files:** `routingerr/classify_test.go` and
`orchestrator/event_handlers_test.go` or a focused provider-failure test.
**How:** table classifier tests plus direct recoverable-failure handler tests.
- **What:** provider quota metadata renders localized model/reset copy,
collapsed sanitized details, and 44px recovery actions without changing
generic errors or running stall notices.
**File:** `apps/web/components/task/chat/messages/action-message.test.tsx`.
**How:** store-backed rendered component tests using English and pseudo
locale fixtures.
## E2E Tests
- **Scenario:** given a settled OpenCode quota failure, opening the task shows
model/reset guidance rather than a running spinner; expanding technical
details reveals the sanitized message but no OpenCode workspace URL or ID.
**File:** `apps/web/e2e/tests/session/provider-quota-recovery.spec.ts`.
- **Scenario:** the same provider-limit explanation, details disclosure, and
recovery actions are usable by touch with no horizontal overflow.
**File:** `apps/web/e2e/tests/session/mobile-provider-quota-recovery.spec.ts`.
- Seed the settled session and persisted status-message metadata through the
existing E2E-only task/session/message helpers. Do not require a live quota
exhaustion or write provider credentials; the real stderr-to-error boundary
is covered by the agentctl and lifecycle integration tests.
## Verification Results
- Task 01: `cd apps/backend && go test ./internal/agent/agents ./internal/agentctl/server/process ./internal/agentctl/server/adapter/transport/acp -run 'Test(OpenCode|ManagedNPMRuntime|Manager.*Stderr|ParseOpenCode)' -count=1` — 24 tests passed.
- Task 02: `cd apps/backend && go test ./internal/agentctl/server/adapter/transport/acp ./internal/agentctl/server/api ./internal/agentctl/server/process -run 'Test(OpenCodeDiagnostic|Prompt.*Diagnostic|HandleWSPrompt.*ProviderError|SendErrorEvent)' -count=1` — 3 tests passed.
- Task 03: `cd apps/backend && go test ./internal/agent/runtime/lifecycle ./internal/agent/runtime/routingerr ./internal/orchestrator ./internal/orchestrator/watcher -run 'Test(.*ProviderError|.*OpenCode.*UsageLimit|HandleRecoverableFailure.*Quota|CreateRecoveryStatusMessage.*Quota)' -count=1` — 13 tests passed.
- Task 04: `cd apps && pnpm --filter @kandev/web test -- --run components/task/chat/messages/action-message.test.tsx` — 17 tests passed; `cd apps/web && pnpm run typecheck`, `pnpm run i18n:check`, and `pnpm run i18n:ratchet` passed.
- Task 05: managed desktop and mobile Playwright runs passed after the E2E seed was corrected to include `completed_at`: one Chromium test and one `mobile-chrome` test passed.
- Fixup: `cd apps/backend && go test ./internal/agent/agents ./internal/agentctl/server/process ./internal/agentctl/server/adapter/transport/acp -run 'Test(OpenCode|ManagedNPMRuntime|Manager.*Stderr|ManagerProcessExit|ParseOpenCode)' -count=1` — 26 tests passed; `go test ./...` passed with 10,237 tests.
## Implementation Waves And Parallel Candidates
Execution is sequential in the primary conversation. Each task consumes a
contract introduced by the previous task, so none is marked parallel-safe.
Wave 1:
- [x] [Task 01: Capture OpenCode error diagnostics](task-01-capture-opencode-error-diagnostics.md)
Wave 2:
- [x] [Task 02: Settle prompts from correlated diagnostics](task-02-settle-correlated-opencode-prompt.md)
Wave 3:
- [x] [Task 03: Classify and persist provider failures](task-03-classify-provider-failure.md)
Wave 4:
- [x] [Task 04: Render localized quota recovery](task-04-render-provider-quota-recovery.md)
Wave 5:
- [x] [Task 05: Prove desktop and mobile recovery](task-05-e2e-provider-quota-recovery.md)
## Risks and non-goals
- OpenCode's stderr record is an agent compatibility dialect. Parsing fails
closed: a format change loses the immediate error but cannot fail an
unrelated turn.
- The stderr reader must never block, because blocking it can deadlock the
supervised process; the OpenCode diagnostic channel is bounded and its
consumer drops records when backlogged.
- Prompt RPC completion, user cancellation, and the diagnostic may race; prompt
generation ownership and a single terminal claim are correctness boundaries.
- Only the sanitized normalized provider record crosses agentctl. OpenCode raw
stderr is inspected in memory by its parser but is never written to generic
logs, the recent-stderr ring, process-exit events, persisted recovery
metadata, or browser payloads.
- The plan does not read OpenCode log files, add an automatic model switch,
schedule reset-time retries, change Office routing, or replace the upstream
ACP fix.
@@ -0,0 +1,90 @@
---
id: "01-capture-opencode-error-diagnostics"
title: "Capture OpenCode error diagnostics"
status: done
wave: 1
depends_on: []
plan: "plan.md"
spec: "../../specs/agent-stall-recovery/spec.md"
---
# Task 01: Capture OpenCode error diagnostics
## Acceptance
- Every managed OpenCode ACP command enables `--print-logs --log-level ERROR`,
while other managed agent commands remain unchanged.
- Agentctl delivers cleaned live stderr lines to an optional consumer without
blocking child-process drainage or changing the bounded recent-stderr API.
- For OpenCode, generic logs, recent-stderr, and nonzero-exit events contain
only the parser's safe provider-message projection; unrecognized records are
excluded so workspace URLs and identifiers cannot leak through the fallback
error path.
- The OpenCode parser accepts only foreground `stream error` records and
returns allowlisted, URL-free provider/model/message/timestamp/reset fields;
background, malformed, and unrelated records are rejected.
## Verification
- `cd apps/backend && go test ./internal/agent/agents ./internal/agentctl/server/process ./internal/agentctl/server/adapter/transport/acp -run 'Test(OpenCode|ManagedNPMRuntime|Manager.*Stderr|ManagerProcessExit|ParseOpenCode)'`
Use TDD: command-contract, stderr-delivery, and parser tests must fail before
their production changes are added.
## Files likely touched
- `apps/backend/internal/agent/agents/opencode_acp.go`
- `apps/backend/internal/agent/agents/opencode_acp_test.go`
- `apps/backend/internal/agent/agents/managed_npm_runtime_test.go`
- `apps/backend/internal/agent/agents/ACP_BRIDGE_VERSIONS.md`
- `apps/backend/internal/agent/runtime/lifecycle/manager_launch_test.go`
- `apps/backend/internal/agentctl/server/adapter/adapter.go`
- `apps/backend/internal/agentctl/server/process/manager.go`
- `apps/backend/internal/agentctl/server/process/manager_test.go`
- `apps/backend/internal/agentctl/server/adapter/transport/acp/opencode_stderr.go`
- `apps/backend/internal/agentctl/server/adapter/transport/acp/opencode_stderr_test.go`
- `apps/backend/internal/agentctl/types/streams/provider_error.go`
- `apps/backend/internal/agentctl/types/streams/agent.go`
## Dependencies
None.
## Parallelism
Sequential. Task 02 consumes the parser, consumer, and safe provider-error
contract introduced here.
## Inputs
- Spec sections `Correlated terminal diagnostics`, `Diagnostic contract`, and
diagnostic failure-mode scenarios
- ADR-2026-08-02 stderr ownership, correlation, and sanitization rules
- Existing `Manager.readStderr`, `StderrProvider`, `ManagedNPMRuntimeSpec`, and
ACP adapter construction patterns
## Risks
- `readStderr` is a process-liveness boundary; consumer delivery must remain
non-blocking, including when the bounded provider-diagnostic channel is full.
- The parser must not preserve the OpenCode workspace URL or identifiers found
in the observed `error.error` suffix.
- The generic process-exit path must consume only the safe OpenCode projection;
raw stderr must never appear in logs, the recent-stderr ring, or exit events.
## Output contract
Report RED assertions, exact argv, normalized field allowlist, rejected record
cases, test results, files changed, blockers, and risks. Mark this task `done`
and update its plan checkbox in the same conversation.
## Results
The managed command contract, optional stderr consumer, parser privacy,
bounded-channel, and nonzero-exit projection cases all have focused
regressions. OpenCode now uses `acp --print-logs --log-level ERROR`; the parser
keeps only the validated foreground
session/provider/model/message/timestamp/reset fields and rejects title,
`small=true`, malformed, unrelated, or incomplete records. The focused
verification passed with 26 tests across three packages; the full backend
suite also passed.
@@ -0,0 +1,79 @@
---
id: "02-settle-correlated-opencode-prompt"
title: "Settle correlated OpenCode prompts"
status: done
wave: 2
depends_on: ["01-capture-opencode-error-diagnostics"]
plan: "plan.md"
spec: "../../specs/agent-stall-recovery/spec.md"
---
# Task 02: Settle Prompts From Correlated Diagnostics
## Acceptance
- A validated OpenCode diagnostic settles only the pending foreground prompt
whose active ACP session ID matches the diagnostic.
- Diagnostic, ACP response, and user-cancel races emit exactly one terminal
result for the owning prompt generation and release the losing operation.
- The resulting agent error event carries the safe provider-error record;
wrong-session, background, stale, post-settlement, and non-OpenCode lines do
not affect the prompt.
## Verification
- `cd apps/backend && go test ./internal/agentctl/server/adapter/transport/acp ./internal/agentctl/server/api ./internal/agentctl/server/process -run 'Test(OpenCodeDiagnostic|Prompt.*Diagnostic|HandleWSPrompt.*ProviderError|SendErrorEvent)'`
Use a fake ACP agent that intentionally holds `session/prompt`; do not call a
real provider or depend on wall-clock stall detection.
## Files likely touched
- `apps/backend/internal/agentctl/server/adapter/transport/acp/adapter.go`
- `apps/backend/internal/agentctl/server/adapter/transport/acp/adapter_prompt.go`
- `apps/backend/internal/agentctl/server/adapter/transport/acp/adapter_prompt_cancel.go`
- `apps/backend/internal/agentctl/server/adapter/transport/acp/opencode_stderr.go`
- `apps/backend/internal/agentctl/server/adapter/transport/acp/opencode_stderr_test.go`
- `apps/backend/internal/agentctl/server/adapter/transport/acp/adapter_prompt_test.go`
- `apps/backend/internal/agentctl/server/api/agent.go`
- `apps/backend/internal/agentctl/server/api/agent_test.go`
- `apps/backend/internal/agentctl/server/process/manager.go`
- `apps/backend/internal/agentctl/server/process/manager_test.go`
- `apps/backend/internal/agentctl/types/streams/provider_error.go`
## Dependencies
Task 01.
## Parallelism
Sequential. Task 03 consumes the structured terminal event created here.
## Inputs
- Spec scenarios for active, wrong-session, background, stale, and racing
diagnostics
- Plan section `OpenCode diagnostic normalization and prompt correlation`
- Existing prompt-turn gate, generation claim, cancel acknowledgement, async
`handleWSPrompt`, and `SendErrorEvent` paths
## Risks
- A losing `conn.Prompt` goroutine must receive cancellation and cannot retain a
prompt gate, trace span, or later error delivery.
- Stderr delivery cannot block on the prompt consumer channel.
## Output contract
Report RED race assertions, correlation rules, single-terminal proof, exact
tests, files changed, blockers, and risks. Mark this task `done` and update its
plan checkbox in the same conversation.
## Results
The ACP adapter correlates diagnostics to the active ACP session and prompt
turn, cancels the held RPC through its context cause, and forwards one typed
provider error through the existing async prompt event. Wrong-session and
post-settlement diagnostics are ignored; duplicate lifecycle terminal events
are guarded by prompt generation. The exact verification command passed with
3 tests across three packages.
@@ -0,0 +1,82 @@
---
id: "03-classify-provider-failure"
title: "Classify and persist provider failures"
status: done
wave: 3
depends_on: ["02-settle-correlated-opencode-prompt"]
plan: "plan.md"
spec: "../../specs/agent-stall-recovery/spec.md"
---
# Task 03: Classify and Persist Provider Failures
## Acceptance
- The winning generation's safe provider-error record and concrete agent ID
reach `agent.failed`; stale or duplicate terminal events cannot replace them.
- OpenCode `usage limit reached` classifies as high-confidence
`quota_limited`, with the existing sanitizer removing URLs and long
identifiers from every persisted excerpt.
- Non-Office recovery messages persist `provider_quota_limited` metadata with
only safe provider/model/reset/details fields and existing recovery actions;
absent or unrecognized details use the generic error card.
## Verification
- `cd apps/backend && go test ./internal/agent/runtime/lifecycle ./internal/agent/runtime/routingerr ./internal/orchestrator ./internal/orchestrator/watcher -run 'Test(.*ProviderError|.*OpenCode.*UsageLimit|HandleRecoverableFailure.*Quota|CreateRecoveryStatusMessage.*Quota)'`
Use TDD at the lifecycle event, classifier, watcher, and persisted-message
boundaries. Assert the observed OpenCode workspace URL and identifier are
absent from error messages, raw excerpts, and message metadata.
## Files likely touched
- `apps/backend/internal/agent/runtime/lifecycle/types.go`
- `apps/backend/internal/agent/runtime/lifecycle/event_types.go`
- `apps/backend/internal/agent/runtime/lifecycle/events.go`
- `apps/backend/internal/agent/runtime/lifecycle/manager_events.go`
- `apps/backend/internal/agent/runtime/lifecycle/manager_events_test.go`
- `apps/backend/internal/agent/runtime/routingerr/rules.go`
- `apps/backend/internal/agent/runtime/routingerr/classify_test.go`
- `apps/backend/internal/orchestrator/watcher/watcher.go`
- `apps/backend/internal/orchestrator/watcher/watcher_test.go`
- `apps/backend/internal/orchestrator/event_handlers_agent.go`
- `apps/backend/internal/orchestrator/event_handlers_test.go`
## Dependencies
Task 02.
## Parallelism
Sequential. Task 04 consumes the persisted metadata contract defined here.
## Inputs
- Spec `Diagnostic contract`, persistence guarantees, and quota scenarios
- Plan sections `Lifecycle propagation and quota classification` and Tests
- Existing `MarkCompleted`, `newAgentEventPayload`, `routingerr.Classify`,
`handleRecoverableFailure`, and `createRecoveryStatusMessage` paths
## Risks
- Provider classification must use the concrete `opencode-acp` agent ID and
must not infer trust from arbitrary error prose.
- Raw recent stderr remains outside the persisted safe record.
## Output contract
Report RED assertions, event and metadata shapes, classification rule and
confidence, sanitization proof, exact tests, files changed, blockers, and
risks. Mark this task `done` and update its plan checkbox in the same
conversation.
## Results
The safe provider record and concrete `opencode-acp` ID now reach
`agent.failed`. The exact five-hour usage-limit signature is high-confidence
`quota_limited`; URL/session/workspace identifiers are redacted before
persistence. Non-Office recovery metadata includes only the specialized
failure kind, provider/model/reset values, sanitized details, and existing
actions. The exact verification command passed with 13 tests across four
packages.
@@ -0,0 +1,76 @@
---
id: "04-render-provider-quota-recovery"
title: "Render localized quota recovery"
status: done
wave: 4
depends_on: ["03-classify-provider-failure"]
plan: "plan.md"
spec: "../../specs/agent-stall-recovery/spec.md"
---
# Task 04: Render Localized Quota Recovery
## Acceptance
- `provider_quota_limited` metadata renders localized model/reset guidance,
existing recovery actions, and sanitized technical details collapsed by
default; no raw OpenCode URL or identifier is displayed.
- Unknown provider failures retain the generic settled-error card, and running
inactivity notices retain their neutral compact behavior.
- Desktop and phone use the same logic; phone actions remain at least 44px,
expanded details stay within the chat width, and no workflow depends on
hover.
## Verification
- `cd apps && pnpm install --frozen-lockfile`
- `cd apps && pnpm --filter @kandev/web test -- --run components/task/chat/messages/action-message.test.tsx`
- `cd apps/web && pnpm run typecheck`
Use TDD for provider metadata, missing model/reset fallbacks, details
disclosure, generic-error preservation, and pseudo-locale rendering.
## Files likely touched
- `apps/web/components/task/chat/types.ts`
- `apps/web/components/task/chat/messages/action-message.tsx`
- `apps/web/components/task/chat/messages/action-message.test.tsx`
- `apps/web/src/locales/en/chat.json`
- `apps/web/src/locales/pseudo/chat.json`
## Dependencies
Task 03.
## Parallelism
Sequential. Task 05 validates this presentation and its backend metadata.
## Inputs
- Spec provider-limit desktop/mobile scenarios
- Plan `Localized provider-limit recovery` and mobile design contract
- Existing `MissingBranchRecovery`, `TechnicalDetails`, `ActionButtons`, and
`useTranslation("chat")` patterns
## Risks
- Reset timestamps must be formatted at render time and must not call `t()` at
module scope.
- The safe technical string is display-only; control flow must use
`failure_kind` rather than translated copy or substring matching.
## Output contract
Report RED assertions, translation keys, desktop/mobile hierarchy, technical
details behavior, exact test/typecheck results, files changed, blockers, and
risks. Mark this task `done` and update its plan checkbox in the same
conversation.
## Results
Added the localized `ProviderQuotaRecovery` inline card with model/reset
fallbacks, collapsed technical details, existing recovery actions, and shared
desktop/mobile layout. Unknown failures and running stall notices retain their
existing renderers. The focused component suite passed all 17 tests; web
typecheck, i18n key/pseudo checks, and the new-code ratchet passed.
@@ -0,0 +1,78 @@
---
id: "05-e2e-provider-quota-recovery"
title: "Prove desktop and mobile quota recovery"
status: done
wave: 5
depends_on:
- "03-classify-provider-failure"
- "04-render-provider-quota-recovery"
plan: "plan.md"
spec: "../../specs/agent-stall-recovery/spec.md"
---
# Task 05: Prove Desktop and Mobile Recovery
## Acceptance
- Desktop Playwright proves a settled OpenCode quota failure replaces the
running status with model/reset guidance, keeps technical details collapsed,
and reveals no workspace URL or identifier when expanded.
- Mobile Playwright proves the same information and recovery actions are
reachable by touch, actions are at least 44px, expanded details remain
viewport-contained, and the document has no horizontal overflow.
- Tests use E2E-only session/message seeding and never exhaust real provider
quota, read a developer's OpenCode log, or add a production test hook.
## Verification
- `cd apps && pnpm install --frozen-lockfile`
- `cd apps/web && pnpm e2e:run --no-build tests/session/provider-quota-recovery.spec.ts`
- `cd apps/web && pnpm e2e:run --no-build --project mobile-chrome tests/session/mobile-provider-quota-recovery.spec.ts`
Run against freshly built backend and Vite artifacts through the managed E2E
runner. Inspect the rendered phone viewport in addition to assertions.
## Files likely touched
- `apps/web/e2e/pages/session-page.ts`
- `apps/web/e2e/tests/session/provider-quota-recovery.spec.ts`
- `apps/web/e2e/tests/session/mobile-provider-quota-recovery.spec.ts`
## Dependencies
Tasks 03 and 04.
## Parallelism
Sequential. This is the integrated user-visible proof for the completed
backend and frontend contracts.
## Inputs
- Spec desktop/mobile quota scenarios and privacy guarantees
- Plan E2E section and mobile design contract
- Existing `seedTaskSession`, `seedSessionMessage`, missing-branch technical
details, transient-retry, and mobile pause/recovery patterns
## Risks
- Seed only the safe normalized metadata contract; do not copy the real
OpenCode workspace URL or account identifier into fixtures.
- A passing seeded UI test does not replace Task 02's real prompt-boundary
integration regression.
## Output contract
Report RED failures, exact desktop/mobile results, rendered mobile inspection,
privacy assertions, files changed, blockers, risks, and teardown evidence.
Mark this task `done`, update its plan checkbox, and synchronize the plan's
verification results in the same conversation.
## Results
Added E2E-only seeded desktop and mobile specs. Both managed production-build
runs passed: Chromium verifies the localized card, collapsed/expanded privacy
details, and recovery actions; `mobile-chrome` verifies touch disclosure,
44px actions, viewport containment, and no horizontal overflow. The first run
found and fixed a fixture requirement for `completed_at`; no provider quota or
developer log was used.