@yaag/cli 0.6.2 → 0.8.0

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/run/run.d.ts

@@ -1,4 +1,5 @@
 import { type Cassette, type CassetteSink } from "../cassette/index.ts";
+import { type EffectiveConfig } from "../config/index.ts";
 import type { StampedEventSink } from "../events.ts";
 import type { TransportFactory } from "../transport/index.ts";
 import { type SkillProbeFactory } from "../transport/index.ts";
@@ -33,6 +34,12 @@ export interface RunOptions {
     readonly signal?: AbortSignal;
     /** Overrides the default checkpoint directory a stopped Run publishes into (ADR-0021). */
     readonly checkpointDir?: string;
+    /**
+     * Effective Config for this Run, read once by the launcher (ADR-0040). The
+     * Run never loads it itself: omission runs config-free, so no Run picks up a
+     * config it was not given, and every test stays hermetic.
+     */
+    readonly config?: EffectiveConfig;
 }
 /**
  * Executes one Orchestration Program and resolves with its return value.

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
@@ -156,6 +157,11 @@ export interface OpenOptions {
     readonly resolvedSkillPaths?: readonly string[];
     /** Absolute launch-ready extension paths resolved above the seam, emitted as repeated `-e` flags. */
     readonly resolvedExtensionPaths?: readonly string[];
+    /**
+     * Declared extensions in final concatenation order, unresolved (ADR-0040).
+     * Spawn identity only: it never becomes argv, and it is absent when empty.
+     */
+    readonly declaredExtensions?: readonly string[];
     /** Session storage directory. Used by the e2e suite to stay out of ~/.pi (ticket 06). */
     readonly sessionDir?: string;
     /** Resumes an existing pi session, translated to `--session <path>`. */
@@ -176,4 +182,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`). */
@@ -32,6 +36,11 @@ export interface SpawnOptions {
      * resolve from the Orchestration Program file; each becomes `pi -e <path>`.
      */
     readonly extensions?: readonly string[];
+    /**
+     * Load the Effective Config's `agents.extensions` for this Agent. Default
+     * true; false spawns with only the extensions this call declares (ADR-0040).
+     */
+    readonly configExtensions?: boolean;
     /**
      * Tool allowlist layered over the ADR-0026 baseline; omission is tool-free when hermetic.
      * `disallowedTools` applies last. A non-empty surviving allowlist is verified after startup;
@@ -56,7 +65,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 +93,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 +120,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 +156,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 +172,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.8.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.8.0",
+    "@yaag/tui": "0.8.0",
     "typebox": "1.3.7"
   }
 }

package/src/argv.ts

@@ -5,9 +5,9 @@
 import { resolve } from "node:path";
 
 export const USAGE = `usage:
-  yaag run <program.ts> [--quiet] [--args <json>] [--record <file>] [--replay <file>] [--resume <file>] [--events-fd <n>]
-  yaag run --eval <source> [--quiet] [--args <json>] [--record <file>] [--replay <file>] [--resume <file>] [--events-fd <n>]
-  yaag run --eval-fd <n> [--quiet] [--args <json>] [--record <file>] [--replay <file>] [--resume <file>] [--events-fd <n>]
+  yaag run <program.ts> [--quiet] [--args <json>] [--record <file>] [--replay <file>] [--resume <file>] [--events-fd <n>] [--config <file>] [--no-config]
+  yaag run --eval <source> [--quiet] [--args <json>] [--record <file>] [--replay <file>] [--resume <file>] [--events-fd <n>] [--config <file>] [--no-config]
+  yaag run --eval-fd <n> [--quiet] [--args <json>] [--record <file>] [--replay <file>] [--resume <file>] [--events-fd <n>] [--config <file>] [--no-config]
   yaag describe <program.ts>
   yaag setup-workspace [dir]
 
@@ -20,6 +20,12 @@ must be a file.
 close that descriptor. It keeps the source out of the process argument list,
 where every local user can read it. The yaag extension always uses it.
 
