pi-better-subagents 0.4.1 → 0.5.0

package/README.md

@@ -14,7 +14,7 @@ Use `pi-better-subagents` when you want Pi to launch independent agent work with
 - Non-blocking subagent launches, with an optional role and named-agent catalog (`docs/agent-catalog.md`, `docs/agent-catalog-lifecycle.md`).
 - Default OS write sandboxing on macOS and Linux.
 - Explicit tool allowlists for child sessions.
-- Durable logs, result retrieval, and [failure observations](docs/failure-observations.md) independent of lifecycle status.
+- Durable logs, result retrieval, and [failure observations](docs/failure-observations.md) independent of lifecycle status. A live child handles its own tool errors; the parent is woken only for actionable incidents, and children can classify handled failures with `failure_disposition`.
 - Live background-work navigator for active runs.
 
 ## Install

package/callback-fields.ts

@@ -0,0 +1,92 @@
+/**
+ * Model-facing content fields for subagent callbacks (#312).
+ *
+ * index.ts spreads these into the shared callback batcher together with its
+ * delivery/receipt closures, so the payload builders here are the production
+ * ones. The measurement harness feeds the same fields through the real
+ * batcher to capture actual delivered content.
+ */
+import type { CallbackBatchEvent, UrgentCallbackEvent } from "./shared-callback-batcher.ts";
+import { activeFailures, pendingAttentionNote, pendingAttentionRows, requiresAction, terminalFailureParts,
+    type FailureState } from "./shared-failure-observations.ts";
+import type { RunMeta } from "./registry.ts";
+
+export function runLabel(meta: Pick<RunMeta, "id" | "name">): string {
+    return meta.name ? `${meta.name} (${meta.id})` : meta.id;
+}
+
+type CompletionFields = Pick<CallbackBatchEvent,
+    "source" | "id" | "label" | "status" | "detailTool" | "outcome" | "failureRows" | "decision" | "incidentCount">;
+
+type UrgentFields = Pick<UrgentCallbackEvent,
+    "source" | "id" | "label" | "status" | "customType" | "content" | "detailTool" | "failureRows" | "incidentCount">;
+
+/**
+ * Lifecycle, current actionability, and retained history are separate facts (#315). Rows are the
+ * actionable/incomplete incidents among `incidents` (the terminal pending set), counted exactly;
+ * unclassified tool failures, expected failures, closed history, and earlier deliveries are counts.
+ */
+function terminalFields(state: FailureState, incidents: readonly string[]) {
+    const { rows, notes } = terminalFailureParts(state, incidents);
+    return { failureRows: rows.length ? rows : undefined, incidentCount: rows.length || undefined, notes };
+}
+
+function observationStatus(state: FailureState): string | undefined {
+    const active = activeFailures(state);
+    return [
+        active.some((observation) => requiresAction(observation)) ? "action required" : "",
+        active.some((observation) => observation.category === "observation-incomplete") ? "observation incomplete" : "",
+    ].filter(Boolean).join("; ") || undefined;
+}
+
+/** Ordinary terminal completion: outcome, pending actionable rows, and history as counts. */
+export function completionCallbackFields(meta: RunMeta, state: FailureState, incidents: readonly string[] = []): CompletionFields {
+    const status = observationStatus(state);
+    const { failureRows, incidentCount, notes } = terminalFields(state, incidents);
+    return {
+        source: "subagent",
+        id: meta.id,
+        label: runLabel(meta),
+        status: status ? `${meta.status}; ${status}` : meta.status,
+        detailTool: "subagent_result",
+        outcome: meta.status,
+        failureRows,
+        ...(notes.length ? { decision: notes.join(" ") } : {}),
+        incidentCount,
+    };
+}
+
+/** Orphaned/lost health transition: the ATTENTION explanation, pending actionable rows, history as counts. */
+export function healthCallbackFields(meta: RunMeta, status: "orphaned" | "lost", state: FailureState, content: string,
+    incidents: readonly string[] = []): UrgentFields {
+    const { failureRows, incidentCount, notes } = terminalFields(state, incidents);
+    return {
+        source: "subagent",
+        id: meta.id,
+        label: runLabel(meta),
+        status,
+        customType: "subagent-health",
+        content: notes.length ? `${content}\n${notes.join(" ")}` : content,
+        detailTool: "subagent_result",
+        failureRows,
+        incidentCount,
+    };
+}
+
+/** Running/orphaned failure attention: exactly the pending incidents; earlier ones are counted, never repeated. */
+export function failureAttentionFields(meta: RunMeta, state: FailureState, pending: { key: string; incidents: string[] }): UrgentFields {
+    const rows = pendingAttentionRows(state, pending.incidents);
+    const note = pendingAttentionNote(state, pending.incidents);
+    const due = rows.length;
+    return {
+        source: "subagent",
+        id: meta.id,
+        label: runLabel(meta),
+        status: `failure:${pending.key}`,
+        customType: "subagent-failure",
+        content: `Subagent ${meta.id} (${meta.status}) has ${due} failure observation${due === 1 ? "" : "s"} that need attention.${note ? ` ${note}` : ""}`,
+        detailTool: "subagent_result",
+        failureRows: rows,
+        incidentCount: due || undefined,
+    };
+}

