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

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
@@ -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