@yaag/cli 0.6.2 → 0.7.0

package/assets/types/runtime/agent/agent.d.ts

@@ -1,7 +1,16 @@
 import type { Static, TSchema } from "typebox";
 import type { EventSink } from "../events.ts";
+import type { ModelErrorHistory, ModelResolution } from "../model/index.ts";
 import type { AgentStats, AgentTransport } from "../transport/index.ts";
 import type { AskOptions, Handle, ResolvedSpawnOptions, StructuredAskOptions } from "../types.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;
@@ -10,6 +19,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. */
@@ -27,8 +41,9 @@ export declare class Agent implements Handle {
     readonly name: string;
     readonly cwd: string;
     readonly branch: string | undefined;
-    readonly model: string;
     constructor(options: AgentOptions);
+    /** The model pi reports for this Agent now; a mid-Ask swap updates it. */
+    get model(): string;
     ask<Schema extends TSchema>(prompt: string, options: StructuredAskOptions<Schema>): Promise<Static<Schema>>;
     ask(prompt: string, options?: AskOptions): Promise<string>;
     /** True when the Agent was killed mid-Ask, so its cost is a floor (ADR-0012). */

package/assets/types/runtime/agent/define-agent.d.ts

@@ -12,10 +12,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[];
@@ -40,7 +48,9 @@ export interface AgentDefinition {
  * 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 declare function defineAgent(config: AgentConfig): AgentDefinition;
 /** True only for values produced by `defineAgent`. */

package/assets/types/runtime/agent/spawn-request.d.ts

@@ -0,0 +1,23 @@
+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 declare function openRequest(options: OpenRequestOptions): OpenOptions;
+/** Replaces the caller's `model`/`thinking` forms with one attempt's settled selection. */
+export declare function withSelection(options: SpawnOptions, selection: ModelSelection): ResolvedSpawnOptions;

package/assets/types/runtime/ask/ask-exchange-events.d.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 type { SettlementCause } from "./stall-watchdog.ts";
 /** What one finished Ask reports in its `ask_end` Lifecycle Event. */
@@ -9,7 +10,10 @@ export interface AskEndOutcome {
     readonly maxFrameGapMs: number | undefined;
     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 declare class AskEvents {
     #private;
     constructor(emit: EventSink, agent: string, index: number);
@@ -18,6 +22,8 @@ export declare class AskEvents {
     output: (channel: AskOutputChannel, text: string) => void;
     /** Composes the Nested Node path from this Ask's identity, then reports it. */
     node: (snapshot: NodeSnapshot) => void;
+    /** Not Ask-scoped: a fallback names the Agent only, like the spawn-time loop. */
+    fallback: (fallback: ModelFallback) => void;
     /** A `normal` cause is the absent default, so ordinary settlements stay lean. */
     end(outcome: AskEndOutcome): void;
 }

package/assets/types/runtime/ask/ask-exchange-options.d.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";
@@ -7,6 +8,15 @@ import type { EffectiveAskOptions } from "./ask-hash.ts";
 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;
@@ -23,6 +33,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/assets/types/runtime/ask/index.d.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/assets/types/runtime/cassette/replay-divergence.d.ts

@@ -1,5 +1,5 @@
-import type { AskMarker, OpenOptions } from "../transport/index.ts";
-import type { CassetteAgent } from "./cassette.ts";
+import type { AskMarker, OpenOptions, RecordedSpawnSelection } from "../transport/index.ts";
+import type { CassetteAgent, CassetteSpawn } from "./cassette.ts";
 /** A pure description of the first strict replay identity mismatch. */
 export interface ReplayMismatch {
     readonly kind: "unexpected-spawn" | "spawn-options" | "changed-ask" | "extra-ask";
@@ -17,3 +17,11 @@ export declare const replayMismatch: {
 };
 /** Converts a detected mismatch into strict replay's public failure. */
 export declare function strictReplay(mismatch: ReplayMismatch): never;
+/**
+ * True when a live spawn matches the recorded one on every identity field
+ * except the resolved model and thinking, so a resume may adopt the recorded
+ * selection instead of re-running Model Resolution (ADR-0039).
+ */
+export declare function spawnMatchesExceptModel(expected: CassetteSpawn, actual: OpenOptions): boolean;
+/** The recorded resolved selection of one Agent, or `undefined` when none is recorded. */
+export declare function recordedSpawnSelection(agent: CassetteAgent | null): RecordedSpawnSelection | undefined;

package/assets/types/runtime/errors.d.ts

@@ -5,7 +5,9 @@ export interface AskLimitOutcome {
     readonly kind: AskLimitKind;
     readonly count: number;
 }
+import type { ModelError } from "./model/index.ts";
 import type { AgentProgress } from "./transport/index.ts";
+export type { ModelError } from "./model/index.ts";
 export type { AgentProgress } from "./transport/index.ts";
 /** The recorded result when yaag rejects an Ask because no frame arrived within `idleMs`. */
 export interface AskStalledOutcome {
@@ -23,8 +25,12 @@ export interface AskInvalidOutputOutcome {
     /** Final extraction or TypeBox diagnostics, localized to JSON paths. */
     readonly errors: readonly string[];
 }
+/** The recorded history when every model candidate of one Model Resolution loop failed. */
+export interface ModelResolutionOutcome {
+    readonly modelErrors: readonly ModelError[];
+}
 /** Why an Ask, spawn, or Run failed. Programs may branch on this; most won't. */
-export type YaagErrorCode = "AGENT_FAILED" | "AGENT_DIED" | "AGENT_BUSY" | "ASK_TIMEOUT" | "ASK_LIMIT" | "ASK_STALLED" | "ASK_INVALID_OUTPUT" | "ARGS_INVALID" | "OPTIONS_CONFLICT" | "REPLAY_DIVERGED" | "RESUME_REFUSED" | "RUN_CLOSED" | "RUN_STOPPED" | "WORKTREE_REFUSED" | "SPAWN_FAILED";
+export type YaagErrorCode = "AGENT_FAILED" | "AGENT_DIED" | "AGENT_BUSY" | "ASK_TIMEOUT" | "ASK_LIMIT" | "ASK_STALLED" | "ASK_INVALID_OUTPUT" | "ARGS_INVALID" | "OPTIONS_CONFLICT" | "REPLAY_DIVERGED" | "RESUME_REFUSED" | "RUN_CLOSED" | "RUN_STOPPED" | "WORKTREE_REFUSED" | "MODEL_RESOLUTION_FAILED" | "SPAWN_FAILED";
 /** The single error class of the runtime (ADR-0003). */
 export declare class YaagError extends Error {
     readonly code: YaagErrorCode;
@@ -44,7 +50,13 @@ export declare class YaagError extends Error {
     readonly steeringEfforts?: number;
     /** Localized extraction or schema errors, present only for `ASK_INVALID_OUTPUT`. */
     readonly errors?: readonly string[];
-    constructor(code: YaagErrorCode, message: string, agent?: string, options?: AskLimitOutcome | AskStalledOutcome | AskInvalidOutputOutcome);
+    /**
+     * Failed model candidates, present only for `MODEL_RESOLUTION_FAILED`. It
+     * holds one entry for each attempt, oldest first. A candidate that already
+     * failed with `not_found` or `auth` is refused again (ADR-0037).
+     */
+    readonly modelErrors?: readonly ModelError[];
+    constructor(code: YaagErrorCode, message: string, agent?: string, options?: AskLimitOutcome | AskStalledOutcome | AskInvalidOutputOutcome | ModelResolutionOutcome);
 }
 /** Builds the runtime's uniform agent-scoped error message. */
 export declare function agentError(agent: string, code: YaagErrorCode, message: string): YaagError;
@@ -52,5 +64,7 @@ export declare function agentError(agent: string, code: YaagErrorCode, message:
 export declare function askLimitError(agent: string, outcome: AskLimitOutcome): YaagError;
 /** The ASK_STALLED rejection for one tripped idle watch. */
 export declare function askStalledError(agent: string, outcome: AskStalledOutcome): YaagError;
+/** The MODEL_RESOLUTION_FAILED rejection for an exhausted or self-repeating resolver. */
+export declare function modelResolutionError(agent: string, errors: readonly ModelError[], refusedCandidate?: string): YaagError;
 /** Narrows an unknown rejection reason to a YaagError. */
 export declare function isYaagError(value: unknown): value is YaagError;

package/assets/types/runtime/events.d.ts

@@ -7,8 +7,10 @@
  * dedicated fd arrives with the extension.
  */
 import type { SettlementCause } from "./ask/index.ts";
+import type { ModelErrorReason } from "./model/index.ts";
 import type { TokenBreakdown, WorktreeResolution } from "./transport/index.ts";
 export type { SettlementCause } from "./ask/index.ts";
+export type { ModelErrorReason } from "./model/index.ts";
 /**
  * A Run's outcome (ADR-0022). `paused` arrives with the pause slice.
  * `interrupted` is not terminal: only an in-flight Checkpoint carries it, and a
@@ -112,6 +114,22 @@ export type LifecycleEventBody = {
      * Watchdog settled it from observed state, so its usage is an undercount.
      */
     readonly cause?: SettlementCause;
+} | {
+    /**
+     * One failed Model Resolution attempt and the candidate that replaced it.
+     * yaag emits it at spawn time and inside an Ask (ADR-0037, ADR-0038).
+     * A resolver that gives up emits none: the Run fails with
+     * MODEL_RESOLUTION_FAILED, which already carries the full history.
+     */
+    readonly type: "model_fallback";
+    readonly agent: string;
+    /** The candidate pattern that failed, after inline-suffix stripping. */
+    readonly failedModel: string;
+    readonly reason: ModelErrorReason;
+    /** 0-based index of the failed attempt, as the resolver's history numbers it. */
+    readonly attempt: number;
+    /** The candidate resolution picked next. */
+    readonly resolvedModel: string;
 } | {
     readonly type: "agent_usage";
     readonly agent: string;

package/assets/types/runtime/index.d.ts

@@ -2,7 +2,7 @@ export type { AgentConfig, AgentDefinition } from "./agent/index.ts";
 export { agentDefinitionConfig, defineAgent, isAgentDefinition } from "./agent/index.ts";
 export type { Cassette, CassetteAgent, CassetteArtifact, CassetteAsk, CassetteGit, CassetteRun, CassetteSink, CassetteSpawn, } from "./cassette/index.ts";
 export { assertReplayable, CASSETTE_VERSION, loadCassette, recordingTransport, replayTransport, resumeTransport, } from "./cassette/index.ts";
-export type { AskInvalidOutputOutcome, AskLimitKind, AskLimitOutcome, AskStalledOutcome, YaagErrorCode, } from "./errors.ts";
+export type { AskInvalidOutputOutcome, AskLimitKind, AskLimitOutcome, AskStalledOutcome, ModelResolutionOutcome, YaagErrorCode, } from "./errors.ts";
 export { isYaagError, YaagError } from "./errors.ts";
 export type { AgentActivity, AskOutputChannel, EventSink, LifecycleEvent, LifecycleEventBody, NodeState, NodeUsage, StampedEventSink, } from "./events.ts";
 export type { ModelError, ModelErrorReason, ModelResolver, ModelSelection, ModelSpec, ThinkingResolver, ThinkingSpec, } from "./model/index.ts";
@@ -11,7 +11,7 @@ export { agentAskPath, childPath, DEFAULT_NODE_DECODERS, NodeTracker, sanitizeNo
 export { prompt, promptGist } from "./prompt/index.ts";
 export type { OrchestrationProgram, ProgramDefinition, RunContext, RunOptions, } from "./run/index.ts";
 export { defineRun, executeRun, isOrchestrationProgram, programDefinition } from "./run/index.ts";
-export type { AgentInfo, AgentState, AskingAgentInfo, EndedRunSummary, ExitedAgentInfo, IdleAgentInfo, NodeInfo, RunningRunSummary, RunOutcome, RunState, RunSummary, } from "./summary/index.ts";
+export type { AgentInfo, AgentState, AskingAgentInfo, EndedRunSummary, ExitedAgentInfo, IdleAgentInfo, ModelFallbackInfo, NodeInfo, RunningRunSummary, RunOutcome, RunState, RunSummary, } from "./summary/index.ts";
 export { applyEvent, initialSummary } from "./summary/index.ts";
 export type { AgentStats, AgentTransport, AskMarker, AskMarkerContext, AskPlayback, DiscoveredSkill, Frame, ReapPath, ReapTarget, SkillProbeFactory, TokenBreakdown, TransportFactory, TransportStartup, TransportStartupObserver, WorktreeResolution, } from "./transport/index.ts";
 export { readSystemPromptSidecar, reap, worktreeTransport } from "./transport/index.ts";

package/assets/types/runtime/model/index.d.ts

@@ -2,5 +2,12 @@
  * Public surface of the `model/` module: model resolution.
  * Files inside this directory import each other directly.
  */
-export { type ModelError, type ModelErrorReason, type ModelResolver, type ModelSelection, type ModelSpec, normalizeModelResolution, type ThinkingResolver, type ThinkingSpec, } from "./model-resolution.ts";
+export { ModelErrorHistory } from "./model-error-history.ts";
+export { classifyAskFailure, classifyModelFailure } from "./model-failure.ts";
+export type { ModelFallback, ModelFallbackSink } from "./model-fallback.ts";
+export type { AvailableModel } from "./model-match.ts";
+export { type ModelError, type ModelErrorReason, type ModelResolution, type ModelResolver, type ModelSelection, type ModelSpec, normalizeModelResolution, type ThinkingResolver, type ThinkingSpec, } from "./model-resolution.ts";
+export { type ModelSwapResult, swapModel } from "./model-swap.ts";
+export { type RecordedResolution, type RecordedResolutionOptions, type RecordedSpawnSelection, resolveRecordedModel, } from "./recorded-resolution.ts";
+export { type FallbackLoopOptions, type ResolutionLoopOptions, resolveModel, retryOnModelFailure, } from "./resolution-loop.ts";
 export type { ThinkingLevel } from "./thinking-level.ts";

package/assets/types/runtime/model/model-error-history.d.ts

@@ -0,0 +1,20 @@
+import type { ModelError, ModelErrorReason } from "./model-resolution.ts";
+/**
+ * The Model Resolution attempt history of one Agent.
+ *
+ * The spawn-time loop and every mid-Ask fallback loop of the same Agent share
+ * one history, so a resolver sees every candidate that already failed, whenever
+ * it failed.
+ */
+export declare class ModelErrorHistory {
+    #private;
+    /** Every failed attempt so far, oldest first. */
+    get errors(): readonly ModelError[];
+    /**
+     * Appends one failed attempt and returns it; the attempt number is the
+     * history length before the push.
+     */
+    record(reason: ModelErrorReason, failedModel: string): ModelError;
+    /** True when this candidate already failed for a reason a retry cannot fix. */
+    failedPermanently(candidate: string): boolean;
+}

package/assets/types/runtime/model/model-failure.d.ts

@@ -0,0 +1,18 @@
+import type { ModelErrorReason } from "./model-resolution.ts";
+/**
+ * Classifies a spawn or Ask failure into a Model Resolution trigger, or
+ * `undefined` for a generic failure that must stay an ordinary failure.
+ *
+ * Evaluation order is `not_found` → `auth` → `rate_limited`, first match wins:
+ * a "model not found" diagnostic may also mention API keys in its help text, so
+ * the most specific table has to be consulted first.
+ */
+export declare function classifyModelFailure(error: unknown): ModelErrorReason | undefined;
+/**
+ * Classifies one Ask rejection into a Model Resolution trigger.
+ *
+ * Only AGENT_FAILED can be a trigger: ASK_STALLED is generic and never enters
+ * resolution (ADR-0029), ASK_LIMIT/ASK_TIMEOUT/ASK_INVALID_OUTPUT are yaag's own
+ * verdicts, and AGENT_DIED leaves nothing to swap a model on.
+ */
+export declare function classifyAskFailure(error: unknown): ModelErrorReason | undefined;

package/assets/types/runtime/model/model-fallback.d.ts

@@ -0,0 +1,13 @@
+import type { ModelErrorReason } from "./model-resolution.ts";
+/** One failed Model Resolution attempt and the candidate that replaced it. */
+export interface ModelFallback {
+    /** The candidate pattern that failed, after inline-suffix stripping. */
+    readonly failedModel: string;
+    readonly reason: ModelErrorReason;
+    /** 0-based index of the failed attempt in the Agent's shared history. */
+    readonly attempt: number;
+    /** The candidate the resolver picked next. */
+    readonly resolvedModel: string;
+}
+/** Where a Model Resolution loop reports each fallback it takes. */
+export type ModelFallbackSink = (fallback: ModelFallback) => void;

package/assets/types/runtime/model/model-match.d.ts

@@ -0,0 +1,31 @@
+/** One entry of pi's `get_available_models` snapshot. */
+export interface AvailableModel {
+    readonly provider: string;
+    readonly id: string;
+    readonly name?: string;
+}
+/** What matching one yaag model pattern against pi's snapshot produced. */
+export type ModelMatch = {
+    readonly kind: "matched";
+    readonly model: AvailableModel;
+} | {
+    readonly kind: "no_match";
+} | {
+    readonly kind: "ambiguous";
+    readonly candidates: readonly string[];
+};
+/**
+ * Matches one yaag model pattern against the models pi reports as available.
+ *
+ * A reduced mirror of pi's `core/model-resolver.js` (`resolveCliModel` /
+ * `tryMatchModel`): exact `provider/id`, exact bare `id`, then a known provider
+ * prefix, then a partial `id`/`name` search. A bare id that exists under several
+ * providers is refused rather than guessed, because yaag cannot see pi's
+ * configured-auth ordering. No suffix parsing happens here: an inline thinking
+ * suffix is already stripped by `normalizeModelResolution`.
+ */
+export declare function matchAvailableModel(pattern: string, models: readonly AvailableModel[]): ModelMatch;
+/** Reads pi's `get_available_models` payload, or `null` when it is not one. */
+export declare function readAvailableModels(data: unknown): readonly AvailableModel[] | null;
+/** Reads one pi Model object, or `null` when the payload is not one. */
+export declare function readAvailableModel(entry: unknown): AvailableModel | null;

package/assets/types/runtime/model/model-resolution.d.ts

@@ -1,7 +1,21 @@
 import { 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. */
@@ -9,13 +23,37 @@ export interface ModelError {
     /** 0-based index of the attempt that produced this error. */
     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. */
 export interface ModelSelection {

package/assets/types/runtime/model/model-swap.d.ts

@@ -0,0 +1,27 @@
+import type { CommandResponse, Frame } from "../transport/index.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 declare function swapModel(options: {
+    readonly agent: string;
+    readonly command: ModelSwapCommand;
+    readonly selection: ModelSelection;
+}): Promise<ModelSwapResult>;

package/assets/types/runtime/model/recorded-resolution.d.ts

@@ -0,0 +1,37 @@
+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 declare function resolveRecordedModel(options: RecordedResolutionOptions): RecordedResolution | undefined;

package/assets/types/runtime/model/resolution-loop.d.ts

@@ -0,0 +1,47 @@
+import { ModelErrorHistory } from "./model-error-history.ts";
+import type { ModelFallbackSink } from "./model-fallback.ts";
+import type { 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 declare function resolveModel<T>(options: ResolutionLoopOptions<T>): Promise<T>;
+/** 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 declare function retryOnModelFailure<T>(options: FallbackLoopOptions<T>): Promise<T>;

package/assets/types/runtime/summary/index.d.ts

@@ -3,4 +3,4 @@
  * Files inside this directory import each other directly.
  */
 export { applyEvent, type EndedRunSummary, initialSummary, type RunningRunSummary, type RunOutcome, type RunState, type RunSummary, } from "./summary.ts";
-export type { AgentInfo, AgentState, AskingAgentInfo, ExitedAgentInfo, IdleAgentInfo, NodeInfo, } from "./summary-agent.ts";
+export type { AgentInfo, AgentState, AskingAgentInfo, ExitedAgentInfo, IdleAgentInfo, ModelFallbackInfo, NodeInfo, } from "./summary-agent.ts";

package/assets/types/runtime/summary/summary-agent.d.ts

@@ -1,7 +1,9 @@
 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. */
 export type AgentState = "idle" | "asking" | "exited";
@@ -24,6 +26,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. */
 export interface IdleAgentInfo extends AgentInfoBase {
@@ -68,6 +74,8 @@ export interface AgentExitObservation {
     readonly incomplete: boolean;
     readonly worktree?: WorktreeResolution;
 }
+/** Produces an idle placeholder for lifecycle events received before a spawn. */
+export declare function placeholderAgent(): IdleAgentInfo;
 /**
  * Reconciles spawn identity without reopening a terminal Agent or losing facts
  * learned from a prior exit. A late spawn fills only missing identity fields.

package/assets/types/runtime/summary/summary-fallbacks.d.ts

@@ -0,0 +1,30 @@
+import type { LifecycleEventBody, ModelErrorReason } from "../events.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 declare function applyModelFallback(agent: AgentRecord, event: ModelFallbackEvent, at: number | null): AgentRecord;
+export {};

package/assets/types/runtime/summary/summary.d.ts

@@ -2,7 +2,7 @@ import type { LifecycleEvent, LifecycleEventBody, RunOutcome } from "../events.t
 import type { TokenBreakdown } from "../transport/index.ts";
 import type { AgentInfo } from "./summary-agent.ts";
 export type { NodeState, NodeUsage, RunOutcome } from "../events.ts";
-export type { AgentActivity, AgentInfo, AgentState, AskingAgentInfo, ExitedAgentInfo, IdleAgentInfo, NodeInfo, } from "./summary-agent.ts";
+export type { AgentActivity, AgentInfo, AgentState, AskingAgentInfo, ExitedAgentInfo, IdleAgentInfo, ModelFallbackInfo, NodeInfo, } from "./summary-agent.ts";
 /** The observer-facing lifecycle state of a Run. */
 export type RunState = "running" | "ended";
 /** Accounting and identity facts shared by all Run observer states. */
@@ -22,6 +22,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. */
 export interface RunningRunSummary extends RunSummaryBase {

package/assets/types/runtime/transport/fake-transport.d.ts

@@ -1,3 +1,4 @@
+import type { AvailableModel } from "../model/index.ts";
 import type { AgentStats, AgentTransport, AskMarker, Frame } from "./transport.ts";
 /**
  * Scripted frame playback for one prompt sent through a FakeTransport.
@@ -42,6 +43,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";
@@ -59,7 +66,8 @@ export interface FakeTransportOptions extends FakePromptScript {
  */
 export declare class FakeTransport implements AgentTransport {
     #private;
-    readonly model = "test/model";
+    /** The model this fake currently reports, which a `set_model` swap updates. */
+    get model(): string;
     /** Everything the runtime wrote, in order. */
     readonly sent: Frame[];
     readonly asks: AskMarker[];

package/assets/types/runtime/transport/index.d.ts

@@ -2,6 +2,7 @@
  * Public surface of the `transport/` module: the pi process seam and its probes.
  * Files inside this directory import each other directly.
  */
+export type { RecordedSpawnSelection } from "../model/index.ts";
 export { type CommandResponse, Connection } from "./connection.ts";
 export { FakeTransport, type FakeTransportOptions, recordedFrames, reportResultFrames, } from "./fake-transport.ts";
 export { FrameGapTracker } from "./frame-gap.ts";

package/assets/types/runtime/transport/stderr-tail.d.ts

@@ -0,0 +1,12 @@
+/** Bound on the kept stderr tail, so a chatty Agent cannot grow the buffer. */
+export declare const STDERR_TAIL_BYTES = 4096;
+/** Bound on the diagnostic folded into a failure message, so it stays readable. */
+export declare const STDERR_MESSAGE_CHARS = 300;
+/** Appends one chunk to a stderr tail, keeping only the last bounded window. */
+export declare function appendStderrTail(tail: string, chunk: string): string;
+/**
+ * The exit diagnostic of a stderr tail as a message suffix, or "" when pi
+ * printed nothing fatal. Warning lines are dropped, the rest is collapsed to one
+ * line and capped, so a failure message stays readable.
+ */
+export declare function stderrDiagnostic(tail: string): string;

package/assets/types/runtime/transport/transport.d.ts

@@ -1,5 +1,6 @@
 import type { CanonicalJsonObject, ReportedResult } from "../ask-contract/index.ts";
 import type { AskLimitOutcome, AskStalledOutcome } from "../errors.ts";
+import type { RecordedSpawnSelection } from "../model/index.ts";
 import type { AskOptions, ResolvedSpawnOptions, ThinkingLevel } from "../types.ts";
 /**
  * The one seam of the runtime (ticket 04). An AgentTransport represents a whole
@@ -176,4 +177,13 @@ export type TransportStartupObserver = (startup: TransportStartup) => void;
 /** How the layer above obtains transports. Swapped wholesale for replay. */
 export interface TransportFactory {
     open(options: OpenOptions, observeStartup?: TransportStartupObserver): Promise<AgentTransport>;
+    /**
+     * The resolved selection this factory recorded for the Agent it would open
+     * next, so a Cassette-backed spawn adopts the recorded outcome instead of
+     * re-running Model Resolution (ADR-0037, ADR-0038, ADR-0039).
+     *
+     * A pure peek: it must not advance the factory's spawn cursor. Live factories
+     * record nothing and omit it.
+     */
+    recordedSpawn?(options: OpenOptions): RecordedSpawnSelection | undefined;
 }

package/assets/types/runtime/types.d.ts

@@ -10,7 +10,10 @@ export interface SpawnOptions {
      *
      * An array is an ordered fallback list and a function picks the next candidate
      * from the failures so far. Any resolved pattern may carry an inline thinking
-     * suffix (`"opus-5:medium"`), which wins over `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`. See
+     * `ModelSpec` and `ModelResolver` for the termination rules (ADR-0037).
      */
     readonly model?: ModelSpec;
     /** Replaces the default system prompt (`pi --system-prompt`). */
@@ -18,7 +21,8 @@ export interface SpawnOptions {
     /**
      * Sets pi's thinking level; omission preserves pi's default. A function picks
      * the level from the settled model, and is not consulted for a model pattern
-     * that carries an inline thinking suffix.
+     * that carries an inline thinking suffix. The resolver runs again for each
+     * attempt, with the model that settled for that attempt (ADR-0037).
      */
     readonly thinking?: ThinkingSpec;
     /** Appends text to pi's system prompt (`pi --append-system-prompt`). */
@@ -56,7 +60,12 @@ export interface SpawnOptions {
     /** Request a fresh Git worktree. The requested cwd remains the base until spawn resolves. */
     readonly worktree?: boolean;
 }
-/** Spawn options after Model Resolution has settled one model and thinking level. */
+/**
+ * Spawn options after Model Resolution has settled one model and thinking level.
+ *
+ * This is the settled shape, and it is what the Cassette identity hashes
+ * (ADR-0039).
+ */
 export interface ResolvedSpawnOptions extends Omit<SpawnOptions, "model" | "thinking"> {
     readonly model?: string;
     readonly thinking?: ThinkingLevel;
@@ -79,6 +88,11 @@ export interface SpawnOverrides {
  * Agent, permits one further turn (or a fixed duration grace), then aborts and
  * rejects with `ASK_LIMIT` if it has not settled. This leaves the Handle alive.
  * `timeoutMs` is independent: it kills the Agent and rejects with `ASK_TIMEOUT`.
+ *
+ * A model failure inside an Ask starts Model Fallback and retries the Ask
+ * (ADR-0038). Each attempt gets fresh soft limits, a fresh Stall Watchdog and a
+ * fresh output collector. `timeoutMs` is the exception: it is the hard ceiling
+ * of the whole Ask, and every attempt shares one deadline.
  */
 export interface AskOptions {
     /** Reject and kill the Agent if it has not settled in time. Unset = no bound. */
@@ -101,7 +115,10 @@ export interface AskOptions {
      * live Ask by default (ADR-0029). On expiry yaag probes the Agent and either
      * recovers a missed settlement or rejects with `ASK_STALLED`. Omission uses
      * the 10-minute default. `false`, and any value that is not above zero,
-     * disable the watchdog for this Ask.
+     * disable the watchdog for this Ask. `ASK_STALLED` is a generic failure: it
+     * never starts Model Fallback. If the silence budget ends the Ask before pi
+     * reports a model failure, the Ask fails `ASK_STALLED` and no swap happens
+     * (ADR-0029).
      */
     readonly stallMs?: number | false;
     /** Per-Ask replacement for the runtime's wrap-up steering message. */
@@ -134,7 +151,10 @@ export interface Handle {
     readonly cwd: string;
     /** Fresh branch for a worktree Agent; undefined for ordinary Agents. */
     readonly branch: string | undefined;
-    /** Model id as reported by the Agent's own `get_state` — not the requested pattern. */
+    /**
+     * Model id as reported by the Agent's own `get_state` — not the requested
+     * pattern. A mid-Ask model swap updates it (ADR-0038).
+     */
     readonly model: string;
     /**
      * Sends a prompt and resolves after the Agent's turn settles.
@@ -147,6 +167,9 @@ export interface Handle {
      * (default 3) and then rejects recoverably with `ASK_INVALID_OUTPUT` after an
      * abort settlement; a reported value the schema rejects fails the same way
      * without a correction. These recoverable outcomes leave the Handle reusable.
+     * A retry after a Model Fallback discards the result the failed attempt
+     * reported, and arms the collector again, so a stale result cannot settle the
+     * retried Ask (ADR-0032, ADR-0038).
      * A concurrent call rejects with `AGENT_BUSY`.
      */
     ask<Schema extends TSchema>(prompt: string, options: StructuredAskOptions<Schema>): Promise<Static<Schema>>;

package/assets/types/runtime/wire-constants.d.ts

@@ -14,5 +14,7 @@ export declare const ASK_OUTPUT_MAX_BYTES: number;
 export declare const NODE_GIST_MAX_CHARS = 120;
 /** Maximum Nested Nodes the Summary keeps per Agent; past it, exited nodes prune oldest-first. */
 export declare const AGENT_NODE_TABLE_MAX = 64;
+/** Maximum Model Resolution fallbacks the Summary keeps per Agent; past it, the oldest prune. */
+export declare const AGENT_MODEL_FALLBACK_MAX = 16;
 /** Prefix marking that the oldest pending Ask output was dropped to fit the wire cap. */
 export declare const ASK_OUTPUT_TRUNCATION_MARKER = "[\u2026output truncated\u2026]";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yaag/cli",
-  "version": "0.6.2",
+  "version": "0.7.0",
   "publishConfig": {
     "access": "public"
   },
@@ -21,8 +21,8 @@
   },
   "dependencies": {
     "@earendil-works/pi-tui": "^0.84.0",
-    "@yaag/runtime": "0.6.2",
-    "@yaag/tui": "0.6.2",
+    "@yaag/runtime": "0.7.0",
+    "@yaag/tui": "0.7.0",
     "typebox": "1.3.7"
   }
 }

package/src/terminal/render.ts

@@ -39,6 +39,8 @@ function renderPlainEvent(event: LifecycleEventBody, mode: PlainRenderMode): str
         event.maxFrameGapMs === undefined ? "" : ` max gap ${seconds(event.maxFrameGapMs)}`;
       return `[${event.agent}] ask #${event.index + 1} ${event.ok ? "done" : "failed"} ${seconds(event.durationMs)}${gap}`;
     }
+    case "model_fallback":
+      return `[${event.agent}] model ${event.failedModel} ${event.reason} — falling back to ${event.resolvedModel}`;
     case "agent_exit":
       return `[${event.agent}] exit ${tokens(event.tokens)} ${cost(event.cost)}${event.incomplete ? " (killed mid-ask, cost incomplete)" : ""}`;
     case "run_end": {
@@ -58,6 +60,7 @@ function minimalEvent(type: LifecycleEventBody["type"]): boolean {
     type === "agent_spawn" ||
     type === "ask_start" ||
     type === "ask_end" ||
+    type === "model_fallback" ||
     type === "agent_exit" ||
     type === "run_end"
   );