agent-lyceum 0.17.3 → 0.19.0

package/dist/config.js

@@ -2,7 +2,7 @@ import fs from "node:fs";
 import path from "node:path";
 import YAML from "yaml";
 import { absPath, homePaths, projectPaths, } from "./paths.js";
-import { DISPATCHER_DEFAULTS, GlobalConfig, ProjectConfig, inferRuntime, } from "./schema.js";
+import { DISPATCHER_DEFAULTS, GlobalConfig, REMOVED_AGENT_KEYS, REMOVED_DISPATCHER_KEYS, ProjectConfig, inferRuntime, } from "./schema.js";
 export class ConfigError extends Error {
 }
 function readYaml(file, schema, label) {
@@ -58,7 +58,8 @@ export function resolveProjectFrom(home, name, g, p) {
     const paths = projectPaths(home, name);
     const hp = homePaths(home);
     const lead = p.team.lead;
-    const dispatcher = { ...DISPATCHER_DEFAULTS, ...stripUndef(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)) {
         const gl = resolveLayer(g.agents[agentName], home);
@@ -128,19 +129,32 @@ 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");
         const canEdit = pick("can_edit_agent_md");
         const canAsk = pick("can_ask_user");
         const allowWeb = pick("allow_web");
-        const owns = pick("owns");
         for (const [k, v] of [
             ["resume", resume],
             ["can_message", canMessage],
             ["can_edit_agent_md", canEdit],
             ["can_ask_user", canAsk],
-            ["owns", owns],
         ]) {
             if (v === undefined)
                 sources[k] = "default";
@@ -157,7 +171,9 @@ export function resolveProjectFrom(home, name, g, p) {
             canEditAgentMd: canEdit ?? isLead,
             canAskUser: canAsk ?? isLead,
             allowWeb,
-            owns: owns ?? [],
+            fallback,
+            fallbackShared,
+            fallbackInvalid,
             sources,
         };
     }
@@ -169,7 +185,45 @@ export function resolveProjectFrom(home, name, g, p) {
         dispatcher,
         agents,
         paths,
+        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 = [];
+    const scan = (file, dispatcher, agents) => {
+        const keys = [];
+        for (const k of REMOVED_DISPATCHER_KEYS)
+            if (dispatcher?.[k] !== undefined)
+                keys.push(`dispatcher.${k}`);
+        for (const [name, a] of Object.entries(agents))
+            for (const k of REMOVED_AGENT_KEYS)
+                if (a[k] !== undefined)
+                    keys.push(`agents.${name}.${k}`);
+        if (keys.length)
+            out.push({ file, keys });
     };
+    scan(globalFile, undefined, g.agents);
+    scan(projectFile, p.dispatcher, p.agents);
+    return out;
 }
 function stripUndef(o) {
     return Object.fromEntries(Object.entries(o).filter(([, v]) => v !== undefined));
@@ -205,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", "owns"];
+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);
@@ -216,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)) {
@@ -232,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");
@@ -240,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);
         }
@@ -249,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;
@@ -264,7 +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;
-        v[`${p}.owns`] = a.owns;
+        if (a.fallback.length)
+            v[`${p}.fallback`] = a.fallback;
     }
     return v;
 }

package/dist/demo.js

@@ -82,7 +82,6 @@ export function prepareDemo(dir, runtime) {
     // One runtime for the whole team, and the roles scoped to the sample repo.
     for (const agent of ["lead", "fe-member", "qa-member"])
         yaml = yaml.replace(`  ${agent}:\n`, `  ${agent}:\n    runtime: ${runtime}\n`);
-    yaml = yaml.replace('# owns: ["src/web/**"]', 'owns: ["src/**"]').replace('# owns: ["tests/**"]', 'owns: ["test/**"]');
     fs.writeFileSync(cfg, yaml);
     return { dir: root, home, repo };
 }

package/dist/dispatcher.d.ts

@@ -3,4 +3,5 @@ import { newRunId } from "./run-store.js";
 export { newRunId };
 export type { ActiveWake, EndReason, RunState, SentTopic, WakeRecord, WakeTopic } from "./run-store.js";
 export { MAX_DONE_REJECTIONS, RESULT_FILE, type RunOptions, type RunSummary } from "./run-session.js";
