agent-lyceum 0.17.3 → 0.19.0

package/README.md

@@ -10,7 +10,8 @@ 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, and each can be limited to the paths it owns.
+- **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.
@@ -39,7 +40,7 @@ Latest unreleased code: `npx github:gogogohuang/agent-lyceum <command>`.
 3. Agents reply by writing mail to their own `outbox/`; the dispatcher checks `can_message` and delivers it.
 4. The run ends when the lead sends `done`.
 
-Its own data (config, mailboxes, logs, memory, worktrees) lives in `~/agent-lyceum-config/`, not in your repo. Agents edit your repo directly, or in git worktrees when running in parallel. agent-lyceum never merges. More: [How a run works](docs/how-it-works.md), [Configuration](docs/configuration.md).
+Its own data (config, mailboxes, logs, memory, worktrees) lives in `~/agent-lyceum-config/`, not in your repo. Concurrency needs no configuration. In a git repo with a commit, every run works in its own git worktree and ends on its own branch (`agent-lyceum/<run>/…`), members with pending mail wake in parallel, and any number of runs can be active at once; the result is not written into your working tree, so use `git merge <branch>` or `open_pr`, and note that a run starts from `HEAD` and does not see your uncommitted edits. In a non-git folder, a repo with no commit, or a repo using reftable, the run works directly in the folder, one agent at a time (an info line says why), and only one such run can be active. agent-lyceum never merges. Upgrading from a version with `owns`, `max_parallel`, `max_concurrent_runs` or `workspace_mode`: see [Upgrading](docs/upgrading-run-v2.md). More: [How a run works](docs/how-it-works.md), [Configuration](docs/configuration.md).
 
 ## Commands
 
@@ -68,7 +69,7 @@ dir: ~/code/web-app
 team: { lead: lead }
 agents:
   lead:      { can_message: all, can_edit_agent_md: true }
-  fe-member: { runtime: codex, can_message: [lead], owns: ["src/web/**"] }
+  fe-member: { runtime: codex, can_message: [lead] }
   pm:        { can_message: [lead], allow_web: fetch }
 ```
 

package/README.zh-TW.md

@@ -10,7 +10,8 @@
 
 - **角色不會跑掉。** 每個 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 可在同一個團隊，並各自限制可寫的路徑。
+- **混用 runtime。** Claude Code 與 Codex agent 可在同一個團隊。
+- **備用模型。** 模型被限流、額度用完或連不上時，run 可以改用備用的模型或 runtime 繼續，而不是直接停下。見[設定](docs/configuration.zh-TW.md#備援模型)。
 - **沒有黑箱。** agent 透過純檔案信箱溝通，每則訊息、決策與記憶都是你能讀、能 grep、能 diff 的檔案；dispatcher 不會替你 merge。
 
 **不適合**小而單次的修改：單一 Claude Code 或 Codex session 更快更省。任務大到值得拆分、review 或平行執行時，再用團隊。
@@ -39,7 +40,7 @@ npx agent-lyceum status
 3. agent 把回信寫進自己的 `outbox/`，dispatcher 檢查 `can_message` 後投遞。
 4. lead 寄出 `done` 時，run 結束。
 
-工具自己的資料（設定、信箱、log、記憶、worktree）放在 `~/agent-lyceum-config/`，不放進你的 repo。agent 直接修改你的 repo；平行執行時則在各自的 git worktree 修改。agent-lyceum 不會幫你合併。詳見[一次執行如何運作](docs/how-it-works.zh-TW.md)、[設定](docs/configuration.zh-TW.md)。
+工具自己的資料（設定、信箱、log、記憶、worktree）放在 `~/agent-lyceum-config/`，不放進你的 repo。並行不需要任何設定。在有 commit 的 git repo 裡，每個 run 都在自己的 git worktree 工作，並結束在自己的 branch（`agent-lyceum/<run>/…`）；有待處理信件的成員會平行喚醒，同時也可有任意多個 run；結果不會寫進你的工作目錄，請用 `git merge <branch>` 或 `open_pr`，且 run 從 `HEAD` 起跑，看不到你未提交的修改。在非 git 資料夾、沒有 commit 的 repo 或使用 reftable 的 repo，run 直接在該資料夾工作、一次只跑一個 agent（會有一行說明原因），且同時只能有一個這樣的 run。agent-lyceum 不會幫你合併。從有 `owns`、`max_parallel`、`max_concurrent_runs` 或 `workspace_mode` 的版本升級：見[升級](docs/upgrading-run-v2.md)。詳見[一次執行如何運作](docs/how-it-works.zh-TW.md)、[設定](docs/configuration.zh-TW.md)。
 
 ## 指令
 
@@ -68,7 +69,7 @@ dir: ~/code/web-app
 team: { lead: lead }
 agents:
   lead:      { can_message: all, can_edit_agent_md: true }
-  fe-member: { runtime: codex, can_message: [lead], owns: ["src/web/**"] }
+  fe-member: { runtime: codex, can_message: [lead] }
   pm:        { can_message: [lead], allow_web: fetch }
 ```
 

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

