@cr1ms0n/pi-subagent 0.10.0 → 0.11.0

package/src/registry.ts

@@ -3,7 +3,7 @@ import { randomUUID } from "node:crypto";
 import type { Message } from "@earendil-works/pi-ai";
 import type { SubagentConfig } from "./config.js";
 import type { PersistenceAdapter, PersistedResult } from "./persistence.js";
-import { normalizeTaskRouting, PersistenceLayer } from "./persistence.js";
+import { normalizeAttemptedModels, normalizeModelAttempts, normalizeTaskRouting, PersistenceLayer } from "./persistence.js";
 import type { ProcessLockManager } from "./process-lock.js";
 import type { RunMode, RunSnapshot, RunState, TaskResult, TaskSpec } from "./types.js";
 import { emptyUsage } from "./types.js";
@@ -49,15 +49,16 @@ const terminalStates = new Set<RunState>(["completed", "partial", "failed", "can
 /** Trailing coalesce window for high-frequency "changed" events. */
 const EMIT_COALESCE_MS = 100;
 
-function finalText(messages: Message[], fallback?: string): string | undefined {
+function finalText(messages: Message[], fallback?: string, 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 fallback;
 }
@@ -96,13 +97,17 @@ export function toPersistedResult(result: TaskResult): PersistedResult {
     sessionId: result.sessionId,
     process: result.process,
     ...(routing === undefined ? {} : { routing }),
-    finalOutput: utf8Prefix(finalText(result.messages, result.liveText), 16_384),
+    finalOutput: utf8Prefix(finalText(result.messages, result.liveText, !!routing?.rankedModels), 16_384),
     transcript: utf8Prefix(result.transcript, 32_768),
     worktree: result.worktree,
     wrappedUp: result.wrappedUp,
     stalledSince: result.stalledSince,
     attempts: result.attempts,
-    attemptedModels: result.attemptedModels,
+    attemptedModels: normalizeAttemptedModels(result.attemptedModels),
+    toolActivity: result.toolActivity,
+    // Clone/validate at the projection boundary as well as reload, preserving
+    // immutable snapshots and the same producer/decoder preview limits.
+    modelAttempts: normalizeModelAttempts(result.modelAttempts),
     structuredOutput: result.structuredOutput,
     structuredError: result.structuredError,
   };
@@ -132,6 +137,13 @@ function resultFingerprint(result: TaskResult): string {
     result.structuredOutput !== undefined ? 1 : 0,
     result.structuredError?.length ?? 0,
     (result as { routing?: { decisionId?: unknown } }).routing?.decisionId ?? "",
+    // Model/attempt revision: a stable decision ID with same-length text must
+    // not keep stale UI state when the actual model, activity latch or attempt
+    // history changed between attempts.
+    result.model ?? "",
+    result.toolActivity ?? "",
+    JSON.stringify(normalizeModelAttempts(result.modelAttempts)) ?? "",
+    JSON.stringify(normalizeAttemptedModels(result.attemptedModels)) ?? "",
   ].join("|");
 }
 
@@ -173,7 +185,21 @@ export function toCheckpointResult(result: TaskResult): PersistedResult {
     wrappedUp: result.wrappedUp,
     stalledSince: result.stalledSince,
     attempts: result.attempts,
-    attemptedModels: result.attemptedModels,
+    attemptedModels: normalizeAttemptedModels(result.attemptedModels),
+    toolActivity: result.toolActivity,
+    // Checkpoints carry attempt metadata/pointers only — preview TEXT is
+    // persisted exactly once at terminal, so repeated checkpoints stay small.
+    modelAttempts: normalizeModelAttempts(result.modelAttempts)?.map((record) => ({
+      attempt: record.attempt,
+      rank: record.rank,
+      model: record.model,
+      probability: record.probability,
+      outcome: record.outcome,
+      ...(record.stopReason === undefined ? {} : { stopReason: record.stopReason }),
+      ...(record.failureCategory === undefined ? {} : { failureCategory: record.failureCategory }),
+      ...(record.toolActivity === undefined ? {} : { toolActivity: record.toolActivity }),
+      ...(record.sessionId === undefined ? {} : { sessionId: record.sessionId }),
+    })),
     ...(routing === undefined ? {} : { routing }),
   };
 }

package/src/routing-policy.ts

@@ -251,7 +251,7 @@ function routingSummary(config: JevRoutingConfig): string[] {
     lines.push(`- …and ${config.models.length - listed.length} more configured candidate(s); every configured candidate is eligible.`);
   }
   lines.push(
-    "The selector returns one execution model and an individual include/exclude decision per eligible tool. Unknown, unsafe or unavailable choices are rejected locally, and required Pi control-plane tools are added locally rather than chosen by the selector.",
+    "The selector returns probability-ranked model candidates and one task-based, model-independent include/exclude decision per eligible tool. Unknown, unsafe or unavailable choices are rejected locally, and required Pi control-plane tools are added locally. Before any tool starts, a recognized settled model-availability failure can advance through this ranking without another selector request, under the total max_retries extra-attempt budget (0 = initial attempt only; default 1). Started or uncertain tool activity, auth/quota/context/schema failures, cancellation and exhausted task budgets stop switching. Confidence is answer-level; priorities use option probabilities, with no threshold.",
   );
   return lines;
 }