-export declare function runTeam(opts: RunOptions): Promise<RunSummary>;
+/** `plan` is what the CLI decided before taking the run's lock. The CLI always passes it; the fallback exists only for direct callers and tests. */
+export declare function runTeam(opts: Omit<RunOptions, "plan"> & Partial<Pick<RunOptions, "plan">>): Promise<RunSummary>;

package/dist/dispatcher.js

@@ -1,7 +1,9 @@
 import { RunSession } from "./run-session.js";
 import { newRunId } from "./run-store.js";
+import { planWorkspace } from "./worktree.js";
 export { newRunId };
 export { MAX_DONE_REJECTIONS, RESULT_FILE } from "./run-session.js";
+/** `plan` is what the CLI decided before taking the run's lock. The CLI always passes it; the fallback exists only for direct callers and tests. */
 export async function runTeam(opts) {
-    return new RunSession(opts).run();
+    return new RunSession({ ...opts, plan: opts.plan ?? planWorkspace(opts.project, opts.resume) }).run();
 }

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

@@ -6,7 +6,7 @@ import { tidyAdvice } from "./memory-tidy.js";
 import { listRunLocks, listUnreadableRunLocks, lockHolderAlive } from "./project-lock.js";
 import { runInvocation } from "./process-runner.js";
 import { validateProject } from "./validate.js";
