Decide what failure evidence a Run retains and shows

[Sandstorm831]

Question

What failure evidence must a Run durably retain, and what should TUI and headless clients show when a Step Attempt or Harness Turn fails, is lost, or leaves the Run halted?

Set the boundary among typed Problems, Attempt and Turn evidence, diagnostic Resources, and the Run Projection. Decide which currently lost causes become durable, including Command spawn/timeout and Agent output-receipt failures; which owner writes each fact; how the existing 90-day detailed-diagnostic retention applies; and what remains in the minimal failure summary until Run deletion. Keep everyday presentation actionable and technical inspection available on demand without raw protocol, private reasoning, or credentials. Name the smallest pre-public-release milestone outcome and what can remain deferred. The separate operational trace is decided by its sibling ticket.

[Sandstorm831]

Starting context

Input	Why it matters	Authority
Pre-public-release report 7 and the tracing scope split	The dropped-cause report and the separate maintainer logging decision.	Source report / sibling decision
ADR 0022, ADR 0023, and ADR 0024	The Harness failure, 90-day diagnostic, and normalized client Interface contracts.	Canonical
Run lifecycle glossary	Canonical Step Attempt, Turn, Entry Turn, and Run state distinctions.	Canonical
Command failure path, Agent receipt and Turn paths, Run Store records, and Run Projection	Attempts currently keep only outcomes, Turn failures lose useful fields, and Command/receipt causes are dropped.	Current fact
OpenCode failed tool presentation and T3 Code failed work presentation	Reference patterns for a later presentation decision, not authority over Secant's domain.	Advisory reference

Reading rule. Decide durable Run failure evidence and client presentation separately from the maintainer trace. Begin by confirming whether the Run view needs a plain failure reason at all; the earlier apparent approval was given before the two purposes were separated and is not a settled decision. Then use /grilling and /domain-modeling to determine storage, read paths, retention, and the smallest pre-release outcome. Respect ADR 0022's exclusion of raw protocol and private reasoning and ADR 0023's split between minimal lasting evidence and detailed diagnostics. Implementation remains outside this planning map.

[Sandstorm831]

Resolution

Recorded in ADR 0041, with amendments to ADR 0023 and ADR 0024 and three glossary terms (docs: record what failure evidence a Run retains and shows).

Whether the Run view needs a reason

1. Yes. Whenever an Attempt or Turn fails, is lost, or the Run rests halted or failed, the everyday screen shows one plain line: what happened and what to do. It shows no codes or ids.

Records and retention

2. Failure evidence lives on the Attempt or Turn, and a Resting cause on a halted or failed Run. Both last until Run deletion.
   • Failure evidence holds the source and code, phase and category, possible effects (none, partial, unknown), native code (exit code, errno, signal), small safe details, and a diagnostic reference.
3. A Detailed diagnostic is a diagnostics/ file pruned after 90 days by the existing prune. It holds the translated cause and stack, a bounded Command output tail, the Harness failure's partial output, retry evidence and diagnostics, and a lost Turn's last observation.
4. A Problem stays a transient Operation outcome and is not persisted. A failed interactive Turn that returns the Run to blocked needs no Resting cause, because its Turn's evidence says why.
5. This record is separate from the Pino operational log decided in Decide Secant's local operational diagnostics for maintainers and CI. The Projection never reads that log.

Codes and wording

6. Only typed codes are stored. The Projection derives the explanation and next step when it reads them, and narrows unknown codes tolerantly.

7. Tailored wording covers:

   • a Command that couldn't start, timed out, or was killed
   • a receipt that is missing, invalid, or too large
   • a Harness that isn't authenticated (log in through the Harness)
   • a Harness that exited or lost contact
   • a Turn lost after a crash
   • an exhausted retry budget
   • a gate answered stop
   • a Materialization conflict
   • a prepare failure
   • an internal fault

   Anything else gets generic wording by category: "Claude Code reported an error. Open the details section for the cause."

8. An unknown code, or an old Run with no evidence, reads "This Step failed for unknown reasons." There is no backfill.

What becomes durable

9. Command spawn errno, an executable gone before spawn, a timeout's bound and output tail, and the killing signal.
10. Which receipt output failed and why: missing, not a regular file, symlink, too large, invalid UTF-8, or blank.
11. Agent failures before a Turn exists (unusable Session, prompt render failure, refused admission), recorded on the Attempt.
12. Every HarnessFailure field, and a lost Turn's last observation, split across the two tiers.
13. Resting causes for a prepare failure, an execution fault (which now rests halted instead of leaving a running Run with no owner), and crash reconciliation. These join the causes execution already knows. CleanupReport and usage go to the operational log only.

Who writes each fact

14. Process gives SpawnResult a typed cause.
15. Run execution saves Failure evidence through the existing publishAttempt and Turn settlement, in the outcome's transaction.
16. A Resting cause rides writeState in the state change's transaction.
    • Execution writes its own halts.
    • Application writes prepare-failure and fault causes.
    • The Run Store's reconciliation writes the crash cause.
17. A diagnostic file is written before the row that references it. No new RunOwner write method is added, so observedOwner still refreshes open clients. Adapters are unchanged.

Privacy

18. Detailed diagnostics pass through the same safe cause translator as the operational log. It copies an allowlist of fields, redacts Secant-introduced secrets, and bounds size.
19. Raw protocol, private reasoning, environment values, credentials, prompts, and user text never enter a Detailed diagnostic. The Command output tail stays exact, as a declared Command output does.

Presentation

20. Workbench transcript: a failure row where the failure happened, with the error-colour left border and muted explanation and next step. A retried Attempt shows "Attempt 1 of 3 failed: … · retrying", and a lost Turn names the unknown half in plain words.
21. partial or unknown possible effects add "It may have changed files before it stopped."
22. A resting Run shows the Resting cause and next step in place of the compose.
23. The details panel gains a Failure section (code, phase, category, possible effects, native code, diagnostic), which reads "Expired after 90 days" once pruned. A Problem's code line leaves everyday screens.
24. Headless: run show prints "Stopped because:" and "Next:", plus a reason on each failed timeline entry. --json adds optional failure objects and a restingCause, with no renames. Exit codes are unchanged.

Milestone

25. One milestone, "A Run says why it stopped", covers items 1 to 24.
    • Its acceptance is an end-to-end scenario test per tailored case, from the cause through run.db to the Workbench and run show text.
    • It follows the agent-screen Run Workbench milestone, because the failure row lands in ADR 0039's per-Session history.
    • It builds the shared translator if the operational-log milestone hasn't built it yet.

Deferred

• Parsing Harness-native messages (usage limits, reset times).
• A copy-error action.
• Backfilling old Runs.
• A log-browsing screen (already deferred by Decide Secant’s local operational diagnostics for maintainers and CI #273).
• Showing retry evidence outside the Detailed diagnostic.

Handed on

• To Approve the second pre-public-release Amendment: the decided redesigns: add the "A Run says why it stopped" milestone after the agent-screen Workbench milestone.
• Unverified: that a run-execution-fault leaves a Run running with no owner is inferred from code, not tested. Item 13's fix covers it either way. The implementing slice should reproduce it first.