agent-lyceum 0.11.2 → 0.13.0

package/dist/project-lock.d.ts

@@ -1,4 +1,14 @@
+/** The project-wide lock of older versions. Still read (it counts as one active run) and cleared; never written. */
 export declare const LOCK_FILE = "lock.json";
+/** One lock file per active run: `<project home>/locks/<run-id>.json`. */
+export declare const LOCKS_DIR = "locks";
+export interface LockOptions {
+    heartbeatMs?: number;
+    /** Most runs that may hold a lock of this project at once, this one included. Default 1. */
+    maxConcurrent?: number;
+    /** The holder needs the whole project (e.g. a memory tidy): refused while any other lock is alive, and it keeps every other lock out while held. */
+    exclusive?: boolean;
+}
 export interface LockInfo {
     token: string;
     hostname: string;
@@ -8,6 +18,8 @@ export interface LockInfo {
     run_id: string;
     acquired_at: string;
     heartbeat_at: string;
+    /** Held by an operation that needs the project to itself (a memory tidy). */
+    exclusive?: boolean;
 }
 export interface ProjectLease {
     readonly info: LockInfo;
@@ -15,9 +27,6 @@ export interface ProjectLease {
     readonly lost: boolean;
     release(): void;
 }
-export interface LockOptions {
-    heartbeatMs?: number;
-}
 /** Field 22 (starttime, in clock ticks) of a /proc/<pid>/stat line. The command name (field 2) may contain spaces and ")". */
 export declare function parseProcStat(text: string): string | undefined;
 export interface PidStartIo {
@@ -27,13 +36,21 @@ 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;
-/** 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;
+/** 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)`). */
+export declare function listUnreadableRunLocks(root: string): string[];
+/** The lock a run holds (per-run file, or an older version's `lock.json` written for that run), if readable. */
+export declare function inspectRunLock(root: string, runId: string): LockInfo | undefined;
 export declare function acquireProjectLock(root: string, runId: string, opts?: LockOptions): ProjectLease;
-/** Remove the lock regardless of owner (the `clear --lock --force` escape hatch). Returns what was there, if readable. */
-export declare function forceUnlock(root: string): LockInfo | undefined;
+/**
+ * Remove a lock regardless of owner (the `clear --lock --force` escape hatch). With a run id: that run's lock (and an
+ * older version's `lock.json` when it was written for that run). Without: only the older project-wide `lock.json`.
+ * Returns what was there, if readable.
+ */
+export declare function forceUnlock(root: string, runId?: string): LockInfo | undefined;

package/dist/project-lock.js

@@ -4,8 +4,11 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { atomicWrite } from "./fs-util.js";
+/** The project-wide lock of older versions. Still read (it counts as one active run) and cleared; never written. */
 export const LOCK_FILE = "lock.json";
-const RECLAIM_FILE = "lock.json.reclaim";
+/** One lock file per active run: `<project home>/locks/<run-id>.json`. */
+export const LOCKS_DIR = "locks";
+const ADMIT_FILE = ".admit";
 const HEARTBEAT_MS = 5000;
 /** Field 22 (starttime, in clock ticks) of a /proc/<pid>/stat line. The command name (field 2) may contain spaces and ")". */
 export function parseProcStat(text) {
@@ -47,10 +50,29 @@ function pidStart(pid) {
 }
 /** Two start times can only be compared when they were taken the same way. */
 const sameKind = (a, b) => a.startsWith("proc:") === b.startsWith("proc:");
-function readLock(root) {
+/**
+ * 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 && sameKind(now, info.pid_started) && now !== info.pid_started)
+            return false;
+    }
+    return true;
+}
+function readLockFile(file) {
     let text;
     try {
-        text = fs.readFileSync(path.join(root, LOCK_FILE), "utf8");
+        text = fs.readFileSync(file, "utf8");
     }
     catch {
         return { kind: "none" };
@@ -65,44 +87,118 @@ function readLock(root) {
     }
     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;
+const runLockFile = (root, runId) => path.join(root, LOCKS_DIR, `${runId}.json`);
+const legacyFile = (root) => path.join(root, LOCK_FILE);
+function assertRunId(runId) {
+    if (!/^[A-Za-z0-9][A-Za-z0-9_.-]*$/.test(runId))
+        throw new Error(`Invalid run id "${runId}" for a lock: use letters, digits, ".", "-" or "_".`);
 }
-/**
- * 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) {
+/** Per-run lock files (not temp or mutex files), then the old project-wide one if it exists. */
+function lockFiles(root) {
+    const dir = path.join(root, LOCKS_DIR);
+    let names = [];
     try {
-        process.kill(info.pid, 0);
+        names = fs.readdirSync(dir).filter((n) => n.endsWith(".json") && !n.startsWith("."));
     }
-    catch (e) {
-        if (e.code !== "EPERM")
-            return false;
+    catch {
+        /* no locks yet */
     }
-    if (info.pid_started) {
-        const now = pidStart(info.pid);
-        if (now && sameKind(now, info.pid_started) && now !== info.pid_started)
-            return false;
+    const files = names.sort().map((n) => path.join(dir, n));
+    if (fs.existsSync(legacyFile(root)))
+        files.push(legacyFile(root));
+    return files;
+}
+/** Every lock of a project that can be read: one per run, plus an older version's `lock.json`. Oldest first. */
+export function listRunLocks(root) {
+    const out = [];
+    for (const f of lockFiles(root)) {
+        const r = readLockFile(f);
+        if (r.kind === "ok")
+            out.push(r.info);
     }
-    return true;
+    return out.sort((a, b) => a.acquired_at.localeCompare(b.acquired_at) || a.run_id.localeCompare(b.run_id));
+}
+/** Run ids whose per-run lock file exists but cannot be read (it can only be removed with `forceUnlock(root, runId)`). */
+export function listUnreadableRunLocks(root) {
+    return lockFiles(root)
+        .filter((f) => path.dirname(f) !== root && readLockFile(f).kind === "unreadable")
+        .map((f) => path.basename(f, ".json"));
+}
+/** The lock a run holds (per-run file, or an older version's `lock.json` written for that run), if readable. */
+export function inspectRunLock(root, runId) {
+    const own = readLockFile(runLockFile(root, runId));
+    if (own.kind === "ok")
+        return own.info;
+    const old = readLockFile(legacyFile(root));
+    return old.kind === "ok" && old.info.run_id === runId ? old.info : undefined;
 }
 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.`);
+    return new Error(`Run ${info.run_id} is still running (pid ${info.pid}, heartbeat ${Number.isFinite(late) ? late : "?"}s ago). ` +
+        `A run cannot be started or resumed twice; 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 clear --lock --force\`.`);
+function limitError(active, max) {
+    const list = active.map((l) => `${l.run_id} (pid ${l.pid})`).join(", ");
+    return new Error(`This project already has ${active.length} run(s) active: ${list}. At most ${max} may run at once (dispatcher.max_concurrent_runs: ${max}); ` +
+        `wait for one to end, stop one, or raise max_concurrent_runs in project.yaml.`);
+}
+function exclusiveError(holder) {
+    return new Error(`${holder.run_id} (pid ${holder.pid}) needs the project to itself (a memory tidy or restore); wait for it to finish, then try again.`);
+}
+function needsIdleError(active) {
+    return new Error(`This needs the project to itself, but ${active.map((l) => `${l.run_id} (pid ${l.pid})`).join(", ")} ${active.length === 1 ? "is" : "are"} active. Wait for ${active.length === 1 ? "it" : "them"} to end, or stop ${active.length === 1 ? "it" : "them"}.`);
+}
+function unreadableError(file) {
+    const perRun = path.basename(path.dirname(file)) === LOCKS_DIR;
+    const cmd = perRun ? `agent-lyceum clear --lock ${path.basename(file, ".json")} --force` : "agent-lyceum clear --lock --force";
+    return new Error(`The run lock ${file} cannot be read or has no known owner. Check that no run is active, then run \`${cmd}\`.`);
+}
+function sleepSync(ms) {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+/**
+ * Counting the active runs and creating our lock must happen as one step, or two starts could both pass the count.
+ * A short-lived mutex file serialises them; a holder that died leaves it behind for at most 10 s.
+ */
+function withAdmission(root, fn) {
+    const mutex = path.join(root, LOCKS_DIR, ADMIT_FILE);
+    const deadline = Date.now() + 5000;
+    for (;;) {
+        let fd;
+        try {
+            fd = fs.openSync(mutex, "wx");
+        }
+        catch (e) {
+            if (e.code !== "EEXIST")
+                throw e;
+        }
+        if (fd !== undefined) {
+            try {
+                return fn();
+            }
+            finally {
+                fs.closeSync(fd);
+                fs.rmSync(mutex, { force: true });
+            }
+        }
+        try {
+            if (Date.now() - fs.statSync(mutex).mtimeMs > 10_000)
+                fs.rmSync(mutex, { force: true });
+        }
+        catch {
+            /* released meanwhile */
+        }
+        if (Date.now() > deadline)
+            throw new Error(`Could not take the project's admission lock ${mutex}; another process holds it. Try again.`);
+        sleepSync(20);
+    }
 }
 /** 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`);
+function tryCreate(file, info) {
+    const tmp = path.join(path.dirname(file), `.${path.basename(file)}.${info.token}.tmp`);
     fs.writeFileSync(tmp, JSON.stringify(info, null, 2));
     try {
-        fs.linkSync(tmp, path.join(root, LOCK_FILE));
+        fs.linkSync(tmp, file);
         return true;
     }
     catch (e) {
@@ -114,37 +210,11 @@ function tryCreate(root, info) {
         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 });
+    assertRunId(runId);
+    fs.mkdirSync(path.join(root, LOCKS_DIR), { recursive: true });
+    const file = runLockFile(root, runId);
+    const max = opts.maxConcurrent ?? 1;
     const now = new Date().toISOString();
     const info = {
         token: crypto.randomBytes(16).toString("hex"),
@@ -154,27 +224,42 @@ export function acquireProjectLock(root, runId, opts = {}) {
         run_id: runId,
         acquired_at: now,
         heartbeat_at: now,
+        ...(opts.exclusive ? { exclusive: true } : {}),
     };
-    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.`);
-    }
+    withAdmission(root, () => {
+        // 1. This run's own lock: a live holder means it is already running; a dead one is replaced.
+        const own = readLockFile(file);
+        if (own.kind === "unreadable")
+            throw unreadableError(file);
+        if (own.kind === "ok") {
+            if (lockHolderAlive(own.info))
+                throw heldError(own.info);
+            fs.rmSync(file, { force: true });
+        }
+        // 2. An older version's project-wide lock counts as one active run; a dead one is cleared.
+        const old = readLockFile(legacyFile(root));
+        if (old.kind === "unreadable")
+            throw unreadableError(legacyFile(root));
+        if (old.kind === "ok" && old.info.run_id === runId && lockHolderAlive(old.info))
+            throw heldError(old.info);
+        if (old.kind === "ok" && !lockHolderAlive(old.info))
+            fs.rmSync(legacyFile(root), { force: true });
+        // 3. The other runs that are active now.
+        const active = listRunLocks(root).filter((l) => l.run_id !== runId && lockHolderAlive(l));
+        const exclusiveHolder = active.find((l) => l.exclusive);
+        if (exclusiveHolder)
+            throw exclusiveError(exclusiveHolder);
+        if (opts.exclusive && active.length)
+            throw needsIdleError(active);
+        if (active.length >= max)
+            throw limitError(active, max);
+        if (!tryCreate(file, info))
+            throw new Error(`Could not take the run lock ${file}; another process just took it. Try again.`);
+    });
     let released = false;
     let lost = false;
-    const file = path.join(root, LOCK_FILE);
     const mine = () => {
-        const r = readLock(root);
+        const r = readLockFile(file);
         return r.kind === "ok" && r.info.token === info.token;
     };
     const timer = setInterval(() => {
@@ -212,10 +297,23 @@ export function acquireProjectLock(root, runId, opts = {}) {
         release,
     };
 }
-/** Remove the lock regardless of owner (the `clear --lock --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 });
+/**
+ * Remove a lock regardless of owner (the `clear --lock --force` escape hatch). With a run id: that run's lock (and an
+ * older version's `lock.json` when it was written for that run). Without: only the older project-wide `lock.json`.
+ * Returns what was there, if readable.
+ */
+export function forceUnlock(root, runId) {
+    if (runId === undefined) {
+        const old = readLockFile(legacyFile(root));
+        fs.rmSync(legacyFile(root), { force: true });
+        fs.rmSync(`${legacyFile(root)}.reclaim`, { force: true });
+        return old.kind === "ok" ? old.info : undefined;
+    }
+    assertRunId(runId);
+    const info = inspectRunLock(root, runId);
+    fs.rmSync(runLockFile(root, runId), { force: true });
+    const old = readLockFile(legacyFile(root));
+    if (old.kind === "ok" && old.info.run_id === runId)
+        fs.rmSync(legacyFile(root), { force: true });
     return info;
 }

package/dist/prompt.js

@@ -23,6 +23,8 @@ function readCapped(file, limit) {
 const PR_ATTRIBUTION_RULE = "- If you open a pull request, end its description with a line saying it was opened by agent-lyceum (e.g. `🤖 Opened by agent-lyceum`). Do not name any agent or role in it.";
 /** A tool call that never returns (a server or daemon started in the foreground) burns the whole wake-up timeout and the finished work is thrown away with it. */
 const NO_DAEMONS_RULE = "- Never start a server, daemon or watcher (pm2, `serve`, `dev`, `--watch`) in the foreground of a command, and never leave one running. Run it in the background, bound every such command with `timeout 60`, stop what you started before you finish, and if it cannot start (e.g. a sandbox denies binding a port) report that as unverified instead of retrying.";
+/** Only the lead (or a solo agent, the lead of a team of one) can send `done`, so only it can ask for a pull request. */
+const OPEN_PR_RULE = "Add the frontmatter line `open_pr: true` to `done` only when the user's task explicitly asks for a pull request; otherwise leave it out. It only has an effect when the run ends `completed` with changes on its own branch, and agent-lyceum (not you) then pushes the branch and opens the pull request. Keep agent and role names out of the report, because it becomes the pull request description.";
 export function readPersona(agent) {
     return fs.readFileSync(agent.agentMd, "utf8").trim();
 }
@@ -34,7 +36,7 @@ export function buildSoloSystemPrompt(project, agent) {
         ? "Do the task you are given. Your final reply text is printed to the user as your answer, so end with the answer or a short report of what you did; nothing else is delivered."
         : "");
     if (!isCall) {
-        lines.push("## Finishing", `When the job is finished, create a Markdown file (any name ending in \`.md\`) directly inside \`${outboxDir(project, agent.name)}\` with this exact shape:`, "", "```", "---", "type: done", "subject: <short subject>", "outcome: completed|partial|blocked|failed", "---", "", "## Result", "## Files", "## Verification", "## Not done", "```", "", "That ends the run. `## Result` is the actual deliverable or conclusion (not just \"done\"), `## Files` the paths you created or changed, `## Verification` what you ran or checked and what it showed, `## Not done` anything skipped or unverified (or `None`). Only `completed` means success and it needs all four headings; if work remains or is blocked say `partial`/`blocked`/`failed` (those need only `## Result` and `## Not done`). A summary in your reply text is never delivered: without a `done` mail the run ends as idle with no report.");
+        lines.push("## Finishing", `When the job is finished, create a Markdown file (any name ending in \`.md\`) directly inside \`${outboxDir(project, agent.name)}\` with this exact shape:`, "", "```", "---", "type: done", "subject: <short subject>", "outcome: completed|partial|blocked|failed", "---", "", "## Result", "## Files", "## Verification", "## Not done", "```", "", "That ends the run. `## Result` is the actual deliverable or conclusion (not just \"done\"), `## Files` the paths you created or changed, `## Verification` what you ran or checked and what it showed, `## Not done` anything skipped or unverified (or `None`). Only `completed` means success and it needs all four headings; if work remains or is blocked say `partial`/`blocked`/`failed` (those need only `## Result` and `## Not done`). A summary in your reply text is never delivered: without a `done` mail the run ends as idle with no report. " + OPEN_PR_RULE);
     }
     lines.push("", "## Memory");
     const mems = memoryDirs(agent);
@@ -81,7 +83,7 @@ export function buildSystemPrompt(project, agent) {
         : `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`: 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. " + OPEN_PR_RULE
         : "- `done` has no required headings.", ...(agent.canAskUser
         ? [
             "",

package/dist/run-cleanup.js

@@ -4,7 +4,7 @@ import { atomicWrite } from "./fs-util.js";
 import { assertName } from "./paths.js";
 import { loadRunState } from "./run-store.js";
 import { runIsAlive } from "./status.js";
-import { deleteSnapshotRefs, inspectWorkspace, listSnapshotRefs, listWorkspaceAgents, removeAgentWorkspace } from "./worktree.js";
+import { deleteSnapshotRefs, existingAgentWorkspace, inspectWorkspace, listSnapshotRefs, listWorkspaceAgents, removeAgentWorkspace } from "./worktree.js";
 import { must } from "./assert.js";
 const journalDir = (p) => path.join(p.paths.root, "cleanup");
 const journalFile = (p, runId) => path.join(journalDir(p), `${runId}.json`);
@@ -36,8 +36,10 @@ export function planRunCleanup(project, runId, opts = {}) {
         if (!state.end_reason && runIsAlive(state, project))
             plan.refusals.push(`Run ${runId} is still running (pid ${state.pid}); stop it first.`);
     }
+    // A concurrent run has a worktree for the lead: members' work lands there, and the lead's branch is what you merge.
+    const leadWs = existingAgentWorkspace(project, runId, project.lead);
     for (const agent of listWorkspaceAgents(project, runId)) {
-        const w = inspectWorkspace(project, runId, agent);
+        const w = inspectWorkspace(project, runId, agent, agent === project.lead ? undefined : leadWs);
         if (!w)
             continue;
         const files = [...new Set([...w.dirty, ...w.unintegrated])];
@@ -45,7 +47,8 @@ export function planRunCleanup(project, runId, opts = {}) {
         if (keepWorktrees || holdsWork) {
             plan.keep.push({ agent, branch: w.branch, path: w.root, files: files.length ? files : w.unknown ? [`(${w.unknown})`] : [] });
             if (holdsWork && !keepWorktrees) {
-                plan.refusals.push(`${agent} has work that is not in the repo: ${files.length ? files.join(", ") : w.unknown} (branch ${w.branch}, worktree ${w.root}). ` +
+                const merge = agent === project.lead && leadWs ? ` Merge it first with \`git merge ${w.branch}\`.` : "";
+                plan.refusals.push(`${agent} has work that is not in the repo: ${files.length ? files.join(", ") : w.unknown} (branch ${w.branch}, worktree ${w.root}).${merge} ` +
                     `Bring it in or discard it by hand, or use --keep-worktrees to keep the worktree and branch and clear the rest.`);
             }
             continue;

package/dist/run-session.d.ts

@@ -1,8 +1,10 @@
 import { type Invoker } from "./adapters/index.js";
 import type { ResolvedProject } from "./config.js";
 import type { RunOutcome } from "./schema.js";
+import { type ResultBranch } from "./worktree.js";
 import { newRunId, type EndReason, type RunState } from "./run-store.js";
 import { type PreparedTask } from "./task.js";
+import { type CommandRunner, type PrOutcome } from "./open-pr.js";
 export { newRunId };
 export type { ActiveWake, EndReason, RunState, SentTopic, WakeRecord, WakeTopic } from "./run-store.js";
 export declare const RESULT_FILE = "result.md";
@@ -25,6 +27,10 @@ export interface RunSummary {
     };
     /** Set when the run waits for the user: the file with the questions. */
     askReplyPath?: string;
+    /** Concurrent runs: the branch holding the lead's work. */
+    resultBranch?: ResultBranch;
+    /** The lead asked for a pull request: what became of it. */
+    pr?: PrOutcome;
 }
 export interface RunOptions {
     project: ResolvedProject;
@@ -36,6 +42,8 @@ export interface RunOptions {
     resume?: RunState;
     runDir: string;
     invoker?: Invoker;
+    /** Runs git and gh for the pull request. Tests pass a fake; the default is the real thing. */
+    pr?: CommandRunner;
     /** Stop the run when this fires: running agents are killed, unread mail is kept, the run ends `cancelled` and can be resumed. */
     signal?: AbortSignal;
     log?: (line: string) => void;
@@ -61,11 +69,18 @@ export declare class RunSession {
     private doneOutcome;
     private doneNote;
     private doneVerification;
+    /** The accepted `done` carried `open_pr: true` (only the lead can send `done`). */
+    private openPrRequested;
+    private readonly prRunner;
     /** Inbox mail each agent in the current batch is working on; it is marked read only after its output is routed. */
     private readonly claims;
     private readonly noSessionNoted;
     /** Git worktrees of the non-lead agents in the batch being woken (empty in shared mode and for the lead). */
     private batchSpaces;
+    /** Members whose worktree was refused (its git files were tampered with): never woken again in this run. */
+    private readonly refused;
+    /** Concurrent runs: the lead's own git worktree for the whole run. */
+    private readonly leadSpace;
     /** The attempt that produced each batch member's output; committed together with its claim. */
     private readonly attempts;
     constructor(opts: RunOptions);
@@ -82,12 +97,24 @@ export declare class RunSession {
      * sees them. When that cannot be done, nothing is applied, the member's work stays on its branch, and the lead is told.
      */
     private integrateMember;
+    /** A member whose worktree was refused: it is not woken again in this run, and the lead is told so it can react. */
+    private refuseMember;
     /** After a batch (or, on resume, before the first one): revert guarded edits, route mail, detect done / lead failure. */
     private settle;
     /** The user answered: send each asker its answers as a `reply`, then mark them delivered. Safe to repeat after a crash. */
     private deliverAnswers;
     /** Store the questions of this pass's valid `ask` mails; malformed ones go back to their sender. Returns true when the run should now wait. */
     private handleAsks;
+    /**
+     * Concurrent runs, at the end of the run: the lead's work is committed on its branch for you to merge.
+     * A run that waits for your answers has not ended (it will be resumed in the same worktree), so it commits nothing.
+     */
+    private finishLead;
+    /**
+     * The lead asked for a pull request in `done`. It is opened from the lead's branch, by the dispatcher, outside any agent sandbox.
+     * A request that cannot be honoured is reported and noted; it never changes how the run turned out.
+     */
+    private maybeOpenPr;
     /** On resume: sort out what the interrupted process left behind before anything is woken. */
     private recover;
     run(): Promise<RunSummary>;