Activity: preserve partial output and present actionable failure recovery #308

Source type

source:user — normalized child of a bot-authored roadmap parent; the
authoritative, clean statement of one independently testable slice.

Source link / evidence

• Parent roadmap: Roadmap: make streaming conversation and tool activity feel alive in TUI and Desktop #291 (Roadmap: make streaming conversation and tool activity feel alive in TUI and Desktop).
• Depends on: Activity: define the shared event presentation model #306 (Activity: define the shared event presentation model).
• Product direction recorded on Roadmap: make streaming conversation and tool activity feel alive in TUI and Desktop #291.

Problem statement

When a step fails mid-run, users need to see what already happened, keep the
partial output, and understand the next action. Failures and retries must be
presented through the shared event model (#306) so both surfaces behave the same,
rather than being swallowed or shown as an opaque error.

User value

A failure preserves the partial output already produced and presents an
actionable next step; retries are surfaced clearly. Users recover confidently
without re-running blindly or losing context.

Scope

• Present failures and retries through the Activity: define the shared event presentation model #306 event model with the canonical
  failure semantics for each event kind.
• Preserve partial output produced before the failure and pair it with an
  actionable next-step message.
• Distinguish a real failure from a bounded retry and from a waiting condition
  (network/rate-limit/CI queue), consistent with the product's failure taxonomy.

Non-goals

• Defining the event model (owned by Activity: define the shared event presentation model #306) or the TUI card renderer (Activity: render progressive-disclosure activity cards with follow-mode in the TUI #307).
• Changing the retry/backoff policy itself (surfacing it only).
• Fabricating a recovery suggestion when none applies.
• Auto-executing the suggested next step.

Acceptance criteria

• A failed step preserves its partial output in the presentation model and
  presents an actionable next-step message.
• Retries are surfaced as distinct events with bounded-retry semantics.
• Waiting conditions (network/rate-limit/CI queue) are distinguished from
  real failures.
• Failure presentation uses the Activity: define the shared event presentation model #306 canonical failure semantics (no
  surface-local message).

Test plan

Failure/retry fixture tests asserting partial-output preservation and the
next-step message; a test distinguishing a waiting condition from a failure; a
contract test asserting failure presentation uses the #306 canonical semantics.

Dogfood plan

Trigger a recoverable failure during a multi-tool task and confirm the partial
output is preserved, the next step is actionable, and a retry is surfaced
distinctly from a hard failure.

Risk and security notes

Partial output may contain secrets or unsafe escape sequences; present only the
redacted, neutralized #306 model. Never auto-execute a suggested recovery or
fabricate a next step that does not apply.

Duplicate search evidence

Searched open and closed Issues and PRs on 2026-07-31. run-failure-taxonomy.ts and
run-recovery.ts classify and recover from failures at the runtime level; this
child presents failures/retries through the shared #306 event model with partial
output and an actionable next step, which is presentation-layer work they do not
cover. No duplicate found.

Parent/child relationship

Child of #291; consumes #306. Independent of the TUI card renderer (#307) at the
model level; both feed the cross-surface parity child.

Dependency order

Requires #306 (shared event model). May proceed once #306 lands; does not require
the Desktop gate (#106/#133).