dreampiler/kandev
1
0
Fork 0
Code Issues 43 Pull Requests Actions 6 Packages Projects Releases Wiki Activity

fix: retain session failures across recovery surfaces (#3669)

Browse Source
This commit is contained in:
Carlos Florêncio
2026-09-15 09:36:47 +01:00
committed by GitHub
parent 54e2e21f32
commit eeeb6f5586
101 changed files with 4057 additions and 1704 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/plans/contribution-resume-recovery/plan.md
+6
View File
@@ -298,3 +298,9 @@ Verification passed:
copy and sanitized details; never infer a specific Git diagnosis from them.
- Exact contributor history and the actor who changed it were not established.
Neither is necessary to reproduce the product defects.
## September 14 presentation successor
The [error scope package](../error-scope-and-history/plan.md) supersedes the session card placement and removal behavior.
Completed results here remain historical evidence. Provider recovery, timeout budgets, cancellation, and authorization remain unchanged.
The successor owns chronological error retention, ordinary scroll behavior, and shared task alerts.
docs/plans/error-scope-and-history/plan.md
+203
View File
@@ -0,0 +1,203 @@
---
created: 2026-09-14
status: complete
requirements:
- REQ-AGENTS-AGENT-RESUME-RUNTIME-RECOVERY-006
- REQ-TASKS-TASK-LAUNCH-FAILURE-RECOVERY-002
system_design:
- ../../specs/agents/system-design/session-recovery-failures.md
- ../../specs/tasks/system-design/task-launch-failure-recovery.md
legacy_specs: []
---
# Implementation Plan: Error scope and history
## Overview
Retain session errors as chronological messages after recovery. Show shared task errors above all task tabs.
Implement session history first, then the shared task surface, then cross-surface regression coverage and public guidance.
All three sequential work orders are complete. This document records the implementation and verification results for the accepted design package.
## Confirmed intent and ownership
The user chose ordinary session error messages and rejected duplicate banners.
The user requires shared task/workspace failures to remain visible across agent sessions and other tabs.
Tasks own durable failure identity, history, and shared projections. Agents retain recovery eligibility and session presentation.
The proposed shared position is below the task header and above tabs. It covers this task, not every task in the workspace.
No material question blocks this design.
## Evidence and scope
Task ef406dc0-8d8b-41bf-b9f1-39ec4b026ff9 had a saved-session load failure after exactly two minutes on September 14.
The diagnostic bundle showed ACP `session/load` returning `context deadline exceeded`. The underlying provider delay remains unproven.
`task-chat-panel.tsx` passes the recovery card as `prependContent` before the history loader.
`message-list-native-scroll.ts` releases recovery top ownership after user scrolling. Later history restores message position and moves the card away.
`deduplicateRecoveryMessages` removes prior recovery messages after later conversation activity.
`SettledActionMessage` hides its body during STARTING, RUNNING, and COMPLETED states.
The projector retains a separate `taskError`, but the public aggregate can select a newer session error.
In scope: durable session entries, resolved action state, ordinary scrolling, explicit failure scope, shared task projection, all-tab presentation, localization, and regression tests.
Out of scope: provider timeout increases, provider hang diagnosis, automatic conversation replacement, a global alert center, and a multi-incident task queue.
The generic timeout label defect remains a separate diagnostic finding. This package preserves existing sanitized cause semantics.
## Technical approach
Task 01 extends the existing fenced error admission and persisted message path.
Keep one marker per session/stamp, preserve markers after resolution, and render recovery actions only on the current error. Bootstrap failures use the execution-fenced terminal commit and then create the same idempotent session message. If that accepted commit is followed by a transcript write failure, the executor retries the same message identity. Profile-specific pre-agent failures remain session-owned, while shared worktree failures use task scope, and Office sessions use the same history producer.
Remove activity-based error filtering, active-session body hiding, and error-specific scroll placement across task Chat and Quick Chat.
Task 02 adds explicit scope to normalized error metadata and exposes independent `TaskStatusSummary.task_error`.
Project existing task metadata independently of session errors. Preserve aggregate `active_error` compatibility.
Mount one shared task-shell alert with a desktop dialog or phone drawer. Retain existing action authorization and stamp guards. Read the live status summary after hydration, announce each task error stamp once, and remove duplicate mobile top padding while retaining the outer task-shell offset.
Task 03 proves recovery followed by new messages, pagination, reload, tab switching, mixed scopes, and mobile geometry. Its composed panel assertions count persisted recovery rows and provisional notices together, and legacy unstamped rows retain controls only when they match the current session error.
Update public recovery guidance only after the behavior exists.
## ASCII UI preview
UI-01: Desktop task, shared failure plus an independently recovered session error.
```text
+--------------------------------------------------------+
| Task title / workflow | fixed
| ! Workspace preparation failed. [Recovery details] | shared
+--------------------------------------------------------+
| Session A | Session B | Plan | Pull request | Files | tabs
+--------------------------------------------------------+
| Earlier conversation ^ |
| ! Session resume failed. 10:18 | |
| Loading timed out. [Recovery details] | | scrolls
| Recovered. | |
| Agent: I resumed work... v |
+--------------------------------------------------------+
| Message input | fixed
+--------------------------------------------------------+
```
UI-02: Phone task Chat, same two independent failures.
```text
+--------------------------------+
| < Task title Session A v | fixed task chrome
| ! Workspace preparation failed |
| [Recovery details] | shared on every view
+--------------------------------+
| Earlier messages ^ |
| ! Session resume failed | |
| Loading timed out. | | transcript scrolls
| Recovered. [Details] | |
| Agent: I resumed work... v |
+--------------------------------+
| Message input | safe-area clearance
| Chat | Plan | Files | More | existing navigation
+--------------------------------+
```
UI-03: Session entry states, inside either transcript.
```text
Unresolved: ! Resume failed. [Resume] [Recovery details]
Pending: ! Resume failed. Resuming... [Details]
Recovered: ! Resume failed. Recovered. [Details]
Older: ! Resume failed. [Details] (no stale actions)
```
Expanded session details wrap inline. Phone actions stack with 44-pixel targets.
A failed new attempt appends a separate error entry. Same-stamp updates retain position.
UI-04: Shared details, desktop dialog / phone inset bottom drawer.
```text
+--------------------------------+
| Workspace preparation X |
| Affected repository: owner/repo|
| Safe cause and bounded details |
| [Valid recovery action] |
+--------------------------------+
```
The phone drawer has safe-area clearance, an internally scrolling body, and 44-pixel controls.
The desktop dialog uses compact controls. Closing details does not clear the shared alert.
Views map to recovery criteria 006.4/6/7/8/9 and task criteria 002.4/5/6/7.
Fixed versus scrolling regions, scope, order, and retained history are requirements.
Copy and spacing are illustrative and must use localized strings and existing tokens.
The two errors coexist only because they represent different failures.
## Tests
- Session criteria 006.4/7/8/9 and task 002.2/3/8: orchestrator failure persistence, repository fencing, processed-message filtering, action-message, and native-list tests.
- Task 002.1/4/5/6/8: task status projector and rebuild tests, normalized client types, shared alert selection, and task layout tests.
- Existing provider recovery and cancellation tests must preserve action semantics.
- Use failure identity, not text, for duplicate tests. Include missing legacy metadata and a newer failed retry after successful recovery.
## E2E tests
Extend `tests/task/launch-failure-recovery.spec.ts` (chromium) and `tests/task/mobile-launch-failure-recovery.spec.ts` (mobile-chrome).
Task 01 adds retained-history and scroll regressions. Task 02 adds shared-alert navigation and no-session regressions.
Task 03 combines both scopes, reload, delayed events, short viewport, touch actions, and representative preview/Quick Chat coverage.
The work orders specify exact commands and scenario names. Mock provider and workspace failures through existing fixtures.
Use causal waits, not arbitrary sleeps. Rebuild through the managed runner.
## Work orders
- [x] [Task 01: Retain session failure entries](task-01-session-history.md)
- [x] [Task 02: Show shared errors across task tabs](task-02-shared-task-errors.md)
- [x] [Task 03: Verify scope and document recovery](task-03-regressions-and-docs.md)
## Verification results
Implementation is complete. Session failures now remain chronological transcript entries with stamp-scoped controls. Task and workspace preparation failures now project independently to one task-shell surface above task tabs, with desktop dialog and phone drawer details.
The review remediation is included in this completed package. Accepted bootstrap failures now write the same idempotent, safe session-history entry as other recoverable failures, including Office sessions. The panel keeps a provisional error notice only until its persisted message arrives. Status-summary restoration honors explicit task/session scope even when a task error carries an originating session ID. Recovery retirement uses a stamp-fenced write and publishes inactive state only after that write wins.
The review fixup also makes bootstrap admission fail closed when an execution-fenced repository commit is unavailable, repairs an accepted terminal state after a transcript write error, and preserves profile-specific launch failures on their originating session. The shared task surface refreshes from the live summary, emits one assertive announcement per task and stamp, and avoids nested mobile top-bar spacing.
Product verification on September 14:
- `pnpm --filter @kandev/web run build:vite`: passed.
- `pnpm run typecheck`: passed.
- `pnpm run lint`: passed.
- `pnpm run i18n:check`: passed for all five complete catalogs.
- `make lint` and the selected Go package tests for orchestrator, executor, SQLite, and status-summary: passed.
- Review regression tests for bootstrap and Office history, persisted/provisional deduplication, scoped projector clearing, and stale recovery retirement: passed.
- The complete selected Go package run passed: orchestrator, executor, SQLite, and status-summary.
- Focused frontend regression tests passed: 6 files, 96 tests.
- Chromium launch-recovery E2E: 4 passed.
- Mobile Chrome launch-recovery E2E: 3 passed.
- Public documentation validators and specification validators: passed.
- `git diff --check`: passed.
Review-fixup verification on September 14:
- `go test ./internal/orchestrator -count=1`: passed.
- The executor and status-summary package suites: passed.
- The five affected frontend suites: 65 tests passed.
- Frontend typecheck and lint: passed.
- Frontend localization checks and Vite build: passed.
- Legacy FAILED Office rows without structured metadata retain their chronological entry and recovery actions; the focused recovery suites pass with 54 tests.
- Desktop and mobile PR watcher failures now exercise the task-shell error strip and both focused E2E specs pass.
- Remaining CI recovery scenarios now assert their owning surface: the GitHub URL launch failure uses the shared task strip, Kubernetes failures use retained session entries with sanitized technical details, and failed mobile resume uses the persisted recovery entry. Focused follow-up runs pass for Chromium, Mobile Chrome, and the applicable Kubernetes container cases.
The implementation changed production and permanent test files as required by the work orders. The provider timeout diagnosis and repair remain outside this package.
Design validation on September 14:
- `python3 scripts/list-docs.py validate`: passed, 268 decisions and 902 specifications.
- `python3 scripts/lint-spec-files.test.py`: passed, 36 tests.
- `python3 scripts/lint-spec-files.py --all`: passed.
- Work-order requirement, acceptance, and system-design reference checks: passed for all three work orders.
- `git diff --check -- docs/specs docs/decisions docs/plans`: passed.
Task 03 updated the public session and task recovery guidance after implementation.
## Risks
- Duplicate websocket or terminal events can create duplicate history unless the durable write is fenced and idempotent.
- Legacy errors lack stamps or retained markers. Preserve known history without inventing missing incidents.
- Mixed-version aggregates cannot recover an untransmitted shared error. New boot/read/update contracts must agree.
- Dockview maximization and phone navigation must not hide task-shell alerts.
- Broad workspace text matching can misclassify session-only errors. Scope comes from the owner.
- Existing completed plans contain historical reveal tests. Replace affected expectations and preserve unrelated guarantees.
## Related decision
[Error scope and history](../../decisions/2026-09-14-error-scope-and-history.md).
docs/plans/error-scope-and-history/task-01-session-history.md
+183
View File
@@ -0,0 +1,183 @@
---
id: "01-session-history"
title: "Retain session failure entries"
status: complete
wave: 1
depends_on: []
plan: "plan.md"
requirements:
- REQ-AGENTS-AGENT-RESUME-RUNTIME-RECOVERY-006
- REQ-TASKS-TASK-LAUNCH-FAILURE-RECOVERY-002
acceptance_criteria:
- AC-AGENTS-AGENT-RESUME-RUNTIME-RECOVERY-006.1
- AC-AGENTS-AGENT-RESUME-RUNTIME-RECOVERY-006.2
- AC-AGENTS-AGENT-RESUME-RUNTIME-RECOVERY-006.3
- AC-AGENTS-AGENT-RESUME-RUNTIME-RECOVERY-006.4
- AC-AGENTS-AGENT-RESUME-RUNTIME-RECOVERY-006.5
- AC-AGENTS-AGENT-RESUME-RUNTIME-RECOVERY-006.6
- AC-AGENTS-AGENT-RESUME-RUNTIME-RECOVERY-006.7
- AC-AGENTS-AGENT-RESUME-RUNTIME-RECOVERY-006.8
- AC-AGENTS-AGENT-RESUME-RUNTIME-RECOVERY-006.9
- AC-TASKS-TASK-LAUNCH-FAILURE-RECOVERY-002.2
- AC-TASKS-TASK-LAUNCH-FAILURE-RECOVERY-002.3
- AC-TASKS-TASK-LAUNCH-FAILURE-RECOVERY-002.8
system_design:
- ../../specs/agents/system-design/session-recovery-failures.md
- ../../specs/tasks/system-design/task-launch-failure-recovery.md
---
# Task 01: Retain session failure entries
## Summary
Persist and render each accepted session failure as one chronological message. Preserve its body and details after recovery and later output.
## In scope
- Reuse failure admission, stable message identity, and stamp/execution fences. Persist bounded marker metadata before terminal publication.
- Make duplicate same-stamp delivery idempotent. Failed successor attempts receive separate entries.
- Remove message deletion after later activity and state-based body hiding. Separate pending, resolved, and superseded controls from history.
- Migrate bootstrap cards into ordinary rows. Remove only error-specific prepend/reveal branches from detail, preview, simple Chat, and Quick Chat.
- Preserve archived-task guards, provider-specific remediation, confirmation, cancellation, and workspace-only semantics.
- Add localized historical/pending labels in all five catalogs. Generate Traditional Chinese with `pnpm run i18n:zh-hant`.
## Out of scope
Shared task projection, provider hang repair, and timeout changes.
## Acceptance
1. Same-stamp replay creates one persisted entry. Recovery and later output preserve it after reload, with no stale actions.
2. Older history insertion and new messages obey ordinary scroll rules. No recovery-specific forced placement or duplicate banner remains.
3. Desktop and phone preserve details and valid recovery actions, including automatic recovery followed by output.
## ASCII UI preview
UI-01: Desktop task, shared failure plus an independently recovered session error.
```text
+--------------------------------------------------------+
| Task title / workflow | fixed
| ! Workspace preparation failed. [Recovery details] | shared
+--------------------------------------------------------+
| Session A | Session B | Plan | Pull request | Files | tabs
+--------------------------------------------------------+
| Earlier conversation ^ |
| ! Session resume failed. 10:18 | |
| Loading timed out. [Recovery details] | | scrolls
| Recovered. | |
| Agent: I resumed work... v |
+--------------------------------------------------------+
| Message input | fixed
+--------------------------------------------------------+
```
UI-02: Phone task Chat, same two independent failures.
```text
+--------------------------------+
| < Task title Session A v | fixed task chrome
| ! Workspace preparation failed |
| [Recovery details] | shared on every view
+--------------------------------+
| Earlier messages ^ |
| ! Session resume failed | |
| Loading timed out. | | transcript scrolls
| Recovered. [Details] | |
| Agent: I resumed work... v |
+--------------------------------+
| Message input | safe-area clearance
| Chat | Plan | Files | More | existing navigation
+--------------------------------+
```
UI-03: Session entry states, inside either transcript.
```text
Unresolved: ! Resume failed. [Resume] [Recovery details]
Pending: ! Resume failed. Resuming... [Details]
Recovered: ! Resume failed. Recovered. [Details]
Older: ! Resume failed. [Details] (no stale actions)
```
Expanded session details wrap inline. Phone actions stack with 44-pixel targets.
A failed new attempt appends a separate error entry. Same-stamp updates retain position.
UI-04: Shared details, desktop dialog / phone inset bottom drawer.
```text
+--------------------------------+
| Workspace preparation X |
| Affected repository: owner/repo|
| Safe cause and bounded details |
| [Valid recovery action] |
+--------------------------------+
```
The phone drawer has safe-area clearance, an internally scrolling body, and 44-pixel controls.
The desktop dialog uses compact controls. Closing details does not clear the shared alert.
Views map to recovery criteria 006.4/6/7/8/9 and task criteria 002.4/5/6/7.
Fixed versus scrolling regions, scope, order, and retained history are requirements.
Copy and spacing are illustrative and must use localized strings and existing tokens.
The two errors coexist only because they represent different failures.
See the [combined plan](plan.md#ascii-ui-preview). Task 01 implements the views within its scope.
## Verification
Run from the repository root. Install workspace dependencies once before the first package command if this checkout lacks them.
Use `/tdd` for changed logic and `/e2e` for browser work. First establish the regression against current behavior.
```bash
(cd apps/backend && go test ./internal/orchestrator ./internal/orchestrator/executor ./internal/task/repository/sqlite)
(cd apps/web && pnpm exec vitest run hooks/processed-message-filtering.test.ts components/task/chat/messages/action-message.test.tsx components/task/chat/message-list-native.test.tsx components/task/chat/message-list-native-scroll.test.ts components/task/task-chat-panel.launch-error.test.tsx components/quick-chat/quick-chat-session-view.test.tsx)
(cd apps/web && pnpm run typecheck && pnpm run lint && pnpm run i18n:check)
(cd apps/web && pnpm e2e:run --project chromium tests/task/launch-failure-recovery.spec.ts)
(cd apps/web && pnpm e2e:run --project mobile-chrome tests/task/mobile-launch-failure-recovery.spec.ts)
```
## Files likely touched
- `apps/backend/internal/orchestrator/event_handlers_agent.go` and existing failure/resolution tests.
- `apps/backend/internal/orchestrator/executor/executor_launch_failure*` and `apps/backend/internal/task/repository/sqlite/` fenced metadata/message operations.
- `apps/web/hooks/processed-message-filtering.ts` and its test.
- `apps/web/components/task/chat/messages/action-message*`, `session-bootstrap-recovery-card.tsx`, and `message-list-{shared,native,native-scroll}*`.
- `apps/web/components/task/task-chat-panel.tsx`, `simple/task-chat.tsx`, and `components/quick-chat/quick-chat-session-view.tsx`.
- Existing tests named in verification. Add `action-message.test.tsx` if absent.
- `apps/web/src/locales/{en,pt-pt,zh-cn,zh-hk,zh-tw}/task.json`.
- Existing desktop/mobile launch-failure E2E files.
## Dependencies
None.
## Inputs
Read both owning specs linked from the plan and the September 14 scope decision.
Use the existing launch-recovery tests as the fixture pattern.
## Risks
Preserve failure identity, sanitized details, existing recovery guards, and message ordering under reversed delivery.
The shared repository can contain other edits. Do not revert unrelated changes.
## Parallelism
`sequential`
## Results
Complete on September 14, 2026. Session failures are persisted as chronological, stamp-scoped messages. Same-stamp writes are idempotent, resolved entries retain their message and details, and later agent output no longer removes or hides them. The accepted bootstrap terminal path now produces the durable entry with safe bootstrap details and existing recovery choices, and Office failures use the same session-history producer. Profile-specific pre-agent failures retain their session scope. Bootstrap state admission requires an execution-fenced repository commit; when that commit succeeds but the transcript write fails, the executor retries the same idempotent message identity. Recovery-specific transcript reveal and prepend behavior was removed while ordinary older-history anchor restoration remains.
Validation passed:
- Backend orchestrator, executor, SQLite, and status-summary tests passed.
- Focused frontend tests for processed-message filtering, action messages, native scrolling, task chat, Quick Chat, session recovery, and mobile layout passed.
- Frontend typecheck, lint, i18n checks, and Vite build passed.
- Real bootstrap admission, Office failure production, stale retirement fencing, and reload-retained history regressions passed.
- Chromium and Mobile Chrome launch-recovery suites passed with 4 and 3 tests respectively.
- The bootstrap repair regression and the profile-specific session ownership regression passed in the full orchestrator suite.
Review follow-up validation:
- Legacy FAILED Office sessions without `last_agent_error` metadata remain in the timeline with their existing recovery actions. The focused chat, recovery, and simple-chat suites passed 54 tests.
docs/plans/error-scope-and-history/task-02-shared-task-errors.md
+172
View File
@@ -0,0 +1,172 @@
---
id: "02-shared-task-errors"
title: "Show shared errors across task tabs"
status: complete
wave: 2
depends_on:
- 01-session-history
plan: "plan.md"
requirements:
- REQ-TASKS-TASK-LAUNCH-FAILURE-RECOVERY-002
acceptance_criteria:
- AC-TASKS-TASK-LAUNCH-FAILURE-RECOVERY-002.1
- AC-TASKS-TASK-LAUNCH-FAILURE-RECOVERY-002.4
- AC-TASKS-TASK-LAUNCH-FAILURE-RECOVERY-002.5
- AC-TASKS-TASK-LAUNCH-FAILURE-RECOVERY-002.6
- AC-TASKS-TASK-LAUNCH-FAILURE-RECOVERY-002.7
- AC-TASKS-TASK-LAUNCH-FAILURE-RECOVERY-002.8
system_design:
- ../../specs/tasks/system-design/task-launch-failure-recovery.md
---
# Task 02: Show shared errors across task tabs
## Summary
Expose shared failures independently of session errors and render them once in the task shell.
## In scope
- Add optional scope to normalized metadata and wire types. Audit existing task admission, shared preparation, bootstrap, and resume producers.
- Preserve originating session correlation without using it as scope. Legacy sessionless task metadata remains shared.
- Add `task_error` to summary model, projector/rebuild, persistence, boot/HTTP/WS projection, and web state consumers.
- Render a proposed `TaskSharedError` outside tab content, with dialog/Drawer details and existing guarded recovery actions.
- Cover no-session, preview, mobile/tablet, full desktop, maximized panel, and plugin-tab paths.
- Suppress equivalent active controls only by scope and stamp. Preserve unrelated session history and all existing authorization.
- Localize new labels in the five catalogs and generate Traditional Chinese.
## Out of scope
A global notification center, a multi-incident queue, and inferred workspace-wide broadcasts.
## Acceptance
1. A shared failure survives newer session failures, session recovery, reload, and tab switches with unchanged identity.
2. Exactly one shared control surface exists per task view. Same-stamp session controls do not duplicate it.
3. Desktop and phone expose equivalent guarded actions with no overflow and reachable no-session recovery.
## ASCII UI preview
UI-01: Desktop task, shared failure plus an independently recovered session error.
```text
+--------------------------------------------------------+
| Task title / workflow | fixed
| ! Workspace preparation failed. [Recovery details] | shared
+--------------------------------------------------------+
| Session A | Session B | Plan | Pull request | Files | tabs
+--------------------------------------------------------+
| Earlier conversation ^ |
| ! Session resume failed. 10:18 | |
| Loading timed out. [Recovery details] | | scrolls
| Recovered. | |
| Agent: I resumed work... v |
+--------------------------------------------------------+
| Message input | fixed
+--------------------------------------------------------+
```
UI-02: Phone task Chat, same two independent failures.
```text
+--------------------------------+
| < Task title Session A v | fixed task chrome
| ! Workspace preparation failed |
| [Recovery details] | shared on every view
+--------------------------------+
| Earlier messages ^ |
| ! Session resume failed | |
| Loading timed out. | | transcript scrolls
| Recovered. [Details] | |
| Agent: I resumed work... v |
+--------------------------------+
| Message input | safe-area clearance
| Chat | Plan | Files | More | existing navigation
+--------------------------------+
```
UI-03: Session entry states, inside either transcript.
```text
Unresolved: ! Resume failed. [Resume] [Recovery details]
Pending: ! Resume failed. Resuming... [Details]
Recovered: ! Resume failed. Recovered. [Details]
Older: ! Resume failed. [Details] (no stale actions)
```
Expanded session details wrap inline. Phone actions stack with 44-pixel targets.
A failed new attempt appends a separate error entry. Same-stamp updates retain position.
UI-04: Shared details, desktop dialog / phone inset bottom drawer.
```text
+--------------------------------+
| Workspace preparation X |
| Affected repository: owner/repo|
| Safe cause and bounded details |
| [Valid recovery action] |
+--------------------------------+
```
The phone drawer has safe-area clearance, an internally scrolling body, and 44-pixel controls.
The desktop dialog uses compact controls. Closing details does not clear the shared alert.
Views map to recovery criteria 006.4/6/7/8/9 and task criteria 002.4/5/6/7.
Fixed versus scrolling regions, scope, order, and retained history are requirements.
Copy and spacing are illustrative and must use localized strings and existing tokens.
The two errors coexist only because they represent different failures.
See the [combined plan](plan.md#ascii-ui-preview). Task 02 implements the views within its scope.
## Verification
Run from the repository root. Install workspace dependencies once before the first package command if this checkout lacks them.
Use `/tdd` for changed logic and `/e2e` for browser work. First establish the regression against current behavior.
```bash
(cd apps/backend && go test ./internal/task/statussummary ./internal/task/repository/sqlite ./internal/orchestrator)
(cd apps/web && pnpm exec vitest run lib/session-recovery-presentation.test.ts components/task/task-shared-error.test.tsx components/task/task-page-content.test.tsx components/task/mobile/session-mobile-layout.test.tsx components/task/task-chat-panel.launch-error.test.tsx)
(cd apps/web && pnpm run typecheck && pnpm run lint && pnpm run i18n:check)
(cd apps/web && pnpm e2e:run --project chromium tests/task/launch-failure-recovery.spec.ts)
(cd apps/web && pnpm e2e:run --project mobile-chrome tests/task/mobile-launch-failure-recovery.spec.ts)
```
## Files likely touched
- `apps/backend/internal/task/models/models.go` normalized errors and `internal/task/statussummary/{model,projector,projector_helpers,rebuild}.go` plus tests.
- `apps/backend/internal/orchestrator/task_launch_recovery.go`, launch failure producers, and fenced task metadata operations.
- Corresponding boot/HTTP/WS summary serialization and replacement consumers found through `TaskStatusSummary` references.
- `apps/web/lib/types/task-status-summary.ts`, `lib/session-recovery-presentation.ts`, and task summary state tests.
- Proposed `apps/web/components/task/task-shared-error.tsx` and `task-shared-error.test.tsx`.
- `apps/web/components/task/task-page-content.tsx`, `task-layout.tsx`, preview composition, mobile/tablet layouts, and launch-error context.
- Existing task recovery action components, five locale catalogs, and launch-failure E2E files.
## Dependencies
01-session-history.
## Inputs
Read both owning specs linked from the plan and the September 14 scope decision.
Use the existing launch-recovery tests as the fixture pattern.
## Risks
Preserve failure identity, sanitized details, existing recovery guards, and message ordering under reversed delivery.
The shared repository can contain other edits. Do not revert unrelated changes.
## Parallelism
`sequential`
## Results
Complete on September 14, 2026. Normalized failures now carry explicit session or task scope. Task-owned errors are projected independently as `task_error`, preserve originating session correlation, and render once above task content. Baseline restoration and fallback derivation route explicit scope before applying legacy session-ID inference, so clearing task metadata also clears the task-owned active error without a session refresh. The shared surface reads the live summary after hydration and emits one assertive announcement for each task and error stamp. Desktop details use a dialog. Phone details use a safe-area-aware, internally scrolling drawer with touch-sized controls and no nested top-bar padding. Existing recovery guards and legacy sessionless task errors remain supported.
Validation passed:
- Backend status-summary, SQLite, and orchestrator tests passed.
- Frontend summary, recovery presentation, shared-shell, task layout, mobile layout, and launch-entry tests passed.
- Frontend typecheck, lint, i18n checks, and Vite build passed.
- Cold-projector clearing and composed-panel single-representation regressions passed.
- Chromium and Mobile Chrome launch-recovery suites passed with 4 and 3 tests respectively.
- The live-summary replacement, one-announcement remount, and mobile top-bar geometry regressions passed.
docs/plans/error-scope-and-history/task-03-regressions-and-docs.md
+188
View File
@@ -0,0 +1,188 @@
---
id: "03-regressions-and-docs"
title: "Verify scope and document recovery"
status: complete
wave: 3
depends_on:
- 02-shared-task-errors
plan: "plan.md"
requirements:
- REQ-AGENTS-AGENT-RESUME-RUNTIME-RECOVERY-006
- REQ-TASKS-TASK-LAUNCH-FAILURE-RECOVERY-002
acceptance_criteria:
- AC-AGENTS-AGENT-RESUME-RUNTIME-RECOVERY-006.5
- AC-AGENTS-AGENT-RESUME-RUNTIME-RECOVERY-006.6
- AC-AGENTS-AGENT-RESUME-RUNTIME-RECOVERY-006.7
- AC-AGENTS-AGENT-RESUME-RUNTIME-RECOVERY-006.8
- AC-AGENTS-AGENT-RESUME-RUNTIME-RECOVERY-006.9
- AC-TASKS-TASK-LAUNCH-FAILURE-RECOVERY-002.1
- AC-TASKS-TASK-LAUNCH-FAILURE-RECOVERY-002.2
- AC-TASKS-TASK-LAUNCH-FAILURE-RECOVERY-002.3
- AC-TASKS-TASK-LAUNCH-FAILURE-RECOVERY-002.4
- AC-TASKS-TASK-LAUNCH-FAILURE-RECOVERY-002.5
- AC-TASKS-TASK-LAUNCH-FAILURE-RECOVERY-002.6
- AC-TASKS-TASK-LAUNCH-FAILURE-RECOVERY-002.7
- AC-TASKS-TASK-LAUNCH-FAILURE-RECOVERY-002.8
system_design:
- ../../specs/agents/system-design/session-recovery-failures.md
- ../../specs/tasks/system-design/task-launch-failure-recovery.md
---
# Task 03: Verify scope and document recovery
## Summary
Exercise the combined experience and update public recovery guidance after implementation.
## In scope
- Extend the existing desktop/phone suites with retained session history and shared-task error scenarios.
- Named scenarios: `retains session failure after automatic recovery and output`, `preserves reading anchor while older history loads`, `keeps shared failure across session and Plan tabs`, `does not clear shared failure on sibling recovery`, and `legacy failure remains readable`.
- Include a manual retry, another failure stamp, delayed old event, reload with recovery boot outside the loaded page, duplicate delivery, and no-session shared error.
- Assert session error chronology and one action owner. Test short viewport, phone touch size, drawer bounds, focus return, safe areas, and no document overflow.
- Exercise the preview and Quick Chat hosts in the same focused suites using their existing navigation fixtures.
- Update `docs/public/tasks-and-workflows.md` as recovery how-to guidance. Explain retained session history and the task-wide strip.
- Reconcile affected older tests and completed-plan successor notes without rewriting historical test results.
## Out of scope
Broad QA/review, production data mutation, and new provider diagnostics.
## Acceptance
1. Combined desktop and phone scenarios pass against a fresh build, including mixed-scope errors and resumed agent output.
2. Rendered structure matches UI-01 through UI-04. Historical controls cannot affect a newer failure.
3. Public guidance describes shipped behavior. Plan and work-order results record actual commands and outcomes.
## ASCII UI preview
UI-01: Desktop task, shared failure plus an independently recovered session error.
```text
+--------------------------------------------------------+
| Task title / workflow | fixed
| ! Workspace preparation failed. [Recovery details] | shared
+--------------------------------------------------------+
| Session A | Session B | Plan | Pull request | Files | tabs
+--------------------------------------------------------+
| Earlier conversation ^ |
| ! Session resume failed. 10:18 | |
| Loading timed out. [Recovery details] | | scrolls
| Recovered. | |
| Agent: I resumed work... v |
+--------------------------------------------------------+
| Message input | fixed
+--------------------------------------------------------+
```
UI-02: Phone task Chat, same two independent failures.
```text
+--------------------------------+
| < Task title Session A v | fixed task chrome
| ! Workspace preparation failed |
| [Recovery details] | shared on every view
+--------------------------------+
| Earlier messages ^ |
| ! Session resume failed | |
| Loading timed out. | | transcript scrolls
| Recovered. [Details] | |
| Agent: I resumed work... v |
+--------------------------------+
| Message input | safe-area clearance
| Chat | Plan | Files | More | existing navigation
+--------------------------------+
```
UI-03: Session entry states, inside either transcript.
```text
Unresolved: ! Resume failed. [Resume] [Recovery details]
Pending: ! Resume failed. Resuming... [Details]
Recovered: ! Resume failed. Recovered. [Details]
Older: ! Resume failed. [Details] (no stale actions)
```
Expanded session details wrap inline. Phone actions stack with 44-pixel targets.
A failed new attempt appends a separate error entry. Same-stamp updates retain position.
UI-04: Shared details, desktop dialog / phone inset bottom drawer.
```text
+--------------------------------+
| Workspace preparation X |
| Affected repository: owner/repo|
| Safe cause and bounded details |
| [Valid recovery action] |
+--------------------------------+
```
The phone drawer has safe-area clearance, an internally scrolling body, and 44-pixel controls.
The desktop dialog uses compact controls. Closing details does not clear the shared alert.
Views map to recovery criteria 006.4/6/7/8/9 and task criteria 002.4/5/6/7.
Fixed versus scrolling regions, scope, order, and retained history are requirements.
Copy and spacing are illustrative and must use localized strings and existing tokens.
The two errors coexist only because they represent different failures.
See the [combined plan](plan.md#ascii-ui-preview). Task 03 implements the views within its scope.
## Verification
Run from the repository root. Install workspace dependencies once before the first package command if this checkout lacks them.
Use `/tdd` for changed logic and `/e2e` for browser work. First establish the regression against current behavior.
```bash
(cd apps/web && pnpm e2e:run --project chromium tests/task/launch-failure-recovery.spec.ts)
(cd apps/web && pnpm e2e:run --project mobile-chrome tests/task/mobile-launch-failure-recovery.spec.ts)
node --test scripts/validate-public-docs.test.mjs
node scripts/validate-public-docs.mjs
python3 scripts/list-docs.py validate
python3 scripts/lint-spec-files.py --all
git diff --check
```
## Files likely touched
- `apps/web/e2e/tests/task/launch-failure-recovery.spec.ts`.
- `apps/web/e2e/tests/task/mobile-launch-failure-recovery.spec.ts` and existing fixture/page-object helpers if necessary.
- `docs/public/tasks-and-workflows.md`.
- This package and the linked owning specs, after implementation matches the design.
## Dependencies
02-shared-task-errors.
## Inputs
Read both owning specs linked from the plan and the September 14 scope decision.
Use the existing launch-recovery tests as the fixture pattern.
## Risks
Preserve failure identity, sanitized details, existing recovery guards, and message ordering under reversed delivery.
The shared repository can contain other edits. Do not revert unrelated changes.
## Parallelism
`sequential`
## Results
Complete on September 14, 2026. The desktop and phone fixtures cover retained session history, ordinary scroll anchoring, shared task errors across session and Plan surfaces, sibling recovery, legacy readability, duplicate stamps, reload, delayed output, no-session recovery, phone drawer bounds, touch targets, and document overflow. Backend and composed frontend regressions also cover the real bootstrap and Office producers, persisted/provisional representation deduplication, legacy recovery controls, cold-projector task scope, stale snapshot retirement, live shared-summary replacement, one assertive announcement per stamp, and mobile top-bar geometry. Public session and task recovery guidance now matches the shipped scope and history behavior.
Validation passed:
- `pnpm e2e:run --host --no-build --project chromium e2e/tests/task/launch-failure-recovery.spec.ts`: 4 passed.
- `pnpm e2e:run --host --no-build --project mobile-chrome e2e/tests/task/mobile-launch-failure-recovery.spec.ts`: 3 passed.
- `node --test scripts/validate-public-docs.test.mjs` and `node scripts/validate-public-docs.mjs`: passed.
- `python3 scripts/list-docs.py validate` and `python3 scripts/lint-spec-files.py --all`: passed.
- `git diff --check`: passed.
- Review regression suites and the complete selected backend package run: passed.
- The composed task panel assertion counts persisted and provisional recovery representations together and passed with the affected frontend suite.
Review follow-up validation:
- The desktop PR watcher missing-branch E2E now opens the task-shell error details and passed with one test.
- The mobile PR watcher missing-branch E2E uses the same shared surface with touch interaction and passed with one test.
- Full frontend lint and typecheck, plus the focused recovery suites, passed after the compatibility fixes.
- The remaining recovery selectors now follow their owning scope: the GitHub URL launch case uses the shared task surface, Kubernetes failures use retained session entries with technical details, and failed mobile resume uses the persisted recovery entry. The focused follow-up runs passed: Chromium 1 test, Mobile Chrome 1 test, and Kubernetes containers 3 tests with 1 fixture-gated skip.
docs/plans/resume-cancellation/plan.md
+6
View File
@@ -207,3 +207,9 @@ pass.
- Cleanup by session ID alone can terminate a replacement execution.
- Error deduplication without attempt correlation can hide historical failures.
- Request disconnect must remain distinct from explicit cancellation.
## September 14 presentation successor
The [error scope package](../error-scope-and-history/plan.md) supersedes the session card placement and removal behavior.
Completed results here remain historical evidence. Provider recovery, timeout budgets, cancellation, and authorization remain unchanged.
The successor owns chronological error retention, ordinary scroll behavior, and shared task alerts.
docs/plans/startup-recovery-scroll-timeout/plan.md
+6
View File
@@ -137,3 +137,9 @@ Targeted product tests and review regressions: passed.
A hung preflight can take longer to report failure. Cancellation must still work.
A new card reveal can conflict with bottom-follow or hidden-panel restoration.
Short viewports require the full card to share the transcript scroll area.
## September 14 presentation successor
The [error scope package](../error-scope-and-history/plan.md) supersedes the session card placement and removal behavior.
Completed results here remain historical evidence. Provider recovery, timeout budgets, cancellation, and authorization remain unchanged.
The successor owns chronological error retention, ordinary scroll behavior, and shared task alerts.