tumwater 0.2.0 → 0.3.0

package/dist/src/git/git-run.js

@@ -2,10 +2,44 @@
  * identity the harness authors commits with. The query helpers built on top of it (heads,
  * refs, branches, diffs) live in git.ts and its siblings — this module knows git's argv,
  * not the repository's shape. */
+/** The author every harness-authored commit carries: tumwater, always, so blame-based
+ * classification (docs/code-metrics.md "Who wrote it", keyed on author and trailer) and
+ * INV-H1's "tumwater-stamped commit" wording stay true regardless of who invokes the team. */
+const COMMIT_AUTHOR = "tumwater <tumwater@localhost>";
+/** The ambient git identity of whoever invokes the team — `git config user.name` and
+ * `user.email` from the repo's local config and then global/system (git's own lookup path),
+ * read through gitTry so a key that is unset (git exits nonzero) reads as blank. When the
+ * repo and machine configure none (or only one of the two), fall back to tumwater on both
+ * sides so runs still work with no global git config (the long-standing fallback). No
+ * process-global cache: identity is resolved per call against the command's `cwd`, so a
+ * repo (or a test) with its own local identity reads correctly and no cross-repo bleed is
+ * possible. */
+export async function committerIdent(cwd) {
+    const name = (await gitTry(cwd, "config", "user.name"))?.trim() ?? "";
+    const email = (await gitTry(cwd, "config", "user.email"))?.trim() ?? "";
+    if (name !== "" && email !== "")
+        return { name, email };
+    return { name: "tumwater", email: "tumwater@localhost" };
+}
+/** The `--author` argv fragment every `git commit` call appends right after its `commit`
+ * subcommand, so the tumwater author is pinned: a commit would otherwise inherit the previous
+ * commit's author once committer and author stop being the same identity. `--author` is a
+ * commit option, not a global one, so it belongs after the subcommand, unlike the `-c` pairs. */
+export function commitAuthorArgs() {
+    return ["--author", COMMIT_AUTHOR];
+}
+/** Committer-only identity argv: the two `-c` pairs alone. For a rebase/cherry-pick these
+ * preserve each source commit's original (tumwater) author while rewriting the committer to
+ * the account running the team; a `git commit` call adds `commitAuthorArgs()` after its
+ * subcommand to pin the author too. */
+export async function committerIdentArgs(cwd) {
+    const { name, email } = await committerIdent(cwd);
+    return ["-c", `user.name=${name}`, "-c", `user.email=${email}`];
+}
 import { spawn } from "node:child_process";
 import { findOnPath } from "../files/files.js";
 import { realGitFromXcrun } from "./xcrun-git.js";
-import { EXEC_MAX_BUFFER, childEnv, releaseChildHandles, signalTree } from "../process/process.js";
+import { EXEC_MAX_BUFFER, captureCappedOutput, childEnv, releaseChildHandles, signalTree } from "../process/process.js";
 import { KILL_GRACE_MS, armGroupDeadline } from "../process/process-group.js";
 import { errorMessage } from "../text/text.js";
 /** The wall-clock bound on one git subprocess. Generous enough for a large rebase or diff on a slow
@@ -15,13 +49,6 @@ import { errorMessage } from "../text/text.js";
  * SIGTERM → SIGKILL escalation then runs for KILL_GRACE_MS, so one call is bounded at timeoutMs +
  * KILL_GRACE_MS whatever the child does. */
 export const GIT_TIMEOUT_MS = 600_000;