package/src/routing-types.ts

@@ -102,6 +102,20 @@ export interface RoutingModelCandidate {
   readonly thinking?: string;
 }
 
+/**
+ * One probability-ranked candidate as returned by the model Choice answer.
+ * `probability` is the validated per-option value from TypeSafe's full
+ * distribution — not the answer-level `confidence` and not a measured
+ * availability or quality score. Entries are ordered by descending
+ * probability; the returned choice leads a tied maximum and remaining ties
+ * keep the configured candidate order. Zero and low probabilities remain
+ * valid candidates; no threshold is applied.
+ */
+export interface RankedModelOption {
+  readonly model: string;
+  readonly probability: number;
+}
+
 /**
  * A tool offered to the selector. The caller must have already removed mandatory local
  * additions (Pi control-plane tools) — those are never Jev questions.
@@ -181,6 +195,14 @@ export interface RoutingDecision {
   readonly selectedTools: readonly string[];
   /** Confidence of the model Choice. Diagnostic only; never a permission threshold. */
   readonly confidence?: number;
+  /**
+   * Full probability-ranked candidate list for automatic pre-tool availability
+   * failover. New router decisions always carry the complete ordered ranking.
+   * Optional only at legacy/persistence boundaries: a decoded decision without
+   * a ranking is display metadata and is never re-materialized into an
+   * executable attempt plan.
+   */
+  readonly rankedModels?: readonly RankedModelOption[];
   readonly selectorModel: string;
   /** Primary selector version: the version reported by the model response. */
   readonly selectorVersion?: string;

package/src/runner.ts

@@ -10,6 +10,7 @@ import type {
   UsageStats,
 } from "./types.js";
 import { emptyUsage } from "./types.js";
+import { addUsage } from "./usage.js";
 import { ProtocolParser, type ProtocolUpdate } from "./protocol.js";
 import { Semaphore } from "./semaphore.js";
 import { defaultConfig } from "./config.js";
@@ -85,6 +86,15 @@ export interface RunnerOptions {
   startupTimeoutMs?: number;
   /** Backend adapter override (defaults to the spec's backend, then pi). */
   backend?: BackendAdapter;
+  /**
+   * Usage already billed by prior ranked attempts of the same task. Affects
+   * in-attempt budget COMPARISONS only (so `max_cost`/`max_turns` never reset
+   * per model); the runner still reports only this attempt's own usage. The
+   * orchestrator alone produces the cumulative figure for checkpoints/results.
+   */
+  priorUsage?: UsageStats;
+  /** Internal ranked-task ownership: orchestrator terminalizes after all attempts/cleanup. */
+  deferRunTerminal?: boolean;
 }
 
 type StopReason =