package/child-incidents.ts

@@ -0,0 +1,147 @@
+/**
+ * Child-side structured failure intent (#315), installed by the trusted task runtime.
+ *
+ * - `bash` accepts optional `operationId`, `attemptId`, and `expectedExitCodes`. They are
+ *   validated before the command runs. A declared exit code returns a non-error result
+ *   whose details carry the structured exit code; every other non-zero exit, timeout, or
+ *   abort stays an ordinary tool error.
+ * - `failure_disposition` lets the agent that owns an incident classify it explicitly.
+ *   It validates against the same incident model the parent scanner replays, so the
+ *   parent journals exactly what the child accepted and nothing else.
+ */
+import * as PiCodingAgent from "@earendil-works/pi-coding-agent";
+import type { BashOperations, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { emptyFailureState, reduceFailure, type FailureEvent, type FailureState } from "./shared-failure-observations.ts";
+import { DISPOSITION_TOOL, INTENT_ID_PATTERN, MAX_EXPECTED_EXIT_CODES, describeOpenTargets, foldToolEnd, foldToolStart,
+    newIncidentModel, readCommandIntent, readDispositionRequest, resolveDisposition, type IncidentModel, type IncidentSink } from "./incident-model.ts";
+
+const { createBashToolDefinition } = PiCodingAgent;
+
+const intentProperties = {
+    operationId: { type: "string", pattern: INTENT_ID_PATTERN,
+        description: "Optional stable id for one logical operation. Reuse it on a modified retry (changed scope, timeout, or flags) so a later success recovers the earlier failure." },
+    attemptId: { type: "string", pattern: INTENT_ID_PATTERN,
+        description: "Optional unique id for this execution, for use as evidence in failure_disposition." },
+    expectedExitCodes: { type: "array", items: { type: "integer", minimum: 1, maximum: 255 }, minItems: 1, maxItems: MAX_EXPECTED_EXIT_CODES, uniqueItems: true,
+        description: "Optional non-zero exit codes that are intentional for this command (for example [1] for an rg/grep no-match or git diff --exit-code probe). Declared before the command runs; the final shell exit code is what is classified." },
+};
+
+function sessionToolCalls(ctx: ExtensionContext | undefined): Array<{ type: string; [key: string]: unknown }> {
+    const branch = (ctx?.sessionManager?.getBranch?.() ?? []) as any[];
+    const rows: Array<{ type: string; [key: string]: unknown }> = [];
+    let pendingEnds: any[] = [];
+    const flush = () => { rows.push(...pendingEnds); pendingEnds = []; };
+    for (const entry of branch) {
+        const message = entry?.type === "message" ? entry.message : undefined;
+        if (!message) continue;
+        if (message.role === "assistant") {
+            flush();
+            for (const part of Array.isArray(message.content) ? message.content : []) {
+                if (part?.type === "toolCall" && typeof part.id === "string") {
+                    rows.push({ type: "tool_execution_start", toolCallId: part.id, toolName: part.name, args: part.arguments });
+                }
+            }
+        } else if (message.role === "toolResult" && typeof message.toolCallId === "string") {
+            pendingEnds.push({ type: "tool_execution_end", toolCallId: message.toolCallId, toolName: message.toolName,
+                isError: message.isError === true, result: { content: message.content, details: message.details } });
+        }
+    }
+    flush();
+    return rows;
+}
+
+/** Rebuild the child's view of its own incidents from the durable session branch. */
+export function childIncidentView(ctx: ExtensionContext | undefined, cwd: string): { model: IncidentModel; state: FailureState } {
+    let state = emptyFailureState();
+    let at = 0;
+    const sink: IncidentSink = {
+        observe: (events: FailureEvent[]) => { for (const event of events) state = reduceFailure(state, event, ++at); return state; },
+        dispose: (event: FailureEvent) => { state = reduceFailure(state, event, ++at); },
+        state: () => state,
+    };
+    const model = newIncidentModel(true);
+    for (const row of sessionToolCalls(ctx)) {
+        if (row.type === "tool_execution_start") foldToolStart(model, row, cwd, sink);
+        else foldToolEnd(model, row, cwd, "session", sink);
+    }
+    return { model, state };
+}
+
+/** Bash with structured intent, delegating execution to the given operations. */
+export function intentBashDefinition(cwd: string, operations: BashOperations) {
+    const base = createBashToolDefinition(cwd, { operations });
+    const parameters = { ...base.parameters, properties: { ...(base.parameters as any).properties, ...intentProperties } };
+    return {
+        ...base,
+        parameters,
+        async execute(toolCallId: string, params: any, signal: AbortSignal | undefined, onUpdate: any, ctx: ExtensionContext) {
+            const { intent, error } = readCommandIntent(params);
+            if (error) throw new Error(`Invalid command intent: ${error}. The command was not run.`);
+            if (intent.attemptId) {
+                const reused = sessionToolCalls(ctx).some((row) => row.type === "tool_execution_start" && row.toolName === "bash" &&
+                    row.toolCallId !== toolCallId && (row.args as any)?.attemptId === intent.attemptId);
+                if (reused) throw new Error(`Invalid command intent: attemptId ${intent.attemptId} was already used. The command was not run.`);
+            }
+            const { operationId: _o, attemptId: _a, expectedExitCodes: _e, ...command } = params ?? {};
+            let exitCode: number | null | undefined;
+            const observed: BashOperations = { ...operations, exec: async (...args: Parameters<BashOperations["exec"]>) => {
+                const result = await operations.exec(...args);
+                exitCode = result.exitCode;
+                return result;
+            } };
+            const run = createBashToolDefinition(cwd, { operations: observed });
+            try {
+                return await run.execute(toolCallId, command, signal, onUpdate, ctx);
+            } catch (failure) {
+                if (typeof exitCode === "number" && intent.expectedExitCodes?.includes(exitCode) && !signal?.aborted) {
+                    const message = failure instanceof Error ? failure.message : String(failure);
+                    return { content: [{ type: "text" as const, text: `${message}\n(Exit code ${exitCode} was declared expected.)` }],
+                        details: { exitCode, expectedExit: true, ...(intent.operationId ? { operationId: intent.operationId } : {}),
+                            ...(intent.attemptId ? { attemptId: intent.attemptId } : {}) } as any };
+                }
+                throw failure;
+            }
+        },
+    };
+}
+
+export function failureDispositionTool(cwd: () => string) {
+    return {
+        name: DISPOSITION_TOOL,
+        label: "Failure disposition",
+        description: [
+            "Classify your own earlier tool failures so the parent is not told about problems you already handled.",
+            "recovered: the same operation later passed (evidence = that attempt). superseded: a different verification or remediation established the outcome (evidence = the successful attempt).",
+            "expected: the failure was intentional. open: it still needs the parent's action (this asks for attention).",
+            "targets: incident ids, the attemptId/operationId you declared on bash, or tool call ids. Unknown or already-disposed incidents are rejected.",
+            "Never claim recovery without a successful later attempt as evidence.",
+        ].join(" "),
+        promptSnippet: "Classify handled tool failures (recovered, superseded, expected) or flag one as open for the parent.",
+        parameters: {
+            type: "object",
+            properties: {
+                disposition: { type: "string", enum: ["recovered", "superseded", "expected", "open"] },
+                targets: { type: "array", items: { type: "string", minLength: 1, maxLength: 200 }, minItems: 1, maxItems: 20 },
+                reason: { type: "string", minLength: 1, maxLength: 400 },
+                evidence: { type: "string", minLength: 1, maxLength: 200, description: "attemptId or tool call id of the successful later attempt; required for recovered and superseded." },
+            },
+            required: ["disposition", "targets", "reason"],
+            additionalProperties: false,
+        },
+        async execute(toolCallId: string, params: unknown, _signal: AbortSignal | undefined, _onUpdate: unknown, ctx: ExtensionContext) {
+            const parsed = readDispositionRequest(params);
+            if (!parsed.request) throw new Error(`Disposition rejected: ${parsed.error}.`);
+            const { model, state } = childIncidentView(ctx, cwd());
+            const outcome = resolveDisposition(model, state, parsed.request, toolCallId);
+            if (!outcome.event) {
+                const open = describeOpenTargets(model, state);
+                throw new Error(`Disposition rejected: ${outcome.error}.` + (open.length ? `\nOpen incidents:\n${open.join("\n")}` : "\nNo open incidents."));
+            }
+            const incidents = outcome.event.incidents ?? [];
+            return {
+                content: [{ type: "text" as const, text: `Recorded ${parsed.request.disposition} for ${incidents.length} incident${incidents.length === 1 ? "" : "s"}: ${incidents.join(", ")}.` }],
+                details: { disposition: parsed.request.disposition, incidents },
+            };
+        },
+    };
+}

package/docs/failure-observations.md

@@ -1,10 +1,57 @@
 # Failure observations
 
-Structured tool, model, exit, and supervision failures are collected separately from lifecycle status. A child may still be `running`, or finish its agent loop, while checks remain unresolved. List, output, result, navigator, and completion notifications expose these observations before assistant progress can suggest that the work is healthy.
+Structured tool, model, exit, and supervision failures are collected separately from lifecycle status. A child may still be `running`, or finish its agent loop, while checks remain unresolved. List, output, result, navigator, and completion notifications expose these observations before assistant progress can suggest that the work is healthy. All of them read the same reduced incident state.
 
-Each run retains a `failures.jsonl` journal. A later successful tool attempt clears an incident only when tool name, arguments, and working directory match and the retry began after the failure. Parallel or unrelated successes cannot clear it. Expected failures require explicit `expected: true` event/result metadata; prose such as “this test should fail” is not interpreted as metadata.
+Each run retains an append-only `failures.jsonl` journal. Nothing is deleted from it: recovered and superseded incidents leave the active summaries but stay in history.
 
-Running failures become eligible for attention after 60 seconds. Observation gaps are eligible immediately, and terminal runs use the existing completion callback. Delivery receipts are independent of recovery and are written after handoff; `callback:false` suppresses notifications without hiding inspection evidence.
+## What each label means
+
+| Label | Meaning |
+|---|---|
+| `Action required` | An incident that needs someone other than the child: a non-tool failure (child exit, model, supervision), the same tool operation failing three times with no recovery, or an incident the child explicitly marked `open`. |
+| `Unclassified failure observation` | A tool error the child has not disposed of. Children normally handle their own tool errors, so this is retained evidence, not the run's outcome. |
+| `Expected failure` | A non-success the child declared intentional before running the command, or disposed as `expected`. |
+| `Observation incomplete` | Missing, corrupt, truncated, or unreadable evidence. |
+| `Recovered` / `Superseded` | Closed. Counted in history, never shown as active. |
+
+A completed run reports lifecycle and incidents as separate facts, for example:
+
+```text
+status=completed
+8 earlier tool failures remain unclassified.
+Work correctness was not inferred from lifecycle alone.
+```
+
+## When the parent is notified
+
+- **While the child runs**, a single tool error does not wake the parent; the child owns it. The parent is woken, after a 60-second grace period, only for non-tool failures, for an operation that failed three times with no recovery, and for incidents the child marked `open`. Each incident is delivered once. Observation gaps (for example an oversized log record) stay visible on every surface and are delivered with the completion or health callback, since the parent cannot act on them mid-run.
+- **At completion**, every still-unresolved incident is reported once in the ordinary completion callback: actionable incidents in full, unclassified tool failures as a count. Incidents a running notification already delivered are counted, not repeated.
+- **Orphaned and lost** health callbacks carry the same facts once.
+
+Every notification renders only its pending incidents. Delivery receipts are independent of recovery and are written after handoff; `callback:false` suppresses notifications without hiding inspection evidence.
+
+## Recovery and disposition
+
+Automatic recovery still requires an exact retry: the same tool name, arguments, and working directory, started after the failure. Parallel or unrelated successes cannot clear an incident, and neither can exit 0 of another command or anything an assistant writes.
+
+Sandboxed children (the task runtime) get two structured additions. The parent honours them only for runs whose metadata it wrote as launched on the task runtime; for any other run, intent-looking arguments are ordinary arguments and `failure_disposition` calls are ignored.
+
+- `bash` accepts optional `operationId`, `attemptId`, and `expectedExitCodes`, validated before the command runs.
+  - `operationId` names one logical operation across modified retries. A later success with the same `operationId` (a changed scope, timeout, or flag) recovers the earlier failure automatically. Without it, the exact rule applies. `attemptId` names one execution for use as evidence and never changes operation identity.
+  - `expectedExitCodes` (distinct integers 1–255) declares intentional non-zero exits, such as `[1]` for an `rg`/`grep` no-match or a `git diff --exit-code` probe. Only the final shell exit code is classified, taken from the tool's structured result, never from output text. Timeouts, aborts, and undeclared codes stay ordinary failures.
+- `failure_disposition({ disposition, targets, reason, evidence? })` records an explicit classification of the child's own incidents:
+  - `recovered`: the same operation later passed. Evidence must be a successful attempt of that operation that started after the failure.
+  - `superseded`: a different verification or remediation established the outcome, such as resolving a merge conflict and continuing. Evidence must be a successful attempt that started after the failure.
+  - `expected`: the failure was intentional. A later successful retry keeps the classification.
+  - `open`: the incident still needs the parent. This makes it `Action required`.
+
+  A `bash` call whose intent is rejected (malformed fields, or a reused `attemptId`) never runs. It is recorded as its own unclassified observation, not as a failure of the command it named, so it cannot make that operation look stuck.
+
+  Targets may be incident ids, the `attemptId` or `operationId` the child declared, or tool call ids. Unknown, already-disposed, evidence-free, or partially invalid requests are rejected whole, with the open incidents listed, and nothing is written. The parent replays the same validation from the child's log before it appends the disposition to the journal, so dispositions survive reload and replay exactly once.
+
+Unconfined children keep the exact-retry rule and do not yet have these additions.
+
+## Evidence health
 
 The collector scans complete structured records independently of the finite progress tail. Missing terminal logs, unreadable records, and detected truncation are shown as **observation incomplete**. Failure classification uses structured error and exit fields; output text and domain-specific status codes are not failure signals.
 

package/failures.ts

@@ -1,14 +1,14 @@
 import { closeSync, fstatSync, openSync, readSync } from "node:fs";
 import { join } from "node:path";
-import { logPathFor, runDir } from "./registry.ts";
-import { failureIdentity, formatFailureSummary, markFailureAttentionDelivered,
+import { logPathFor, readMeta, runDir } from "./registry.ts";
+import { activeFailures, disposeIncidents, failureIdentity, formatFailureSummary, formatTerminalFailureFacts, markFailureAttentionDelivered,
     observeFailures, pendingFailureAttention, readFailureState, type FailureState } from "./shared-failure-observations.ts";
+import { evidenceText, foldToolEnd, foldToolStart, newIncidentModel, toolOperation, type IncidentModel, type IncidentSink } from "./incident-model.ts";
 
-export { formatFailureSummary, pendingFailureAttention, markFailureAttentionDelivered };
+export { formatFailureSummary, pendingFailureAttention, markFailureAttentionDelivered, toolOperation };
 export const failurePath = (id: string) => join(runDir(id), "failures.jsonl");
 export const readRunFailures = (id: string): FailureState => readFailureState(failurePath(id));
-interface Attempt { operation: string; sequence: number }
-interface Scan { offset: number; head: string; identity: string; attempts: Map<string, Attempt>; failed: Map<string, { id: string; sequence: number }>; sequence: number; retry?: number }
+interface Scan { offset: number; head: string; identity: string; model: IncidentModel; retry?: number }
 const scans = new Map<string, Scan>();
 /** Drop an in-memory scan cursor (e.g. on reload); the journal remains authoritative. */
 export function resetFailureScanCursor(id?: string): void {
@@ -17,79 +17,57 @@ export function resetFailureScanCursor(id?: string): void {
 }
 const CHUNK = 64 * 1024;
 const MAX_LINE = 2 * 1024 * 1024;
-function stable(value: unknown): unknown {
-    if (Array.isArray(value)) return value.map(stable);
-    if (value && typeof value === "object") return Object.fromEntries(Object.entries(value).sort(([a], [b]) => a.localeCompare(b)).map(([k, v]) => [k, stable(v)]));
-    return value;
-}
-export function toolOperation(name: string, args: unknown, cwd: string): string {
-    return failureIdentity("tool", name, stable(args ?? {}), cwd);
-}
-function evidence(value: unknown): string | undefined {
-    if (value == null) return undefined;
-    const raw = typeof value === "string" ? value : JSON.stringify(value);
-    return raw?.replace(/[\x00-\x1f\x7f]/g, " ").slice(0, 300);
-}
-function resultError(result: any): string | undefined {
-    if (result?.isError === true || (typeof result?.exitCode === "number" && result.exitCode !== 0)) {
-        return evidence(result?.content?.find?.((x: any) => x?.type === "text")?.text ?? result?.stderr ?? result?.error ?? result);
-    }
-    return undefined;
-}
 function time(event: any): number | undefined {
     return typeof event.at === "number" && Number.isFinite(event.at) ? event.at :
         typeof event.message?.timestamp === "number" && Number.isFinite(event.message.timestamp) ? event.message.timestamp : undefined;
 }
+function sinkFor(id: string): IncidentSink {
+    const path = failurePath(id);
+    return {
+        observe: (events) => observeFailures(path, events),
+        dispose: (event) => { disposeIncidents(path, event); },
+        state: () => readFailureState(path),
+    };
+}
 function fold(id: string, scan: Scan, row: any, offset: number, cwd: string): void {
-    const eventId = typeof row.toolCallId === "string" ? row.toolCallId : `offset:${offset}`;
-    const seq = ++scan.sequence;
     const path = failurePath(id);
+    const model = scan.model;
     if (row.type === "tool_execution_start") {
-        scan.attempts.set(eventId, { operation: toolOperation(String(row.toolName ?? "unknown"), row.args, cwd), sequence: seq });
+        foldToolStart(model, row, cwd, sinkFor(id));
     } else if (row.type === "tool_execution_end") {
-        const attempt = scan.attempts.get(eventId);
-        if (attempt) scan.attempts.delete(eventId);
-        const operation = attempt?.operation ?? toolOperation(String(row.toolName ?? "unknown"), row.args, cwd);
-        const error = row.isError === true ? evidence(row.result) ?? "Tool returned an error" : resultError(row.result);
-        if (error) {
-            const failureId = `tool:${eventId}`;
-            const state = observeFailures(path, [{ id: failureId, operation, kind: "failure", at: time(row), category: "tool",
-                summary: `${row.toolName ?? "Tool"} failed: ${error.slice(0, 180)}`, evidence: `${logPathFor(id)}#byte=${offset}`,
-                expected: row.expected === true || row.result?.expected === true }]);
-            scan.failed.set(operation, { id: state.observations[failureIdentity(operation)]?.id ?? failureId, sequence: seq });
-        } else if (attempt) {
-            const failed = scan.failed.get(operation);
-            if (failed && attempt.sequence > failed.sequence) {
-                observeFailures(path, [{ id: `recovered:${eventId}`, operation, kind: "recovered", at: time(row), incidents: [failed.id] }]);
-                scan.failed.delete(operation);
-            }
-        }
+        foldToolEnd(model, row, cwd, `${logPathFor(id)}#byte=${offset}`, sinkFor(id));
     } else if (row.type === "message_end" && row.message?.role === "assistant" &&
         (row.message.stopReason === "error" || typeof row.message.errorMessage === "string")) {
-        const message = evidence(row.message.errorMessage) ?? "Model response failed";
+        const seq = ++model.sequence;
+        const message = evidenceText(row.message.errorMessage) ?? "Model response failed";
         const failureId = `model:${offset}`;
         const state = observeFailures(path, [{ id: failureId, operation: "model-call", kind: "failure", at: time(row), category: "model", summary: message }]);
-        scan.failed.set("model-call", { id: state.observations[failureIdentity("model-call")]?.id ?? failureId, sequence: seq });
+        model.failed.set("model-call", { id: state.observations[failureIdentity("model-call")]?.id ?? failureId, sequence: seq });
     } else if (row.type === "auto_retry_start") {
+        const seq = ++model.sequence;
         if (typeof row.errorMessage === "string") {
             const failureId = `model-retry:${offset}`;
             const state = observeFailures(path, [{ id: failureId, operation: "model-call", kind: "failure", at: time(row), category: "model", summary: row.errorMessage }]);
-            scan.failed.set("model-call", { id: state.observations[failureIdentity("model-call")]?.id ?? failureId, sequence: seq - 1 });
+            model.failed.set("model-call", { id: state.observations[failureIdentity("model-call")]?.id ?? failureId, sequence: seq - 1 });
         }
         scan.retry = seq;
     } else if (row.type === "auto_retry_end" && row.success === false) {
+        const seq = ++model.sequence;
         const failureId = `model-exhausted:${offset}`;
         const state = observeFailures(path, [{ id: failureId, operation: "model-call", kind: "failure", at: time(row), category: "model",
-            summary: evidence(row.finalError) ?? "Model retry exhausted" }]);
-        scan.failed.set("model-call", { id: state.observations[failureIdentity("model-call")]?.id ?? failureId, sequence: seq });
+            summary: evidenceText(row.finalError) ?? "Model retry exhausted" }]);
+        model.failed.set("model-call", { id: state.observations[failureIdentity("model-call")]?.id ?? failureId, sequence: seq });
         scan.retry = undefined;
     } else if (row.type === "auto_retry_end" && row.success === true && scan.retry !== undefined) {
-        const failed = scan.failed.get("model-call");
+        ++model.sequence;
+        const failed = model.failed.get("model-call");
         if (failed && scan.retry > failed.sequence) {
             observeFailures(path, [{ id: `model-recovered:${offset}`, operation: "model-call", kind: "recovered", at: time(row), incidents: [failed.id] }]);
-            scan.failed.delete("model-call");
+            model.failed.delete("model-call");
         }
         scan.retry = undefined;
+    } else {
+        ++model.sequence;
     }
 }
 /** Scan complete source records, independent of the finite progress/transcript tail. */
