agent-lyceum 0.19.0 → 0.21.0

package/dist/cli.js

@@ -22,6 +22,8 @@ import { prepareTask, readTaskFile, taskMessageBody } from "./task.js";
 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 { 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";
 const program = new Command();
@@ -145,6 +147,8 @@ function takeLock(pr, runId, opts = {}) {
 /**
  * Ctrl-C (or SIGTERM) stops the run cleanly: the first signal cancels it (agents are killed, unread mail is kept,
  * the lock is released, exit code 130); a second one quits at once.
+ * Started through a launcher that does not relay SIGHUP (npx, npm exec, tsx), the launcher exiting counts as that
+ * first signal: otherwise closing the terminal would leave this process running on its own (spec 21).
  */
 function cancelOnSignals() {
     const ac = new AbortController();
@@ -157,13 +161,29 @@ function cancelOnSignals() {
         else
             process.exit(130);
     };
+    const onParentGone = () => {
+        if (seen > 0)
+            return; // already stopping
+        seen = 1;
+        // stderr may be a dead terminal or pipe: console.error would throw EPIPE/EIO there
+        try {
+            fs.writeSync(2, "\nLauncher exited (parent process gone): stopping the run (running agents are being stopped; unread mail is kept).\n");
+        }
+        catch { }
+        ac.abort();
+    };
     const onInt = handler("Interrupted");
     const onTerm = handler("Terminated");
+    const onHup = handler("Hung up");
     process.on("SIGINT", onInt);
     process.on("SIGTERM", onTerm);
+    process.on("SIGHUP", onHup); // the terminal went away
+    const stopWatch = startedByWrapper() ? watchParent(onParentGone, { startPpid: LAUNCH_PPID }) : () => { };
     return { signal: ac.signal, dispose: () => {
+            stopWatch();
             process.off("SIGINT", onInt);
             process.off("SIGTERM", onTerm);
+            process.off("SIGHUP", onHup);
         },
     };
 }
@@ -774,8 +794,16 @@ program
             }
             process.stdout.write(`\x1b[2J\x1b[H${text}\n\nRefreshing every ${sec}s — ${new Date().toLocaleTimeString()} — Ctrl-C to quit\n`);
         };