-import { dirtyPaths, git, isGitRepo, resolveWorkspaceMode } from "./worktree.js";
+import { dirtyPaths, git, isolationBlocker } from "./worktree.js";
 const BINARY = { "claude-code": "claude", codex: "codex" };
 /** Run a read-only CLI query (`--version`, `--help`): bounded in time and output, never an agent task. */
 async function query(cmd, args, opts) {
@@ -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 = {}) {
@@ -116,20 +125,19 @@ export async function diagnoseProject(project, opts = {}) {
         checks.push({ level: i.level === "error" ? "error" : "warn", subject: "config", message: i.message });
     if (!v.issues.length)
         checks.push({ level: "ok", subject: "config", message: "Configuration is valid." });
-    if (fs.existsSync(project.dir) && isGitRepo(project.dir)) {
-        if (resolveWorkspaceMode(project.dispatcher) === "worktree") {
+    const blocker = fs.existsSync(project.dir) ? isolationBlocker(project.dir) : undefined;
+    if (fs.existsSync(project.dir)) {
+        if (blocker) {
+            checks.push({ level: "info", subject: "git", message: `Runs work directly in ${project.dir}, one agent at a time (${blocker}).` });
+        }
+        else {
             const dirty = dirtyPaths(project.dir);
-            if (dirty.length && project.dispatcher.max_concurrent_runs > 1) {
-                checks.push({ level: "info", subject: "git", message: `${dirty.length} uncommitted change(s) in ${project.dir}: concurrent runs start from HEAD and do not see them.` });
-            }
-            else if (dirty.length) {
-                checks.push({ level: "warn", subject: "git", message: `${dirty.length} uncommitted change(s) in ${project.dir}: a parallel run would refuse to start until they are committed or stashed.` });
-            }
-            else
-                checks.push({ level: "ok", subject: "git", message: "Repo is clean; parallel runs can start." });
+            checks.push(dirty.length
+                ? { level: "info", subject: "git", message: `${dirty.length} uncommitted change(s) in ${project.dir}: runs start from HEAD and do not see them.` }
+                : { level: "ok", subject: "git", message: "git repo with a commit: runs and agents work in their own worktrees." });
         }
     }
-    if (project.dispatcher.max_concurrent_runs > 1 && fs.existsSync(project.dir) && isGitRepo(project.dir)) {
+    if (fs.existsSync(project.dir) && !blocker) {
         const missing = [];
         if (!findOnPath("gh", opts.env?.PATH ?? process.env.PATH))
             missing.push("`gh` is not on PATH");
@@ -161,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>>;

package/dist/fallback.js

@@ -0,0 +1,157 @@
+/** `<runtime>/<model>`, the model trimmed and lowercased (no model = ""), so entries naming the same model share one key. */
+const keyOf = (runtime, model) => `${runtime}/${(model ?? "").trim().toLowerCase()}`;
+/**
+ * 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 function candidatesFor(agent) {
+    // `validate` refuses an agent without a runtime before anything is woken.
+    const runtime = agent.runtime;
+    const primary = { runtime, model: agent.model, effort: agent.effort, primary: true, key: keyOf(runtime, agent.model) };
+    const out = [primary];
+    const seen = new Set([primary.key]);
+    for (const f of agent.fallback) {
+        const model = f.model || undefined;
+        const key = keyOf(f.runtime, model);
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        out.push({ runtime: f.runtime, model, effort: f.effort, primary: false, key });
+    }
+    return out;
+}
+/**
+ * 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 function agentForCandidate(agent, c) {
+    if (c.primary)
+        return agent;
+    const allowWeb = agent.allowWeb ?? (agent.runtime === "claude-code" && c.runtime === "codex" ? "none" : undefined);
+    return { ...agent, runtime: c.runtime, model: c.model, effort: c.effort, allowWeb };
+}
+/** Models that failed with `rate_limit`/`quota`, and until when (epoch ms) wakes skip them. Shared by a run, kept in `state.json`. */
+export class Cooldowns {
+    table = new Map();
+    /** Cool `key` down for `sec` seconds from `now`; never shortens a longer cooldown already in place. */
+    mark(key, kind, now, sec) {
+        if (sec <= 0)
+            return;
+        const until = now + sec * 1000;
+        if ((this.table.get(key)?.until ?? 0) >= until)
+            return;
+        this.table.set(key, { until, kind });
+    }
+    /** Milliseconds of cooldown left for `key` at `now`; 0 = none. */
+    active(key, now) {
+        const until = this.table.get(key)?.until ?? 0;
+        return Math.max(0, until - now);
+    }
+    toJSON() {
+        return Object.fromEntries([...this.table].map(([k, v]) => [k, { until: new Date(v.until).toISOString(), kind: v.kind }]));
+    }
+    /** Rebuild from `toJSON()` output; a missing table (older `state.json`) is an empty one. */
+    static from(json) {
+        const c = new Cooldowns();
+        for (const [k, v] of Object.entries(json ?? {})) {
+            const until = Date.parse(v.until);
+            if (Number.isFinite(until))
+                c.table.set(k, { until, kind: v.kind });
+        }
+        return c;
+    }
+}
+/** The candidates for one wake: the chain minus those cooling down, or the whole chain when every one is (something must be tried). */
+export function planAttempts(agent, cooldowns, now) {
+    const all = candidatesFor(agent);
+    const warm = all.filter((c) => cooldowns.active(c.key, now) === 0);
+    return warm.length ? warm : all;
+}
+/**
+ * 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 function nextStep(kind, attemptsOnCurrent, retry, hasNext, legacy) {
+    const retriesLeft = attemptsOnCurrent <= retry;
+    if (legacy)
+        return retriesLeft ? "retry-same" : "stop";
+    switch (kind) {
+        case "rate_limit":
+        case "quota":
+            return hasNext ? "next-candidate" : "stop";
+        case "timeout":
+        case "network":
+        case "crash":
+            return retriesLeft ? "retry-same" : hasNext ? "next-candidate" : "stop";
+        case "auth":
+            return "stop";
+        default:
+            // `unknown` and unclassified failures: same model only, as before fallback existed.
+            return retriesLeft ? "retry-same" : "stop";
+    }
+}
+/** Wait before the `n`th retry (1-based) on the same candidate: 5s, 15s, 45s, then 60s. */
+export function backoffMs(n) {
+    return Math.min(5 * 3 ** (n - 1), 60) * 1000;
+}
+/** `setTimeout` as a promise that resolves early (never rejects) when `signal` aborts. */
+export function defaultSleep(ms, signal) {
+    return new Promise((resolve) => {
+        if (signal?.aborted)
+            return resolve();
+        const done = () => {
+            clearTimeout(timer);
+            signal?.removeEventListener("abort", done);
+            resolve();
+        };
+        const timer = setTimeout(done, ms);
+        signal?.addEventListener("abort", done, { once: true });
+    });
+}
+/**
+ * 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 async function runWithFallback(o) {
+    const first = o.candidates[0];
+    if (!first)
+        throw new Error("runWithFallback needs at least one candidate");
+    const sleep = o.sleep ?? defaultSleep;
+    const now = o.now ?? Date.now;
+    const tried = [];
+    let index = 0;
+    let used = first;
+    let ctx = { attempt: 0, candidateAttempt: 0 };
+    let result;
+    for (;;) {
+        if (o.beforeAttempt?.(used, ctx) === "stop")
+            return { result, tried, used, stopped: "beforeAttempt" };
+        result = await o.invoke(used, ctx);
+        await o.afterAttempt?.(used, result, ctx);
+        if (result.ok || result.cancelled)
+            return { result, tried, used };
+        tried.push({ runtime: used.runtime, model: used.model, kind: result.kind, error: result.error });
+        if (!o.legacy && (result.kind === "rate_limit" || result.kind === "quota"))
+            o.cooldowns.mark(used.key, result.kind, now(), o.cooldownSec);
+        const next = o.candidates[index + 1];
+        const step = nextStep(result.kind, ctx.candidateAttempt + 1, o.retry, !!next, o.legacy);
+        if (step === "stop")
+            return { result, tried, used };
+        if (step === "retry-same") {
+            if (!o.legacy) {
+                await sleep(backoffMs(ctx.candidateAttempt + 1), o.signal);
+                if (o.signal?.aborted)
+                    return { result, tried, used, stopped: "aborted" };
+            }
+            ctx = { attempt: ctx.attempt + 1, candidateAttempt: ctx.candidateAttempt + 1, previous: result };
+            continue;
+        }
+        const to = next;
+        o.onSwitch?.(used, to, result.kind, result);
+        ctx = { attempt: ctx.attempt + 1, candidateAttempt: 0, previous: result, switchedFrom: used };
+        index++;
+        used = to;
+    }
+}

package/dist/paths.d.ts

@@ -26,5 +26,3 @@ export interface ProjectPaths {
 export declare function projectPaths(home: string, project: string): ProjectPaths;
 /** True when `child` is `parent` or inside it. */
 export declare function isInside(parent: string, child: string): boolean;
-/** Directory part of a glob that precedes the first wildcard segment. */
-export declare function globStaticPrefix(glob: string): string;

package/dist/paths.js

@@ -49,14 +49,3 @@ export function isInside(parent, child) {
     const rel = path.relative(parent, child);
     return rel === "" || (!rel.startsWith("..") && !path.isAbsolute(rel));
 }
-/** Directory part of a glob that precedes the first wildcard segment. */
-export function globStaticPrefix(glob) {
-    const segs = glob.split("/");
-    const out = [];
-    for (const s of segs) {
-        if (/[*?[\]{}]/.test(s))
-            break;
-        out.push(s);
-    }
-    return out.join("/");
-}

package/dist/policy.d.ts

@@ -8,7 +8,6 @@ export interface AgentEnforcement {
     otherContext: Level;
     shared: Level;
     repoInstructions: Level;
-    owns: Level;
     /** Absolute paths outside the repo this agent may write. */
     writablePaths: string[];
     notes: string[];
@@ -22,9 +21,6 @@ export interface WritePolicy {
     allowFiles: string[];
     /** Files/dirs that must stay unwritable (checked even inside the repo). */
     deny: string[];
-    /** Repo-relative globs the agent owns (only enforced when max_parallel > 1). */
-    owns: string[];
-    restrictRepoToOwns: boolean;
 }
 export declare function commonFile(project: ResolvedProject): string;
 export declare function outboxDir(project: ResolvedProject, agent: string): string;
@@ -41,8 +37,8 @@ export declare function sharedIndex(project: ResolvedProject): string | undefine
 /** The repo directory this agent works in: its own worktree, or the main repo. */
 export declare function repoDirFor(project: ResolvedProject, agent: string): string;
 export declare function writePolicy(project: ResolvedProject, agent: ResolvedAgent): WritePolicy;
+/** Test seam: pretend the OS sandbox is (un)available; `undefined` re-probes the host. */
+export declare function setOsSandboxForTest(available: boolean | undefined): void;
 export declare function enforcementFor(project: ResolvedProject, agent: ResolvedAgent): AgentEnforcement;
-/** Static directory prefixes (absolute) of an agent's `owns` globs. */
-export declare function ownsDirs(project: ResolvedProject, agent: ResolvedAgent): string[];
 /** Can `agent` legitimately change this protected file? */
 export declare function mayEditProtected(project: ResolvedProject, agent: ResolvedAgent, file: string): boolean;