@cr1ms0n/pi-subagent 0.9.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

@@ -1,6 +1,5 @@
 import { isThinkingLevel } from "./thinking.js";
 import {
-  DEFAULT_API_KEY_ENV,
   DEFAULT_ROUTING_TIMEOUT_MS,
   DEFAULT_SELECTOR_MODEL,
   MAX_ROUTING_MODEL_ID_LENGTH,
@@ -30,22 +29,21 @@ export type {
  * - `parseJevRouting(raw, source?)` parses the `jevRouting` **subtree** (not the whole
  *   `~/.pi/subagent.json` file) and returns an immutable snapshot. It throws a plain
  *   `Error` with an actionable message on any unknown field, duplicate/blank model ID,
- *   blank description, invalid environment-variable name, non-integer/out-of-range timeout
- *   or unsupported candidate count. Callers (`src/config.ts`) catch that message and expose
- *   it as a config error; no credential or provider catalog is read.
+ *   blank description, missing/invalid credential, non-integer/out-of-range timeout
+ *   or unsupported candidate count. Callers (`src/config.ts`) expose safe error messages;
+ *   the parser never reads the environment or a provider catalog.
  * - `formatJevRoutingPrompt` renders model-facing guidance and works with **no** config, no
  *   credential and no inference, so management actions stay independent of routing setup.
  * - The candidate helpers are pure; they never contact Pi or TypeSafe.
  *
- * The credential *value* must never be stored in config: only the environment-variable name
- * is parsed and returned. The parser rejects unknown fields, so an accidental `apiKey` or
- * `apiKeyValue` field is an error rather than silently ignored.
+ * The private snapshot contains the credential from `apiKey`. Never serialize it into
+ * model-facing guidance or selector input. Credential diagnostics contain no supplied
+ * values. Legacy `apiKeyEnv` is rejected with manual migration guidance, without lookup.
  */
 
 /** Default config-file label used in prose (owned by `config.ts` for file reads). */
 export const JEV_ROUTING_CONFIG_FILE = "~/.pi/subagent.json";
 
-const ENV_VAR_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
 /** Exact provider/model ID: at least one slash, further ID slashes allowed; no whitespace, control chars or globs. */
 const MODEL_ID = /^[^\s\u0000-\u001f\u007f/*?]+(?:\/[^\s\u0000-\u001f\u007f/*?]+)+$/u;
 const MAX_GUIDANCE_MODEL_LINES = 50;
@@ -76,12 +74,19 @@ function parseSelectorModel(value: unknown, source: string): string {
   return model;
 }
 
-function parseApiKeyEnv(value: unknown, source: string): string {
-  if (value === undefined) return DEFAULT_API_KEY_ENV;
-  if (typeof value !== "string" || !ENV_VAR_NAME.test(value.trim())) {
-    invalid(source, "apiKeyEnv must be an environment-variable name such as TYPESAFE_API_KEY (the credential value must not be stored in config)");
+/** Shared credential normalization for config parsing and defensive transport validation. */
+export function normalizeRoutingApiKey(value: unknown): string | undefined {
+  if (typeof value !== "string") return undefined;
+  const key = value.trim();
+  return key && !/[\s\u0000-\u001f\u007f-\u009f]/u.test(key) ? key : undefined;
+}
+
+function parseApiKey(value: unknown, source: string): string {
+  const key = normalizeRoutingApiKey(value);
+  if (key === undefined) {
+    invalid(source, "apiKey is required and must be a non-blank key without embedded whitespace or control characters; store it only in your private user config");
   }
-  return value.trim();
+  return key;
 }
 
 function parseTimeoutMs(value: unknown, source: string): number {
@@ -144,11 +149,14 @@ function parseModels(value: unknown, source: string): readonly JevRoutingModelEn
  */
 export function parseJevRouting(raw: unknown, source = JEV_ROUTING_CONFIG_FILE): JevRoutingConfig {
   const record = requireObject(raw, source, "jevRouting");
-  rejectUnknownKeys(record, ["selectorModel", "apiKeyEnv", "timeoutMs", "models"], source, "jevRouting");
+  if (Object.prototype.hasOwnProperty.call(record, "apiKeyEnv")) {
+    invalid(source, "apiKeyEnv is no longer supported; remove it and set jevRouting.apiKey to the credential in your private user config. No environment fallback or automatic migration is performed");
+  }
+  rejectUnknownKeys(record, ["selectorModel", "apiKey", "timeoutMs", "models"], source, "jevRouting");
 
   const snapshot: JevRoutingConfig = {
     selectorModel: parseSelectorModel(record.selectorModel, source),
-    apiKeyEnv: parseApiKeyEnv(record.apiKeyEnv, source),
+    apiKey: parseApiKey(record.apiKey, source),
     timeoutMs: parseTimeoutMs(record.timeoutMs, source),
     models: parseModels(record.models, source),
   };
@@ -160,7 +168,7 @@ export function jevRoutingTemplate(): string {
   return JSON.stringify({
     jevRouting: {
       selectorModel: DEFAULT_SELECTOR_MODEL,
-      apiKeyEnv: DEFAULT_API_KEY_ENV,
+      apiKey: "<your-typesafe-api-key>",
       timeoutMs: DEFAULT_ROUTING_TIMEOUT_MS,
       models: [
         {
@@ -230,7 +238,7 @@ function routingSummary(config: JevRoutingConfig): string[] {
     "Every new task/tasks[] spawn, action:\"plan\" request, /btw, resume, fork and synthesis is routed by the Jev selector against the user's candidate-model list.",
     "Do not pass model or fallback_models: those fields no longer select a route on new work and are rejected. Management actions (status/wait/cancel/steer/diff/apply/discard) never call the selector and need no credential.",
     `Selector: ${config.selectorModel} (pin an exact version instead of the moving alias to make selection reproducible).`,
-    `Credential: environment variable ${config.apiKeyEnv}, read locally at request time; the value is never stored in config, prompts, logs or results.`,
+    "Credential: jevRouting.apiKey in the private ~/.pi/subagent.json config file. Never read or copy its value into prompts, logs or results; the routing transport uses it only for the Authorization header.",
     `Logical selection deadline: ${config.timeoutMs} ms, covering all selector requests and waiting for one invocation.`,
     "Only Pi-backed new dispatch is supported; native Codex/Claude new dispatches are rejected rather than routed.",
     "Candidate models (exact IDs; the user's per-model characteristics are the matching criteria):",
@@ -243,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;
 }
@@ -259,7 +267,7 @@ export function formatJevRoutingPrompt(config: JevRoutingConfig | undefined, err
       "## Subagent routing (Jev / TypeSafe)",
       error || `No valid jevRouting configuration was found in ${JEV_ROUTING_CONFIG_FILE}.`,
       "Management actions (status/wait/cancel/steer/diff/apply/discard) remain available, but every new task/tasks[] spawn, plan, /btw, resume, fork and synthesis is rejected until jevRouting is configured.",
-      "Add jevRouting with selectorModel, apiKeyEnv and 1-255 candidate model entries (exact provider/model IDs plus user-written characteristics, including Chinese). The credential itself is read from the named environment variable at request time and is never stored in the config file.",
+      "Add jevRouting with selectorModel, apiKey and 1-255 candidate model entries (exact provider/model IDs plus user-written characteristics, including Chinese). The user must store the credential in the private config file, not in chat or source control. Do not read or display the key. Legacy apiKeyEnv is rejected; there is no environment fallback.",
       "Do not pass model or fallback_models; the selector chooses the execution model and tools.",
       "Use the package routing template; do not invent model IDs or import legacy modelPolicy entries automatically.",
     ].join("\n");

package/src/routing-types.ts

@@ -18,8 +18,6 @@ export const TYPESAFE_SYSTEMONE_ENDPOINT = "https://api.typesafe.ai/v1/systemone
 
 /** Stable alias default. An exact supported version may be pinned through config. */
 export const DEFAULT_SELECTOR_MODEL = "jev-latest";
-/** Environment variable that holds the TypeSafe credential. Never the credential value. */
-export const DEFAULT_API_KEY_ENV = "TYPESAFE_API_KEY";
 /** Default logical selection deadline in milliseconds. */
 export const DEFAULT_ROUTING_TIMEOUT_MS = 15_000;
 export const ROUTING_TIMEOUT_MIN_MS = 100;
@@ -86,11 +84,13 @@ export interface JevRoutingModelEntry {
 
 /**
  * Immutable `jevRouting` snapshot parsed from the user config subtree.
- * The credential value never appears here — only the environment-variable name.
+ * Contains a private credential. Never log this snapshot or serialize it into prompts,
+ * selector bodies, task specs, receipts or results; use explicit non-secret projections.
  */
 export interface JevRoutingConfig {
   readonly selectorModel: string;
-  readonly apiKeyEnv: string;
+  /** User-configured TypeSafe credential; transport Authorization header only. */
+  readonly apiKey: string;
   readonly timeoutMs: number;
   readonly models: readonly JevRoutingModelEntry[];
 }
@@ -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.",
       }),
     ),
   ),