@yaag/runtime 0.6.2 → 0.7.0

package/src/model/model-resolution.ts

@@ -1,10 +1,24 @@
 import { parseModelSuffix } from "./model-suffix.ts";
 import { isThinkingLevel, type ThinkingLevel } from "./thinking-level.ts";
 
-/** Why one model candidate was rejected by pi. */
+/**
+ * Why one model candidate was rejected by pi (ADR-0037).
+ *
+ * `not_found`: the pattern matched no model, or pi refused the live swap.
+ * `auth`: the provider refused the credentials.
+ * `rate_limited`: the provider stayed rate-limited after pi's own retries.
+ *
+ * These three classes are the only triggers of Model Resolution. A different
+ * transport or turn failure stays an ordinary failure and starts no new attempt.
+ */
 export type ModelErrorReason = "not_found" | "auth" | "rate_limited";
 
-/** One failed Model Resolution attempt, handed back to the caller's resolver. */
+/**
+ * One failed Model Resolution attempt, handed back to the caller's resolver.
+ *
+ * yaag gives the full history to each resolver call, oldest attempt first. The
+ * first call gets an empty list (ADR-0037).
+ */
 export interface ModelError {
   readonly reason: ModelErrorReason;
   /** The model pattern that failed, after inline-suffix stripping. */
@@ -13,19 +27,43 @@ export interface ModelError {
   readonly attempt: number;
 }
 
-/** Picks the next model candidate, or `undefined` to give up. */
+/**
+ * Picks the next model candidate, or `undefined` to give up (ADR-0037).
+ *
+ * When the resolver gives up, the spawn or the Ask fails with
+ * `MODEL_RESOLUTION_FAILED`, which carries the full error history. yaag also
+ * refuses a candidate that already failed with `not_found` or `auth` in the
+ * same loop, so a resolver cannot loop forever. The resolver must be pure and
+ * synchronous.
+ */
 export type ModelResolver = (errors: readonly ModelError[]) => string | undefined;
 
-/** Every accepted `model` form: one pattern, an ordered list, or a resolver. */
+/**
+ * Every accepted `model` form: one pattern, an ordered list, or a resolver.
+ *
+ * An array is the resolver that reads the candidate at the attempt index, and
+ * gives `undefined` past the end. One pattern is the one-element list. So the
+ * termination rule of `ModelResolver` covers every form (ADR-0037).
+ */
 export type ModelSpec = string | readonly string[] | ModelResolver;
 
-/** Picks the thinking level for a settled model, or `undefined` for pi's default. */
+/**
+ * Picks the thinking level for a settled model, or `undefined` for pi's default.
+ *
+ * `undefined` means "no thinking preference". It is not a failure, and it does
+ * not stop the attempt (ADR-0037).
+ */
 export type ThinkingResolver = (
   selectedModel: string,
   errors: readonly ModelError[],
 ) => ThinkingLevel | undefined;
 
-/** Every accepted `thinking` form: one level or a resolver. */
+/**
+ * Every accepted `thinking` form: one level or a resolver.
+ *
+ * An inline suffix on the resolved model pattern wins over this property
+ * (ADR-0037).
+ */
 export type ThinkingSpec = ThinkingLevel | ThinkingResolver;
 
 /** One attempt's settled selection; `model: undefined` inherits pi's default model. */

package/src/model/model-swap.ts

@@ -0,0 +1,81 @@
+import { agentError } from "../errors.ts";
+import type { CommandResponse, Frame } from "../transport/index.ts";
+import { matchAvailableModel, readAvailableModel, readAvailableModels } from "./model-match.ts";
+import type { ModelSelection } from "./model-resolution.ts";
+
+/** Sends one command frame to the live Agent. The Connection satisfies it. */
+export type ModelSwapCommand = (frame: Frame) => Promise<CommandResponse>;
+
+/** What one successful swap left the Agent running. */
+export interface ModelSwapResult {
+  /** `provider/id` pi reports for the new model. */
+  readonly model: string;
+}
+
+/**
+ * Swaps one live Agent's model in place; the conversation context survives.
+ *
+ * pi's `set_model` takes a concrete `{provider, modelId}` pair and no pattern, so
+ * the swap is two frames: `get_available_models` to read the snapshot, then
+ * `set_model` on the entry yaag matched itself. A thinking level is a third
+ * frame, sent only when the selection names one — `undefined` means "no
+ * preference", exactly as at spawn.
+ *
+ * Rejects with an AGENT_FAILED-shaped error carrying pi's own diagnostic, so
+ * `classifyAskFailure` can re-enter Model Resolution: a refused pattern and a
+ * refused `set_model` both classify as `not_found`.
+ */
+export async function swapModel(options: {
+  readonly agent: string;
+  readonly command: ModelSwapCommand;
+  readonly selection: ModelSelection;
+}): Promise<ModelSwapResult> {
+  const pattern = options.selection.model;
+  if (pattern === undefined) {
+    throw failed(options.agent, "model swap needs a model candidate");
+  }
+  const available = await options.command({ type: "get_available_models" });
+  if (!available.success) {
+    throw failed(options.agent, available.error ?? "get_available_models was rejected");
+  }
+  const models = readAvailableModels(available.data);
+  if (models === null || models.length === 0) {
+    throw failed(options.agent, "no models available");
+  }
+  const match = matchAvailableModel(pattern, models);
+  if (match.kind === "no_match") {
+    throw failed(options.agent, `No models match pattern "${pattern}"`);
+  }
+  if (match.kind === "ambiguous") {
+    throw failed(
+      options.agent,
+      `Model "${pattern}" is ambiguous across providers: ${match.candidates.join(", ")}`,
+    );
+  }
+  const response = await options.command({
+    type: "set_model",
+    provider: match.model.provider,
+    modelId: match.model.id,
+  });
+  if (!response.success) throw failed(options.agent, response.error ?? "set_model was rejected");
+  if (options.selection.thinking !== undefined) {
+    const thinking = await options.command({
+      type: "set_thinking_level",
+      level: options.selection.thinking,
+    });
+    if (!thinking.success) {
+      throw failed(options.agent, thinking.error ?? "set_thinking_level was rejected");
+    }
+  }
+  return { model: reportedModel(response.data) ?? `${match.model.provider}/${match.model.id}` };
+}
+
+/** pi answers `set_model` with the full Model object it switched to. */
+function reportedModel(data: Record<string, unknown> | null): string | undefined {
+  const model = readAvailableModel(data?.model ?? data);
+  return model === null ? undefined : `${model.provider}/${model.id}`;
+}
+
+function failed(agent: string, message: string): Error {
+  return agentError(agent, "AGENT_FAILED", message);
+}

package/src/model/recorded-resolution.ts

@@ -0,0 +1,61 @@
+import { ModelErrorHistory } from "./model-error-history.ts";
+import type { ModelError, ModelResolution, ModelSelection } from "./model-resolution.ts";
+import type { ThinkingLevel } from "./thinking-level.ts";
+
+/**
+ * The model and thinking a Cassette recorded for one Agent's settled spawn.
+ *
+ * It lives in `model/` because `transport/` already depends on this directory,
+ * and never the other way round: one name for one concept (ADR-0039).
+ */
+export interface RecordedSpawnSelection {
+  readonly model?: string;
+  readonly thinking?: ThinkingLevel;
+}
+
+/** What to replay: the declared resolution and the outcome the Cassette holds. */
+export interface RecordedResolutionOptions {
+  readonly resolution: ModelResolution;
+  readonly recorded: RecordedSpawnSelection;
+}
+
+/** The adopted selection and the attempts the declared resolution skipped to reach it. */
+export interface RecordedResolution {
+  readonly selection: ModelSelection;
+  /**
+   * The synthetic failures of every candidate offered before the recorded one.
+   * The caller seeds the Agent's shared history with them, so a later mid-Ask
+   * fallback re-resolves from the attempt index the recording reached.
+   */
+  readonly skipped: readonly ModelError[];
+}
+
+/**
+ * Replays Model Resolution against a recorded outcome, without any model call.
+ *
+ * Offers the declared resolution one candidate at a time, feeding every
+ * non-matching candidate back as a synthetic `not_found` failure, and settles on
+ * the first selection that names the recorded model. Returns `undefined` when
+ * the declared spec can no longer produce that outcome — the caller then runs
+ * the ordinary loop, and Cassette identity reports the Divergence (ADR-0039).
+ */
+export function resolveRecordedModel(
+  options: RecordedResolutionOptions,
+): RecordedResolution | undefined {
+  const history = new ModelErrorHistory();
+  for (;;) {
+    const selection = options.resolution.resolve(history.errors);
+    if (selection === undefined) return undefined;
+    if (selection.model === options.recorded.model) {
+      return { selection, skipped: [...history.errors] };
+    }
+    const candidate = selection.model;
+    // No candidate means pi's default, which the resolution offers only once:
+    // it cannot be rejected and retried, so the recorded outcome is unreachable.
+    if (candidate === undefined) return undefined;
+    // A resolver that repeats a permanently failed candidate stops here, with
+    // the same termination rule the live loop uses (`resolution-loop.ts`).
+    if (history.failedPermanently(candidate)) return undefined;
+    history.record("not_found", candidate);
+  }
+}

package/src/model/resolution-loop.ts

@@ -0,0 +1,115 @@
+import { modelResolutionError } from "../errors.ts";
+import { ModelErrorHistory } from "./model-error-history.ts";
+import { classifyAskFailure, classifyModelFailure } from "./model-failure.ts";
+import type { ModelFallbackSink } from "./model-fallback.ts";
+import type { ModelError, ModelResolution, ModelSelection } from "./model-resolution.ts";
+
+/** One Model Resolution loop: what to resolve, for whom, and how one attempt runs. */
+export interface ResolutionLoopOptions<T> {
+  readonly resolution: ModelResolution;
+  readonly agent: string;
+  /** The Agent's shared attempt history; a fresh one when the caller keeps none. */
+  readonly history?: ModelErrorHistory;
+  /** Runs one attempt with the settled selection; rejects to feed classification. */
+  attempt(selection: ModelSelection): Promise<T>;
+  /** Reports each failed attempt whose resolution produced a next candidate. */
+  readonly onFallback?: ModelFallbackSink;
+}
+
+/**
+ * Runs the Model Resolution loop: resolve → attempt → classify → re-resolve.
+ *
+ * Rejects with MODEL_RESOLUTION_FAILED (carrying the full error history) when the
+ * resolver gives up, or when it returns a candidate that already failed
+ * permanently (`not_found`/`auth`) in this loop. Any failure that is not a Model
+ * Resolution trigger is rethrown unchanged, and so is any failure of an attempt
+ * that named no candidate at all (it inherited pi's default, so there is nothing
+ * to fall back from).
+ */
+export async function resolveModel<T>(options: ResolutionLoopOptions<T>): Promise<T> {
+  const history = options.history ?? new ModelErrorHistory();
+  // The failed attempt still waiting for the candidate that replaces it. A
+  // resolver that gives up throws before it is ever reported, and a selection
+  // that names no candidate inherits pi's default, which is no fallback either.
+  let pending: ModelError | undefined;
+  for (;;) {
+    const selection = nextSelection(options.agent, options.resolution, history);
+    if (pending !== undefined && selection.model !== undefined) {
+      options.onFallback?.({ ...pending, resolvedModel: selection.model });
+    }
+    pending = undefined;
+    try {
+      return await options.attempt(selection);
+    } catch (error) {
+      const reason = classifyModelFailure(error);
+      if (reason === undefined || selection.model === undefined) throw error;
+      pending = history.record(reason, selection.model);
+    }
+  }
+}
+
+/** One mid-Ask fallback loop: the work already runs on a model, so resolution comes second. */
+export interface FallbackLoopOptions<T> {
+  readonly resolution: ModelResolution;
+  readonly agent: string;
+  readonly history: ModelErrorHistory;
+  /** The model the Agent runs right now; a failure is attributed to it. */
+  currentModel(): string;
+  /** Runs one attempt on the current model; rejects to feed classification. */
+  attempt(): Promise<T>;
+  /** Applies a re-resolved selection to the live Agent; rejects to feed classification. */
+  swap(selection: ModelSelection): Promise<void>;
+  /** Reports each failed attempt or swap whose resolution produced a next candidate. */
+  readonly onFallback?: ModelFallbackSink;
+}
+
+/**
+ * Runs the mid-Ask Model Resolution loop: attempt → classify → re-resolve → swap → retry.
+ *
+ * Unlike `resolveModel`, the first attempt runs on the model already in place,
+ * and a failed swap is classified exactly like a failed attempt, so a pattern pi
+ * refuses re-enters the loop instead of ending the Ask.
+ */
+export async function retryOnModelFailure<T>(options: FallbackLoopOptions<T>): Promise<T> {
+  // `undefined` means "run an attempt"; a selection means "swap to it first".
+  let pending: ModelSelection | undefined;
+  for (;;) {
+    // What a failure of this step is attributed to: the candidate a swap tries
+    // to apply, or the model the Agent runs right now.
+    const failing = pending?.model ?? options.currentModel();
+    try {
+      if (pending === undefined) return await options.attempt();
+      await options.swap(pending);
+      pending = undefined;
+    } catch (error) {
+      const reason = classifyAskFailure(error);
+      if (reason === undefined) throw error;
+      const recorded = options.history.record(reason, failing);
+      pending = nextSelection(options.agent, options.resolution, options.history);
+      // A selection that names no candidate inherits pi's default, so there is
+      // nothing to swap to: the original failure stays what it was.
+      if (pending.model === undefined) throw error;
+      options.onFallback?.({
+        reason,
+        failedModel: failing,
+        attempt: recorded.attempt,
+        resolvedModel: pending.model,
+      });
+    }
+  }
+}
+
+/** The next selection to try, or a rejection when resolution is over. */
+function nextSelection(
+  agent: string,
+  resolution: ModelResolution,
+  history: ModelErrorHistory,
+): ModelSelection {
+  const selection = resolution.resolve(history.errors);
+  if (selection === undefined) throw modelResolutionError(agent, history.errors);
+  const candidate = selection.model;
+  if (candidate !== undefined && history.failedPermanently(candidate)) {
+    throw modelResolutionError(agent, history.errors, candidate);
+  }
+  return selection;
+}

package/src/summary/index.ts

@@ -18,5 +18,6 @@ export type {
   AskingAgentInfo,
   ExitedAgentInfo,
   IdleAgentInfo,
+  ModelFallbackInfo,
   NodeInfo,
 } from "./summary-agent.ts";

package/src/summary/summary-agent.ts

@@ -1,8 +1,10 @@
 import type { AgentActivity } from "../events.ts";
 import type { TokenBreakdown, WorktreeResolution } from "../transport/index.ts";
+import type { ModelFallbackInfo } from "./summary-fallbacks.ts";
 import type { NodeInfo } from "./summary-nodes.ts";
 
 export type { AgentActivity } from "../events.ts";
+export type { ModelFallbackInfo } from "./summary-fallbacks.ts";
 export type { NodeInfo } from "./summary-nodes.ts";
 
 /** The observer-facing lifecycle state of an Agent. */
@@ -27,6 +29,10 @@ interface AgentInfoBase {
   readonly nodes: readonly NodeInfo[];
   /** Exited Nested Nodes dropped to keep the table bounded. */
   readonly finishedNodesPruned: number;
+  /** This Agent's bounded Model Resolution fallback table, oldest first. */
+  readonly modelFallbacks: readonly ModelFallbackInfo[];
+  /** Fallbacks dropped to keep the table bounded. */
+  readonly modelFallbacksPruned: number;
 }
 
 /** An Agent between Asks; its latest settled Ask identity, if any, is retained. */
@@ -80,7 +86,7 @@ export interface AgentExitObservation {
 }
 
 /** Produces an idle placeholder for lifecycle events received before a spawn. */
-function placeholderAgent(): IdleAgentInfo {
+export function placeholderAgent(): IdleAgentInfo {
   return {
     model: null,
     cwd: null,
@@ -98,6 +104,8 @@ function placeholderAgent(): IdleAgentInfo {
     askStartedAt: null,
     nodes: [],
     finishedNodesPruned: 0,
+    modelFallbacks: [],
+    modelFallbacksPruned: 0,
   };
 }
 

package/src/summary/summary-fallbacks.ts

@@ -0,0 +1,50 @@
+import type { LifecycleEventBody, ModelErrorReason } from "../events.ts";
+import { AGENT_MODEL_FALLBACK_MAX } from "../wire-constants.ts";
+import type { AgentRecord } from "./summary-agent.ts";
+
+/** One failed Model Resolution attempt as the Summary keeps it. */
+export interface ModelFallbackInfo {
+  readonly failedModel: string;
+  readonly reason: ModelErrorReason;
+  readonly attempt: number;
+  readonly resolvedModel: string;
+  readonly at: number | null;
+}
+
+type ModelFallbackEvent = Extract<LifecycleEventBody, { readonly type: "model_fallback" }>;
+
+/**
+ * Folds one `model_fallback` into an Agent's bounded fallback table.
+ *
+ * A fallback is an append-only fact, not a state replacement, so entries keep
+ * arrival order (the loop already orders attempts) and no stamped entry is
+ * rejected. Past `AGENT_MODEL_FALLBACK_MAX` entries the oldest drop into
+ * `modelFallbacksPruned`.
+ *
+ * The Agent's `model` is left alone. `resolvedModel` is a yaag pattern, which
+ * can be partial, and the event reports it before the swap is applied, while
+ * `model` is pi's resolved `provider/id` for the model the Agent really runs.
+ * `agent_spawn` is the only writer of that field: a mid-Ask swap updates the
+ * Handle alone and reports no Lifecycle Event, so the Summary keeps the
+ * spawn-time id.
+ */
+export function applyModelFallback(
+  agent: AgentRecord,
+  event: ModelFallbackEvent,
+  at: number | null,
+): AgentRecord {
+  const entry: ModelFallbackInfo = {
+    failedModel: event.failedModel,
+    reason: event.reason,
+    attempt: event.attempt,
+    resolvedModel: event.resolvedModel,
+    at,
+  };
+  const appended = [...agent.modelFallbacks, entry];
+  const excess = Math.max(0, appended.length - AGENT_MODEL_FALLBACK_MAX);
+  return {
+    ...agent,
+    modelFallbacks: appended.slice(excess),
+    modelFallbacksPruned: agent.modelFallbacksPruned + excess,
+  };
+}

package/src/summary/summary.ts

@@ -5,12 +5,14 @@ import {
   type AgentRecord,
   endAsk,
   exitAgent,
+  placeholderAgent,
   setActivity,
   setUsage,
   spawnAgent,
   startAsk,
   totalsFromAgents,
 } from "./summary-agent.ts";
+import { applyModelFallback } from "./summary-fallbacks.ts";
 import { applyNodeUpdate } from "./summary-nodes.ts";
 
 export type { NodeState, NodeUsage, RunOutcome } from "../events.ts";
@@ -21,6 +23,7 @@ export type {
   AskingAgentInfo,
   ExitedAgentInfo,
   IdleAgentInfo,
+  ModelFallbackInfo,
   NodeInfo,
 } from "./summary-agent.ts";
 
@@ -44,6 +47,8 @@ interface RunSummaryBase {
   readonly incomplete: boolean;
   readonly durationMs: number;
   readonly worstFrameGapMs: number;
+  /** Run-wide Model Resolution fallbacks, pruned per-Agent entries included. */
+  readonly modelFallbacks: number;
 }
 
 /** A Run that has not settled; it has neither outcome nor compatibility result. */
@@ -101,6 +106,7 @@ export function initialSummary(): RunningRunSummary {
     incomplete: false,
     durationMs: 0,
     worstFrameGapMs: 0,
+    modelFallbacks: 0,
     ok: null,
   };
 }
@@ -140,6 +146,12 @@ export function applyEvent(
       return updateActivity(summary, event, at);
     case "node_update":
       return updateNodes(summary, event, at);
+    case "model_fallback":
+      return withAgent(
+        { ...summary, modelFallbacks: summary.modelFallbacks + 1 },
+        event.agent,
+        applyModelFallback(summary.agents[event.agent] ?? placeholderAgent(), event, at),
+      );
     case "agent_usage":
       return withAgent(summary, event.agent, setUsage(summary.agents[event.agent], event, at));
     case "ask_end":

package/src/transport/fake-transport.ts

@@ -3,6 +3,7 @@ import {
   isReportResultCommandFrame,
   REPORT_RESULT_TOOL_NAME,
 } from "../ask-contract/index.ts";
+import type { AvailableModel } from "../model/index.ts";
 import { FrameQueue } from "./frame-queue.ts";
 import { parseFrame } from "./jsonl.ts";
 import type { AgentStats, AgentTransport, AskMarker, Frame } from "./transport.ts";
@@ -51,6 +52,12 @@ export interface FakeTransportOptions extends FakePromptScript {
   readonly abortError?: string;
   /** Makes the private report_result schema command fail. */
   readonly schemaCommandError?: string;
+  /** The snapshot answered to `get_available_models`; defaults to this fake's own model. */
+  readonly models?: readonly AvailableModel[];
+  /** Makes a `set_model` command fail, as pi does for a pair it does not know. */
+  readonly setModelError?: string;
+  /** Makes a `set_thinking_level` command fail. */
+  readonly setThinkingError?: string;
   readonly stats?: AgentStats;
   /** pi can answer a command after `agent_settled` — it is last among events only. */
   readonly promptResponse?: "immediate" | "after-settle";
@@ -68,7 +75,13 @@ export interface FakeTransportOptions extends FakePromptScript {
  * It never spawns or closes a real Agent process.
  */
 export class FakeTransport implements AgentTransport {
-  readonly model = "test/model";
+  #model = "test/model";
+
+  /** The model this fake currently reports, which a `set_model` swap updates. */
+  get model(): string {
+    return this.#model;
+  }
+
   /** Everything the runtime wrote, in order. */
   readonly sent: Frame[] = [];
   readonly asks: AskMarker[] = [];
@@ -97,6 +110,10 @@ export class FakeTransport implements AgentTransport {
     if (frame.type === "abort") void this.#answerAbort(frame);
     if (frame.type === "get_last_assistant_text") this.#answerLastText(frame);
     if (frame.type === "get_state") this.#answerState(frame);
+    if (frame.type === "get_available_models") this.#answerAvailableModels(frame);
+    if (frame.type === "set_model") this.#answerSetModel(frame);
+    if (frame.type === "set_thinking_level")
+      this.#answerControl(frame, this.#options.setThinkingError);
   }
 
   frames(): AsyncIterable<Frame> {
@@ -236,6 +253,45 @@ export class FakeTransport implements AgentTransport {
     }
   }
 
+  #answerAvailableModels(frame: Frame): void {
+    this.#queue.push({
+      type: "response",
+      command: "get_available_models",
+      id: frame.id,
+      success: true,
+      data: { models: this.#models() },
+    });
+  }
+
+  #models(): readonly AvailableModel[] {
+    return this.#options.models ?? [{ provider: "test", id: "model" }];
+  }
+
+  /**
+   * Answers pi's `set_model` and, on success, reports the new model.
+   *
+   * A swap begins a new attempt of the same Ask, so the fake re-arms the initial
+   * prompt: the retried prompt selects the next top-level script instead of a
+   * correction script. That is a yaag rule encoded in a test double on purpose
+   * — one `beginAsk` per Ask keeps the double honest.
+   */
+  #answerSetModel(frame: Frame): void {
+    const error = this.#options.setModelError;
+    if (error === undefined) {
+      this.#model = `${String(frame.provider)}/${String(frame.modelId)}`;
+      this.#initialPromptPending = true;
+    }
+    this.#queue.push({
+      type: "response",
+      command: "set_model",
+      id: frame.id,
+      success: error === undefined,
+      ...(error === undefined
+        ? { data: { model: { provider: frame.provider, id: frame.modelId } } }
+        : { error }),
+    });
+  }
+
   #answerState(frame: Frame): void {
     if (this.#options.stateSilent === true) return;
     this.#queue.push({

package/src/transport/index.ts

@@ -2,6 +2,10 @@
  * Public surface of the `transport/` module: the pi process seam and its probes.
  * Files inside this directory import each other directly.
  */
+
+// One name for one concept: the recorded selection type lives in `model/`,
+// which `transport/` already depends on (ADR-0039).
+export type { RecordedSpawnSelection } from "../model/index.ts";
 export { type CommandResponse, Connection } from "./connection.ts";
 export {
   FakeTransport,

package/src/transport/live-transport.ts

@@ -3,6 +3,7 @@ import { FrameQueue } from "./frame-queue.ts";
 import { decodeFrames } from "./jsonl.ts";
 import { piCommand, readModel, readSessionFile, readStats } from "./pi-state.ts";
 import { reap } from "./reap.ts";
+import { appendStderrTail, stderrDiagnostic } from "./stderr-tail.ts";
 import {
   createToolProbe,
   TOOL_PROBE_EXTENSION_PATH,
@@ -25,6 +26,8 @@ import type {
 const READY_TIMEOUT_MS = 30_000;
 /** Cost is a local read answering in ~0ms, but the kill must never block on it. */
 const STATS_TIMEOUT_MS = 2_000;
+/** How long an exit message waits for stderr, which grandchildren may hold open. */
+const STDERR_DRAIN_MS = 100;
 
 /** Agents are real `pi --mode rpc` child processes (ADR-0001). */
 export const liveTransport: TransportFactory = {
@@ -42,7 +45,11 @@ class LiveTransport implements AgentTransport {
   model = "";
 
   readonly #name: string;
-  readonly #process: Bun.Subprocess<"pipe", "pipe", "ignore">;
+  readonly #process: Bun.Subprocess<"pipe", "pipe", "pipe">;
+  /** Last bytes pi wrote to stderr; the only classification signal a spawn gets (ADR-0037). */
+  #stderrTail = "";
+  /** Settles when stderr reaches EOF, so an exit message can wait for the diagnostic. */
+  readonly #stderrDone: Promise<void>;
   readonly #queue = new FrameQueue();
   readonly #pending = new Map<string, (frame: Frame) => void>();
   /** Both halves of tool verification, or null when the spawn promised nothing. */
@@ -60,12 +67,29 @@ class LiveTransport implements AgentTransport {
       cwd: options.cwd,
       stdin: "pipe",
       stdout: "pipe",
-      stderr: "ignore",
+      // pi prints model and startup diagnostics to stderr and exits 1 (main() →
+      // reportDiagnostics → process.exit(1)), so stderr carries the only reason
+      // yaag can classify. The reader below drains it so pi never blocks.
+      stderr: "pipe",
       // Its own process group, so the Agent sees stdin EOF rather than a signal
       // when the Orchestrator dies — EOF is the path that reaps grandchildren.
       detached: true,
     });
     void this.#read();
+    // A stream error must not surface as an unhandled rejection: the tail is a
+    // best-effort diagnostic, never a reason to fail an Agent that started.
+    this.#stderrDone = this.#readStderr().catch(() => undefined);
+  }
+
+  /** Drains stderr continuously, keeping only a bounded tail. */
+  async #readStderr(): Promise<void> {
+    const decoder = new TextDecoder();
+    for await (const chunk of readChunks(this.#process.stderr)) {
+      this.#stderrTail = appendStderrTail(
+        this.#stderrTail,
+        decoder.decode(chunk, { stream: true }),
+      );
+    }
   }
 
   /** Confirms the Agent is up and speaking the protocol, and resolves its model. */
@@ -90,6 +114,8 @@ class LiveTransport implements AgentTransport {
         // The original startup error remains the useful failure.
       }
       if (error instanceof YaagError) throw error;
+      // Only the exit path folds in stderr: a tool-contract or timeout failure
+      // must stay generic, whatever pi warned about earlier (ADR-0037).
       const message = error instanceof Error ? error.message : "agent startup failed";
       throw new YaagError("SPAWN_FAILED", message, this.#name);
     }
@@ -174,8 +200,15 @@ class LiveTransport implements AgentTransport {
         timeoutMs,
       );
     });
-    const death = this.#process.exited.then((code) => {
-      throw new YaagError("SPAWN_FAILED", `agent "${this.#name}" exited (${code})`, this.#name);
+    const death = this.#process.exited.then(async (code) => {
+      // Detached grandchildren can hold the pipe open, so the drain is bounded:
+      // an exit must reject fast, with whatever diagnostic already arrived.
+      await Promise.race([this.#stderrDone, Bun.sleep(STDERR_DRAIN_MS)]);
+      throw new YaagError(
+        "SPAWN_FAILED",
+        `agent "${this.#name}" exited (${code})${stderrDiagnostic(this.#stderrTail)}`,
+        this.#name,
+      );
     });
     return Promise.race([response, failure, death]).finally(() => clearTimeout(timer));
   }