+--config <file> reads one more config file for this Run. Give it one time only.
+yaag reads it after the global config and after the project config.
+
+--no-config tells yaag to ignore the global config and the project config. It
+does not ignore --config.
+
 A --resume or --replay Run also needs the program: give the program file,
 --eval <source>, or --eval-fd <n>. A Cassette holds the history of a Run, and never the program
 to run.
@@ -44,6 +50,8 @@ export type ParsedArgv =
       readonly record?: string;
       readonly replay?: string;
       readonly resume?: string;
+      readonly config?: string;
+      readonly noConfig?: boolean;
     }
   | { readonly ok: true; readonly command: "describe"; readonly file: string }
   | { readonly ok: true; readonly command: "setup-workspace"; readonly dir: string }
@@ -72,12 +80,16 @@ function parseRun(tokens: readonly string[]): ParsedArgv {
   let record: string | undefined;
   let replay: string | undefined;
   let resume: string | undefined;
+  let config: string | undefined;
+  let noConfig = false;
   let quiet = false;
 
   for (let index = 0; index < tokens.length; index += 1) {
     const token = tokens[index] ?? "";
     if (token === "--quiet") {
       quiet = true;
+    } else if (token === "--no-config") {
+      noConfig = true;
     } else if (
       token === "--args" ||
       token === "--eval" ||
@@ -85,7 +97,8 @@ function parseRun(tokens: readonly string[]): ParsedArgv {
       token === "--events-fd" ||
       token === "--record" ||
       token === "--replay" ||
-      token === "--resume"
+      token === "--resume" ||
+      token === "--config"
     ) {
       const value = tokens[index + 1];
       if (value === undefined) return failure(`${token} needs a value\n${USAGE}`);
@@ -108,6 +121,10 @@ function parseRun(tokens: readonly string[]): ParsedArgv {
         record = value;
       } else if (token === "--replay") {
         replay = value;
+      } else if (token === "--config") {
+        // One Run Config only: two of them would leave the merge order unstated.
+        if (config !== undefined) return failure(`--config may be given once\n${USAGE}`);
+        config = value;
       } else {
         resume = value;
       }
@@ -134,6 +151,8 @@ function parseRun(tokens: readonly string[]): ParsedArgv {
     ...(record === undefined ? {} : { record }),
     ...(replay === undefined ? {} : { replay }),
     ...(resume === undefined ? {} : { resume }),
+    ...(config === undefined ? {} : { config }),
+    ...(noConfig ? { noConfig: true } : {}),
   };
 }
 

package/src/cli.ts

@@ -10,6 +10,7 @@ import {
   type StampedEventSink,
 } from "@yaag/runtime";
 import { parseArgv } from "./argv.ts";
+import { loadRunConfig } from "./config/index.ts";
 import { loadProgram, loadRunProgram, registerRuntimeAlias } from "./program/index.ts";
 import { setupWorkspace } from "./setup-workspace.ts";
 import {
@@ -47,6 +48,13 @@ export async function main(argv: readonly string[]): Promise<number> {
       await loadCassette(parsed.resume);
     }
     if (parsed.command === "describe") return describe(await loadProgram(resolve(parsed.file)));
+    // Before the program import: a bad config must fail the Run at start, and
+    // never after an arbitrary program module ran its top level (ADR-0040).
+    const config = await loadRunConfig({
+      programFile: parsed.program.kind === "file" ? resolve(parsed.program.file) : undefined,
+      ...(parsed.config === undefined ? {} : { configPath: parsed.config }),
+      ...(parsed.noConfig === true ? { noConfig: true } : {}),
+    });
     const { program, programFile, programSource } = await loadRunProgram(parsed.program);
     return await run(program, {
       programFile,
@@ -56,6 +64,7 @@ export async function main(argv: readonly string[]): Promise<number> {
       record: parsed.record,
       replay: parsed.replay,
       resume: parsed.resume,
+      config,
       quiet: parsed.quiet,
     });
   } catch (error) {