agent-lyceum 0.29.0 → 0.31.0

package/README.md

@@ -9,7 +9,7 @@ Give a task to a **team of agents** (Claude Code and/or Codex) instead of one ov
 ## Why
 
 - **Roles that stay in role.** Each agent has its own persona (`AGENT.md`) and long-term memory, so a reviewer keeps reviewing instead of drifting into writing code.
-- **Agents can't rewrite the rules.** An agent can only write its own memory and outbox. It can't touch other agents' context or its own persona, and this is enforced by the OS sandbox where possible, not just by a prompt. See [Write scope](docs/write-scope.md).
+- **Agents can't rewrite the rules.** An agent can write its own memory, its outbox, and its project agent directory (`agents/<name>/`, including a project persona it creates there). It can't touch other agents' context, `COMMON.md`, the project records, or a global persona. This is enforced by the OS sandbox where possible, not just by a prompt. See [Write scope](docs/write-scope.md).
 - **Mix runtimes.** Claude Code and Codex agents work in the same team.
 - **Backup models.** If a model is rate-limited, out of quota or unreachable, a run can switch to a backup model or runtime instead of stopping. See [Configuration](docs/configuration.md#fallback-models).
 - **Nothing hidden.** Agents talk through plain-file mailboxes, so every message, decision and memory is a file you can read, grep and diff. The dispatcher never merges for you.

package/README.zh-TW.md

@@ -9,7 +9,7 @@
 ## 為什麼用它
 
 - **角色不會跑掉。** 每個 agent 有自己的人設（`AGENT.md`）與長期記憶，reviewer 會一直做 review，不會漸漸變成在寫程式。
-- **agent 改不了規則。** agent 只能寫自己的記憶與寄件匣（outbox），不能改其他 agent 的 context，也不能改自己的人設；能做到的地方由 OS 沙箱強制，而不只靠 prompt。見 [Write scope](docs/write-scope.zh-TW.md)。
+- **agent 改不了規則。** agent 可以寫自己的記憶、寄件匣（outbox），以及自己的專案 agent 目錄（`agents/<name>/`，含它在那裡建立的專案人設）。它不能改其他 agent 的 context、`COMMON.md`、專案紀錄，或全域人設。能做到的地方由 OS 沙箱強制，而不只靠 prompt。見 [Write scope](docs/write-scope.zh-TW.md)。
 - **混用 runtime。** Claude Code 與 Codex agent 可在同一個團隊。
 - **備用模型。** 模型被限流、額度用完或連不上時，run 可以改用備用的模型或 runtime 繼續，而不是直接停下。見[設定](docs/configuration.zh-TW.md#備援模型)。
 - **沒有黑箱。** agent 透過純檔案信箱溝通，每則訊息、決策與記憶都是你能讀、能 grep、能 diff 的檔案；dispatcher 不會替你 merge。

package/dist/adapters/codex.js

@@ -1,10 +1,13 @@
 import fs from "node:fs";
 import path from "node:path";
-import { repoDirFor, scratchCwd, writePolicy } from "../policy.js";
+import { projectCommonDir, projectCommonDirAllowed, repoDirFor, scratchCwd, writePolicy } from "../policy.js";
 export function codexWritableRoots(input) {
     const pol = input.policy ?? writePolicy(input.project, input.agent);
     const work = input.policy ? scratchCwd(input.workDir) : repoDirFor(input.project, input.agent.name);
-    const roots = [...pol.allowDirs, ...pol.allowFiles.map((f) => path.dirname(f))].filter((d) => !(d === work || d.startsWith(work + path.sep)));
+    const common = projectCommonDir(input.project);
+    const withholdCommon = !input.policy && !projectCommonDirAllowed(input.project, input.agent);
+    const fileRoots = pol.allowFiles.map((f) => path.dirname(f)).filter((d) => !withholdCommon || (d !== common && !d.startsWith(common + path.sep)));
+    const roots = [...pol.allowDirs, ...fileRoots].filter((d) => !(d === work || d.startsWith(work + path.sep)));
     return [...new Set(roots)];
 }
 function sessionIdOf(line) {

package/dist/cli.js

@@ -24,6 +24,7 @@ import { callAgent, callProject, callsDir, resolveCallAgent } from "./call.js";
 import { formatEnforcement, validateProject } from "./validate.js";
 import { must } from "./assert.js";
 import { runMonitor } from "./monitor-lifecycle.js";
+import { codeFingerprint, watchCodeChange, WATCH_RESTART_EXIT, WATCH_RESTART_MESSAGE } from "./code-change.js";
 import { createStatusWatcher } from "./status-watch.js";
 import { LAUNCH_PPID, startedByWrapper, watchParent } from "./parent-watch.js";
 import { onlyAgent, soloProject } from "./solo.js";
@@ -832,8 +833,22 @@ program
                 write: (line) => process.stdout.write(`${line}\n`),
                 debounceMs: 100,
             });
+            const codeFile = fileURLToPath(import.meta.url);
+            const changed = watchCodeChange(() => codeFingerprint(path.dirname(codeFile), path.extname(codeFile)));
             runMonitor({
-                draw: watcher.beat,
+                draw: () => {
+                    if (changed()) {
+                        try {
+                            fs.writeSync(2, `${WATCH_RESTART_MESSAGE}\n`);
+                        }
+                        catch {
+                            // A closed stderr must not prevent replacement.
+                        }
+                        watcher.close();
+                        process.exit(WATCH_RESTART_EXIT);
+                    }
+                    watcher.beat();
+                },
                 intervalMs: beat * 1000,
                 stdout: process.stdout,
                 stdin: process.stdin,

package/dist/code-change.d.ts

@@ -0,0 +1,6 @@
+export declare const WATCH_RESTART_EXIT = 75;
+export declare const WATCH_RESTART_MESSAGE = "status --watch: agent-lyceum code changed on disk; restart to load it";
+/** Sorted relative paths, sizes and mtimes; unreadable trees never trigger a restart. */
+export declare function codeFingerprint(dir: string, ext: string): string;
+/** Two equal reads debounce changes; they do not establish build completion. */
+export declare function watchCodeChange(read: () => string): () => boolean;

package/dist/code-change.js

@@ -0,0 +1,37 @@
+import fs from "node:fs";
+import path from "node:path";
+export const WATCH_RESTART_EXIT = 75;
+export const WATCH_RESTART_MESSAGE = "status --watch: agent-lyceum code changed on disk; restart to load it";
+/** Sorted relative paths, sizes and mtimes; unreadable trees never trigger a restart. */
+export function codeFingerprint(dir, ext) {
+    const files = [];
+    function visit(relative) {
+        for (const entry of fs.readdirSync(path.join(dir, relative), { withFileTypes: true })) {
+            const rel = path.join(relative, entry.name);
+            if (entry.isDirectory())
+                visit(rel);
+            else if (entry.isFile() && path.extname(entry.name) === ext) {
+                const stat = fs.statSync(path.join(dir, rel));
+                files.push(`${rel}:${stat.size}:${stat.mtimeMs}`);
+            }
+        }
+    }
+    try {
+        visit("");
+        return files.sort().join("\n");
+    }
+    catch {
+        return "";
+    }
+}
+/** Two equal reads debounce changes; they do not establish build completion. */
+export function watchCodeChange(read) {
+    const initial = read();
+    let previous = initial;
+    return () => {
+        const current = read();
+        const changed = current !== "" && current !== initial && current === previous;
+        previous = current;
+        return changed;
+    };
+}

package/dist/guard.d.ts

@@ -24,7 +24,7 @@ export declare class ProtectedGuard {
     private project;
     private otherLiveRuns;
     private baseline;
-    /** Regular files of the records tree (including `.archive/`); only the lead may change them. */
+    /** Regular files of the records tree (including `.archive/`); any agent in the running batch may change them. */
     private records;
     /** Changes kept (not reverted) because another live run may have made them; see `takeUnattributed`. */
     private unattributed;

package/dist/guard.js

@@ -16,7 +16,7 @@ export class ProtectedGuard {
     project;
     otherLiveRuns;
     baseline = new Map();
-    /** Regular files of the records tree (including `.archive/`); only the lead may change them. */
+    /** Regular files of the records tree (including `.archive/`); any agent in the running batch may change them. */
     records = new Map();
     /** Changes kept (not reverted) because another live run may have made them; see `takeUnattributed`. */
     unattributed = [];
@@ -92,6 +92,16 @@ export class ProtectedGuard {
         const violations = [];
         const other = [...new Set([...this.liveAtBase, ...this.otherLiveRuns()])];
         for (const [file, before] of this.baseline) {
+            if (unsafeToRead(file)) {
+                const kept = this.keep(file, null);
+                fs.rmSync(file, { force: true });
+                if (before !== null) {
+                    fs.mkdirSync(path.dirname(file), { recursive: true });
+                    fs.writeFileSync(file, before);
+                }
+                violations.push({ file, action: before === null ? "removed" : "restored", suspects: running.map((a) => a.name), ...kept });
+                continue;
+            }
             const now = read(file);
             if (same(before, now))
                 continue;
@@ -126,7 +136,7 @@ export class ProtectedGuard {
         if (isLink(path.dirname(root)) || isLink(path.dirname(path.dirname(root))))
             return;
         const now = readTree(root);
-        const lead = running.some((a) => a.name === this.project.lead);
+        const authorized = running.some((a) => a.name === this.project.lead);
         const suspects = running.map((a) => a.name);
         const fixedDirs = new Set();
         for (const file of new Set([...this.records.keys(), ...now.keys()])) {
@@ -134,7 +144,7 @@ export class ProtectedGuard {
             const cur = now.get(file) ?? null;
             if (same(before, cur))
                 continue;
-            if (lead)
+            if (authorized)
                 continue;
             if (other.length) {
                 this.unattributed.push({ file, agents: suspects, otherRuns: other });
@@ -155,7 +165,7 @@ export class ProtectedGuard {
                 violations.push({ file, action: "restored", suspects, ...kept });
             }
         }
-        if (lead || other.length)
+        if (authorized || other.length)
             this.records = now;
     }
     /**
@@ -242,13 +252,55 @@ function readTree(dir) {
     walk(dir);
     return out;
 }
+const GUARD_READ_MAX = MAX_KEEP_BYTES * 2;
+/** A FIFO, device, directory, or a symlink to one. Opening it would block or is not a file the guard can compare. */
+function unsafeToRead(file) {
+    let fd;
+    try {
+        const listed = fs.lstatSync(file);
+        if (listed.isFIFO() || listed.isSocket() || listed.isCharacterDevice() || listed.isBlockDevice() || listed.isDirectory())
+            return true;
+        fd = fs.openSync(file, fs.constants.O_RDONLY | (fs.constants.O_NONBLOCK ?? 0));
+        return !fs.fstatSync(fd).isFile();
+    }
+    catch {
+        return false;
+    }
+    finally {
+        if (fd !== undefined) {
+            try {
+                fs.closeSync(fd);
+            }
+            catch {
+                // already closed
+            }
+        }
+    }
+}
 function read(file) {
+    let fd;
     try {
-        return fs.readFileSync(file);
+        fd = fs.openSync(file, fs.constants.O_RDONLY | (fs.constants.O_NONBLOCK ?? 0));
+        const st = fs.fstatSync(fd);
+        if (!st.isFile())
+            return null;
+        if (st.size > GUARD_READ_MAX)
+            return null;
+        return fs.readFileSync(fd);
     }
     catch {
         return null;
     }
+    finally {
+        if (fd !== undefined) {
+            try {
+                fs.closeSync(fd);
+            }
+            catch {
+                // already closed
+            }
+        }
+    }
 }
 function same(a, b) {
     if (a === null || b === null)

package/dist/policy.d.ts

@@ -23,7 +23,7 @@ export interface WritePolicy {
     deny: string[];
 }
 export declare function commonFile(project: ResolvedProject): string;
-/** Durable decisions and lessons of the project, one file per entry: the lead writes them, everyone else reads them. `.archive/` is tidy's output, never shown in prompts. */
+/** Durable decisions and lessons of the project, one file per entry. Only the lead may write them. `.archive/` is tidy's output, never shown in prompts. */
 export declare function recordsDir(project: ResolvedProject): string;
 export declare function recordsKindDir(project: ResolvedProject, kind: "decisions" | "lessons"): string;
 /** The lead-maintained files shared by every run of the project. */
@@ -43,6 +43,12 @@ export declare function sharedIndex(project: ResolvedProject): string | undefine
 export declare const scratchCwd: (workDir: string) => string;
 /** The repo directory this agent works in: its own worktree, or the main repo. */
 export declare function repoDirFor(project: ResolvedProject, agent: string): string;
+export declare function projectAgentDir(project: ResolvedProject, agentName: string): string;
+export declare function projectCommonDir(project: ResolvedProject): string;
+/** True when `agents/<name>/` stays inside the project agents directory and does not overlap another agent's protected paths. */
+export declare function ownAgentDirAllowed(project: ResolvedProject, agent: ResolvedAgent): boolean;
+/** True when `shared/common/` does not overlap another agent's persona, memory, inbox or outbox. */
+export declare function projectCommonDirAllowed(project: ResolvedProject, agent: ResolvedAgent): boolean;
 export declare function writePolicy(project: ResolvedProject, agent: ResolvedAgent): WritePolicy;
 export declare function osSandboxAvailable(): boolean;
 /** Test seam: pretend the OS sandbox is (un)available; `undefined` re-probes the host. */

package/dist/policy.js

@@ -5,7 +5,7 @@ import { canonicalPath } from "./paths.js";
 export function commonFile(project) {
     return path.join(project.paths.shared, "common", "COMMON.md");
 }
-/** Durable decisions and lessons of the project, one file per entry: the lead writes them, everyone else reads them. `.archive/` is tidy's output, never shown in prompts. */
+/** Durable decisions and lessons of the project, one file per entry. Only the lead may write them. `.archive/` is tidy's output, never shown in prompts. */
 export function recordsDir(project) {
     return path.join(project.paths.shared, "common", "records");
 }
@@ -76,6 +76,57 @@ export const scratchCwd = (workDir) => path.join(workDir, "cwd");
 export function repoDirFor(project, agent) {
     return project.workspaces?.[agent]?.dir ?? project.dir;
 }
+export function projectAgentDir(project, agentName) {
+    return path.join(project.paths.agentsDir, agentName);
+}
+export function projectCommonDir(project) {
+    return path.join(project.paths.shared, "common");
+}
+function covers(dir, target) {
+    const root = canonicalPath(dir);
+    const file = canonicalPath(target);
+    const prefix = root.endsWith(path.sep) ? root : root + path.sep;
+    return file === root || file.startsWith(prefix);
+}
+/** Another agent's persona, memory, inbox or outbox. A slot that shares this agent's persona file is not another persona. */
+function foreignProtectedPaths(project, agent, other) {
+    return [
+        ...(other.agentMd === agent.agentMd ? [] : [other.agentMd]),
+        inboxDir(project, other.name),
+        outboxDir(project, other.name),
+        ...memoryDirs(other),
+    ];
+}
+/**
+ * True when `dir` contains a foreign protected path, or sits inside one.
+ * Codex has no deny list inside a writable root, so either direction closes the root.
+ * Compared on real paths: a symlink grant is the target the sandbox would write if it follows links.
+ * Whether a live Claude or Codex sandbox follows that symlink was not verified; the directory is not granted either way.
+ */
+function overlapsForeign(project, agent, dir) {
+    for (const other of Object.values(project.agents)) {
+        if (other.name === agent.name)
+            continue;
+        if (foreignProtectedPaths(project, agent, other).some((p) => covers(dir, p) || covers(p, dir)))
+            return true;
+    }
+    return false;
+}
+/** True when the real path of `dir` is `parent` or a directory inside it. */
+function staysInside(dir, parent) {
+    const real = canonicalPath(dir);
+    const root = canonicalPath(parent);
+    return real === root || real.startsWith(root + path.sep);
+}
+/** True when `agents/<name>/` stays inside the project agents directory and does not overlap another agent's protected paths. */
+export function ownAgentDirAllowed(project, agent) {
+    const dir = projectAgentDir(project, agent.name);
+    return staysInside(dir, project.paths.agentsDir) && !overlapsForeign(project, agent, dir);
+}
+/** True when `shared/common/` does not overlap another agent's persona, memory, inbox or outbox. */
+export function projectCommonDirAllowed(project, agent) {
+    return !overlapsForeign(project, agent, projectCommonDir(project));
+}
 export function writePolicy(project, agent) {
     const isLead = agent.name === project.lead && !project.solo;
     const ws = project.workspaces?.[agent.name];
@@ -83,12 +134,15 @@ export function writePolicy(project, agent) {
     const shared = sharedDir(project);
     const sharedIdx = sharedIndex(project);
     const mayWriteShared = !!shared && agent.name === project.lead;
+    const ownDir = projectAgentDir(project, agent.name);
+    const grantOwnDir = ownAgentDirAllowed(project, agent);
     const allowDirs = [
         ...memoryDirs(agent),
         ...(project.solo === "call" ? [] : [outboxDir(project, agent.name)]),
         ...(ws ? [ws.gitDir] : []),
         ...(shared && mayWriteShared ? [shared] : []),
         ...(isLead ? [recordsDir(project)] : []),
+        ...(grantOwnDir ? [ownDir] : []),
         // Spec 25: canonical, because the OS sandbox compares real paths (`/tmp` is `/private/tmp` on macOS).
         ...(agent.sandbox?.write ?? []).map(canonicalPath),
     ];
@@ -104,8 +158,9 @@ export function writePolicy(project, agent) {
     }
     const deny = [];
     const allowedFileSet = new Set(allowFiles);
+    const grantedRoots = [...(grantOwnDir ? [ownDir] : [])];
     const addDeny = (p) => {
-        if (!allowedFileSet.has(p))
+        if (!allowedFileSet.has(p) && !grantedRoots.some((d) => covers(d, p)))
             deny.push(p);
     };
     for (const a of Object.values(project.agents)) {
@@ -230,7 +285,11 @@ function sandboxNotes(agent, os) {
 }
 /** Can `agent` legitimately change this protected file? */
 export function mayEditProtected(project, agent, file) {
-    return writePolicy(project, agent).allowFiles.includes(file);
+    const pol = writePolicy(project, agent);
+    if (pol.allowFiles.includes(file))
+        return true;
+    const roots = [projectAgentDir(project, agent.name)].filter((d) => pol.allowDirs.includes(d));
+    return roots.some((d) => file === d || file.startsWith(d + path.sep));
 }
 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. */

package/dist/project-lock.d.ts

@@ -44,13 +44,27 @@ 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;
+/** Reader side: C locale, so `ps` start times stay in one language and `samePidStart` can compare them. */
+export declare const readerPs: (pid: number) => string | undefined;
+/** Writer side: the inherited environment, exactly what versions before 0.29.0 wrote and compare against raw; never pin it, or an older reader in a non-C locale judges the lock dead and takes the run over. */
+export declare const writerPs: (pid: number) => 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;
+export interface LivenessIo extends PidStartIo {
+    signal0(pid: number): boolean;
+    psUtc(pid: number): string | undefined;
+}
+export declare const utcPsEnv: (base: NodeJS.ProcessEnv) => NodeJS.ProcessEnv;
+export declare const readerPsUtc: (pid: number) => string | undefined;
+/** Only ESRCH proves absence; permissions and unknown signal errors are conservative. */
+export declare function signalAlive(pid: number, kill?: (pid: number, signal: 0) => unknown): boolean;
+/** Conventional quarter-hour offsets only; arbitrary POSIX TZ offsets remain a limitation. */
+export declare function sameStartAnyZone(written: string, utc: string): boolean | undefined;
 /**
  * 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).
  */
-export declare function lockHolderAlive(info: LockInfo): boolean;
+export declare function lockHolderAlive(info: Pick<LockInfo, "pid" | "pid_started">, io?: LivenessIo): boolean;
 /** Every lock of a project that can be read: one per run, plus an older version's `lock.json`. Oldest first. */
 export declare function listRunLocks(root: string): LockInfo[];
 /** Run ids whose per-run lock file exists but cannot be read (it can only be removed with `forceUnlock(root, runId)`). */

package/dist/project-lock.js

@@ -39,28 +39,27 @@ export function pidStartFrom(pid, io) {
     }
     return io.ps(pid);
 }
-const realIo = {
-    platform: process.platform,
-    readFile: (p) => {
-        try {
-            return fs.readFileSync(p, "utf8");
-        }
-        catch {
-            return undefined;
-        }
-    },
-    ps: (pid) => {
-        // 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;
-    },
+const psLstart = (pid, env) => {
+    const r = spawnSync("ps", ["-o", "lstart=", "-p", String(pid)], { encoding: "utf8", env });
+    return (r.status === 0 ? r.stdout.trim() : "") || undefined;
+};
+/** Reader side: C locale, so `ps` start times stay in one language and `samePidStart` can compare them. */
+export const readerPs = (pid) => psLstart(pid, { ...process.env, LANG: "C", LC_ALL: "C" });
+/** Writer side: the inherited environment, exactly what versions before 0.29.0 wrote and compare against raw; never pin it, or an older reader in a non-C locale judges the lock dead and takes the run over. */
+export const writerPs = (pid) => psLstart(pid, process.env);
+const fileReader = (p) => {
+    try {
+        return fs.readFileSync(p, "utf8");
+    }
+    catch {
+        return undefined;
+    }
 };
+const realIo = { platform: process.platform, readFile: fileReader, ps: readerPs };
+const writerIo = { ...realIo, ps: writerPs };
 function pidStart(pid) {
-    return pidStartFrom(pid, realIo);
+    return pidStartFrom(pid, writerIo);
 }
-/** 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) {
@@ -85,24 +84,62 @@ export function samePidStart(a, b) {
     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).
- */
-export function lockHolderAlive(info) {
+export const utcPsEnv = (base) => ({ ...base, LANG: "C", LC_ALL: "C", TZ: "UTC0" });
+export const readerPsUtc = (pid) => psLstart(pid, utcPsEnv(process.env));
+/** Only ESRCH proves absence; permissions and unknown signal errors are conservative. */
+export function signalAlive(pid, kill = process.kill) {
     try {
-        process.kill(info.pid, 0);
+        kill(pid, 0);
+        return true;
     }
     catch (e) {
-        if (e.code !== "EPERM")
-            return false;
+        return e?.code !== "ESRCH";
     }
-    if (info.pid_started) {
-        const now = pidStart(info.pid);
-        if (now && sameKind(now, info.pid_started) && !samePidStart(info.pid_started, now))
-            return false;
+}
+const realLivenessIo = {
+    ...realIo,
+    signal0: signalAlive,
+    psUtc: readerPsUtc,
+};
+function lstartFieldsMs(text) {
+    const c = canonicalLstart(text);
+    const ms = c === undefined ? NaN : Date.parse(`${c}Z`);
+    return Number.isFinite(ms) && new Date(ms).toISOString().slice(0, 19) === c ? ms : undefined;
+}
+/** Conventional quarter-hour offsets only; arbitrary POSIX TZ offsets remain a limitation. */
+export function sameStartAnyZone(written, utc) {
+    const a = lstartFieldsMs(written);
+    const b = lstartFieldsMs(utc);
+    if (a === undefined || b === undefined)
+        return undefined;
+    const d = (a - b) / 1000;
+    return Number.isInteger(d) && d % 900 === 0 && Math.abs(d) <= 26 * 3600;
+}
+/**
+ * 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).
+ */
+export function lockHolderAlive(info, io = realLivenessIo) {
+    if (!io.signal0(info.pid))
+        return false;
+    const written = info.pid_started;
+    if (typeof written !== "string" || !written)
+        return true;
+    if (io.platform === "linux") {
+        if (!written.startsWith("proc:"))
+            return true;
+        const ticks = parseProcStat(io.readFile(`/proc/${info.pid}/stat`) ?? "");
+        return !ticks || `proc:${ticks}` === written;
     }
-    return true;
+    if (written.startsWith("proc:"))
+        return true;
+    const local = io.ps(info.pid);
+    if (!local || samePidStart(written, local))
+        return true;
+    const utc = io.psUtc(info.pid);
+    if (!utc)
+        return true;
+    return sameStartAnyZone(written, utc) !== false;
 }
 function readLockFile(file) {
     let text;

package/dist/prompt.d.ts

@@ -20,7 +20,12 @@ export declare const CONTEXT_LIMIT: number;
 /** Largest mail body put in a prompt (the inline task limit), and the total for the mails handled in one wake-up. */
 export declare const MAIL_BODY_LIMIT: number;
 export declare const MAIL_BATCH_LIMIT: number;
+/** Same-thread `reply`/`failure` messages a non-lead agent takes in one wake-up. The lead uses `MAIL_BATCH_LIMIT` and `LEAD_REPLY_CAP` instead. */
 export declare const LEAD_BATCH_LIMIT = 5;
+/** Most waiting `reply`/`failure` messages the lead takes in one wake-up; headers are not counted in `MAIL_BATCH_LIMIT`, so tiny replies need a count cap too. */
+export declare const LEAD_REPLY_CAP = 20;
+/** A project persona is injected into every wake-up. Cap it, and refuse a FIFO or other non-file, so one write cannot stall the dispatcher. */
+export declare const PERSONA_LIMIT: number;
 export declare function readPersona(agent: ResolvedAgent): string;
 /** The protocol of an agent working alone: no teammates, no ask. `run --agent` still ends with a `done` mail; `call` just answers. */
 export declare function buildSoloSystemPrompt(project: ResolvedProject, agent: ResolvedAgent): string;
@@ -28,7 +33,12 @@ export declare function buildSoloSystemPrompt(project: ResolvedProject, agent: R
 export declare function buildCallUserPrompt(agent: ResolvedAgent, task: string): string;
 /** Everything that goes to the runtime's system prompt: the persona plus the team protocol. */
 export declare function buildSystemPrompt(project: ResolvedProject, agent: ResolvedAgent): string;
-/** Messages one wake-up handles: the oldest one, or a run of `reply`/`failure` mail (up to LEAD_BATCH_LIMIT) so the agent decides once on all of it; the lead takes any such run, other agents only same-thread ones. */
+/**
+ * Messages one wake-up handles: the oldest one, or a run of `reply`/`failure` so the agent decides once.
+ * The lead takes every such message that is already waiting and whose body still fits in `MAIL_BATCH_LIMIT`
+ * (a later one that would show none of its body stays unread), at most `LEAD_REPLY_CAP`. Other agents take
+ * at most `LEAD_BATCH_LIMIT` on the same thread.
+ */
 export declare function pickMessages(project: ResolvedProject, agent: ResolvedAgent, queue: Message[]): Message[];
 export declare function buildUserPrompt(project: ResolvedProject, agent: ResolvedAgent, unread: Message[], handleCount?: number, handoff?: boolean): string;
 export interface TidyRecordsContext {

package/dist/prompt.js

@@ -1,11 +1,10 @@
-import fs from "node:fs";
 import { cutUtf8, readFileCapped } from "./fs-util.js";
 import path from "node:path";
 import { REQUIRED_SECTIONS } from "./format.js";
 import { senderLabel, slotName } from "./instances.js";
 import { modelForTier } from "./tiers.js";
 import { buildRecordsView, RECORDS_BUDGET } from "./records.js";
-import { commonFile, memoryDirs, outboxDir, recordsKindDir, repoDirFor, sharedDir, sharedIndex } from "./policy.js";
+import { commonFile, memoryDirs, outboxDir, ownAgentDirAllowed, projectAgentDir, recordsKindDir, repoDirFor, sharedDir, sharedIndex } from "./policy.js";
 function memoryLabel(agent, dir) {
     if (dir === agent.memory.task)
         return "task (this task only, isolated)";
@@ -49,7 +48,10 @@ export const CONTEXT_LIMIT = RECORDS_BUDGET;
 /** Largest mail body put in a prompt (the inline task limit), and the total for the mails handled in one wake-up. */
 export const MAIL_BODY_LIMIT = 16 * 1024;
 export const MAIL_BATCH_LIMIT = 64 * 1024;
+/** Same-thread `reply`/`failure` messages a non-lead agent takes in one wake-up. The lead uses `MAIL_BATCH_LIMIT` and `LEAD_REPLY_CAP` instead. */
 export const LEAD_BATCH_LIMIT = 5;
+/** Most waiting `reply`/`failure` messages the lead takes in one wake-up; headers are not counted in `MAIL_BATCH_LIMIT`, so tiny replies need a count cap too. */
+export const LEAD_REPLY_CAP = 20;
 const BATCHABLE = new Set(["reply", "failure"]);
 const readCapped = readFileCapped;
 /** A PR only needs to say agent-lyceum opened it; no agent or role names. */
@@ -58,8 +60,14 @@ const PR_ATTRIBUTION_RULE = "- If you open a pull request, end its description w
 const NO_DAEMONS_RULE = "- Never start a server, daemon or watcher (pm2, `serve`, `dev`, `--watch`) in the foreground of a command, and never leave one running. Run it in the background, bound every such command with `timeout 60`, stop what you started before you finish, and if it cannot start (e.g. a sandbox denies binding a port) report that as unverified instead of retrying.";
 /** Only the lead (or a solo agent, the lead of a team of one) can send `done`, so only it can ask for a pull request. */
 const OPEN_PR_RULE = "Add the frontmatter line `open_pr: true` to `done` only when the user's task explicitly asks for a pull request; otherwise leave it out. It only has an effect when the run ends `completed` with changes on its own branch, and agent-lyceum (not you) then pushes the branch and opens the pull request. Keep agent and role names out of the report, because it becomes the pull request description.";
+/** A project persona is injected into every wake-up. Cap it, and refuse a FIFO or other non-file, so one write cannot stall the dispatcher. */
+export const PERSONA_LIMIT = 64 * 1024;
 export function readPersona(agent) {
-    return fs.readFileSync(agent.agentMd, "utf8").trim();
+    const read = readFileCapped(agent.agentMd, PERSONA_LIMIT);
+    if (!read)
+        return "";
+    const text = read.text.trim();
+    return read.truncated ? `${text}\n\n[persona truncated at ${PERSONA_LIMIT} bytes]` : text;
 }
 /** What the lead (or a solo agent) is told about the handoff notes: they are what a reopened task starts from. */
 function handoffRule(dir) {
@@ -69,6 +77,32 @@ function handoffRule(dir) {
         `This task may be reopened later with a follow-up request, and the agents woken then start with fresh sessions. Before you send \`done\`, write what they need to carry on into \`${dir}\`: keep a \`MEMORY.md\` index there (one line per entry, pointing at a file) and record the decisions made and why, the interfaces agreed, the current state, what is left and what to do next, and the pitfalls met. Your teammates can read this folder but cannot write it; if a report from a teammate holds something worth keeping, add it yourself. Only the index is shown in prompts, and only the first ${HANDOFF_LIMIT / 1024} KB of it, so keep it short. These notes are about this task only; lessons that outlive it belong in your project or global memory.`,
     ];
 }
+function extraWritableDirs(project, agent) {
+    if (project.solo === "call")
+        return [];
+    return ownAgentDirAllowed(project, agent) ? [projectAgentDir(project, agent.name)] : [];
+}
+function extraWriteClause(dirs) {
+    return dirs.length ? ` You may also write ${dirs.map((d) => `\`${d}/\``).join(" and ")}.` : "";
+}
+function writeScopeRules(project, agent) {
+    const isLead = agent.name === project.lead && !project.solo;
+    const ownDir = projectAgentDir(project, agent.name);
+    const mayWriteOwn = project.solo !== "call" && ownAgentDirAllowed(project, agent);
+    const ownPersona = mayWriteOwn && (agent.agentMd === path.join(ownDir, "AGENT.md") || agent.agentMd.startsWith(ownDir + path.sep));
+    const records = `decisions in \`${recordsKindDir(project, "decisions")}/\` and lessons in \`${recordsKindDir(project, "lessons")}/\`. The file name without \`.md\` is the entry id (lowercase letters, digits, \`-\`). Each file starts with YAML frontmatter between \`---\` lines: \`status: active|superseded\`, \`date: YYYY-MM-DD\`, \`title: <one line>\`, optionally \`run: <run id>\` and \`supersedes: [<ids of entries of the same kind>]\`; the body is the decision or lesson and its reason. Prompts show only effective-active entries (\`status: active\` and not named in another entry's \`supersedes\`), newest first, up to ${CONTEXT_LIMIT / 1024} KB per kind, and list what does not fit as one line each. When an entry becomes outdated, mark it \`status: superseded\` or name it in a new entry's \`supersedes\`.`;
+    return [
+        isLead
+            ? `- You keep the shared team context \`${commonFile(project)}\` (you maintain it; keep it short) and two kinds of durable records for every future run of this project, one Markdown file per entry: ${records} Add or update entries before you send \`done\`.`
+            : `- The shared team context is in \`${commonFile(project)}\` (read-only). Project records are ${records} Both are read-only.`,
+        ...(mayWriteOwn ? [`- You may write your project agent directory \`${ownDir}/\`. Creating \`AGENT.md\` there makes it this project's persona on the next run; the global persona file stays read-only.`] : []),
+        ...(ownPersona ? [`- You may edit your project persona \`${agent.agentMd}\`.`] : []),
+        ...(agent.canEditAgentMd
+            ? ["- You may edit every `AGENT.md` and the repository's `CLAUDE.md`/`AGENTS.md`; those changes are logged."]
+            : ["- Never edit another agent's AGENT.md, a global `AGENT.md`, or the repository's own `CLAUDE.md`/`AGENTS.md`."]),
+        "- Never touch another agent's memory, inbox or outbox, or the configuration files of agent-lyceum (`project.yaml`, `team.yaml`, `runs/`).",
+    ];
+}
 /** The protocol of an agent working alone: no teammates, no ask. `run --agent` still ends with a `done` mail; `call` just answers. */
 export function buildSoloSystemPrompt(project, agent) {
     const isCall = project.solo === "call";
@@ -89,9 +123,10 @@ export function buildSoloSystemPrompt(project, agent) {
     for (const m of mems)
         lines.push(`- ${memoryLabel(agent, m)}: \`${m}\``);
     if (mems.length) {
-        lines.push("Keep a `MEMORY.md` index in each memory directory (one line per entry, pointing at a file). Its contents are shown in your prompt on every wake-up; you can write only inside these directories.", "Use memory only for durable lessons that stay true across tasks; never record task-specific details there.");
+        const extra = extraWritableDirs(project, agent);
+        lines.push(`Keep a \`MEMORY.md\` index in each memory directory (one line per entry, pointing at a file). Its contents are shown in your prompt on every wake-up.${extraWriteClause(extra)}`, "Use memory only for durable lessons that stay true across tasks; never record task-specific details there.");
     }
-    lines.push("", "## Rules", "- Never edit any `AGENT.md`, `COMMON.md`, or the repository's own `CLAUDE.md`/`AGENTS.md`.", "- Never touch another agent's memory, inbox or outbox, or the configuration files of agent-lyceum.", PR_ATTRIBUTION_RULE, NO_DAEMONS_RULE);
+    lines.push("", "## Rules", ...writeScopeRules(project, agent), PR_ATTRIBUTION_RULE, NO_DAEMONS_RULE);
     return lines.join("\n");
 }
 /** The prompt of a `call`: the memory indexes the agent is used to, then the task. */
@@ -175,17 +210,13 @@ export function buildSystemPrompt(project, agent) {
         lines.push(`- ${label}: \`${m}\``);
     }
     if (mems.length) {
-        lines.push("Keep a `MEMORY.md` index in each memory directory (one line per entry, pointing at a file). Its contents are shown in your prompt", "on every wake-up; read other memory files on demand; you can write only inside these directories.", "Put anything specific to the current task (decisions, progress, findings, branch names) in the **task** memory: it is private to this task and starts empty for every new task.", "Also record approaches you considered but rejected, with the reason, so they can be revisited or reversed later.", ...(sharedMems.length
+        const extra = extraWritableDirs(project, agent);
+        lines.push(`Keep a \`MEMORY.md\` index in each memory directory (one line per entry, pointing at a file). Its contents are shown in your prompt on every wake-up.${extraWriteClause(extra)}`, "Put anything specific to the current task (decisions, progress, findings, branch names) in the **task** memory: it is private to this task and starts empty for every new task.", "Also record approaches you considered but rejected, with the reason, so they can be revisited or reversed later.", ...(sharedMems.length
             ? ["You cannot write the shared memory: put lessons worth keeping in your reply to the lead."]
             : ["Use the global/project memory only for durable lessons that stay true across tasks; never record task-specific details there."]));
     }
     lines.push("", "## Rules");
-    lines.push("- Never edit any `AGENT.md`, `COMMON.md`, or the repository's own `CLAUDE.md`/`AGENTS.md`" +
-        (isLead || agent.canEditAgentMd ? " unless you need to as lead (changes are logged)." : "."), "- Never touch another agent's memory, inbox or outbox, or the team's config files.", `- The shared team context is in \`${commonFile(project)}\`${isLead ? " (you maintain it; keep it short)" : " (read-only)"}.`, ...(isLead
-        ? [
-            `- You also keep two kinds of durable records for every future run of this project, one Markdown file per entry: decisions in \`${recordsKindDir(project, "decisions")}/\` (what was decided and why) and lessons in \`${recordsKindDir(project, "lessons")}/\` (heuristics and pitfalls that stay true). The file name without \`.md\` is the entry id (lowercase letters, digits, \`-\`). Each file starts with YAML frontmatter between \`---\` lines: \`status: active|superseded\`, \`date: YYYY-MM-DD\`, \`title: <one line>\`, optionally \`run: <run id>\` and \`supersedes: [<ids of entries of the same kind>]\`; the body is the decision or lesson and its reason. Prompts show only effective-active entries (\`status: active\` and not named in another entry's \`supersedes\`), newest first, up to ${CONTEXT_LIMIT / 1024} KB per kind, and list what does not fit as one line each. When an entry becomes outdated, mark it \`status: superseded\` or name it in a new entry's \`supersedes\`. Add or update entries before you send \`done\`.`,
-        ]
-        : []), PR_ATTRIBUTION_RULE, NO_DAEMONS_RULE);
+    lines.push(...writeScopeRules(project, agent), PR_ATTRIBUTION_RULE, NO_DAEMONS_RULE);
     let text = lines.join("\n");
     if (isLead && project.run?.instances)
         text = `${text}\n\n${PARALLEL_SECTION(project.run.instances.max)}`;
@@ -199,7 +230,18 @@ export function buildSystemPrompt(project, agent) {
     }
     return text;
 }
-/** Messages one wake-up handles: the oldest one, or a run of `reply`/`failure` mail (up to LEAD_BATCH_LIMIT) so the agent decides once on all of it; the lead takes any such run, other agents only same-thread ones. */
+/** Bytes of `body` this wake-up would actually show, using the same caps as the prompt. */
+function shownBodyBytes(body, remaining) {
+    if (remaining <= 0)
+        return 0;
+    return cutUtf8(Buffer.from(body, "utf8"), Math.min(MAIL_BODY_LIMIT, remaining)).length;
+}
+/**
+ * Messages one wake-up handles: the oldest one, or a run of `reply`/`failure` so the agent decides once.
+ * The lead takes every such message that is already waiting and whose body still fits in `MAIL_BATCH_LIMIT`
+ * (a later one that would show none of its body stays unread), at most `LEAD_REPLY_CAP`. Other agents take
+ * at most `LEAD_BATCH_LIMIT` on the same thread.
+ */
 export function pickMessages(project, agent, queue) {
     const sorted = [...queue].sort((a, b) => path.basename(a.file).localeCompare(path.basename(b.file)));
     const first = sorted[0];
@@ -207,12 +249,20 @@ export function pickMessages(project, agent, queue) {
         return sorted.slice(0, 1);
     const isLead = agent.name === project.lead;
     const run = [];
+    let remaining = MAIL_BATCH_LIMIT;
     for (const m of sorted) {
-        if (!BATCHABLE.has(m.meta.type) || run.length >= LEAD_BATCH_LIMIT)
+        if (!BATCHABLE.has(m.meta.type))
+            break;
+        if (run.length >= (isLead ? LEAD_REPLY_CAP : LEAD_BATCH_LIMIT))
             break;
         if (!isLead && m.meta.thread !== first.meta.thread)
             break;
+        const shown = isLead ? shownBodyBytes(m.body, remaining) : 0;
+        if (isLead && Buffer.byteLength(m.body, "utf8") > 0 && shown === 0)
+            break;
         run.push(m);
+        if (isLead)
+            remaining -= shown;
     }
     return run;
 }

package/dist/status-watch.d.ts

@@ -1,6 +1,6 @@
 import type { ResolvedProject } from "./config.js";
 import { type StatusReport } from "./status.js";
-/** What `status --json --watch` prints, one JSON object per line: the project's report plus one per task that is not completed. */
+/** What `status --json --watch` prints, one JSON object per line: the project's report plus one per task that is not finished (completed or partial). */
 export type WatchFrame = {
     schema_version: 1;
     report?: StatusReport;
@@ -8,9 +8,9 @@ export type WatchFrame = {
     error?: string;
 };
 /**
- * The frame for now. Every task that is not completed (running, interrupted, waiting for answers, or ended partial,
- * blocked, failed or cancelled) gets its own report, so it stays listed until it is resumed to completion or cleared.
- * A task that was running in the previous frame and has completed since is included once more, so the reader sees
+ * The frame for now. Every task that is not finished (running, interrupted, waiting for answers, or ended blocked,
+ * failed or cancelled) gets its own report, so it stays listed until it is resumed or cleared.
+ * A task that was running in the previous frame and has finished (completed or partial) since is included once more, so the reader sees
  * it finish (and can toast) before it is dropped. `tracked` is that previous set; it is replaced by the ids running now.
  */
 export declare function buildWatchFrame(project: ResolvedProject, tracked: Set<string>, opts?: {

package/dist/status-watch.js

@@ -1,17 +1,17 @@
 import fs from "node:fs";
-import { buildStatusReport, buildTaskListReport, isCompletedRun } from "./status.js";
+import { buildStatusReport, buildTaskListReport, isFinishedRun } from "./status.js";
 /**
- * The frame for now. Every task that is not completed (running, interrupted, waiting for answers, or ended partial,
- * blocked, failed or cancelled) gets its own report, so it stays listed until it is resumed to completion or cleared.
- * A task that was running in the previous frame and has completed since is included once more, so the reader sees
+ * The frame for now. Every task that is not finished (running, interrupted, waiting for answers, or ended blocked,
+ * failed or cancelled) gets its own report, so it stays listed until it is resumed or cleared.
+ * A task that was running in the previous frame and has finished (completed or partial) since is included once more, so the reader sees
  * it finish (and can toast) before it is dropped. `tracked` is that previous set; it is replaced by the ids running now.
  */
 export function buildWatchFrame(project, tracked, opts) {
     const all = buildTaskListReport(project).runs;
     const running = all.filter((r) => r.state === "running").map((r) => r.run_id);
-    const open = all.filter((r) => !isCompletedRun(r)).map((r) => r.run_id);
+    const open = all.filter((r) => !isFinishedRun(r)).map((r) => r.run_id);
     const runs = {};
-    // The web page keeps every task. The terminal watch drops one after it has completed, once the finish has been seen.
+    // The web page keeps every task. The terminal watch drops one after it has finished, once the finish has been seen.
     const ids = opts?.allTasks ? all.map((r) => r.run_id) : [...open, ...tracked];
     for (const id of new Set(ids))
         runs[id] = buildStatusReport(project, id);

package/dist/status.d.ts

@@ -173,8 +173,8 @@ export declare function buildRunReport(run: {
 }, project?: ResolvedProject, opts?: {
     detail?: boolean;
 }): RunReport;
-/** A run that ended with a verified-or-inferred `completed` outcome: the only kind the monitor stops listing. */
-export declare const isCompletedRun: (r: Pick<RunReport, "state" | "outcome">) => boolean;
+/** A run that ended with a `completed` or `partial` outcome: the only kinds the monitor stops listing (blocked, failed and cancelled stay). */
+export declare const isFinishedRun: (r: Pick<RunReport, "state" | "outcome">) => boolean;
 /** The status of a project: its agents and one run (the newest running one, else the newest, or the one named by `runId`). */
 export declare function buildStatusReport(base: ResolvedProject, runId?: string, now?: number): StatusReport;
 /** Every run of the project, newest first. */

package/dist/status.js

@@ -266,8 +266,8 @@ export function buildRunReport(run, project, opts = {}) {
         ...(ask ? { ask } : {}),
     };
 }
-/** A run that ended with a verified-or-inferred `completed` outcome: the only kind the monitor stops listing. */
-export const isCompletedRun = (r) => r.state === "ended" && r.outcome === "completed";
+/** A run that ended with a `completed` or `partial` outcome: the only kinds the monitor stops listing (blocked, failed and cancelled stay). */
+export const isFinishedRun = (r) => r.state === "ended" && (r.outcome === "completed" || r.outcome === "partial");
 const projectInfo = (p) => ({ name: p.name, dir: p.dir, lead: p.lead });
 /** The fallback part of an agent's report: nothing at all for an agent without a chain. */
 function fallbackView(a, state, now) {

package/package.json

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