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/decisions/2026-09-14-error-scope-and-history.md
+36
View File
@@ -0,0 +1,36 @@
# ADR-2026-09-14-error-scope-and-history: Error scope and conversation history
**Status:** accepted
**Date:** 2026-09-14
**Area:** frontend
## Context
The startup recovery card precedes the transcript history loader. Special scroll ownership tries to keep it visible during pagination.
After user scrolling releases that ownership, another history page can move the card out of view.
Existing recovery-message filters also remove errors after later messages. This loses useful conversation context after automatic recovery.
Shared task errors can affect several sessions and non-chat views.
## Decision
Session failures are durable chronological chat entries. Successful recovery removes active controls, not the historical entry.
The normal transcript scroll controller owns these entries. No error-specific reveal or top-pinning policy remains.
Task and shared workspace failures appear once in the task shell, above tabs and outside their content scrollers.
Error scope comes from the failure owner. An initiating session or the presence of a repository identifier does not determine scope.
Shared task errors have an independent projection, so session failures cannot hide them.
Existing recovery permissions, stamps, provider identity, and sanitized details remain authoritative.
## Consequences
Users can read the failure followed by resumed agent work. Session errors can scroll out of view as ordinary messages.
A shared alert stays visible across tab switches. Its details use a desktop dialog or phone drawer to preserve content space.
Failure identity and recovery eligibility must remain separate from historical message visibility.
This decision applies within an affected task. It does not introduce an installation-wide alert center or workspace-wide broadcast system.
## Alternatives Considered
- A fixed session banner keeps errors visible but duplicates conversation history and consumes permanent chat space.
- A special entry above all history requires competing scroll rules and does not preserve chronological context.
- Removing errors after recovery hides why the conversation stopped and restarted.
- A shared error inside Chat disappears on other tabs and misrepresents its scope.
- Inferring scope from error text or counting failed sessions can misclassify unrelated failures.
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.
docs/public/sessions-and-review.md
+4 -2
View File
@@ -59,9 +59,11 @@ Right-click an agent tab on desktop to manage it. Available actions depend on it
| **Handoff** | Opens the launch dialog with Blank context. Select a summary when you want to include this conversation |
| **Close Others** | Closes other visible agent panels without deleting their sessions |
Stopping is not deletion. Resume succeeds only while the executor still has the session record needed to continue. A removed worktree, expired remote environment, restarted executor, removed profile, or missing runtime record can force a fresh session instead. When startup or resume fails, Kandev shows one recovery card in the selected session's chat. It labels the safe cause, keeps technical details collapsed, and offers **Resume**, **Restore read-only workspace**, or **Start fresh session** when each action is valid.
Stopping is not deletion. Resume succeeds only while the executor still has the session record needed to continue. A removed worktree, expired remote environment, restarted executor, removed profile, or missing runtime record can force a fresh session instead. When startup or resume fails, Kandev adds one recovery entry to the selected session's chat. The entry stays in chronological history after recovery and later agent output. Only the current unresolved failure shows recovery controls. Older entries keep their message and technical details, and repeated delivery of the same failure does not create another entry. History loading and new messages use the normal chat scroll behavior.
**Restore read-only workspace** makes the existing files available for inspection without claiming that the agent resumed. A successful restore keeps the recovery card visible until a later resume succeeds. Kandev keeps the card in the chat scroll area and uses stacked touch-sized actions on phones. A failure in another session or an unrelated provider error remains on its own existing surface.
**Restore read-only workspace** makes the existing files available for inspection without claiming that the agent resumed. The session entry remains visible until the session resumes successfully. Kandev uses stacked touch-sized actions on phones. A failure in another session remains in that session's history.
Failures during task or workspace preparation appear as one task error strip below the task header and above the session and Plan tabs. The strip remains visible when you switch sessions or tabs and disappears only after task recovery succeeds. Select **Show details** to open the available guarded actions in a desktop dialog or phone drawer.
Stopping a turn does not itself run the next queued message. If pending rows remain, Kandev sets their session's **Auto-run** switch to OFF. Expand the queue and turn Auto-run ON when you want FIFO processing to continue.
docs/public/tasks-and-workflows.md
+3 -1
View File
@@ -747,7 +747,9 @@ To restore a task, open **List**, enable **Show archived**, and choose **Unarchi
While a task is archived, Kandev shows its history but does not start its agent or restore its workspace. After a successful unarchive, the open task checks its existing session once and follows the normal start preference. It can resume the same session or restore its worktree while keeping the session and environment identity. If **Prevent auto-start on open** is enabled, select **Start agent** to begin recovery.
If recovery fails, the task shows a short error with expandable details for the resume and workspace restore attempts. Select **Retry** to try again. If you archive the task during recovery, Kandev stops that recovery path and does not start a fallback restore. For worktree tasks, archive keeps the environment identity and the local branch. The next session recreates the worktree directory from that branch. Recovery is best-effort and does not rewrite ambiguous multi-row attachments for the same repository. If an external action or an older Kandev version removed the branch, Kandev also checks `origin`. If no branch exists, the next session starts from the base branch. Removed worktree directories, containers, and sandboxes are materialized again on a later launch rather than resumed in place.
If session startup or resume fails, Kandev keeps the failure as a chronological entry in that session's chat. The current unresolved entry provides the valid recovery actions. After recovery and later agent output, the entry remains in the chat with its details, while older entries have no stale controls. History loading and new messages keep the normal chat scroll position.
If task or workspace preparation fails, Kandev shows one task error strip below the task header and above the session and Plan tabs. The strip stays visible when you switch sessions or tabs. Select **Show details** to open the available guarded actions in a desktop dialog or phone drawer. Kandev clears the strip after task recovery succeeds. If you archive the task during recovery, Kandev stops that recovery path and does not start a fallback restore. For worktree tasks, archive keeps the environment identity and the local branch. The next session recreates the worktree directory from that branch. Recovery is best-effort and does not rewrite ambiguous multi-row attachments for the same repository. If an external action or an older Kandev version removed the branch, Kandev also checks `origin`. If no branch exists, the next session starts from the base branch. Removed worktree directories, containers, and sandboxes are materialized again on a later launch rather than resumed in place.
Delete is permanent. If **Also delete _N_ subtasks** is left unchecked, direct children become root tasks. If selected, descendants are deleted. The operation cannot be undone, and executor cleanup follows the same asynchronous retry and restart-reconciliation rules as archive.
docs/specs/agents/requirements/session-recovery-failures.md
+12 -5
View File
@@ -2,7 +2,7 @@
status: active
system: agents
created: 2026-09-11
updated: 2026-09-12
updated: 2026-09-14
owners:
- Kandev
---
@@ -42,15 +42,22 @@ results, including the shared recovery owner and phone touch-target checks.
- **AC-AGENTS-AGENT-RESUME-RUNTIME-RECOVERY-006.1:** When the same failure appears in automatic recovery, session state, and the transcript, the selected session shall show one active recovery card. An equivalent top banner, stopped-session warning, or synthetic agent error shall not repeat it.
- **AC-AGENTS-AGENT-RESUME-RUNTIME-RECOVERY-006.2:** The card shall show a localized cause summary, valid actions, and one initially collapsed details disclosure. Resume and restore causes shall have separate labels and bounded, sanitized details.
- **AC-AGENTS-AGENT-RESUME-RUNTIME-RECOVERY-006.3:** A failure before agent startup shall be described as startup or recovery failure. It shall not state that the agent encountered an error while working.
- **AC-AGENTS-AGENT-RESUME-RUNTIME-RECOVERY-006.4:** Retry shall update the existing card and disable equivalent actions while pending. Successful resume shall clear the active failure; workspace-only success shall show a nonblocking notice that the agent remains stopped.
- **AC-AGENTS-AGENT-RESUME-RUNTIME-RECOVERY-006.4:** Retry shall show pending state on the error entry and disable equivalent actions. Successful resume shall retire its actions without removing history. Workspace-only success shall retain the stopped-agent notice.
- **AC-AGENTS-AGENT-RESUME-RUNTIME-RECOVERY-006.5:** Reload, reconnect, and reversed event order shall converge on the current failure. A stale attempt or unrelated historical error shall neither replace nor be hidden by that failure.
- **AC-AGENTS-AGENT-RESUME-RUNTIME-RECOVERY-006.6:** Desktop and phone shall expose the same recovery choices and details. Phone actions shall have at least 44-pixel touch targets, with no horizontal page overflow or extra details scroller.
- **AC-AGENTS-AGENT-RESUME-RUNTIME-RECOVERY-006.7:** Chat shall use one vertical scroll area for the recovery card, expanded details, and transcript. Opening a session with an active failure, or receiving a new failure, shall reveal the card. Later user scrolling shall remain under user control. Recovery actions and the composer shall remain reachable on desktop and phone.
- **AC-AGENTS-AGENT-RESUME-RUNTIME-RECOVERY-006.7:** Chat shall show the session error at its chronological position in the transcript. Normal message scrolling shall govern initial placement, pagination, and new entries. Errors shall not force a separate scroll position. Recovery actions and the composer shall remain reachable on desktop and phone.
## Proposed recovery scrolling amendment
- **AC-AGENTS-AGENT-RESUME-RUNTIME-RECOVERY-006.8:** After manual or automatic recovery, the session error shall remain readable before later messages. It shall retain its original cause and occurrence time after reload.
- **AC-AGENTS-AGENT-RESUME-RUNTIME-RECOVERY-006.9:** Only the current unresolved failure shall offer recovery actions. Pending recovery shall not imply success. A later failure shall not reactivate controls on an older entry.
This amendment is draft. The [startup recovery fix package](../../../plans/startup-recovery-scroll-timeout/plan.md) owns implementation of criterion 006.7.
## Session error history amendment
The September 14 amendment changes criteria 006.4 and 006.7 and adds 006.8 and 006.9.
Implementation is complete in the [error scope package](../../../plans/error-scope-and-history/plan.md).
This supersedes the reveal-at-top behavior from the completed startup recovery scrolling package.
The task system owns durable history and shared error scope through
[task error ownership](../../tasks/requirements/task-launch-failure-recovery.md).
## Proposed recovery attempt amendment
docs/specs/agents/system-design/session-recovery-failures.md
+34 -18
View File
@@ -2,7 +2,7 @@
status: draft
system: agents
created: 2026-09-11
updated: 2026-09-12
updated: 2026-09-14
requirements:
- REQ-AGENTS-AGENT-RESUME-RUNTIME-RECOVERY-005
- REQ-AGENTS-AGENT-RESUME-RUNTIME-RECOVERY-006
@@ -97,24 +97,40 @@ Use 28-pixel fine-pointer buttons and at least 44-pixel phone/coarse-pointer
targets. The semantic disclosure supports Enter/Space and expanded state.
### Proposed recovery scroll ownership
### Chronological recovery entries (September 14 amendment)
The [startup recovery fix package](../../../plans/startup-recovery-scroll-timeout/plan.md) implements criterion 006.7.
Place the recovery card inside the existing transcript viewport, before the message content.
Disable outer `PanelBody` scrolling for the mounted chat.
Preserve the fixed composer and existing dynamic viewport and safe-area layout.
Expanded recovery details remain in the transcript scroll area.
Do not add a card scroller, duplicate banner, or permanent fixed recovery panel.
This amendment supersedes recovery reveal and prepend placement from the completed
[startup recovery scrolling package](../../../plans/startup-recovery-scroll-timeout/plan.md).
The [error scope package](../../../plans/error-scope-and-history/plan.md) owns implementation.
Reveal the active card once per session and failure stamp when the chat becomes visible.
Use the existing transcript scroll controller to coordinate this reveal with initial bottom positioning.
A repeated event with the same stamp must not pull the user away from older messages.
Scope reveal state to session identity and defer hidden-panel scrolling until visibility returns.
Preserve normal bottom-follow behavior when no active recovery card exists.
Render a session failure through the ordinary message pipeline at its persisted occurrence position.
Reuse `ActionMessage`, `RunErrorEntry`, and `SessionBootstrapRecoveryCard` presentation and recovery handlers where applicable.
One correlated failure selects one renderer, not a footer plus a prepended card.
`TaskChatLaunchError` remains an adapter for compatible callers until those callers migrate.
Task detail and preview share the chat panel. Audit Quick Chat for the same nested-scroll condition.
The dedicated phone Chat surface retains stacked touch actions and one-dimensional navigation.
The recovery card remains the sole explanation and action owner.
Remove activity-based deletion from `deduplicateRecoveryMessages` in `processed-message-filtering.ts`.
Deduplicate by session and durable stamp, with message ID as the legacy fallback.
Do not collapse every recovery entry into the latest one. Preserve unrelated errors and provider-specific remediation.
`ActionMessage` must retain a historical body while the session is STARTING, RUNNING, or COMPLETED.
Neither a button click nor any later user message proves successful recovery.
Use the existing durable recovery resolution timestamp and correlated boot evidence for outcome state.
Only the matching current unresolved stamp can mount active recovery controls.
A newer failed attempt creates a new chronological entry. The previous entry remains historical with no stale actions.
An update within the same failure identity updates that entry without moving it.
Remove recovery-specific `prependContent`, `recoveryRevealKey`, and top-placement branches from mounted chat paths.
Remove only error-specific scroll behavior, preserving search, ordinary history anchors, bottom follow, and environment-switch placement.
Update detail, preview, simple Chat, and Quick Chat. Keep the composer outside the single transcript scroll owner.
A following reader sees new errors through normal append behavior. A reader in history stays at the same anchor.
An active error outside the loaded page must not be fabricated at the tail.
The existing session metadata can supply one provisional entry at its occurrence time until the persisted marker arrives.
Merge that entry by stamp and replace it with the persisted message identity without duplication.
After recovery, never reconstruct absent historical errors from current state alone.
Phone entries stack actions with 44-pixel targets. Their details expand inline and wrap in the transcript.
Shared task errors use the task-owned shell surface described in the
[task design](../../tasks/system-design/task-launch-failure-recovery.md).
The [scope decision](../../../decisions/2026-09-14-error-scope-and-history.md) records the tradeoffs.
## Persistence and compatibility
@@ -209,8 +225,8 @@ Explicit cancellation is a cancellation outcome, not a resume failure card.
Reuse the existing `TaskLaunchErrorEntry` and recovery view model. The summary
identifies recovery failure. Details identify the load timeout. Existing Retry
and confirmed Start fresh actions keep their semantics. No new layout, setting,
public retry endpoint, or background retry loop is necessary.
and confirmed Start fresh actions keep their semantics. No new setting, public retry endpoint, or background retry loop is necessary.
The chronological presentation amendment governs the layout.
The nearest phone exemplar is the existing inline launch recovery card in
`mobile/session-mobile-layout.tsx`. Phone actions stack below the summary and
docs/specs/tasks/requirements/task-launch-failure-recovery.md
+23 -1
View File
@@ -2,7 +2,7 @@
status: active
system: tasks
created: 2026-08-19
updated: 2026-09-11
updated: 2026-09-14
owners:
- cfl12
---
@@ -71,6 +71,28 @@ These criteria are implemented in the
with execution fencing, transaction-serialized ownership, and recovery-surface
regressions recorded in its verification results.
### REQ-TASKS-TASK-LAUNCH-FAILURE-RECOVERY-002: Error ownership and retained session history
**Intent:** Keep session failures in their conversation and shared failures visible across the affected task.
This September 14 amendment is implemented in the [error scope package](../../../plans/error-scope-and-history/plan.md).
It changes presentation and retention, not recovery permissions or provider resume behavior.
#### Acceptance criteria
- **AC-TASKS-TASK-LAUNCH-FAILURE-RECOVERY-002.1:** Each failure shall identify session or task scope. A shared resource failure shall name its affected resource when known. An initiating session shall not make a shared failure session-scoped.
- **AC-TASKS-TASK-LAUNCH-FAILURE-RECOVERY-002.2:** A session failure shall create one durable chronological entry in its owning session. Repeated delivery of the same failure shall not create another entry.
- **AC-TASKS-TASK-LAUNCH-FAILURE-RECOVERY-002.3:** Successful recovery, later messages, reload, and reconnect shall preserve the original session error. Recovery shall retire only matching active error state.
- **AC-TASKS-TASK-LAUNCH-FAILURE-RECOVERY-002.4:** An active shared error shall appear once below the task header and above tab content. It shall remain visible on session, Plan, PR, Files, and plugin views. Task previews and tasks without sessions shall expose the same error.
- **AC-TASKS-TASK-LAUNCH-FAILURE-RECOVERY-002.5:** A newer session error or session recovery shall not replace or clear an unresolved shared error. An unrelated session shall not display another session's error as its own.
- **AC-TASKS-TASK-LAUNCH-FAILURE-RECOVERY-002.6:** One failure shall have one recovery control surface per task view. A shared error shall not repeat as an actionable banner inside each session. Separate failures can remain visible together.
- **AC-TASKS-TASK-LAUNCH-FAILURE-RECOVERY-002.7:** Phone users shall see the shared error outside tab content and reach its details and actions from a bottom drawer. Targets shall measure at least 44 pixels. Desktop shall use a compact shared strip and details dialog.
- **AC-TASKS-TASK-LAUNCH-FAILURE-RECOVERY-002.8:** Older records shall remain readable without invented failures or guessed resource scope. Stale recovery requests shall remain unable to mutate a successor error.
Implementation belongs to the [error scope package](../../../plans/error-scope-and-history/plan.md).
Session action presentation remains owned by the
[agent recovery requirement](../../agents/requirements/session-recovery-failures.md).
## Out of scope
- A background poller for all repository defaults.
docs/specs/tasks/system-design/task-launch-failure-recovery.md
+73 -39
View File
@@ -1,10 +1,11 @@
---
status: current
status: draft
system: tasks
requirements:
- REQ-TASKS-TASK-LAUNCH-FAILURE-RECOVERY-001
- REQ-TASKS-TASK-LAUNCH-FAILURE-RECOVERY-002
created: 2026-08-24
updated: 2026-09-11
updated: 2026-09-14
owners:
- cfl12
---
@@ -22,7 +23,8 @@ task-owned projection.
| Requirement | Design sections |
| --- | --- |
| REQ-TASKS-TASK-LAUNCH-FAILURE-RECOVERY-001 | PR gate, initial prompt admission, error projection, recovery actions, responsive surface |
| REQ-TASKS-TASK-LAUNCH-FAILURE-RECOVERY-001 | PR gate, initial prompt admission, error projection, recovery actions |
| REQ-TASKS-TASK-LAUNCH-FAILURE-RECOVERY-002 | Error scope, durable session history, shared task surface |
## PR gate and launch paths
@@ -203,53 +205,83 @@ Initial-prompt errors use a safe generic durable message and the same
stale-event checks as other agent failures. Raw attachment paths and provider
details remain in backend diagnostics and do not reach the durable projection.
## Launch-error presentation ownership
## Error scope (September 14 amendment)
The active `TaskStatusSummary.active_error` record owns the primary launch
error for its matching session and stamp. A task-wide record remains visible
while a prior session is selected, but it owns session surfaces only when no
session is selected. A session-owned record owns surfaces only for its exact
session and stamp. The task Chat surface renders one persistent card from this
record.
Implementation is complete in the [error scope package](../../../plans/error-scope-and-history/plan.md).
This section supersedes the earlier Chat-only task error surface.
Tasks own durable error records and task-shell projections. Agents own session recovery eligibility and entry presentation.
Workspace services retain authority over resource validity. This change does not add a workspace-wide alert bus.
The matching launch error suppresses these secondary presentations:
Add an optional `scope` discriminator, `session` or `task`, to existing normalized error metadata and wire types.
The producer selects scope from operation ownership, never from English error text or a count of failed sessions.
Session bootstrap, provider, turn, and resume failures default to session scope.
Task admission and preparation failures before session creation remain task scope.
A shared workspace or repository preparation failure uses task scope only when its owner establishes shared impact.
Preserve `task_repository_id` and the originating session correlation when available.
A repository ID alone does not prove shared impact. Unknown legacy session records remain session-scoped.
Legacy task metadata without scope remains task-scoped. Reject or safely ignore malformed optional scope values.
- The previous-agent-error notice.
- The standalone failed preparation row.
- The empty-turn warning.
- The generic failed-agent status row.
- The stopped-session recovery banner.
- A launch-error toast while the user views the affected task.
Continue storing current session errors in `task_sessions.metadata.last_agent_error`.
Store the current shared failure in `tasks.metadata.last_launch_error`, with the existing stamp fencing and recovery validation.
Do not create the same active failure in both stores. An origin session can retain a non-actionable historical reference.
Recovery lookup uses scope to choose the source record. The originating session ID is correlation, not authority to select session metadata.
Legacy requests retain their existing lookup rules. Scoped requests must pass the same task, repository, and stamp guards.
The existing single current task error contract remains. This package does not add a multi-incident queue.
Only synthetic rows generated by the active launch failure are suppressed;
stale stamped or historical launch-only rows remain visible. An unrelated
historical error keeps its normal transcript presentation. A runtime error that
occurs after agent startup keeps the existing session
recovery surface.
Expose optional `TaskStatusSummary.task_error` independently of `active_error`.
The projector already tracks `taskError` separately from its session error map.
Use that source for the shared field, while preserving `active_error` for existing aggregate consumers.
Boot payloads, HTTP reads, summary persistence, rebuilds, equality checks, and WebSocket replacements must carry the same field.
A newer session failure cannot displace `task_error`. Session success cannot clear task metadata.
Clear the shared record only through its matching successful recovery or an authoritative resource-resolution event.
For old payloads, clients can use an explicitly task-scoped or sessionless `active_error` as a compatibility fallback.
An old aggregate cannot reconstruct a shared error that it never carried.
The card shows a category title, a short cause, a no-change statement, and only
valid recovery actions. One disclosure shows bounded technical details. The
disclosure does not show raw Git output, credentials, or local file paths.
## Durable session history
A failed recovery updates the same card. It does not add another banner or
toast. A successful recovery removes the card after launch succeeds.
Use existing persisted session messages as the history ledger. No new history table or frontend error store is required.
Persist one sanitized error marker for each accepted session failure stamp before publishing the terminal state.
The marker carries session, execution, attempt, stamp, occurrence time, phase, and bounded cause data when available.
Reuse the current failure path and message storage rather than writing a second copy from the browser.
Extend the fenced persistence boundary so marker creation and active error admission cannot diverge under duplicate or late delivery.
An operation that loses its execution or stamp fence must not insert a failure for the successor.
Use deterministic message identity derived from the owning session and failure stamp for idempotent insertion.
## Responsive presentation
Successful recovery clears matching active metadata and retains `recovery_resolved_at` under existing rules.
It must not delete the error marker. Client presentation reads resolution separately from historical content.
Workspace-only restoration does not resolve the stopped agent. New agent output does not resolve shared workspace state.
A failed retry has a new attempt/stamp and a new entry. Request feedback for the same stamp updates only that entry.
Old records with markers remain readable. Metadata-only legacy failures can use the agent design's provisional entry while unresolved.
No migration invents historical errors after metadata has already been cleared.
The task Chat surface is the entry point on desktop and phone. The card remains
inline because the error and its actions belong to the current task.
## Shared task surface
Desktop actions use one compact row. Phone actions use a vertical layout with
44-pixel touch targets. The existing mobile picker remains the branch-selection
surface for `base_branch_missing` and `default_branch_unresolved`.
Mount one shared alert in the task shell below the task title/header and above session and content tabs.
It is outside Dockview and mobile tab content, including maximized panels and tasks without sessions.
Audit `task-page-content.tsx`, `task-layout.tsx`, preview composition, and dedicated phone/tablet layouts to choose the common host.
Extract a proposed `TaskSharedError` view instead of mounting `TaskChatLaunchError` inside every chat.
The compact strip shows the safe cause, affected resource label, and a Recovery details control.
A desktop dialog exposes existing valid task recovery actions. The phone equivalent uses an inset Drawer.
Use the existing branch picker and confirmation controls inside their established flows.
The alert has no dismiss action that clears unresolved state. Details can close without resolving the error.
Preserve focus return and use an accessible status announcement once for a new stamp.
The transcript owns vertical scrolling. Expanded technical details wrap inside
the card and do not create a second scroll region. Both layouts prevent
document-level horizontal overflow.
A shared alert and an unrelated session error can coexist. They represent separate failures.
The same stamp cannot mount recovery controls in both places.
Session error filtering must not hide the durable historical marker merely because a shared alert is present.
Session switching, Plan/PR navigation, and message pagination do not affect the shared alert.
`useEnsureTaskSession` keeps one request latch after an error. Store updates and
loader identity changes do not start another request. The Retry control starts
the next request explicitly. A task change clears the prior task's error state.
## Responsive behavior
Phone entry: the task header above the selected session/content view.
Exemplars: `mobile/session-mobile-layout.tsx` for task chrome and
`mobile/mobile-picker-sheet.tsx` for the inset drawer interaction.
The strip provides summary and details entry. The drawer provides cause, resource, then recovery actions.
This occasional multi-action recovery fits a temporary drawer, while the transcript remains the main reading surface.
Use one internal drawer body scroller for long shared details, dynamic viewport bounds, and bottom safe-area clearance.
Phone targets measure at least 44 pixels. Fine-pointer controls retain 28-pixel sizing.
Session entry details remain inline in the transcript and never gain a nested details scroller.
Shared view models, action guards, stamps, and request state serve both presentations.
## Verification
@@ -262,3 +294,5 @@ the next request explicitly. A task change clears the prior task's error state.
## Related decisions
- [ADR-2026-08-18-never-started-agent-stall-terminal](../../../decisions/2026-08-18-never-started-agent-stall-terminal.md)
- [Error scope and history decision](../../../decisions/2026-09-14-error-scope-and-history.md)