agent-lyceum 0.17.3 → 0.19.0

package/dist/schema.d.ts

@@ -11,6 +11,32 @@ export declare function inferRuntime(model: string | undefined): Runtime | undef
 /** How much of the web an agent may use: nothing, search only, or search plus fetching pages. Unset leaves each runtime's own default alone. */
 export declare const WEB_LEVELS: readonly ["none", "search", "fetch"];
 export type WebLevel = (typeof WEB_LEVELS)[number];
+/** Why a wake failed, as far as the CLI's output reveals; decides whether to retry, fall back, or stop. */
+export declare const ERROR_KINDS: readonly ["rate_limit", "quota", "timeout", "network", "crash", "auth", "unknown"];
+export type ErrorKind = (typeof ERROR_KINDS)[number];
+/** One link of a fallback chain after resolution: runtime and model are filled in (model "" = the runtime's own default). */
+export interface FallbackEntry {
+    runtime: Runtime;
+    model: string;
+    effort?: Effort;
+}
+/** A fallback entry as written in a file: `runtime` may be omitted (inferred from `model`, else the agent's). */
+export declare const FallbackEntryPartial: z.ZodObject<{
+    runtime: z.ZodOptional<z.ZodEnum<{
+        "claude-code": "claude-code";
+        codex: "codex";
+    }>>;
+    model: z.ZodOptional<z.ZodString>;
+    effort: z.ZodOptional<z.ZodEnum<{
+        high: "high";
+        low: "low";
+        max: "max";
+        medium: "medium";
+        minimal: "minimal";
+        xhigh: "xhigh";
+    }>>;
+}, z.core.$strict>;
+export type FallbackEntryPartialT = z.infer<typeof FallbackEntryPartial>;
 export declare const AgentPartial: z.ZodObject<{
     runtime: z.ZodOptional<z.ZodEnum<{
         "claude-code": "claude-code";
@@ -39,23 +65,53 @@ export declare const AgentPartial: z.ZodObject<{
         none: "none";
         search: "search";
     }>>;
-    owns: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    fallback: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        runtime: z.ZodOptional<z.ZodEnum<{
+            "claude-code": "claude-code";
+            codex: "codex";
+        }>>;
+        model: z.ZodOptional<z.ZodString>;
+        effort: z.ZodOptional<z.ZodEnum<{
+            high: "high";
+            low: "low";
+            max: "max";
+            medium: "medium";
+            minimal: "minimal";
+            xhigh: "xhigh";
+        }>>;
+    }, z.core.$strict>>>;
+    owns: z.ZodOptional<z.ZodUnknown>;
 }, z.core.$strict>;
 export type AgentPartialT = z.infer<typeof AgentPartial>;
 export declare const DispatcherPartial: z.ZodObject<{
     max_rounds: z.ZodOptional<z.ZodNumber>;
-    max_parallel: z.ZodOptional<z.ZodNumber>;
-    max_concurrent_runs: z.ZodOptional<z.ZodNumber>;
+    max_parallel: z.ZodOptional<z.ZodUnknown>;
+    max_concurrent_runs: z.ZodOptional<z.ZodUnknown>;
     wake_timeout_sec: z.ZodOptional<z.ZodNumber>;
     retry: z.ZodOptional<z.ZodNumber>;
     strict: z.ZodOptional<z.ZodBoolean>;
-    workspace_mode: z.ZodOptional<z.ZodEnum<{
-        auto: "auto";
-        shared: "shared";
-        worktree: "worktree";
-    }>>;
+    workspace_mode: z.ZodOptional<z.ZodUnknown>;
     log_max_bytes: z.ZodOptional<z.ZodNumber>;
+    fallback: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        runtime: z.ZodOptional<z.ZodEnum<{
+            "claude-code": "claude-code";
+            codex: "codex";
+        }>>;
+        model: z.ZodOptional<z.ZodString>;
+        effort: z.ZodOptional<z.ZodEnum<{
+            high: "high";
+            low: "low";
+            max: "max";
+            medium: "medium";
+            minimal: "minimal";
+            xhigh: "xhigh";
+        }>>;
+    }, z.core.$strict>>>;
+    fallback_cooldown_sec: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strict>;
+/** Settings that no longer exist; files that still carry them load, and `validate` warns. */
+export declare const REMOVED_DISPATCHER_KEYS: readonly ["max_parallel", "max_concurrent_runs", "workspace_mode"];
+export declare const REMOVED_AGENT_KEYS: readonly ["owns"];
 export declare const GlobalConfig: z.ZodObject<{
     agents: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
         runtime: z.ZodOptional<z.ZodEnum<{
@@ -85,7 +141,22 @@ export declare const GlobalConfig: z.ZodObject<{
             none: "none";
             search: "search";
         }>>;
-        owns: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        fallback: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            runtime: z.ZodOptional<z.ZodEnum<{
+                "claude-code": "claude-code";
+                codex: "codex";
+            }>>;
+            model: z.ZodOptional<z.ZodString>;
+            effort: z.ZodOptional<z.ZodEnum<{
+                high: "high";
+                low: "low";
+                max: "max";
+                medium: "medium";
+                minimal: "minimal";
+                xhigh: "xhigh";
+            }>>;
+        }, z.core.$strict>>>;
+        owns: z.ZodOptional<z.ZodUnknown>;
     }, z.core.$strict>>>;
 }, z.core.$strict>;
 export declare const ProjectConfig: z.ZodObject<{
@@ -95,17 +166,29 @@ export declare const ProjectConfig: z.ZodObject<{
     }, z.core.$strict>;
     dispatcher: z.ZodDefault<z.ZodObject<{
         max_rounds: z.ZodOptional<z.ZodNumber>;
-        max_parallel: z.ZodOptional<z.ZodNumber>;
-        max_concurrent_runs: z.ZodOptional<z.ZodNumber>;
+        max_parallel: z.ZodOptional<z.ZodUnknown>;
+        max_concurrent_runs: z.ZodOptional<z.ZodUnknown>;
         wake_timeout_sec: z.ZodOptional<z.ZodNumber>;
         retry: z.ZodOptional<z.ZodNumber>;
         strict: z.ZodOptional<z.ZodBoolean>;
-        workspace_mode: z.ZodOptional<z.ZodEnum<{
-            auto: "auto";
-            shared: "shared";
-            worktree: "worktree";
-        }>>;
+        workspace_mode: z.ZodOptional<z.ZodUnknown>;
         log_max_bytes: z.ZodOptional<z.ZodNumber>;
+        fallback: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            runtime: z.ZodOptional<z.ZodEnum<{
+                "claude-code": "claude-code";
+                codex: "codex";
+            }>>;
+            model: z.ZodOptional<z.ZodString>;
+            effort: z.ZodOptional<z.ZodEnum<{
+                high: "high";
+                low: "low";
+                max: "max";
+                medium: "medium";
+                minimal: "minimal";
+                xhigh: "xhigh";
+            }>>;
+        }, z.core.$strict>>>;
+        fallback_cooldown_sec: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strict>>;
     agents: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
         runtime: z.ZodOptional<z.ZodEnum<{
@@ -135,21 +218,33 @@ export declare const ProjectConfig: z.ZodObject<{
             none: "none";
             search: "search";
         }>>;
-        owns: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        fallback: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            runtime: z.ZodOptional<z.ZodEnum<{
+                "claude-code": "claude-code";
+                codex: "codex";
+            }>>;
+            model: z.ZodOptional<z.ZodString>;
+            effort: z.ZodOptional<z.ZodEnum<{
+                high: "high";
+                low: "low";
+                max: "max";
+                medium: "medium";
+                minimal: "minimal";
+                xhigh: "xhigh";
+            }>>;
+        }, z.core.$strict>>>;
+        owns: z.ZodOptional<z.ZodUnknown>;
     }, z.core.$strict>>>;
 }, z.core.$strict>;
 export interface DispatcherSettings {
     max_rounds: number;
-    max_parallel: number;
-    /** How many runs of one project may be active at once. Above 1, every run works in its own git worktree. */
-    max_concurrent_runs: number;
     wake_timeout_sec: number;
     retry: number;
     strict: boolean;
-    /** "auto": a git worktree per non-lead agent when agents can run in parallel, otherwise one shared checkout. */
-    workspace_mode: "auto" | "shared" | "worktree";
     /** log.jsonl is rotated to log.1.jsonl past this size; 0 = never. */
     log_max_bytes: number;
+    /** How long a primary that hit rate_limit/quota is skipped within a run, unless the CLI says when to come back. */
+    fallback_cooldown_sec: number;
 }
 export declare const DISPATCHER_DEFAULTS: DispatcherSettings;
 /** How a run turned out, independent of why it stopped (`EndReason`). Only "completed" means success. */

