fix: retain session failures across recovery surfaces (#3669)
This commit is contained in:
@@ -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
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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