agent-lyceum 0.4.9

package/dist/process-runner.js

@@ -0,0 +1,165 @@
+import { spawn } 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. */
+export const TAIL_BYTES = 64 * 1024;
+/** A stdout line longer than this is not offered to the adapter's parser (it is still logged). */
+export const MAX_LINE_BYTES = 16 * 1024 * 1024;
+class Tail {
+    buf = Buffer.alloc(0);
+    push(chunk) {
+        this.buf = Buffer.concat([this.buf, chunk]);
+        if (this.buf.length > TAIL_BYTES * 2)
+            this.buf = this.buf.subarray(this.buf.length - TAIL_BYTES);
+    }
+    text() {
+        return (this.buf.length > TAIL_BYTES ? this.buf.subarray(this.buf.length - TAIL_BYTES) : this.buf).toString("utf8");
+    }
+}
+/** Fallback for adapters without `stream`: keep the head of stdout (bounded) for their `parse`. */
+const FALLBACK_STDOUT_BYTES = 8 * 1024 * 1024;
+function endStream(s) {
+    return new Promise((resolve) => {
+        const t = setTimeout(() => {
+            s.destroy();
+            resolve();
+        }, 2000);
+        t.unref();
+        s.end(() => {
+            clearTimeout(t);
+            resolve();
+        });
+    });
+}
+/**
+ * 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,
+ * and the whole process tree is gone by then (SIGTERM, then SIGKILL after `killGraceMs`).
+ */
+export function runInvocation(inv, opts) {
+    const grace = opts.killGraceMs ?? 5000;
+    const settleWait = opts.settleWaitMs ?? 1000;
+    const cancelled = { ok: false, text: "", exitCode: null, timedOut: false, cancelled: true, error: "cancelled" };
+    if (opts.signal?.aborted)
+        return Promise.resolve(cancelled);
+    return new Promise((resolve) => {
+        fs.mkdirSync(opts.logDir, { recursive: true });
+        const outLog = fs.createWriteStream(path.join(opts.logDir, "stdout.log"));
+        const errLog = fs.createWriteStream(path.join(opts.logDir, "stderr.log"));
+        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" });
+        const stdoutTail = new Tail();
+        const stderrTail = new Tail();
+        const parser = inv.stream?.();
+        let fallback = Buffer.alloc(0);
+        let exitCode;
+        let reason;
+        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 */
+            }
+        };
+        const finish = (spawnError) => {
+            if (settled)
+                return;
+            settled = true;
+            for (const t of timers)
+                clearTimeout(t);
+            opts.signal?.removeEventListener("abort", onAbort);
+            killGroup("SIGKILL"); // whatever of the tree is still around
+            child.stdout?.destroy();
+            child.stderr?.destroy();
+            void Promise.all([endStream(outLog), endStream(errLog)]).then(() => {
+                if (spawnError) {
+                    const hint = spawnError.code === "ENOENT" ? ` ("${inv.cmd}" not found on PATH)` : "";
+                    return resolve({ ok: false, text: "", exitCode: null, timedOut: false, error: `${spawnError.message}${hint}` });
+                }
+                if (reason === "cancel")
+                    return resolve({ ...cancelled, exitCode: exitCode ?? null });
+                if (reason === "timeout")
+                    return resolve({ ok: false, text: "", exitCode: exitCode ?? null, timedOut: true, error: `timed out after ${opts.timeoutSec}s` });
+                const parsed = parser
+                    ? parser.finish({ code: exitCode ?? null, stdoutTail: stdoutTail.text(), stderrTail: stderrTail.text() })
+                    : inv.parse({ stdout: fallback.length ? fallback.toString("utf8") : stdoutTail.text(), stderr: stderrTail.text(), code: exitCode ?? null });
+                resolve({ ...parsed, exitCode: exitCode ?? null, timedOut: false });
+            });
+        };
+        /** Stop the whole tree, then give up on the pipes shortly after, whatever still holds them. */
+        const stop = (why) => {
+            if (settled || reason)
+                return;
+            reason = why;
+            killGroup("SIGTERM");
+            timers.push(setTimeout(() => killGroup("SIGKILL"), grace));
+            timers.push(setTimeout(() => finish(), grace + settleWait));
+        };
+        function onAbort() {
+            stop("cancel");
+        }
+        opts.signal?.addEventListener("abort", onAbort, { once: true });
+        timers.push(setTimeout(() => stop("timeout"), opts.timeoutSec * 1000));
+        // stdout: log in full with backpressure, keep a tail, and give each line to the adapter
+        let partial = "";
+        let skipping = false;
+        const onLine = (l) => parser?.line(l);
+        child.stdout.on("data", (chunk) => {
+            if (!outLog.write(chunk)) {
+                child.stdout.pause();
+                outLog.once("drain", () => child.stdout.resume());
+            }
+            stdoutTail.push(chunk);
+            if (!parser && fallback.length < FALLBACK_STDOUT_BYTES)
+                fallback = Buffer.concat([fallback, chunk]);
+            if (!parser)
+                return;
+            let text = partial + chunk.toString("utf8");
+            partial = "";
+            let nl;
+            while ((nl = text.indexOf("\n")) >= 0) {
+                const line = text.slice(0, nl).replace(/\r$/, "");
+                text = text.slice(nl + 1);
+                if (skipping)
+                    skipping = false;
+                else if (line)
+                    onLine(line);
+            }
+            if (skipping || text.length > MAX_LINE_BYTES) {
+                skipping = true; // drop the rest of an enormous line
+            }
+            else
+                partial = text;
+        });
+        child.stderr.on("data", (chunk) => {
+            if (!errLog.write(chunk)) {
+                child.stderr.pause();
+                errLog.once("drain", () => child.stderr.resume());
+            }
+            stderrTail.push(chunk);
+        });
+        child.on("error", (e) => finish(e));
+        child.on("exit", (code) => {
+            exitCode = code;
+            // The runtime is gone. Normally its pipes close at once; if a descendant still holds them, stop waiting soon.
+            timers.push(setTimeout(() => finish(), settleWait));
+        });
+        child.on("close", () => {
+            if (partial && parser && !skipping)
+                onLine(partial.replace(/\r$/, ""));
+            partial = "";
+            finish();
+        });
+        child.stdin.on("error", () => { });
+        child.stdin.end(inv.stdin);
+    });
+}