package/dist/schema.js

@@ -20,12 +20,22 @@ export function inferRuntime(model) {
 }
 /** How much of the web an agent may use: nothing, search only, or search plus fetching pages. Unset leaves each runtime's own default alone. */
 export const WEB_LEVELS = ["none", "search", "fetch"];
+/** Why a wake failed, as far as the CLI's output reveals; decides whether to retry, fall back, or stop. */
+export const ERROR_KINDS = ["rate_limit", "quota", "timeout", "network", "crash", "auth", "unknown"];
 const Memory = z
     .object({
     global: z.string().optional(),
     project: z.string().optional(),
 })
     .strict();
+/** A fallback entry as written in a file: `runtime` may be omitted (inferred from `model`, else the agent's). */
+export const FallbackEntryPartial = z
+    .object({
+    runtime: z.enum(RUNTIMES).optional(),
+    model: z.string().optional(),
+    effort: z.enum(EFFORTS).optional(),
+})
+    .strict();
 export const AgentPartial = z
     .object({
     runtime: z.enum(RUNTIMES).optional(),
@@ -38,21 +48,28 @@ export const AgentPartial = z
     can_edit_agent_md: z.boolean().optional(),
     can_ask_user: z.boolean().optional(),
     allow_web: z.enum(WEB_LEVELS).optional(),
-    owns: z.array(z.string()).optional(),
+    fallback: z.array(FallbackEntryPartial).optional(),
+    /** Removed setting: still accepted (any value) so old files load; ignored, with a warning from `validate`. */
+    owns: z.unknown().optional(),
 })
     .strict();
 export const DispatcherPartial = z
     .object({
     max_rounds: z.number().int().min(0).optional(),
-    max_parallel: z.number().int().positive().optional(),
-    max_concurrent_runs: z.number().int().positive().optional(),
+    max_parallel: z.unknown().optional(),
+    max_concurrent_runs: z.unknown().optional(),
     wake_timeout_sec: z.number().int().positive().optional(),
     retry: z.number().int().min(0).optional(),
     strict: z.boolean().optional(),
-    workspace_mode: z.enum(["auto", "shared", "worktree"]).optional(),
+    workspace_mode: z.unknown().optional(),
     log_max_bytes: z.number().int().min(0).optional(),
+    fallback: z.array(FallbackEntryPartial).optional(),
+    fallback_cooldown_sec: z.number().int().min(0).optional(),
 })
     .strict();