-        draw();
-        setInterval(draw, sec * 1000);
+        runMonitor({
+            draw,
+            intervalMs: sec * 1000,
+            stdout: process.stdout,
+            stdin: process.stdin,
+            ppid: () => process.ppid,
+            exit: (code) => process.exit(code),
+            onSignal: (sig, handler) => process.on(sig, handler),
+            fail: (message) => fail(message),
+        });
         await new Promise(() => { });
     }
     catch (e) {

package/dist/monitor-lifecycle.d.ts

@@ -0,0 +1,19 @@
+import type { EventEmitter } from "node:events";
+export interface MonitorDeps {
+    draw: () => void;
+    intervalMs: number;
+    stdout: EventEmitter & {
+        destroyed?: boolean;
+        writable?: boolean;
+    };
+    stdin: EventEmitter & {
+        isTTY?: boolean;
+        resume: () => unknown;
+    };
+    ppid: () => number;
+    exit: (code: number) => void;
+    onSignal: (sig: NodeJS.Signals, handler: () => void) => void;
+    fail: (message: string) => void;
+}
+/** Run `draw` every interval and end the process when the monitor is closed: signal, dead stdout, TTY stdin close, or lost parent. */
+export declare function runMonitor(d: MonitorDeps): void;

package/dist/monitor-lifecycle.js

@@ -0,0 +1,42 @@
+const SIGNAL_CODES = [["SIGINT", 130], ["SIGTERM", 143], ["SIGHUP", 129]];
+/** Run `draw` every interval and end the process when the monitor is closed: signal, dead stdout, TTY stdin close, or lost parent. */
+export function runMonitor(d) {
+    const startPpid = d.ppid();
+    let timer;
+    let done = false;
+    const stop = (code) => {
+        if (done)
+            return;
+        done = true;
+        if (timer)
+            clearInterval(timer);
+        d.exit(code);
+    };
+    for (const [sig, code] of SIGNAL_CODES)
+        d.onSignal(sig, () => stop(code));
+    d.stdout.on("error", (e) => {
+        if (e.code === "EPIPE" || e.code === "EIO")
+            return stop(0);
+        done = true;
+        if (timer)
+            clearInterval(timer);
+        d.fail(e.message);
+    });
+    if (d.stdin.isTTY) {
+        for (const ev of ["end", "close", "error"])
+            d.stdin.on(ev, () => stop(0));
+        d.stdin.resume(); // a TTY only reports EOF while it is being read
+    }
+    const tick = () => {
+        if (done)
+            return;
+        if (d.ppid() !== startPpid)
+            return stop(129);
+        if (d.stdout.destroyed || d.stdout.writable === false)
+            return stop(0);
+        d.draw();
+    };
+    tick();
+    if (!done)
+        timer = setInterval(tick, d.intervalMs);
+}

package/dist/parent-watch.d.ts

@@ -0,0 +1,17 @@
+/** The parent pid when the process started (read at module load, before config loading and preflight). */
+export declare const LAUNCH_PPID: number;
+/**
+ * Started by a launcher that does not relay SIGHUP: npm/npx/pnpm/yarn (they set `npm_execpath`), or the tsx CLI
+ * (its child runs with `--require …/tsx/dist/preflight.cjs`). A directly run binary is never watched, so runs that are
+ * detached on purpose (`&`, `disown`, `setsid`, supervisors) keep running when their parent exits.
+ */
+export declare function startedByWrapper(env?: NodeJS.ProcessEnv, execArgv?: readonly string[]): boolean;
+/**
+ * Call `onGone` once when the parent pid differs from `startPpid` (the launcher exited and the process was adopted):
+ * checked at once, then every `intervalMs` on an unref'd timer. Returns a function that stops the watch.
+ */
+export declare function watchParent(onGone: () => void, opts: {
+    startPpid: number;
+    ppid?: () => number;
+    intervalMs?: number;
+}): () => void;

package/dist/parent-watch.js

@@ -0,0 +1,37 @@
+/** The parent pid when the process started (read at module load, before config loading and preflight). */
+export const LAUNCH_PPID = process.ppid;
+/**
+ * Started by a launcher that does not relay SIGHUP: npm/npx/pnpm/yarn (they set `npm_execpath`), or the tsx CLI
+ * (its child runs with `--require …/tsx/dist/preflight.cjs`). A directly run binary is never watched, so runs that are
+ * detached on purpose (`&`, `disown`, `setsid`, supervisors) keep running when their parent exits.
+ */
+export function startedByWrapper(env = process.env, execArgv = process.execArgv) {
+    if (env.npm_execpath)
+        return true;
+    return execArgv.some((a) => /[\\/]tsx[\\/]dist[\\/]preflight\.cjs$/.test(a));
+}
+/**
+ * Call `onGone` once when the parent pid differs from `startPpid` (the launcher exited and the process was adopted):
+ * checked at once, then every `intervalMs` on an unref'd timer. Returns a function that stops the watch.
+ */
+export function watchParent(onGone, opts) {
+    const ppid = opts.ppid ?? (() => process.ppid);
+    let timer;
+    const stop = () => {
+        if (timer)
+            clearInterval(timer);
+        timer = undefined;
+    };
+    if (ppid() !== opts.startPpid) {
+        onGone();
+        return stop;
+    }
+    timer = setInterval(() => {
+        if (ppid() === opts.startPpid)
+            return;
+        stop();
+        onGone();
+    }, opts.intervalMs ?? 1000);
+    timer.unref();
+    return stop;
+}

package/dist/process-runner.d.ts

@@ -13,6 +13,16 @@ export interface RunnerOptions {
     /** How long to wait for output pipes to close after the process is gone or killed, before giving up on them. Default 1000. */
     settleWaitMs?: number;
 }
+/** Pids below `root` (children, grandchildren, ...) by parent links; catches descendants that left the process group (setsid, daemons). */
+export declare function descendantsOf(root: number): number[];
+/** Sampling interval of the descendant timer (default 2000 ms); for tests. Takes effect for the next timer. */
+export declare function setSamplerIntervalMs(ms: number): void;
+/** Whether the descendant timer is running (for tests). */
+export declare function samplerActive(): boolean;
+/** How many runtimes are registered as running (for tests). */
+export declare function runningCount(): number;
+/** Synchronously SIGKILL every runtime still running, with the descendants seen when it was started or last checked. Used when agent-lyceum itself is going away. */
+export declare function killAllRunning(): void;
 /**
  * Run an invocation as a child process in its own process group, with a timeout, cancellation, bounded memory
  * and a bounded finish: whatever the runtime and its descendants do with the output pipes, this settles once,

package/dist/process-runner.js

@@ -1,4 +1,4 @@
-import { spawn } from "node:child_process";
+import { spawn, spawnSync } from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
 /** Most output kept in memory per stream; the rest only goes to the log files. */
@@ -31,6 +31,121 @@ function endStream(s) {
         });
     });
 }