@@ -149,6 +159,9 @@ export class ChildRunner {
   private readonly stallKillAfterMs: number;
   private readonly startupTimeoutMs: number;
   private readonly backendOverride?: BackendAdapter;
+  /** Prior-attempt usage included in budget comparisons (never in returned usage). */
+  private readonly budgetOffset?: UsageStats;
+  private readonly deferRunTerminal: boolean;
   /** Backend for the in-flight run; set at spawn so steer() uses the right dialect. */
   private backend: BackendAdapter = resolveBackend("pi");
 
@@ -167,10 +180,12 @@ export class ChildRunner {
     private readonly maxTaskBytes = DEFAULT_MAX_TASK_BYTES,
     options: Pick<
       RunnerOptions,
-      "graceTurns" | "stallAfterMs" | "stallKillAfterMs" | "startupTimeoutMs" | "backend"
+      "graceTurns" | "stallAfterMs" | "stallKillAfterMs" | "startupTimeoutMs" | "backend" | "priorUsage" | "deferRunTerminal"
     > = {},
   ) {
     this.backendOverride = options.backend;
+    this.budgetOffset = options.priorUsage;
+    this.deferRunTerminal = options.deferRunTerminal === true;
     this.graceTurns = options.graceTurns ?? defaultConfig.graceTurns;
     this.stallAfterMs = options.stallAfterMs ?? defaultConfig.stallAfterMs;
     this.stallKillAfterMs =
@@ -222,6 +237,10 @@ export class ChildRunner {
     };
 
     let processHandle: ChildProcess | undefined;
+    const failedBeforeSpawn = (error: unknown): boolean => {
+      const code = (error as NodeJS.ErrnoException | undefined)?.code;
+      return !processHandle?.pid && (code === "ENOENT" || code === "EPERM" || code === "EACCES");
+    };
     let slotHeld = false;
     let globalSlot: SlotToken | undefined;
     let forceKillTimer: NodeJS.Timeout | undefined;
@@ -256,6 +275,12 @@ export class ChildRunner {
     // `spec.routing` is added by the extension only for Jev-routed dispatches; the
     // trusted low-level SDK never sets it, so unrouted runs keep the old lifecycle.
     const routed = spec.routing !== undefined;
+    // Ranked extension runs carry a locally finalized probability plan. They get
+    // the stricter structured-output contract (no repair prompt and no final
+    // structuredOutput publication after a terminal provider error/abort or a
+    // failed/cancelled/timed-out settle). Trusted unranked SDK semantics stay
+    // exactly as before.
+    const ranked = routed && Array.isArray(spec.modelAttemptPlan) && spec.modelAttemptPlan.length > 0;
     let taskPromptSent = false;
     const absoluteDeadline =
       typeof spec.deadline === "number" && Number.isFinite(spec.deadline) ? spec.deadline : undefined;
@@ -473,6 +498,9 @@ export class ChildRunner {
         ...result,
         liveText: parser.getLiveText(),
       };
+      // Live sticky tool activity when the parser observes it (Pi adapter).
+      const liveActivity = parser.getToolActivity?.();
+      if (liveActivity !== undefined) checkpoint.toolActivity = liveActivity;
       if (withTranscript) checkpoint.transcript = parser.getTranscript();
       else delete checkpoint.transcript;
       this.onCheckpoint?.(checkpoint);
@@ -563,8 +591,16 @@ export class ChildRunner {
           // Structured-output gate: validate before letting the child exit.
           // Invalid → one steer-based repair round (a fresh prompt keeps the
           // RPC child alive and produces a new settle when it finishes).
-          if (spec.outputSchema && !requestedStop && !pendingBudgetStop) {
-            const extracted = extractStructuredResult(parser.getLiveText());
+          // Ranked exception: a settled assistant provider error/abort must NOT
+          // receive an extra same-model repair prompt — that prompt would add
+          // unintended work ahead of the ranked failover decision. A ranked
+          // parser without this observation capability is also not proof of a
+          // clean settle (fail closed); the unranked path is untouched.
+          const settledAssistantStop = parser.getAssistantStopReason?.();
+          const providerTerminated = settledAssistantStop === "error" || settledAssistantStop === "aborted"
+            || (ranked && settledAssistantStop === undefined);
+          if (spec.outputSchema && !requestedStop && !pendingBudgetStop && !(ranked && providerTerminated)) {
+            const extracted = extractStructuredResult(ranked ? parser.getAssistantText?.() : parser.getLiveText());
             const check =
               extracted.value !== undefined
                 ? checkAgainstSchema(extracted.value, spec.outputSchema)
@@ -608,6 +644,9 @@ export class ChildRunner {
         state: "timeout",
         stopReason: "timeout",
         timeoutPhase: phase,
+        // A "queued" phase is runner-owned proof the slot was never held, so no
+        // child could have begun work; other phases are not pre-work conclusive.
+        preWorkInfraFailure: phase === "queued" ? true : base.preWorkInfraFailure,
         errorMessage:
           phase === "queued"
             ? "Timed out waiting for a process slot (never started)"
@@ -623,6 +662,7 @@ export class ChildRunner {
         result.stopReason = requestedStop ?? "cancelled";
         result.timeoutPhase =
           requestedStop === "timeout" ? (timeoutPhase ?? "queued") : undefined;
+        result.preWorkInfraFailure = result.timeoutPhase === "queued" ? true : undefined;
         result.exitCode = 1;
         result.endedAt = Date.now();
         if (result.state === "timeout" && !result.errorMessage) {
@@ -675,6 +715,10 @@ export class ChildRunner {
           result.errorMessage = error?.message ?? String(error);
           result.exitCode = 1;
           result.endedAt = Date.now();
+          // Admission rejection happens before any process exists: conclusive
+          // runner-owned proof that no child/task work began.
+          result.preWorkInfraFailure = true;
+          result.toolActivity = "none";
           return result;
         }
       }
@@ -770,6 +814,7 @@ export class ChildRunner {
             runId: this.runId,
             parentSessionKey: this.parentSessionKey ?? "",
             childSessionId: result.sessionId,
+            ...(this.deferRunTerminal ? { childSessionIds: [] } : {}),
             // Worktree-isolated runs record their checkout so concurrent Pi
             // processes' machine-wide GC sweeps can shield it while we live.
             worktreeCwd: spec.isolation === "worktree" ? spec.cwd : undefined,
@@ -1097,12 +1142,17 @@ export class ChildRunner {
         // Capability mismatch is not transient: never compensate by broadening tools,
         // choosing another model or retrying into an unverified launch.
         await stopChildForStartupFailure();
-        throw startupFailure(startupOutcome.code, startupOutcome.detail);
+        // If the OS never created a process, no capability check could run.
+        // Preserve this positive pre-work spawn proof for the same-model retry
+        // path; an actually launched child's mismatch still refuses outright.
+        if (!(ranked && failedBeforeSpawn(childExited?.error))) {
+          throw startupFailure(startupOutcome.code, startupOutcome.detail);
+        }
       }
       if (startupOutcome.kind === "cancelled") {
         // Cancelled/timed out during startup: never send the real task prompt.
         if (!requestedStop) requestStop("cancelled");
-      } else {
+      } else if (startupOutcome.kind === "ok") {
         this.sendCommand = send;
         taskPromptSent = send({ type: "prompt", message: spec.task });
         // RPC mode has no session header line; get_state supplies the session id.
@@ -1131,7 +1181,11 @@ export class ChildRunner {
         thinking: spec.thinking,
         profile: spec.profile,
         backend: spec.backend ?? "pi",
-        model: finalized.model ?? result.model ?? spec.model,
+        // Routed children were startup-verified against the exact `provider/model`
+        // identity; provider message payloads may echo a bare ID, which must never
+        // become the recorded actual model of an attempt.
+        model: routed && spec.model ? spec.model : (finalized.model ?? result.model ?? spec.model),
+        liveText: ranked ? parser.getAssistantText?.() || undefined : finalized.liveText,
         canWrite: spec.canWrite,
         process: result.process,
         startedAt,
@@ -1143,6 +1197,15 @@ export class ChildRunner {
         result.state = "failed";
         result.stopReason = "spawn_error";
         result.errorMessage = closed.error.message;
+        // Only spawn-stage failures where the OS never produced a process are
+        // conclusive pre-work proof. Any other child error leaves uncertainty:
+        // a ranked attempt must not restart on it, so the activity latch rises
+        // to `unknown` instead of staying `none`.
+        const neverStarted = failedBeforeSpawn(closed.error);
+        result.preWorkInfraFailure = neverStarted;
+        if (!neverStarted && ranked && result.toolActivity !== "started") {
+          result.toolActivity = "unknown";
+        }
       } else if (requestedStop) {
         if (requestedStop === "timeout") {
           Object.assign(result, applyTimeoutSemantics(result));
@@ -1163,12 +1226,19 @@ export class ChildRunner {
           result.stopReason = requestedStop;
           result.exitCode = closed.code;
           result.errorMessage = `Stopped by ${requestedStop.replace("_", " ")} budget after the wrap-up grace period; partial output preserved`;
-        } else {
+        } else if (requestedStop === "fatal") {
+          // A fatal RPC rejection supersedes any earlier assistant error: the
+          // final settled outcome is a protocol failure, not provider evidence.
+          // Stale evidence must never authorize cross-model advancement.
+          result.providerError = undefined;
           result.state = "failed";
-          result.stopReason =
-            requestedStop === "fatal" ? "error" : requestedStop;
+          result.stopReason = "error";
           result.exitCode = closed.code ?? 1;
           if (fatalError) result.errorMessage = fatalError;
+        } else {
+          result.state = "failed";
+          result.stopReason = requestedStop;
+          result.exitCode = closed.code ?? 1;
         }
       } else if (
         pendingBudgetStop &&
@@ -1185,7 +1255,17 @@ export class ChildRunner {
       // Structured-output verdict: validate the final text once, after any
       // repair round. Failure downgrades completed → partial (paid work is
       // still delivered; the parent sees why it is not machine-readable).
-      if (spec.outputSchema) {
+      // Ranked exception: a failed/cancelled/timed-out terminal attempt, or one
+      // whose latest completed assistant message ended in a provider
+      // error/abort, must never publish structuredOutput even when its text
+      // contains a valid, schema-matching json:result block — that text stays
+      // ordinary failed-attempt output/preview. Successful and legitimate
+      // budget-limited "partial" attempts keep the existing validation.
+      const settledAssistantStop = parser.getAssistantStopReason?.();
+      const rankedAssistantTerminated = ranked && (settledAssistantStop === "error"
+        || settledAssistantStop === "aborted"
+        || settledAssistantStop === undefined);
+      if (spec.outputSchema && !(ranked && (["failed", "cancelled", "timeout", "lost"].includes(result.state as TaskResult["state"]) || rankedAssistantTerminated))) {
         const extracted = extractStructuredResult(result.liveText);
         const check =
           extracted.value !== undefined
@@ -1210,7 +1290,7 @@ export class ChildRunner {
         }
       }
 
-      if (this.locks && this.runId) {
+      if (!this.deferRunTerminal && this.locks && this.runId) {
         this.locks.markRunTerminal(this.runId, result.state);
       }
       return result;
@@ -1220,7 +1300,7 @@ export class ChildRunner {
       const startupFailureInfo = readStartupFailure(error);
       if (startupFailureInfo && requestedStop !== "timeout" && !abortSignal?.aborted) {
         markStartupFailure(result, startupFailureInfo.code, startupFailureInfo.detail);
-        if (this.locks && this.runId)
+        if (!this.deferRunTerminal && this.locks && this.runId)
           this.locks.markRunTerminal(this.runId, result.state);
         return result;
       }
@@ -1232,6 +1312,7 @@ export class ChildRunner {
         result.stopReason = "timeout";
         result.timeoutPhase =
           timeoutPhase ?? (!slotHeld ? "queued" : "running");
+        result.preWorkInfraFailure = result.timeoutPhase === "queued" ? true : undefined;
         result.errorMessage =
           result.timeoutPhase === "queued"
             ? "Timed out waiting for a process slot (never started)"
@@ -1245,7 +1326,7 @@ export class ChildRunner {
       }
       result.exitCode ??= 1;
       result.endedAt = Date.now();
-      if (this.locks && this.runId)
+      if (!this.deferRunTerminal && this.locks && this.runId)
         this.locks.markRunTerminal(this.runId, result.state);
       return result;
     } finally {
@@ -1258,9 +1339,12 @@ export class ChildRunner {
     usage: UsageStats,
   ): "max_turns" | "max_cost" | undefined {
     // Stop only after a completed turn has pushed usage beyond the configured ceiling.
-    if (spec.maxTurns !== undefined && usage.turns > spec.maxTurns)
+    // Prior-attempt usage is included in this comparison so a replacement model does
+    // not reset max_cost/max_turns, while returned usage stays attempt-local.
+    const compared = this.budgetOffset ? addUsage(this.budgetOffset, usage) : usage;
+    if (spec.maxTurns !== undefined && compared.turns > spec.maxTurns)
       return "max_turns";
-    if (spec.maxCost !== undefined && usage.cost > spec.maxCost)
+    if (spec.maxCost !== undefined && compared.cost > spec.maxCost)
       return "max_cost";
     return undefined;
   }
@@ -1294,6 +1378,8 @@ export function runSubagent(
       stallKillAfterMs: options.stallKillAfterMs,
       startupTimeoutMs: options.startupTimeoutMs,
       backend: options.backend,
+      priorUsage: options.priorUsage,
+      deferRunTerminal: options.deferRunTerminal,
     },
   ).run(spec, options.signal);
 }

package/src/schema.ts

@@ -58,8 +58,8 @@ export const TaskFields = {
   max_turns: Type.Optional(Type.Number({ minimum: 1, maximum: 500, description: "Budget: at this many turns the child is steered to wrap up and given grace turns for a final answer; ends as 'partial' with output preserved." })),
   max_cost: Type.Optional(Type.Number({ minimum: 0, description: "Soft provider-reported execution cost ceiling in dollars, checked after each turn. TypeSafe routing currency is unreported and NOT capped by max_cost." })),
   grace_turns: Type.Optional(Type.Number({ minimum: 0, maximum: 20, description: "Wrap-up turns allowed after a budget breach before hard stop. 0 = immediate stop. Default from config (2)." })),
-  fallback_models: Type.Optional(Type.Array(Type.String(), { maxItems: 5, description: "Legacy field: omit on new work, including an empty list. Jev routing has no emergency or fallback model." })),
-  max_retries: Type.Optional(Type.Number({ minimum: 0, maximum: 5, description: "Extra same-model attempts on transient child failures; never reselects Jev or broadens tools. Defaults to config maxRetries (1). Task-quality failures never retry." })),
+  fallback_models: Type.Optional(Type.Array(Type.String(), { maxItems: 5, description: "Legacy field: omit on new work, including an empty list. Ranked alternatives come only from Jev; manual fallback and emergency models are not accepted." })),
+  max_retries: Type.Optional(Type.Number({ minimum: 0, maximum: 5, description: "Total extra child attempts (0 = initial attempt only; default 1). Before any tool execution, a recognized availability failure advances to the next Jev probability-ranked model with the same tools and no new selection. Auth/quota/context/task-quality failures never switch." })),
   context: Type.Optional(
     Type.Union([Type.Literal("fresh"), Type.Literal("fork")], {
       description: "fork starts the child from a branched copy of the parent conversation (needs a persisted parent session); fresh (default) starts clean. Fork is single-task only.",
@@ -70,7 +70,7 @@ export const TaskFields = {
     Type.Unsafe<Record<string, unknown>>(
       Type.Object({}, {
         additionalProperties: true,
-        description: "JSON Schema the child's final result must satisfy. The child ends with a fenced json:result block; validation failures get one steer-based repair round, then end 'partial' with the errors reported.",
+        description: "JSON Schema the child's final result must satisfy. The child ends with a fenced json:result block; successful but invalid answers get one repair round, then end 'partial' with the errors reported. Provider errors/aborts are not repaired and failed attempts cannot publish structured output.",
       }),
     ),
   ),

package/src/types.ts

@@ -41,6 +41,66 @@ export interface UsageStats {
 
 export type BackendName = "pi" | "codex" | "claude";
 
+/**
+ * Sticky current-invocation tool activity for the pre-tool switch boundary. `started` latches on tool_execution_start, a newly observed
+ * completed assistant toolCall or a toolResult; `unknown` marks malformed,
+ * truncated or absent evidence. Both are sticky: neither can be erased by a
+ * later complete event, and only a conclusive `none` authorizes a new child.
+ */
+export type ToolActivity = "none" | "started" | "unknown";
+
+/**
+ * Conservative classification of the latest completed assistant provider error
+ * (see `model-failover.ts`). Only the availability categories advance the
+ * ranked path; everything else stops and is reported without switching.
+ */
+export type ModelFailureCategory =
+  | "model_unavailable"
+  | "rate_limited"
+  | "service_overload"
+  | "transport"
+  | "auth"
+  | "quota"
+  | "invalid_request"
+  | "context_overflow"
+  | "refusal"
+  | "unknown";
+
+/**
+ * One locally finalized ranked execution candidate. Internal contract built by
+ * `policy.ts` from the validated ranking and the original model catalog; never
+ * a tool-request/config field and never decoded from a persisted snapshot into
+ * an executable plan. Thinking follows explicit > agent > profile > candidate >
+ * parent per entry; tools/writer classification are shared across all entries.
+ */
+export interface ModelAttemptSpec {
+  readonly model: string;
+  readonly probability: number;
+  readonly thinking?: ThinkingLevel;
+}
+
+/**
+ * Bounded descriptive history for one ranked/legacy attempt. Records are not
+ * a second usage ledger (TaskResult.usage stays cumulative) and never become
+ * executable: they carry the reason for a switch, the session pointer for
+ * discoverable partial work, and a 1 KiB output preview (16 KiB per task).
+ */
+export interface ModelAttemptRecord {
+  /** 1-based launch count for this task. */
+  attempt: number;
+  /** 0-based ranking position of the candidate that ran. */
+  rank: number;
+  model: string;
+  probability: number;
+  outcome: RunState;
+  stopReason?: string;
+  failureCategory?: ModelFailureCategory;
+  toolActivity?: ToolActivity;
+  sessionId?: string;
+  /** Bounded output preview; metadata/session pointer survive when text is trimmed. */
+  outputPreview?: string;
+}
+
 export interface TaskSpec {
   /** Agent CLI powering this child. Defaults to "pi". */
   backend?: BackendName;
@@ -75,8 +135,15 @@ export interface TaskSpec {
   graceTurns?: number;
   /** Ordered backup models tried on transient provider failures. */
   fallbackModels?: string[];
-  /** Extra attempts on transient failures (queue timeout, stall, provider error). */
+  /** Extra launches: ranked pre-tool recovery, or the legacy SDK transient loop. */
   maxRetries?: number;
+  /**
+   * Locally finalized probability-ranked candidate plan for extension-managed
+   * tasks (internal; built only by `policy.finalizeRoutedTasks`). Its presence
+   * selects the ranked attempt loop; the legacy `fallbackModels` loop stays
+   * untouched for trusted unranked SDK tasks.
+   */
+  modelAttemptPlan?: readonly ModelAttemptSpec[];
   /** Fork the parent conversation into the child (real branched session). */
   contextFork?: boolean;
   /** Parent session file used for contextFork. */
@@ -129,6 +196,22 @@ export interface TaskResult {
   attempts?: number;
   /** Models tried across attempts, in order. */
   attemptedModels?: string[];
+  /** Sticky current-invocation tool activity across this task's attempts. */
+  toolActivity?: ToolActivity;
+  /**
+   * Bounded errorMessage + primitive diagnostics.error.code from the latest
+   * completed assistant provider error. Set only for stopReason "error";
+   * generic runner/RPC errors and diagnostic bodies never fill it.
+   */
+  providerError?: string;
+  /**
+   * Runner-owned positive proof that no child/task work could have begun
+   * (queue/admission timeout or a spawn that never produced a process). Only
+   * this conclusive evidence permits a same-model infrastructure retry.
+   */
+  preWorkInfraFailure?: boolean;
+  /** Bounded per-attempt history for ranked runs (descriptive, never executable). */
+  modelAttempts?: ModelAttemptRecord[];
   /** Parsed structured result when output_schema was requested and validated. */
   structuredOutput?: unknown;
   /** Validation errors when output_schema was requested but the result failed. */
@@ -182,6 +265,10 @@ export interface RunSnapshot {
     stalledSince?: number;
     attempts?: number;
     attemptedModels?: string[];
+    /** Sticky tool-activity boundary state across the task's attempts. */
+    toolActivity?: ToolActivity;
+    /** Bounded ranked attempt history (descriptive; previews capped). */
+    modelAttempts?: ModelAttemptRecord[];
     structuredOutput?: unknown;
     structuredError?: string;
   }>;