@yaag/runtime 0.6.2 → 0.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yaag/runtime",
-  "version": "0.6.2",
+  "version": "0.7.0",
   "publishConfig": {
     "access": "public"
   },

package/src/agent/agent.ts

@@ -4,11 +4,21 @@ import { exchangeAsk } from "../ask/index.ts";
 import { ReportResultTool } from "../ask-contract/index.ts";
 import { agentError } from "../errors.ts";
 import type { EventSink } from "../events.ts";
+import type { ModelErrorHistory, ModelResolution } from "../model/index.ts";
 import type { AgentStats, AgentTransport } from "../transport/index.ts";
 import { Connection } from "../transport/index.ts";
 import type { AskOptions, Handle, ResolvedSpawnOptions, StructuredAskOptions } from "../types.ts";
 import { AgentUsage } from "./agent-usage.ts";
 
+/** The mid-Ask Model Resolution one Agent's spawn handed it (ADR-0038). */
+export interface AgentModelFallback {
+  readonly resolution: ModelResolution;
+  /** The Agent-wide attempt history, shared with its spawn loop. */
+  readonly history: ModelErrorHistory;
+  /** The model candidate this Agent's spawn settled on. */
+  readonly candidate: string;
+}
+
 export interface AgentOptions {
   readonly name: string;
   readonly cwd: string;
@@ -17,6 +27,11 @@ export interface AgentOptions {
   readonly emit: EventSink;
   /** The options this Agent was spawned with, for the ADR-0014 Ask hash. */
   readonly spawnOptions: ResolvedSpawnOptions;
+  /**
+   * Mid-Ask Model Resolution for this Agent, sharing the spawn loop's history.
+   * Absent when the spawn named no candidate: there is nothing to fall back from.
+   */
+  readonly modelFallback?: AgentModelFallback;
   /** Definition-owned defaults merged below explicit per-Ask options. */
   readonly askDefaults?: AskOptions;
   /** Definition identity recorded on its Asks, outside replay identity. */
@@ -34,7 +49,6 @@ export class Agent implements Handle {
   readonly name: string;
   readonly cwd: string;
   readonly branch: string | undefined;
-  readonly model: string;
 
   readonly #transport: AgentTransport;
   readonly #connection: Connection;
@@ -45,6 +59,9 @@ export class Agent implements Handle {
   readonly #askLimitGraceMs: number | undefined;
   readonly #idleAbortSettleMs: number | undefined;
   readonly #stallProbeSettleMs: number | undefined;
+  readonly #modelFallback: AgentModelFallback | undefined;
+  #model: string;
+  #candidate: string;
   readonly #usage: AgentUsage;
   readonly #reportResultTool = new ReportResultTool();
   #busy = false;
@@ -56,7 +73,9 @@ export class Agent implements Handle {
     this.name = options.name;
     this.cwd = options.cwd;
     this.branch = options.branch;
-    this.model = options.transport.model;
+    this.#model = options.transport.model;
+    this.#modelFallback = options.modelFallback;
+    this.#candidate = options.modelFallback?.candidate ?? options.transport.model;
     this.#transport = options.transport;
     this.#emit = options.emit;
     this.#spawnOptions = options.spawnOptions;
@@ -71,6 +90,11 @@ export class Agent implements Handle {
     this.#connection = new Connection(options.transport, options.name);
   }
 
+  /** The model pi reports for this Agent now; a mid-Ask swap updates it. */
+  get model(): string {
+    return this.#model;
+  }
+
   async ask<Schema extends TSchema>(
     prompt: string,
     options: StructuredAskOptions<Schema>,
@@ -101,6 +125,18 @@ export class Agent implements Handle {
         reportResultTool: this.#reportResultTool,
         emit: this.#emit,
         usage: this.#usage,
+        modelFallback:
+          this.#modelFallback === undefined
+            ? undefined
+            : {
+                resolution: this.#modelFallback.resolution,
+                history: this.#modelFallback.history,
+                currentModel: () => this.#candidate,
+                onSwapped: (candidate: string, reportedModel: string) => {
+                  this.#candidate = candidate;
+                  this.#model = reportedModel;
+                },
+              },
         close: () => void this.close().catch(() => {}),
         askLimitGraceMs: this.#askLimitGraceMs,
         idleAbortSettleMs: this.#idleAbortSettleMs,

package/src/agent/define-agent.ts

@@ -14,10 +14,18 @@ export interface AgentConfig {
   /**
    * Model id handed to `pi --model`. Unset = pi's default. An array is an ordered
    * fallback list, a function picks the next candidate from the failures so far,
-   * and any pattern may carry an inline thinking suffix (`"opus-5:medium"`).
+   * and any pattern may carry an inline thinking suffix (`"opus-5:medium"`),
+   * which wins over `thinking`. Each attempt settles the model first, then the
+   * thinking level for that model. yaag starts a new attempt only when pi
+   * reports `not_found`, `auth`, or `rate_limited` (ADR-0037).
    */
   readonly model?: ModelSpec;
-  /** Thinking budget for the Agent's turns, as a level or a resolver. */
+  /**
+   * Thinking budget for the Agent's turns, as a level or a resolver. The
+   * resolver runs again for each attempt, with the model that settled for that
+   * attempt. A resolver kept in a definition is frozen policy, so it must stay
+   * pure and synchronous (ADR-0037).
+   */
   readonly thinking?: ThinkingSpec;
   /** Allow-list of tool names. Unset = pi's default tool set. */
   readonly tools?: readonly string[];
@@ -47,7 +55,9 @@ const arrayFields = ["tools", "disallowedTools", "skills", "disallowedSkills"] a
  * Throws a TypeError when `name` is missing or blank, or when `cwd`/`worktree`
  * appear — those are topology, chosen at spawn time, not baked into a definition.
  * The config is defensively copied and deep-frozen, so later mutation of the
- * caller's arrays cannot change the definition.
+ * caller's arrays cannot change the definition. `defineAgent` also copies and
+ * freezes a model array, so a later change of the caller's array cannot change
+ * Model Resolution (ADR-0037).
  */
 export function defineAgent(config: AgentConfig): AgentDefinition {
   if (typeof config.name !== "string" || config.name.trim() === "") {

package/src/agent/spawn-request.ts

@@ -0,0 +1,64 @@
+import type { ModelSelection } from "../model/index.ts";
+import type { OpenOptions } from "../transport/index.ts";
+import type { ResolvedSpawnOptions, SpawnOptions } from "../types.ts";
+
+/** Everything one spawn needs to build its open request, before a model settles. */
+export interface OpenRequestOptions {
+  readonly name: string;
+  readonly cwd: string;
+  readonly spawnOptions: SpawnOptions;
+  readonly resolvedExtensionPaths?: readonly string[];
+  readonly sessionDir: string | undefined;
+}
+
+/**
+ * Builds one spawn's open request from its options.
+ *
+ * A caller that has not settled a model yet passes the declared options: the
+ * request then carries a literal `model`/`thinking` and carries none for an
+ * array or resolver spec. That request is what a Cassette-backed factory peeks
+ * at, which is why the resume peek blanks model and thinking before it compares
+ * the request with the recorded spawn (ADR-0039).
+ */
+export function openRequest(options: OpenRequestOptions): OpenOptions {
+  const spawnOptions = options.spawnOptions;
+  const model = typeof spawnOptions.model === "string" ? spawnOptions.model : undefined;
+  const thinking = typeof spawnOptions.thinking === "function" ? undefined : spawnOptions.thinking;
+  return {
+    cwd: options.cwd,
+    name: options.name,
+    ...(model === undefined ? {} : { model }),
+    ...(spawnOptions.systemPrompt === undefined ? {} : { systemPrompt: spawnOptions.systemPrompt }),
+    ...(thinking === undefined ? {} : { thinking }),
+    ...(spawnOptions.appendSystemPrompt === undefined
+      ? {}
+      : { appendSystemPrompt: spawnOptions.appendSystemPrompt }),
+    ...(spawnOptions.inherit === undefined ? {} : { inherit: spawnOptions.inherit }),
+    ...(spawnOptions.tools === undefined ? {} : { tools: spawnOptions.tools }),
+    ...(spawnOptions.disallowedTools === undefined
+      ? {}
+      : { disallowedTools: spawnOptions.disallowedTools }),
+    ...(spawnOptions.skills === undefined ? {} : { skills: spawnOptions.skills }),
+    ...(spawnOptions.disallowedSkills === undefined
+      ? {}
+      : { disallowedSkills: spawnOptions.disallowedSkills }),
+    ...(options.resolvedExtensionPaths === undefined
+      ? {}
+      : { resolvedExtensionPaths: options.resolvedExtensionPaths }),
+    ...(spawnOptions.worktree === true ? { worktree: true as const } : {}),
+    ...(options.sessionDir === undefined ? {} : { sessionDir: options.sessionDir }),
+  };
+}
+
+/** Replaces the caller's `model`/`thinking` forms with one attempt's settled selection. */
+export function withSelection(
+  options: SpawnOptions,
+  selection: ModelSelection,
+): ResolvedSpawnOptions {
+  const { model: _model, thinking: _thinking, ...rest } = options;
+  return {
+    ...rest,
+    ...(selection.model === undefined ? {} : { model: selection.model }),
+    ...(selection.thinking === undefined ? {} : { thinking: selection.thinking }),
+  };
+}

package/src/agent/spawn.ts

@@ -2,7 +2,13 @@ import { resolve } from "node:path";
 import { YaagError } from "../errors.ts";
 import type { EventSink } from "../events.ts";
 import { resolveExtensionPaths } from "../extension/index.ts";
-import { normalizeModelResolution } from "../model/index.ts";
+import {
+  ModelErrorHistory,
+  type ModelSelection,
+  normalizeModelResolution,
+  resolveModel,
+  resolveRecordedModel,
+} from "../model/index.ts";
 import type { RunContext } from "../run/index.ts";
 import type { AgentTransport, TransportFactory, TransportStartup } from "../transport/index.ts";
 import type {
@@ -15,6 +21,7 @@ import type {
 import { Agent } from "./agent.ts";
 import { uniqueAgentName } from "./agent-names.ts";
 import { type AgentDefinition, agentDefinitionConfig, isAgentDefinition } from "./define-agent.ts";
+import { openRequest, withSelection } from "./spawn-request.ts";
 
 /** Dependencies for one Run's Agent-spawn gate. */
 export interface SpawnDependencies {
@@ -48,16 +55,70 @@ export function makeSpawn(deps: SpawnDependencies): SpawnGate {
     const request = resolveRequest(definitionOrOptions, overrides);
     const cwd = resolve(request.spawnOptions.cwd ?? process.cwd());
     const name = uniqueAgentName(request.spawnOptions.name, deps.agents.length, taken);
-    const spawnOptions = resolveSpawnSelection(request.spawnOptions, name);
+    const resolution = normalizeModelResolution(request.spawnOptions);
+    // One history per Agent: its spawn loop and every mid-Ask fallback loop
+    // append to it, so a resolver sees every candidate that already failed.
+    const history = new ModelErrorHistory();
     try {
-      const opened = await openTransport({
-        factory: deps.factory,
-        name,
-        cwd,
-        spawnOptions,
-        sessionDir: deps.sessionDir,
-        programFile: deps.programFile,
-      });
+      // Extension paths do not vary per candidate, so a bad path fails once, generically.
+      const resolvedExtensionPaths =
+        request.spawnOptions.extensions === undefined
+          ? undefined
+          : await resolveExtensionPaths(request.spawnOptions.extensions, {
+              ...(deps.programFile === undefined ? {} : { programFile: deps.programFile }),
+              projectRoot: cwd,
+            }).catch((error: unknown) => {
+              if (error instanceof YaagError) throw error;
+              throw new YaagError("SPAWN_FAILED", `agent "${name}": ${String(error)}`, name);
+            });
+      const attempt = async (
+        selection: ModelSelection,
+      ): Promise<{ opened: OpenedTransport; spawnOptions: ResolvedSpawnOptions }> => {
+        const settled = withSelection(request.spawnOptions, selection);
+        return {
+          opened: await openTransport({
+            factory: deps.factory,
+            name,
+            cwd,
+            spawnOptions: settled,
+            ...(resolvedExtensionPaths === undefined ? {} : { resolvedExtensionPaths }),
+            sessionDir: deps.sessionDir,
+          }),
+          spawnOptions: settled,
+        };
+      };
+      // The peek must stay in the same synchronous block as the first open: a
+      // Cassette-backed factory claims Agents in open order (ADR-0013).
+      const recorded = deps.factory.recordedSpawn?.(
+        openRequest({
+          name,
+          cwd,
+          spawnOptions: request.spawnOptions,
+          ...(resolvedExtensionPaths === undefined ? {} : { resolvedExtensionPaths }),
+          sessionDir: deps.sessionDir,
+        }),
+      );
+      // A Cassette-backed spawn adopts the recorded resolved selection and skips
+      // the loop, so a replayed Run emits no spawn-time fallback (ADR-0039).
+      const adopted =
+        recorded === undefined ? undefined : resolveRecordedModel({ resolution, recorded });
+      // The adopted outcome carries the attempts the recording already spent, so
+      // a later mid-Ask fallback re-resolves from that attempt index (ADR-0039).
+      for (const skipped of adopted?.skipped ?? []) {
+        history.record(skipped.reason, skipped.failedModel);
+      }
+      const { opened, spawnOptions } =
+        adopted === undefined
+          ? await resolveModel({
+              resolution,
+              agent: name,
+              history,
+              onFallback: (fallback) => {
+                deps.emit({ type: "model_fallback", agent: name, ...fallback });
+              },
+              attempt,
+            })
+          : await attempt(adopted.selection);
       const resolvedCwd = opened.startup.worktree?.cwd ?? cwd;
       const branch = opened.startup.worktree?.branch;
       const sessionFile = opened.startup.sessionFile;
@@ -68,6 +129,11 @@ export function makeSpawn(deps: SpawnDependencies): SpawnGate {
         transport: opened.transport,
         emit: deps.emit,
         spawnOptions,
+        // An Agent that named no candidate inherits pi's default model, so a
+        // failing Ask has nothing to fall back from and stays an Ask failure.
+        ...(spawnOptions.model === undefined
+          ? {}
+          : { modelFallback: { resolution, history, candidate: spawnOptions.model } }),
         ...(request.askDefaults === undefined ? {} : { askDefaults: request.askDefaults }),
         ...(request.definitionName === undefined ? {} : { definitionName: request.definitionName }),
       });
@@ -100,23 +166,6 @@ export function makeSpawn(deps: SpawnDependencies): SpawnGate {
   };
 }
 
-/**
- * Attempt-0 shim for Model Resolution: one selection, no retry loop.
- * Ticket 02 replaces this with the fallback loop and MODEL_RESOLUTION_FAILED.
- */
-function resolveSpawnSelection(options: SpawnOptions, name: string): ResolvedSpawnOptions {
-  const selection = normalizeModelResolution(options).resolve([]);
-  if (selection === undefined) {
-    throw new YaagError("SPAWN_FAILED", `agent "${name}": no model candidate to try`, name);
-  }
-  const { model: _model, thinking: _thinking, ...rest } = options;
-  return {
-    ...rest,
-    ...(selection.model === undefined ? {} : { model: selection.model }),
-    ...(selection.thinking === undefined ? {} : { thinking: selection.thinking }),
-  };
-}
-
 type MutableSpawnOverrides = { -readonly [Key in keyof SpawnOverrides]: SpawnOverrides[Key] };
 
 interface SpawnRequest {
@@ -206,8 +255,8 @@ interface OpenTransportOptions {
   readonly name: string;
   readonly cwd: string;
   readonly spawnOptions: ResolvedSpawnOptions;
+  readonly resolvedExtensionPaths?: readonly string[];
   readonly sessionDir: string | undefined;
-  readonly programFile: string | undefined;
 }
 
 interface OpenedTransport {
@@ -218,44 +267,16 @@ interface OpenedTransport {
 async function openTransport(options: OpenTransportOptions): Promise<OpenedTransport> {
   const startup: TransportStartup = {};
   try {
-    const resolvedExtensionPaths =
-      options.spawnOptions.extensions === undefined
-        ? undefined
-        : await resolveExtensionPaths(options.spawnOptions.extensions, {
-            ...(options.programFile === undefined ? {} : { programFile: options.programFile }),
-            projectRoot: options.cwd,
-          });
     const transport = await options.factory.open(
-      {
-        cwd: options.cwd,
+      openRequest({
         name: options.name,
-        ...(options.spawnOptions.model === undefined ? {} : { model: options.spawnOptions.model }),
-        ...(options.spawnOptions.systemPrompt === undefined
-          ? {}
-          : { systemPrompt: options.spawnOptions.systemPrompt }),
-        ...(options.spawnOptions.thinking === undefined
-          ? {}
-          : { thinking: options.spawnOptions.thinking }),
-        ...(options.spawnOptions.appendSystemPrompt === undefined
-          ? {}
-          : { appendSystemPrompt: options.spawnOptions.appendSystemPrompt }),
-        ...(options.spawnOptions.inherit === undefined
-          ? {}
-          : { inherit: options.spawnOptions.inherit }),
-        ...(options.spawnOptions.tools === undefined ? {} : { tools: options.spawnOptions.tools }),
-        ...(options.spawnOptions.disallowedTools === undefined
-          ? {}
-          : { disallowedTools: options.spawnOptions.disallowedTools }),
-        ...(options.spawnOptions.skills === undefined
-          ? {}
-          : { skills: options.spawnOptions.skills }),
-        ...(options.spawnOptions.disallowedSkills === undefined
+        cwd: options.cwd,
+        spawnOptions: options.spawnOptions,
+        ...(options.resolvedExtensionPaths === undefined
           ? {}
-          : { disallowedSkills: options.spawnOptions.disallowedSkills }),
-        ...(resolvedExtensionPaths === undefined ? {} : { resolvedExtensionPaths }),
-        ...(options.spawnOptions.worktree === true ? { worktree: true } : {}),
-        ...(options.sessionDir === undefined ? {} : { sessionDir: options.sessionDir }),
-      },
+          : { resolvedExtensionPaths: options.resolvedExtensionPaths }),
+        sessionDir: options.sessionDir,
+      }),
       (report) => Object.assign(startup, report),
     );
     return { transport, startup };

package/src/ask/ask-exchange-events.ts

@@ -1,4 +1,5 @@
 import type { AgentActivity, AskOutputChannel, EventSink } from "../events.ts";
+import type { ModelFallback } from "../model/index.ts";
 import type { NodeSnapshot } from "../node/index.ts";
 import { agentAskPath, childPath } from "../node/index.ts";
 import { promptGist } from "../prompt/index.ts";
@@ -13,7 +14,10 @@ export interface AskEndOutcome {
   readonly cause?: SettlementCause;
 }
 
-/** Emits the four Ask-scoped Lifecycle Events for one exchange. */
+/**
+ * Emits the Ask-scoped Lifecycle Events for one exchange, plus the Agent-scoped
+ * `model_fallback` this exchange's fallback loop reports.
+ */
 export class AskEvents {
   readonly #emit: EventSink;
   readonly #agent: string;
@@ -57,6 +61,11 @@ export class AskEvents {
     });
   };
 
+  /** Not Ask-scoped: a fallback names the Agent only, like the spawn-time loop. */
+  fallback = (fallback: ModelFallback): void => {
+    this.#emit({ type: "model_fallback", agent: this.#agent, ...fallback });
+  };
+
   /** A `normal` cause is the absent default, so ordinary settlements stay lean. */
   end(outcome: AskEndOutcome): void {
     const { durationMs, ok, maxFrameGapMs, cause = "normal" } = outcome;

package/src/ask/ask-exchange-options.ts

@@ -1,5 +1,6 @@
 import type { ReportResultTool } from "../ask-contract/index.ts";
 import type { EventSink } from "../events.ts";
+import type { ModelErrorHistory, ModelResolution } from "../model/index.ts";
 import type { AgentTransport, Connection, Frame } from "../transport/index.ts";
 import type { ResolvedSpawnOptions } from "../types.ts";
 import type { EffectiveAskOptions } from "./ask-hash.ts";
@@ -9,6 +10,16 @@ export interface FrameObserver {
   observe(frame: Frame): void;
 }
 
+/** Mid-Ask Model Resolution for one Agent, shared with its spawn-time loop. */
+export interface AskModelFallback {
+  readonly resolution: ModelResolution;
+  readonly history: ModelErrorHistory;
+  /** The model candidate the Agent runs right now; a failure is attributed to it. */
+  currentModel(): string;
+  /** Reports the candidate a successful swap applied, and the model pi now reports. */
+  onSwapped(candidate: string, reportedModel: string): void;
+}
+
 /** Options that connect one Ask exchange to its Agent's identity and event stream. */
 export interface AskExchangeOptions {
   readonly agent: string;
@@ -25,6 +36,8 @@ export interface AskExchangeOptions {
   readonly emit: EventSink;
   /** The Agent's persistent usage accumulator; fed frames only during live Asks. */
   readonly usage: FrameObserver;
+  /** Mid-Ask Model Resolution; absent when this Agent's spawn named no candidate. */
+  readonly modelFallback: AskModelFallback | undefined;
   /** Kills the Agent on ASK_TIMEOUT and destructive stalls — the one upward capability. */
   readonly close: () => void;
   /** Test-only override for the fixed duration-limit grace. */

package/src/ask/ask-exchange.ts

@@ -17,6 +17,7 @@ import {
   askStalledError,
   isYaagError,
 } from "../errors.ts";
+import { retryOnModelFailure, swapModel } from "../model/index.ts";
 import { NodeTracker } from "../node/index.ts";
 import type { AskPlayback } from "../transport/index.ts";
 import { FrameGapTracker } from "../transport/index.ts";
@@ -43,7 +44,7 @@ export async function exchangeAsk(options: AskExchangeOptions): Promise<unknown>
 }
 class AskExchange {
   readonly #options: AskExchangeOptions;
-  readonly #turn = new AskTurn();
+  #turn = new AskTurn();
   readonly #events: AskEvents;
   #limit: AskLimit | null = null;
   #idle: IdleWatch | null = null;
@@ -73,16 +74,48 @@ class AskExchange {
 
   async run(): Promise<unknown> {
     const startedAt = Date.now();
+    this.#openEnvelope();
     try {
-      const result = await this.#exchange();
+      const result = await this.#attempts();
       this.#events.end(this.#endOutcome(startedAt, true));
       return result;
     } catch (error) {
       if (this.#began) this.#events.end(this.#endOutcome(startedAt, false));
       throw error;
+    } finally {
+      this.#finish();
     }
   }
 
+  /**
+   * Runs the Ask, retrying it on a swapped-in model when a model failure ends an
+   * attempt. Every attempt stays inside one Ask envelope, so one Ask still emits
+   * exactly one `ask_start`, one `ask_end` and one recorded Cassette Ask.
+   */
+  async #attempts(): Promise<unknown> {
+    const fallback = this.#options.modelFallback;
+    if (fallback === undefined) return await this.#exchange();
+    return await retryOnModelFailure({
+      resolution: fallback.resolution,
+      agent: this.#options.agent,
+      history: fallback.history,
+      onFallback: this.#events.fallback,
+      currentModel: () => fallback.currentModel(),
+      attempt: async () => await this.#exchange(),
+      swap: async (selection) => {
+        // Replay re-runs this loop and re-sends the recorded swap frames, which
+        // CassetteReplay matches as ordinary frames (ADR-0039). The Ask keeps its
+        // spawn-time identity, so the retry records under the same hash.
+        const swapped = await swapModel({
+          agent: this.#options.agent,
+          command: async (frame) => await this.#options.connection.command(frame),
+          selection,
+        });
+        fallback.onSwapped(selection.model ?? swapped.model, swapped.model);
+      },
+    });
+  }
+
   #endOutcome(startedAt: number, ok: boolean): AskEndOutcome {
     return {
       durationMs: Date.now() - startedAt,
@@ -94,8 +127,7 @@ class AskExchange {
 
   async #exchange(): Promise<unknown> {
     try {
-      this.#begin();
-      this.#timeoutDeadline = this.#deadline();
+      this.#armAttempt();
       // The schema command is answered without a turn, so settlement tracking
       // starts after it: nothing it could emit may settle this Ask (ADR-0032).
       await this.#deliverSchema();
@@ -119,11 +151,12 @@ class AskExchange {
       this.#recordInvalidOutput(error);
       throw error;
     } finally {
-      this.#cleanup();
+      this.#cleanupAttempt();
     }
   }
 
-  #begin(): void {
+  /** Opens the Ask envelope: identity, recording and the Ask-scoped events. Once per Ask. */
+  #openEnvelope(): void {
     this.#legacyExtraction = this.#recordedLegacyPolicy();
     const outputContract = structuredOutputContract(
       this.#options.ask,
@@ -147,7 +180,27 @@ class AskExchange {
     });
     this.#began = true;
     this.#playback = playback;
+    // `timeoutMs` is the Ask's hard ceiling and kills the Agent (ADR-0003), so
+    // it is Ask-scoped: retries share one deadline, unlike the soft limits.
+    this.#timeoutDeadline = this.#deadline();
     this.#events.start(this.#options.prompt, playback !== undefined);
+  }
+
+  /**
+   * Arms one attempt: fresh turn tracking, limits, watches and report_result
+   * state, so a retry starts from nothing — the failed attempt's work died with
+   * its model error, and its stale reported result cannot settle the retry.
+   */
+  #armAttempt(): void {
+    const playback = this.#playback;
+    this.#turn = new AskTurn();
+    this.#outcome = undefined;
+    this.#stalled = undefined;
+    // A failed attempt's stall recovery and invalid output describe work that
+    // died with it, so neither may reach the Ask's single `ask_end` or its one
+    // recorded completion when a later attempt settles cleanly.
+    this.#cause = "normal";
+    this.#invalidOutput = undefined;
     this.#gap = playback === undefined ? new FrameGapTracker() : null;
     this.#activity = playback === undefined ? new AskActivityTracker(this.#events.activity) : null;
     this.#output =
@@ -443,15 +496,23 @@ class AskExchange {
       this.#invalidOutput = { kind: "invalid_output", steeringEfforts: error.steeringEfforts ?? 0 };
   }
 
-  #cleanup(): void {
-    this.#maxFrameGapMs = this.#gap?.maxGapMs;
+  /** Ends one attempt; the envelope stays open, so a retry can arm the next one. */
+  #cleanupAttempt(): void {
+    this.#maxFrameGapMs = maxGap(this.#maxFrameGapMs, this.#gap?.maxGapMs);
     this.#stalled ??= this.#idle?.result ?? this.#stall?.result ?? undefined;
     this.#limit?.cleanup();
     this.#idle?.cleanup();
     this.#stall?.cleanup();
     this.#output?.close();
+    if (this.#drainStaleFrames) {
+      this.#options.connection.drainStaleTurn();
+      this.#drainStaleFrames = false;
+    }
+  }
+
+  /** Closes the Ask envelope: one `finishAsk` for the whole Ask, retries included. */
+  #finish(): void {
     this.#options.connection.observe(null);
-    if (this.#drainStaleFrames) this.#options.connection.drainStaleTurn();
     if (!this.#began) return;
     try {
       this.#options.transport.finishAsk({
@@ -465,3 +526,10 @@ class AskExchange {
     }
   }
 }
+
+/** The widest frame gap seen across an Ask's attempts. */
+function maxGap(left: number | undefined, right: number | undefined): number | undefined {
+  if (left === undefined) return right;
+  if (right === undefined) return left;
+  return Math.max(left, right);
+}

package/src/ask/index.ts

@@ -3,5 +3,6 @@
  * Files inside this directory import each other directly.
  */
 export { exchangeAsk } from "./ask-exchange.ts";
+export type { AskModelFallback } from "./ask-exchange-options.ts";
 export { askHash, askMarkerContext, type EffectiveAskOptions } from "./ask-hash.ts";
 export type { SettlementCause } from "./stall-watchdog.ts";

package/src/cassette/cassette-replay.ts

@@ -48,6 +48,11 @@ export class CassetteReplay {
         this.#releaseOneResponse();
         return;
       }
+      // A recorded swap ends one Ask attempt (ADR-0038): the prompt that
+      // follows is the retry, not an ADR-0027 correction, so the floor moves.
+      if (expected.type === "set_model" || expected.type === "set_thinking_level") {
+        this.#openAttempt(this.#sentCursor);
+      }
       this.#releaseFor(frame.type);
       this.#consumeControls();
       return;
@@ -72,10 +77,7 @@ export class CassetteReplay {
     this.#receivedCursor = 0;
     this.#sent = ask.sentFrames;
     this.#received = ask.receivedFrames;
-    // A schema-bearing Ask opens with the report_result schema command, so the
-    // Ask's own prompt is the second sent frame, not the first (ADR-0032).
-    const first = ask.sentFrames[0];
-    this.#promptFloor = first !== undefined && isReportResultCommandFrame(first) ? 1 : 0;
+    this.#openAttempt(0);
     const awaitsAbortSettlement = abortSettlementFollowsFinalText(ask);
     const settles = ask.receivedFrames.some((frame) => frame.type === "agent_settled");
     const reported = recordedReportedResult(ask);
@@ -95,6 +97,19 @@ export class CassetteReplay {
     this.#queue.end();
   }
 
+  /**
+   * Opens one Ask attempt at `cursor`: the first prompt at or after it is the
+   * attempt's own prompt, and every later prompt is a recorded correction.
+   *
+   * A schema-bearing attempt opens with the report_result schema command, so
+   * its own prompt is the second sent frame, not the first (ADR-0032).
+   */
+  #openAttempt(cursor: number): void {
+    const first = this.#sent[cursor];
+    this.#promptFloor =
+      first !== undefined && isReportResultCommandFrame(first) ? cursor + 1 : cursor;
+  }
+
   #consumeControls(): void {
     for (;;) {
       const expected = this.#sent[this.#sentCursor];
@@ -110,6 +125,10 @@ export class CassetteReplay {
    * amendment). A recorded `get_state` is a Stall Watchdog probe: replay is
    * never silent, so it never probes, and the recorded exchange is consumed
    * here instead of blocking the frames that follow it (ADR-0029).
+   *
+   * A recorded `get_available_models`/`set_model` pair is deliberately not a
+   * control: replay re-runs the mid-Ask Model Resolution and sends those
+   * commands itself, so `send()` matches them like any other frame (ADR-0039).
    */
   #isRecordedControl(frame: Frame): boolean {
     if (frame.type === "steer" || frame.type === "abort" || frame.type === "get_state") return true;