agent-lyceum 0.27.0 → 0.29.0

package/README.md

@@ -49,7 +49,7 @@ Its own data (config, mailboxes, logs, memory, worktrees) lives in `~/agent-lyce
 | `init` | Create the home and the global agent library. [details](docs/commands.md#init) |
 | `project add` / `project` / `project remove` | Register, list or remove projects. [details](docs/commands.md#project-add) |
 | `doctor` | Check config, git, lock and runtime CLIs without running agents. [details](docs/commands.md#doctor) |
-| `status` | Show agents, mail, the current wake-up and past runs. [details](docs/commands.md#status) |
+| `status` | Show agents, mail, the current wake-up and past runs. `status --web` opens every registered project in a browser. [details](docs/commands.md#status) |
 | `run` | Give the task to the lead and run until done. [details](docs/commands.md#run) |
 | `resume` | Continue an interrupted run, or reopen a finished one with a follow-up. [details](docs/commands.md#resume) |
 | `clear` | Delete a run, or remove a stale lock. [details](docs/commands.md#clear) |

package/README.zh-TW.md

@@ -49,7 +49,7 @@ npx agent-lyceum status
 | `init` | 建立 home 與全域 agent 庫。 [詳細](docs/commands.zh-TW.md#init) |
 | `project add` / `project` / `project remove` | 註冊、列出或移除專案。 [詳細](docs/commands.zh-TW.md#project-add) |
 | `doctor` | 不執行 agent，檢查設定、git、鎖與 runtime CLI。 [詳細](docs/commands.zh-TW.md#doctor) |
-| `status` | 顯示 agent、信件、目前的喚醒與過去的 run。 [詳細](docs/commands.zh-TW.md#status) |
+| `status` | 顯示 agent、信件、目前的喚醒與過去的 run。`status --web` 在瀏覽器看全部已註冊專案。 [詳細](docs/commands.zh-TW.md#status) |
 | `run` | 把任務交給 lead，執行到完成。 [詳細](docs/commands.zh-TW.md#run) |
 | `resume` | 繼續中斷的 run，或用追加需求重開已完成的 run。 [詳細](docs/commands.zh-TW.md#resume) |
 | `clear` | 刪除 run，或移除殘留的鎖。 [詳細](docs/commands.zh-TW.md#clear) |

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/cli.js

@@ -3,6 +3,7 @@ import fs from "node:fs";
 import path from "node:path";
 import readline from "node:readline/promises";
 import { spawnSync } from "node:child_process";
+import { fileURLToPath, pathToFileURL } from "node:url";
 import { Command } from "commander";
 import { ConfigError, findProjectForCwd, flattenResolved, listProjects, loadGlobal, resolveProject, resolveProjectWithSources } from "./config.js";
 import { openInEditor, prepareAnswers } from "./ask-answer.js";
@@ -27,6 +28,7 @@ import { createStatusWatcher } from "./status-watch.js";
 import { LAUNCH_PPID, startedByWrapper, watchParent } from "./parent-watch.js";
 import { onlyAgent, soloProject } from "./solo.js";
 import { DEMO_PROJECT, DEMO_TASK, defaultDemoDir, detectRuntime, prepareDemo } from "./demo.js";
+import { claudeQuota, codexQuota } from "./quota.js";
 const program = new Command();
 program
     .name("agent-lyceum")
@@ -764,9 +766,57 @@ program
     .option("--interval <sec>", "refresh interval for --monitor", "2")
     .option("--json", "print the report as JSON (no colour); works with --task-list and --task-id")
     .option("--watch", "with --json: keep running and print one JSON line (the project report plus one per running task) whenever it changes (Ctrl-C to quit)")
-    .option("--heartbeat <sec>", "with --watch: how often to re-check when no file event came", "5")
+    .option("--heartbeat <sec>", "with --watch or --web: how often to re-check when no file event came", "5")
+    .option("--web", "open a local page for every registered project")
+    .option("--port <n>", "with --web: TCP port", "8787")
+    .option("--host <addr>", "with --web: bind address", "127.0.0.1")
+    .option("--no-open", "with --web: do not open a browser")
     .action(async (opts) => {
     try {
+        if (opts.web) {
+            if (opts.json || opts.watch || opts.monitor || opts.taskList || opts.taskId !== undefined)
+                fail("--web cannot be combined with --json, --watch, --monitor, --task-list or --task-id.");
+            if (opts.project)
+                fail("--web shows every registered project; it does not take --project.");
+            const port = Number(opts.port);
+            if (!Number.isInteger(port) || port < 1 || port > 65535)
+                fail("--port must be a TCP port.");
+            const beat = Number(opts.heartbeat);
+            if (!(beat > 0))
+                fail("--heartbeat must be a positive number of seconds.");
+            const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+            const entry = path.join(root, "web", "dist", "start.js");
+            const staticDir = path.join(root, "web", "dist", "public");
+            if (!fs.existsSync(entry) || !fs.existsSync(path.join(staticDir, "index.html"))) {
+                fail(`The web monitor is not built.\nFrom the repo: pnpm --dir web install && pnpm --dir web build\nExpected ${entry}`);
+            }
+            const mod = (await import(pathToFileURL(entry).href));
+            const page = await mod.startWebServer({
+                port,
+                host: opts.host,
+                open: opts.open !== false,
+                staticDir,
+                heartbeatMs: beat * 1000,
+                factory: {
+                    list: () => listProjects(home()).map((item) => item.name),
+                    watch: (name, onFrame) => createStatusWatcher({
+                        load: () => resolveProject(home(), name),
+                        dir: (project) => project.paths.runs,
+                        write: (line) => onFrame(JSON.parse(line)),
+                        debounceMs: 100,
+                        allTasks: true,
+                    }),
+                    quota: () => Promise.all([claudeQuota(), codexQuota()]),
+                },
+            });
+            console.log(page.url);
+            const stop = (code) => {
+                void page.close().finally(() => process.exit(code));
+            };
+            process.on("SIGINT", () => stop(130));
+            process.on("SIGTERM", () => stop(143));
+            await new Promise(() => { });
+        }
         if (opts.watch) {
             if (!opts.json)
                 fail("--watch needs --json.");

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/project-lock.d.ts

@@ -44,6 +44,8 @@ export interface PidStartIo {
 }
 /** A start time that identifies one process: `proc:<ticks>` on Linux, the `ps` text elsewhere or when /proc cannot be read. */
 export declare function pidStartFrom(pid: number, io: PidStartIo): string | undefined;
+/** True when both strings name the same process start. Locale-specific `ps` text for one instant matches. */
+export declare function samePidStart(a: string, b: string): boolean;
 /**
  * Is the process that wrote this lock still the same running process? Judged by pid and its start time,
  * never by hostname (macOS changes it with the network) or by heartbeat age (a busy holder may be late).

package/dist/project-lock.js

@@ -50,7 +50,8 @@ const realIo = {
         }
     },
     ps: (pid) => {
-        const r = spawnSync("ps", ["-o", "lstart=", "-p", String(pid)], { encoding: "utf8" });
+        // C locale: `ps` start times stay in one language. A lock written from a Chinese terminal would otherwise look like a different process.
+        const r = spawnSync("ps", ["-o", "lstart=", "-p", String(pid)], { encoding: "utf8", env: { ...process.env, LANG: "C", LC_ALL: "C" } });
         const out = r.status === 0 ? r.stdout.trim() : "";
         return out || undefined;
     },
@@ -60,6 +61,30 @@ function pidStart(pid) {
 }
 /** Two start times can only be compared when they were taken the same way. */
 const sameKind = (a, b) => a.startsWith("proc:") === b.startsWith("proc:");
+const MONTHS = { Jan: "01", Feb: "02", Mar: "03", Apr: "04", May: "05", Jun: "06", Jul: "07", Aug: "08", Sep: "09", Oct: "10", Nov: "11", Dec: "12" };
+/** `ps -o lstart` in the C locale, or the same instant from a Chinese macOS locale, as `YYYY-MM-DDTHH:mm:ss`. */
+function canonicalLstart(text) {
+    const s = text.trim();
+    const en = /^[A-Za-z]{3}\s+([A-Za-z]{3})\s+(\d{1,2})\s+(\d{2}):(\d{2}):(\d{2})\s+(\d{4})$/.exec(s);
+    if (en) {
+        const month = MONTHS[en[1] ?? ""];
+        if (!month)
+            return undefined;
+        return `${en[6]}-${month}-${(en[2] ?? "").padStart(2, "0")}T${en[3]}:${en[4]}:${en[5]}`;
+    }
+    const zh = /^\S+\s+(\d{1,2})月\/\s*(\d{1,2})\s+(\d{2}):(\d{2}):(\d{2})\s+(\d{4})$/.exec(s);
+    if (zh)
+        return `${zh[6]}-${(zh[1] ?? "").padStart(2, "0")}-${(zh[2] ?? "").padStart(2, "0")}T${zh[3]}:${zh[4]}:${zh[5]}`;
+    return undefined;
+}
+/** True when both strings name the same process start. Locale-specific `ps` text for one instant matches. */
+export function samePidStart(a, b) {
+    if (a === b)
+        return true;
+    const left = canonicalLstart(a);
+    const right = canonicalLstart(b);
+    return !!left && left === right;
+}
 /**
  * Is the process that wrote this lock still the same running process? Judged by pid and its start time,
  * never by hostname (macOS changes it with the network) or by heartbeat age (a busy holder may be late).
@@ -74,7 +99,7 @@ export function lockHolderAlive(info) {
     }
     if (info.pid_started) {
         const now = pidStart(info.pid);
-        if (now && sameKind(now, info.pid_started) && now !== info.pid_started)
+        if (now && sameKind(now, info.pid_started) && !samePidStart(info.pid_started, now))
             return false;
     }
     return true;

package/dist/quota.d.ts

@@ -0,0 +1,25 @@
+export type QuotaWindow = {
+    label: string;
+    used_percent: number;
+    remaining_percent: number;
+    resets: string;
+};
+export type QuotaReport = {
+    runtime: "claude" | "codex";
+    windows: QuotaWindow[];
+    error?: string;
+};
+export declare function parseClaudeUsage(text: string): QuotaWindow[];
+type LimitWindow = {
+    usedPercent?: number;
+    windowDurationMins?: number;
+    resetsAt?: number;
+};
+type RateLimits = {
+    primary?: LimitWindow | null;
+    secondary?: LimitWindow | null;
+};
+export declare function codexWindows(limits: RateLimits): QuotaWindow[];
+export declare function claudeQuota(): Promise<QuotaReport>;
+export declare function codexQuota(): Promise<QuotaReport>;
+export {};