agent-lyceum 0.27.0 → 0.28.0

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";
@@ -157,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,
@@ -166,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. */
@@ -102,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;
     }>;
 };
@@ -150,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;
     }>;
 };
@@ -177,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,7 +1,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import YAML from "yaml";
-import { absPath, escapesParent, homePaths, projectPaths, } from "./paths.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 {
@@ -162,6 +162,7 @@ export function resolveProjectFrom(home, name, g, p) {
         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],
@@ -183,6 +184,7 @@ export function resolveProjectFrom(home, name, g, p) {
             canEditAgentMd: canEdit ?? isLead,
             canAskUser: canAsk ?? isLead,
             allowWeb,
+            ...(sandbox ? { sandbox } : {}),
             fallback,
             fallbackShared,
             fallbackInvalid,
@@ -274,7 +276,39 @@ 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", "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);
@@ -361,6 +395,8 @@ 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;
     }

package/dist/fallback.d.ts

@@ -42,6 +42,12 @@ export declare 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 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
@@ -80,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`). */
@@ -93,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

@@ -75,12 +75,25 @@ export function planAttempts(all, cooldowns, now) {
     const warm = all.filter((c) => cooldowns.active(c.key, now) === 0);
     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
  * 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) {
+    // 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";
@@ -122,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;
@@ -142,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 };
@@ -157,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/mailbox.js

@@ -27,14 +27,31 @@ export function serialize(meta, body) {
     const fm = YAML.stringify(meta).trimEnd();
     return `---\n${fm}\n---\n\n${body.trim()}\n`;
 }
+const ID_KEYS = new Set(["id", "reply_to", "thread", "about", "run_id"]);
 export function parseRaw(text) {
     const m = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/.exec(text);
     if (!m)
         throw new Error("missing frontmatter (--- ... ---)");
-    const data = YAML.parse(m[1] ?? "");
+    const fm = m[1] ?? "";
+    const data = YAML.parse(fm);
     if (!data || typeof data !== "object" || Array.isArray(data))
         throw new Error("frontmatter is not a mapping");
-    return { data: data, body: (m[2] ?? "").trim() };
+    const out = data;
+    // Ids are 8 hex characters: `79e76911` parses as Infinity and `01234567` as 1234567.
+    // Only an id key that came out as a number is re-read from its source text; everything else stays as YAML.parse returned it.
+    if (Object.entries(out).some(([k, v]) => ID_KEYS.has(k) && typeof v === "number")) {
+        const doc = YAML.parseDocument(fm);
+        if (YAML.isMap(doc.contents)) {
+            for (const pair of doc.contents.items) {
+                const key = YAML.isScalar(pair.key) ? String(pair.key.value) : "";
+                if (!ID_KEYS.has(key) || typeof out[key] !== "number" || !YAML.isScalar(pair.value))
+                    continue;
+                if (pair.value.type === "PLAIN" && typeof pair.value.source === "string")
+                    out[key] = pair.value.source;
+            }
+        }
+    }
+    return { data: out, body: (m[2] ?? "").trim() };
 }
 export function ensureProjectDirs(project) {
     fs.mkdirSync(path.join(project.paths.shared, "common"), { recursive: true });

package/dist/policy.d.ts

@@ -50,3 +50,36 @@ export declare function setOsSandboxForTest(available: boolean | undefined): voi
 export declare function enforcementFor(project: ResolvedProject, agent: ResolvedAgent): AgentEnforcement;
 /** Can `agent` legitimately change this protected file? */
 export declare function mayEditProtected(project: ResolvedProject, agent: ResolvedAgent, file: string): boolean;
+export type SandboxRelation = "equal" | "inside" | "contains";
+export interface SandboxPathConflict {
+    key: "write" | "unix_sockets";
+    index: number;
+    path: string;
+    protectedPath: string;
+    reason: string;
+    relation: SandboxRelation;
+}
+/** Pure (spec 25.4.3): which canonical sandbox paths equal, sit inside or contain a protected path. Callers canonicalize. */
+export declare function sandboxPathConflicts(entries: {
+    key: "write" | "unix_sockets";
+    index: number;
+    path: string;
+}[], protectedPaths: {
+    path: string;
+    reason: string;
+}[]): SandboxPathConflict[];
+/** What a runtime really applies of an agent's allowances (spec 25.9): the tuple a fallback must not exceed. */
+export interface SandboxCaps {
+    network: "none" | "domains" | "all";
+    localBinding: boolean;
+    unixSockets: boolean;
+}
+export declare const NETWORK_RANK: {
+    readonly none: 0;
+    readonly domains: 1;
+    readonly all: 2;
+};
+/** Without an OS sandbox nothing is applied, so every runtime is equal there. */
+export declare function sandboxCaps(agent: ResolvedAgent, runtime?: string | undefined): SandboxCaps;
+/** Components in which `backup` applies more than `primary`, as `name: primary -> backup`. */
+export declare function sandboxCapExcess(primary: SandboxCaps, backup: SandboxCaps): string[];

package/dist/policy.js

@@ -1,6 +1,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { findOnPath } from "./fs-util.js";
+import { canonicalPath } from "./paths.js";
 export function commonFile(project) {
     return path.join(project.paths.shared, "common", "COMMON.md");
 }
@@ -88,6 +89,8 @@ export function writePolicy(project, agent) {
         ...(ws ? [ws.gitDir] : []),
         ...(shared && mayWriteShared ? [shared] : []),
         ...(isLead ? [recordsDir(project)] : []),
+        // Spec 25: canonical, because the OS sandbox compares real paths (`/tmp` is `/private/tmp` on macOS).
+        ...(agent.sandbox?.write ?? []).map(canonicalPath),
     ];
     const allowFiles = [];
     if (isLead)
@@ -180,6 +183,8 @@ export function enforcementFor(project, agent) {
         if (agent.canEditAgentMd)
             notes.push("can_edit_agent_md widens Codex writable roots to whole agent directories.");
     }
+    if (agent.sandbox)
+        notes.push(...sandboxNotes(agent, os));
     return {
         agent: agent.name,
         runtime: agent.runtime ?? "?",
@@ -188,7 +193,82 @@ export function enforcementFor(project, agent) {
         notes,
     };
 }
+/** Doctor lines for an agent's sandbox allowances (spec 25.7, 25.10): what is requested and what its runtime really applies. */
+function sandboxNotes(agent, os) {
+    const s = agent.sandbox;
+    if (!s)
+        return [];
+    const claude = agent.runtime === "claude-code";
+    const notes = [];
+    if (!os) {
+        notes.push(claude
+            ? "no OS sandbox; sandbox.write changes Edit tool rules only; network/local_binding/unix_sockets have no effect."
+            : "no OS sandbox; enforcement is prompt-only; sandbox allowances provide no OS enforcement.");
+    }
+    if (s.network.length) {
+        notes.push(`network: ${s.network.join(", ")} (${claude ? "claude-code: per-domain" : "codex: all hosts"})`);
+        if (!claude)
+            notes.push(`warn: sandbox.network is all-or-nothing on Codex: this agent may reach any host, not only ${s.network.join(", ")}.`);
+    }
+    if (s.localBinding) {
+        notes.push(claude ? (process.platform === "darwin" ? "local_binding: on" : "local_binding: requested, no effect on this platform (macOS only)") : "local_binding: requested, not supported by codex");
+        if (!claude)
+            notes.push("warn: sandbox.local_binding has no Codex setting; whether a workspace-write sandbox lets it bind ports is unverified. sandbox.network turns on all network access, not only binding.");
+    }
+    if (s.unixSockets.length) {
+        notes.push(`unix_sockets: ${s.unixSockets.map(canonicalPath).join(", ")} (${claude ? "applied" : "not applied by codex"})`);
+        if (!claude)
+            notes.push("warn: sandbox.unix_sockets has no per-socket Codex control; no setting emitted.");
+    }
+    for (const [key, list] of [["write", s.write], ["unix_sockets", s.unixSockets]]) {
+        list.forEach((p, i) => {
+            if (!fs.existsSync(p))
+                notes.push(`info: sandbox.${key}[${i}] ${p} does not exist yet`);
+        });
+    }
+    return notes;
+}
 /** Can `agent` legitimately change this protected file? */
 export function mayEditProtected(project, agent, file) {
     return writePolicy(project, agent).allowFiles.includes(file);
 }
+const within = (parent, p) => p === parent || p.startsWith(parent.endsWith(path.sep) ? parent : parent + path.sep);
+/** Pure (spec 25.4.3): which canonical sandbox paths equal, sit inside or contain a protected path. Callers canonicalize. */
+export function sandboxPathConflicts(entries, protectedPaths) {
+    const out = [];
+    for (const e of entries) {
+        for (const pp of protectedPaths) {
+            const relation = e.path === pp.path ? "equal" : within(pp.path, e.path) ? "inside" : within(e.path, pp.path) ? "contains" : undefined;
+            if (relation)
+                out.push({ ...e, protectedPath: pp.path, reason: pp.reason, relation });
+        }
+    }
+    return out;
+}
+export const NETWORK_RANK = { none: 0, domains: 1, all: 2 };
+/** Without an OS sandbox nothing is applied, so every runtime is equal there. */
+export function sandboxCaps(agent, runtime = agent.runtime) {
+    const s = agent.sandbox;
+    const none = { network: "none", localBinding: false, unixSockets: false };
+    if (!s || !osSandboxAvailable())
+        return none;
+    if (runtime === "claude-code") {
+        return {
+            network: s.network.length ? "domains" : "none",
+            localBinding: s.localBinding && process.platform === "darwin",
+            unixSockets: s.unixSockets.length > 0,
+        };
+    }
+    return { ...none, network: s.network.length ? "all" : "none" };
+}
+/** Components in which `backup` applies more than `primary`, as `name: primary -> backup`. */
+export function sandboxCapExcess(primary, backup) {
+    const out = [];
+    if (NETWORK_RANK[backup.network] > NETWORK_RANK[primary.network])
+        out.push(`network: ${primary.network} -> ${backup.network}`);
+    if (backup.localBinding && !primary.localBinding)
+        out.push("local_binding: off -> on");
+    if (backup.unixSockets && !primary.unixSockets)
+        out.push("unix_sockets: off -> on");
+    return out;
+}

package/dist/run-session.js

@@ -1,7 +1,8 @@
 import fs from "node:fs";
 import path from "node:path";
+import { invokeWithSandboxChecks } from "./sandbox-invocation.js";
 import { realInvoker } from "./adapters/index.js";
-import { agentForCandidate, candidatesFor, Cooldowns, defaultSleep, planAttempts, runWithFallback } from "./fallback.js";
+import { agentForCandidate, candidatesFor, Cooldowns, defaultSleep, deferredAttempts, planAttempts, runWithFallback } from "./fallback.js";
 import { briefOf, digestOf, doneContract, mergeSteps, parseSteps } from "./format.js";
 import { ProtectedGuard } from "./guard.js";
 import { listRunLocks, lockHolderAlive } from "./project-lock.js";
@@ -580,6 +581,8 @@ export class RunSession {
         const all = candidatesFor(agent, tier && agent.tiers ? modelForTier(agent.tiers, tier) : undefined);
         const chain = all.length > 1;
         const candidates = chain ? planAttempts(all, cooldowns, Date.now()) : all;
+        // Models cooling down at the start are not dropped for good: when the warm ones fail they are tried last, once recovered.
+        const deferred = chain && candidates.length < all.length ? deferredAttempts(all, cooldowns, Date.now()).filter((c) => !candidates.includes(c)) : [];
         const ceiling = must(all.find((c) => c.primary), "the agent's own model");
         const tieredFirst = all[0]?.tiered ? all[0] : undefined;
         // The model a backup's calls stand in for: the one switched away from in this wake, or the cooling-down primary it started past.
@@ -594,6 +597,7 @@ export class RunSession {
         let stoppedByCancel = false;
         const outcome = await runWithFallback({
             candidates,
+            deferred,
             legacy: !chain,
             retry: cfg.retry,
             cooldowns,
@@ -609,6 +613,12 @@ export class RunSession {
                 // The round limit (when one is set) ends the run; this message stays unread for the resume.
                 return state.max_rounds > 0 && state.rounds >= state.max_rounds ? "stop" : undefined;
             },
+            onCooldownWait: (c, ms) => {
+                if (opts.signal?.aborted)
+                    return;
+                say(`  ${agent.name}: no other model is available; waiting ${Math.ceil(ms / 1000)}s for ${modelLabel(c)} to recover`);
+                log("cooldown_wait", { agent: agent.name, model: modelLabel(c), wait_ms: ms });
+            },
             onSwitch: (from, to, kind) => {
                 if (!from.tiered)
                     replaced = from;
@@ -651,14 +661,14 @@ export class RunSession {
                 const activeHandling = unread.map((m, i) => ({ ...handling[i], digest: digestOf(m.meta.type, m.body, true) }));
                 state.active[agent.name] = { round, since: new Date(started).toISOString(), handling: activeHandling };
                 this.saveState();
-                const result = await invoke({
+                const result = await invokeWithSandboxChecks(invoke, {
                     ...base,
                     agent: runAs,
                     signal: opts.signal,
                     logDir: attemptLogDir(runDir, att.id),
                     userPrompt,
                     sessionId,
-                }).catch((e) => ({
+                }, agent, { event: (name, fields) => log(name, fields) }, attempt).catch((e) => ({
                     ok: false,
                     text: "",
                     exitCode: null,
@@ -724,6 +734,10 @@ export class RunSession {
                 fault("park:before-finish");
                 finishAttempt(runDir, att.id, "failed", { error: result.error, parked });
                 say(`  ${agent.name} failed: ${result.error ?? "unknown error"}`);
+                if (result.kind === "config" && result.error?.startsWith("sandbox refused")) {
+                    this.note(`${agent.name} attempt ${att.n} was refused before it started (${result.error}); nothing was run, so there are no side effects to undo.`);
+                    return result;
+                }
                 this.note(`${agent.name} attempt ${att.n} failed (${result.error ?? "unknown error"})${parked.length ? `; ${parked.length} output file(s) set aside in ${path.join("mail", "attempts", att.id, "outbox")}` : ""}. ` +
                     `Anything it already did outside its mailbox (file edits, commands) was not undone: side effects may have happened.`);
                 return result;

package/dist/sandbox-invocation.d.ts

@@ -0,0 +1,35 @@
+import type { WakeInput, WakeResult, Invoker } from "./adapters/types.js";
+import type { ResolvedAgent, ResolvedProject } from "./config.js";
+import { type SandboxPathConflict } from "./policy.js";
+/** Where the `sandbox` and `sandbox-refused` events go: the run's log, or stderr for `call` (spec 25.8). */
+export interface SandboxSink {
+    event(name: string, fields: Record<string, unknown>): void;
+}
+export interface ProtectedPath {
+    path: string;
+    reason: string;
+}
+/**
+ * Everything a sandbox allowance must not reach (spec 25.4.3), canonical. `deep` adds the per-invocation items: the concrete
+ * write policy's deny list, bound workspaces and the git common dir. The agent's own checkout is left out: it is already writable.
+ */
+export declare function protectedPathsFor(project: ResolvedProject, agent: ResolvedAgent, deep: boolean): ProtectedPath[];
+export declare function describeConflict(agent: string, c: SandboxPathConflict, when: "load" | "invocation"): string;
+/** Conflicts of one agent's `write`/`unix_sockets` with the protected set. */
+export declare function sandboxConflictsOf(project: ResolvedProject, agent: ResolvedAgent, deep: boolean): SandboxPathConflict[];
+/** Capability excess of each backup of `agent` over its primary (spec 25.9): `[candidate label, excess...]`. */
+export declare function fallbackCapExcess(agent: ResolvedAgent): {
+    label: string;
+    excess: string[];
+}[];
+/** The refusal, if any, for this invocation. */
+export declare function sandboxRefusal(input: WakeInput, base: ResolvedAgent): {
+    reason: string;
+    path?: string;
+} | undefined;
+/**
+ * The one entry every adapter invocation goes through (spec 25.4.3, 25.19.1): refuses (returning a `config` failure, never
+ * throwing, never spawning) when an allowance reaches a protected path or a backup would widen them; otherwise records
+ * the `sandbox` event and calls `invoke`. An agent without `sandbox`, and a policy-override wake, go straight through.
+ */
+export declare function invokeWithSandboxChecks(invoke: Invoker, input: WakeInput, base: ResolvedAgent, sink: SandboxSink, attempt: number): Promise<WakeResult>;

package/dist/sandbox-invocation.js

@@ -0,0 +1,186 @@
+import { execFileSync } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { canonicalPath } from "./paths.js";
+/**
+ * `canonicalPath` for the sandbox check: a path that is missing (ENOENT/ENOTDIR) falls back to its nearest existing ancestor as
+ * usual, but any other realpath error (EACCES, ELOOP, ...) throws so the invocation is refused (fail closed).
+ */
+function strictCanonical(p) {
+    for (let head = path.resolve(p);; head = path.dirname(head)) {
+        try {
+            fs.realpathSync.native(head);
+            break;
+        }
+        catch (e) {
+            const code = e.code;
+            if (code !== "ENOENT" && code !== "ENOTDIR")
+                throw new Error(`cannot resolve ${head} (${code ?? e.message})`);
+            if (path.dirname(head) === head)
+                break;
+        }
+    }
+    return canonicalPath(p);
+}
+import { inboxDir, memoryDirs, osSandboxAvailable, outboxDir, recordsDir, repoDirFor, repoInstructionFiles, sandboxCapExcess, sandboxCaps, sandboxPathConflicts, sharedContextFiles, writePolicy, } from "./policy.js";
+/** Whether `cwd` or a parent holds a `.git` entry (a directory, or the file of a linked worktree). */
+function insideGitCheckout(cwd) {
+    for (let d = path.resolve(cwd);; d = path.dirname(d)) {
+        if (fs.existsSync(path.join(d, ".git")))
+            return true;
+        if (path.dirname(d) === d)
+            return false;
+    }
+}
+/**
+ * `git rev-parse --git-common-dir` of `cwd`, absolute; undefined when `cwd` is not in a git checkout. Fails closed: when it is a
+ * checkout but the probe fails, throws, so the invocation is refused instead of running with the shared git dir unprotected.
+ */
+function gitCommonDir(cwd) {
+    try {
+        const out = execFileSync("git", ["rev-parse", "--git-common-dir"], { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], timeout: 5000 }).trim();
+        if (out)
+            return path.resolve(cwd, out);
+    }
+    catch (e) {
+        if (!insideGitCheckout(cwd))
+            return undefined;
+        throw new Error(`cannot find the git common dir of ${cwd} (git rev-parse --git-common-dir failed: ${e.message.split("\n")[0]})`);
+    }
+    if (insideGitCheckout(cwd))
+        throw new Error(`cannot find the git common dir of ${cwd} (git rev-parse --git-common-dir printed nothing)`);
+    return undefined;
+}
+/**
+ * Everything a sandbox allowance must not reach (spec 25.4.3), canonical. `deep` adds the per-invocation items: the concrete
+ * write policy's deny list, bound workspaces and the git common dir. The agent's own checkout is left out: it is already writable.
+ */
+export function protectedPathsFor(project, agent, deep) {
+    const out = [];
+    const add = (p, reason) => {
+        if (p)
+            out.push({ path: canonicalPath(p), reason });
+    };
+    add(project.home, "agent-lyceum home");
+    add(project.dir, "project directory");
+    add(path.join(os.homedir(), ".claude"), "Claude Code settings");
+    add(process.env.CODEX_HOME || path.join(os.homedir(), ".codex"), "Codex settings");
+    for (const a of Object.values(project.agents)) {
+        add(a.agentMd, `AGENT.md of ${a.name}`);
+        for (const m of memoryDirs(a))
+            add(m, `memory of ${a.name}`);
+        add(outboxDir(project, a.name), `outbox of ${a.name}`);
+        add(inboxDir(project, a.name), `inbox of ${a.name}`);
+    }
+    for (const f of sharedContextFiles(project))
+        add(f, "shared context");
+    for (const f of repoInstructionFiles(project))
+        add(f, "repo instruction file");
+    add(recordsDir(project), "project records");
+    if (!deep)
+        return out;
+    for (const d of writePolicy(project, agent).deny)
+        add(d, "write-protected path");
+    if (project.run)
+        add(project.run.dir, "run directory");
+    add(path.join(project.paths.root, "worktrees"), "worktrees root");
+    const own = project.workspaces?.[agent.name];
+    for (const [name, ws] of Object.entries(project.workspaces ?? {})) {
+        if (name === agent.name)
+            continue;
+        add(ws.root, `workspace of ${name}`);
+        add(ws.gitDir, `git dir of ${name}`);
+        add(ws.commonDir, "git common dir");
+    }
+    // The agent's own checkout and git dir are already inside its write scope, so they are not listed; the shared common dir is.
+    add(own?.commonDir ?? gitCommonDir(repoDirFor(project, agent.name)), "git common dir");
+    return out;
+}
+export function describeConflict(agent, c, when) {
+    const suffix = when === "invocation" ? " (checked before invocation)" : "";
+    const rel = c.relation === "equal" ? "is" : c.relation === "inside" ? "is inside" : "contains";
+    return `agent ${agent}: sandbox.${c.key}[${c.index}] ${c.path} ${rel} protected path ${c.protectedPath} (${c.reason}); pick a different directory.${suffix}`;
+}
+/** Conflicts of one agent's `write`/`unix_sockets` with the protected set. */
+export function sandboxConflictsOf(project, agent, deep) {
+    const s = agent.sandbox;
+    if (!s)
+        return [];
+    const entries = [
+        ...s.write.map((p, index) => ({ key: "write", index, path: canonicalPath(p) })),
+        ...s.unixSockets.map((p, index) => ({ key: "unix_sockets", index, path: canonicalPath(p) })),
+    ];
+    return sandboxPathConflicts(entries, protectedPathsFor(project, agent, deep));
+}
+/** Capability excess of each backup of `agent` over its primary (spec 25.9): `[candidate label, excess...]`. */
+export function fallbackCapExcess(agent) {
+    if (!agent.sandbox || !agent.runtime)
+        return [];
+    const primary = sandboxCaps(agent, agent.runtime);
+    const out = [];
+    for (const f of agent.fallback) {
+        const excess = sandboxCapExcess(primary, sandboxCaps(agent, f.runtime));
+        if (excess.length)
+            out.push({ label: `${f.runtime}/${f.model || "(default model)"}`, excess });
+    }
+    return out;
+}
+/** The refusal, if any, for this invocation. */
+export function sandboxRefusal(input, base) {
+    const agent = input.agent;
+    if (!agent.sandbox)
+        return undefined;
+    for (const p of [...agent.sandbox.write, ...agent.sandbox.unixSockets])
+        strictCanonical(p);
+    const c = sandboxConflictsOf(input.project, agent, true)[0];
+    if (c)
+        return { reason: describeConflict(agent.name, c, "invocation"), path: c.path };
+    const f = fallbackCapExcess(base)[0];
+    if (f)
+        return { reason: `agent ${base.name}: fallback ${f.label} would apply more sandbox allowance than the primary (${f.excess.join("; ")}) (checked before invocation)` };
+    return undefined;
+}
+function applied(agent) {
+    const caps = sandboxCaps(agent);
+    const osOn = osSandboxAvailable();
+    if (!osOn)
+        return { write: agent.runtime === "claude-code" ? "tool-rules" : "none", network: "unrestricted", local_binding: "unrestricted", unix_sockets: "unrestricted" };
+    return { write: "os", network: caps.network, local_binding: caps.localBinding ? "on" : "off", unix_sockets: caps.unixSockets ? "on" : "off" };
+}
+/**
+ * The one entry every adapter invocation goes through (spec 25.4.3, 25.19.1): refuses (returning a `config` failure, never
+ * throwing, never spawning) when an allowance reaches a protected path or a backup would widen them; otherwise records
+ * the `sandbox` event and calls `invoke`. An agent without `sandbox`, and a policy-override wake, go straight through.
+ */
+export async function invokeWithSandboxChecks(invoke, input, base, sink, attempt) {
+    const agent = input.agent;
+    if (!agent.sandbox || input.policy)
+        return invoke(input);
+    const refuse = (reason) => ({ ok: false, text: "", exitCode: null, timedOut: false, error: `sandbox refused: ${reason}`, kind: "config" });
+    try {
+        const bad = sandboxRefusal(input, base);
+        if (bad) {
+            sink.event("sandbox-refused", { agent: agent.name, runtime: agent.runtime, reason: bad.reason, ...(bad.path ? { path: bad.path } : {}) });
+            return refuse(bad.reason);
+        }
+        const s = agent.sandbox;
+        sink.event("sandbox", {
+            agent: agent.name,
+            runtime: agent.runtime,
+            model: agent.model,
+            attempt,
+            write: s.write.map(canonicalPath),
+            network: s.network,
+            local_binding: s.localBinding,
+            unix_sockets: s.unixSockets.map(canonicalPath),
+            applied: applied(agent),
+        });
+    }
+    catch (e) {
+        const reason = `${agent.name}: sandbox check failed: ${e.message}`;
+        sink.event("sandbox-refused", { agent: agent.name, runtime: agent.runtime, reason });
+        return refuse(reason);
+    }
+    return invoke(input);
+}

package/dist/schema.d.ts

@@ -12,7 +12,7 @@ export declare function inferRuntime(model: string | undefined): Runtime | undef
 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 declare const ERROR_KINDS: readonly ["rate_limit", "quota", "timeout", "network", "crash", "auth", "config", "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 {
@@ -37,6 +37,14 @@ export declare const FallbackEntryPartial: z.ZodObject<{
     }>>;
 }, z.core.$strict>;
 export type FallbackEntryPartialT = z.infer<typeof FallbackEntryPartial>;
+/** Per-agent sandbox allowances (spec 25); every key is optional and absent = none. */
+export declare const SandboxPartial: z.ZodObject<{
+    write: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    network: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    local_binding: z.ZodOptional<z.ZodBoolean>;
+    unix_sockets: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strict>;
+export type SandboxPartialT = z.infer<typeof SandboxPartial>;
 export declare const AgentPartial: z.ZodObject<{
     runtime: z.ZodOptional<z.ZodEnum<{
         "claude-code": "claude-code";
@@ -80,6 +88,12 @@ export declare const AgentPartial: z.ZodObject<{
             xhigh: "xhigh";
         }>>;
     }, z.core.$strict>>>;
+    sandbox: z.ZodOptional<z.ZodObject<{
+        write: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        network: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        local_binding: z.ZodOptional<z.ZodBoolean>;
+        unix_sockets: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>>;
     owns: z.ZodOptional<z.ZodUnknown>;
 }, z.core.$strict>;
 export type AgentPartialT = z.infer<typeof AgentPartial>;
@@ -168,6 +182,12 @@ export declare const GlobalConfig: z.ZodObject<{
                 xhigh: "xhigh";
             }>>;
         }, z.core.$strict>>>;
+        sandbox: z.ZodOptional<z.ZodObject<{
+            write: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            network: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            local_binding: z.ZodOptional<z.ZodBoolean>;
+            unix_sockets: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        }, z.core.$strict>>;
         owns: z.ZodOptional<z.ZodUnknown>;
     }, z.core.$strict>>>;
 }, z.core.$strict>;
@@ -250,6 +270,12 @@ export declare const ProjectConfig: z.ZodObject<{
                 xhigh: "xhigh";
             }>>;
         }, z.core.$strict>>>;
+        sandbox: z.ZodOptional<z.ZodObject<{
+            write: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            network: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            local_binding: z.ZodOptional<z.ZodBoolean>;
+            unix_sockets: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        }, z.core.$strict>>;
         owns: z.ZodOptional<z.ZodUnknown>;
     }, z.core.$strict>>>;
 }, z.core.$strict>;

package/dist/schema.js

@@ -21,7 +21,7 @@ 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"];
+export const ERROR_KINDS = ["rate_limit", "quota", "timeout", "network", "crash", "auth", "config", "unknown"];
 const Memory = z
     .object({
     global: z.string().optional(),
@@ -36,6 +36,18 @@ export const FallbackEntryPartial = z
     effort: z.enum(EFFORTS).optional(),
 })
     .strict();
+const DOMAIN_RE = /^(\*\.)?([a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,63}$/;
+/** Per-agent sandbox allowances (spec 25); every key is optional and absent = none. */
+export const SandboxPartial = z
+    .object({
+    write: z.array(z.string().trim().min(1)).optional(),
+    network: z
+        .array(z.string().trim().toLowerCase().regex(DOMAIN_RE, "expected a host name like registry.npmjs.org or *.example.com (no scheme, port, path or IP)"))
+        .optional(),
+    local_binding: z.boolean().optional(),
+    unix_sockets: z.array(z.string().trim().min(1)).optional(),
+})
+    .strict();
 export const AgentPartial = z
     .object({
     runtime: z.enum(RUNTIMES).optional(),
@@ -49,6 +61,7 @@ export const AgentPartial = z
     can_ask_user: z.boolean().optional(),
     allow_web: z.enum(WEB_LEVELS).optional(),
     fallback: z.array(FallbackEntryPartial).optional(),
+    sandbox: SandboxPartial.optional(),
     /** Removed setting: still accepted (any value) so old files load; ignored, with a warning from `validate`. */
     owns: z.unknown().optional(),
 })

package/dist/validate.js

@@ -1,5 +1,6 @@
 import fs from "node:fs";
 import { enforcementFor, memoryDirs } from "./policy.js";
+import { describeConflict, fallbackCapExcess, sandboxConflictsOf } from "./sandbox-invocation.js";
 import { isInside } from "./paths.js";
 import { inferRuntime, RUNTIME_EFFORTS, RUNTIMES } from "./schema.js";
 import { ladderIndex } from "./tiers.js";
@@ -50,6 +51,10 @@ export function validateProject(project) {
             err(`Agent "${a.name}": effort "${a.effort}" is not supported by ${a.runtime} (use ${RUNTIME_EFFORTS[a.runtime].join(", ")}).`);
         }
         validateFallback(project, a, err);
+        for (const c of sandboxConflictsOf(project, a, false))
+            err(describeConflict(a.name, c, "load"));
+        for (const f of fallbackCapExcess(a))
+            err(`agent ${a.name}: fallback ${f.label} would apply more sandbox allowance than the primary (${f.excess.join("; ")}).`);
         if (!fs.existsSync(a.agentMd))
             err(`Agent "${a.name}": AGENT.md not found at ${a.agentMd}`);
         if (!a.memory.global && !a.memory.project)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-lyceum",
-  "version": "0.27.0",
+  "version": "0.28.0",
   "description": "Config + dispatcher for teams of Claude Code / Codex agents with scoped context and file-based mailboxes",
   "keywords": [
     "ai",