@cr1ms0n/pi-subagent 0.9.0 → 0.11.0

package/src/output.ts

@@ -1,5 +1,6 @@
 import { Buffer } from "node:buffer";
 import type { SubagentConfig } from "./config.js";
+import { earlierAttemptOutputNote } from "./model-failover.js";
 import type { OutputMode, RunSnapshot, TaskResult } from "./types.js";
 
 export interface CappedDelivery {
@@ -9,15 +10,16 @@ export interface CappedDelivery {
   totalLines: number;
 }
 
-function finalAssistantText(messages: any[]): string | undefined {
+function finalAssistantText(messages: any[], latestOnly = false): string | undefined {
   for (let i = messages.length - 1; i >= 0; i--) {
     const message = messages[i];
-    if (message?.role !== "assistant" || !Array.isArray(message.content)) continue;
+    if (message?.role !== "assistant") continue;
+    if (!Array.isArray(message.content)) { if (latestOnly) return undefined; continue; }
     const text = message.content
       .filter((part: any) => part?.type === "text" && typeof part.text === "string")
       .map((part: any) => part.text)
       .join("");
-    if (text) return text;
+    if (text || latestOnly) return text || undefined;
   }
   return undefined;
 }
@@ -87,7 +89,10 @@ export class OutputManager {
         // the narrative preamble around the fenced block.
         raw = JSON.stringify(result.structuredOutput, null, 2);
       } else {
-        raw = result.finalOutput || finalAssistantText(result.messages || []) || result.liveText || result.errorMessage || result.stderr || "(no output)";
+        const primary = result.finalOutput || finalAssistantText(result.messages || [], !!result.routing?.rankedModels) || result.liveText;
+        raw = primary || result.errorMessage || result.stderr || "(no output)";
+        const earlier = !primary ? earlierAttemptOutputNote(result) : undefined;
+        if (earlier) raw += `\n\n${earlier}`;
       }
       const artifact = result.outputFile ? ` Full output: ${result.outputFile}` : " Full output is in the child session transcript.";
       const marker = `[Truncated.${artifact}]`;

package/src/persistence.ts

@@ -1,7 +1,14 @@
 import { Buffer } from "node:buffer";
 import type { SubagentConfig } from "./config.js";
-import { MAX_ROUTING_TOOL_QUESTIONS, type RoutingReceipt } from "./routing-types.js";
-import type { ChildProcessIdentity, RunMode, RunSnapshot, RunState, TaskProfile, TaskRouting, TaskSpec, TimeoutPhase, UsageStats } from "./types.js";
+import {
+  MAX_ATTEMPT_PREVIEW_BYTES,
+  MAX_MODEL_ATTEMPT_RECORDS,
+  trimAttemptPreviews,
+  utf8SafePrefix,
+  validateModelRanking,
+} from "./model-failover.js";
+import { MAX_ROUTING_MODEL_ID_LENGTH, MAX_ROUTING_TOOL_QUESTIONS, type RankedModelOption, type RoutingReceipt } from "./routing-types.js";
+import type { ChildProcessIdentity, ModelAttemptRecord, ModelFailureCategory, RunMode, RunSnapshot, RunState, TaskProfile, TaskRouting, TaskSpec, TimeoutPhase, ToolActivity, UsageStats } from "./types.js";
 import { emptyUsage } from "./types.js";
 import { isThinkingLevel } from "./thinking.js";
 
@@ -46,6 +53,20 @@ const MAX_ROUTING_VERSION_LENGTH = 128;
 const MAX_ROUTING_MODEL_LENGTH = 256;
 const MAX_ROUTING_LIST = 256;
 
+const TOOL_ACTIVITY_STATES = ["none", "started", "unknown"] as const;
+const MODEL_FAILURE_CATEGORIES: readonly ModelFailureCategory[] = [
+  "model_unavailable",
+  "rate_limited",
+  "service_overload",
+  "transport",
+  "auth",
+  "quota",
+  "invalid_request",
+  "context_overflow",
+  "refusal",
+  "unknown",
+];
+
 function routingString(value: unknown, max = MAX_ROUTING_ID_LENGTH): string | undefined {
   if (typeof value !== "string") return undefined;
   const trimmed = value.trim();
@@ -138,6 +159,27 @@ export function normalizeTaskRouting(value: unknown): TaskRouting | undefined {
   const selectorVersions = routingStringArray(r.selectorVersions, MAX_ROUTING_TOOL_QUESTIONS + 1);
   const receiptIds = routingStringArray(r.receiptIds, MAX_ROUTING_TOOL_QUESTIONS + 1);
   const latencyMs = routingNonNegativeNumber(r.latencyMs);
+  // Probability ranking is display/history metadata on reload. Any malformed or
+  // oversized entry drops the WHOLE field: a partially decoded ranking must
+  // never exist downstream, and persisted rankings are never re-finalized into
+  // an executable attempt plan regardless.
+  let rankedModels: readonly RankedModelOption[] | undefined;
+  if (Array.isArray(r.rankedModels) && r.rankedModels.length > 0 && r.rankedModels.length <= MAX_MODEL_ATTEMPT_RECORDS) {
+    const entries: RankedModelOption[] = [];
+    let valid = true;
+    for (const raw of r.rankedModels) {
+      if (!raw || typeof raw !== "object" || Array.isArray(raw)) { valid = false; break; }
+      const entry = raw as Record<string, unknown>;
+      const model = routingString(entry.model, MAX_ROUTING_MODEL_ID_LENGTH);
+      const probability = entry.probability;
+      if (!model || typeof probability !== "number" || !Number.isFinite(probability) || probability < 0 || probability > 1) { valid = false; break; }
+      entries.push(Object.freeze({ model, probability }));
+    }
+    if (valid && (r.rankedTotal === undefined || r.rankedTotal === entries.length)
+      && validateModelRanking(entries, entries.map((entry) => entry.model), selectedModel) === undefined) {
+      rankedModels = Object.freeze(entries);
+    }
+  }
 
   return Object.freeze({
     decisionId,
@@ -146,6 +188,7 @@ export function normalizeTaskRouting(value: unknown): TaskRouting | undefined {
     selectedModel,
     selectedTools,
     ...(confidence === undefined ? {} : { confidence }),
+    ...(rankedModels === undefined ? {} : { rankedModels }),
     selectorModel,
     ...(selectorVersion === undefined ? {} : { selectorVersion }),
     selectorVersions: selectorVersions ?? (selectorVersion ? Object.freeze([selectorVersion]) : Object.freeze([])),
@@ -343,6 +386,10 @@ export interface PersistedResult {
   attempts?: number;
   /** Models tried across attempts, in order. */
   attemptedModels?: string[];
+  /** Sticky tool-activity boundary state across the task's attempts. */
+  toolActivity?: ToolActivity;
+  /** Bounded ranked attempt history; previews capped, never executable. */
+  modelAttempts?: ModelAttemptRecord[];
   /** Parsed structured result when output_schema validated. */
   structuredOutput?: unknown;
   /** Validation errors when output_schema was requested but failed. */
@@ -429,6 +476,72 @@ function utf8Prefix(value: string, maxBytes: number): string {
   return buffer.subarray(0, end).toString("utf8");
 }
 
+/**
+ * Bounded decode of the ranked attempt history. Any structurally invalid or
+ * over-cap record drops the whole optional field (never a partial ranking),
+ * and retained previews beyond the task total lose OLDEST text first while
+ * keeping metadata/session pointers. Decoded records are descriptive only:
+ * they never authorize execution.
+ */
+export function normalizeModelAttempts(value: unknown): ModelAttemptRecord[] | undefined {
+  if (!Array.isArray(value) || value.length === 0 || value.length > MAX_MODEL_ATTEMPT_RECORDS) return undefined;
+  const records: ModelAttemptRecord[] = [];
+  for (const raw of value) {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) return undefined;
+    const entry = raw as Record<string, unknown>;
+    const attempt = routingNonNegativeInt(entry.attempt);
+    const rank = routingNonNegativeInt(entry.rank);
+    const model = routingString(entry.model, MAX_ROUTING_MODEL_ID_LENGTH);
+    const probability = entry.probability;
+    const outcome = isRunState(entry.outcome) ? entry.outcome : undefined;
+    if (attempt === undefined || attempt !== records.length + 1 || attempt > MAX_MODEL_ATTEMPT_RECORDS
+      || rank === undefined || rank >= MAX_MODEL_ATTEMPT_RECORDS || !model
+      || typeof probability !== "number" || !Number.isFinite(probability) || probability < 0 || probability > 1
+      || outcome === undefined) return undefined;
+    const stopReason = entry.stopReason === undefined ? undefined : routingString(entry.stopReason, 128);
+    if (entry.stopReason !== undefined && stopReason === undefined) return undefined;
+    const failureCategory = entry.failureCategory === undefined
+      ? undefined
+      : (MODEL_FAILURE_CATEGORIES as readonly string[]).includes(String(entry.failureCategory))
+        ? (entry.failureCategory as ModelFailureCategory)
+        : undefined;
+    const toolActivity = (TOOL_ACTIVITY_STATES as readonly string[]).includes(String(entry.toolActivity))
+      ? (entry.toolActivity as ToolActivity)
+      : undefined;
+    const sessionId = entry.sessionId === undefined ? undefined : routingString(entry.sessionId, MAX_ROUTING_ID_LENGTH);
+    if (entry.sessionId !== undefined && sessionId === undefined) return undefined;
+    const outputPreview = typeof entry.outputPreview === "string"
+      ? utf8SafePrefix(entry.outputPreview, MAX_ATTEMPT_PREVIEW_BYTES) || undefined
+      : undefined;
+    records.push({
+      attempt,
+      rank,
+      model,
+      probability,
+      outcome,
+      ...(stopReason === undefined ? {} : { stopReason }),
+      ...(failureCategory === undefined ? {} : { failureCategory }),
+      ...(toolActivity === undefined ? {} : { toolActivity }),
+      ...(sessionId === undefined ? {} : { sessionId }),
+      ...(outputPreview === undefined ? {} : { outputPreview }),
+    });
+  }
+  trimAttemptPreviews(records);
+  return records;
+}
+
+/** Bounded compatibility model chain; repeated IDs are valid for infrastructure retries. */
+export function normalizeAttemptedModels(value: unknown): string[] | undefined {
+  if (!Array.isArray(value) || value.length === 0 || value.length > MAX_MODEL_ATTEMPT_RECORDS) return undefined;
+  const models: string[] = [];
+  for (const entry of value) {
+    const model = routingString(entry, MAX_ROUTING_MODEL_ID_LENGTH);
+    if (!model) return undefined;
+    models.push(model);
+  }
+  return models;
+}
+
 function normalizeResult(value: unknown): PersistedResult | undefined {
   if (!value || typeof value !== "object") return undefined;
   const r = value as Partial<PersistedResult>;
@@ -464,9 +577,11 @@ function normalizeResult(value: unknown): PersistedResult | undefined {
     wrappedUp: r.wrappedUp === true ? true : undefined,
     stalledSince: typeof r.stalledSince === "number" && Number.isFinite(r.stalledSince) ? r.stalledSince : undefined,
     attempts: typeof r.attempts === "number" && Number.isInteger(r.attempts) && r.attempts > 1 ? r.attempts : undefined,
-    attemptedModels: Array.isArray(r.attemptedModels)
-      ? r.attemptedModels.filter((m): m is string => typeof m === "string").slice(0, 10)
+    attemptedModels: normalizeAttemptedModels(r.attemptedModels),
+    toolActivity: (TOOL_ACTIVITY_STATES as readonly string[]).includes(String((r as { toolActivity?: unknown }).toolActivity))
+      ? (r as { toolActivity?: ToolActivity }).toolActivity
       : undefined,
+    modelAttempts: normalizeModelAttempts((r as { modelAttempts?: unknown }).modelAttempts),
     structuredOutput: r.structuredOutput !== undefined && Buffer.byteLength(JSON.stringify(r.structuredOutput) ?? "", "utf8") <= 32_768
       ? r.structuredOutput
       : undefined,
@@ -619,8 +734,15 @@ export class PersistenceLayer {
       if (typeof event.data.childSessionId === "string") ids.add(event.data.childSessionId);
       if (Array.isArray(event.data.results)) {
         for (const result of event.data.results) {
-          const sessionId = (result as Partial<PersistedResult>)?.sessionId;
+          const partial = result as Partial<PersistedResult>;
+          const sessionId = partial?.sessionId;
           if (typeof sessionId === "string" && sessionId) ids.add(sessionId);
+          // Earlier ranked attempts stay referenced while their result record
+          // survives on the active branch, so lifecycle distillation cannot
+          // delete still-discoverable paid partial output.
+          for (const record of normalizeModelAttempts(partial?.modelAttempts) ?? []) {
+            if (record.sessionId) ids.add(record.sessionId);
+          }
         }
       }
     }

package/src/policy.ts

@@ -3,10 +3,11 @@ import type { AgentDefinition } from "./agents.js";
 import { resolveAgent } from "./agents.js";
 import { isPlausibleSchema, repairDoubleEncodedText } from "./structured.js";
 import { defaultConfig, type TaskDefaults, type TaskDefaultsByProfile } from "./config.js";
-import type { OutputMode, TaskProfile, TaskSpec } from "./types.js";
+import type { ModelAttemptSpec, OutputMode, TaskProfile, TaskSpec } from "./types.js";
 import type { ParallelTaskInput, SubagentParams } from "./schema.js";
 import { BACKEND_NAMES, checkCapabilities, type BackendName } from "./backend.js";
 import { resolveBackend } from "./backends/index.js";
+import { validateModelRanking } from "./model-failover.js";
 import type { JevRoutingConfig, RoutingDecision, RoutingModelCandidate } from "./routing-types.js";
 import { isThinkingLevel } from "./thinking.js";
 
@@ -548,11 +549,33 @@ export function finalizeRoutedTasks(
     const tools = [...new Set([...decision.selectedTools, ...item.mandatoryTools])];
     const canWrite = tools.some((tool) => !NON_WRITING_TOOLS.has(tool));
     if (item.profile !== "general" && canWrite) return { ok: false, error: `Task ${index + 1}: writable selector choice violates ${item.profile}.` };
+    // The probability ranking is mandatory for every new route: without it there
+    // is no failover plan, and a persisted/legacy decision shape must never be
+    // silently re-promoted into one.
+    const ranked = decision.rankedModels;
+    const rankingProblem = validateModelRanking(ranked, models.map((entry) => entry.model), decision.selectedModel);
+    if (rankingProblem) return { ok: false, error: `Task ${index + 1}: ${rankingProblem}.` };
     const { candidateTools: _candidates, mandatoryTools, requestedThinking, parentThinking, ...spec } = item;
-    const thinking = requestedThinking ?? candidate.thinking ?? parentThinking;
+    // One frozen attempt plan per ranked candidate: same shared tools and route,
+    // per-candidate thinking under explicit > agent > profile > candidate > parent.
+    const modelAttemptPlan: ModelAttemptSpec[] = [];
+    for (const entry of ranked!) {
+      const candidateEntry = models.find((model) => model.model === entry.model)!;
+      const thinking = requestedThinking ?? candidateEntry.thinking ?? parentThinking;
+      if (thinking !== undefined && !isThinkingLevel(thinking)) {
+        return { ok: false, error: `Task ${index + 1}: candidate ${JSON.stringify(entry.model)} has an invalid Pi thinking default.` };
+      }
+      modelAttemptPlan.push(Object.freeze({
+        model: entry.model,
+        probability: entry.probability,
+        ...(thinking === undefined ? {} : { thinking }),
+      }));
+    }
+    const first = modelAttemptPlan[0]!;
     tasks.push({
-      ...spec, model: candidate.model, thinking, tools, effectiveTools: tools, canWrite,
+      ...spec, model: candidate.model, thinking: first.thinking, tools, effectiveTools: tools, canWrite,
       fallbackModels: [],
+      modelAttemptPlan: Object.freeze(modelAttemptPlan),
       routing: { ...decision, mandatoryTools: [...mandatoryTools], outcome: "success" },
       resolutionNotes: [...item.resolutionNotes.filter((note) => !note.startsWith("routing=")), "routing=jev", `access=${canWrite ? "RW" : "RO"}`],
     });

package/src/process-lock.ts

@@ -4,6 +4,7 @@ import * as fsp from "node:fs/promises";
 import * as os from "node:os";
 import * as path from "node:path";
 import { defaultConfig } from "./config.js";
+import { MAX_ROUTING_MODELS } from "./routing-types.js";
 
 /**
  * Durable, crash-surviving coordination primitives under `~/.pi/subagent-locks/`.
@@ -48,6 +49,8 @@ export interface RunProcessRecord {
   runId: string;
   parentSessionKey: string;
   childSessionId?: string;
+  /** Ranked task's attempt sessions, protected together until final terminalization. */
+  childSessionIds?: string[];
   /** Live worktree checkout of this run; shields it from machine-wide GC sweeps. */
   worktreeCwd?: string;
   process: ProcessIdentity;
@@ -57,6 +60,12 @@ export interface RunProcessRecord {
   updatedAt: number;
 }
 
+/** Bounded machine-wide session protection; old single-session records still work. */
+export function runRecordSessionIds(record: RunProcessRecord): string[] {
+  const values: unknown[] = [record.childSessionId, ...(Array.isArray(record.childSessionIds) ? record.childSessionIds.slice(0, MAX_ROUTING_MODELS) : [])];
+  return [...new Set(values.filter((value): value is string => typeof value === "string" && value.trim().length > 0 && value.length <= 256))].slice(0, MAX_ROUTING_MODELS);
+}
+
 export interface SlotToken {
   slotId: string;
   path: string;
@@ -582,6 +591,13 @@ export class ProcessLockManager {
   // ---- Run process records (orphan reconcile) ------------------------------
 
   writeRunRecord(record: RunProcessRecord): void {
+    const previous = this.readRunRecord(record.runId);
+    if (record.childSessionIds !== undefined || (previous?.state === "running" && previous.childSessionIds !== undefined)) {
+      record = { ...record, childSessionIds: [...new Set([
+        ...runRecordSessionIds(record),
+        ...(previous?.state === "running" ? runRecordSessionIds(previous) : []),
+      ])].slice(0, MAX_ROUTING_MODELS) };
+    }
     writeJsonAtomicSync(runRecordPath(this.root, record.runId), record);
   }
 

package/src/protocol.ts

@@ -1,7 +1,8 @@
 import type { Message } from "@earendil-works/pi-ai";
-import type { TaskResult, UsageStats } from "./types.js";
+import type { TaskResult, ToolActivity, UsageStats } from "./types.js";
 import { emptyUsage } from "./types.js";
 import { addUsage, hasBilledUsage, usageFromMessage, usageFromToolResultMessage } from "./usage.js";
+import { extractProviderError, mergeToolActivity } from "./model-failover.js";
 import { PREFLIGHT_ACK_TYPE } from "./startup-check.js";
 
 export type ProtocolUpdate =
@@ -33,6 +34,7 @@ export class ProtocolParser {
   private messages: Message[] = [];
   private usage = emptyUsage();
   private liveText = "";
+  private assistantText?: string;
   private parseErrors = 0;
   private validEvents = 0;
   private headerSeen = false;
@@ -43,6 +45,25 @@ export class ProtocolParser {
   private model?: string;
   private stopReason?: string;
   private errorMessage?: string;
+  /**
+   * Sticky current-invocation tool activity for the pre-tool switch boundary. Latches `started` on
+   * tool_execution_start, a completed assistant toolCall or a toolResult; any
+   * malformed/dropped protocol evidence raises an otherwise-clean `none` to
+   * `unknown`. A later complete event never erases started/unknown and events
+   * from resumed/forked history never reach this parser at all (only this
+   * child's live event stream does), so historical tool records cannot create
+   * false live activity.
+   */
+  private toolActivity: ToolActivity = "none";
+  /** stopReason of the latest completed assistant message (settle diagnosis). */
+  private lastAssistantStopReason?: string;
+  /**
+   * Bounded errorMessage and primitive diagnostics.error.code from the latest
+   * completed assistant error, the only availability-classification input.
+   * Replaced on every completed assistant message; never mixed with normal
+   * content, arbitrary diagnostics or runner/RPC fallback text.
+   */
+  private providerError?: string;
   private transcriptLines: string[] = [];
   private transcriptBytes = 0;
   private transcriptTruncated = false;
@@ -53,6 +74,49 @@ export class ProtocolParser {
   private static readonly MAX_LINE_BYTES = 4 * 1024 * 1024;
   private static readonly MAX_BUFFER_BYTES = 8 * 1024 * 1024;
 
+  /** Sticky failover-latch merge; never lowers an existing started/unknown mark. */
+  private noteToolActivity(observed: ToolActivity): void {
+    this.toolActivity = mergeToolActivity(this.toolActivity, observed);
+  }
+
+  /**
+   * Conservative streamed assistant delta observations: a started tool call is
+   * completed-call evidence, its end too; a delta without any start proves the
+   * model was emitting a call and the outcome may have been lost — never a
+   * conclusive `none`.
+   */
+  private observeAssistantDelta(deltaEvent: unknown): void {
+    const event = deltaEvent as Record<string, unknown> | undefined;
+    if (!event || typeof event !== "object" || typeof event.type !== "string") {
+      this.noteMalformedEvidence();
+      return;
+    }
+    if (event.type === "toolcall_start" || event.type === "toolcall_end") {
+      // Compact RPC retains contentIndex for both start/end; Pi enriches
+      // start with id/toolName, while end carries a nested toolCall. Accept
+      // the indexed form as well as identity-bearing legacy events.
+      const modern = typeof event.contentIndex === "number" && Number.isInteger(event.contentIndex) && event.contentIndex >= 0;
+      const legacy = typeof event.id === "string" && !!event.id && typeof event.toolName === "string" && !!event.toolName;
+      if (modern || legacy) this.noteToolActivity("started");
+      else this.noteMalformedEvidence();
+      return;
+    }
+    if (event.type === "toolcall_delta") {
+      if (typeof event.contentIndex === "number" && Number.isInteger(event.contentIndex) && event.contentIndex >= 0) {
+        this.noteToolActivity("unknown");
+      } else {
+        this.noteMalformedEvidence();
+      }
+    }
+  }
+
+  /** Malformed/dropped evidence: counts a parse error and blocks failover. */
+  private noteMalformedEvidence(): void {
+    this.parseErrors++;
+    // A later complete event cannot erase the uncertainty this creates.
+    this.noteToolActivity("unknown");
+  }
+
   /** Append transcript lines incrementally; never re-flattens the full message list. */
   private appendTranscript(lines: string[]): void {
     for (const line of lines) {
@@ -92,7 +156,7 @@ export class ProtocolParser {
     this.buffer += data.toString();
     // If a single line grows past the hard limit without a newline, drop it as a parse error.
     if (Buffer.byteLength(this.buffer, "utf8") > ProtocolParser.MAX_BUFFER_BYTES) {
-      this.parseErrors++;
+      this.noteMalformedEvidence();
       this.buffer = "";
       return [];
     }
@@ -113,25 +177,25 @@ export class ProtocolParser {
     const trimmed = line.trim();
     if (!trimmed) return [];
     if (Buffer.byteLength(trimmed, "utf8") > ProtocolParser.MAX_LINE_BYTES) {
-      this.parseErrors++;
+      this.noteMalformedEvidence();
       return [];
     }
     let event: any;
     try {
       event = JSON.parse(trimmed);
     } catch {
-      this.parseErrors++;
+      this.noteMalformedEvidence();
       return [];
     }
     if (!event || typeof event !== "object" || typeof event.type !== "string") {
-      this.parseErrors++;
+      this.noteMalformedEvidence();
       return [];
     }
     this.validEvents++;
 
     if (event.type === "session") {
       if (typeof event.id !== "string" || !event.id) {
-        this.parseErrors++;
+        this.noteMalformedEvidence();
         return [];
       }
       this.sessionId = event.id;
@@ -174,10 +238,63 @@ export class ProtocolParser {
       return dialog && typeof event.id === "string" ? [{ type: "ui-request", id: event.id }] : [];
     }
 
-    if (event.type === "message_update" && event.message?.role === "assistant") {
+    // Tool execution begin is the pre-tool switch boundary. Pi emits it before tool
+    // preparation (including some rejected/truncated calls); that conservative
+    // start is still the no-restart line. Only shape-valid events latch
+    // `started`; a malformed start event means a tool may have begun anyway, so
+    // it raises `unknown`, which blocks failover just like a proven start.
+    if (event.type === "tool_execution_start") {
+      if (typeof event.toolCallId === "string" && event.toolCallId
+        && typeof event.toolName === "string" && event.toolName) {
+        this.noteToolActivity("started");
+      } else {
+        this.noteMalformedEvidence();
+      }
+      return [];
+    }
+
+    // Update/end events prove execution progressed even when the start event
+    // was lost or the stream was truncated; neither may leave a `none` latch.
+    if (event.type === "tool_execution_update" || event.type === "tool_execution_end") {
+      if (typeof event.toolCallId === "string" && event.toolCallId
+        && typeof event.toolName === "string" && event.toolName) {
+        this.noteToolActivity("started");
+      } else {
+        this.noteMalformedEvidence();
+      }
+      return [];
+    }
+
+    // Modern RPC message_update events are compact: {usage, assistantMessageEvent}
+    // without the full message. Every message_update must carry a readable
+    // assistant envelope or a typed delta event; one without either is dropped
+    // evidence that could hide a tool call or the terminal error.
+    if (event.type === "message_update") {
+      const hasMessage = !!event.message && typeof event.message === "object" && !Array.isArray(event.message);
+      const hasDeltaEvent = !!event.assistantMessageEvent && typeof event.assistantMessageEvent === "object" && !Array.isArray(event.assistantMessageEvent);
+      if (!hasMessage && !hasDeltaEvent) {
+        this.noteMalformedEvidence();
+        return [];
+      }
+      if (hasDeltaEvent) this.observeAssistantDelta(event.assistantMessageEvent);
+      if (!hasMessage || event.message.role !== "assistant") {
+        // Compact streamed turn (no full message), or an unexpected envelope:
+        // the delta observation above already recorded whatever is provable.
+        return [];
+      }
+      // An assistant stream envelope whose content array carries unreadable
+      // parts could hide a tool call: uncertain, never a conclusive none.
+      if (event.message.content !== undefined
+        && (!Array.isArray(event.message.content)
+          || (event.message.content as unknown[]).some((part: any) => !part || typeof part !== "object" || Array.isArray(part)))) {
+        this.noteMalformedEvidence();
+      }
+      if (Array.isArray(event.message.content) && event.message.content.some((part: any) => part?.type === "toolCall")) {
+        this.noteToolActivity("started");
+      }
       const delta =
-        typeof event.assistantMessageEvent?.delta === "string"
-          ? event.assistantMessageEvent.delta
+        typeof (event.assistantMessageEvent as any)?.delta === "string"
+          ? (event.assistantMessageEvent as any).delta
           : this.textParts(event.message).join("");
       if (!delta) return [];
       // Cap live text growth: keep the last 64KB of visible text so long runs stay bounded.
@@ -185,24 +302,68 @@ export class ProtocolParser {
       return [{ type: "live-text", delta, liveText: this.liveText }];
     }
 
-    if (event.type === "message_end" && event.message) {
+    if (event.type === "message_end") {
+      // A message_end without a readable message object could have carried the
+      // final assistant error or a tool call; that uncertainty must not leave a
+      // conclusive `none` for the failover gate.
+      if (!event.message || typeof event.message !== "object" || Array.isArray(event.message)) {
+        this.noteMalformedEvidence();
+        return [];
+      }
       const message = event.message as Message & { customType?: unknown };
       // Startup-handshake acknowledgement: report it, but never fold verification
       // traffic into messages, transcript, live text or usage accounting.
       if (message.customType === PREFLIGHT_ACK_TYPE) {
         return [{ type: "preflight-ack", content: typeof (message as any).content === "string" ? (message as any).content : "" }];
       }
+      if (typeof message.role !== "string" || !message.role) {
+        // Roleless message envelope: nothing about it is trustworthy.
+        this.noteMalformedEvidence();
+        return [];
+      }
       this.messages.push(message);
       this.appendTranscript(this.transcriptFromMessage(message));
       if (message.role === "assistant") {
+        // Every new completed message needs a fresh terminal watermark, even
+        // when an older host omits agent_start between task and repair turns.
+        this.agentEndSeen = false;
+        this.agentSettledSeen = false;
         this.assistantEndSeen = true;
         this.usage = addUsage(this.usage, usageFromMessage(message));
         this.model ||= message.model;
         this.stopReason = message.stopReason;
         this.errorMessage = message.errorMessage;
+        const partsValid = Array.isArray(message.content) && (message.content as unknown[]).every((part: any) => !!part && typeof part === "object" && !Array.isArray(part));
+        const validShape = partsValid && typeof message.stopReason === "string";
+        this.lastAssistantStopReason = validShape ? message.stopReason : undefined;
+        if (!validShape) {
+          // Unreadable assistant content parts, non-array content, or a
+          // missing/non-string stopReason: a tool call or terminal error could
+          // be hidden in the unreadable shape, so activity becomes uncertain
+          // and no error evidence is kept.
+          this.noteMalformedEvidence();
+          this.providerError = undefined;
+        } else {
+          const toolCallParts = (message.content as any[]).some((part: any) => part?.type === "toolCall");
+          if (toolCallParts) {
+            // A completed assistant tool call is conservative execution evidence:
+            // a missing tool_execution_start/result must not authorize a restart.
+            this.noteToolActivity("started");
+          } else if (message.stopReason === "toolUse" || message.stopReason === "refusal") {
+            // Claims turn continuation on tools without a readable tool call,
+            // or a refusal shape we cannot interpret: uncertain by contract.
+            this.noteMalformedEvidence();
+          }
+          this.providerError = message.stopReason === "error"
+            ? extractProviderError(message.errorMessage, message.diagnostics)
+            : undefined;
+        }
         const text = this.textParts(message).join("");
+        this.assistantText = text; // Empty latest messages must replace earlier failed text.
         if (text) this.liveText = text;
       } else if (message.role === "toolResult") {
+        // Any completed tool result proves execution happened in this invocation.
+        this.noteToolActivity("started");
         // Pi ≥ #6671: tool results may carry nested LLM usage (e.g. a
         // grandchild subagent). Fold it into the run's cumulative spend so
         // budgets and parent ledgers see true subtree cost.
@@ -214,6 +375,13 @@ export class ProtocolParser {
 
     if (event.type === "agent_end") {
       this.agentEndSeen = true;
+      // `willRetry` must be a real boolean when present: a string "true" or any
+      // other shape means the settle boundary is unreadable, which is uncertain
+      // execution evidence and must block failover, never imply "no retry".
+      if (event.willRetry !== undefined && typeof event.willRetry !== "boolean") {
+        this.noteMalformedEvidence();
+        return [];
+      }
       // Pi may retry after agent_end (willRetry: true). That is NOT terminal;
       // only agent_settled marks a fully settled run.
       const willRetry = event.willRetry === true;
@@ -221,6 +389,18 @@ export class ProtocolParser {
       return [{ type: "agent-end", willRetry }];
     }
 
+    // A new live agent turn invalidates any earlier settle watermark: the run
+    // is running again, and only a NEW agent_end-without-retry or
+    // agent_settled may complete it. Without this reset, an old settle plus a
+    // later provider retry could fake a complete protocol around the newest
+    // terminal error.
+    if (event.type === "agent_start") {
+      this.agentEndSeen = false;
+      this.agentSettledSeen = false;
+      this.pendingRetry = false;
+      return [];
+    }
+
     if (event.type === "agent_settled") {
       this.agentSettledSeen = true;
       this.pendingRetry = false;
@@ -251,7 +431,7 @@ export class ProtocolParser {
     // Prefer agent_settled as the true terminal watermark. Fall back to
     // agent_end without a pending retry for older Pi builds that never emitted
     // agent_settled (json print historically closed after agent_end).
-    const settled = this.agentSettledSeen || (this.agentEndSeen && !this.pendingRetry);
+    const settled = !this.pendingRetry && (this.agentSettledSeen || this.agentEndSeen);
     const completeProtocol = this.headerSeen && this.assistantEndSeen && settled;
     const assistantFailed = this.stopReason === "error" || this.stopReason === "aborted";
     const successfulExit = exitCode === 0 && !signal && !assistantFailed;
@@ -299,6 +479,8 @@ export class ProtocolParser {
           : undefined),
       liveText: this.liveText || undefined,
       transcript: this.getTranscript(),
+      toolActivity: this.toolActivity,
+      providerError: this.providerError,
       protocol,
       sessionId: this.sessionId,
     };
@@ -317,4 +499,19 @@ export class ProtocolParser {
   getMessages(): Message[] {
     return [...this.messages];
   }
+
+  /** Sticky current-invocation tool activity observed by this parser. */
+  getToolActivity(): ToolActivity {
+    return this.toolActivity;
+  }
+
+  /** stopReason of the latest completed assistant message, if any. */
+  getAssistantStopReason(): string | undefined {
+    return this.lastAssistantStopReason;
+  }
+
+  /** Latest completed assistant text, including an explicitly empty message. */
+  getAssistantText(): string | undefined {
+    return this.assistantText;
+  }
 }