Goal

Define a unified Run Incident Framework for assistant runs that end unexpectedly. This is the umbrella direction for #802, #803, and #804: do not fix each observed interruption as an isolated patch; build one shared language for facts, cause, phase, recovery policy, and user-facing presentation.

Why this exists

Recent terminated-session exports showed that PawWork can collect many useful low-level signals, but the signals are still too ad hoc:

• [Feature] Add lifecycle causality diagnostics for interrupted runs #802 tracks local lifecycle-close causality: if PawWork locally reloads/disposes an active run, the export should say who initiated it.
• [Feature] Refine run diagnostics for interrupted streaming tool calls #803 tracks provider/transport interruption classification: if OpenAI streaming disconnects while tool input is still being generated, it must not be labeled as a tool execution failure.
• [Feature] Add safe recovery for interrupted streaming runs #804 tracks recovery UX: once the cause and safety facts are known, the session should offer the safest next step instead of feeling dead.

The common problem is not just one missing field. The common problem is that PawWork needs a unified run-incident model.

Direction

A run incident should be split into five layers:

1. Facts — what actually happened.
2. Cause — why the run ended.
3. Phase — where the run was interrupted.
4. Policy — what recovery action is safe.
5. Presentation — what export reviewers and users should see.

The first design draft is recorded in the first comment on this issue.

Related work

Direct implementation issues:

• [Feature] Add lifecycle causality diagnostics for interrupted runs #802 — local lifecycle causality diagnostics.
• [Feature] Refine run diagnostics for interrupted streaming tool calls #803 — provider/transport streaming interruption diagnostics.
• [Feature] Add safe recovery for interrupted streaming runs #804 — safe recovery and retry/continue UX.

Related active or residual reliability work:

• [Bug] 30s LLM connect timeout aborts OpenAI reasoning streams (post-#729 residual) #755 — OpenAI connect-timeout behavior.

Foundational completed work:

• feat(session): add run observability diagnostics #788 — run observability diagnostics.
• feat(session): trace lifecycle close provenance #794 — lifecycle close provenance.
• [Feature] Add LLM stream diagnostics to local session export #214 — LLM stream diagnostics in local session export.
• [Feature] Add lightweight loop observation and session diagnostics #133 — lightweight loop observation and session diagnostics.
• [Feature] Add structured tool failure reasons for agent recovery #439 — structured tool failure reasons for agent recovery.

Series index:

• [Task] Track harness improvement series #195 — harness improvement series.

Scope

In scope:

• Establish the shared model and naming for run incidents.
• Keep [Feature] Add lifecycle causality diagnostics for interrupted runs #802/[Feature] Refine run diagnostics for interrupted streaming tool calls #803/[Feature] Add safe recovery for interrupted streaming runs #804 aligned under this model.
• Require future interruption diagnostics to add facts/cause/phase/policy/presentation rather than one-off fields.
• Preserve privacy and redaction constraints.

Out of scope:

• One giant implementation PR.
• Provider SDK/network fixes.
• Telemetry sink integration.
• Broad UI redesign.

Execution mode

Investigate and get the design plan approved first. Here, "plan" means the issue-level design / scope proposal, not a PR-level implementation checklist. Once the approved design exists, agents may proceed with implementation plans inside the agreed scope; post a new issue comment and wait for explicit "approved" only when the implementation would change that design scope.