+/**
+ * Runtimes that are running right now, with the descendants seen so far, so an exiting agent-lyceum can take them with it.
+ * A descendant that left the process group (setsid, daemon) is only found by parent links while its parent is alive, so a
+ * shared timer samples the process table while any runtime is registered. Remaining gap: a child that escapes and
+ * outlives its parent within one sampling interval is never seen.
+ */
+const live = new Map();
+let exitHook = false;
+let sampler;
+let samplerMs = 2000;
+/** Parent -> children from one `ps` run, or undefined when it fails or hangs (SIGKILL on timeout: a ps that ignores SIGTERM must not block, even in the exit hook). */
+function processTable() {
+    if (process.platform === "win32")
+        return undefined;
+    const ps = spawnSync("ps", ["-A", "-o", "pid=,ppid="], { encoding: "utf8", timeout: 2000, killSignal: "SIGKILL" });
+    if (ps.status !== 0 || !ps.stdout)
+        return undefined;
+    const kids = new Map();
+    for (const line of ps.stdout.split("\n")) {
+        const [pid, ppid] = line.trim().split(/\s+/).map(Number);
+        if (!pid || !ppid)
+            continue;
+        kids.set(ppid, [...(kids.get(ppid) ?? []), pid]);
+    }
+    return kids;
+}
+function below(kids, root) {
+    const out = [];
+    if (!kids)
+        return out;
+    for (let todo = [root]; todo.length;) {
+        const next = [];
+        for (const p of todo) {
+            for (const k of kids.get(p) ?? []) {
+                if (out.includes(k))
+                    continue;
+                out.push(k);
+                next.push(k);
+            }
+        }
+        todo = next;
+    }
+    return out;
+}
+/** Pids below `root` (children, grandchildren, ...) by parent links; catches descendants that left the process group (setsid, daemons). */
+export function descendantsOf(root) {
+    return below(processTable(), root);
+}
+/** Record the current descendants of every live runtime (one `ps` for all). */
+function sample() {
+    if (!live.size)
+        return;
+    const kids = processTable();
+    for (const [pid, seen] of live)
+        for (const d of below(kids, pid))
+            seen.add(d);
+}
+function register(pid) {
+    live.set(pid, new Set());
+    if (!exitHook) {
+        exitHook = true;
+        process.on("exit", killAllRunning); // process.exit() and crashes must not leave detached runtimes behind
+    }
+    if (!sampler) {
+        sampler = setInterval(sample, samplerMs);
+        sampler.unref();
+    }
+}
+function unregister(pid) {
+    live.delete(pid);
+    if (!live.size && sampler) {
+        clearInterval(sampler);
+        sampler = undefined;
+    }
+}
+/** Sampling interval of the descendant timer (default 2000 ms); for tests. Takes effect for the next timer. */
+export function setSamplerIntervalMs(ms) {
+    samplerMs = ms;
+}
+/** Whether the descendant timer is running (for tests). */
+export function samplerActive() {
+    return sampler !== undefined;
+}
+function signalPid(pid, sig, group) {
+    try {
+        process.kill(group && process.platform !== "win32" ? -pid : pid, sig);
+    }
+    catch {
+        /* already gone */
+    }
+}
+/** Signal the runtime's group, the descendants recorded earlier that are still in the process table, and its current descendants. */
+function killTree(pid, sig) {
+    const kids = processTable();
+    const seen = live.get(pid) ?? new Set();
+    const now = below(kids, pid);
+    const present = kids ? new Set([...kids.values()].flat()) : undefined; // without a table, trust the record
+    for (const d of now)
+        seen.add(d);
+    signalPid(pid, sig, true);
+    for (const d of seen)
+        if (!present || present.has(d))
+            signalPid(d, sig, false);
+}
+/** How many runtimes are registered as running (for tests). */
+export function runningCount() {
+    return live.size;
+}
+/** Synchronously SIGKILL every runtime still running, with the descendants seen when it was started or last checked. Used when agent-lyceum itself is going away. */
+export function killAllRunning() {
+    for (const pid of [...live.keys()]) {
+        killTree(pid, "SIGKILL");
+        unregister(pid);
+    }
+}
 /**
  * Run an invocation as a child process in its own process group, with a timeout, cancellation, bounded memory
  * and a bounded finish: whatever the runtime and its descendants do with the output pipes, this settles once,
@@ -49,6 +164,8 @@ export function runInvocation(inv, opts) {
         outLog.on("error", () => { });
         errLog.on("error", () => { });
         const child = spawn(inv.cmd, inv.args, { cwd: inv.cwd, env: inv.env, stdio: ["pipe", "pipe", "pipe"], detached: process.platform !== "win32" });
+        if (child.pid !== undefined)
+            register(child.pid);
         const stdoutTail = new Tail();
         const stderrTail = new Tail();
         const parser = inv.stream?.();
@@ -58,17 +175,8 @@ export function runInvocation(inv, opts) {
         let settled = false;
         const timers = [];
         const killGroup = (sig) => {
-            if (child.pid === undefined)
-                return;
-            try {
-                if (process.platform === "win32")
-                    child.kill(sig);
-                else
-                    process.kill(-child.pid, sig);
-            }
-            catch {
-                /* nothing left to signal */
-            }
+            if (child.pid !== undefined)
+                killTree(child.pid, sig);
         };
         const finish = (spawnError) => {
             if (settled)
@@ -78,6 +186,8 @@ export function runInvocation(inv, opts) {
                 clearTimeout(t);
             opts.signal?.removeEventListener("abort", onAbort);
             killGroup("SIGKILL"); // whatever of the tree is still around
+            if (child.pid !== undefined)
+                unregister(child.pid);
             child.stdout?.destroy();
             child.stderr?.destroy();
             void Promise.all([endStream(outLog), endStream(errLog)]).then(() => {

package/package.json

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