agent-lyceum 0.11.2 → 0.12.0

package/dist/worktree.js

@@ -4,8 +4,10 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { atomicWrite } from "./fs-util.js";
-/** Agents share the repo, or each non-lead agent gets its own git worktree. `auto` picks worktrees as soon as agents can run in parallel. */
+/** Agents share the repo, or each non-lead agent gets its own git worktree. `auto` picks worktrees as soon as agents can run in parallel; several concurrent runs always do. */
 export function resolveWorkspaceMode(d) {
+    if ((d.max_concurrent_runs ?? 1) > 1)
+        return "worktree";
     if (d.workspace_mode === "worktree")
         return "worktree";
     if (d.workspace_mode === "shared")
@@ -18,15 +20,19 @@ const IDENTITY = {
     GIT_COMMITTER_NAME: "agent-lyceum",
     GIT_COMMITTER_EMAIL: "agent-lyceum@localhost",
 };
-export function git(cwd, args, env = {}) {
+function runGit(cwd, args, env = {}, input) {
     return execFileSync("git", args, {
         cwd,
         encoding: "utf8",
         maxBuffer: 256 * 1024 * 1024,
-        stdio: ["ignore", "pipe", "pipe"],
+        stdio: [input === undefined ? "ignore" : "pipe", "pipe", "pipe"],
+        input,
         env: { ...process.env, ...env },
     }).replace(/\n$/, "");
 }
+export function git(cwd, args, env = {}) {
+    return runGit(cwd, args, env);
+}
 function tryGit(cwd, args, env) {
     try {
         return git(cwd, args, env);
@@ -35,13 +41,173 @@ function tryGit(cwd, args, env) {
         return undefined;
     }
 }
-export function isGitRepo(dir) {
-    return tryGit(dir, ["rev-parse", "--is-inside-work-tree"]) === "true";
+// ---- git in an agent's worktree ----
+/**
+ * What the dispatcher never lets git take from a place an agent can write. Each one was seen running a planted program:
+ * fsmonitor and hooks (post-commit runs despite --no-verify); a nested repository in the worktree, which `status` and `add`
+ * otherwise visit with git reading that repository's own config (its fsmonitor and filters); `submodule.recurse` / `diff.submodule`
+ * would do the same for reset and diff; signing runs gpg.program.
+ */
+const PINNED_CONFIG = [
+    "-c", "core.fsmonitor=false",
+    "-c", "core.hooksPath=/dev/null",
+    "-c", "diff.ignoreSubmodules=dirty",
+    "-c", "submodule.recurse=false",
+    "-c", "diff.submodule=short",
+    "-c", "commit.gpgsign=false",
+];
+/** Added to every diff/show/log: no external diff program, no textconv program. */
+const DIFF_PINS = ["--no-ext-diff", "--no-textconv"];
+const DIFF_COMMANDS = new Set(["diff", "show", "log"]);
+const fingerprint = (file) => {
+    let st;
+    try {
+        st = fs.lstatSync(file);
+    }
+    catch {
+        return undefined;
+    }
+    if (!st.isFile())
+        return `not a regular file (${st.isSymbolicLink() ? "symlink" : "other"})`;
+    return crypto.createHash("sha256").update(fs.readFileSync(file)).digest("hex");
+};
+const samePath = (a, b) => {
+    try {
+        return fs.realpathSync(a) === fs.realpathSync(b);
+    }
+    catch {
+        return false;
+    }
+};
+/**
+ * Refuse a worktree whose git files were rewritten in a way pinning cannot neutralise:
+ * - `commondir`: git's ref store follows it even with GIT_COMMON_DIR set, so refs would be read from and written to the agent's dir;
+ * - `config.worktree` (read when the user enabled extensions.worktreeConfig): it can name filters, chosen by the worktree's own
+ *   .gitattributes, and a signing program — more than any `-c` list can switch off;
+ * - files git writes by following links (COMMIT_EDITMSG, logs/HEAD): a symlink or hard link would make git write outside the sandbox;
+ * - `HEAD` not the worktree's own branch: the ref store is shared, so a HEAD naming another branch (say `main`) or a detached
+ *   commit would make the dispatcher commit onto, or measure against, a ref the agent chose. git writes exactly
+ *   `ref: refs/heads/<branch>\n` and keeps it so through the dispatcher's commits and `reset --hard`;
+ * - the worktree or its git dir replaced by a symlink.
+ */
+export function assertWorkspaceIntact(ws) {
+    const problems = [];
+    const realDir = (p) => {
+        try {
+            return fs.lstatSync(p).isDirectory();
+        }
+        catch {
+            return false;
+        }
+    };
+    if (!realDir(ws.root))
+        problems.push(`${ws.root} is not a plain directory`);
+    if (!realDir(ws.gitDir))
+        problems.push(`its git dir ${ws.gitDir} is not a plain directory`);
+    else {
+        let commondir;
+        try {
+            commondir = fs.readFileSync(path.join(ws.gitDir, "commondir"), "utf8").trim();
+        }
+        catch {
+            commondir = undefined;
+        }
+        if (commondir === undefined || !samePath(path.resolve(ws.gitDir, commondir), ws.commonDir))
+            problems.push(`${path.join(ws.gitDir, "commondir")} no longer points at ${ws.commonDir}`);
+        if (fingerprint(path.join(ws.gitDir, "config.worktree")) !== ws.worktreeConfig)
+            problems.push(`${path.join(ws.gitDir, "config.worktree")} changed since the worktree was made`);
+        for (const name of ["logs", "logs/HEAD", "COMMIT_EDITMSG"]) {
+            let st;
+            try {
+                st = fs.lstatSync(path.join(ws.gitDir, name));
+            }
+            catch {
+                continue;
+            }
+            const ok = name === "logs" ? st.isDirectory() : st.isFile() && st.nlink === 1;
+            if (!ok)
+                problems.push(`${path.join(ws.gitDir, name)} is a link or not what git made`);
+        }
+        const head = path.join(ws.gitDir, "HEAD");
+        let headOk = false;
+        try {
+            const st = fs.lstatSync(head);
+            headOk = st.isFile() && st.nlink === 1 && fs.readFileSync(head, "utf8") === `ref: refs/heads/${ws.branch}\n`;
+        }
+        catch {
+            headOk = false;
+        }
+        if (!headOk)
+            problems.push(`${head} is not a plain file naming its own branch ${ws.branch}`);
+    }
+    if (problems.length) {
+        throw new Error(`Refusing to run git in the worktree ${ws.root}: ${problems.join("; ")}. Its git files were changed after it was made (an agent can write them); nothing in it was touched. ` +
+            `The work in it is still there and nothing was deleted. \`agent-lyceum clear\` will refuse this worktree too, because it counts as holding work: inspect it, and once you are sure it is safe, remove it by hand with \`git worktree remove --force <path>\`.`);
+    }
 }
-const toplevel = (dir) => git(dir, ["rev-parse", "--show-toplevel"]);
-/** Files in the repo with changes nobody committed (modified, staged or new and not ignored). Paths are relative to the repo root. */
-export function dirtyPaths(dir) {
-    const out = execFileSync("git", ["status", "--porcelain", "-z", "--untracked-files=all"], { cwd: dir, encoding: "utf8", maxBuffer: 256 * 1024 * 1024 });
+function pinnedArgs(args) {
+    const i = args.findIndex((a) => !a.startsWith("-"));
+    const withDiffPins = i >= 0 && DIFF_COMMANDS.has(args[i] ?? "") ? [...args.slice(0, i + 1), ...DIFF_PINS, ...args.slice(i + 1)] : args;
+    return [...PINNED_CONFIG, ...withDiffPins];
+}
+function pinnedEnv(ws, env) {
+    return { ...env, GIT_DIR: ws.gitDir, GIT_COMMON_DIR: ws.commonDir, GIT_WORK_TREE: ws.root };
+}
+/**
+ * Run git against an agent's worktree without letting git discover anything from it. The agent may rewrite the worktree's `.git`
+ * pointer file and its per-worktree git dir; git is told exactly where the git dir, the common dir and the work tree are
+ * (`ws.gitDir` / `ws.commonDir` come from the workspace meta, recorded before any agent ran in it), and the worktree is checked
+ * for what pinning cannot neutralise first (`assertWorkspaceIntact`).
+ * The cwd is the worktree root: git does not discover from it (GIT_DIR is set), and commands that take paths relative to the cwd
+ * (`git apply`) would otherwise write wherever the cwd is.
+ */
+export function agentGit(ws, args, env = {}, input) {
+    assertWorkspaceIntact(ws);
+    return runGit(ws.root, pinnedArgs(args), pinnedEnv(ws, env), input);
+}
+/** `agentGit`, with a failing git command giving `undefined`. A worktree that fails `assertWorkspaceIntact` still throws. */
+export function tryAgentGit(ws, args, env) {
+    assertWorkspaceIntact(ws);
+    try {
+        return runGit(ws.root, pinnedArgs(args), pinnedEnv(ws, env ?? {}));
+    }
+    catch {
+        return undefined;
+    }
+}
+const zList = (out) => out.split("\0").filter(Boolean);
+/** Paths of the gitlink (mode 160000) entries in `git ls-files -s -z` / `git ls-tree -r -z` output. */
+const gitlinks = (out) => zList(out)
+    .filter((e) => e.startsWith("160000 "))
+    .map((e) => e.slice(e.indexOf("\t") + 1));
+/**
+ * Refuse a worktree that holds a git repository of its own. `status`, `add -A` and `commit` can visit a nested repository and run
+ * git there with that repository's config — which the agent wrote. Run before any command that walks the working tree.
+ * - untracked: `ls-files -o` (it does not enter them, and runs nothing) lists a nested repository as one entry ending in `/`;
+ * - a submodule entry in the (agent-writable) index that the snapshot did not have;
+ * - a submodule path from the snapshot that now holds a repository (`git worktree add` never fills it, and an agent cannot).
+ * A repo that uses submodules keeps working: its submodule entries come from the snapshot and stay empty in a worktree.
+ */
+export function assertNoNestedRepos(ws) {
+    const problems = [];
+    for (const p of zList(agentGit(ws, ["ls-files", "-o", "--exclude-standard", "-z"])).filter((e) => e.endsWith("/"))) {
+        problems.push(`it contains a nested git repository at ${p.slice(0, -1)}; remove it, or add it to .gitignore if it must stay`);
+    }
+    const allowed = new Set(gitlinks(agentGit(ws, ["ls-tree", "-r", "-z", ws.base])));
+    for (const p of gitlinks(agentGit(ws, ["ls-files", "-s", "-z"]))) {
+        if (!allowed.has(p))
+            problems.push(`its index has a submodule entry ${p} that the snapshot it started from does not have`);
+        else if (fs.existsSync(path.join(ws.root, p, ".git")))
+            problems.push(`a git repository was placed at the submodule path ${p}`);
+    }
+    if (problems.length)
+        throw new Error(`Refusing to run git in the worktree ${ws.root}: ${problems.join("; ")}. Nothing in it was touched.`);
+}
+const gitAt = (at, args, env, input) => ("ws" in at ? agentGit(at.ws, args, env, input) : runGit(at.top, args, env, input));
+const tryGitAt = (at, args, env) => ("ws" in at ? tryAgentGit(at.ws, args, env) : tryGit(at.top, args, env));
+const workTreeOf = (at) => ("ws" in at ? at.ws.root : at.top);
+/** Paths in `git status --porcelain -z` output. */
+function parseStatus(out) {
     const parts = out.split("\0").filter(Boolean);
     const paths = [];
     for (let i = 0; i < parts.length; i++) {
@@ -52,13 +218,37 @@ export function dirtyPaths(dir) {
     }
     return paths;
 }
+export function isGitRepo(dir) {
+    return tryGit(dir, ["rev-parse", "--is-inside-work-tree"]) === "true";
+}
+/** The main repository's top-level directory for `dir`. */
+export const toplevel = (dir) => git(dir, ["rev-parse", "--show-toplevel"]);
+/** Files in the repo with changes nobody committed (modified, staged or new and not ignored). Paths are relative to the repo root. */
+export function dirtyPaths(dir) {
+    return parseStatus(execFileSync("git", ["status", "--porcelain", "-z", "--untracked-files=all"], { cwd: dir, encoding: "utf8", maxBuffer: 256 * 1024 * 1024 }));
+}
 /** Refuse to start a worktree run when it cannot be isolated; returns nothing when it is fine. */
 export function assertWorktreeRunnable(project, opts) {
     if (!isGitRepo(project.dir)) {
         throw new Error(`Parallel runs (worktree workspaces) need ${project.dir} to be a git repository. Run sequentially instead: dispatcher.max_parallel: 1.`);
     }
+    // With git's reftable ref storage a linked worktree's HEAD lives in `<gitDir>/reftable/`, a place the agent can write, and the
+    // file `<gitDir>/HEAD` only says `ref: refs/heads/.invalid`: the check that a worktree's HEAD is its own branch cannot hold
+    // there, so every worktree would be refused in the middle of the run. Say so up front instead. (`rev-parse --show-ref-format`
+    // does not exist in older git, which only knows `files`.)
+    if (tryGit(project.dir, ["rev-parse", "--show-ref-format"]) === "reftable") {
+        throw new Error(`${project.dir} uses git's reftable ref storage, whose worktrees agent-lyceum cannot yet verify as isolated, so parallel agents and concurrent runs are not supported there. ` +
+            `Use a repository with the default "files" ref storage, or run one agent at a time without worktrees: dispatcher.max_parallel: 1 and dispatcher.max_concurrent_runs: 1.`);
+    }
     if (!opts.fresh)
         return;
+    if (opts.concurrent) {
+        // A concurrent run starts from HEAD and never touches the working tree, so uncommitted changes are fine.
+        if (tryGit(project.dir, ["rev-parse", "--verify", "-q", "HEAD"]) === undefined) {
+            throw new Error(`Concurrent runs start from HEAD, but ${project.dir} has no commit yet. Make an initial commit, or set dispatcher.max_concurrent_runs: 1.`);
+        }
+        return;
+    }
     const dirty = dirtyPaths(project.dir);
     if (dirty.length) {
         const shown = dirty.slice(0, 5).join(", ") + (dirty.length > 5 ? `, ... (${dirty.length} in all)` : "");
@@ -66,24 +256,35 @@ export function assertWorktreeRunnable(project, opts) {
             `Commit or stash them first (agent-lyceum never touches your own edits), or run sequentially with dispatcher.max_parallel: 1.`);
     }
 }
+/** `refs/agent-lyceum/<run>/base-0` pointing at the repo's HEAD: where a concurrent run starts. Nothing in the repo changes. */
+export function snapshotHead(project, runId) {
+    const top = toplevel(project.dir);
+    const sha = git(top, ["rev-parse", "--verify", "HEAD^{commit}"]);
+    const ref = `refs/agent-lyceum/${runId}/base-0`;
+    git(top, ["update-ref", ref, sha]);
+    return ref;
+}
 /**
  * Commit the repo's current working tree (tracked changes and new, non-ignored files) as an unreferenced-by-branch
  * snapshot `refs/agent-lyceum/<run>/base-<n>`. Uses a throwaway index, so HEAD, branches, the real index and the
  * working tree are not touched. Returns the ref.
+ * `from`: the checkout to snapshot — the lead's worktree in a concurrent run; by default your repo's working tree.
  */
-export function snapshotBase(project, runId, n) {
-    const top = toplevel(project.dir);
+export function snapshotBase(project, runId, n, from) {
+    const at = from ? { ws: from } : { top: toplevel(project.dir) };
     const index = path.join(os.tmpdir(), `agent-lyceum-index-${crypto.randomBytes(6).toString("hex")}`);
     const env = { ...IDENTITY, GIT_INDEX_FILE: index };
     try {
-        const head = tryGit(top, ["rev-parse", "--verify", "HEAD"]);
+        if (from)
+            assertNoNestedRepos(from);
+        const head = tryGitAt(at, ["rev-parse", "--verify", "HEAD"]);
         if (head)
-            git(top, ["read-tree", head], env);
-        git(top, ["add", "-A"], env);
-        const tree = git(top, ["write-tree"], env);
-        const commit = git(top, ["commit-tree", tree, ...(head ? ["-p", head] : []), "-m", `agent-lyceum snapshot ${runId} #${n}`], env);
+            gitAt(at, ["read-tree", head], env);
+        gitAt(at, ["add", "-A"], env);
+        const tree = gitAt(at, ["write-tree"], env);
+        const commit = gitAt(at, ["commit-tree", tree, ...(head ? ["-p", head] : []), "-m", `agent-lyceum snapshot ${runId} #${n}`], env);
         const ref = `refs/agent-lyceum/${runId}/base-${n}`;
-        git(top, ["update-ref", ref, commit]);
+        gitAt(at, ["update-ref", ref, commit]);
         return ref;
     }
     finally {
@@ -91,15 +292,63 @@ export function snapshotBase(project, runId, n) {
     }
 }
 const workspaceRoot = (project, runId, agent) => path.join(project.paths.root, "worktrees", runId, agent);
+/** The user's repo's git common dir, as a real absolute path. Asked of the user's repo, never of a worktree. */
+const commonDirOf = (top) => fs.realpathSync(git(top, ["rev-parse", "--path-format=absolute", "--git-common-dir"]));
+/** The admin dirs under `<commonDir>/worktrees/` whose `gitdir` file names `<root>/.git` (the file may hold a relative path). */
+function adminDirsNaming(commonDir, root, names) {
+    const admin = path.join(commonDir, "worktrees");
+    let entries;
+    try {
+        entries = names ?? fs.readdirSync(admin);
+    }
+    catch {
+        entries = [];
+    }
+    const want = path.join(root, ".git");
+    return entries
+        .map((n) => path.join(admin, n))
+        .filter((d) => {
+        try {
+            return samePath(path.resolve(d, fs.readFileSync(path.join(d, "gitdir"), "utf8").trim()), want);
+        }
+        catch {
+            return false;
+        }
+    });
+}
+function writeMeta(root, meta) {
+    atomicWrite(`${root}.json`, JSON.stringify(meta, null, 2));
+}
+/**
+ * The meta of a worktree made by an older version lacks `gitDir`/`commonDir`: take the common dir from the user's repo and the git
+ * dir from the one admin dir that names this worktree. Anything but exactly one is refused rather than guessed (an agent can
+ * rewrite its own admin dir's `gitdir` to claim another worktree). The result is written back to the meta.
+ */
+function completeLegacyMeta(top, root, meta) {
+    if (meta.gitDir && meta.commonDir)
+        return meta;
+    const commonDir = commonDirOf(top);
+    const found = adminDirsNaming(commonDir, root);
+    if (found.length !== 1) {
+        throw new Error(`Cannot tell which git dir belongs to the worktree ${root}: its metadata predates recording it, and ${found.length} git dirs under ${path.join(commonDir, "worktrees")} name it${found.length ? ` (${found.join(", ")})` : ""}. ` +
+            `Refusing to guess. Inspect it by hand, or remove it with \`git worktree remove\`.`);
+    }
+    const done = { ...meta, gitDir: found[0], commonDir };
+    writeMeta(root, done);
+    return done;
+}
 function describeWorkspace(project, root, agent, meta) {
     const top = toplevel(project.dir);
+    const full = completeLegacyMeta(top, root, meta);
     // `top` is a real path (git resolves symlinks, e.g. /var -> /private/var on macOS), so compare against the real project dir.
     const rel = path.relative(top, fs.realpathSync(project.dir));
     return {
         agent,
         root,
         dir: rel ? path.join(root, rel) : root,
-        gitDir: git(root, ["rev-parse", "--absolute-git-dir"]),
+        gitDir: full.gitDir,
+        commonDir: full.commonDir,
+        ...(full.worktreeConfig ? { worktreeConfig: full.worktreeConfig } : {}),
         branch: meta.branch,
         base: meta.base,
     };
@@ -122,23 +371,43 @@ export function prepareAgentWorkspace(project, runId, agent, baseRef) {
         meta = undefined;
     }
     if (meta && fs.existsSync(root)) {
-        if (meta.base !== newBase) {
-            const untouched = git(root, ["status", "--porcelain", "--untracked-files=all"]) === "" && git(root, ["rev-parse", "HEAD"]) === meta.base;
+        const ws = describeWorkspace(project, root, agent, meta);
+        if (ws.base !== newBase) {
+            assertNoNestedRepos(ws);
+            const untouched = agentGit(ws, ["status", "--porcelain", "--untracked-files=all"]) === "" && agentGit(ws, ["rev-parse", "HEAD"]) === ws.base;
             if (untouched) {
-                git(root, ["reset", "-q", "--hard", newBase]);
-                meta = { ...meta, base: newBase };
-                atomicWrite(metaFile, JSON.stringify(meta, null, 2));
+                agentGit(ws, ["reset", "-q", "--hard", newBase]);
+                writeMeta(root, metaOf({ ...ws, base: newBase }));
+                return { ...ws, base: newBase };
             }
         }
-        return describeWorkspace(project, root, agent, meta);
+        return ws;
     }
     const branch = `agent-lyceum/${runId}/${agent}`;
     fs.mkdirSync(path.dirname(root), { recursive: true });
+    // The new worktree's git dir is the admin dir `worktree add` creates: the one under <commonDir>/worktrees/ that was not there
+    // before and whose `gitdir` names this root. Only the user's repo and what git just wrote are read — no agent has run in it yet,
+    // and another dispatcher adding a worktree at the same moment cannot be mistaken for it.
+    const commonDir = commonDirOf(top);
+    const adminDir = path.join(commonDir, "worktrees");
+    const before = new Set(fs.existsSync(adminDir) ? fs.readdirSync(adminDir) : []);
     git(top, ["worktree", "add", "-q", "-B", branch, root, newBase]);
-    meta = { branch, base: newBase };
-    atomicWrite(metaFile, JSON.stringify(meta, null, 2));
+    const created = adminDirsNaming(commonDir, root, fs.readdirSync(adminDir).filter((n) => !before.has(n)));
+    if (created.length !== 1)
+        throw new Error(`git worktree add made ${root}, but ${created.length} new git dirs under ${adminDir} name it; refusing to guess which is its own.`);
+    const gitDir = created[0];
+    const worktreeConfig = fingerprint(path.join(gitDir, "config.worktree"));
+    meta = { branch, base: newBase, gitDir, commonDir, ...(worktreeConfig ? { worktreeConfig } : {}) };
+    writeMeta(root, meta);
     return describeWorkspace(project, root, agent, meta);
 }
+const metaOf = (ws) => ({
+    branch: ws.branch,
+    base: ws.base,
+    gitDir: ws.gitDir,
+    commonDir: ws.commonDir,
+    ...(ws.worktreeConfig ? { worktreeConfig: ws.worktreeConfig } : {}),
+});
 /** Remove an agent's worktree, its branch and its metadata. The caller decides whether the work in it may be discarded. */
 export function removeAgentWorkspace(project, runId, agent) {
     const top = toplevel(project.dir);
@@ -192,21 +461,27 @@ export function globMatch(glob, file) {
     return new RegExp(`^${re}$`).test(file);
 }
 const PROTECTED_NAMES = ["CLAUDE.md", "AGENTS.md"];
+/** Commit whatever is in an agent's worktree (no hooks, no signing, dispatcher identity). Returns the HEAD afterwards and whether a commit was made. */
+export function commitWorkspace(ws, message) {
+    assertNoNestedRepos(ws);
+    agentGit(ws, ["add", "-A"]);
+    let committed = false;
+    if (tryAgentGit(ws, ["diff", "--cached", "--quiet"]) === undefined) {
+        // agentGit already switches hooks and signing off; --no-verify says so here too
+        agentGit(ws, ["commit", "-q", "--no-verify", "-m", message], IDENTITY);
+        committed = true;
+    }
+    return { head: agentGit(ws, ["rev-parse", "HEAD"]), committed };
+}
 /**
  * Commit whatever the agent left in its worktree and list what changed since its snapshot, checking every
  * changed path (modified, added, deleted, or either end of a rename) against the agent's `owns`, the project
  * folder, the protected instruction files, and symlink/submodule rules. Nothing is applied here.
  */
 export function collectAgentChanges(workspace, owns) {
-    const { root } = workspace;
-    git(root, ["add", "-A"]);
-    if (tryGit(root, ["diff", "--cached", "--quiet"]) === undefined) {
-        // hooks belong to the user's repo (a worktree shares them): do not run them for the dispatcher's own commit
-        git(root, ["-c", "commit.gpgsign=false", "commit", "-q", "--no-verify", "-m", `agent-lyceum: changes by ${workspace.agent}`], IDENTITY);
-    }
-    const head = git(root, ["rev-parse", "HEAD"]);
+    const { head } = commitWorkspace(workspace, `agent-lyceum: changes by ${workspace.agent}`);
     const base = workspace.base;
-    const raw = base === head ? "" : execFileSync("git", ["diff", "--raw", "-z", "--no-renames", "--no-abbrev", base, head], { cwd: root, encoding: "utf8", maxBuffer: 256 * 1024 * 1024 });
+    const raw = base === head ? "" : agentGit(workspace, ["diff", "--raw", "-z", "--no-renames", "--no-abbrev", base, head]);
     const parts = raw.split("\0").filter(Boolean);
     const files = [];
     for (let i = 0; i + 1 < parts.length; i += 2) {
@@ -232,7 +507,7 @@ export function collectAgentChanges(workspace, owns) {
         if (f.mode === "160000")
             violations.push(`${f.path}: submodule changes are not integrated`);
         if (f.mode === "120000" && f.status !== "D") {
-            const target = git(root, ["show", `${head}:${f.path}`]);
+            const target = agentGit(workspace, ["show", `${head}:${f.path}`]);
             const resolved = path.posix.normalize(path.posix.join(path.posix.dirname(p), target));
             if (path.posix.isAbsolute(target))
                 violations.push(`${f.path}: symlink to an absolute path (${target})`);
@@ -244,12 +519,12 @@ export function collectAgentChanges(workspace, owns) {
     }
     return { workspace, base, head, files, violations };
 }
-function blobAt(top, commit, file) {
-    return tryGit(top, ["rev-parse", "--verify", "-q", `${commit}:${file}`]) ?? "absent";
+function blobAt(at, commit, file) {
+    return tryGitAt(at, ["rev-parse", "--verify", "-q", `${commit}:${file}`]) ?? "absent";
 }
-/** Git's blob id of what is in the main working tree at `file`, or "absent". */
-function workingBlob(top, file) {
-    const abs = path.join(top, file);
+/** Git's blob id of what is in the working tree at `file`, or "absent". */
+function workingBlob(at, file) {
+    const abs = path.join(workTreeOf(at), file);
     let st;
     try {
         st = fs.lstatSync(abs);
@@ -260,7 +535,7 @@ function workingBlob(top, file) {
     if (st.isDirectory())
         return "directory";
     const input = st.isSymbolicLink() ? fs.readlinkSync(abs) : fs.readFileSync(abs);
-    return execFileSync("git", ["hash-object", "--stdin"], { cwd: top, input, encoding: "utf8" }).trim();
+    return gitAt(at, ["hash-object", "--stdin"], {}, input).trim();
 }
 function writeBlockedReport(project, changes, reason, patch) {
     const dir = path.join(project.run?.dir ?? project.paths.root, "integration");
@@ -284,20 +559,27 @@ function writeBlockedReport(project, changes, reason, patch) {
     ].join("\n"));
     return { report: `${base}.md`, patch: `${base}.patch` };
 }
+/** A member's changes that could not even be collected (e.g. its worktree was refused): reported like any blocked integration, with nothing applied. */
+export function refusedIntegration(project, workspace, reason) {
+    const changes = { workspace, base: workspace.base, head: workspace.base, files: [], violations: [] };
+    return { status: "blocked", reason, branch: workspace.branch, workspace: workspace.root, ...writeBlockedReport(project, changes, reason, "") };
+}
 function advanceBase(workspace, newBase) {
-    const metaFile = `${workspace.root}.json`;
-    atomicWrite(metaFile, JSON.stringify({ branch: workspace.branch, base: newBase }, null, 2));
+    writeMeta(workspace.root, metaOf({ ...workspace, base: newBase }));
 }
 /**
  * Bring an agent's collected changes into the main working tree (not the index, not HEAD), all or nothing.
  * Blocked, with nothing applied and the agent's work kept, when the changes break the rules, when a file
  * changed in the repo since the agent's snapshot, or when git cannot apply the patch. Repeating a call whose
  * changes are already in place is harmless.
+ * `target`: the checkout to bring the changes into — the lead's worktree in a concurrent run; by default your repo's working tree.
  */
-export function integrateAgentChanges(project, changes) {
-    const top = toplevel(project.dir);
+export function integrateAgentChanges(project, changes, target) {
+    const at = target ? { ws: target } : { top: toplevel(project.dir) };
+    if (target)
+        assertNoNestedRepos(target); // `apply` does not walk the tree, but a tampered lead worktree is not written to either
     const { workspace, base, head } = changes;
-    const fullPatch = (paths) => paths.length === 0 ? "" : git(top, ["--literal-pathspecs", "diff", "--binary", "--full-index", base, head, "--", ...paths]) + "\n";
+    const fullPatch = (paths) => paths.length === 0 ? "" : gitAt(at, ["--literal-pathspecs", "diff", "--binary", "--full-index", base, head, "--", ...paths]) + "\n";
     const block = (reason, paths = changes.files.map((f) => f.path)) => ({
         status: "blocked",
         reason,
@@ -312,10 +594,10 @@ export function integrateAgentChanges(project, changes) {
     const pending = [];
     const conflicts = [];
     for (const f of changes.files) {
-        const work = workingBlob(top, f.path);
-        if (work === blobAt(top, head, f.path))
+        const work = workingBlob(at, f.path);
+        if (work === blobAt(at, head, f.path))
             continue; // already in place
-        if (work === blobAt(top, base, f.path))
+        if (work === blobAt(at, base, f.path))
             pending.push(f);
         else
             conflicts.push(f.path);
@@ -326,7 +608,7 @@ export function integrateAgentChanges(project, changes) {
     if (pending.length) {
         const patch = fullPatch(pending.map((f) => f.path));
         try {
-            execFileSync("git", ["apply", "--binary", "--whitespace=nowarn", "-"], { cwd: top, input: patch, encoding: "utf8", stdio: ["pipe", "pipe", "pipe"] });
+            gitAt(at, ["apply", "--binary", "--whitespace=nowarn", "-"], {}, patch);
         }
         catch (e) {
             const err = e;
@@ -336,37 +618,57 @@ export function integrateAgentChanges(project, changes) {
     advanceBase(workspace, head);
     return { status: "integrated", files: changes.files, applied: pending.length };
 }
-/** An agent's existing worktree for this run, if it has one. */
+/**
+ * An agent's existing worktree for this run, if it has one (no worktree or no metadata: undefined).
+ * Throws when the metadata predates recording the git dir and the git dir cannot be told for certain.
+ */
 export function existingAgentWorkspace(project, runId, agent) {
     const root = workspaceRoot(project, runId, agent);
+    let meta;
     try {
-        const meta = JSON.parse(fs.readFileSync(`${root}.json`, "utf8"));
-        return fs.existsSync(root) ? describeWorkspace(project, root, agent, meta) : undefined;
+        meta = JSON.parse(fs.readFileSync(`${root}.json`, "utf8"));
     }
     catch {
         return undefined;
     }
+    return fs.existsSync(root) ? describeWorkspace(project, root, agent, meta) : undefined;
 }
 /** What is in an agent's worktree that exists nowhere else: uncommitted changes, and commits whose files are not in the main repo. */
-export function inspectWorkspace(project, runId, agent) {
+export function inspectWorkspace(project, runId, agent, target) {
     const root = workspaceRoot(project, runId, agent);
     if (!fs.existsSync(root))
         return undefined;
-    const ws = existingAgentWorkspace(project, runId, agent);
-    const branch = ws?.branch ?? `agent-lyceum/${runId}/${agent}`;
+    let ws;
+    let wsError;
+    try {
+        ws = existingAgentWorkspace(project, runId, agent);
+    }
+    catch (e) {
+        wsError = e.message.split("\n")[0];
+    }
+    let branch = `agent-lyceum/${runId}/${agent}`;
+    try {
+        branch = ws?.branch ?? JSON.parse(fs.readFileSync(`${root}.json`, "utf8")).branch ?? branch;
+    }
+    catch {
+        /* no metadata */
+    }
     const work = { agent, root, branch, dirty: [], unintegrated: [] };
+    if (wsError)
+        return { ...work, unknown: `its git dir cannot be determined (${wsError})` };
     if (!ws)
         return { ...work, unknown: "its metadata is missing, so what it holds cannot be compared with the repo" };
     try {
-        work.dirty = dirtyPaths(root);
-        const top = toplevel(project.dir);
-        const head = git(root, ["rev-parse", "HEAD"]);
-        if (head !== ws.base && tryGit(top, ["merge-base", "--is-ancestor", head, "HEAD"]) === undefined) {
-            const raw = execFileSync("git", ["diff", "--raw", "-z", "--no-renames", "--no-abbrev", ws.base, head], { cwd: root, encoding: "utf8", maxBuffer: 256 * 1024 * 1024 });
+        assertNoNestedRepos(ws);
+        work.dirty = parseStatus(agentGit(ws, ["status", "--porcelain", "-z", "--untracked-files=all"]));
+        const at = target ? { ws: target } : { top: toplevel(project.dir) };
+        const head = agentGit(ws, ["rev-parse", "HEAD"]);
+        if (head !== ws.base && tryGitAt(at, ["merge-base", "--is-ancestor", head, "HEAD"]) === undefined) {
+            const raw = agentGit(ws, ["diff", "--raw", "-z", "--no-renames", "--no-abbrev", ws.base, head]);
             const parts = raw.split("\0").filter(Boolean);
             for (let i = 1; i < parts.length; i += 2) {
                 const file = parts[i] ?? "";
-                if (workingBlob(top, file) !== blobAt(top, head, file))
+                if (workingBlob(at, file) !== blobAt(at, head, file))
                     work.unintegrated.push(file);
             }
         }
@@ -376,6 +678,14 @@ export function inspectWorkspace(project, runId, agent) {
     }
     return work;
 }
+/** Commit the lead's checkout on its branch (once, at the end of a run) and write what changed as a patch. Never touches your repo's working tree. */
+export function finishLeadBranch(ws, message, patchFile) {
+    const { head } = commitWorkspace(ws, message);
+    const files = head === ws.base ? [] : agentGit(ws, ["diff", "--name-only", ws.base, head]).split("\n").filter(Boolean);
+    if (files.length)
+        fs.writeFileSync(patchFile, agentGit(ws, ["diff", "--binary", "--full-index", ws.base, head]) + "\n");
+    return { branch: ws.branch, head, base: ws.base, files: files.length, patch: files.length ? patchFile : undefined };
+}
 /** Names of the agents that have a worktree for this run. */
 export function listWorkspaceAgents(project, runId) {
     const dir = path.join(project.paths.root, "worktrees", runId);

package/package.json

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