@@ -27,13 +27,7 @@ export function buildClaudeSettings(project, agent) {
         allow.push("WebSearch");
     if (agent.allowWeb === "fetch")
         allow.push("WebFetch");
-    if (pol.restrictRepoToOwns) {
-        for (const g of pol.owns)
-            allow.push(rule("Edit", path.join(repo, g)));
-    }
-    else {
-        allow.push(rule("Edit", `${repo}/**`));
-    }
+    allow.push(rule("Edit", `${repo}/**`));
     for (const d of pol.allowDirs)
         allow.push(rule("Edit", `${d}/**`));
     for (const f of pol.allowFiles)
@@ -94,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,
@@ -104,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";
@@ -33,7 +34,6 @@ export function resolveCallAgent(home, name) {
         canMessage: [],
         canAskUser: false,
         canEditAgentMd: false,
-        owns: [],
     };
 }
 /** The made-up project a call runs in: the working directory is its repo, and every other path is inside the call's own folder. */
@@ -54,7 +54,7 @@ export function callProject(home, agent, dir, callDir) {
         name: CALL_PROJECT,
         dir,
         lead: agent.name,
-        dispatcher: { ...DISPATCHER_DEFAULTS, max_parallel: 1, workspace_mode: "shared" },
+        dispatcher: DISPATCHER_DEFAULTS,
         agents: { [agent.name]: agent },
         paths,
         solo: "call",
@@ -138,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/cli.js

@@ -11,6 +11,7 @@ import { RESULT_FILE, runTeam } from "./dispatcher.js";
 import { executeRunCleanup, planRunCleanup } from "./run-cleanup.js";
 import { diagnoseProject, formatDoctor, preflightRuntimes } from "./doctor.js";
 import { acquireProjectLock, forceUnlock, inspectRunLock, listRunLocks, listUnreadableRunLocks, LOCK_FILE, lockHolderAlive } from "./project-lock.js";
+import { planWorkspace } from "./worktree.js";
 import { loadRunState, newRunId, outcomeOf, resolveRun, roundLimit, roundsLabel, runLabel, slugify, uniqueName } from "./run-store.js";
 import { failureGuide } from "./run-outcome.js";
 import { exitCodeForOutcome, RUNTIMES } from "./schema.js";
@@ -132,10 +133,10 @@ function findRun(pr, query) {
     const list = r.candidates.map((c) => `  ${c.state.name ?? "(no name)"}  ${c.state.run_id}  ${c.state.task_summary}`).join("\n");
     return fail(`"${query}" matches several runs:\n${list}\nGive more of the name or id.`);
 }
-/** Take the lock of one run, or exit with the reason. `ignoreLimit`: the caller does not start a run (e.g. `clear`). `exclusive`: it needs the whole project (memory tidy). */
+/** Take the lock of one run, or exit with the reason. `checkout`: the run works in the project checkout, so only one may be active. `exclusive`: it needs the whole project (memory tidy). */
 function takeLock(pr, runId, opts = {}) {
     try {
-        return acquireProjectLock(pr.paths.root, runId, { maxConcurrent: opts.ignoreLimit ? Number.MAX_SAFE_INTEGER : pr.dispatcher.max_concurrent_runs, exclusive: opts.exclusive });
+        return acquireProjectLock(pr.paths.root, runId, { checkout: opts.checkout, exclusive: opts.exclusive, dir: pr.dir, reason: opts.reason });
     }
     catch (e) {
         return fail(e.message);
@@ -197,17 +198,23 @@ function reportRun(summary, runDir) {
 const firstLine = (t) => t.trim().split("\n")[0].trim();
 /** Take the lock and continue a run; the lock is released when it stops (also when it stops because it waits for answers). */
 async function continueRun(pr, dir, runId, followup) {
-    const lease = takeLock(pr, runId);
+    const planned = loadRunState(dir);
+    // Where the run works is decided (from its state) before the lock is taken, and handed to the session as is.
+    const plan = planWorkspace(pr, planned);
+    const lease = takeLock(pr, runId, { checkout: !plan.leadWorktree, reason: "it was started without its own worktree" });
     const cancel = cancelOnSignals();
     try {
-        console.log(`Project ${pr.name} — repo ${pr.dir}`);
+        // Read the state again under the lock: another process may have changed it while we were checking.
         const state = loadRunState(dir);
+        if (state.lead_workspace !== planned.lead_workspace || state.workspace_mode !== planned.workspace_mode) {
+            throw new Error(`Run ${runId} changed while it was starting (where it works was ${planned.lead_workspace ? "its own worktree" : planned.workspace_mode ?? "unset"}, now ${state.lead_workspace ? "its own worktree" : state.workspace_mode ?? "unset"}); try again.`);
+        }
+        console.log(`Project ${pr.name} — repo ${pr.dir}`);
         if (followup)
             console.log(`Reopening run ${runLabel(state)} (follow-up ${(state.reopened?.length ?? 0) + 1}): ${firstLine(followup.text)}`);
         else
             console.log(`Resuming run ${runLabel(state)} (${state.end_reason ?? "interrupted"}) at round ${roundsLabel(state.rounds, roundLimit(state, pr.dispatcher.max_rounds))}: ${state.task_summary}`);
-        // Read the state again under the lock: another process may have changed it while we were checking.
-        return await runTeam({ project: pr, resume: state, runDir: dir, signal: cancel.signal, followup });
+        return await runTeam({ project: pr, resume: state, plan, runDir: dir, signal: cancel.signal, followup });
     }
     finally {
         cancel.dispose();
@@ -289,7 +296,8 @@ program
         }
         const runId = newRunId();
         const runDir = path.join(pr.paths.runs, runId);
-        const lease = takeLock(pr, runId);
+        const plan = planWorkspace(pr);
+        const lease = takeLock(pr, runId, { checkout: !plan.leadWorktree, reason: plan.reason });
         let summary;
         const cancel = cancelOnSignals();
         try {
@@ -297,7 +305,7 @@ program
             console.log(`Project ${pr.name} — repo ${pr.dir}${opts.agent ? ` — solo: ${opts.agent}` : ""}`);
             console.log(`Task: ${prepared.source === "file" ? `file ${prepared.sourcePath}` : "text"} (${prepared.bytes} bytes${prepared.inline ? "" : ", passed by reference"})`);
             const name = opts.name ?? uniqueName(slugify(taskMessageBody(prepared).subject), taken);
-            summary = await runTeam({ project: pr, name, task: prepared, runDir, soloAgent: opts.agent, signal: cancel.signal });
+            summary = await runTeam({ project: pr, name, plan, task: prepared, runDir, soloAgent: opts.agent, signal: cancel.signal });
         }
         finally {
             cancel.dispose();
@@ -514,7 +522,7 @@ program
                 refuse(plan);
             return;
         }
-        const lease = takeLock(pr, full, { ignoreLimit: true });
+        const lease = takeLock(pr, full, { checkout: false });
         try {
             const plan = planRunCleanup(pr, full, { keepWorktrees: opts.keepWorktrees });
             if (plan.refusals.length)

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,7 +22,15 @@ export interface ResolvedAgent {
     canAskUser: boolean;
     /** Web access for this agent; undefined = not configured, so the runtime keeps its own default. */
     allowWeb?: WebLevel;
-    owns: string[];
+    /** 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>;
 }
@@ -35,6 +43,11 @@ export interface ResolvedProject {
     dispatcher: DispatcherSettings;
     agents: Record<string, ResolvedAgent>;
     paths: ProjectPaths;
+    /** Removed settings still present in config files (ignored); `validate` warns once per file. */
+    ignoredSettings?: {
+        file: string;
+        keys: string[];
+    }[];
     /** Set once the project is bound to one run (see `bindRunProject`): which run, and where its mail lives. */
     run?: {
         id: string;
@@ -61,7 +74,12 @@ export declare function loadGlobal(home: string): {
         can_edit_agent_md?: boolean | undefined;
         can_ask_user?: boolean | undefined;
         allow_web?: "fetch" | "none" | "search" | undefined;
-        owns?: string[] | undefined;
+        fallback?: {
+            runtime?: "claude-code" | "codex" | undefined;
+            model?: string | undefined;
+            effort?: "high" | "low" | "max" | "medium" | "minimal" | "xhigh" | undefined;
+        }[] | undefined;
+        owns?: unknown;
     }>;
 };
 export declare function loadProjectRaw(home: string, name: string): {
@@ -71,13 +89,19 @@ export declare function loadProjectRaw(home: string, name: string): {
     };
     dispatcher: {
         max_rounds?: number | undefined;
-        max_parallel?: number | undefined;
-        max_concurrent_runs?: number | undefined;
+        max_parallel?: unknown;
+        max_concurrent_runs?: unknown;
         wake_timeout_sec?: number | undefined;
         retry?: number | undefined;
         strict?: boolean | undefined;
-        workspace_mode?: "auto" | "shared" | "worktree" | 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;
@@ -93,7 +117,12 @@ 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;
-        owns?: string[] | undefined;
+        fallback?: {
+            runtime?: "claude-code" | "codex" | undefined;
+            model?: string | undefined;
+            effort?: "high" | "low" | "max" | "medium" | "minimal" | "xhigh" | undefined;
+        }[] | undefined;
+        owns?: unknown;
     }>;
 };
 export declare function resolveProject(home: string, name: string): ResolvedProject;