fix: retain session failures across recovery surfaces (#3669)
This commit is contained in:
@@ -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.
|
||||
|
||||
@@ -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)
|
||||
|
||||
Reference in New Issue
Block a user