agent-lyceum 0.18.0 → 0.19.0

package/README.md

@@ -11,6 +11,7 @@ Give a task to a **team of agents** (Claude Code and/or Codex) instead of one ov
 - **Roles that stay in role.** Each agent has its own persona (`AGENT.md`) and long-term memory, so a reviewer keeps reviewing instead of drifting into writing code.
 - **Agents can't rewrite the rules.** An agent can only write its own memory and outbox. It can't touch other agents' context or its own persona, and this is enforced by the OS sandbox where possible, not just by a prompt. See [Write scope](docs/write-scope.md).
 - **Mix runtimes.** Claude Code and Codex agents work in the same team.
+- **Backup models.** If a model is rate-limited, out of quota or unreachable, a run can switch to a backup model or runtime instead of stopping. See [Configuration](docs/configuration.md#fallback-models).
 - **Nothing hidden.** Agents talk through plain-file mailboxes, so every message, decision and memory is a file you can read, grep and diff. The dispatcher never merges for you.
 
 **Not a fit** for small, one-shot edits: a single Claude Code or Codex session is faster and cheaper. Use a team when the task is big enough to split, review or run in parallel.

package/README.zh-TW.md

@@ -11,6 +11,7 @@
 - **角色不會跑掉。** 每個 agent 有自己的人設（`AGENT.md`）與長期記憶，reviewer 會一直做 review，不會漸漸變成在寫程式。
 - **agent 改不了規則。** agent 只能寫自己的記憶與寄件匣（outbox），不能改其他 agent 的 context，也不能改自己的人設；能做到的地方由 OS 沙箱強制，而不只靠 prompt。見 [Write scope](docs/write-scope.zh-TW.md)。
 - **混用 runtime。** Claude Code 與 Codex agent 可在同一個團隊。
+- **備用模型。** 模型被限流、額度用完或連不上時，run 可以改用備用的模型或 runtime 繼續，而不是直接停下。見[設定](docs/configuration.zh-TW.md#備援模型)。
 - **沒有黑箱。** agent 透過純檔案信箱溝通，每則訊息、決策與記憶都是你能讀、能 grep、能 diff 的檔案；dispatcher 不會替你 merge。
 
 **不適合**小而單次的修改：單一 Claude Code 或 Codex session 更快更省。任務大到值得拆分、review 或平行執行時，再用團隊。

package/dist/adapters/claude.d.ts

@@ -1,7 +1,19 @@
 import type { ResolvedAgent, ResolvedProject } from "../config.js";
+import type { ErrorKind } from "../schema.js";
 import type { Invocation, WakeInput } from "./types.js";
 export declare function buildClaudeSettings(project: ResolvedProject, agent: ResolvedAgent): Record<string, unknown>;
 export declare function buildClaudeInvocation(input: WakeInput): Invocation;
+/**
+ * The text the rules read: the result message (only when it is an error message: pass `result` for an `is_error` run), stderr, and the HTTP status
+ * the CLI reports as `api_error_status`. With no `result` and no result in stdout, stdout itself, but only when it is plain text: structured
+ * output (starting with `{` or `[`) without a result is a transcript, and the agent's own words there must not read as an error.
+ */
+export declare function classifyClaudeError(out: {
+    code: number | null;
+    stdout: string;
+    stderr: string;
+    result?: string;
+}): ErrorKind;
 interface ClaudeResult {
     result?: string;
     session_id?: string;

package/dist/adapters/claude.js

@@ -88,9 +88,45 @@ export function buildClaudeInvocation(input) {
         stream: () => claudeStream(),
     };
 }
+/**
+ * Ordered, first match wins: put the more specific kind before the broader one (a usage limit is `quota`, not `rate_limit`).
+ * Samples: observed = captured from a real run, documented = from the CLI/API docs, not yet seen in a log.
+ */
+const CLAUDE_RULES = [
+    // observed: `Invalid API key · Fix external API key` with api_error_status 401; documented: `Not logged in · Please run /login`
+    { kind: "auth", re: /\bHTTP 401\b|invalid api key|not logged in|please run \/login/i },
+    // documented: `5-hour limit reached ∙ resets 3pm`, API 400 `Credit balance is too low`
+    { kind: "quota", re: /\b(5-hour|weekly|usage) limit reached\b|credit balance is too low/i },
+    // documented: API 429 `rate_limit_error`, 529 `overloaded_error`
+    { kind: "rate_limit", re: /\bHTTP (429|529)\b|rate_limit_error|rate limit (reached|exceeded)|overloaded_error|^api error: overloaded/im },
+    // observed: `API Error: Connection refused — ... (ECONNREFUSED)`; documented: the other Node error codes
+    { kind: "network", re: /ECONNREFUSED|ECONNRESET|ENOTFOUND|EAI_AGAIN|ETIMEDOUT|socket hang up/i },
+    // documented: a native crash prints one of these (a signal kill has no exit code, see `isSignalKill`)
+    { kind: "crash", re: /segmentation fault|heap out of memory/i },
+];
+/** A process that ended without an exit code was killed by a signal that was not ours (timeouts and cancels never get here). */
+const isSignalKill = (code) => code === null;
+function classifyWith(rules, code, text) {
+    const hit = rules.find((r) => r.re.test(text));
+    if (hit)
+        return hit.kind;
+    return isSignalKill(code) ? "crash" : "unknown"; // never default to crash: a wrong guess would switch models for nothing
+}
+/**
+ * The text the rules read: the result message (only when it is an error message: pass `result` for an `is_error` run), stderr, and the HTTP status
+ * the CLI reports as `api_error_status`. With no `result` and no result in stdout, stdout itself, but only when it is plain text: structured
+ * output (starting with `{` or `[`) without a result is a transcript, and the agent's own words there must not read as an error.
+ */
+export function classifyClaudeError(out) {
+    const status = /"api_error_status":\s*(\d{3})/.exec(out.stdout)?.[1];
+    const j = extractClaudeResult(out.stdout);
+    const structured = /^[[{]/.test(out.stdout.trimStart());
+    const message = out.result ?? (j ? (j.is_error ? String(j.result ?? "") : "") : structured ? "" : out.stdout);
+    return classifyWith(CLAUDE_RULES, out.code, [message, out.stderr, status ? `HTTP ${status}` : ""].join("\n"));
+}
 function interpretClaude(j, stdout, stderr, code) {
     if (!j)
-        return { ok: false, text: stdout, error: (stderr || stdout || `exit code ${code}`).slice(0, 500) };
+        return { ok: false, text: stdout, error: (stderr || stdout || `exit code ${code}`).slice(0, 500), kind: classifyClaudeError({ code, stdout, stderr }) };
     const ok = code === 0 && !j.is_error;
     return {
         ok,
@@ -98,6 +134,7 @@ function interpretClaude(j, stdout, stderr, code) {
         sessionId: j.session_id,
         outputTokens: j.usage?.output_tokens,
         error: ok ? undefined : String(j.result ?? stderr).slice(0, 500),
+        kind: ok ? undefined : classifyClaudeError({ code, stdout, stderr, result: j.is_error && j.result !== undefined ? String(j.result) : undefined }),
     };
 }
 /** Reads `--output-format json` output line by line: only JSON lines are kept, and only the last few, so a flood of other output costs nothing. */

package/dist/adapters/codex.d.ts

@@ -1,5 +1,12 @@
+import type { ErrorKind } from "../schema.js";
 import type { Invocation, WakeInput } from "./types.js";
 export declare function codexWritableRoots(input: WakeInput): string[];
 /** Sum `output_tokens` over `turn.completed` events in `codex exec --json` output. */
 export declare function codexOutputTokens(jsonl: string): number | undefined;
 export declare function buildCodexInvocation(input: WakeInput): Invocation;
+export declare function classifyCodexError(out: {
+    code: number | null;
+    stdout: string;
+    stderr: string;
+    result?: string;
+}): ErrorKind;

package/dist/adapters/codex.js

@@ -100,6 +100,46 @@ export function buildCodexInvocation(input) {
         },
     };
 }
+/**
+ * Ordered, first match wins: put the more specific kind before the broader one (an exhausted quota also arrives as a 429).
+ * Samples: observed = captured from a real `codex exec`, documented = from the CLI/API docs, not yet seen in a log.
+ */
+const CODEX_RULES = [
+    // documented: `You exceeded your current quota` / `insufficient_quota`, ChatGPT plans: `You've hit your usage limit`
+    { kind: "quota", re: /insufficient_quota|exceeded your current quota|hit your usage limit/i },
+    // documented: `exceeded retry limit, last status: 429 Too Many Requests`, `rate_limit_exceeded`
+    { kind: "rate_limit", re: /\bstatus:? 429\b|\b429 too many requests|rate_limit_exceeded|rate limit reached/i },
+    // observed: `unexpected status 401 Unauthorized: Incorrect API key provided ... invalid_api_key`; documented: `Not logged in`
+    { kind: "auth", re: /\bstatus:? 401\b|\b401 unauthorized|invalid_api_key|incorrect api key|not logged in|codex login/i },
+    // `Reconnecting... waiting for network (Connection failed: error sending request)` is observed as a retry event only (a real codex with a dead
+    // network never ends by itself: the runner times it out); a final-failure sample is documented-not-observed, as are DNS / Node error codes
+    { kind: "network", re: /waiting for network|error sending request|dns error|ECONNREFUSED|ECONNRESET|ENOTFOUND|EAI_AGAIN|ETIMEDOUT/i },
+    { kind: "crash", re: /segmentation fault|panicked at/i },
+];
+/** The message of the last `turn.failed` event: the final verdict, as opposed to the reconnect noise before it. */
+function failureMessage(stdout) {
+    for (const line of stdout.split("\n").reverse()) {
+        if (!line.includes('"turn.failed"'))
+            continue;
+        try {
+            const m = JSON.parse(line).error?.message;
+            if (typeof m === "string")
+                return m;
+        }
+        catch {
+            /* cut off by the tail window: not JSON */
+        }
+    }
+    return undefined;
+}
+export function classifyCodexError(out) {
+    // Only error channels are read: the final turn.failed message, else stderr. stdout also carries command output and the agent's own words.
+    const text = out.result ?? failureMessage(out.stdout) ?? out.stderr;
+    const hit = CODEX_RULES.find((r) => r.re.test(text));
+    if (hit)
+        return hit.kind;
+    return out.code === null ? "crash" : "unknown"; // killed by a signal; otherwise never guess crash
+}
 function finishCodex(lastFile, sessionId, outputTokens, stdout, stderr, code) {
     let text = "";
     try {
@@ -109,5 +149,6 @@ function finishCodex(lastFile, sessionId, outputTokens, stdout, stderr, code) {
         /* no last message */
     }
     const ok = code === 0;
-    return { ok, text, sessionId, outputTokens, error: ok ? undefined : (stderr || stdout || `exit code ${code}`).slice(-500) };
+    // `error` is the last 500 chars of stderr||stdout; `kind` comes from the classifier's own, narrower source preference
+    return { ok, text, sessionId, outputTokens, error: ok ? undefined : (stderr || stdout || `exit code ${code}`).slice(-500), kind: ok ? undefined : classifyCodexError({ code, stdout, stderr }) };
 }

package/dist/adapters/types.d.ts

@@ -1,3 +1,4 @@
+import type { ErrorKind } from "../schema.js";
 import type { ResolvedAgent, ResolvedProject } from "../config.js";
 import type { AgentWorkspace } from "../worktree.js";
 export interface WakeInput {
@@ -26,6 +27,8 @@ export interface WakeResult {
     error?: string;
     /** Stopped because the run was cancelled, not because it failed. */
     cancelled?: boolean;
+    /** Why it failed, for the fallback decision. Unset on success and on cancellation. */
+    kind?: ErrorKind;
 }
 export type Parsed = {
     ok: boolean;
@@ -33,6 +36,8 @@ export type Parsed = {
     sessionId?: string;
     outputTokens?: number;
     error?: string;
+    /** Set on failure only; `unknown` when no rule recognizes the output. */
+    kind?: ErrorKind;
 };
 /** Reads a runtime's stdout line by line while it runs, keeping only what it needs. */
 export interface StreamParser {

package/dist/call.d.ts

@@ -1,5 +1,6 @@
 import { type Invoker } from "./adapters/index.js";
 import { type ResolvedAgent, type ResolvedProject } from "./config.js";
+import { type Tried } from "./fallback.js";
 export declare const CALL_PROJECT = "(call)";
 export declare const callsDir: (home: string) => string;
 export interface CallOptions {
@@ -11,6 +12,8 @@ export interface CallOptions {
     invoker?: Invoker;
     signal?: AbortSignal;
     say?: (line: string) => void;
+    /** Only used with a fallback chain, to wait out a cooldown; tests pass one that does not wait. */
+    sleep?: (ms: number, signal?: AbortSignal) => Promise<void>;
 }
 export interface CallResult {
     callId: string;
@@ -20,6 +23,8 @@ export interface CallResult {
     /** The agent's final reply (empty when the call failed). */
     text: string;
     error?: string;
+    /** With a fallback chain: each model that failed, in order. */
+    tried?: Tried[];
     /** Protected files the agent changed and agent-lyceum put back. */
     reverted: string[];
 }

package/dist/call.js

@@ -3,6 +3,7 @@ import path from "node:path";
 import { realInvoker } from "./adapters/index.js";
 import { must } from "./assert.js";
 import { ConfigError, loadGlobal, resolveProjectFrom } from "./config.js";
+import { agentForCandidate, candidatesFor, Cooldowns, runWithFallback } from "./fallback.js";
 import { atomicWrite } from "./fs-util.js";
 import { ProtectedGuard } from "./guard.js";
 import { assertName, homePaths, isInside } from "./paths.js";
@@ -137,23 +138,45 @@ export async function callAgent(o) {
         const guard = new ProtectedGuard(project);
         say(`Calling ${agent.name} in ${dir} (call ${callId})`);
         const invoke = o.invoker ?? realInvoker;
-        const result = await invoke({
-            project,
-            agent,
-            workDir: callDir,
-            systemPrompt: buildSoloSystemPrompt(project, agent),
-            userPrompt: buildCallUserPrompt(agent, o.task),
-            timeoutSec: project.dispatcher.wake_timeout_sec,
+        const all = candidatesFor(agent);
+        const chain = all.length > 1;
+        // The primary logs to log/ as always; each backup to a directory of its own, so its run does not overwrite the primary's logs.
+        const logDirFor = (c) => (c.primary ? path.join(callDir, "log") : path.join(callDir, "log", `fallback-${all.indexOf(c)}`));
+        // A call is a single shot: no retries on one model, and cooldowns that live only as long as it does.
+        const outcome = await runWithFallback({
+            candidates: all,
+            legacy: !chain,
+            retry: 0,
+            cooldowns: new Cooldowns(),
+            cooldownSec: project.dispatcher.fallback_cooldown_sec,
             signal: o.signal,
-            logDir: path.join(callDir, "log"),
-        }).catch((e) => ({ ok: false, text: "", exitCode: null, timedOut: false, error: e.message }));
+            sleep: o.sleep,
+            onSwitch: (_from, to, kind) => {
+                if (o.signal?.aborted)
+                    return;
+                say(`  ${agent.name} falling back to ${to.model ? `${to.runtime}/${to.model}` : to.runtime} (${kind ?? "unknown error"})`);
+            },
+            invoke: (c) => invoke({
+                project,
+                agent: agentForCandidate(agent, c),
+                workDir: callDir,
+                systemPrompt: buildSoloSystemPrompt(project, agent),
+                userPrompt: buildCallUserPrompt(agent, o.task),
+                timeoutSec: project.dispatcher.wake_timeout_sec,
+                signal: o.signal,
+                logDir: logDirFor(c),
+            }).catch((e) => ({ ok: false, text: "", exitCode: null, timedOut: false, error: e.message })),
+        });
+        const result = must(outcome.result, "the call's result");
+        const tried = chain ? outcome.tried : undefined;
         const reverted = guard.check([agent]).map((v) => v.file);
         for (const f of reverted)
             say(`warn   ${agent.name} changed ${f}; it was put back.`);
         const cancelled = !!result.cancelled;
         const error = result.ok ? undefined : cancelled ? "cancelled" : (result.error ?? (result.timedOut ? "timed out" : "failed"));
-        atomicWrite(path.join(callDir, "result.md"), result.ok ? `${result.text.trimEnd()}\n` : `# Call ${cancelled ? "cancelled" : "failed"}\n\n${error}\n`);
-        return { callId, callDir, ok: result.ok, cancelled, text: result.ok ? result.text : "", error, reverted };
+        const triedList = !result.ok && !cancelled && tried?.length ? `\nTried:\n${tried.map((t) => `- ${t.model ? `${t.runtime}/${t.model}` : t.runtime} (${t.kind ?? "unknown"}): ${t.error ?? "failed"}`).join("\n")}\n` : "";
+        atomicWrite(path.join(callDir, "result.md"), result.ok ? `${result.text.trimEnd()}\n` : `# Call ${cancelled ? "cancelled" : "failed"}\n\n${error}\n${triedList}`);
+        return { callId, callDir, ok: result.ok, cancelled, text: result.ok ? result.text : "", error, ...(tried ? { tried } : {}), reverted };
     }
     finally {
         lease.release();

package/dist/config.d.ts

@@ -1,6 +1,6 @@
 import { type ProjectPaths } from "./paths.js";
 import type { AgentWorkspace } from "./worktree.js";
-import { type DispatcherSettings, type Effort, type Runtime, type WebLevel } from "./schema.js";
+import { type DispatcherSettings, type Effort, type FallbackEntry, type Runtime, type WebLevel } from "./schema.js";
 export declare class ConfigError extends Error {
 }
 export type Source = "global" | "project" | "default" | "model";
@@ -22,6 +22,15 @@ export interface ResolvedAgent {
     canAskUser: boolean;
     /** Web access for this agent; undefined = not configured, so the runtime keeps its own default. */
     allowWeb?: WebLevel;
+    /** Ordered failover chain (runtime and model filled in); empty = no fallback. */
+    fallback: FallbackEntry[];
+    /** True when the chain came from `dispatcher.fallback` rather than the agent's own setting. */
+    fallbackShared: boolean;
+    /** Entries of the chain that could not be resolved (left out of `fallback`); `validate` reports them. */
+    fallbackInvalid: {
+        index: number;
+        reason: "empty" | "no-runtime";
+    }[];
     /** Where each field's value came from (for `validate` output). */
     sources: Record<string, Source>;
 }
@@ -65,6 +74,11 @@ export declare function loadGlobal(home: string): {
         can_edit_agent_md?: boolean | undefined;
         can_ask_user?: boolean | undefined;
         allow_web?: "fetch" | "none" | "search" | undefined;
+        fallback?: {
+            runtime?: "claude-code" | "codex" | undefined;
+            model?: string | undefined;
+            effort?: "high" | "low" | "max" | "medium" | "minimal" | "xhigh" | undefined;
+        }[] | undefined;
         owns?: unknown;
     }>;
 };
@@ -82,6 +96,12 @@ export declare function loadProjectRaw(home: string, name: string): {
         strict?: boolean | undefined;
         workspace_mode?: unknown;
         log_max_bytes?: number | undefined;
+        fallback?: {
+            runtime?: "claude-code" | "codex" | undefined;
+            model?: string | undefined;
+            effort?: "high" | "low" | "max" | "medium" | "minimal" | "xhigh" | undefined;
+        }[] | undefined;
+        fallback_cooldown_sec?: number | undefined;
     };
     agents: Record<string, {
         runtime?: "claude-code" | "codex" | undefined;
@@ -97,6 +117,11 @@ export declare function loadProjectRaw(home: string, name: string): {
         can_edit_agent_md?: boolean | undefined;
         can_ask_user?: boolean | undefined;
         allow_web?: "fetch" | "none" | "search" | undefined;
+        fallback?: {
+            runtime?: "claude-code" | "codex" | undefined;
+            model?: string | undefined;
+            effort?: "high" | "low" | "max" | "medium" | "minimal" | "xhigh" | undefined;
+        }[] | undefined;
         owns?: unknown;
     }>;
 };

package/dist/config.js

@@ -58,7 +58,7 @@ export function resolveProjectFrom(home, name, g, p) {
     const paths = projectPaths(home, name);
     const hp = homePaths(home);
     const lead = p.team.lead;
-    const { max_parallel: _mp, max_concurrent_runs: _mc, workspace_mode: _wm, ...liveDispatcher } = p.dispatcher;
+    const { max_parallel: _mp, max_concurrent_runs: _mc, workspace_mode: _wm, fallback: dispatcherFallback, ...liveDispatcher } = p.dispatcher;
     const dispatcher = { ...DISPATCHER_DEFAULTS, ...stripUndef(liveDispatcher) };
     const agents = {};
     for (const agentName of Object.keys(p.agents)) {
@@ -129,6 +129,21 @@ export function resolveProjectFrom(home, name, g, p) {
                 break;
             }
         }
+        // Precedence: the agent's own chain (project > global), then dispatcher.fallback, then none. `[]` is a real value: no fallback.
+        let rawFallback = pick("fallback");
+        let fallbackShared = false;
+        if (rawFallback === undefined) {
+            fallbackShared = dispatcherFallback !== undefined;
+            if (dispatcherFallback !== undefined) {
+                rawFallback = dispatcherFallback;
+                sources.fallback = "project";
+            }
+            else {
+                rawFallback = [];
+                sources.fallback = "default";
+            }
+        }
+        const { entries: fallback, invalid: fallbackInvalid } = resolveFallback(rawFallback, runtime);
         const isLead = agentName === lead;
         const resume = pick("resume");
         const canMessage = pick("can_message");
@@ -156,6 +171,9 @@ export function resolveProjectFrom(home, name, g, p) {
             canEditAgentMd: canEdit ?? isLead,
             canAskUser: canAsk ?? isLead,
             allowWeb,
+            fallback,
+            fallbackShared,
+            fallbackInvalid,
             sources,
         };
     }
@@ -170,6 +188,24 @@ export function resolveProjectFrom(home, name, g, p) {
         ignoredSettings: collectIgnored(hp.globalConfig, g, paths.config, p),
     };
 }
+/** Fill each entry's runtime: `inferRuntime(model)`, else the agent's own. Entries with nothing to go on are set aside, not guessed. */
+function resolveFallback(raw, agentRuntime) {
+    const entries = [];
+    const invalid = [];
+    for (const [index, e] of raw.entries()) {
+        if (e.runtime === undefined && !e.model) {
+            invalid.push({ index, reason: "empty" });
+            continue;
+        }
+        const runtime = e.runtime ?? inferRuntime(e.model) ?? agentRuntime;
+        if (!runtime) {
+            invalid.push({ index, reason: "no-runtime" });
+            continue;
+        }
+        entries.push({ runtime, model: e.model ?? "", ...(e.effort ? { effort: e.effort } : {}) });
+    }
+    return { entries, invalid };
+}
 /** The removed keys present in the global and project files, by full path, per file (empty files omitted). */
 function collectIgnored(globalFile, g, projectFile, p) {
     const out = [];
@@ -223,7 +259,7 @@ export function findProjectForCwd(home, cwd) {
     }
     return best?.name;
 }
-const AGENT_FIELDS = ["runtime", "model", "effort", "agent_md", "memory.global", "memory.project", "resume", "can_message", "can_edit_agent_md", "can_ask_user", "allow_web"];
+const AGENT_FIELDS = ["runtime", "model", "effort", "agent_md", "memory.global", "memory.project", "resume", "can_message", "can_edit_agent_md", "can_ask_user", "allow_web", "fallback"];
 /** The resolved project plus, for every setting, the file and key it was taken from (or "default"). */
 export function resolveProjectWithSources(home, name) {
     const project = resolveProject(home, name);
@@ -234,7 +270,10 @@ export function resolveProjectWithSources(home, name) {
         dir: { file: projectFile, key: "dir" },
         "team.lead": { file: projectFile, key: "team.lead" },
     };
+    const anyFallback = Object.values(project.agents).some((a) => a.fallback.length > 0);
     for (const k of Object.keys(DISPATCHER_DEFAULTS)) {
+        if (k === "fallback_cooldown_sec" && !anyFallback)
+            continue;
         sources[`dispatcher.${k}`] = raw.dispatcher[k] !== undefined ? { file: projectFile, key: `dispatcher.${k}` } : { default: true };
     }
     for (const a of Object.values(project.agents)) {
@@ -250,6 +289,8 @@ export function resolveProjectWithSources(home, name) {
             const src = a.sources[f];
             if (src === undefined)
                 continue; // not set anywhere (e.g. no effort)
+            if (f === "fallback" && a.fallback.length === 0)
+                continue;
             if (src === "model")
                 sources[`agents.${a.name}.${f}`] = (() => {
                     const m = at(a.sources.model, "model");
@@ -258,6 +299,9 @@ export function resolveProjectWithSources(home, name) {
             // A project-level AGENT.md found by convention is not a setting in project.yaml.
             else if (f === "agent_md" && src === "project" && raw.agents[a.name]?.agent_md === undefined)
                 sources[`agents.${a.name}.${f}`] = { default: true };
+            // A chain inherited from dispatcher.fallback lives under that key, not under the agent.
+            else if (f === "fallback" && src === "project" && raw.agents[a.name]?.fallback === undefined)
+                sources[`agents.${a.name}.${f}`] = { file: projectFile, key: "dispatcher.fallback" };
             else
                 sources[`agents.${a.name}.${f}`] = at(src, f);
         }
@@ -267,8 +311,12 @@ export function resolveProjectWithSources(home, name) {
 /** Every effective setting under the same keys as `resolveProjectWithSources` reports sources for. */
 export function flattenResolved(project) {
     const v = { dir: project.dir, "team.lead": project.lead };
-    for (const [k, val] of Object.entries(project.dispatcher))
+    const anyFallback = Object.values(project.agents).some((a) => a.fallback.length > 0);
+    for (const [k, val] of Object.entries(project.dispatcher)) {
+        if (k === "fallback_cooldown_sec" && !anyFallback)
+            continue; // keep `doctor --resolved` unchanged without fallback
         v[`dispatcher.${k}`] = val;
+    }
     for (const a of Object.values(project.agents)) {
         const p = `agents.${a.name}`;
         v[`${p}.runtime`] = a.runtime;
@@ -282,6 +330,8 @@ export function flattenResolved(project) {
         v[`${p}.can_edit_agent_md`] = a.canEditAgentMd;
         v[`${p}.can_ask_user`] = a.canAskUser;
         v[`${p}.allow_web`] = a.allowWeb;
+        if (a.fallback.length)
+            v[`${p}.fallback`] = a.fallback;
     }
     return v;
 }

package/dist/doctor.d.ts

@@ -35,7 +35,7 @@ export interface DoctorReport {
     checks: DoctorCheck[];
     runtimes: RuntimeCapabilities[];
 }
-export declare function probeProjectRuntimes(project: ResolvedProject, opts?: ProbeOptions): Promise<RuntimeCapabilities[]>;
+export declare function probeProjectRuntimes(project: ResolvedProject, opts?: ProbeOptions, withFallback?: boolean): Promise<RuntimeCapabilities[]>;
 /** Before a run starts: what is explicitly unsupported (refuse) and what is merely unknown (warn). */
 export declare function preflightRuntimes(project: ResolvedProject, opts?: ProbeOptions): Promise<{
     errors: string[];

package/dist/doctor.js

@@ -76,7 +76,13 @@ function judgeRuntimes(project, caps) {
         const cmd = BINARY[c.runtime];
         const users = Object.values(project.agents).filter((a) => a.runtime === c.runtime);
         if (c.binary === "missing") {
-            checks.push({ level: "error", subject: c.runtime, message: `${cmd} not found on PATH (needed by ${users.map((a) => a.name).join(", ")}).` });
+            if (!users.length) {
+                // Only a fallback chain uses it: a backup that is not installed must not stop a run that works until the primary fails.
+                const backups = Object.values(project.agents).filter((a) => a.fallback.some((f) => f.runtime === c.runtime));
+                checks.push({ level: "warn", subject: c.runtime, message: `${cmd} not found on PATH (it is a fallback for ${backups.map((a) => a.name).join(", ")}).` });
+            }
+            else
+                checks.push({ level: "error", subject: c.runtime, message: `${cmd} not found on PATH (needed by ${users.map((a) => a.name).join(", ")}).` });
             continue;
         }
         checks.push({ level: "ok", subject: c.runtime, message: `${cmd} ${c.version ?? "(version unknown)"}` });
@@ -96,9 +102,12 @@ function judgeRuntimes(project, caps) {
     }
     return checks;
 }
-const runtimesUsed = (project) => [...new Set(Object.values(project.agents).map((a) => a.runtime).filter((r) => !!r))];
-export async function probeProjectRuntimes(project, opts = {}) {
-    return Promise.all(runtimesUsed(project).map((r) => probeRuntime(r, opts)));
+/** Runtimes of the agents themselves; with `withFallback`, also those that only a fallback chain uses. */
+const runtimesUsed = (project, withFallback) => [
+    ...new Set(Object.values(project.agents).flatMap((a) => [a.runtime, ...(withFallback ? a.fallback.map((f) => f.runtime) : [])]).filter((r) => !!r)),
+];
+export async function probeProjectRuntimes(project, opts = {}, withFallback = false) {
+    return Promise.all(runtimesUsed(project, withFallback).map((r) => probeRuntime(r, opts)));
 }
 /** Before a run starts: what is explicitly unsupported (refuse) and what is merely unknown (warn). */
 export async function preflightRuntimes(project, opts = {}) {
@@ -160,7 +169,7 @@ export async function diagnoseProject(project, opts = {}) {
     }
     for (const a of tidyAdvice(project))
         checks.push({ level: "info", subject: "memory", message: `${a.agent}: ${a.reason}. Consider: agent-lyceum tidy -p ${project.name} --agent ${a.agent} (doctor only suggests; it never tidies).` });
-    const runtimes = await probeProjectRuntimes(project, opts);
+    const runtimes = await probeProjectRuntimes(project, opts, true);
     checks.push(...judgeRuntimes(project, runtimes));
     checks.push({ level: "info", subject: "login", message: "Login status is unknown: agent-lyceum does not read credentials, and the CLIs offer no read-only login check it can rely on." });
     return { project: project.name, ok: !checks.some((c) => c.level === "error"), checks, runtimes };

package/dist/fallback.d.ts

@@ -0,0 +1,111 @@
+import type { ResolvedAgent } from "./config.js";
+import type { Effort, ErrorKind, Runtime } from "./schema.js";
+/** One model a wake may run on: the agent's own (`primary`) or a link of its fallback chain. */
+export interface Candidate {
+    runtime: Runtime;
+    /** Unset = the runtime's own default model. */
+    model?: string;
+    effort?: Effort;
+    primary: boolean;
+    /** `<runtime>/<model>`; the cooldown and session key. */
+    key: string;
+}
+/**
+ * The primary model followed by the agent's fallback chain, in order. An entry with the same key as the primary or as an
+ * earlier entry is dropped: a chain shared through `dispatcher.fallback` may list the agent's own primary (spec 20.12).
+ */
+export declare function candidatesFor(agent: ResolvedAgent): Candidate[];
+/**
+ * The agent as it runs on candidate `c`: itself for the primary; for a backup, the same agent on the backup's runtime, model
+ * and effort, at the primary's effective web level (spec 20.12). A set `allow_web` carries over. Unset, claude-code has no web
+ * tools while codex keeps its own default, which may search: a codex backup of such an agent gets `none`.
+ */
+export declare function agentForCandidate(agent: ResolvedAgent, c: Candidate): ResolvedAgent;
+/** Models that failed with `rate_limit`/`quota`, and until when (epoch ms) wakes skip them. Shared by a run, kept in `state.json`. */
+export declare class Cooldowns {
+    private table;
+    /** Cool `key` down for `sec` seconds from `now`; never shortens a longer cooldown already in place. */
+    mark(key: string, kind: ErrorKind, now: number, sec: number): void;
+    /** Milliseconds of cooldown left for `key` at `now`; 0 = none. */
+    active(key: string, now: number): number;
+    toJSON(): Record<string, {
+        until: string;
+        kind: ErrorKind;
+    }>;
+    /** Rebuild from `toJSON()` output; a missing table (older `state.json`) is an empty one. */
+    static from(json?: Record<string, {
+        until: string;
+        kind: ErrorKind;
+    }>): Cooldowns;
+}
+/** The candidates for one wake: the chain minus those cooling down, or the whole chain when every one is (something must be tried). */
+export declare function planAttempts(agent: ResolvedAgent, cooldowns: Cooldowns, now: number): Candidate[];
+export type Step = "retry-same" | "next-candidate" | "stop";
+/**
+ * What to do after a failed call (spec 20.2 decisions 2 and 5). `attemptsOnCurrent` counts the calls made on the current
+ * candidate, the failed one included; each candidate gets `retry` retries. `legacy` (the agent has no fallback chain)
+ * keeps the old loop: every kind is retried `retry` times, then the wake fails.
+ */
+export declare function nextStep(kind: ErrorKind | undefined, attemptsOnCurrent: number, retry: number, hasNext: boolean, legacy: boolean): Step;
+/** Wait before the `n`th retry (1-based) on the same candidate: 5s, 15s, 45s, then 60s. */
+export declare function backoffMs(n: number): number;
+/** `setTimeout` as a promise that resolves early (never rejects) when `signal` aborts. */
+export declare function defaultSleep(ms: number, signal?: AbortSignal): Promise<void>;
+/** What the driver needs to know about a call's result. */
+export interface AttemptResult {
+    ok: boolean;
+    kind?: ErrorKind;
+    cancelled?: boolean;
+    error?: string;
+}
+export interface AttemptCtx<R> {
+    /** Calls made so far in this wake, across candidates (0 = the first). */
+    attempt: number;
+    /** Calls made so far on this candidate; restarts at 0 on a switch. */
+    candidateAttempt: number;
+    /** The previous call's failed result, for a retry prompt. */
+    previous?: R;
+    /** Set on the first call after switching: the candidate given up on. */
+    switchedFrom?: Candidate;
+}
+/** A failed call, in order, for `failure.tried`. */
+export interface Tried {
+    runtime: Runtime;
+    model?: string;
+    kind?: ErrorKind;
+    error?: string;
+}
+export interface RunWithFallbackOptions<R extends AttemptResult> {
+    /** From `planAttempts`; tried in order. */
+    candidates: Candidate[];
+    /** The agent has no fallback chain (see `nextStep`): no backoff, no cooldowns. */
+    legacy: boolean;
+    /** Retries per candidate (`dispatcher.retry`). */
+    retry: number;
+    /** Marked on `rate_limit`/`quota` failures. */
+    cooldowns: Cooldowns;
+    cooldownSec: number;
+    invoke(candidate: Candidate, ctx: AttemptCtx<R>): Promise<R>;
+    /** Runs before each call; "stop" ends the loop without calling (e.g. the round limit). */
+    beforeAttempt?(candidate: Candidate, ctx: AttemptCtx<R>): "stop" | undefined;
+    /** Runs after each call, awaited before the next decision. */
+    afterAttempt?(candidate: Candidate, result: R, ctx: AttemptCtx<R>): void | Promise<void>;
+    onSwitch?(from: Candidate, to: Candidate, kind: ErrorKind | undefined, result: R): void;
+    sleep?(ms: number, signal?: AbortSignal): Promise<void>;
+    now?(): number;
+    signal?: AbortSignal;
+}
+export interface FallbackOutcome<R> {
+    /** The last call's result; undefined only when stopped before the first call. */
+    result: R | undefined;
+    tried: Tried[];
+    /** The candidate of the last call (or the first one, when none was made). */
+    used: Candidate;
+    /** Why the loop ended without a final verdict from a call: `beforeAttempt` said stop, or the signal aborted during a backoff. */
+    stopped?: "beforeAttempt" | "aborted";
+}
+/**
+ * The one retry/fallback loop shared by `RunSession.wake` and `call` (spec 20.2 decision 9): call each candidate,
+ * retry it or move on as `nextStep` says, back off between retries. Success and cancellation end the loop as they are.
+ */
+export declare function runWithFallback<R extends AttemptResult>(o: RunWithFallbackOptions<R>): Promise<FallbackOutcome<R>>;