viewable-one 0.0.0-stage → 0.12.1

package/lib/worktree.mjs

@@ -0,0 +1,1138 @@
+// A spawned session gets its own git worktree, so a bad run cannot touch the
+// checkout the user is looking at.
+//
+// The ruling, 2026-08-26: "Worktree yes!". The gap it closes was found while
+// the first real board-spawned session was still running: the runner passes
+// `cwd: request.cwd || root`, and a board request deliberately carries no cwd
+// (a browser directory handle has a name, not a path), so every spawned
+// session was landing in the MAIN checkout, on whatever branch was checked
+// out - which was `main`. Every session dispatched by hand that night ran in
+// an isolated worktree and got that safety for free; the ones spawned from
+// the canvas, the whole point of the feature, did not. The brief asked them
+// nicely to work on a branch. Nothing enforced it.
+//
+// TWO THINGS THIS MUST NOT BREAK, both learned the hard way:
+//
+// `canvas/` and `inbox/` are GITIGNORED, so a worktree has neither. A session
+// whose board root resolved to its own worktree would write ops files into a
+// folder the app has never heard of - the call succeeds, an op id comes back,
+// and nothing ever reaches the canvas (bridge/README.md, "Sessions in a git
+// worktree"). The child's PM_BOARD_ROOT already points at the real linked
+// folder and MUST keep doing so; that is why this returns a cwd and touches
+// nothing else about the environment.
+//
+// `node_modules` is not in a fresh worktree either, and a session that cannot
+// run `npx vitest` cannot verify what it built. It is symlinked rather than
+// installed: an install per spawn costs minutes and disk for a tree that is
+// usually thrown away.
+
+import { execFile } from "node:child_process";
+import { symlink, mkdir, rm, access, readFile, writeFile, stat, lstat } from "node:fs/promises";
+import { hostname } from "node:os";
+import { canonicalPath, staysInProject } from "./projectPaths.mjs";
+import { basename, isAbsolute, join, resolve, sep } from "node:path";
+// THE PROCESS KILLING LIVES IN procs.mjs since 2026-09-02: it is about
+// processes, not about git, and both of its functions had already learned the
+// same "whose process is this?" lesson the hard way. Re-exported below so no
+// importer and no test changed.
+// GLYTCH lives in procs.mjs and is re-exported here. It is the prefix every
+// board-spawned tree and branch carries, and procs.mjs is where it is
+// MATCHED - the reaper's whole first guard is "is this directory one
+// makeWorktree could have made?". Putting it there rather than importing it
+// from here is what keeps these two modules a straight line instead of a
+// cycle, which is the thing check-portable --strict now looks for.
+import { CHAT_PREFIX, GLYTCH, killProcessesIn } from "./procs.mjs";
+export { CHAT_PREFIX, GLYTCH };
+export { isOursToKill, parseProcessTable, reapOrphanedWorktreeProcesses, reapableWorktreeName } from "./procs.mjs";
+
+/** How `node_modules` is linked into a fresh worktree.
+ *
+ * A DIRECTORY SYMLINK ON WINDOWS NEEDS DEVELOPER MODE OR ADMIN. Without one it
+ * throws EPERM, which the caller catches and logs, and the session then cannot
+ * run the project's own tests - which is most of what a brief asks it to do.
+ * A junction needs no privilege, works for a local absolute directory (which
+ * this always is: it is `<root>/node_modules`), and is what npm itself uses on
+ * Windows. Brief 21, session 3. Exported so the choice can be pinned from a
+ * Mac rather than only observed on Windows. */
+export const nodeModulesLinkType = (platform = process.platform) => (platform === "win32" ? "junction" : "dir");
+
+// Exported (2026-09-11, brief 30 Move 2) so `runner.mjs`'s rows-based
+// admission check can run the same merge-base check
+// this file already does, without a second copy of the `execFile` wrapper.
+export const git = (args, cwd) =>
+  new Promise((resolve) => {
+    execFile("git", args, { cwd, maxBuffer: 8 * 1024 * 1024 }, (error, stdout, stderr) => {
+      resolve({
+        ok: !error,
+        // The exit status, for the few commands whose non-zero exit is an
+        // answer rather than a failure (`merge-tree` exits 1 on a conflict).
+        code: error ? (typeof error.code === "number" ? error.code : -1) : 0,
+        stdout: String(stdout ?? ""),
+        stderr: String(stderr ?? ""),
+        detail: error ? String(stderr || error.message).trim() : "",
+      });
+    });
+  });
+
+/** Is `dir` inside a git checkout? False when git says no or cannot run. */
+export async function isGitCheckout(dir) {
+  const inRepo = await git(["rev-parse", "--is-inside-work-tree"], dir);
+  return inRepo.ok && inRepo.stdout.trim() === "true";
+}
+
+const exists = async (path) => {
+  try {
+    await access(path);
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+// PER-REPO LOCK for git mutations. makeWorktree, cleanWorktree, reuseWorktree,
+// mergeWorktree and deleteWorktree on the same root run one at a time. Reads
+// (branchOfWorktree, worktreeSummary) stay unlocked.
+//
+// It is TWO locks, because there are two ways to collide.
+//
+// IN-PROCESS, a promise chain keyed by repo root: two sessions finishing
+// inside one runner can no longer both `git checkout main` and merge at once.
+// This is the lock that has been here since 2026-09-01.
+//
+// CROSS-PROCESS, a lockdir under the repo's own `.git/`. The comment above
+// used to say "one runner process owns a root (the claim files keep two
+// runners apart), so an in-process lock is enough", and that was not true of
+// the code standing beside it: `spawn-runner.mjs merge <path>` and
+// `spawn-runner.mjs delete-worktree <path>` are a SECOND process, typed by a
+// person, calling straight into mergeWorktree while a watcher is running. The
+// claim files keep two runners from taking the same REQUEST; they say nothing
+// about two processes running `git checkout main` in the same second.
+//
+// `mkdir` is the primitive because it is the one atomic exclusive create every
+// filesystem agrees on - the same reasoning the claim file uses `flag: "wx"`.
+// The owner file inside it is who holds it, and it is how a lock survives its
+// holder being killed: a pid that is gone on this host frees it immediately, a
+// lock from another host frees on age alone. Waiting is bounded and losing the
+// wait is not fatal - it logs loudly and proceeds, because refusing to clean up
+// a worktree is worse than the small race that was there all along.
+const lockChains = new Map(); // root -> Promise that resolves when the lock is free
+
+/** How long a lockdir is believed before it is treated as abandoned. Git
+ * mutations here take seconds; ten minutes is a crashed holder, not a busy
+ * one. */
+export const LOCK_STALE_MS = 10 * 60_000;
+/** How long to wait for another process to finish before going ahead anyway. */
+export const LOCK_WAIT_MS = 60_000;
+const LOCK_POLL_MS = 150;
+
+// INSIDE `.git/`, and the reason is not tidiness. mergeWorktreeImpl refuses to
+// merge into a dirty checkout, and rightly - so a lock that git can SEE makes
+// every merge refuse itself. `.git/` is the one directory `git status` never
+// reports, it is exactly per-repo, and it is already where git keeps its own
+// locks. When `.git` is a file rather than a directory (this root is itself a
+// linked worktree) the mkdir fails, and acquireFileLock says so and proceeds.
+const lockDirFor = (root) => join(resolve(root), ".git", "pm-repo.lock");
+
+const stillAlive = (pid) => {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    // EPERM means it exists and belongs to somebody else.
+    return error?.code === "EPERM";
+  }
+};
+
+/** Take the cross-process lock. Returns a release function, or null when the
+ * wait ran out - the caller proceeds either way, and says so. */
+async function acquireFileLock(root, log) {
+  const dir = lockDirFor(root);
+  const startedAt = Date.now();
+  const deadline = startedAt + LOCK_WAIT_MS;
+  const mine = { pid: process.pid, host: hostname(), at: Date.now() };
+  // WAITED, NAMED (2026-09-21, the claim-to-spawn gap). `busy` is only true
+  // once the FIRST `mkdir` has already lost to EEXIST - so a lock taken on
+  // the first try logs nothing, same as before, and only a caller that
+  // actually queued behind another holder pays for a line. `lastOwner` is
+  // whichever `owner.json` was last read while waiting, so the eventual
+  // success can say who it waited on even though that holder may have
+  // released and vanished by the time this loop wins.
+  let busy = false;
+  let lastOwner = null;
+  for (;;) {
+    try {
+      await mkdir(dir); // EEXIST when somebody holds it: the whole of the lock
+      await writeFile(join(dir, "owner.json"), `${JSON.stringify(mine)}\n`, "utf8").catch(() => {});
+      if (busy) {
+        const waitedSecs = ((Date.now() - startedAt) / 1000).toFixed(1);
+        log(
+          `took the repo lock at ${dir} after waiting ${waitedSecs}s ` +
+            `(previously held by pid ${lastOwner?.pid ?? "?"} on ${lastOwner?.host ?? "?"})`,
+        );
+      }
+      return async () => { await rm(dir, { recursive: true, force: true }).catch(() => {}); };
+    } catch (error) {
+      if (error?.code !== "EEXIST") {
+        // No lock is better than no worktree operation: a `.git` that is a
+        // file (this root is a linked worktree), a read-only checkout, or a
+        // filesystem that will not mkdir must not stop a merge.
+        log(`could not take the repo lock (${error?.code ?? error}); proceeding without it`);
+        return null;
+      }
+      busy = true;
+      let owner = null;
+      try { owner = JSON.parse(await readFile(join(dir, "owner.json"), "utf8")); } catch { /* mid-write, or crashed between mkdir and write */ }
+      if (owner) lastOwner = owner;
+      // A holder that just won the `mkdir` has not written `owner.json` yet,
+      // so a reader landing in that gap sees the same ENOENT a crashed holder
+      // would leave forever. Treating "unreadable" as "infinitely old" (age
+      // measured from `at: 0`) cleared a LIVE lock out from under its holder
+      // on every such read - a real cross-process race, not just a test one.
+      // Falling back to the lock DIRECTORY's own age keeps a lock that was
+      // just taken safe (its mtime is now) while still reclaiming one whose
+      // holder crashed before ever writing owner.json (the dir ages past
+      // LOCK_STALE_MS same as always).
+      let age;
+      if (owner) {
+        age = Date.now() - (Number(owner.at) || 0);
+      } else {
+        const dirStat = await stat(dir).catch(() => null);
+        age = dirStat ? Date.now() - dirStat.mtimeMs : 0;
+      }
+      const deadHolder = owner?.host === mine.host && Number.isFinite(owner?.pid) && !stillAlive(owner.pid);
+      if (deadHolder || age > LOCK_STALE_MS) {
+        log(`clearing a ${deadHolder ? "dead" : "stale"} repo lock at ${dir} (pid ${owner?.pid ?? "?"})`);
+        await rm(dir, { recursive: true, force: true }).catch(() => {});
+        continue;
+      }
+      if (Date.now() >= deadline) {
+        log(
+          `waited ${Math.round(LOCK_WAIT_MS / 1000)}s for the repo lock held by pid ${owner?.pid ?? "?"} ` +
+            `on ${owner?.host ?? "?"}; going ahead anyway`,
+        );
+        return null;
+      }
+      await new Promise((r) => setTimeout(r, LOCK_POLL_MS));
+    }
+  }
+}
+
+/** Acquire the in-process lock for the given repo root. Returns a release
+ * function. */
+async function acquireRepoLock(root) {
+  const normalized = resolve(root); // normalize paths so /foo and /foo/ are the same key
+  const existingChain = lockChains.get(normalized) ?? Promise.resolve();
+  let release;
+  const newChain = new Promise((res) => { release = res; });
+  lockChains.set(normalized, newChain);
+  await existingChain;
+  return release;
+}
+
+/** Wrap a worktree operation with the repo lock, both halves. In-process
+ * first, so a queue of callers inside this process waits on a promise rather
+ * than on a directory. */
+export async function withRepoLock(root, fn, log = () => {}) {
+  const release = await acquireRepoLock(root);
+  let releaseFile = null;
+  try {
+    releaseFile = await acquireFileLock(root, log);
+    return await fn();
+  } finally {
+    if (releaseFile) await releaseFile();
+    release();
+  }
+}
+
+/** The repo's default branch, LOCAL only: `main` if `refs/heads/main` exists,
+ * else `master` if that exists, else null.
+ *
+ * PROVEN 2026-09-21: `makeWorktreeImpl` branched off `git rev-parse HEAD` -
+ * whatever the main checkout happened to have checked out, not the repo's
+ * actual default branch. A run based on a side branch someone left checked
+ * out, and `mergeWorktreeImpl` (which checks out literal `main` and merges
+ * into it) would have dragged that whole side branch into main. A run's
+ * worktree must instead base on the SAME ref the merge op merges into.
+ *
+ * LOCAL over `origin/*`: the merge op merges into the local branch of that
+ * name, so the base must be the same ref - basing off `origin/main` while
+ * local `main` has diverged would silently drop or duplicate commits at
+ * merge time. `--verify --quiet` against `refs/heads/<name>` so a detached
+ * HEAD or a missing branch is a clean `null`, not a thrown error. */
+export async function defaultBranchOf(root) {
+  for (const name of ["main", "master"]) {
+    const check = await git(["rev-parse", "--verify", "--quiet", `refs/heads/${name}`], root);
+    if (check.ok) return name;
+  }
+  return null;
+}
+
+/** The prompt's own name, made safe for a git ref and a directory.
+ *
+ * Only [a-z0-9-] survives, which is what keeps the result a legal ref: every
+ * shape git refuses (a leading dash, `..`, `@{`, a `.lock` ending, a space)
+ * is spelled with a character this drops. Capped so a 60-character title does
+ * not become a 60-character path segment; the tail below is what makes it
+ * unique, so cutting here loses traceability, never correctness. */
+export const slugForTitle = (title) =>
+  String(title ?? "")
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 40)
+    .replace(/-+$/g, "");
+
+/** The name both the tree and the branch are built from: the prompt, then the
+ *  request id.
+ *
+ * THE ID STAYS, and it is not decoration. Two runs of the same prompt would
+ * otherwise ask for the same branch, `git worktree add -b` would fail, and
+ * makeWorktree's failure path is "run in the linked checkout instead" - so a
+ * name collision would silently put the second session on his own working
+ * tree. It also keeps the tree traceable back to the file that asked for it,
+ * which is what the id was for before the prompt name joined it. Its `spawn-`
+ * prefix is dropped: `glytch` already says what this is. */
+export const worktreeStem = (id, title) => {
+  const slug = slugForTitle(title);
+  const tail = String(id ?? "").replace(/^spawn-/, "");
+  return [slug, tail].filter((part) => part !== "").join("-") || "session";
+};
+
+/** Where a request's worktree and branch live. A directory cannot hold the
+ *  branch's `/`, so the two differ by that one character and nothing else. */
+export const worktreeName = (id, title) => `${GLYTCH}-${worktreeStem(id, title)}`;
+export const worktreePath = (root, id, title) =>
+  join(root, ".claude", "worktrees", worktreeName(id, title));
+export const worktreeBranch = (id, title) => `${GLYTCH}/${worktreeStem(id, title)}`;
+
+/** True only when `target` resolves to a path strictly inside
+ *  `<root>/.claude/worktrees/` — the one directory makeWorktree ever creates.
+ *
+ * The merge/delete SIGNAL FILES carry the worktree path to act on, and until
+ * this nothing validated it: `killProcessesIn` SIGTERMs every process with a
+ * file open under the path, then `rm -rf` takes the directory, both twice.
+ * A `.delete` file containing {"worktreePath":"/Users/<me>"} would kill every
+ * process holding a file under home and recursively delete it. Board content
+ * is an injection surface (a spawned session can write into inbox/), so the
+ * path a request can name is fenced to where spawns actually live. Resolving
+ * an absolute `target` ignores `root`, which is exactly the escape we block;
+ * the trailing `sep` stops `.claude/worktrees-evil` passing as a sibling. */
+export function isContainedWorktree(root, target) {
+  if (typeof target !== "string" || target.trim() === "") return false;
+  const base = resolve(root, ".claude", "worktrees");
+  const abs = resolve(root, target);
+  return abs !== base && (abs + sep).startsWith(base + sep) && staysInProject(root, abs);
+}
+
+/** A directory inside the tree folder is not necessarily this repository's
+ * worktree. Destructive operations require Git's exact registration too. */
+async function registeredWorktree(root, target) {
+  if (!isContainedWorktree(root, target)) return false;
+  const listed = await git(["worktree", "list", "--porcelain", "-z"], root);
+  if (!listed.ok) return false;
+  try {
+    const canonical = canonicalPath(target);
+    return listed.stdout.split("\0").some((field) => {
+      if (!field.startsWith("worktree ")) return false;
+      try { return canonicalPath(field.slice(9)) === canonical; } catch { return false; }
+    });
+  } catch { return false; }
+}
+
+// ---------- THE CHAT WORKTREE (brief 25, ruling 1, 2026-09-07) ----------
+//
+// "One long-lived chat worktree per agent per folder,
+// `<root>/.claude/worktrees/chat-<agentId>`, made once and kept." A chat must
+// not mint a tree per MESSAGE - thirty messages would be thirty trees and
+// thirty branches, and resume would break on every one of them because Claude
+// Code keys its conversations to a working directory.
+//
+// So this half of the file is the opposite of the half above it. A session's
+// tree is made per run and thrown away by cleanWorktree when the run left
+// nothing in it; a chat tree is made ONCE, on the first message that finds it
+// missing, and is removed only when the AGENT is deleted. Nothing here
+// removes one, cleanWorktreeImpl refuses to (below), and the orphan reaper
+// steps over the name (procs.mjs, reapableWorktreeName).
+
+/** True when `target` is a chat worktree of this folder: inside the one
+ *  directory makeWorktree ever creates AND named `chat-<agentId>`.
+ *
+ * Both halves matter. The containment fence is isContainedWorktree's, for its
+ * reason (a request file is an injection surface and the path it names must
+ * not be able to say "up"); the name is what separates an agent's kept tree
+ * from a session's disposable one. */
+export function isChatWorktreePath(root, target) {
+  if (!isContainedWorktree(root, target)) return false;
+  return basename(resolve(root, target)).startsWith(CHAT_PREFIX);
+}
+
+/** The branch a chat worktree sits on: `glytch/chat-<agentId>`.
+ *
+ * Read OFF THE PATH rather than off a new request field, because the path
+ * already carries the agent id - the app builds `.claude/worktrees/chat-
+ * <agentId>` and that name is the only thing on either side of the contract
+ * that has to agree. `glytch/` is the prefix his 2026-08-28 ask put on every
+ * board-made branch so `git branch` correlates with the canvas, and a chat
+ * tree is board-made like any other. */
+export const chatWorktreeBranch = (path) => `${GLYTCH}/${basename(path)}`;
+
+/** WHERE A CHAT TURN RUNS, as an absolute path, or a refusal in words.
+ *
+ * The app writes `cwd` RELATIVE to the folder root and cannot do otherwise: a
+ * browser directory handle has a name, not a path (see the `cwd` note in
+ * src/folder/spawnRequest.ts), so it must not invent an absolute one. A cwd
+ * written by the CLI is absolute and is used as it stands. From the second
+ * turn on the app hands back the runner's own absolute `worktreePath` as the
+ * cwd, so only a first turn is ever relative.
+ *
+ * ANYTHING THAT ESCAPES THE FOLDER IS REFUSED, `..` and an absolute path
+ * outside it alike. A chat turn holds Write, Edit and Bash, and the folder is
+ * the boundary the person linked; a path outside it is either a mistake or
+ * somebody else's idea, and neither is worth guessing at. The root ITSELF is
+ * allowed, because a caller naming it is a caller who said so - the thing
+ * ruling 1 refuses is a silent FALLBACK to his checkout, which nothing here
+ * does. */
+export function resolveChatCwd(root, cwd) {
+  const named = typeof cwd === "string" ? cwd.trim() : "";
+  if (named === "") {
+    return { ok: false, reason: "A chat turn must name cwd: the directory the conversation lives in." };
+  }
+  return resolveContainedCwd(root, named, "a chat conversation");
+}
+
+/** The same fence for any request that names a `cwd` (#324): an ordinary
+ * run holds Write, Edit and Bash too, so a cwd that resolves outside the
+ * linked folder, or through a symbolic link, is refused rather than run in.
+ * `what` names the thing in the refusal. */
+export function resolveContainedCwd(root, cwd, what = "a run") {
+  const named = typeof cwd === "string" ? cwd.trim() : "";
+  const base = resolve(root);
+  const path = isAbsolute(named) ? resolve(named) : resolve(base, named);
+  if (named === "" || (path !== base && !(path + sep).startsWith(base + sep)) || !staysInProject(root, path)) {
+    return {
+      ok: false,
+      path,
+      reason:
+        `it resolves to ${path}, which is outside the folder this runner watches (${base}) or traverses a symbolic link. ` +
+        `A relative cwd is resolved against that folder and an absolute one is used as it stands; ` +
+        `either way ${what} runs inside the linked folder or it does not run.`,
+    };
+  }
+  return { ok: true, path };
+}
+
+/** Mint the chat worktree, once, for a turn that found it missing.
+ *
+ * `mintIfMissing: true` on the request is what asks for this, and it is asked
+ * for because THE APP CANNOT MAKE A WORKTREE. Ruling 1's directory has to
+ * exist before the first message can run in it, and the browser can only
+ * write a file. Session 1's refusal stands untouched for a request WITHOUT
+ * the flag: a missing directory with nothing asking for one is the
+ * conversation being gone, and falling back to the linked checkout would put
+ * a chat agent in the tree he is working in.
+ *
+ * Idempotent by construction: the caller only reaches this when the directory
+ * is not there, so a tree that already exists is used as it stands and a
+ * swept one comes back on the next message instead of failing it. The BRANCH
+ * may outlive the directory (someone `rm -rf`'d the tree, or `git worktree
+ * remove` left the branch), so an existing branch is checked out into the new
+ * tree rather than re-created - a `-b` onto a name git already knows fails,
+ * and failing here means a message he typed does not run.
+ *
+ * Returns `{ ok: true, path, branch, base, detail }`, or `{ ok: false,
+ * reason }` in words a person reads in the transcript. It never falls back
+ * the way makeWorktreeImpl does, and that is the difference between the two:
+ * a session that could not get a tree still has somewhere to run, and a chat
+ * turn's tree IS which conversation this is. */
+async function makeChatWorktreeImpl(root, path, log = () => {}) {
+  // A CHAT NEEDS A GIT REPO FOR ITS OWN WORKTREE. There is no unisolated
+  // fallback to offer: ruling 1 gives the agent a tree so it can edit and
+  // commit without touching his checkout, and a folder that is not a
+  // repository cannot give it one.
+  const inRepo = await git(["rev-parse", "--is-inside-work-tree"], root);
+  if (!inRepo.ok || inRepo.stdout.trim() !== "true") {
+    return {
+      ok: false,
+      reason:
+        `${root} is not a git repository, and a chat with a coding agent needs one: the agent ` +
+        `gets its OWN long-lived worktree (${path}) so it can read, edit and commit without ` +
+        `touching the checkout you are working in, and a worktree can only be cut from a repo. ` +
+        `Link a folder that is a git checkout, or run \`git init\` in this one, and send the ` +
+        `message again.`,
+    };
+  }
+  // The one place a chat tree may be made, so an injected request file cannot
+  // turn "mint if missing" into "create a directory anywhere in my folder".
+  if (!isChatWorktreePath(root, path)) {
+    return {
+      ok: false,
+      reason:
+        `${path} is not a chat worktree path. The runner mints one only at ` +
+        `<folder>/.claude/worktrees/chat-<agentId> (his ruling 1: one long-lived chat worktree ` +
+        `per agent per folder), so nothing was created and nothing was spawned.`,
+    };
+  }
+
+  await ensureIgnored(root, log);
+
+  const branch = chatWorktreeBranch(path);
+  // THE SAME BASE makeWorktreeImpl PICKS, and for its reason: the repo's
+  // default branch (main, else master), not whatever the main checkout
+  // happens to have checked out - a chat tree cut from a side branch someone
+  // left checked out would carry that branch's commits forever. Falls back to
+  // HEAD only when neither local branch exists.
+  const defaultBranch = await defaultBranchOf(root);
+  const baseRev = await git(["rev-parse", defaultBranch ?? "HEAD"], root);
+  const base = baseRev.ok ? baseRev.stdout.trim() : (defaultBranch ?? "HEAD");
+  const baseLabel = defaultBranch
+    ? `${defaultBranch} at ${base.slice(0, 7)}`
+    : `HEAD at ${base.slice(0, 7)}, no main or master branch`;
+  const known = await git(["rev-parse", "--verify", branch], root);
+  const add = known.ok
+    ? await git(["worktree", "add", path, branch], root)
+    : await git(["worktree", "add", "-b", branch, path, base], root);
+  if (!add.ok) {
+    return {
+      ok: false,
+      reason:
+        `The chat worktree ${path} could not be created, so this message did not run and ` +
+        `nothing was billed.\ngit said: ${add.detail}`,
+    };
+  }
+
+  // Same link a session's tree gets, for the same reason: an agent that
+  // cannot run the project's own tests cannot check what it just wrote.
+  const modules = join(root, "node_modules");
+  if (await exists(modules)) {
+    try {
+      await symlink(modules, join(path, "node_modules"), nodeModulesLinkType());
+    } catch (error) {
+      log(`chat worktree ${branch}: node_modules could not be linked: ${error?.message ?? error}`);
+    }
+  }
+
+  return {
+    ok: true,
+    path,
+    branch,
+    base,
+    detail: known.ok
+      ? `Minted the chat worktree ${path} on the existing branch ${branch}.`
+      : `Minted the chat worktree ${path} on branch ${branch} off ${baseLabel}.`,
+  };
+}
+
+/** Make the worktree a session will run in.
+ *
+ * Returns `{ cwd, isolated, branch?, path?, detail }`. Never throws and never
+ * refuses to run: if this is not a git repo, or git fails for any reason, the
+ * session still runs in `root` and `detail` says why it was not isolated. A
+ * runner that would rather spawn nothing than spawn unisolated is a runner
+ * that stops working the day someone tries it outside a checkout, and the
+ * money gate - not this - is what decides whether anything runs at all. */
+async function makeWorktreeImpl(root, id, log = () => {}, title = "") {
+  const inRepo = await git(["rev-parse", "--is-inside-work-tree"], root);
+  if (!inRepo.ok || inRepo.stdout.trim() !== "true") {
+    return {
+      cwd: root,
+      isolated: false,
+      detail:
+        `Not a git checkout, so this session ran in the linked folder itself ` +
+        `rather than an isolated worktree. Anything it changed, it changed there.`,
+    };
+  }
+
+  await ensureIgnored(root, log);
+
+  const path = worktreePath(root, id, title);
+  if (!isContainedWorktree(root, path)) throw new Error("Worktree creation refused: the path leaves this project or traverses a symbolic link.");
+  const branch = worktreeBranch(id, title);
+  // Branch off the repo's DEFAULT BRANCH (main, else master), not whatever
+  // the main checkout happens to have checked out. PROVEN 2026-09-21: basing
+  // on HEAD meant a run cut while the checkout sat on a side branch inherited
+  // that branch's commits, and "Keep changes" would have dragged the whole
+  // thing into main. Falls back to HEAD, and says so, only when neither local
+  // branch exists.
+  const defaultBranch = await defaultBranchOf(root);
+  const baseRev = await git(["rev-parse", defaultBranch ?? "HEAD"], root);
+  const base = baseRev.ok ? baseRev.stdout.trim() : (defaultBranch ?? "HEAD");
+  const baseLabel = defaultBranch
+    ? `${defaultBranch} at ${base.slice(0, 7)}`
+    : `HEAD at ${base.slice(0, 7)}, no main or master branch`;
+
+  const add = await git(["worktree", "add", "-b", branch, path, base], root);
+  if (!add.ok) {
+    return {
+      cwd: root,
+      isolated: false,
+      detail:
+        `Could not create a worktree, so this session ran in the linked folder ` +
+        `itself and anything it changed, it changed there.\ngit said: ${add.detail}`,
+    };
+  }
+
+  // Without this the session cannot run the project's own tests, which is
+  // most of what a brief asks it to do before reporting.
+  const modules = join(root, "node_modules");
+  if (await exists(modules)) {
+    try {
+      await symlink(modules, join(path, "node_modules"), nodeModulesLinkType());
+    } catch (error) {
+      log(`[${id}] node_modules could not be linked: ${error?.message ?? error}`);
+    }
+  }
+
+  return {
+    cwd: path,
+    isolated: true,
+    branch,
+    path,
+    detail: `Ran in its own worktree, ${path}, on branch ${branch} off ${baseLabel}.`,
+  };
+}
+
+/** Take the worktree away IF the session left nothing in it.
+ *
+ * An untouched tree is litter and goes. A tree with commits or uncommitted
+ * changes STAYS, because that is the session's work and the only copy of it -
+ * removing it would throw away the thing the run was for. The receipt says
+ * which happened, so a kept tree is never a surprise found weeks later. */
+async function cleanWorktreeImpl(root, made, log = () => {}, wroteFiles = []) {
+  // A CHAT WORKTREE IS NEVER CLEANED (brief 25, ruling 1, 2026-09-07:
+  // one long-lived chat worktree per agent per folder, kept). It is not this
+  // run's tree - it was there before the message and is what the NEXT message
+  // resumes in, and Claude Code keeps its conversations per working directory,
+  // so removing it because one turn happened to leave it tidy would throw the
+  // whole conversation away. runner.mjs does not call this for a chat turn at
+  // all; this is the guard that says so where the removal is, so a future
+  // caller cannot reach it by accident.
+  if (isChatWorktreePath(root, made?.path ?? "")) {
+    return {
+      removed: false,
+      detail: `${made?.detail ?? ""}\nKEPT: a chat worktree is the agent's own and outlives every turn that runs in it.`,
+    };
+  }
+  if (!made?.isolated || !made.path) return { removed: false, detail: made?.detail ?? "" };
+  if (!(await registeredWorktree(root, made.path))) return { removed: false, detail: "KEPT: worktree ownership could not be verified." };
+
+  const dirty = await git(["status", "--porcelain"], made.path);
+  const base = await git(["merge-base", made.branch, "HEAD"], root);
+  const commits = base.ok && base.stdout.trim()
+    ? await git(["log", "--oneline", `${base.stdout.trim()}..HEAD`], made.path)
+    : { ok: false, detail: base.detail || "Could not establish the worktree base." };
+  // Failed inspection is not evidence that this tree contains no work.
+  if (!dirty.ok || !commits.ok) {
+    const detail = `KEPT: could not verify worktree changes: ${!dirty.ok ? dirty.detail : commits.detail}`;
+    log(`[${made.branch}] ${detail}`);
+    return { removed: false, detail: `${made.detail}\n${detail}` };
+  }
+  // WHAT THE RUNNER WROTE IS NOT THE SESSION'S WORK. A config dropped in so
+  // the engine can reach the board (opencode.json) must not make the tree look
+  // dirty, or no opencode worktree would ever be cleaned up.
+  //
+  // Filtered here rather than excluded in git, and that distinction cost an
+  // hour: worktrees SHARE .git/info/exclude with the main checkout, so a
+  // "per-worktree" exclude is nothing of the sort - it silently made
+  // opencode.json un-trackable across the whole repository, which only
+  // surfaced when checking the file in failed. Deciding it at the one place
+  // that asks the question touches no shared git config and cannot leak.
+  const theirs = dirty.stdout
+    .split("\n")
+    .map((l) => l.trim())
+    .filter((l) => l !== "")
+    .filter((l) => !wroteFiles.some((f) => l.endsWith(` ${f}`) || l.endsWith(`/${f}`)));
+  const changed = (theirs.length > 0 || commits.stdout.trim() !== "");
+
+  if (changed) {
+    const n = commits.stdout.trim() === "" ? 0 : commits.stdout.trim().split("\n").length;
+    return {
+      removed: false,
+      detail:
+        `${made.detail}\nKEPT, because the session left work in it: ` +
+        `${n} commit${n === 1 ? "" : "s"}` +
+        `${theirs.length > 0 ? " and uncommitted changes" : ""}. ` +
+        `Review it there; nothing was merged anywhere.`,
+    };
+  }
+
+  const removed = await git(["worktree", "remove", "--force", made.path], root);
+  if (!removed.ok) {
+    log(`[${made.branch}] worktree could not be removed: ${removed.detail}`);
+    return { removed: false, detail: `${made.detail}\nIt is still on disk: ${removed.detail}` };
+  }
+  await git(["branch", "-D", made.branch], root);
+  return { removed: true, detail: `${made.detail}\nIt changed nothing, so the worktree was removed.` };
+}
+
+/** Keep spawn worktrees and preview records out of `git status`, without touching a tracked file.
+ *
+ * They live inside the repo on purpose - every worktree in this project is
+ * under `.claude/worktrees/`, and a session's tree should be where he already
+ * looks for one rather than in a temp directory he has to be told about. The
+ * cost is that git sees them.
+ *
+ * This clone happens to ignore them already, but through `.git/info/exclude`,
+ * which is LOCAL and not checked in - so on a fresh clone, or on anyone
+ * else's machine, the first spawn would start dirtying `git status` with its
+ * own worktrees. Depending on a file that only exists here is the kind of
+ * thing that works right up until it is someone else's problem.
+ *
+ * `.git/info/exclude` and not `.gitignore`: this is the runner's housekeeping,
+ * not a decision about the project, and a detachable sidecar has no business
+ * editing a tracked file to make itself comfortable. */
+async function ensureIgnored(root, log = () => {}) {
+  const missing = [];
+  for (const [file, pattern] of [[".claude/worktrees", ".claude/worktrees/"], [".glytch-server.json", "/.glytch-server.json"], [".glytch-page.json", "/.glytch-page.json"]]) {
+    const ignored = await git(["check-ignore", "-q", file], root);
+    if (!ignored.ok) missing.push(pattern);
+  }
+  if (missing.length === 0) return;
+  const dir = await git(["rev-parse", "--git-common-dir"], root);
+  if (!dir.ok) return;
+  const base = dir.stdout.trim();
+  // `git rev-parse --git-common-dir` prints an absolute path or a path
+  // relative to `root`. `base.startsWith("/")` only recognized the POSIX
+  // shape; a Windows absolute path ("C:\Users\..." or "C:/Users/...") never
+  // starts with "/", so it was joined onto `root` and wrote the exclude file
+  // to a garbage path. `isAbsolute` is platform-bound and gets both shapes
+  // right, including on the machine this actually runs on.
+  const path = join(isAbsolute(base) ? base : join(root, base), "info", "exclude");
+  try {
+    let current = "";
+    try {
+      current = await readFile(path, "utf8");
+    } catch {
+      /* no exclude file yet, which is normal */
+    }
+    const additions = missing.filter((pattern) => !current.split(/\r?\n/).includes(pattern));
+    if (additions.length === 0) return;
+    const sep = current === "" || current.endsWith("\n") ? "" : "\n";
+    await writeFile(
+      path,
+      `${current}${sep}# spawn runner files (bridge/lib/worktree.mjs), local only\n${additions.join("\n")}\n`,
+      "utf8",
+    );
+  } catch (error) {
+    // Not fatal: an unignored worktree is untidy, never unsafe.
+    log(`could not add runner files to the local exclude: ${error?.message ?? error}`);
+  }
+}
+
+/** Reuse an existing worktree for a resumed session.
+ *
+ * Returns the same shape as makeWorktree, but checks the tree still exists on
+ * disk and that git still knows about it. A worktree that was manually removed
+ * or pruned falls back to null, which tells the caller to make a fresh one. */
+async function reuseWorktreeImpl(root, existingPath, log = () => {}) {
+  // Same fence as merge/delete, and for a sharper reason: this path becomes the
+  // session's cwd and is reported as `isolated: true`. A resume request naming
+  // the linked checkout itself (a real git work tree, so every check below
+  // passes) would put an acceptEdits session on his own branch while the
+  // receipt swore it was isolated. Refusing here falls back to a fresh tree.
+  if (!isContainedWorktree(root, existingPath)) {
+    log(`reuse: refusing ${existingPath}, outside .claude/worktrees/`);
+    return null;
+  }
+  if (!existingPath || !(await exists(existingPath))) {
+    log(`reuse: path ${existingPath} does not exist on disk`);
+    return null;
+  }
+  if (!(await registeredWorktree(root, existingPath))) return null;
+  // Check git still knows this worktree.
+  const check = await git(["rev-parse", "--is-inside-work-tree"], existingPath);
+  if (!check.ok || check.stdout.trim() !== "true") {
+    log(`reuse: ${existingPath} is no longer a git worktree`);
+    return null;
+  }
+  // Find the branch name.
+  const branch = await git(["rev-parse", "--abbrev-ref", "HEAD"], existingPath);
+  const branchName = branch.ok ? branch.stdout.trim() : "unknown";
+  return {
+    cwd: existingPath,
+    isolated: true,
+    branch: branchName,
+    path: existingPath,
+    reused: true,
+    detail: `Reused existing worktree at ${existingPath} on branch ${branchName}.`,
+  };
+}
+
+/** The commit the worktree started from, for counting what the session added. */
+async function baseOf(made, root) {
+  const merge = await git(["merge-base", made.branch, "HEAD"], root);
+  return merge.ok && merge.stdout.trim() ? merge.stdout.trim() : "HEAD";
+}
+
+// ---------- post-session worktree operations ----------
+//
+// Called by the runner when the app writes a merge or delete signal file.
+// Git operations stay here, in the sidecar process, never in the browser.
+
+/** Derive the branch name from a worktree path, if git knows it. */
+export async function branchOfWorktree(worktreePath) {
+  if (!worktreePath) return null;
+  const branch = await git(["rev-parse", "--abbrev-ref", "HEAD"], worktreePath);
+  return branch.ok ? branch.stdout.trim() : null;
+}
+
+/** The identity a commit falls back to when the folder has none configured:
+ *  `git commit` and `commit-tree` refuse outright without one, and a Keep
+ *  that fails on "Please tell me who you are" is a Keep nobody can press. */
+async function identityArgs(cwd) {
+  const email = await git(["config", "user.email"], cwd);
+  const name = await git(["config", "user.name"], cwd);
+  return [
+    ...(name.ok && name.stdout.trim() ? [] : ["-c", "user.name=Viewable"]),
+    ...(email.ok && email.stdout.trim() ? [] : ["-c", "user.email=glytch@localhost"]),
+  ];
+}
+
+/** NUL-separated git output as a list, empties dropped. */
+const zList = (stdout) => stdout.split("\0").filter((p) => p !== "");
+
+/** What `git merge-tree --write-tree --name-only` says: the tree it would
+ *  write, or the files that conflict. Exit 0 is clean and exit 1 is a
+ *  conflict; anything else means this git cannot answer (merge-tree's
+ *  --write-tree is git 2.38), which is a refusal, never a guess. */
+async function trialMerge(cwd, ours, theirs) {
+  const out = await git(["merge-tree", "--write-tree", "--name-only", ours, theirs], cwd);
+  const lines = out.stdout.split("\n");
+  if (out.code === 0) return { clean: true, tree: lines[0].trim() };
+  if (out.code === 1) {
+    const end = lines.indexOf("", 1);
+    return { clean: false, files: lines.slice(1, end === -1 ? undefined : end).filter((l) => l !== "") };
+  }
+  return { error: out.detail || "git merge-tree failed" };
+}
+
+/** The paths a merge adds that already have something of the person's on
+ *  disk: an untracked file, an ignored one, or a file where the merge needs
+ *  a folder. It reads the disk, not `ls-files --exclude-standard`: git's
+ *  fast-forward overwrites an ignored file without a word, so an ignored
+ *  `.env.local` the agent also committed would be lost. A parent the merge
+ *  itself deletes (`removed`) is the merge's own and is not in the way. */
+async function inTheWay(root, added, removed) {
+  const hit = [];
+  for (const path of added) {
+    const parts = path.split("/");
+    for (let i = 1; i <= parts.length; i++) {
+      const at = parts.slice(0, i).join("/");
+      if (i < parts.length && removed.has(at)) break;
+      const found = await lstat(join(root, at)).catch(() => null);
+      if (!found) break;
+      if (i === parts.length || !found.isDirectory()) {
+        hit.push(path);
+        break;
+      }
+    }
+  }
+  return hit;
+}
+
+/** Keep changes (#483): one gesture that lands a session's copy in the
+ *  folder and clears the copy away.
+ *
+ *   1. Commit what the agent left uncommitted in the copy.
+ *   2. Work out the merge into the default branch WITHOUT touching the
+ *      folder (`merge-tree`), and, when the folder is on that branch with
+ *      changes of the person's own, whether those changes still sit on top
+ *      of the result. Either one conflicting stops here: nothing in the
+ *      folder has moved, and the answer names the files (`conflict: true`)
+ *      so the app can send Coding back to fit its changes around them.
+ *   3. Land it. On the default branch: set the person's changes aside (a
+ *      stash with its own name, tracked files only; untracked files are
+ *      never touched), fast-forward to the merge commit, put the changes
+ *      back. On any other branch: move the default branch's ref only, so
+ *      the folder does not change at all.
+ *   4. Delete the copy and its branch.
+ *
+ * Nothing is pushed: the person pushes when they want to. Returns
+ * `{ ok, detail, files?, conflict? }`; a success detail starts "Merged " (the
+ * app's `keptOf` reads that). */
+async function mergeWorktreeImpl(root, worktreePath, log = () => {}) {
+  if (!isContainedWorktree(root, worktreePath)) {
+    log(`refusing to merge a worktree outside .claude/worktrees/: ${worktreePath}`);
+    return { ok: false, detail: `Refusing to act on ${worktreePath}: not inside this project's .claude/worktrees/.` };
+  }
+  if (!(await registeredWorktree(root, worktreePath))) return { ok: false, detail: "Refusing: worktree ownership could not be verified." };
+  const branch = await branchOfWorktree(worktreePath);
+  if (!branch) {
+    return { ok: false, detail: `Could not determine branch for worktree at ${worktreePath}.` };
+  }
+  // SAME HELPER the worktree's own base used: a `master` repo merges into
+  // `master`, not a literal `main` that repo may not even have.
+  const defaultBranch = await defaultBranchOf(root);
+  if (!defaultBranch) {
+    return { ok: false, detail: `Could not find a local main or master branch to merge ${branch} into.` };
+  }
+  if (branch === defaultBranch) {
+    return { ok: false, detail: `Refusing to merge ${branch} into itself.` };
+  }
+  const folder = basename(root);
+  const ident = await identityArgs(root);
+
+  // 1. THE AGENT'S LEFTOVERS. Exclude the machine-specific preview record
+  // even if local exclude setup failed, along with the node_modules link the
+  // runner put there: `node_modules/` in a .gitignore matches a directory,
+  // not a symlink, so `add -A` alone would commit the link. The preview
+  // path uses a glob so git does not reject an already-ignored literal path.
+  // Older sessions may already have staged or committed the record. Remove
+  // only its index entry, even if the disk copy changed since staging; leave
+  // the live preview file intact. Do this before status so a clean tracked
+  // record produces a deletion commit too.
+  const untrack = await git(["rm", "--cached", "--force", "--ignore-unmatch", "--", ".glytch-server.json", ".glytch-page.json"], worktreePath);
+  if (!untrack.ok) return { ok: false, detail: `Could not commit what the session left: ${untrack.detail}` };
+  const leftovers = await git(["status", "--porcelain"], worktreePath);
+  if (!leftovers.ok) return { ok: false, detail: `Could not read the copy: ${leftovers.detail}` };
+  if (leftovers.stdout.trim() !== "") {
+    const add = await git(["add", "-A", "--", ".", ":(exclude)node_modules", ":(top,exclude,glob)[.]glytch-server.json", ":(top,exclude,glob)[.]glytch-page.json"], worktreePath);
+    const staged = add.ok ? await git(["diff", "--cached", "--quiet"], worktreePath) : add;
+    if (!add.ok) return { ok: false, detail: `Could not commit what the session left: ${add.detail}` };
+    if (staged.code === 1) {
+      const commit = await git([...ident, "commit", "-m", "What the session left uncommitted"], worktreePath);
+      if (!commit.ok) return { ok: false, detail: `Could not commit what the session left: ${commit.detail}` };
+    }
+  }
+
+  // 2. THE TRIAL, read-only. Every object it writes is unreferenced until
+  // step 3 points a ref at it.
+  const head = await git(["rev-parse", `refs/heads/${defaultBranch}`], root);
+  const tip = await git(["rev-parse", `refs/heads/${branch}`], root);
+  if (!head.ok || !tip.ok) return { ok: false, detail: `Could not read ${defaultBranch} or ${branch}: ${head.detail || tip.detail}` };
+  const base = head.stdout.trim();
+  const trial = await trialMerge(root, base, tip.stdout.trim());
+  if (trial.error) return { ok: false, detail: `Keep needs git 2.38 or newer to check for a conflict first. git said: ${trial.error}` };
+  const stopped = (files) => ({
+    ok: false,
+    conflict: true,
+    files,
+    detail: `Keep stopped: ${folder} changed while Coding worked${files.length ? ` (${files.join(", ")})` : ""}. Nothing in ${folder} was changed.`,
+  });
+  if (!trial.clean) return stopped(trial.files);
+  const made = await git(
+    [...ident, "commit-tree", trial.tree, "-p", base, "-p", tip.stdout.trim(), "-m", `Merge branch '${branch}'`],
+    root,
+  );
+  if (!made.ok) return { ok: false, detail: `Could not make the merge commit: ${made.detail}` };
+  const merged = made.stdout.trim();
+  const changed = await git(["diff", "--name-only", "-z", base, merged], root);
+  const files = changed.ok ? zList(changed.stdout).length : 0;
+
+  const current = await git(["symbolic-ref", "--quiet", "--short", "HEAD"], root);
+  const onDefault = current.ok && current.stdout.trim() === defaultBranch;
+
+  if (onDefault) {
+    // The person's untracked and ignored files stay where they are; one the
+    // merge would add under the same name is a conflict, not an overwrite.
+    // `--no-renames` so a rename or copy counts as its destination added
+    // (and a rename's source removed), whatever the folder's diff.renames.
+    const added = await git(["diff", "--no-renames", "--name-only", "-z", "--diff-filter=A", base, merged], root);
+    const removed = await git(["diff", "--no-renames", "--name-only", "-z", "--diff-filter=D", base, merged], root);
+    if (!added.ok || !removed.ok) return { ok: false, detail: `Could not read ${folder}: ${added.detail || removed.detail}` };
+    const clash = await inTheWay(root, zList(added.stdout), new Set(zList(removed.stdout)));
+    if (clash.length) return stopped(clash);
+    // Their tracked changes as a commit nothing points at (`stash create`
+    // touches neither the folder nor the stash list), tried on the result.
+    const pending = await git(["stash", "create"], root);
+    if (!pending.ok) return { ok: false, detail: `Could not read ${folder}: ${pending.detail}` };
+    if (pending.stdout.trim()) {
+      const fits = await trialMerge(root, merged, pending.stdout.trim());
+      if (fits.error) return { ok: false, detail: `Could not check your changes against the merge: ${fits.error}` };
+      if (!fits.clean) return stopped(fits.files);
+    }
+  } else {
+    // Another branch (or none) is checked out: the folder is never touched,
+    // so the only thing to refuse is a default branch checked out in some
+    // other worktree, whose files would fall out of step with its ref.
+    const trees = await git(["worktree", "list", "--porcelain"], root);
+    if (trees.ok && trees.stdout.split("\n").includes(`branch refs/heads/${defaultBranch}`)) {
+      return { ok: false, detail: `${defaultBranch} is open in another copy of this folder, so Keep left it alone.` };
+    }
+  }
+
+  // 3. LAND IT. The copy's processes go first: its dev server holds files
+  // open and `worktree remove` fails on them.
+  await killProcessesIn(worktreePath, log);
+  if (onDefault) {
+    const landed = await landOnCheckout(root, base, merged, log);
+    if (!landed.ok) return landed.conflict ? stopped(landed.files ?? []) : landed;
+  } else {
+    // Compare-and-swap: a default branch that moved since the trial fails here.
+    const moved = await git(["update-ref", `refs/heads/${defaultBranch}`, merged, base], root);
+    if (!moved.ok) return stopped([]);
+  }
+
+  // 4. THE COPY GOES. The merge is in; a copy that will not go is said, not hidden.
+  const removed = await git(["worktree", "remove", "--force", worktreePath], root);
+  const dropped = removed.ok ? await git(["branch", "-D", branch], root) : removed;
+  const tail = removed.ok
+    ? dropped.ok ? " The copy and its branch are gone." : ` The copy is gone; branch ${branch} was kept: ${dropped.detail}`
+    : ` The copy was kept: ${removed.detail}`;
+  log(`kept ${branch} in ${defaultBranch}: ${files} file(s)`);
+  return {
+    ok: true,
+    files,
+    detail: `Merged ${branch} into ${defaultBranch}, ${files} file${files === 1 ? "" : "s"} changed.${tail}`,
+  };
+}
+
+/** The folder is on the default branch: set the person's tracked changes
+ *  aside under a name of our own, fast-forward to the merge, put them back.
+ *  Any step that fails puts everything back as it was. */
+async function landOnCheckout(root, base, merged, log) {
+  const tag = `glytch keep ${Date.now()}`;
+  const dirty = await git(["status", "--porcelain", "--untracked-files=no"], root);
+  let saved = null;
+  if (dirty.ok && dirty.stdout.trim() !== "") {
+    const push = await git(["stash", "push", "-m", tag], root);
+    if (!push.ok) return { ok: false, detail: `Could not set your changes aside: ${push.detail}` };
+    const list = await git(["stash", "list", "--format=%H%x09%gs"], root);
+    saved = list.stdout.split("\n").map((l) => l.split("\t")).find(([, msg]) => msg?.endsWith(tag))?.[0] ?? null;
+    if (!saved) return { ok: false, detail: `Your changes were set aside as "${tag}" in git stash and could not be found again. Nothing was merged.` };
+  }
+  const restore = async () => {
+    if (!saved) return true;
+    const back = await git(["stash", "apply", "--index", saved], root);
+    const ok = back.ok || (await git(["stash", "apply", saved], root)).ok;
+    if (ok) await dropStash(root, saved);
+    else log(`could not put the person's changes back; they are in git stash as "${tag}"`);
+    return ok;
+  };
+  const ff = await git(["merge", "--ff-only", merged], root);
+  if (!ff.ok) {
+    await restore();
+    return { ok: false, conflict: true, files: [] };
+  }
+  if (!(await restore())) {
+    // The trial said this fits; the folder changed between the trial and now.
+    const unmerged = await git(["diff", "--name-only", "-z", "--diff-filter=U"], root);
+    await git(["reset", "--hard", base], root);
+    const again = await restore();
+    return again
+      ? { ok: false, conflict: true, files: unmerged.ok ? zList(unmerged.stdout) : [] }
+      : { ok: false, detail: `Your changes are safe in git stash as "${tag}"; Keep could not put them back by itself.` };
+  }
+  return { ok: true };
+}
+
+/** Drop one stash entry by its commit, re-finding its index first: other
+ *  stashes may have been pushed above it. */
+async function dropStash(root, sha) {
+  const list = await git(["stash", "list", "--format=%H"], root);
+  const at = list.stdout.split("\n").indexOf(sha);
+  if (at >= 0) await git(["stash", "drop", `stash@{${at}}`], root);
+}
+
+/** Throw away (#483): delete a session's copy and its branch without
+ *  merging. The run's history, plan and session stay readable on the board. */
+async function deleteWorktreeImpl(root, worktreePath, log = () => {}) {
+  if (!isContainedWorktree(root, worktreePath)) {
+    log(`refusing to delete a worktree outside .claude/worktrees/: ${worktreePath}`);
+    return { ok: false, detail: `Refusing to act on ${worktreePath}: not inside this project's .claude/worktrees/.` };
+  }
+  if (!(await registeredWorktree(root, worktreePath))) {
+    return { ok: false, detail: "Refusing: worktree ownership could not be verified." };
+  }
+  const branch = await branchOfWorktree(worktreePath);
+  await killProcessesIn(worktreePath, log);
+  // Recheck after asynchronous process cleanup. A failed Git removal never
+  // authorizes a recursive filesystem deletion.
+  if (!(await registeredWorktree(root, worktreePath))) return { ok: false, detail: "Refusing: worktree ownership changed." };
+  const remove = await git(["worktree", "remove", "--force", worktreePath], root);
+  if (!remove.ok) return { ok: false, detail: `Worktree was kept: ${remove.detail}` };
+  if (branch && branch !== "main" && branch !== "master") {
+    const deleted = await git(["branch", "-D", branch], root);
+    if (!deleted.ok) return { ok: false, detail: `Worktree removed; branch ${branch} was kept: ${deleted.detail}` };
+  }
+  return { ok: true, detail: `Deleted worktree at ${worktreePath}${branch ? ` and branch ${branch}` : ""}.` };
+}
+
+/** One summary line for a worktree: branch, commit count, files touched
+ * (committed or not, #482). The ruling on q-mtf66we4: "One summary line: branch, commits, files touched."
+ * Written by the runner into the sidecar so the app can show it on the run's
+ * card before a merge (DATED REWRITE 2026-09-07, brief 26 ruling 4: was "in
+ * the frame"). Returns null when the worktree is not a git checkout. */
+export async function worktreeSummary(worktreePath, root) {
+  if (!worktreePath) return null;
+  const branch = await branchOfWorktree(worktreePath);
+  if (!branch) return null;
+  const base = await baseOf({ branch }, root);
+  const log = await git(["log", "--oneline", `${base}..HEAD`], worktreePath);
+  const commits = log.ok && log.stdout.trim() !== "" ? log.stdout.trim().split("\n").length : 0;
+  const { files: touched, uncommitted } = await changedPaths(worktreePath, base);
+  const files = touched.length;
+  return {
+    branch, commits, files, uncommitted: uncommitted.length,
+    line: `${branch}: ${commits} commit${commits === 1 ? "" : "s"}, ${files} file${files === 1 ? "" : "s"} touched`,
+  };
+}
+
+/** Every path the session changed in its copy, committed or not (#482). A
+ *  session stopped before it committed still changed files: they count, so
+ *  the ending offers Keep changes, and the merge commits them. */
+async function changedPaths(worktreePath, base) {
+  const diff = await git(["diff", "--name-only", `${base}..HEAD`], worktreePath);
+  const committed = diff.ok ? diff.stdout.trim().split("\n").filter((l) => l !== "") : [];
+  const uncommitted = await uncommittedFiles(worktreePath);
+  return { files: [...new Set([...committed, ...uncommitted])], uncommitted };
+}
+
+/** The paths a run changed in its copy, for the page pictures (#2194). Empty
+ *  when the path is not a runner copy. */
+export async function changedFiles(worktreePath, root) {
+  if (!worktreePath) return [];
+  const branch = await branchOfWorktree(worktreePath);
+  if (!branch) return [];
+  const base = await baseOf({ branch }, root);
+  return (await changedPaths(worktreePath, base)).files;
+}
+
+/** The session's changes not yet committed in its copy, as paths. The
+ *  node_modules link the runner made (makeWorktree) is not the session's. */
+async function uncommittedFiles(worktreePath) {
+  const status = await git(["status", "--porcelain", "-z", "--untracked-files=all"], worktreePath);
+  if (!status.ok) return [];
+  const parts = status.stdout.split("\0");
+  const paths = [];
+  for (let i = 0; i < parts.length; i++) {
+    const entry = parts[i];
+    if (entry.length < 4) continue;
+    paths.push(entry.slice(3));
+    // A rename or copy is followed by its old path, which is not a second file.
+    if (entry[0] === "R" || entry[0] === "C") i++;
+  }
+  return paths.filter((p) => p !== "node_modules");
+}
+
+// LOCKED WRAPPERS for the five mutation functions. Git mutations on the same
+// root run one at a time, serialized by the in-process lock. Two concurrent
+// mergeWorktree calls on the same root are guaranteed to run sequentially, order
+// preserved. Reads (branchOfWorktree, worktreeSummary)
+// stay unlocked.
+export async function makeWorktree(root, id, log = () => {}, title = "") {
+  return withRepoLock(root, () => makeWorktreeImpl(root, id, log, title), log);
+}
+
+/** The chat tree's mint takes the repo lock like every other git mutation:
+ *  two rooms' first messages to the same agent, typed at once, are two
+ *  `worktree add` calls for one path. */
+export async function makeChatWorktree(root, path, log = () => {}) {
+  return withRepoLock(root, () => makeChatWorktreeImpl(root, path, log), log);
+}
+
+export async function cleanWorktree(root, made, log = () => {}, wroteFiles = []) {
+  return withRepoLock(root, () => cleanWorktreeImpl(root, made, log, wroteFiles), log);
+}
+
+export async function reuseWorktree(root, existingPath, log = () => {}) {
+  return withRepoLock(root, () => reuseWorktreeImpl(root, existingPath, log), log);
+}
+
+export async function mergeWorktree(root, worktreePath, log = () => {}) {
+  return withRepoLock(root, () => mergeWorktreeImpl(root, worktreePath, log), log);
+}
+
+export async function deleteWorktree(root, worktreePath, log = () => {}) {
+  return withRepoLock(root, () => deleteWorktreeImpl(root, worktreePath, log), log);
+}
+