+/** Settings that no longer exist; files that still carry them load, and `validate` warns. */
+export const REMOVED_DISPATCHER_KEYS = ["max_parallel", "max_concurrent_runs", "workspace_mode"];
+export const REMOVED_AGENT_KEYS = ["owns"];
 export const GlobalConfig = z
     .object({
     agents: z.record(z.string(), AgentPartial).default({}),
@@ -68,13 +85,11 @@ export const ProjectConfig = z
     .strict();
 export const DISPATCHER_DEFAULTS = {
     max_rounds: 0,
-    max_parallel: 1,
-    max_concurrent_runs: 1,
     wake_timeout_sec: 600,
     retry: 2,
     strict: false,
-    workspace_mode: "auto",
     log_max_bytes: 8 * 1024 * 1024,
+    fallback_cooldown_sec: 300,
 };
 /** How a run turned out, independent of why it stopped (`EndReason`). Only "completed" means success. */
 export const RUN_OUTCOMES = ["completed", "partial", "blocked", "failed", "waiting", "cancelled"];

package/dist/solo.js

@@ -15,8 +15,7 @@ export function soloProject(project, name, hints = {}) {
         ...project,
         solo: "run",
         lead: name,
-        dispatcher: { ...project.dispatcher, max_parallel: 1, workspace_mode: "shared" },
-        agents: { ...project.agents, [name]: { ...a, canMessage: [], canAskUser: false, canEditAgentMd: false, owns: [] } },
+        agents: { ...project.agents, [name]: { ...a, canMessage: [], canAskUser: false, canEditAgentMd: false } },
     };
 }
 /** `project` with only `name` listed: what a preflight of a solo run needs to look at. */

package/dist/status.d.ts

@@ -1,4 +1,4 @@
-import { type ActiveWake, type EndReason, type RunState, type WakeRecord } from "./run-store.js";
+import { type ActiveWake, type EndReason, type RunFailure, type RunState, type WakeRecord } from "./run-store.js";
 import type { RunOutcome } from "./schema.js";
 import type { ResolvedProject } from "./config.js";
 import { type DigestSection, type Step } from "./format.js";
@@ -72,11 +72,7 @@ export interface RunReport {
     /** 0 = no limit. */
     max_rounds: number;
     /** Set when an agent kept failing and the run stopped: `resume` after fixing the cause. */
-    failure?: {
-        agent: string;
-        error?: string;
-        attempts: number;
-    };
+    failure?: RunFailure;
     output_tokens: number;
     task_source: "text" | "file";
     task_path?: string;
@@ -123,6 +119,19 @@ export interface AgentReport {
         ok: boolean;
         error?: string;
     };
+    /** Only for an agent with a fallback chain: the model it last ran on (or its own, before any wake). */
+    model?: string;
+    /** Only when the agent's latest wake ran on a backup: what it replaced and why. */
+    fallback?: {
+        from: string;
+        kind: string;
+    };
+    /** Only for an agent with a fallback chain: its models that are cooling down now (`model` is `<runtime>/<model>`). */
+    cooldowns?: {
+        model: string;
+        kind: string;
+        remaining_sec: number;
+    }[];
 }
 export interface StatusReport {
     schema_version: 1;
@@ -153,7 +162,7 @@ export declare function buildRunReport(run: {
     detail?: boolean;
 }): RunReport;
 /** The status of a project: its agents and one run (the newest running one, else the newest, or the one named by `runId`). */
-export declare function buildStatusReport(base: ResolvedProject, runId?: string): StatusReport;
+export declare function buildStatusReport(base: ResolvedProject, runId?: string, now?: number): StatusReport;
 /** Every run of the project, newest first. */
 export declare function buildTaskListReport(project: ResolvedProject): TaskListReport;
 /** Live view: summary and agent table, plus the latest run and any run still going, wake by wake. */

package/dist/status.js

@@ -3,6 +3,7 @@ import path from "node:path";
 import { askReplyPath, readAskReply } from "./ask-reply.js";
 import { RESULT_FILE } from "./dispatcher.js";
 import { bindRunProject, loadRunState, outcomeOf, roundsLabel, runLabel } from "./run-store.js";
+import { candidatesFor } from "./fallback.js";
 import { briefOf, digestOf } from "./format.js";
 import { listUnread } from "./mailbox.js";
 import { tidyAdvice } from "./memory-tidy.js";
@@ -226,8 +227,37 @@ export function buildRunReport(run, project, opts = {}) {
     };
 }
 const projectInfo = (p) => ({ name: p.name, dir: p.dir, lead: p.lead });
+/** The fallback part of an agent's report: nothing at all for an agent without a chain. */
+function fallbackView(a, state, now) {
+    if (!a.fallback.length || !a.runtime)
+        return {};
+    const lw = state?.last_wake[a.name];
+    const ran = lw?.runtime ? lw : undefined;
+    const model = ran ? ran.model : a.model;
+    const mine = (state?.wakes ?? []).filter((w) => w.agent === a.name);
+    const last = mine.at(-1);
+    let fallback;
+    if (last?.fallback_from) {
+        // The reason is on the failed wake just before: the nearest earlier wake of this agent that has a kind.
+        let kind = "unknown";
+        for (let i = mine.length - 2; i >= 0; i--) {
+            const k = mine[i].kind;
+            if (k) {
+                kind = k;
+                break;
+            }
+        }
+        fallback = { from: last.fallback_from, kind };
+    }
+    const keys = new Set(candidatesFor(a).map((c) => c.key));
+    const cooldowns = Object.entries(state?.cooldowns ?? {})
+        .filter(([k]) => keys.has(k))
+        .map(([k, v]) => ({ model: k, kind: v.kind, remaining_sec: Math.ceil((Date.parse(v.until) - now) / 1000) }))
+        .filter((c) => Number.isFinite(c.remaining_sec) && c.remaining_sec > 0);
+    return { runtime: ran?.runtime ?? a.runtime, ...(model ? { model } : {}), ...(fallback ? { fallback } : {}), ...(cooldowns.length ? { cooldowns } : {}) };
+}
 /** The status of a project: its agents and one run (the newest running one, else the newest, or the one named by `runId`). */
-export function buildStatusReport(base, runId) {
+export function buildStatusReport(base, runId, now = Date.now()) {
     let run;
     if (runId) {
         const dir = path.join(base.paths.runs, runId);
@@ -257,6 +287,7 @@ export function buildStatusReport(base, runId) {
             unread: listUnread(project, a.name).length,
             can_message: (a.canMessage === "all" ? Object.keys(project.agents) : a.canMessage).filter((n) => n !== a.name),
             last_wake: run?.state.last_wake[a.name],
+            ...fallbackView(a, run?.state, now),
         })),
         run: report,
         ...(advice.length ? { memory_advice: advice } : {}),
@@ -425,6 +456,20 @@ export function formatTaskListReport(report, color = false) {
 export function formatStatus(base, now = Date.now(), color = false) {
     return formatStatusReport(buildStatusReport(base), now, color);
 }
+const shortSec = (sec) => (sec < 60 ? `${sec}s` : `${Math.floor(sec / 60)}m${String(sec % 60).padStart(2, "0")}s`);
+/** `runtime/model`, or the runtime alone for its default model (cooldown keys end in `/` then). */
+const modelName = (key) => key.replace(/\/$/, "");
+/** Agents running on a backup and models cooling down; empty for a run without fallback. */
+function fallbackLines(agents, c) {
+    const out = [];
+    for (const a of agents) {
+        if (a.fallback)
+            out.push(`  ${c.cyan(a.name)} ${c.yellow(`備援中 fallback: ${a.fallback.kind}`)} (${modelName(`${a.runtime ?? "?"}/${a.model ?? ""}`)})`);
+        for (const k of a.cooldowns ?? [])
+            out.push(`  ${c.cyan(a.name)} ${c.yellow(`冷卻中：${modelName(k.model)} 剩 ${shortSec(k.remaining_sec)}`)}（${k.kind}）`);
+    }
+    return out;
+}
 export function formatStatusReport(report, now = Date.now(), color = false) {
     const c = paint(color);
     const run = report.run;
@@ -452,6 +497,9 @@ export function formatStatusReport(report, now = Date.now(), color = false) {
     const table = rows.map((r, ri) => r.map((_, i) => cell(r, ri, i)).join("  ").trimEnd());
     table.splice(1, 0, c.dim(w.map((n) => "-".repeat(n)).join("  ")));
     const lines = [`${c.bold("專案：")}${report.project.name}  ${c.dim(`（repo：${report.project.dir}）`)}`, "", ...summaryBlock(run, now, c), "", ...table];
+    const fb = fallbackLines(report.agents, c);
+    if (fb.length)
+        lines.push("", ...fb);
     if (run)
         lines.push("", `輸出 tokens：${tokens(run.output_tokens)}`);
     if (report.memory_advice?.length)

package/dist/validate.js

@@ -1,8 +1,7 @@
 import fs from "node:fs";
-import { enforcementFor, memoryDirs, ownsDirs } from "./policy.js";
+import { enforcementFor, memoryDirs } from "./policy.js";
 import { isInside } from "./paths.js";
 import { inferRuntime, RUNTIME_EFFORTS } from "./schema.js";
-import { isGitRepo, resolveWorkspaceMode } from "./worktree.js";
 import { must } from "./assert.js";
 export function validateProject(project) {
     const issues = [];
@@ -26,6 +25,7 @@ export function validateProject(project) {
         if (a.effort && a.runtime && !RUNTIME_EFFORTS[a.runtime].includes(a.effort)) {
             err(`Agent "${a.name}": effort "${a.effort}" is not supported by ${a.runtime} (use ${RUNTIME_EFFORTS[a.runtime].join(", ")}).`);
         }
+        validateFallback(project, a, err);
         if (!fs.existsSync(a.agentMd))
             err(`Agent "${a.name}": AGENT.md not found at ${a.agentMd}`);
         if (!a.memory.global && !a.memory.project)
@@ -55,40 +55,8 @@ export function validateProject(project) {
             }
         }
     }
-    // Parallelism requires disjoint `owns`.
-    if (project.dispatcher.max_parallel > 1) {
-        const withOwns = Object.values(project.agents).filter((a) => a.name !== project.lead);
-        for (const a of withOwns) {
-            if (a.owns.length === 0)
-                err(`max_parallel > 1 requires "owns" for agent "${a.name}".`);
-        }
-        for (let i = 0; i < withOwns.length; i++) {
-            for (let j = i + 1; j < withOwns.length; j++) {
-                const ai = must(withOwns[i], "agent");
-                const aj = must(withOwns[j], "agent");
-                for (const x of ownsDirs(project, ai)) {
-                    for (const y of ownsDirs(project, aj)) {
-                        if (isInside(x, y) || isInside(y, x)) {
-                            err(`"owns" overlap: ${ai.name} (${x}) vs ${aj.name} (${y})`);
-                        }
-                    }
-                }
-            }
-        }
-    }
-    // Parallel agents and concurrent runs each need their own checkout, which needs git.
-    const concurrent = project.dispatcher.max_concurrent_runs > 1;
-    if (concurrent && project.dispatcher.workspace_mode === "shared") {
-        err(`dispatcher.workspace_mode "shared" cannot be combined with max_concurrent_runs > 1: every run needs its own git worktree (use "auto" or "worktree").`);
-    }
-    else if (concurrent && fs.existsSync(project.dir) && !isGitRepo(project.dir)) {
-        err(`max_concurrent_runs > 1 needs ${project.dir} to be a git repository (each run works in its own git worktree). Set max_concurrent_runs: 1.`);
-    }
-    else if (project.dispatcher.workspace_mode === "shared" && project.dispatcher.max_parallel > 1) {
-        err(`dispatcher.workspace_mode "shared" cannot be combined with max_parallel > 1: parallel agents need separate git worktrees (use "auto" or "worktree").`);
-    }
-    else if (!concurrent && resolveWorkspaceMode(project.dispatcher) === "worktree" && fs.existsSync(project.dir) && !isGitRepo(project.dir)) {
-        err(`Parallel runs (worktree workspaces) need ${project.dir} to be a git repository. Run sequentially instead (max_parallel: 1, workspace_mode: auto or shared).`);
+    for (const ig of project.ignoredSettings ?? []) {
+        warn(`${ig.file}: ignoring removed setting(s) ${ig.keys.join(", ")}. Concurrency needs no configuration now: in a git repo with a commit every run and every agent gets its own worktree. Delete these lines.`);
     }
     // Context paths should live outside the repo (the tool never writes into it).
     for (const a of Object.values(project.agents)) {
@@ -108,11 +76,46 @@ export function validateProject(project) {
     }
     return { issues, enforcement, ok: !issues.some((i) => i.level === "error") };
 }
+const PARITY_FIELDS = ["memory", "agentMd", "otherContext", "shared", "repoInstructions"];
+const norm = (m) => (m ?? "").trim().toLowerCase();
+/** Load-time (fail closed) checks of one agent's fallback chain: well-formed, not a no-op, and no weaker at write-scope than the primary. */
+function validateFallback(project, a, err) {
+    for (const bad of a.fallbackInvalid) {
+        err(bad.reason === "empty"
+            ? `agent ${a.name}: fallback #${bad.index + 1} needs a model or a runtime.`
+            : `agent ${a.name}: fallback #${bad.index + 1} has no recognizable runtime (set runtime, or use a recognizable model).`);
+    }
+    const primary = a.runtime ? enforcementFor(project, a) : undefined;
+    for (const f of a.fallback) {
+        const label = `${f.runtime}/${f.model || "(default model)"}`;
+        if (f.runtime === a.runtime && norm(f.model) === norm(a.model)) {
+            // A chain shared through dispatcher.fallback may already contain this agent's primary: just skip it then.
+            if (!a.fallbackShared)
+                err(`agent ${a.name}: fallback ${label} is the same as the primary runtime and model.`);
+            continue;
+        }
+        if (f.effort && !RUNTIME_EFFORTS[f.runtime].includes(f.effort)) {
+            err(`agent ${a.name}: fallback ${label}: effort "${f.effort}" is not supported by ${f.runtime} (use ${RUNTIME_EFFORTS[f.runtime].join(", ")}).`);
+        }
+        if (!primary)
+            continue;
+        // `prompt-only` is the one level that is no enforcement at all; everything else (os, tool-rules, post-hoc) still holds the line.
+        const swapped = enforcementFor(project, { ...a, runtime: f.runtime, model: f.model || undefined, effort: f.effort });
+        for (const k of PARITY_FIELDS) {
+            const from = primary[k];
+            const to = swapped[k];
+            if (from === "n/a" || to === "n/a")
+                continue;
+            if (to === "prompt-only" && from !== "prompt-only")
+                err(`agent ${a.name}: fallback ${label} cannot enforce ${k} (${from} -> ${to})`);
+        }
+    }
+}
 export function formatEnforcement(list) {
-    const header = ["agent", "runtime", "memory", "AGENT.md", "others' ctx", "handoff", "repo CLAUDE/AGENTS", "owns"];
+    const header = ["agent", "runtime", "memory", "AGENT.md", "others' ctx", "handoff", "repo CLAUDE/AGENTS"];
     const rows = [header];
     for (const e of list)
-        rows.push([e.agent, e.runtime, e.memory, e.agentMd, e.otherContext, e.shared, e.repoInstructions, e.owns]);
+        rows.push([e.agent, e.runtime, e.memory, e.agentMd, e.otherContext, e.shared, e.repoInstructions]);
     const w = header.map((_, i) => Math.max(...rows.map((r) => (r[i] ?? "").length)));
     const lines = rows.map((r) => r.map((c, i) => c.padEnd(w[i] ?? 0)).join("  ").trimEnd());
     lines.splice(1, 0, w.map((n) => "-".repeat(n)).join("  "));

package/dist/worktree.d.ts

@@ -1,8 +1,6 @@
 import type { ResolvedProject } from "./config.js";
-import type { DispatcherSettings } from "./schema.js";
+import type { RunState } from "./run-store.js";
 export type WorkspaceMode = "shared" | "worktree";
-/** Agents share the repo, or each non-lead agent gets its own git worktree. `auto` picks worktrees as soon as agents can run in parallel; several concurrent runs always do. */
-export declare function resolveWorkspaceMode(d: Pick<DispatcherSettings, "workspace_mode" | "max_parallel"> & Partial<Pick<DispatcherSettings, "max_concurrent_runs">>): WorkspaceMode;
 export interface AgentWorkspace {
     agent: string;
     /** Root of the git worktree. */
@@ -58,11 +56,22 @@ export declare function isGitRepo(dir: string): boolean;
 export declare const toplevel: (dir: string) => string;
 /** Files in the repo with changes nobody committed (modified, staged or new and not ignored). Paths are relative to the repo root. */
 export declare function dirtyPaths(dir: string): string[];
-/** Refuse to start a worktree run when it cannot be isolated; returns nothing when it is fine. */
-export declare function assertWorktreeRunnable(project: ResolvedProject, opts: {
-    fresh: boolean;
-    concurrent?: boolean;
-}): void;
+/** Why `dir` cannot give every run and agent its own git worktree, or undefined when it can. */
+export declare function isolationBlocker(dir: string): string | undefined;
+export interface WorkspacePlan {
+    mode: WorkspaceMode;
+    /** The lead works in its own worktree (isolation mode); otherwise it works in the checkout. */
+    leadWorktree: boolean;
+    /** Why the run works in the checkout, when it was probed. */
+    reason?: string;
+}
+/**
+ * Where a run's agents work. A new run is isolated when the project dir can be (see `isolationBlocker`), otherwise it shares the
+ * checkout. A resumed run keeps what its state recorded, whatever the repo looks like now. Decided once, before the run's lock is taken.
+ */
+export declare function planWorkspace(project: ResolvedProject, resume?: RunState): WorkspacePlan;
+/** Refuse to resume a worktree run when its repo can no longer be isolated; returns nothing when it is fine. */
+export declare function assertWorktreeRunnable(project: ResolvedProject): void;
 /** `refs/agent-lyceum/<run>/base-0` pointing at the repo's HEAD: where a concurrent run starts. Nothing in the repo changes. */
 export declare function snapshotHead(project: ResolvedProject, runId: string): string;
 /**
@@ -97,8 +106,6 @@ export interface ChangeSet {
     /** Why these changes may not be integrated (empty when they may). */
     violations: string[];
 }
-/** Glob as used in `owns`: `**` crosses folders, `*` and `?` stay within one, `{a,b}` alternates. */
-export declare function globMatch(glob: string, file: string): boolean;
 /** Commit whatever is in an agent's worktree (no hooks, no signing, dispatcher identity). Returns the HEAD afterwards and whether a commit was made. */
 export declare function commitWorkspace(ws: AgentWorkspace, message: string): {
     head: string;
@@ -106,10 +113,10 @@ export declare function commitWorkspace(ws: AgentWorkspace, message: string): {
 };
 /**
  * Commit whatever the agent left in its worktree and list what changed since its snapshot, checking every
- * changed path (modified, added, deleted, or either end of a rename) against the agent's `owns`, the project
+ * changed path (modified, added, deleted, or either end of a rename) against the project
  * folder, the protected instruction files, and symlink/submodule rules. Nothing is applied here.
  */
-export declare function collectAgentChanges(workspace: AgentWorkspace, owns: string[]): ChangeSet;
+export declare function collectAgentChanges(workspace: AgentWorkspace): ChangeSet;
 export type IntegrationResult = {
     status: "integrated";
     files: ChangedFile[];