agent-lyceum 0.29.0 → 0.30.0

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/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/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.30.0",
   "description": "Config + dispatcher for teams of Claude Code / Codex agents with scoped context and file-based mailboxes",
   "keywords": [
     "ai",