-/** Identity used for harness-authored commits so ticks work without global git config. */
-export const COMMIT_IDENT = [
-    "-c",
-    "user.name=tumwater",
-    "-c",
-    "user.email=tumwater@localhost",
-];
 /** The error every failed git subprocess reports: the argv, the cause text (git's stderr or the
  * spawn error's message), and git's exit code or the spawn errno. */
 export class GitError extends Error {
@@ -35,12 +62,26 @@ export class GitError extends Error {
     /** git's exit code (a number) — or a spawn errno like "ENOENT" (a string) when the
      * binary itself could not be started, which is what execFile puts in `err.code` then. */
     code) {
-        super(`git ${args.join(" ")} failed${code !== undefined ? ` (${code})` : ""}${stderr ? `: ${stderr}` : ""}`);
+        // Quote any argv a space or quote would make ambiguous (a multi-word commit message, a
+        // path), so the reported command reads unambiguously instead of "commit -m some message"
+        // reading as a stray subcommand plus arguments. Single-token argv stays bare, keeping the
+        // pinned "git status failed (1)" shape. JSON.stringify is the codebase's shared value
+        // quoting idiom (gotSuffix, cli/error text use it for the same reason).
+        const argv = args.map((a) => (/[\s"\\]/.test(a) ? JSON.stringify(a) : a)).join(" ");
+        super(`git ${argv} failed${code !== undefined ? ` (${code})` : ""}${stderr ? `: ${stderr}` : ""}`);
         this.args = args;
         this.stderr = stderr;
         this.code = code;
     }
 }
+/** True when `err` is a git call whose process could not be started at all: a spawn errno such
+ * as EAGAIN or ENOMEM, which is what every git call reported while the 2026-10-21 process-table
+ * wedge lasted. That says nothing about the repository and passes with the condition, so a
+ * caller about to act on the answer (discard edits, reset a workspace) waits and retries rather
+ * than treating it as "nothing there". */
+export function gitCouldNotStart(err) {
+    return err instanceof GitError && typeof err.code === "string";
+}
 /** The one error every entry point that shells out to git reports when the binary itself is
  * missing from PATH. Without a preflight check, `isGitRepo`'s failed probe reads as "not a
  * git repository (run `git init` first)" — pointing at the wrong fix for a machine with no
@@ -129,17 +170,25 @@ export function execGitBounded(args, opts) {
         stdio: ["pipe", "pipe", "pipe"],
         ...(opts.extraEnv ? { env: childEnv(opts.extraEnv) } : {}),
     });
-    let stdout = "";
-    let stderr = "";
     const promise = new Promise((resolve, reject) => {
         let settled = false;
-        let stdoutSize = 0;
-        let stderrSize = 0;
         const deadline = armGroupDeadline(child, {
             timeoutMs,
             killGraceMs,
             onTimedOut: () => finish(new GitTimeoutError(timeoutMs)),
         });
+        // setEncoding gives the stream a StringDecoder, so a multibyte UTF-8 character split
+        // across chunk boundaries is reassembled rather than corrupted — what execFile's utf8
+        // decoding did before this rewrite. It must precede captureCappedOutput so the receiver
+        // sees strings, not raw buffers.
+        child.stdout?.setEncoding("utf8");
+        child.stderr?.setEncoding("utf8");
+        const cap = captureCappedOutput(child, EXEC_MAX_BUFFER, (stream) => {
+            // Output past the ceiling is a hard failure, not silent truncation: killing the group
+            // stops a git that would otherwise emit unbounded output, and the error names the stream.
+            signalTree(child, "SIGKILL");
+            finish(new GitExecError(cap.stderr, "ERR_CHILD_PROCESS_STDIO_MAXBUFFER", `${stream} maxBuffer length exceeded`));
+        });
         const finish = (err) => {
             if (settled)
                 return;
@@ -152,32 +201,11 @@ export function execGitBounded(args, opts) {
                 reject(err);
             }
             else {
-                resolve({ stdout, stderr });
+                // Read cap's fields at settle time (they accumulate as data arrives) rather than
+                // destructuring a snapshot that stays empty.
+                resolve({ stdout: cap.stdout, stderr: cap.stderr });
             }
         };
-        const onOverflow = (stream) => {
-            signalTree(child, "SIGKILL");
-            finish(new GitExecError(stderr, "ERR_CHILD_PROCESS_STDIO_MAXBUFFER", `${stream} maxBuffer length exceeded`));
-        };
-        // setEncoding gives the stream a StringDecoder, so a multibyte UTF-8 character split
-        // across chunk boundaries is reassembled rather than corrupted — what execFile's utf8
-        // decoding did before this rewrite.
-        child.stdout?.setEncoding("utf8");
-        child.stderr?.setEncoding("utf8");
-        child.stdout?.on("data", (chunk) => {
-            stdoutSize += Buffer.byteLength(chunk);
-            if (stdoutSize > EXEC_MAX_BUFFER)
-                onOverflow("stdout");
-            else
-                stdout += chunk;
-        });
-        child.stderr?.on("data", (chunk) => {
-            stderrSize += Buffer.byteLength(chunk);
-            if (stderrSize > EXEC_MAX_BUFFER)
-                onOverflow("stderr");
-            else
-                stderr += chunk;
-        });
         child.on("error", (err) => {
             // Before the deadline this is the spawn failing (git missing from PATH); after it, it can
             // only be a teardown signal that could not be delivered — the run is a timeout either
@@ -194,7 +222,7 @@ export function execGitBounded(args, opts) {
             else if (code === 0)
                 finish();
             else
-                finish(new GitExecError(stderr, code ?? undefined));
+                finish(new GitExecError(cap.stderr, code ?? undefined));
         });
     });
     return Object.assign(promise, { child });
@@ -235,3 +263,16 @@ export async function gitTry(cwd, ...args) {
         return null;
     }
 }
+/** gitTry for a call whose failure is itself an answer the caller acts on (no merge-base, a
+ * cherry-pick that stopped), when acting on it drops work: null only when git ran and failed,
+ * and a throw when git could not start (gitCouldNotStart), which answers nothing. */
+export async function gitTryStarted(cwd, ...args) {
+    try {
+        return await runGit(cwd, args);
+    }
+    catch (err) {
+        if (gitCouldNotStart(err))
+            throw err;
+        return null;
+    }
+}

package/dist/src/git/git.js

@@ -1,6 +1,8 @@
+import { errCode } from "../errno.js";
+import { isDirectory } from "../files/files.js";
 import fs from "node:fs";
 import path from "node:path";
-import { COMMIT_IDENT, GIT_TIMEOUT_MS, execGitBounded, git, gitTry } from "./git-run.js";
+import { GIT_TIMEOUT_MS, commitAuthorArgs, committerIdentArgs, execGitBounded, git, gitCouldNotStart, gitTry } from "./git-run.js";
 /** A valid object id (SHA-1 or SHA-256). */
 function isSha(s) {
     return /^[0-9a-f]{40,64}$/.test(s);
@@ -12,17 +14,11 @@ function isSha(s) {
  * when the ref cannot be resolved from files — no repo here, `.git` is a worktree pointer
  * file, the branch does not exist, or content fails validation — so callers can fall back to
  * `git rev-parse`. Synchronous and microsecond-scale: this exists for poll loops that would
- * otherwise pay a ~10ms subprocess spawn per tick just to watch main. */
+ * otherwise pay a ~10ms subprocess spawn per run just to watch main. */
 export function readBranchHead(root, branch) {
-    let st;
-    try {
-        st = fs.statSync(path.join(root, ".git"));
-    }
-    catch {
-        return null; // Not a repo (or .git missing).
-    }
-    if (!st.isDirectory())
-        return null; // Worktree pointer file — the spawn fallback knows better.
+    // Not a repo (or .git missing), or a worktree pointer file — the spawn fallback knows better.
+    if (!isDirectory(path.join(root, ".git")))
+        return null;
     try {
         const sha = fs.readFileSync(path.join(root, ".git", "refs", "heads", branch), "utf8").trim();
         if (isSha(sha))
@@ -43,8 +39,8 @@ export function readBranchHead(root, branch) {
 /** Resolve a branch's head without paying for a spawn when the ref files suffice:
  * readBranchHead (microsecond-scale) first, then `git rev-parse` as the fallback that covers
  * what file reads cannot (a worktree-pointer .git, anything unusual). Returns null when
- * neither resolves it. Shared by the orchestrator's per-poll main watch, each tick's
- * end-of-tick head update, the red-main baseline check, and the stack merger, so the
+ * neither resolves it. Shared by the orchestrator's per-poll main watch, each run's
+ * end-of-run head update, the red-main baseline check, and the stack merger, so the
  * file-first/spawn-fallback strategy lives in one place. */
 export async function branchHead(root, branch) {
     return readBranchHead(root, branch) ?? (await gitTry(root, "rev-parse", branch));
@@ -87,7 +83,7 @@ function repoFiles(dir) {
         commondir = path.resolve(gitdir, pointer);
     }
     catch (err) {
-        if (err.code !== "ENOENT")
+        if (errCode(err) !== "ENOENT")
             return undefined; // A primary checkout has none.
     }
     try {
@@ -139,7 +135,7 @@ function storedRef(commondir, ref) {
         return isSha(loose) ? loose : undefined;
     }
     catch (err) {
-        if (err.code !== "ENOENT")
+        if (errCode(err) !== "ENOENT")
             return undefined;
     }
     let packed;
@@ -147,7 +143,7 @@ function storedRef(commondir, ref) {
         packed = fs.readFileSync(path.join(commondir, "packed-refs"), "utf8");
     }
     catch (err) {
-        return err.code === "ENOENT" ? null : undefined;
+        return errCode(err) === "ENOENT" ? null : undefined;
     }
     return shaFromPackedRefs(packed, ` ${ref}`);
 }
@@ -204,7 +200,7 @@ export function hasWorktreeRegistrations(root) {
         return fs.readdirSync(path.join(repo.commondir, "worktrees")).length > 0;
     }
     catch (err) {
-        return err.code === "ENOENT" ? false : undefined;
+        return errCode(err) === "ENOENT" ? false : undefined;
     }
 }
 /** True when the files settle that the full ref name `ref` does NOT exist in `dir`'s repository:
@@ -249,6 +245,10 @@ export async function refsUnder(root, prefix) {
         return { ref, sha };
     });
 }
+/** Whether `sha` names a commit present in the repository. */
+export async function commitExists(root, sha) {
+    return (await gitTry(root, "cat-file", "-e", `${sha}^{commit}`)) !== null;
+}
 /** Delete `ref` only while it still names `sha` (git update-ref -d guarded by the old value). */
 export async function deleteRefIfAt(root, ref, sha) {
     await gitTry(root, "update-ref", "-d", ref, sha);
@@ -294,7 +294,7 @@ function toplevelFromFiles(dir) {
             text = fs.readFileSync(config, "utf8");
         }
         catch (err) {
-            if (err.code === "ENOENT")
+            if (errCode(err) === "ENOENT")
                 continue;
             return undefined;
         }
@@ -311,12 +311,7 @@ function toplevelFromFiles(dir) {
 }
 /** True when the local branch `<branch>` exists in the repo. */
 export async function branchExists(root, branch) {
-    const ref = `refs/heads/${branch}`;
-    if (refShaFromFiles(root, ref) !== undefined)
-        return true;
-    if (refAbsentFromFiles(root, ref))
-        return false;
-    return (await gitTry(root, "rev-parse", "--verify", ref)) !== null;
+    return (await refSha(root, `refs/heads/${branch}`)) !== null;
 }
 /** The revision a worktree's change should be judged against: the merge-base of its HEAD with
  * `mainBranch`, falling back to main's tip when the merge-base fails (no common ancestor, or no
@@ -430,17 +425,23 @@ export async function isDirty(cwd) {
  * HEAD by the time the reset runs) and untracked files via clean -fd. Returns the new commit hash,
  * or null when nothing was stageable under those paths (the caller then decides what to do with the
  * rest). The refusal path uses this so a refusing run's objection note is kept while its half-done
- * code work is not. */
+ * code work is not. A git that could not start throws instead (gitCouldNotStart): read as
+ * "nothing stageable", it would send the caller on to discard everything, notes included. */
 export async function commitPathsAndDiscardRest(wt, message, paths) {
     if (paths.length === 0)
         return null;
-    const added = await gitTry(wt, "add", "--", ...paths);
-    if (added === null)
+    try {
+        await git(wt, "add", "--", ...paths);
+    }
+    catch (err) {
+        if (gitCouldNotStart(err))
+            throw err;
         return null; // Pathspec matched nothing — treat as nothing stageable.
-    const staged = await gitTry(wt, "diff", "--cached", "--name-only");
+    }
+    const staged = await git(wt, "diff", "--cached", "--name-only");
     if (!staged)
         return null; // Nothing actually changed under those paths.
-    await git(wt, ...COMMIT_IDENT, "commit", "-m", message);
+    await git(wt, ...(await committerIdentArgs(wt)), "commit", ...commitAuthorArgs(), "-m", message);
     await git(wt, "reset", "--hard", "HEAD");
     await git(wt, "clean", "-fd");
     return headOf(wt, "HEAD");
@@ -473,9 +474,10 @@ export async function aheadOfMain(wt, mainBranch) {
 }
 /** The patch-id of the change `head` makes on top of `base`: `git diff` over `base...head` (from
  * their merge-base, the same range aheadOfMainDiff hands the reviewer) piped into
- * `git patch-id`. Two shas carrying the same diff — an approved head and its clean rebase onto
- * a moved main — share it, since patch-id ignores hunk line numbers; a rebase that changed any
- * line of the patch, context included, does not. `--verbatim` over `--stable`: `--stable` also
+ * `git patch-id`. The diff is `-U0`: the change's own lines only, no context. Two shas carrying
+ * the same change — an approved head and its rebase onto a main that moved next to a hunk —
+ * share it, since patch-id ignores hunk line numbers; a rebase that changed any added or removed
+ * line does not. `--verbatim` over `--stable`: `--stable` also
  * strips whitespace, so a whitespace-only difference would reuse an approval. `--binary` puts
  * binary content in the hash (without it every binary change reads "Binary files differ"), and
  * `--no-ext-diff --no-textconv` keep user diff config out of it. The raw stdout goes to
@@ -486,7 +488,7 @@ export async function patchId(wt, base, head) {
     try {
         // Both children run through execGitBounded, so a hung diff or patch-id is SIGTERMed group-wide
         // and SIGKILLed after the grace instead of stalling merge's approval check.
-        const { stdout: diff } = await execGitBounded(["diff", "--no-color", "--no-ext-diff", "--no-textconv", "--binary", `${base}...${head}`], { cwd: wt, timeoutMs: GIT_TIMEOUT_MS });
+        const { stdout: diff } = await execGitBounded(["diff", "--no-color", "--no-ext-diff", "--no-textconv", "--binary", "-U0", `${base}...${head}`], { cwd: wt, timeoutMs: GIT_TIMEOUT_MS });
         if (diff === "")
             return null;
         const run = execGitBounded(["patch-id", "--verbatim"], { cwd: wt, timeoutMs: GIT_TIMEOUT_MS });
@@ -514,6 +516,6 @@ export async function foldCommitsSince(wt, base) {
 /** Stage and commit everything in the worktree. Returns the new commit hash. */
 export async function commitAll(wt, message) {
     await git(wt, "add", "-A");
-    await git(wt, ...COMMIT_IDENT, "commit", "-m", message);
+    await git(wt, ...(await committerIdentArgs(wt)), "commit", ...commitAuthorArgs(), "-m", message);
     return headOf(wt, "HEAD");
 }

package/dist/src/git/slot-salvage.js

@@ -0,0 +1,253 @@
+/** Saving what a pooled slot still holds before it is reset for another lease, and handing a
+ * role's unfinished work back to its next run. A run the harness could not clean up after
+ * (killed, or its own git calls failing, as every spawn did during the 2026-10-21 process-table
+ * wedge) can release its slot with uncommitted edits still in it. The next lease resets the slot
+ * to main, which used to fail on those edits for every role it was handed ("Your local changes …
+ * would be overwritten by checkout"), and a role branch's forced checkout dropped them without a
+ * trace. The reset now always succeeds (worktree.ts checks out with --force), so this is the step
+ * that keeps the work: the edits become a patch and a warning names the slot, the role that left
+ * them and the file.
+ *
+ * A patch whose run gave its slot up unsettled (the slot record's `unsettledRun`: an exception
+ * escaped the run, or its process died holding the lease) waits under salvagePendingDir until
+ * that role's next run, which restores it into its fresh checkout (restoreSalvagedWork) and
+ * runs as a handoff over it. A patch the role's branch has moved under still goes back: files
+ * that conflict keep their markers, and hunks git cannot place at all reach the run as text to
+ * apply by hand. Every other patch is edits a settled run chose to discard, or a verification's
+ * scratch output: those stay directly under salvageDir for the operator. Session retention
+ * prunes both kinds (src/orchestrator/retention.ts).
+ *
+ * Neither half throws work away on a git that could not start (gitCouldNotStart, the wedge's
+ * EAGAIN): the salvage leaves the slot as it is and fails the lease, and the restore leaves the
+ * patch waiting, so the next attempt finds everything where it was. */
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { warnEventBestEffort, TUMWATER_SOURCE } from "../events/events.js";
+import { writeTextAtomic } from "../files/files.js";
+import { conflictedFiles } from "../merge/merge-git.js";
+import { salvageDir, salvagePendingDir } from "../paths.js";
+import { errorMessage } from "../text/text.js";
+import { git, gitCouldNotStart, gitTry, runGit } from "./git-run.js";
+import { isUsableWorktree } from "./worktree.js";
+/** The patch file's name: a sortable local timestamp, the slot's directory name and the role that
+ * last held it, so a listing reads in order and names whose work each file is. */
+function salvageFileName(now, slotDir, leftBy) {
+    const pad = (n) => String(n).padStart(2, "0");
+    const stamp = `${now.getFullYear()}-${pad(now.getMonth() + 1)}-${pad(now.getDate())}` +
+        `-${pad(now.getHours())}${pad(now.getMinutes())}${pad(now.getSeconds())}`;
+    return `${stamp}-${path.basename(slotDir)}-${leftBy ?? "unknown"}.patch`;
+}
+/** Save the uncommitted changes in `dir` (modified, deleted and untracked files, ignored ones
+ * excepted) as a patch against its HEAD, and log a warning naming the slot, the role that left
+ * them and the file, before `forRole`'s lease resets it. The patch waits for `recoverFor`'s next
+ * run under salvagePendingDir when it is set, and is kept directly under salvageDir otherwise.
+ * Returns the patch path, or null when there was nothing to save or `dir` is not a worktree git
+ * can read (a slot about to be recreated). The patch is built through a temporary index, so the
+ * slot's own index is untouched. Throws only when git could not start (gitCouldNotStart), which
+ * fails the lease with the slot untouched: the lease that finds git running again saves the
+ * edits. Any other failure to save is logged as a warning that the edits are being discarded
+ * unsaved, and the reset goes ahead, since a slot that no lease can reset would fail every role
+ * the pool hands it. */
+export async function salvageSlotLeftovers(root, dir, { leftBy, recoverFor, forRole }, now = new Date()) {
+    const slot = path.basename(dir);
+    let status;
+    try {
+        status = await git(dir, "status", "--porcelain", "--untracked-files=all");
+    }
+    catch (err) {
+        if (gitCouldNotStart(err) && (await isUsableWorktree(dir)))
+            throw err;
+        return null;
+    }
+    if (status === "")
+        return null;
+    const files = status.split("\n").filter((line) => line.trim() !== "").length;
+    const by = leftBy ?? "an unknown role";
+    let tmp;
+    try {
+        tmp = fs.mkdtempSync(path.join(os.tmpdir(), "tumwater-salvage-"));
+        const env = { GIT_INDEX_FILE: path.join(tmp, "index") };
+        await runGit(dir, ["read-tree", "HEAD"], env);
+        await runGit(dir, ["add", "-A"], env);
+        const patch = await runGit(dir, ["diff", "--cached", "--binary", "HEAD"], env);
+        if (patch === "")
+            return null;
+        const base = await git(dir, "rev-parse", "HEAD");
+        const home = recoverFor === null ? salvageDir(root) : salvagePendingDir(root, recoverFor);
+        const file = path.join(home, salvageFileName(now, dir, leftBy));
+        fs.mkdirSync(home, { recursive: true });
+        // Atomic: the patch is the only copy left once the lease resets the workspace, so a kill
+        // mid-write must never leave a truncated .patch that a later restore reads and partially
+        // applies. Written to a temp name and renamed, a reader (restoreSalvagedWork) sees either
+        // no file or the complete patch, never a prefix.
+        writeTextAtomic(file, `# ${files} uncommitted file(s) ${by} left in workspace ${slot}, saved before ${forRole} reused it\n` +
+            `# base ${base}; apply with: git apply --index <this file> on a checkout of that commit\n` +
+            `${patch}\n`);
+        const saved = path.relative(root, file);
+        warnEventBestEffort(root, TUMWATER_SOURCE, recoverFor === null
+            ? `workspace ${slot} still held ${files} uncommitted file(s) ${by} left behind; saved them to ${saved} and reset it for ${forRole}`
+            : `workspace ${slot} still held ${files} uncommitted file(s) from ${recoverFor}'s unfinished run; saved them to ${saved} for its next run and reset it for ${forRole}`);
+        return file;
+    }
+    catch (err) {
+        if (gitCouldNotStart(err))
+            throw err;
+        warnEventBestEffort(root, TUMWATER_SOURCE, `workspace ${slot} still held ${files} uncommitted file(s) ${by} left behind, and saving them failed (${errorMessage(err)}); resetting it for ${forRole} discards them`);
+        return null;
+    }
+    finally {
+        if (tmp !== undefined)
+            fs.rmSync(tmp, { recursive: true, force: true });
+    }
+}
+/** The patches waiting for `role`'s next run, newest first (the timestamped names sort in time
+ * order). Empty when none wait or the directory cannot be read. */
+function pendingPatches(root, role) {
+    const dir = salvagePendingDir(root, role);
+    let names;
+    try {
+        names = fs.readdirSync(dir);
+    }
+    catch {
+        return [];
+    }
+    return names
+        .filter((name) => name.endsWith(".patch"))
+        .sort()
+        .reverse()
+        .map((name) => path.join(dir, name));
+}
+/** Move a pending patch out to salvageDir, where it is kept for the operator until retention
+ * prunes it, and return its new path (the old one when the move fails, so the warning that
+ * names it still points at the file). */
+function settlePatch(root, file) {
+    const kept = path.join(salvageDir(root), path.basename(file));
+    try {
+        fs.renameSync(file, kept);
+        return kept;
+    }
+    catch {
+        return file;
+    }
+}
+/** Restore the newest patch of `role`'s unfinished work waiting under salvagePendingDir into `dir`,
+ * the fresh checkout of the role's branch its run is about to work in, as uncommitted edits. The
+ * patch applies exactly when the checkout is still at the patch's base. When the branch has moved,
+ * each file goes back on its own (placeSalvagedFile): by a three-way merge, which may leave
+ * conflict markers, else hunk by hunk, with the hunks that fit nowhere returned as text. The
+ * result is unstaged, so the run finds the worktree an interrupted run would have kept. The
+ * patch, and any older one it supersedes, then moves out to salvageDir. Returns null when
+ * nothing was pending. When git could not start or the patch could not be read, the checkout is
+ * put back as it was, the patch stays waiting for the role's next run, and a warning says so.
+ * Never throws. */
+export async function restoreSalvagedWork(root, role, dir) {
+    const [newest, ...older] = pendingPatches(root, role);
+    if (newest === undefined)
+        return null;
+    let placed;
+    try {
+        placed = await applySalvage(dir, newest);
+    }
+    catch (err) {
+        await gitTry(dir, "reset", "-q", "--hard");
+        await gitTry(dir, "clean", "-fdq");
+        warnEventBestEffort(root, role, `could not restore the uncommitted work an earlier run left unfinished (${errorMessage(err)}); it stays waiting at ${path.relative(root, newest)} for the next run`);
+        return null;
+    }
+    for (const file of older)
+        settlePatch(root, file);
+    return { patch: settlePatch(root, newest), ...placed };
+}
+/** Apply `patch` into the clean checkout `dir`: exactly when it fits, else file by file. Throws
+ * only when git could not start or the patch cannot be read. */
+async function applySalvage(dir, patch) {
+    try {
+        await git(dir, "apply", "--index", patch);
+        await git(dir, "reset", "-q");
+        return { conflicted: [], unplaced: [] };
+    }
+    catch (err) {
+        if (gitCouldNotStart(err))
+            throw err;
+    }
+    const unplaced = [];
+    const tmp = fs.mkdtempSync(path.join(os.tmpdir(), "tumwater-restore-"));
+    try {
+        const sections = fs.readFileSync(patch, "utf8").split(/^(?=diff --git )/m).filter((p) => p.startsWith("diff --git "));
+        for (const [i, section] of sections.entries()) {
+            const file = path.join(tmp, `${i}.patch`);
+            fs.writeFileSync(file, section);
+            unplaced.push(...(await placeSalvagedFile(dir, file, section)));
+        }
+    }
+    finally {
+        fs.rmSync(tmp, { recursive: true, force: true });
+    }
+    // Read before the reset drops the unmerged index entries; the markers stay in the files.
+    const conflicted = await conflictedFiles(dir);
+    await git(dir, "reset", "-q");
+    return { conflicted, unplaced };
+}
+/** The paths one file's section of a patch touches (`git apply --numstat -z`: a rename names its
+ * new path), without decoding git's quoting by hand. */
+async function sectionPaths(dir, file) {
+    const fields = (await git(dir, "apply", "--numstat", "-z", file)).split("\0");
+    const paths = [];
+    for (let i = 0; i < fields.length; i++) {
+        const m = /^[-\d]+\t[-\d]+\t(.*)$/s.exec(fields[i]);
+        if (m === null)
+            continue;
+        if (m[1] !== "")
+            paths.push(m[1]);
+        else if (fields[i + 2] !== undefined) {
+            paths.push(fields[i + 2]); // a rename: the empty path is followed by its old and new path
+            i += 2;
+        }
+    }
+    return paths;
+}
+/** Put one file's section of a salvaged patch back into `dir`: by a three-way merge, which leaves
+ * conflict markers where both sides changed the same lines, else by direct application hunk by
+ * hunk. Returns the hunks that fit nowhere (git's `.rej` text, read and removed so it is never
+ * committed), or the whole section when git could place none of it; empty when all of it went
+ * back. */
+async function placeSalvagedFile(dir, file, section) {
+    const paths = await sectionPaths(dir, file).catch((err) => {
+        if (gitCouldNotStart(err))
+            throw err;
+        return [];
+    });
+    const label = paths.join(", ") || (/^diff --git a\/(.*?) b\//.exec(section)?.[1] ?? "a file");
+    if (await applied(dir, ["apply", "--3way", file]))
+        return [];
+    if (paths.length > 0 && (await git(dir, "--literal-pathspecs", "ls-files", "-u", "--", ...paths)) !== "")
+        return [];
+    // A deletion whose file the branch has already removed is done; there is nothing to hand back.
+    if (/^deleted file mode /m.test(section) && paths.length > 0 && paths.every((p) => !fs.existsSync(path.join(dir, p)))) {
+        return [];
+    }
+    if (await applied(dir, ["apply", "--reject", file]))
+        return [];
+    const rejected = [];
+    for (const p of paths) {
+        const rej = path.join(dir, `${p}.rej`);
+        if (!fs.existsSync(rej))
+            continue;
+        rejected.push({ path: p, diff: fs.readFileSync(rej, "utf8") });
+        fs.rmSync(rej, { force: true });
+    }
+    return rejected.length > 0 ? rejected : [{ path: label, diff: section }];
+}
+/** Run one `git apply` and say whether it succeeded; a git that could not start throws. */
+async function applied(dir, args) {
+    try {
+        await git(dir, ...args);
+        return true;
+    }
+    catch (err) {
+        if (gitCouldNotStart(err))
+            throw err;
+        return false;
+    }
+}

package/dist/src/git/slots-state.js

@@ -1,4 +1,3 @@
-// vocabulary: plain
 /** The persisted slot layout of the worktree pool (plans/worktree-pool.md): which
  * `.tumwater/worktrees/_slot-<n>` checkouts exist, who leases each, and which role each is pinned
  * for. Kept in its own module, apart from the pool's lease machinery, so the readers that run in
@@ -26,8 +25,8 @@ function withSlotsLock(root, fn) {
  * entries follows readJsonFile's no-data policy for the file as a whole: the good slots stay,
  * the reader and the operator view degrade instead of crashing. Each readable entry's known
  * fields are defaulted by readSlotRecord (a `lease` that is not a complete claim reads as no
- * lease, and pinnedFor/lastRole/lastReleasedAt as null), while any field it does not know
- * rides along so an update's read-modify-write still round-trips it. */
+ * lease, and pinnedFor/lastRole/lastReleasedAt/unsettledRun as null), while any field it does
+ * not know rides along so an update's read-modify-write still round-trips it. */
 export function readSlotsState(root) {
     const state = readJsonFile(slotsStatePath(root));
     if (state === null || !Array.isArray(state.slots))
@@ -46,7 +45,7 @@ export function readSlotsState(root) {
 function isSlotLease(value) {
     return (isJsonObject(value) &&
         typeof value.role === "string" &&
-        (value.purpose === "run" || value.purpose === "verify" || value.purpose === "tick" || value.purpose === "vet") && // vocabulary-ok: legacy value read from old files
+        (value.purpose === "run" || value.purpose === "verify" || value.purpose === "verify-check" || value.purpose === "tick" || value.purpose === "vet") && // vocabulary-ok: legacy value read from old files
         nonNegativeNumber(value.since, null) !== null &&
         nonNegativeNumber(value.pid, null) !== null);
 }
@@ -78,6 +77,7 @@ function readSlotRecord(slot) {
         pinnedAt: slot.pinnedAt === undefined ? undefined : finiteNumber(slot.pinnedAt, null),
         lastRole: typeof slot.lastRole === "string" ? canonicalRoleId(slot.lastRole) : null,
         lastReleasedAt: finiteNumber(slot.lastReleasedAt, null),
+        unsettledRun: typeof slot.unsettledRun === "string" ? canonicalRoleId(slot.unsettledRun) : null,
     };
 }
 function writeSlotsStateUnlocked(root, state) {
@@ -102,9 +102,9 @@ export function slotForDir(root, dir) {
 }
 /** The directory holding a role's checkout, resolved from other processes' point of view
  * (plans/worktree-pool.md, "Readers find a role's checkout"): a slot listed as leased by the role
- * for a tick, or pinned for the role, wins; otherwise the legacy `worktreePath` when it is a
+ * for a run, or pinned for the role, wins; otherwise the legacy `worktreePath` when it is a
  * usable worktree; otherwise null (the reader's "absent" state). Changes no behavior until role
- * ticks lease slots (part 4/5), because nothing writes those leases yet. */
+ * runs lease slots (part 4/5), because nothing writes those leases yet. */
 export async function roleWorktreeDir(root, role) {
     const slots = readSlotsState(root).slots;
     const leased = slots.find((slot) => slot.lease?.role === role && slot.lease.purpose === "run");