agent-lyceum 0.26.0 → 0.28.0

package/README.md

@@ -75,6 +75,10 @@ agents:
 
 Folder layout, every agent field and the rules `doctor` checks: [Configuration](docs/configuration.md).
 
+## Downgrading
+
+Older versions refuse a `team.yaml` or `project.yaml` that contains `model_tiers` (a load error, "Unrecognized key"). Before using an older binary, remove `model_tiers` from every `project.yaml` and from `team.yaml`. Other mail and run state are unaffected: older versions ignore a `tier` line in mail. See [Model tiers](docs/configuration.md#model-tiers). (Spec 24.3.2, 24.13)
+
 ## Topics
 
 | Topic | Read |

package/README.zh-TW.md

@@ -75,6 +75,10 @@ agents:
 
 資料夾結構、所有 agent 欄位與 `doctor` 檢查的規則：[設定](docs/configuration.zh-TW.md)。
 
+## 降級（改用舊版）
+
+舊版程式會拒絕載入含 `model_tiers` 的 `team.yaml` 或 `project.yaml`（載入錯誤，「Unrecognized key」）。改用舊版前，請先從每個 `project.yaml` 與 `team.yaml` 拿掉 `model_tiers`。其他信件與 run 狀態不受影響：舊版會忽略信件中的 `tier` 行。見[模型分級](docs/configuration.zh-TW.md#模型分級)。（spec 24.3.2、24.13）
+
 ## 主題
 
 | 主題 | 閱讀 |

package/dist/adapters/claude.js

@@ -1,6 +1,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { repoDirFor, scratchCwd, writePolicy } from "../policy.js";
+import { canonicalPath } from "../paths.js";
 /** Claude Code path rules: `//abs/path` — a leading "/" plus the absolute path. */
 const rule = (tool, p) => `${tool}(/${p})`;
 function denyRules(p) {
@@ -34,6 +35,15 @@ export function buildClaudeSettings(project, agent, override) {
     for (const f of pol.allowFiles)
         allow.push(rule("Edit", f));
     const deny = pol.deny.flatMap(denyRules);
+    // Spec 25: network allowances; never with a policy override (a minimal-authority wake).
+    const sb = override ? undefined : agent.sandbox;
+    const network = {};
+    if (sb?.network.length)
+        network.allowedDomains = sb.network;
+    if (sb?.localBinding)
+        network.allowLocalBinding = true;
+    if (sb?.unixSockets.length)
+        network.allowUnixSockets = sb.unixSockets.map(canonicalPath);
     return {
         // The user's own and plugin hooks (e.g. a hook that asks the user a question) would block every tool call of a headless wake-up.
         disableAllHooks: true,
@@ -45,6 +55,7 @@ export function buildClaudeSettings(project, agent, override) {
                 allowWrite: [override?.cwd ?? ws?.root ?? project.dir, ...pol.allowDirs, ...pol.allowFiles],
                 denyWrite: pol.deny,
             },
+            ...(Object.keys(network).length ? { network } : {}),
         },
     };
 }

package/dist/adapters/codex.js

@@ -63,6 +63,8 @@ export function buildCodexInvocation(input) {
         'approval_policy="never"',
         "-c",
         `sandbox_workspace_write.writable_roots=${JSON.stringify(roots)}`,
+        // Codex has one switch for all network access; spec 25 never uses it under a policy override.
+        ...(!input.policy && agent.sandbox?.network.length ? ["-c", "sandbox_workspace_write.network_access=true"] : []),
         "--json",
         "-o",
         lastFile,

package/dist/call.js

@@ -1,5 +1,6 @@
 import fs from "node:fs";
 import path from "node:path";
+import { invokeWithSandboxChecks } from "./sandbox-invocation.js";
 import { realInvoker } from "./adapters/index.js";
 import { must } from "./assert.js";
 import { ConfigError, loadGlobal, resolveProjectFrom } from "./config.js";
@@ -55,6 +56,8 @@ export function callProject(home, agent, dir, callDir) {
         lead: agent.name,
         dispatcher: DISPATCHER_DEFAULTS,
         agents: { [agent.name]: agent },
+        modelTiers: {},
+        modelTiersFrom: {},
         paths,
         solo: "call",
     };
@@ -155,7 +158,7 @@ export async function callAgent(o) {
                     return;
                 say(`  ${agent.name} falling back to ${to.model ? `${to.runtime}/${to.model}` : to.runtime} (${kind ?? "unknown error"})`);
             },
-            invoke: (c) => invoke({
+            invoke: (c, ctx) => invokeWithSandboxChecks(invoke, {
                 project,
                 agent: agentForCandidate(agent, c),
                 workDir: callDir,
@@ -164,7 +167,7 @@ export async function callAgent(o) {
                 timeoutSec: project.dispatcher.wake_timeout_sec,
                 signal: o.signal,
                 logDir: logDirFor(c),
-            }).catch((e) => ({ ok: false, text: "", exitCode: null, timedOut: false, error: e.message })),
+            }, agent, { event: (name, fields) => say(JSON.stringify({ event: name, ...fields })) }, ctx.attempt).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;

package/dist/config.d.ts

@@ -1,9 +1,15 @@
 import { type ProjectPaths } from "./paths.js";
 import type { AgentWorkspace } from "./worktree.js";
-import { type DispatcherSettings, type Effort, type FallbackEntry, type Runtime, type WebLevel } from "./schema.js";
+import { type DispatcherSettings, type Effort, type FallbackEntry, type SandboxPartialT, type Runtime, type WebLevel } from "./schema.js";
 export declare class ConfigError extends Error {
 }
 export type Source = "global" | "project" | "default" | "model";
+export interface SandboxAllowances {
+    write: string[];
+    network: string[];
+    localBinding: boolean;
+    unixSockets: string[];
+}
 export interface ResolvedAgent {
     name: string;
     runtime?: Runtime;
@@ -22,6 +28,8 @@ export interface ResolvedAgent {
     canAskUser: boolean;
     /** Web access for this agent; undefined = not configured, so the runtime keeps its own default. */
     allowWeb?: WebLevel;
+    /** Spec 25 allowances; unset when none is requested (the only switch that keeps output identical). Paths are absolute, `~` expanded, not yet canonical. */
+    sandbox?: SandboxAllowances;
     /** 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. */
@@ -33,6 +41,8 @@ export interface ResolvedAgent {
     }[];
     /** Where each field's value came from (for `validate` output). */
     sources: Record<string, Source>;
+    /** Spec 24: the tiers this agent can run on (its runtime's ladder up to and including `model`); unset when nothing is below `model`. */
+    tiers?: string[];
     /** Set when the run bound this agent as an instance of a role that has several (spec 23): which role, and the instance number. */
     instance?: {
         role: string;
@@ -52,6 +62,10 @@ export interface ResolvedProject {
     lead: string;
     dispatcher: DispatcherSettings;
     agents: Record<string, ResolvedAgent>;
+    /** Spec 24: non-empty model ladders per runtime, lowest first (project.yaml replaces team.yaml's per runtime). */
+    modelTiers: Partial<Record<Runtime, string[]>>;
+    /** Which file each ladder in `modelTiers` came from. */
+    modelTiersFrom: Partial<Record<Runtime, "global" | "project">>;
     paths: ProjectPaths;
     /** Removed settings still present in config files (ignored); `validate` warns once per file. */
     ignoredSettings?: {
@@ -73,6 +87,10 @@ export interface ResolvedProject {
     solo?: "run" | "call";
 }
 export declare function loadGlobal(home: string): {
+    model_tiers?: {
+        "claude-code"?: string[] | undefined;
+        codex?: string[] | undefined;
+    } | undefined;
     agents: Record<string, {
         runtime?: "claude-code" | "codex" | undefined;
         model?: string | undefined;
@@ -92,6 +110,12 @@ export declare function loadGlobal(home: string): {
             model?: string | undefined;
             effort?: "high" | "low" | "max" | "medium" | "minimal" | "xhigh" | undefined;
         }[] | undefined;
+        sandbox?: {
+            write?: string[] | undefined;
+            network?: string[] | undefined;
+            local_binding?: boolean | undefined;
+            unix_sockets?: string[] | undefined;
+        } | undefined;
         owns?: unknown;
     }>;
 };
@@ -100,6 +124,10 @@ export declare function loadProjectRaw(home: string, name: string): {
     team: {
         lead: string;
     };
+    model_tiers?: {
+        "claude-code"?: string[] | undefined;
+        codex?: string[] | undefined;
+    } | undefined;
     dispatcher: {
         max_rounds?: number | undefined;
         max_parallel?: unknown;
@@ -136,6 +164,12 @@ export declare function loadProjectRaw(home: string, name: string): {
             model?: string | undefined;
             effort?: "high" | "low" | "max" | "medium" | "minimal" | "xhigh" | undefined;
         }[] | undefined;
+        sandbox?: {
+            write?: string[] | undefined;
+            network?: string[] | undefined;
+            local_binding?: boolean | undefined;
+            unix_sockets?: string[] | undefined;
+        } | undefined;
         owns?: unknown;
     }>;
 };
@@ -163,6 +197,8 @@ export type SourceInfo = {
 } | {
     default: true;
 };
+/** Spec 25.4.2: validated, deduplicated allowances; undefined when nothing is requested. */
+export declare function resolveSandbox(agent: string, s: SandboxPartialT | undefined): SandboxAllowances | undefined;
 /** The resolved project plus, for every setting, the file and key it was taken from (or "default"). */
 export declare function resolveProjectWithSources(home: string, name: string): {
     project: ResolvedProject;

package/dist/config.js

@@ -1,8 +1,9 @@
 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, REMOVED_AGENT_KEYS, REMOVED_DISPATCHER_KEYS, ProjectConfig, inferRuntime, } from "./schema.js";
+import { absPath, canonicalPath, escapesParent, expandHome, homePaths, projectPaths, } from "./paths.js";
+import { availableTiers } from "./tiers.js";
+import { DISPATCHER_DEFAULTS, GlobalConfig, REMOVED_AGENT_KEYS, REMOVED_DISPATCHER_KEYS, ProjectConfig, inferRuntime, RUNTIMES, } from "./schema.js";
 export class ConfigError extends Error {
 }
 function readYaml(file, schema, label) {
@@ -60,6 +61,16 @@ export function resolveProjectFrom(home, name, g, p) {
     const lead = p.team.lead;
     const { max_parallel: _mp, max_concurrent_runs: _mc, workspace_mode: _wm, fallback: dispatcherFallback, ...liveDispatcher } = p.dispatcher;
     const dispatcher = { ...DISPATCHER_DEFAULTS, ...stripUndef(liveDispatcher) };
+    const modelTiers = {};
+    const modelTiersFrom = {};
+    for (const rt of RUNTIMES) {
+        const fromProject = p.model_tiers?.[rt] !== undefined;
+        const ladder = fromProject ? p.model_tiers?.[rt] : g.model_tiers?.[rt];
+        if (ladder?.length) {
+            modelTiers[rt] = [...ladder];
+            modelTiersFrom[rt] = fromProject ? "project" : "global";
+        }
+    }
     const agents = {};
     for (const agentName of Object.keys(p.agents)) {
         const gl = resolveLayer(g.agents[agentName], home);
@@ -144,12 +155,14 @@ export function resolveProjectFrom(home, name, g, p) {
             }
         }
         const { entries: fallback, invalid: fallbackInvalid } = resolveFallback(rawFallback, runtime);
+        const tiers = runtime ? availableTiers(modelTiers[runtime], model) : undefined;
         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 sandbox = resolveSandbox(agentName, pick("sandbox"));
         for (const [k, v] of [
             ["resume", resume],
             ["can_message", canMessage],
@@ -171,10 +184,12 @@ export function resolveProjectFrom(home, name, g, p) {
             canEditAgentMd: canEdit ?? isLead,
             canAskUser: canAsk ?? isLead,
             allowWeb,
+            ...(sandbox ? { sandbox } : {}),
             fallback,
             fallbackShared,
             fallbackInvalid,
             sources,
+            ...(tiers ? { tiers } : {}),
         };
     }
     return {
@@ -184,6 +199,8 @@ export function resolveProjectFrom(home, name, g, p) {
         lead,
         dispatcher,
         agents,
+        modelTiers,
+        modelTiersFrom,
         paths,
         ignoredSettings: collectIgnored(hp.globalConfig, g, paths.config, p),
     };
@@ -252,14 +269,46 @@ export function findProjectForCwd(home, cwd) {
     let best;
     for (const pr of listProjects(home)) {
         const rel = path.relative(pr.dir, cwd);
-        if (rel === "" || (!rel.startsWith("..") && !path.isAbsolute(rel))) {
+        if (!escapesParent(rel)) {
             if (!best || pr.dir.length > best.len)
                 best = { name: pr.name, len: pr.dir.length };
         }
     }
     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", "fallback"];
+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", "sandbox"];
+/** Claude pattern metacharacters and control characters: refused in sandbox paths instead of escaped (spec 25.4.1). */
+const PATH_CHARS = /[*?[\]{}()!\\]/;
+const PATH_META = { test: (p) => PATH_CHARS.test(p) || [...p].some((c) => c.charCodeAt(0) < 32 || c.charCodeAt(0) === 127) };
+function sandboxPath(agent, key, i, raw) {
+    const at = `agents.${agent}.sandbox.${key}.${i}`;
+    if (PATH_META.test(raw))
+        throw new ConfigError(`${at}: must not contain pattern characters (* ? [ ] { } ( ) !), backslashes or control characters (got ${JSON.stringify(raw)})`);
+    if (/^\$|\$\{?[A-Za-z_]/.test(raw))
+        throw new ConfigError(`${at}: environment variables are not expanded; write the absolute path (got "${raw}")`);
+    const expanded = expandHome(raw);
+    if (!path.isAbsolute(expanded))
+        throw new ConfigError(`${at}: must be an absolute path or start with ~/ (got "${raw}")`);
+    const resolved = path.resolve(expanded);
+    const canon = canonicalPath(resolved);
+    for (const p of [resolved, canon])
+        if (PATH_META.test(p))
+            throw new ConfigError(`${at}: resolved path contains pattern characters (${JSON.stringify(p)})`);
+    return resolved;
+}
+/** Spec 25.4.2: validated, deduplicated allowances; undefined when nothing is requested. */
+export function resolveSandbox(agent, s) {
+    if (!s)
+        return undefined;
+    const uniq = (xs) => [...new Set(xs)];
+    const write = uniq((s.write ?? []).map((p, i) => sandboxPath(agent, "write", i, p)));
+    const unixSockets = uniq((s.unix_sockets ?? []).map((p, i) => sandboxPath(agent, "unix_sockets", i, p)));
+    const network = uniq(s.network ?? []);
+    const localBinding = s.local_binding === true;
+    if (!write.length && !unixSockets.length && !network.length && !localBinding)
+        return undefined;
+    return { write, network, localBinding, unixSockets };
+}
 /** 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);
@@ -278,6 +327,11 @@ export function resolveProjectWithSources(home, name) {
     }
     if (raw.dispatcher.max_instances !== undefined)
         sources["dispatcher.max_instances"] = { file: projectFile, key: "dispatcher.max_instances" };
+    for (const rt of RUNTIMES) {
+        const from = project.modelTiersFrom[rt];
+        if (from)
+            sources[`model_tiers.${rt}`] = { file: from === "project" ? projectFile : globalFile, key: `model_tiers.${rt}` };
+    }
     for (const a of Object.values(project.agents)) {
         const at = (src, field) => {
             const key = `agents.${a.name}.${field}`;
@@ -307,6 +361,10 @@ export function resolveProjectWithSources(home, name) {
             else
                 sources[`agents.${a.name}.${f}`] = at(src, f);
         }
+        // The ladder is the runtime's, so its source is the ladder's own key (spec 24.9).
+        const ladderSrc = a.tiers ? sources[`model_tiers.${a.runtime}`] : undefined;
+        if (ladderSrc)
+            sources[`agents.${a.name}.model_tiers`] = ladderSrc;
     }
     return { project, sources };
 }
@@ -314,6 +372,9 @@ export function resolveProjectWithSources(home, name) {
 export function flattenResolved(project) {
     const v = { dir: project.dir, "team.lead": project.lead };
     const anyFallback = Object.values(project.agents).some((a) => a.fallback.length > 0);
+    for (const rt of RUNTIMES)
+        if (project.modelTiers[rt])
+            v[`model_tiers.${rt}`] = project.modelTiers[rt];
     for (const [k, val] of Object.entries(project.dispatcher)) {
         if (k === "fallback_cooldown_sec" && !anyFallback)
             continue; // keep `doctor --resolved` unchanged without fallback
@@ -334,6 +395,10 @@ export function flattenResolved(project) {
         v[`${p}.allow_web`] = a.allowWeb;
         if (a.fallback.length)
             v[`${p}.fallback`] = a.fallback;
+        if (a.sandbox)
+            v[`${p}.sandbox`] = { write: a.sandbox.write, network: a.sandbox.network, local_binding: a.sandbox.localBinding, unix_sockets: a.sandbox.unixSockets };
+        if (a.tiers)
+            v[`${p}.model_tiers`] = a.tiers;
     }
     return v;
 }

package/dist/duplicate-notices.d.ts

@@ -0,0 +1,9 @@
+/** How many distinct sent-again mails of one repeat are announced to the sender before further repeats are set aside silently. */
+export declare const MAX_DUPLICATE_NOTICES = 2;
+/** Key of one sender's repeat of earlier mail; JSON keeps it unambiguous whatever the names contain. */
+export declare function duplicateNoticeKey(sender: string, repeats: Iterable<[string, string]>): string;
+/**
+ * Decide whether the repeat found in outbox mail `source` is announced. Idempotent per source: the notified source ids
+ * are stored, so a replay after a crash neither counts twice nor loses a notice it already earned.
+ */
+export declare function shouldNotifyDuplicate(runDir: string, key: string, source: string): boolean;

package/dist/duplicate-notices.js

@@ -0,0 +1,34 @@
+import fs from "node:fs";
+import path from "node:path";
+import { atomicWrite } from "./fs-util.js";
+/** How many distinct sent-again mails of one repeat are announced to the sender before further repeats are set aside silently. */
+export const MAX_DUPLICATE_NOTICES = 2;
+const FILE = "duplicate-notices.json";
+/** Key of one sender's repeat of earlier mail; JSON keeps it unambiguous whatever the names contain. */
+export function duplicateNoticeKey(sender, repeats) {
+    return JSON.stringify([sender, [...repeats].map(([to, id]) => [to, id]).sort()]);
+}
+function load(runDir) {
+    try {
+        const data = JSON.parse(fs.readFileSync(path.join(runDir, FILE), "utf8"));
+        return data && typeof data === "object" && !Array.isArray(data) ? data : {};
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * Decide whether the repeat found in outbox mail `source` is announced. Idempotent per source: the notified source ids
+ * are stored, so a replay after a crash neither counts twice nor loses a notice it already earned.
+ */
+export function shouldNotifyDuplicate(runDir, key, source) {
+    const all = load(runDir);
+    const seen = Array.isArray(all[key]) ? all[key] : [];
+    if (seen.includes(source))
+        return true;
+    if (seen.length >= MAX_DUPLICATE_NOTICES)
+        return false;
+    all[key] = [...seen, source];
+    atomicWrite(path.join(runDir, FILE), `${JSON.stringify(all, null, 2)}\n`);
+    return true;
+}

package/dist/fallback.d.ts

@@ -7,6 +7,8 @@ export interface Candidate {
     model?: string;
     effort?: Effort;
     primary: boolean;
+    /** The cheaper model a lead's `tier` picked (spec 24.7): not the primary, and not a fallback either. */
+    tiered?: true;
     /** `<runtime>/<model>`; the cooldown and session key. */
     key: string;
 }
@@ -14,7 +16,7 @@ export interface Candidate {
  * 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[];
+export declare function candidatesFor(agent: ResolvedAgent, tierModel?: string): 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
@@ -39,7 +41,13 @@ export declare class Cooldowns {
     }>): 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 declare function planAttempts(all: readonly Candidate[], cooldowns: Cooldowns, now: number): Candidate[];
+/**
+ * The candidates `planAttempts` left out because they are cooling down, soonest to recover first. They are tried last, after
+ * waiting for their cooldown to end, so a wake-up whose warm models all fail is not lost to a cooldown that ends moments later.
+ * A tier's cheaper model is not one of them: stepping back down to it after the ceiling failed would be wrong.
+ */
+export declare function deferredAttempts(all: readonly Candidate[], 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
@@ -78,6 +86,8 @@ export interface Tried {
 export interface RunWithFallbackOptions<R extends AttemptResult> {
     /** From `planAttempts`; tried in order. */
     candidates: Candidate[];
+    /** From `deferredAttempts`: tried after `candidates`, each one only once its cooldown has ended. */
+    deferred?: Candidate[];
     /** The agent has no fallback chain (see `nextStep`): no backoff, no cooldowns. */
     legacy: boolean;
     /** Retries per candidate (`dispatcher.retry`). */
@@ -91,6 +101,8 @@ export interface RunWithFallbackOptions<R extends AttemptResult> {
     /** 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;
+    /** Runs before the loop sleeps `ms` for `candidate`'s cooldown to end. */
+    onCooldownWait?(candidate: Candidate, ms: number): void;
     sleep?(ms: number, signal?: AbortSignal): Promise<void>;
     now?(): number;
     signal?: AbortSignal;

package/dist/fallback.js

@@ -4,12 +4,18 @@ 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) {
+export function candidatesFor(agent, tierModel) {
     // `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]);
+    // A tier's cheaper model goes first (spec 24.7.1); one that is the ceiling itself adds nothing.
+    if (tierModel && keyOf(runtime, tierModel) !== primary.key) {
+        const key = keyOf(runtime, tierModel);
+        out.unshift({ runtime, model: tierModel, effort: agent.effort, primary: false, tiered: true, key });
+        seen.add(key);
+    }
     for (const f of agent.fallback) {
         const model = f.model || undefined;
         const key = keyOf(f.runtime, model);
@@ -28,6 +34,8 @@ export function candidatesFor(agent) {
 export function agentForCandidate(agent, c) {
     if (c.primary)
         return agent;
+    if (c.tiered)
+        return { ...agent, model: c.model };
     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 };
 }
@@ -63,10 +71,19 @@ export class 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 function planAttempts(agent, cooldowns, now) {
-    const all = candidatesFor(agent);
+export function planAttempts(all, cooldowns, now) {
     const warm = all.filter((c) => cooldowns.active(c.key, now) === 0);
-    return warm.length ? warm : all;
+    return warm.length ? warm : [...all];
+}
+/**
+ * The candidates `planAttempts` left out because they are cooling down, soonest to recover first. They are tried last, after
+ * waiting for their cooldown to end, so a wake-up whose warm models all fail is not lost to a cooldown that ends moments later.
+ * A tier's cheaper model is not one of them: stepping back down to it after the ceiling failed would be wrong.
+ */
+export function deferredAttempts(all, cooldowns, now) {
+    return all
+        .filter((c) => !c.tiered && cooldowns.active(c.key, now) > 0)
+        .sort((a, b) => cooldowns.active(a.key, now) - cooldowns.active(b.key, now));
 }
 /**
  * What to do after a failed call (spec 20.2 decisions 2 and 5). `attemptsOnCurrent` counts the calls made on the current
@@ -74,6 +91,9 @@ export function planAttempts(agent, cooldowns, now) {
  * keeps the old loop: every kind is retried `retry` times, then the wake fails.
  */
 export function nextStep(kind, attemptsOnCurrent, retry, hasNext, legacy) {
+    // A refused configuration cannot get better by trying again or on another model (spec 25.19.1).
+    if (kind === "config")
+        return "stop";
     const retriesLeft = attemptsOnCurrent <= retry;
     if (legacy)
         return retriesLeft ? "retry-same" : "stop";
@@ -115,7 +135,8 @@ export function defaultSleep(ms, signal) {
  * 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];
+    const list = [...o.candidates, ...(o.deferred ?? [])];
+    const first = list[0];
     if (!first)
         throw new Error("runWithFallback needs at least one candidate");
     const sleep = o.sleep ?? defaultSleep;
@@ -135,7 +156,7 @@ export async function runWithFallback(o) {
         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 next = list[index + 1];
         const step = nextStep(result.kind, ctx.candidateAttempt + 1, o.retry, !!next, o.legacy);
         if (step === "stop")
             return { result, tried, used };
@@ -150,6 +171,13 @@ export async function runWithFallback(o) {
         }
         const to = next;
         o.onSwitch?.(used, to, result.kind, result);
+        const wait = o.legacy ? 0 : o.cooldowns.active(to.key, now());
+        if (wait > 0) {
+            o.onCooldownWait?.(to, wait);
+            await sleep(wait, o.signal);
+            if (o.signal?.aborted)
+                return { result, tried, used, stopped: "aborted" };
+        }
         ctx = { attempt: ctx.attempt + 1, candidateAttempt: 0, previous: result, switchedFrom: used };
         index++;
         used = to;

package/dist/guard.d.ts

@@ -9,6 +9,12 @@ export interface Violation {
     /** The kept copy is cut to MAX_KEEP_BYTES. */
     truncated?: boolean;
 }
+/** A change to a cross-run shared file that no agent of the batch may make, while another run of the project was live. */
+export interface Unattributed {
+    file: string;
+    agents: string[];
+    otherRuns: string[];
+}
 export declare const MAX_KEEP_BYTES: number;
 /**
  * Detects (and reverts) changes to protected files made by agents that may not edit them.
@@ -16,10 +22,20 @@ export declare const MAX_KEEP_BYTES: number;
  */
 export declare class ProtectedGuard {
     private project;
+    private otherLiveRuns;
     private baseline;
     /** Regular files of the records tree (including `.archive/`); only the lead may change them. */
     private records;
-    constructor(project: ResolvedProject);
+    /** Changes kept (not reverted) because another live run may have made them; see `takeUnattributed`. */
+    private unattributed;
+    /** Other runs that were live at the last `rebase()` (or at `check()` time); computed once per batch. */
+    private liveAtBase;
+    /** `otherLiveRuns`: ids of the project's other runs that have a live lock holder right now. */
+    constructor(project: ResolvedProject, otherLiveRuns?: () => string[]);
+    /** The unattributed changes since the last call (they were kept and adopted as the baseline). */
+    takeUnattributed(): Unattributed[];
+    /** Files shared by every run of the project: only these can be changed by another run's lead. */
+    private crossRunShared;
     /**
      * Take the current files as the baseline. Called right before a batch is woken, so only what changes while it runs is
      * judged: edits made in between (you, or another run of the project) are not the batch's doing.