package/dist/project-lock.d.ts

@@ -0,0 +1,30 @@
+export declare const LOCK_FILE = "lock.json";
+export interface LockInfo {
+    token: string;
+    hostname: string;
+    pid: number;
+    /** `ps` start time of `pid`, to tell the holder from a different process that reused the pid. */
+    pid_started?: string;
+    run_id: string;
+    acquired_at: string;
+    heartbeat_at: string;
+}
+export interface ProjectLease {
+    readonly info: LockInfo;
+    /** True once another process replaced our lock file; the run should stop writing. */
+    readonly lost: boolean;
+    release(): void;
+}
+export interface LockOptions {
+    heartbeatMs?: number;
+}
+/** The lock of a project (`root` = the project's home directory), if one is held and readable. */
+export declare function inspectProjectLock(root: string): LockInfo | 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 acquireProjectLock(root: string, runId: string, opts?: LockOptions): ProjectLease;
+/** Remove the lock regardless of owner (the `unlock --force` escape hatch). Returns what was there, if readable. */
+export declare function forceUnlock(root: string): LockInfo | undefined;

package/dist/project-lock.js

@@ -0,0 +1,186 @@
+import crypto from "node:crypto";
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { atomicWrite } from "./fs-util.js";
+export const LOCK_FILE = "lock.json";
+const RECLAIM_FILE = "lock.json.reclaim";
+const HEARTBEAT_MS = 5000;
+function pidStart(pid) {
+    const r = spawnSync("ps", ["-o", "lstart=", "-p", String(pid)], { encoding: "utf8" });
+    const out = r.status === 0 ? r.stdout.trim() : "";
+    return out || undefined;
+}
+function readLock(root) {
+    let text;
+    try {
+        text = fs.readFileSync(path.join(root, LOCK_FILE), "utf8");
+    }
+    catch {
+        return { kind: "none" };
+    }
+    try {
+        const j = JSON.parse(text);
+        if (j && typeof j.token === "string" && typeof j.pid === "number" && typeof j.run_id === "string")
+            return { kind: "ok", info: j };
+    }
+    catch {
+        /* fall through */
+    }
+    return { kind: "unreadable" };
+}
+/** The lock of a project (`root` = the project's home directory), if one is held and readable. */
+export function inspectProjectLock(root) {
+    const r = readLock(root);
+    return r.kind === "ok" ? r.info : 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 function lockHolderAlive(info) {
+    try {
+        process.kill(info.pid, 0);
+    }
+    catch (e) {
+        if (e.code !== "EPERM")
+            return false;
+    }
+    if (info.pid_started) {
+        const now = pidStart(info.pid);
+        if (now && now !== info.pid_started)
+            return false;
+    }
+    return true;
+}
+function heldError(info) {
+    const late = Math.round((Date.now() - Date.parse(info.heartbeat_at)) / 1000);
+    return new Error(`This project is still running: run ${info.run_id} (pid ${info.pid}, heartbeat ${Number.isFinite(late) ? late : "?"}s ago). ` +
+        `Only one run per project at a time; wait for it to end, or stop it first.`);
+}
+function unreadableError(root) {
+    return new Error(`The project lock ${path.join(root, LOCK_FILE)} cannot be read or has no known owner. Check that no run is active, then run \`agent-lyceum unlock --force\`.`);
+}
+/** Create the lock file only if absent: write a private temp file, then hard-link it into place (atomic, never half-written). */
+function tryCreate(root, info) {
+    const tmp = path.join(root, `.${LOCK_FILE}.${info.token}.tmp`);
+    fs.writeFileSync(tmp, JSON.stringify(info, null, 2));
+    try {
+        fs.linkSync(tmp, path.join(root, LOCK_FILE));
+        return true;
+    }
+    catch (e) {
+        if (e.code === "EEXIST")
+            return false;
+        throw e;
+    }
+    finally {
+        fs.rmSync(tmp, { force: true });
+    }
+}
+/** Replace a lock whose holder is gone. Reclaimers take a short mutex so two of them cannot delete each other's fresh lock. */
+function reclaim(root, info, stale) {
+    const mutex = path.join(root, RECLAIM_FILE);
+    try {
+        if (Date.now() - fs.statSync(mutex).mtimeMs > 10_000)
+            fs.rmSync(mutex, { force: true });
+    }
+    catch {
+        /* no mutex yet */
+    }
+    let fd;
+    try {
+        fd = fs.openSync(mutex, "wx");
+    }
+    catch {
+        return false;
+    }
+    try {
+        const again = readLock(root);
+        if (again.kind !== "ok" || again.info.token !== stale.token)
+            return false;
+        fs.rmSync(path.join(root, LOCK_FILE), { force: true });
+        return tryCreate(root, info);
+    }
+    finally {
+        fs.closeSync(fd);
+        fs.rmSync(mutex, { force: true });
+    }
+}
+export function acquireProjectLock(root, runId, opts = {}) {
+    fs.mkdirSync(root, { recursive: true });
+    const now = new Date().toISOString();
+    const info = {
+        token: crypto.randomBytes(16).toString("hex"),
+        hostname: os.hostname(),
+        pid: process.pid,
+        pid_started: pidStart(process.pid),
+        run_id: runId,
+        acquired_at: now,
+        heartbeat_at: now,
+    };
+    for (let attempt = 0;; attempt++) {
+        if (tryCreate(root, info))
+            break;
+        const cur = readLock(root);
+        if (cur.kind === "unreadable")
+            throw unreadableError(root);
+        if (cur.kind === "none")
+            continue; // released between our two calls
+        if (lockHolderAlive(cur.info))
+            throw heldError(cur.info);
+        if (reclaim(root, info, cur.info))
+            break;
+        if (attempt >= 5)
+            throw new Error(`Could not take the project lock ${path.join(root, LOCK_FILE)}; another process is reclaiming it. Try again.`);
+    }
+    let released = false;
+    let lost = false;
+    const file = path.join(root, LOCK_FILE);
+    const mine = () => {
+        const r = readLock(root);
+        return r.kind === "ok" && r.info.token === info.token;
+    };
+    const timer = setInterval(() => {
+        if (released)
+            return;
+        if (!mine()) {
+            lost = true;
+            clearInterval(timer);
+            return;
+        }
+        info.heartbeat_at = new Date().toISOString();
+        try {
+            atomicWrite(file, JSON.stringify(info, null, 2));
+        }
+        catch {
+            /* try again next tick */
+        }
+    }, opts.heartbeatMs ?? HEARTBEAT_MS);
+    timer.unref();
+    const release = () => {
+        if (released)
+            return;
+        released = true;
+        clearInterval(timer);
+        process.off("exit", release);
+        if (mine())
+            fs.rmSync(file, { force: true });
+    };
+    process.on("exit", release);
+    return {
+        info,
+        get lost() {
+            return lost;
+        },
+        release,
+    };
+}
+/** Remove the lock regardless of owner (the `unlock --force` escape hatch). Returns what was there, if readable. */
+export function forceUnlock(root) {
+    const info = inspectProjectLock(root);
+    fs.rmSync(path.join(root, LOCK_FILE), { force: true });
+    fs.rmSync(path.join(root, RECLAIM_FILE), { force: true });
+    return info;
+}

package/dist/prompt.d.ts

@@ -0,0 +1,11 @@
+import type { ResolvedAgent, ResolvedProject } from "./config.js";
+import type { Message } from "./mailbox.js";
+export declare const COMMON_LIMIT: number;
+export declare const MEMORY_INDEX_LIMIT: number;
+export declare const LEAD_BATCH_LIMIT = 5;
+export declare function readPersona(agent: ResolvedAgent): 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 for the lead a run of `reply`/`failure` mail (up to LEAD_BATCH_LIMIT) so it decides once on all of it. */
+export declare function pickMessages(project: ResolvedProject, agent: ResolvedAgent, queue: Message[]): Message[];
+export declare function buildUserPrompt(project: ResolvedProject, agent: ResolvedAgent, unread: Message[], handleCount?: number): string;

package/dist/prompt.js

@@ -0,0 +1,125 @@
+import fs from "node:fs";
+import path from "node:path";
+import { REQUIRED_SECTIONS } from "./format.js";
+import { commonFile, memoryDirs, outboxDir, repoDirFor } from "./policy.js";
+function memoryLabel(agent, dir) {
+    if (dir === agent.memory.task)
+        return "task (this task only, isolated)";
+    return dir === agent.memory.global ? "global (all projects)" : "project (all tasks of this project)";
+}
+export const COMMON_LIMIT = 8 * 1024;
+export const MEMORY_INDEX_LIMIT = 4 * 1024;
+export const LEAD_BATCH_LIMIT = 5;
+const BATCHABLE = new Set(["reply", "failure"]);
+function readCapped(file, limit) {
+    if (!fs.existsSync(file))
+        return undefined;
+    const buf = fs.readFileSync(file);
+    if (buf.length <= limit)
+        return { text: buf.toString("utf8"), truncated: false };
+    return { text: buf.subarray(0, limit).toString("utf8"), truncated: true };
+}
+export function readPersona(agent) {
+    return fs.readFileSync(agent.agentMd, "utf8").trim();
+}
+/** Everything that goes to the runtime's system prompt: the persona plus the team protocol. */
+export function buildSystemPrompt(project, agent) {
+    const outbox = outboxDir(project, agent.name);
+    const mates = Object.keys(project.agents).filter((n) => n !== agent.name);
+    const recipients = agent.canMessage === "all" ? mates : agent.canMessage.filter((n) => project.agents[n] && n !== agent.name);
+    const isLead = agent.name === project.lead;
+    const lines = [];
+    lines.push(readPersona(agent), "", "---", "", "# Team protocol (injected by agent-lyceum)", "");
+    lines.push(`You are **${agent.name}**, a member of the team "${project.name}". You work in the repository \`${repoDirFor(project, agent.name)}\`.`, ...(project.workspaces?.[agent.name]
+        ? [
+            `That directory is your own isolated git worktree (branch \`${project.workspaces[agent.name].branch}\`): teammates cannot see your changes while you work, and you cannot see theirs. Do not commit, push, switch branches or touch any other checkout; the dispatcher collects your changes from this directory after you finish.`,
+        ]
+        : []), `The team lead is **${project.lead}**${isLead ? " (that is you)" : ""}. Teammates: ${mates.join(", ") || "(none)"}.`, "", "## Sending mail", "You cannot talk to teammates directly. Mail you receive is shown in your prompt. To send mail, create a Markdown file", `(any name ending in \`.md\`) directly inside \`${outbox}\` with this exact shape:`, "", "```", "---", "to: <agent-name>", "type: reply        # task | reply" + (isLead ? " | done" : ""), "subject: <short subject>", "reply_to: <message id>   # optional", "---", "", "<body>", "```", "", `You may send to: ${recipients.join(", ") || "(nobody)"}.`, isLead
+        ? `When the whole job is finished, send a message with \`type: done\` (no \`to\` needed). That ends the run. A summary in your reply text is never delivered and does not end the run: after the last teammate reply is verified you MUST send \`done\` (or a \`task\` for the remaining work), or the run stops as "idle" with no final report.`
+        : `Report results to the lead by mail; the lead decides what happens next.`, isLead
+        ? "Each wake-up handles one message, except that several `reply`/`failure` messages waiting together are handed to you in one wake-up: weigh them together, then decide the next step once."
+        : "Each wake-up handles one message. Do the work it asks, then send the replies that are needed, then stop.", "", "## Message format", "The body of every `task` and `reply` must contain these `##` headings, exactly as written (write `None` under a heading if there is nothing to say).", "Mail missing a heading is still delivered, but is flagged to the recipient.", "", `- \`task\`: ${REQUIRED_SECTIONS.task.map((h) => `\`## ${h}\``).join(", ")} (Upstream = id of the mail this task derives from, or \`None\`).`, `- \`reply\`: ${REQUIRED_SECTIONS.reply.map((h) => `\`## ${h}\``).join(", ")}.`, isLead
+        ? "- `done`: your final report to the user (shown when the run ends, saved as `result.md`). Its frontmatter must contain `outcome: completed|partial|blocked|failed`, and the body the headings `## Result` (the actual deliverable or conclusion, not just \"done\"), `## Files` (paths created or changed), `## Verification` (what you ran or checked, and what it showed) and `## Not done` (anything skipped or unverified, or `None`). Only `completed` means success, and it needs all four headings and every checklist step ticked; if work remains or is blocked, say `partial`/`blocked`/`failed` (those need only `## Result` and `## Not done`). A `done` that breaks this is sent back to you and does not end the run."
+        : "- `done` has no required headings.", ...(isLead
+        ? [
+            "",
+            "## Progress tracking (optional, shown in `agent-lyceum status`)",
+            "Put a `## Steps` heading with a checklist (`- [ ] step`, `- [x] finished step`) in the mail you send. Each time you send mail, re-list the full",
+            "checklist with finished steps ticked; the latest one you send is what `status` reports as task progress.",
+            "Your final `done` mail must also include the full `## Steps` checklist. Tick only steps that were actually done and verified; leave undone ones",
+            "(e.g. build, app start, commit) unticked and say so in the mail instead of reporting them as finished.",
+        ]
+        : []), "", "## Memory");
+    const mems = memoryDirs(agent);
+    if (mems.length === 0)
+        lines.push("You have no long-term memory directory.");
+    for (const m of mems) {
+        const label = memoryLabel(agent, m);
+        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.", "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)"}.`);
+    if (project.dispatcher.max_parallel > 1 && agent.owns.length > 0 && !isLead) {
+        lines.push(`- You own these repo paths and must only change files there: ${agent.owns.join(", ")}.`);
+    }
+    return lines.join("\n");
+}
+/** Messages one wake-up handles: the oldest one, or for the lead a run of `reply`/`failure` mail (up to LEAD_BATCH_LIMIT) so it decides once on all of it. */
+export function pickMessages(project, agent, queue) {
+    const sorted = [...queue].sort((a, b) => path.basename(a.file).localeCompare(path.basename(b.file)));
+    if (agent.name !== project.lead || !BATCHABLE.has(sorted[0]?.meta.type))
+        return sorted.slice(0, 1);
+    const run = [];
+    for (const m of sorted) {
+        if (!BATCHABLE.has(m.meta.type) || run.length >= LEAD_BATCH_LIMIT)
+            break;
+        run.push(m);
+    }
+    return run;
+}
+export function buildUserPrompt(project, agent, unread, handleCount = 1) {
+    const parts = [];
+    const common = readCapped(commonFile(project), COMMON_LIMIT);
+    parts.push("# Shared team context (COMMON.md)");
+    if (!common)
+        parts.push("(empty)");
+    else {
+        parts.push(common.text.trim());
+        if (common.truncated) {
+            parts.push(`\n[COMMON.md was truncated at ${COMMON_LIMIT} bytes — the lead should condense it.]`);
+        }
+    }
+    for (const dir of 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]`);
+        }
+    }
+    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");
+    if (current.length === 0)
+        parts.push("(no message)");
+    current.forEach((m, i) => {
+        if (current.length > 1)
+            parts.push("", `## Message ${i + 1} of ${current.length}`);
+        parts.push(`id: ${m.meta.id}`, `from: ${m.meta.from}`, `type: ${m.meta.type}`, `thread: ${m.meta.thread}`, `subject: ${m.meta.subject}`, "", m.body);
+    });
+    if (queued.length) {
+        parts.push("", "# Queued messages (not handled in this wake-up; each gets its own wake-up later, titles only)");
+        for (const m of queued)
+            parts.push(`- from ${m.meta.from} [${m.meta.type}] "${m.meta.subject}" -> ${m.file}`);
+    }
+    return parts.join("\n");
+}