@@ -118,7 +96,9 @@ export function collectRunFailures(id: string, cwd: string, terminal = false): F
             observeFailures(path, [{ id: failureIdentity("log-rewritten", scan.head, scan.offset), operation: "child-log", kind: "incomplete", summary: "Child log was truncated or rewritten; observations may be incomplete" }]);
             scan = undefined;
         }
-        if (!scan) scan = { offset: 0, head, identity, attempts: new Map(), failed: new Map(), sequence: 0 };
+        // Structured intent and dispositions are honoured only for runs launched on the trusted task
+        // runtime, whose bash and failure_disposition tools are the guarded ones (parent-written metadata).
+        if (!scan) scan = { offset: 0, head, identity, model: newIncidentModel(readMeta(id)?.taskRuntime === true) };
         scan.head = head;
         let position = scan.offset;
         let start = position;
@@ -177,8 +157,17 @@ export function collectRunFailures(id: string, cwd: string, terminal = false): F
     } finally { closeSync(fd); }
     return readRunFailures(id);
 }
+/**
+ * The one presentation of a run's reduced incident state for the navigator. Running: prioritized
+ * active rows. Terminal: actionable and incomplete rows, with unclassified agent tool failures
+ * counted rather than presented as the run's outcome (#315).
+ */
+export function runFailureFacts(state: FailureState, terminal: boolean): string {
+    if (!terminal) return formatFailureSummary(state);
+    return formatTerminalFailureFacts(state, activeFailures(state).map((x) => x.id));
+}
 export function failureSummary(id: string, cwd: string, terminal = false): string {
-    return formatFailureSummary(collectRunFailures(id, cwd, terminal));
+    return runFailureFacts(collectRunFailures(id, cwd, terminal), terminal);
 }
 export function prependFailureSummary(body: string, summary: string): string {
     if (!summary) return body;

package/finalization.ts

@@ -10,11 +10,10 @@ import { collectRunFailures, failurePath } from "./failures.ts";
 import { observeFailures } from "./shared-failure-observations.ts";
 import {
     classifyChildExit,
-    formatSubagentResult,
-    resolveLifecycle,
     type ChildExitOutcome,
 } from "./lifecycle.ts";
-import { parseRunForLifecycle, tailLog } from "./parse.ts";
+import { assembleSubagentResult } from "./output-payload.ts";
+import { parseRunForLifecycle } from "./parse.ts";
 import {
     canExitFinalize,
     effectiveStatus,
@@ -89,7 +88,8 @@ export function finalizeRun(
     const verdict = outcome.verdict;
     const el = fmtElapsed(meta.endedAt - meta.startedAt);
     const spend = fmtSpend(r.usage);
-    const stat = `${el}${spend ? ` · ${spend}` : ""}`;
+    const humanStat = `${el}${spend ? ` · ${spend}` : ""}`;
+    const stat = el;
 
     // A finished run is no longer in the widget; redraw (and stop the ticker if
     // it was the last one).
@@ -98,7 +98,7 @@ export function finalizeRun(
     // Best-effort human toast. ctx may be stale by now; never let it throw.
     try {
         hooks.notify?.(
-            `Subagent ${label} ${verdict} · ${stat}`,
+            `Subagent ${label} ${verdict} · ${humanStat}`,
             meta.status === "completed" ? "info" : "warning",
         );
     } catch {
@@ -138,28 +138,19 @@ export function finalizeRun(
  * Returns null when the run is still live so the tool can emit its running message.
  */
 export function buildSubagentResultText(id: string): string | null {
+    return buildSubagentResultPayload(id);
+}
+
+/** Optional paging/raw evidence for the registered result tool. */
+export function buildSubagentResultPayload(
+    id: string,
+    request?: { cursor?: string; maxBytes?: unknown; mode?: unknown; all?: unknown },
+    healthLine = "",
+    scopeKey = `parent:${process.pid}`,
+): string | null {
     const meta = readMeta(id);
     if (!meta) throw new Error(`Unknown run id: ${id}`);
     const st = effectiveStatus(meta);
-    // Non-final statuses (running / orphaned) have no final result body.
     if (!isFinalResultStatus(st)) return null;
-
-    const exit = meta.exitCode === undefined ? "?" : String(meta.exitCode);
-    // Re-derive lifecycle diagnostics from the complete stream even when meta is stale.
-    const r = parseRunForLifecycle(id);
-    const el = fmtElapsed((meta.endedAt ?? Date.now()) - meta.startedAt);
-    const spend = fmtSpend(r.usage);
-    const statSeg = ` · ${el}${spend ? ` · ${spend}` : ""}`;
-    const tools = r.toolCalls.length ? ` · tools: ${r.toolCalls.join(", ")}` : "";
-    const lifecycle = resolveLifecycle(meta, r);
-    return formatSubagentResult({
-        id,
-        status: st,
-        exitCode: exit,
-        statSeg,
-        toolsSeg: tools,
-        run: r,
-        rawLogTail: tailLog(id, 40),
-        lifecycle,
-    });
+    return assembleSubagentResult(id, meta, request ?? {}, healthLine, scopeKey);
 }