agent-lyceum 0.34.0 → 0.36.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. `status --web` opens every registered project in a browser. [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 (**breaking:** it now rejects unknown `Host` names; use `--allow-host`). [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。`status --web` 在瀏覽器看全部已註冊專案。 [詳細](docs/commands.zh-TW.md#status) |
+| `status` | 顯示 agent、信件、目前的喚醒與過去的 run。`status --web` 在瀏覽器看全部已註冊專案（**breaking：** 現在會拒絕未知的 `Host` 名稱，請用 `--allow-host`）。 [詳細](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/cli.js

@@ -25,6 +25,7 @@ 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 { probeHealth, runAttachedWeb } from "./web-attach.js";
 import { createStatusWatcher } from "./status-watch.js";
 import { LAUNCH_PPID, startedByWrapper, watchParent } from "./parent-watch.js";
 import { onlyAgent, soloProject } from "./solo.js";
@@ -749,16 +750,20 @@ program
     .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")
+    .option("--exit-with-parent", "with --web: stop when the launching process goes away (parent exit, closed stdout) and print the URL as the first stdout line")
+    .option("--allow-host <name>", "with --web on a loopback address: also accept this Host name (repeatable)", (value, previous) => [...previous, value], [])
     .action(async (opts) => {
     try {
+        if (opts.exitWithParent && !opts.web)
+            fail("--exit-with-parent needs --web.");
         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.");
+            if (!Number.isInteger(port) || port < 0 || port > 65535)
+                fail("--port must be a TCP port (0 picks a free one).");
             const beat = Number(opts.heartbeat);
             if (!(beat > 0))
                 fail("--heartbeat must be a positive number of seconds.");
@@ -769,12 +774,15 @@ program
                 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({
+            const version = JSON.parse(fs.readFileSync(path.join(root, "package.json"), "utf8")).version ?? "unknown";
+            const startOptions = {
                 port,
                 host: opts.host,
                 open: opts.open !== false,
                 staticDir,
                 heartbeatMs: beat * 1000,
+                identity: { version, home: home() },
+                allowHosts: opts.allowHost,
                 factory: {
                     list: () => listProjects(home()).map((item) => item.name),
                     watch: (name, onFrame) => createStatusWatcher({
@@ -784,10 +792,38 @@ program
                         debounceMs: 100,
                         allTasks: true,
                     }),
-                    quota: () => Promise.all([claudeQuota(), codexQuota()]),
+                    quota: (signal) => Promise.all([claudeQuota(signal), codexQuota(signal)]),
                     summarize: ({ runtime, prompt }) => summarizeProgress(runtime, prompt),
                 },
-            });
+            };
+            if (opts.exitWithParent) {
+                const codeFile = fileURLToPath(import.meta.url);
+                const changed = watchCodeChange(() => codeFingerprint(path.dirname(codeFile), path.extname(codeFile)));
+                await runAttachedWeb({
+                    start: () => mod.startWebServer(startOptions),
+                    port,
+                    ppid: () => process.ppid,
+                    startPpid: LAUNCH_PPID,
+                    stdout: process.stdout,
+                    stdin: process.stdin,
+                    onSignal: (sig, handler) => process.on(sig, handler),
+                    writeErr: (line) => {
+                        try {
+                            fs.writeSync(2, line);
+                        }
+                        catch {
+                            // A closed stderr must not prevent the exit.
+                        }
+                    },
+                    exit: (code) => process.exit(code),
+                    fail: (message) => fail(message),
+                    probeHealth,
+                    intervalMs: beat * 1000,
+                    changed,
+                });
+                await new Promise(() => { });
+            }
+            const page = await mod.startWebServer(startOptions);
             console.log(page.url);
             const stop = (code) => {
                 void page.close().finally(() => process.exit(code));

package/dist/code-change.d.ts

@@ -1,5 +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";
+export declare const WEB_RESTART_MESSAGE = "status --web: 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. */

package/dist/code-change.js

@@ -2,6 +2,7 @@ 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";
+export const WEB_RESTART_MESSAGE = "status --web: 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 = [];

package/dist/monitor-lifecycle.d.ts

@@ -11,6 +11,8 @@ export interface MonitorDeps {
         resume: () => unknown;
     };
     ppid: () => number;
+    /** The parent pid recorded before any await; when absent the pid at call time is used. */
+    startPpid?: number;
     exit: (code: number) => void;
     onSignal: (sig: NodeJS.Signals, handler: () => void) => void;
     fail: (message: string) => void;

package/dist/monitor-lifecycle.js

@@ -1,7 +1,7 @@
 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();
+    const startPpid = d.startPpid ?? d.ppid();
     let timer;
     let done = false;
     const stop = (code) => {

package/dist/prompt.js

@@ -13,6 +13,25 @@ function memoryLabel(agent, dir) {
     const kind = dir === (agent.memory.global ?? agent.sharedMemory?.global) ? "global (all projects" : "project (all tasks of this project";
     return shared ? `${kind}, read-only for you: ${instance1} maintains it)` : `${kind})`;
 }
+/** Escape a value for a double-quoted attribute of the tags that wrap injected data. */
+function attr(v) {
+    return v.replace(/&/g, "&amp;").replace(/"/g, "&quot;").replace(/</g, "&lt;");
+}
+/** One memory directory as a `<memory>` block: its MEMORY.md index, or a hint to create one. */
+function memoryBlock(agent, dir) {
+    const idx = readCapped(path.join(dir, "MEMORY.md"), MEMORY_INDEX_LIMIT);
+    const scope = memoryLabel(agent, dir).split(" ")[0];
+    const out = [`<memory scope="${attr(scope ?? "")}" dir="${attr(dir)}" index="MEMORY.md">`];
+    if (!idx)
+        out.push("(no MEMORY.md yet — create one when you have something worth keeping)");
+    else {
+        out.push(idx.text.trim());
+        if (idx.truncated)
+            out.push(`\n[index truncated at ${MEMORY_INDEX_LIMIT} bytes — trim it]`);
+    }
+    out.push("</memory>");
+    return out;
+}
 /** Lead-only rules that keep the number of wake-ups down; placed after the progress-tracking block. */
 export const WAKE_ECONOMY_SECTION = [
     "## Keeping wake-ups few",
@@ -132,15 +151,9 @@ export function buildSoloSystemPrompt(project, agent) {
 /** The prompt of a `call`: the memory indexes the agent is used to, then the task. */
 export function buildCallUserPrompt(agent, task) {
     const parts = [];
-    for (const dir of memoryDirs(agent)) {
-        const idx = readCapped(path.join(dir, "MEMORY.md"), MEMORY_INDEX_LIMIT);
-        parts.push(`# Your ${memoryLabel(agent, dir).split(" ")[0]} memory index (${dir}/MEMORY.md)`);
-        if (!idx)
-            parts.push("(no MEMORY.md yet — create one when you have something worth keeping)", "");
-        else
-            parts.push(idx.text.trim(), ...(idx.truncated ? [`[index truncated at ${MEMORY_INDEX_LIMIT} bytes — trim it]`] : []), "");
-    }
-    parts.push("# Task", task.trim());
+    for (const dir of memoryDirs(agent))
+        parts.push(...memoryBlock(agent, dir), "");
+    parts.push("<task>", task.trim(), "</task>");
     return parts.join("\n");
 }
 /** Everything that goes to the runtime's system prompt: the persona plus the team protocol. */
@@ -269,7 +282,7 @@ export function pickMessages(project, agent, queue) {
 export function buildUserPrompt(project, agent, unread, handleCount = 1, handoff = false) {
     const parts = [];
     const common = readCapped(commonFile(project), COMMON_LIMIT);
-    parts.push("# Shared team context (COMMON.md)");
+    parts.push('<shared_context source="COMMON.md">');
     if (!common)
         parts.push("(empty)");
     else {
@@ -278,56 +291,48 @@ export function buildUserPrompt(project, agent, unread, handleCount = 1, handoff
             parts.push(`\n[COMMON.md was truncated at ${COMMON_LIMIT} bytes — the lead should condense it.]`);
         }
     }
-    for (const [title, kind] of [
-        ["Project decisions", "decisions"],
-        ["Project lessons", "lessons"],
+    parts.push("</shared_context>");
+    for (const [tag, kind] of [
+        ["project_decisions", "decisions"],
+        ["project_lessons", "lessons"],
     ]) {
         const view = buildRecordsView(project, kind, CONTEXT_LIMIT);
         if (view)
-            parts.push("", `# ${title}`, view); // nothing recorded yet: no heading, no tokens
+            parts.push("", `<${tag}>`, view, `</${tag}>`); // nothing recorded yet: no tag, no tokens
     }
     const handoffFile = handoff ? sharedIndex(project) : undefined;
     const notes = handoffFile ? readCapped(handoffFile, HANDOFF_LIMIT) : undefined;
     if (handoffFile && notes?.text.trim()) {
-        parts.push("", `# Handoff notes from earlier segments of this task (${handoffFile})`, notes.text.trim());
+        parts.push("", `<handoff_notes from="earlier segments of this task" file="${attr(handoffFile)}">`, notes.text.trim());
         if (notes.truncated)
             parts.push(`\n[handoff index truncated at ${HANDOFF_LIMIT} bytes — the lead should condense it.]`);
-        parts.push("The other files in that folder are there to read on demand.");
-    }
-    for (const dir of [...Object.values(agent.sharedMemory ?? {}), ...memoryDirs(agent)]) {
-        const idx = readCapped(path.join(dir, "MEMORY.md"), MEMORY_INDEX_LIMIT);
-        const label = memoryLabel(agent, dir).split(" ")[0];
-        parts.push("", `# Your ${label} memory index (${dir}/MEMORY.md)`);
-        if (!idx)
-            parts.push("(no MEMORY.md yet — create one when you have something worth keeping)");
-        else {
-            parts.push(idx.text.trim());
-            if (idx.truncated)
-                parts.push(`\n[index truncated at ${MEMORY_INDEX_LIMIT} bytes — trim it]`);
-        }
+        parts.push("The other files in that folder are there to read on demand.", "</handoff_notes>");
     }
+    for (const dir of [...Object.values(agent.sharedMemory ?? {}), ...memoryDirs(agent)])
+        parts.push("", ...memoryBlock(agent, dir));
     const sorted = [...unread].sort((a, b) => path.basename(a.file).localeCompare(path.basename(b.file)));
     const current = sorted.slice(0, handleCount);
     const queued = sorted.slice(handleCount);
-    parts.push("", current.length > 1 ? `# Messages to handle now (${current.length}, oldest first — decide on them together)` : "# Message to handle now");
+    parts.push("", current.length > 1 ? `<messages count="${current.length}" order="oldest first" note="decide on them together">` : `<messages count="${current.length}">`);
     if (current.length === 0)
         parts.push("(no message)");
     let remaining = MAIL_BATCH_LIMIT;
     current.forEach((m, i) => {
-        if (current.length > 1)
-            parts.push("", `## Message ${i + 1} of ${current.length}`);
+        parts.push(current.length > 1 ? `<message n="${i + 1}" of="${current.length}">` : "<message>");
         const raw = Buffer.from(m.body, "utf8");
         const shown = cutUtf8(raw, Math.min(MAIL_BODY_LIMIT, remaining));
         remaining -= shown.length;
         const body = shown.length === raw.length
             ? m.body
             : `${shown.toString("utf8")}\n[agent-lyceum: this message was cut at ${shown.length} of ${raw.length} bytes; read the whole message in \`${m.file}\` (it moves to \`read/\` in the same folder after this wake-up)]`;
-        parts.push(`id: ${m.meta.id}`, `from: ${senderLabel(m.meta.from, project.agents)}`, `type: ${m.meta.type}`, `thread: ${m.meta.thread}`, `subject: ${m.meta.subject}`, "", body);
+        parts.push(`id: ${m.meta.id}`, `from: ${senderLabel(m.meta.from, project.agents)}`, `type: ${m.meta.type}`, `thread: ${m.meta.thread}`, `subject: ${m.meta.subject}`, "", body, "</message>");
     });
+    parts.push("</messages>");
     if (queued.length) {
-        parts.push("", "# Queued messages (not handled in this wake-up; each gets its own wake-up later, titles only)");
+        parts.push("", '<queued_messages note="not handled in this wake-up; each gets its own wake-up later, titles only">');
         for (const m of queued)
             parts.push(`- from ${senderLabel(m.meta.from, project.agents)} [${m.meta.type}] "${m.meta.subject}" -> ${m.file}`);
+        parts.push("</queued_messages>");
     }
     return parts.join("\n");
 }

package/dist/quota.d.ts

@@ -20,6 +20,6 @@ type RateLimits = {
     secondary?: LimitWindow | null;
 };
 export declare function codexWindows(limits: RateLimits): QuotaWindow[];
-export declare function claudeQuota(): Promise<QuotaReport>;
-export declare function codexQuota(): Promise<QuotaReport>;
+export declare function claudeQuota(signal?: AbortSignal): Promise<QuotaReport>;
+export declare function codexQuota(signal?: AbortSignal): Promise<QuotaReport>;
 export {};

package/dist/quota.js

@@ -36,27 +36,35 @@ function windowOf(label, used, resets) {
 function roundPercent(n) {
     return Math.round(n * 10) / 10;
 }
-export async function claudeQuota() {
+export async function claudeQuota(signal) {
     try {
-        const text = await capture("claude", ["-p", "--no-session-persistence", "--output-format", "text", "/usage"], 20_000);
+        const text = await capture("claude", ["-p", "--no-session-persistence", "--output-format", "text", "/usage"], 20_000, signal);
         const windows = parseClaudeUsage(text.stdout);
         if (windows.length === 0)
             return { runtime: "claude", windows: [], error: firstLine(text.stderr) || firstLine(text.stdout) || "claude /usage 沒有回傳額度。" };
         return { runtime: "claude", windows };
     }
     catch (error) {
+        if (isAbort(error))
+            throw error;
         return { runtime: "claude", windows: [], error: missing("claude", error) };
     }
 }
-export async function codexQuota() {
+export async function codexQuota(signal) {
     try {
-        const limits = await readCodexLimits();
+        const limits = await readCodexLimits(signal);
         return { runtime: "codex", windows: codexWindows(limits) };
     }
     catch (error) {
+        if (isAbort(error))
+            throw error;
         return { runtime: "codex", windows: [], error: missing("codex", error) };
     }
 }
+/** An aborted quota read is a cancelled request, not a report: callers (the hub) discard it. */
+function isAbort(error) {
+    return error.name === "AbortError";
+}
 function missing(cmd, error) {
     const code = error.code;
     if (code === "ENOENT")
@@ -66,9 +74,9 @@ function missing(cmd, error) {
 function firstLine(text) {
     return text.split("\n").map((line) => line.trim()).find(Boolean) ?? "";
 }
-function capture(cmd, args, timeoutMs) {
+function capture(cmd, args, timeoutMs, signal) {
     return new Promise((resolve, reject) => {
-        const child = spawn(cmd, args, { stdio: ["ignore", "pipe", "pipe"] });
+        const child = spawn(cmd, args, { stdio: ["ignore", "pipe", "pipe"], ...(signal ? { signal } : {}) });
         let stdout = "";
         let stderr = "";
         const timer = setTimeout(() => {
@@ -87,9 +95,9 @@ function capture(cmd, args, timeoutMs) {
         });
     });
 }
-function readCodexLimits() {
+function readCodexLimits(signal) {
     return new Promise((resolve, reject) => {
-        const child = spawn("codex", ["app-server", "--stdio"], { stdio: ["pipe", "pipe", "pipe"] });
+        const child = spawn("codex", ["app-server", "--stdio"], { stdio: ["pipe", "pipe", "pipe"], ...(signal ? { signal } : {}) });
         let buf = "";
         const timer = setTimeout(() => {
             child.kill();

package/dist/web-attach.d.ts

@@ -0,0 +1,47 @@
+import type { EventEmitter } from "node:events";
+import { type MonitorDeps } from "./monitor-lifecycle.js";
+export type HealthProbe = {
+    kind: "ours";
+    pid: number;
+    home: string;
+} | {
+    kind: "foreign";
+} | {
+    kind: "timeout";
+};
+export interface AttachedWebDeps {
+    start: () => Promise<{
+        url: string;
+        close: () => Promise<void>;
+    }>;
+    /** The port that was asked for; `probeHealth` is called with it when binding fails because it is taken. */
+    port: number;
+    ppid: () => number;
+    /** The parent pid recorded before anything was awaited. */
+    startPpid: number;
+    stdout: EventEmitter & {
+        write: (chunk: string) => unknown;
+        destroyed?: boolean;
+        writable?: boolean;
+    };
+    stdin: MonitorDeps["stdin"];
+    onSignal: MonitorDeps["onSignal"];
+    /** Writes one complete line (with its newline) to stderr. */
+    writeErr: (line: string) => void;
+    exit: (code: number) => void;
+    fail: (message: string) => void;
+    probeHealth: (port: number) => Promise<HealthProbe>;
+    intervalMs: number;
+    /** True once the code on disk changed (`watchCodeChange`). */
+    changed?: () => boolean;
+    /** Replaceable in tests. */
+    monitor?: (d: MonitorDeps) => void;
+}
+/** Ask `GET /health` on a taken port who holds it. Aborts after 1 s; an aborted or silent holder is `timeout`. */
+export declare function probeHealth(port: number): Promise<HealthProbe>;
+/**
+ * `status --web --exit-with-parent`: the page lives and dies with the launcher.
+ * The parent pid is checked before the server starts, stop signals are caught while it starts, and the server
+ * is closed (never left behind) on every path that ends the process.
+ */
+export declare function runAttachedWeb(d: AttachedWebDeps): Promise<void>;

package/dist/web-attach.js

@@ -0,0 +1,102 @@
+import http from "node:http";
+import { WATCH_RESTART_EXIT, WEB_RESTART_MESSAGE } from "./code-change.js";
+import { runMonitor } from "./monitor-lifecycle.js";
+const SIGNAL_CODES = [["SIGINT", 130], ["SIGTERM", 143], ["SIGHUP", 129]];
+/** Ask `GET /health` on a taken port who holds it. Aborts after 1 s; an aborted or silent holder is `timeout`. */
+export async function probeHealth(port) {
+    const signal = AbortSignal.timeout(1000);
+    return new Promise((resolve) => {
+        const timeout = () => resolve({ kind: "timeout" });
+        const req = http.get({ host: "127.0.0.1", port, path: "/health", signal }, (res) => {
+            let body = "";
+            res.setEncoding("utf8");
+            res.on("data", (chunk) => {
+                body += chunk;
+                if (body.length > 65_536)
+                    res.destroy();
+            });
+            res.on("error", () => (signal.aborted ? timeout() : resolve({ kind: "foreign" })));
+            res.on("end", () => {
+                try {
+                    const j = JSON.parse(body);
+                    if (j.app === "agent-lyceum-web" && typeof j.pid === "number")
+                        return resolve({ kind: "ours", pid: j.pid, home: String(j.home ?? "") });
+                }
+                catch {
+                    /* not ours */
+                }
+                resolve({ kind: "foreign" });
+            });
+        });
+        req.on("error", () => (signal.aborted ? timeout() : resolve({ kind: "foreign" })));
+    });
+}
+/**
+ * `status --web --exit-with-parent`: the page lives and dies with the launcher.
+ * The parent pid is checked before the server starts, stop signals are caught while it starts, and the server
+ * is closed (never left behind) on every path that ends the process.
+ */
+export async function runAttachedWeb(d) {
+    if (d.ppid() !== d.startPpid)
+        return d.exit(129);
+    let stopCode;
+    let started = false;
+    for (const [sig, code] of SIGNAL_CODES) {
+        d.onSignal(sig, () => {
+            if (!started)
+                stopCode ??= code;
+        });
+    }
+    d.stdout.on("error", (e) => {
+        if (!started && (e.code === "EPIPE" || e.code === "EIO"))
+            stopCode ??= 0;
+    });
+    let page;
+    try {
+        page = await d.start();
+    }
+    catch (error) {
+        const message = error.message;
+        const taken = /already in use/.test(message);
+        if (!taken) {
+            d.writeErr(`status --web: ${message}\n`);
+            return d.exit(1);
+        }
+        const holder = await d.probeHealth(d.port);
+        if (holder.kind === "ours")
+            d.writeErr(`status --web: port ${d.port} in use by agent-lyceum-web pid ${holder.pid} home ${holder.home}\n`);
+        else if (holder.kind === "foreign")
+            d.writeErr(`status --web: port ${d.port} in use by another program\n`);
+        else
+            d.writeErr(`status --web: port ${d.port} in use, no answer in 1 s\n`);
+        return d.exit(1);
+    }
+    const closeThenExit = (code) => void page.close().then(() => d.exit(code), () => d.exit(code));
+    if (stopCode !== undefined)
+        return closeThenExit(stopCode);
+    if (d.ppid() !== d.startPpid)
+        return closeThenExit(129);
+    started = true;
+    d.stdout.write(`${page.url}\n`);
+    let stopping = false;
+    (d.monitor ?? runMonitor)({
+        draw: () => {
+            if (stopping)
+                return;
+            d.stdout.write("\n");
+            if (d.changed?.()) {
+                stopping = true;
+                d.writeErr(`${WEB_RESTART_MESSAGE}\n`);
+                closeThenExit(WATCH_RESTART_EXIT);
+            }
+        },
+        intervalMs: d.intervalMs,
+        stdout: d.stdout,
+        stdin: d.stdin,
+        ppid: d.ppid,
+        startPpid: d.startPpid,
+        exit: closeThenExit,
+        onSignal: d.onSignal,
+        fail: d.fail,
+    });
+}

package/package.json

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

package/web/dist/server/guard.js

@@ -0,0 +1,65 @@
+/** Host and Origin checks against DNS rebinding and cross-site `POST /quota`. Pure: no sockets, no node imports. */
+const LOOPBACK_NAMES = ["127.0.0.1", "localhost", "::1"];
+/** Trim, lowercase, drop `:port` or `[v6]:port` brackets and one trailing dot. Undefined when there is nothing usable. */
+export function normalizeHost(value) {
+    let host = (value ?? "").trim().toLowerCase();
+    if (!host)
+        return undefined;
+    if (host.startsWith("[")) {
+        const end = host.indexOf("]");
+        if (end < 0)
+            return undefined;
+        host = host.slice(1, end);
+    }
+    else if ((host.match(/:/g) ?? []).length === 1) {
+        host = host.slice(0, host.indexOf(":"));
+    }
+    if (host.endsWith("."))
+        host = host.slice(0, -1);
+    return host || undefined;
+}
+export function isLoopbackHost(host) {
+    const name = normalizeHost(host);
+    if (!name)
+        return false;
+    return name === "localhost" || name === "::1" || /^127\.\d+\.\d+\.\d+$/.test(name);
+}
+function allowed(opts) {
+    const names = new Set(LOOPBACK_NAMES);
+    for (const name of [opts.bindHost, ...opts.allowHosts]) {
+        const n = normalizeHost(name);
+        if (n)
+            names.add(n);
+    }
+    return names;
+}
+/** The HTTP status to reject with (400 or 403), or undefined when the request may proceed. */
+export function checkRequest(req, opts) {
+    if (!isLoopbackHost(opts.bindHost))
+        return undefined;
+    const names = allowed(opts);
+    const host = normalizeHost(req.host);
+    if (!host)
+        return 400;
+    if (!names.has(host))
+        return 403;
+    if (req.method === "POST" && req.pathname === "/quota" && req.origin !== undefined) {
+        if (req.origin === "null")
+            return 403;
+        let url;
+        try {
+            url = new URL(req.origin);
+        }
+        catch {
+            return 403;
+        }
+        if (url.protocol !== "http:")
+            return 403;
+        const name = normalizeHost(url.hostname);
+        if (!name || !names.has(name))
+            return 403;
+        if (Number(url.port || 80) !== opts.port)
+            return 403;
+    }
+    return undefined;
+}

package/web/dist/server/hub.js

@@ -4,6 +4,7 @@ export function createWebHub(factory) {
     const listeners = new Set();
     let quota;
     let quotaToken = 0;
+    const quotaAbort = new AbortController();
     const emit = (event) => {
         for (const listener of listeners) {
             try {
@@ -61,7 +62,7 @@ export function createWebHub(factory) {
             return Promise.resolve(quota);
         const token = ++quotaToken;
         return factory
-            .quota()
+            .quota(quotaAbort.signal)
             .then((reports) => {
             if (token !== quotaToken)
                 return quota;
@@ -80,6 +81,7 @@ export function createWebHub(factory) {
         },
         close() {
             quotaToken += 1;
+            quotaAbort.abort(); // asks in-flight quota children to end (SIGTERM); it does not wait for them
             for (const watch of watchers.values())
                 watch.close();
             watchers.clear();

package/web/dist/start.js

@@ -1,15 +1,35 @@
 import { createWebHub } from "./server/hub.js";
-import { attachEvents, listen, serveStatic } from "./server/http.js";
+import { checkRequest } from "./server/guard.js";
+import { attachEvents, listen as listenHttp, serveStatic } from "./server/http.js";
 import { openBrowser } from "./server/open.js";
 import { handleSummary } from "./server/summary.js";
+const JSON_HEADERS = { "Content-Type": "application/json; charset=utf-8", "Cache-Control": "no-store" };
+/** Binds first; the hub, the quota reads and the timers start only once the port is ours, and are undone if that fails. */
 export async function startWebServer(opts) {
     const hub = createWebHub(opts.factory);
-    hub.start();
-    hub.refreshQuota();
-    const heartbeat = setInterval(() => hub.beat(), opts.heartbeatMs ?? 5_000);
-    const quotaBeat = setInterval(() => hub.refreshQuota(), 60_000);
-    const { server, sockets } = await listen(opts.port, opts.host, (req, res) => {
+    const startedAt = new Date().toISOString();
+    let boundPort = opts.port;
+    const { server, sockets } = await (opts.listen ?? listenHttp)(opts.port, opts.host, (req, res) => {
         const pathname = (req.url ?? "/").split("?")[0] ?? "/";
+        const origin = req.headers.origin;
+        const rejected = checkRequest({ method: req.method, pathname, host: req.headers.host, origin: Array.isArray(origin) ? origin[0] : origin }, { bindHost: opts.host, allowHosts: opts.allowHosts ?? [], port: boundPort });
+        if (rejected) {
+            res.writeHead(rejected);
+            res.end();
+            return;
+        }
+        if (pathname === "/health" && (req.method === "GET" || req.method === "HEAD")) {
+            res.writeHead(200, JSON_HEADERS);
+            res.end(JSON.stringify({
+                app: "agent-lyceum-web",
+                version: opts.identity?.version ?? "unknown",
+                pid: process.pid,
+                ppid: process.ppid,
+                home: opts.identity?.home ?? "",
+                started_at: startedAt,
+            }));
+            return;
+        }
         if (pathname === "/events") {
             attachEvents(hub, req, res);
             return;
@@ -18,14 +38,14 @@ export async function startWebServer(opts) {
             void handleSummary(req, res, hub, opts.factory.summarize).catch(() => {
                 if (res.headersSent)
                     return;
-                res.writeHead(500, { "Content-Type": "application/json; charset=utf-8", "Cache-Control": "no-store" });
+                res.writeHead(500, JSON_HEADERS);
                 res.end(JSON.stringify({ error: "沒有寫出摘要。" }));
             });
             return;
         }
         if (pathname === "/quota" && req.method === "POST") {
             void hub.refreshQuota().then((reports) => {
-                res.writeHead(200, { "Content-Type": "application/json; charset=utf-8", "Cache-Control": "no-store" });
+                res.writeHead(200, JSON_HEADERS);
                 res.end(JSON.stringify(reports ?? []));
             }, () => {
                 if (res.headersSent)
@@ -43,26 +63,36 @@ export async function startWebServer(opts) {
         serveStatic(opts.staticDir, req, res);
     });
     const address = server.address();
-    const port = typeof address === "object" && address ? address.port : opts.port;
+    boundPort = typeof address === "object" && address ? address.port : opts.port;
+    let heartbeat;
+    let quotaBeat;
+    const close = () => new Promise((resolve, reject) => {
+        clearInterval(heartbeat);
+        clearInterval(quotaBeat);
+        hub.close();
+        for (const socket of sockets)
+            socket.destroy();
+        server.close((err) => {
+            if (err && err.code !== "ERR_SERVER_NOT_RUNNING")
+                reject(err);
+            else
+                resolve();
+        });
+    });
     const host = opts.host === "0.0.0.0" || opts.host === "::" ? "127.0.0.1" : opts.host;
     const shown = host.includes(":") ? `[${host}]` : host;
-    const url = `http://${shown}:${port}/`;
-    if (opts.open)
-        openBrowser(url);
-    return {
-        url,
-        close: () => new Promise((resolve, reject) => {
-            clearInterval(heartbeat);
-            clearInterval(quotaBeat);
-            hub.close();
-            for (const socket of sockets)
-                socket.destroy();
-            server.close((err) => {
-                if (err && err.code !== "ERR_SERVER_NOT_RUNNING")
-                    reject(err);
-                else
-                    resolve();
-            });
-        }),
-    };
+    const url = `http://${shown}:${boundPort}/`;
+    try {
+        hub.start();
+        void hub.refreshQuota();
+        heartbeat = setInterval(() => hub.beat(), opts.heartbeatMs ?? 5_000);
+        quotaBeat = setInterval(() => void hub.refreshQuota(), 60_000);
+        if (opts.open)
+            openBrowser(url);
+    }
+    catch (error) {
+        await close().catch(() => { });
+        throw error;
+    }
+    return { url, close };
 }