package/dist/run-cleanup.d.ts

@@ -0,0 +1,51 @@
+import type { ResolvedProject } from "./config.js";
+export interface CleanupItem {
+    kind: "workspace" | "refs" | "task-memory" | "run";
+    /** One line for people. */
+    label: string;
+    path?: string;
+    agent?: string;
+}
+export interface CleanupPlan {
+    project: ResolvedProject;
+    runId: string;
+    runDir: string;
+    keepWorktrees: boolean;
+    /** What will be removed, in this order (the run itself last, so an interrupted clear can be found and repeated). */
+    items: CleanupItem[];
+    /** Reasons not to clear at all. */
+    refusals: string[];
+    /** Work that exists only in a worktree: kept, never deleted. */
+    keep: {
+        agent: string;
+        branch: string;
+        path: string;
+        files: string[];
+    }[];
+    /** Short description of the run, for messages. */
+    summary: string;
+}
+export interface CleanupReport {
+    done: CleanupItem[];
+    failed: {
+        item: CleanupItem;
+        error: string;
+    }[];
+}
+/**
+ * What clearing a run would do. Deletes nothing. Refuses (see `refusals`) while the run is running, or while
+ * a worktree holds work that is not in the repo, unless `keepWorktrees` keeps the worktrees and their branches.
+ */
+export declare function planRunCleanup(project: ResolvedProject, runId: string, opts?: {
+    keepWorktrees?: boolean;
+}): CleanupPlan;
+export interface ExecuteHooks {
+    /** Test seam: called after each item is done and recorded. */
+    afterItem?: (item: CleanupItem) => void;
+}
+/**
+ * Carry out a plan, step by step. Progress is written to a journal in the project home (outside the run being
+ * deleted), so an interrupted clear can simply be repeated. Stops at the first step that fails, leaving the run
+ * directory in place for the retry.
+ */
+export declare function executeRunCleanup(plan: CleanupPlan, hooks?: ExecuteHooks): CleanupReport;