Make agent failures truthful, recoverable, and actionable

[shiny-code-bot]

Objective

Make Every Code agent failures trustworthy from provider call through child status, parent aggregation, CLI/TUI output, and persisted rollout. The July 18, 2026 investigation found separate defects being collapsed into a generic failed state: retryable transport errors poisoning successful outcomes, predictable provider blockers surfacing late, and rollout writer failure losing its root cause while flooding diagnostics.

Deliver this as sequenced independent tracks so the released false-failure bug and persistence containment can ship before broader status/preflight and storage-format work.

Finish Line

Agent outcome, provider blocker, and persistence signals are truthful and actionable across the full regression fault matrix.

Current Status

State: Active
Next action: Land PR #439 for the #434 manager-level false-success correction once its queued self-hosted blob-size check runs; #436 can continue independently on persistence containment.
Blocked by: PR #439's Blob size policy check is queued waiting for the self-hosted chris-testing runner. The equivalent local policy check passes.
Waiting for: Self-hosted runner availability and PR review.
Last verified: July 19, 2026. Current main already has corrected retryable StreamError handling; PR #439 preserves fatal child errors through trailing completion/abort events and keeps parent notifications consistent.

Scope

• In: terminal outcome reconciliation, additive outcome/health status, provider preflight classification, rollout writer recovery/health, segmented/checkpointed rollout follow-up.
• Out: silent cross-provider failover, automatic deletion of user history, unrelated agent UX redesign, JetBrains inspection semantics (tracked in a related cross-repo plan).

Acceptance Criteria

• Make agent terminal outcomes reflect final evidence #434 prevents recoverable stream errors from creating false terminal failures and establishes the outcome/health contract.
• Preflight agent providers and classify blockers before execution #435 classifies provider/configuration blockers before or at the earliest reliable execution boundary.
• Harden rollout writer recovery and surface persistence health #436 preserves rollout writer root causes, bounds recovery, and surfaces edge-triggered persistence health.
• Segment and checkpoint large rollouts with safe stale-session cleanup #437 introduces crash-consistent segmented/checkpointed storage without breaking V1 or live-session safety.
• Parent summaries, child results, exec exit status, and persisted terminal evidence agree across the regression matrix.
• Release notes distinguish the immediate remediation from later protocol/storage evolution.
• No implementation track relies on a feature flag, silent fallback, or automatic user-data deletion.

Relationships

Sub-issues:

• Make agent terminal outcomes reflect final evidence #434 — terminal outcome truth and additive health semantics
• Preflight agent providers and classify blockers before execution #435 — provider preflight and blocker classification
• Harden rollout writer recovery and surface persistence health #436 — V1 writer recovery and persistence health
• Segment and checkpoint large rollouts with safe stale-session cleanup #437 — V2 segmentation, checkpointing, and conservative cleanup

A cross-repo JetBrains inspection clarity plan will be linked as related context because misleading inspection evidence can look like an agent failure without sharing the runtime root cause.

• related: Make JetBrains inspection failures distinct and actionable jetbrains-inspection-api#216 - Make JetBrains inspection failures distinct and actionable jetbrains-inspection-api#216

Validation

• Shared fault matrix covering retry/recovery, retry exhaustion, auth/quota/rate limit, cancellation/shutdown ordering, disk full/I/O error, writer panic, and multi-gigabyte resume.
• Focused crate tests per child, end-to-end parent/child dogfood, and release gates appropriate to each shipping phase.
• Structured telemetry validates outcome source and health transition without recording result content.

Decisions

• Ship the minimal released-line stream fix without waiting for the full manager/storage redesign.
• Separate semantic work outcome from runtime/provider/persistence health.
• Treat typed terminal evidence as authoritative; task_complete alone is lifecycle quiescence, not proof of success.
• Keep persistence and inspection evidence as distinct workstreams with native relationships.

Open Questions

• Which remediation slices should share the next patch release versus land only on main after compatibility review?