tumwater 0.1.3 → 0.2.0

package/dist/src/git/git.js

@@ -38,38 +38,30 @@ export function readBranchHead(root, branch) {
     catch {
         return null; // Neither store has it: the branch does not exist (or no repo state).
     }
-    const suffix = ` refs/heads/${branch}`;
-    for (const line of packed.split("\n")) {
-        if (!line.endsWith(suffix))
-            continue; // Skips comments, peel lines, and other refs.
-        const sha = line.slice(0, -suffix.length);
-        if (isSha(sha))
-            return sha;
-    }
-    return null;
+    return shaFromPackedRefs(packed, ` refs/heads/${branch}`) ?? null;
 }
 /** 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 lander, so the
+ * end-of-tick 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));
 }
 // ── Ref reads from files ───────────────────────────────────────────────────────────────────
 // The read-only probes below (isGitRepo, hasCommits, headOf, refSha, branchExists) each used to
-// spawn a `git rev-parse`. The harness asks them constantly: a landing alone re-reads HEAD a
-// dozen times, and the test suite, which process creation bounds (DEVELOPMENT.md), spawned
-// ~8,000 of them a run. Each probe now answers from the repository's files when the files
-// settle it POSITIVELY: a resolvable git dir, or a ref whose loose file or packed-refs line
-// names a SHA. Everything else spawns git exactly as before: a miss, a symref other than HEAD,
-// a name git's DWIM rules could read another way, a reftable repo, an environment that
-// redirects git (GIT_DIR and friends), or a repository another user owns, which git itself
-// refuses (safe.directory). A hit is the SHA `rev-parse --verify` prints. It resolves the name
-// and does not check that the object exists, and neither does this. The one negative answered
-// from files is a plain full `refs/…` name with no loose file and no packed-refs line
-// (refAbsentFromFiles): in a files-backend repository that is everywhere git looks.
+// spawn a `git rev-parse`. The harness asks them constantly: a merge alone re-reads HEAD a dozen
+// times, and the test suite, which process creation bounds (DEVELOPMENT.md), spawned ~8,000 of them
+// a run. Each probe now answers from the repository's files when the files settle it POSITIVELY: a
+// resolvable git dir, or a ref whose loose file or packed-refs line names a SHA. Everything else
+// spawns git exactly as before: a miss, a symref other than HEAD, a name git's DWIM rules could
+// read another way, a reftable repo, an environment that redirects git (GIT_DIR and friends), or a
+// repository another user owns, which git itself refuses (safe.directory). A hit is the SHA
+// `rev-parse --verify` prints. It resolves the name and does not check that the object exists, and
+// neither does this. The one negative answered from files is a plain full `refs/…` name with no
+// loose file and no packed-refs line (refAbsentFromFiles): in a files-backend repository that is
+// everywhere git looks.
 /** Environment variables that make git look somewhere other than the files `dir` holds. While
  * any is set, every probe spawns git. */
 const GIT_REDIRECT_ENV = ["GIT_DIR", "GIT_COMMON_DIR", "GIT_WORK_TREE", "GIT_NAMESPACE"];
@@ -120,6 +112,24 @@ function isPlainRefName(ref) {
         return false;
     return ref.split("/").every((part) => part !== "" && !part.startsWith(".") && !part.endsWith(".lock"));
 }
+/** The SHA a packed-refs line whose refname ends with `suffix` (e.g. " refs/heads/main")
+ * names, else null when no line matches. undefined when a line matches the refname but holds
+ * a non-SHA — the "the files say something git would read differently" signal storedRef's
+ * callers distinguish from a plain miss. Both packed-refs readers (readBranchHead and
+ * storedRef) scan the file this way: git writes every packed-refs line as ``<sha> <refname>``
+ * (or ``<sha> <refname>^{}`` peel lines), so skipping lines that do not end in the suffix and
+ * slicing that suffix off the first match is the whole format. */
+function shaFromPackedRefs(packed, suffix) {
+    for (const line of packed.split("\n")) {
+        if (!line.endsWith(suffix))
+            continue; // Skips the header, comments, peel lines and other refs.
+        const sha = line.slice(0, -suffix.length);
+        if (isSha(sha))
+            return sha;
+        return undefined;
+    }
+    return null;
+}
 /** The SHA a full ref name holds in `commondir`: its loose file (which wins in git too), else
  * its packed-refs line. null when neither has it, and undefined when the files hold something
  * git would read differently (a symref, unreadable content). */
@@ -139,14 +149,7 @@ function storedRef(commondir, ref) {
     catch (err) {
         return err.code === "ENOENT" ? null : undefined;
     }
-    const suffix = ` ${ref}`;
-    for (const line of packed.split("\n")) {
-        if (!line.endsWith(suffix))
-            continue; // Skips the header, peel lines and other refs.
-        const sha = line.slice(0, -suffix.length);
-        return isSha(sha) ? sha : undefined;
-    }
-    return null;
+    return shaFromPackedRefs(packed, ` ${ref}`);
 }
 /** The SHA `git rev-parse --verify <ref>` would print in `dir`, read from files, or undefined
  * when the files do not settle it (see the section comment): the caller then spawns git. `ref`
@@ -232,13 +235,24 @@ export async function hasCommits(root) {
 export async function headOf(cwd, ref) {
     return refShaFromFiles(cwd, ref) ?? git(cwd, "rev-parse", "--verify", ref);
 }
-/** Point `ref` at `sha`, creating the ref if needed (git update-ref). The landing pin of
+/** Point `ref` at `sha`, creating the ref if needed (git update-ref). The merge pin of
  * plans/merge-queue.md invariant 4 uses this to keep a committed sha reachable across the role
- * branch's reset-to-main. Returns false instead of throwing when git fails — the caller then
- * keeps the commit on its branch (no reset) so leftover recovery can still reach it. */
+ * branch's reset-to-main. Returns false instead of throwing when git fails — the caller then keeps
+ * the commit on its branch (no reset) so leftover recovery can still reach it. */
 export async function setRef(root, ref, sha) {
     return (await gitTry(root, "update-ref", ref, sha)) !== null;
 }
+/** Every ref under `prefix` with the sha it names (git for-each-ref). Empty when none match. */
+export async function refsUnder(root, prefix) {
+    return gitLines(await gitTry(root, "for-each-ref", "--format=%(refname) %(objectname)", prefix)).map((line) => {
+        const [ref, sha] = line.split(" ");
+        return { ref, sha };
+    });
+}
+/** 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);
+}
 /** Delete `ref`; a no-op when it is already gone (idempotent cleanup on terminal outcomes). */
 export async function deleteRef(root, ref) {
     await gitTry(root, "update-ref", "-d", ref);
@@ -253,7 +267,7 @@ export async function refSha(root, ref) {
     return gitTry(root, "rev-parse", "--verify", ref);
 }
 /** True when `sha` is already contained in `branch` (git merge-base --is-ancestor; equality counts
- * as contained). The leftover-recovery entry condition uses this to tell a stale pin — landed but
+ * as contained). The leftover-recovery entry condition uses this to tell a stale pin — merged but
  * not yet un-pinned by a crash between the ff and the ref deletion — from real work. */
 export async function isMergedInto(root, sha, branch) {
     return (await gitTry(root, "merge-base", "--is-ancestor", sha, branch)) !== null;
@@ -304,13 +318,12 @@ export async function branchExists(root, branch) {
         return false;
     return (await gitTry(root, "rev-parse", "--verify", ref)) !== 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 commits yet). The one home of the "diff against the merge-base, not
- * main's tip" policy shared by falseFixReason's BUGS.md base read and
- * backlogStructureReason's per-file base reads — both judge a backlog edit against the
- * tree the change builds on, so a stacked batch's earlier landing cannot make an
- * Open→Fixed restoration compare as already done (BUGS.md 2026-09-23). `rev` is the commit
+/** 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
+ * commits yet). The one home of the "diff against the merge-base, not main's tip" policy shared by
+ * falseFixReason's BUGS.md base read and backlogStructureReason's per-file base reads — both judge
+ * a backlog edit against the tree the change builds on, so a stacked batch's earlier merge cannot
+ * make an Open→Fixed restoration compare as already done (BUGS.md 2026-09-23). `rev` is the commit
  * whose merge-base with main is wanted; it defaults to the worktree's HEAD, and the rejected
  * change's revision interdiff asks for its own prior commit instead (git-diff.ts). */
 export async function changeBaseRev(wt, mainBranch, rev = "HEAD") {
@@ -395,7 +408,7 @@ export async function currentBranch(root) {
     const fromFile = currentBranchFromHeadFile(root);
     return fromFile !== undefined ? fromFile : gitTry(root, "symbolic-ref", "--short", "HEAD");
 }
-/** The branch a read-only surface treats as the fleet's main: a configured `baseBranch` wins (`run
+/** The branch a read-only surface treats as the team's main: a configured `baseBranch` wins (`run
  * --branch` is per-invocation and invisible to a later query), else whatever the primary checkout
  * has checked out, else the literal "main". change/change-data.ts's collectRoleChange (async, via
  * currentBranch) and status-polls's mainCheckForPoll (sync, via currentBranchFromHeadFile — a
@@ -412,12 +425,12 @@ export async function isDirty(cwd) {
     const out = await git(cwd, "status", "--porcelain");
     return out.length > 0;
 }
-/** Stage ONLY the given repo-relative paths, commit them with `message`, then discard every
- * other change in the worktree — tracked edits via reset --hard HEAD (the committed content is
- * safe at 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
- * lands while its half-done code work does not. */
+/** Stage ONLY the given repo-relative paths, commit them with `message`, then discard every other
+ * change in the worktree — tracked edits via reset --hard HEAD (the committed content is safe at
+ * 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. */
 export async function commitPathsAndDiscardRest(wt, message, paths) {
     if (paths.length === 0)
         return null;
@@ -432,10 +445,10 @@ export async function commitPathsAndDiscardRest(wt, message, paths) {
     await git(wt, "clean", "-fd");
     return headOf(wt, "HEAD");
 }
-/** Commit subjects landed on `mainBranch` since `sinceHead`, newest first — the range is
- * exclusive of its base, so a head that is an ancestor of main yields exactly what moved past
- * it (empty when nothing has). Null when the range cannot be resolved (unknown head, not a
- * repo), so callers fall back conservatively. */
+/** Commit subjects merged on `mainBranch` since `sinceHead`, newest first — the range is exclusive
+ * of its base, so a head that is an ancestor of main yields exactly what moved past it (empty when
+ * nothing has). Null when the range cannot be resolved (unknown head, not a repo), so callers fall
+ * back conservatively. */
 export async function subjectsBetween(root, sinceHead, mainBranch) {
     const out = await gitTry(root, "log", "--format=%s", `${sinceHead}..${mainBranch}`);
     if (out === null)
@@ -446,10 +459,17 @@ export async function subjectsBetween(root, sinceHead, mainBranch) {
 export async function commitMessage(cwd, sha) {
     return gitTry(cwd, "log", "-1", "--format=%B", sha);
 }
+/** The number of commits in a `A..B` range: `git rev-list --count <range>` parsed as an
+ * integer. The one home of the count idiom, so every surface that measures how far one ref
+ * is ahead of another (a branch over main, main over a build) reads identically instead of
+ * re-spelling the git call. Throws through `git` on failure; callers that must tolerate an
+ * unknown ref use `gitTry` directly (as build-info's buildStaleness does for its sentinel). */
+export async function countCommitsInRange(cwd, range) {
+    return Number.parseInt(await git(cwd, "rev-list", "--count", range), 10);
+}
 /** Commits ahead of main on the worktree's branch. */
 export async function aheadOfMain(wt, mainBranch) {
-    const out = await git(wt, "rev-list", "--count", `${mainBranch}..HEAD`);
-    return Number.parseInt(out, 10);
+    return countCommitsInRange(wt, `${mainBranch}..HEAD`);
 }
 /** 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
@@ -464,8 +484,8 @@ export async function aheadOfMain(wt, mainBranch) {
  * as "no match", never an error. */
 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 landing's approval check.
+        // 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 });
         if (diff === "")
             return null;
@@ -481,13 +501,13 @@ export async function patchId(wt, base, head) {
     }
 }
 /** Undo commits the agent made on top of `base` (INV-H1): a soft reset keeps their content as
- * staged edits, so the harness's own commitAll lands it as one commit. Returns how many commits
- * were folded — 0 when HEAD never moved. A count of 0 from rev-list with HEAD moved means the
- * agent amended or reset away from `base`; that still folds, and counts as 1. */
+ * staged edits, so the harness's own commitAll records it as one commit. Returns how many commits
+ * were folded — 0 when HEAD never moved. A count of 0 from rev-list with HEAD moved means the agent
+ * amended or reset away from `base`; that still folds, and counts as 1. */
 export async function foldCommitsSince(wt, base) {
     if ((await headOf(wt, "HEAD")) === base)
         return 0;
-    const count = Number(await git(wt, "rev-list", "--count", `${base}..HEAD`));
+    const count = await countCommitsInRange(wt, `${base}..HEAD`);
     await git(wt, "reset", "--soft", base);
     return count > 0 ? count : 1;
 }

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

@@ -1,3 +1,4 @@
+// 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
@@ -11,6 +12,7 @@ import { finiteNumber, isJsonObject, nonNegativeNumber } from "../files/json-obj
 import { withStateLock } from "../concurrency/lock.js";
 import { slotsLockPath, slotsStatePath, worktreePath } from "../paths.js";
 import { isUsableWorktree } from "./worktree.js";
+import { canonicalRoleId } from "../roles/legacy-role-ids.js";
 /** Run `fn` holding the cross-process slots lock. withStateLock creates the `.tumwater/state/`
  * parent first, since a reader or `retire` may run before any state write has made it. */
 function withSlotsLock(root, fn) {
@@ -44,10 +46,17 @@ export function readSlotsState(root) {
 function isSlotLease(value) {
     return (isJsonObject(value) &&
         typeof value.role === "string" &&
-        (value.purpose === "tick" || value.purpose === "vet") &&
+        (value.purpose === "run" || value.purpose === "verify" || value.purpose === "tick" || value.purpose === "vet") && // vocabulary-ok: legacy value read from old files
         nonNegativeNumber(value.since, null) !== null &&
         nonNegativeNumber(value.pid, null) !== null);
 }
+/** A lease an older build wrote carries the pre-rename purpose names; read them as
+ * `run`/`verify`. */
+function readSlotLease(lease) {
+    const l = lease;
+    const purpose = l.purpose === "tick" ? "run" : l.purpose === "vet" ? "verify" : l.purpose; // vocabulary-ok: legacy value read from old files
+    return { ...l, role: canonicalRoleId(l.role), purpose };
+}
 /** Coerce one persisted entry into a SlotRecord, defaulting the known fields a hand edit or an
  * older writer may omit. Each field is the value or its empty form, so a record missing
  * `pinnedFor` is not frozen as permanently pinned (chooseSlot treats `!== null` as pinned),
@@ -63,11 +72,11 @@ function readSlotRecord(slot) {
     return {
         ...slot,
         dir: slot.dir,
-        lease: isSlotLease(slot.lease) ? slot.lease : null,
-        pinnedFor: typeof slot.pinnedFor === "string" ? slot.pinnedFor : null,
+        lease: isSlotLease(slot.lease) ? readSlotLease(slot.lease) : null,
+        pinnedFor: typeof slot.pinnedFor === "string" ? canonicalRoleId(slot.pinnedFor) : null,
         // Absent stays absent (an older writer's shape is preserved); present-but-foreign is null.
         pinnedAt: slot.pinnedAt === undefined ? undefined : finiteNumber(slot.pinnedAt, null),
-        lastRole: typeof slot.lastRole === "string" ? slot.lastRole : null,
+        lastRole: typeof slot.lastRole === "string" ? canonicalRoleId(slot.lastRole) : null,
         lastReleasedAt: finiteNumber(slot.lastReleasedAt, null),
     };
 }
@@ -98,7 +107,7 @@ export function slotForDir(root, dir) {
  * ticks 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 === "tick");
+    const leased = slots.find((slot) => slot.lease?.role === role && slot.lease.purpose === "run");
     if (leased !== undefined)
         return leased.dir;
     const pinned = slots.find((slot) => slot.pinnedFor === role);

package/dist/src/git/worktree-pool.js

@@ -1,14 +1,15 @@
-/** The worktree pool's lease machinery (plans/worktree-pool.md, "Leases"; part 2a/5): a fixed
- * set of `.tumwater/worktrees/_slot-<n>` checkouts that ticks and vets lease and switch commits
- * in place, instead of keeping one `_land-<role>` checkout per role. The persisted layout and
- * its cross-process lock live in slots-state.ts, which other processes (`tumwater diff`,
- * `retire`) also read; this module owns choosing a slot, holding it through the disk-floor
- * registry, and handing it back. Nothing leases a slot yet — part 4/5 wires the loops to it.
+// vocabulary: plain
+/** The worktree pool's lease machinery (plans/worktree-pool.md, "Leases"; part 2a/5): a fixed set
+ * of `.tumwater/worktrees/_slot-<n>` checkouts that ticks and verifies lease and switch commits in
+ * place, instead of keeping one `_land-<role>` checkout per role. The persisted layout and its
+ * cross-process lock live in slots-state.ts, which other processes (`tumwater diff`, `retire`) also
+ * read; this module owns choosing a slot, holding it through the disk-floor registry, and handing
+ * it back. Nothing leases a slot yet — part 4/5 wires the loops to it.
  *
- * The lease decision is synchronous: `updateSlotsState` writes slots.json under the slots lock,
- * and one Node process runs every tick and landing, so two concurrent `leaseSlot` calls claim
- * distinct free slots and a call with none free registers an in-process waiter. A release wakes
- * the waiters, which re-decide; `signal` aborts a waiter. */
+ * The lease decision is synchronous: `updateSlotsState` writes slots.json under the slots lock, and
+ * one Node process runs every tick and merge, so two concurrent `leaseSlot` calls claim distinct
+ * free slots and a call with none free registers an in-process waiter. A release wakes the waiters,
+ * which re-decide; `signal` aborts a waiter. */
 import path from "node:path";
 import { loadConfig, slotCount } from "../config/config.js";
 import { worktreesDir, slotWorktreePath } from "../paths.js";
@@ -17,9 +18,10 @@ import { DIRECTOR_ROLE } from "../roles/roles.js";
 import { readSlotsState, slotForDir, updateSlotsState } from "./slots-state.js";
 import { beginWorktreeUse } from "./worktree-use.js";
 import { ensureDetachedWorktree, removeWorktreeDir } from "./worktree.js";
-import { logEventBestEffort, warnEventBestEffort } from "../events/events.js";
+import { logEventBestEffort, warnEventBestEffort, TUMWATER_SOURCE } from "../events/events.js";
 import { errorMessage } from "../text/text.js";
 import { subdirectoryNames } from "../files/files.js";
+import { dropProviderLeaseKey } from "../concurrency/provider-lease.js";
 /** In-process waiters per root, woken when any slot is released. Keyed by resolved root so two
  * roots never wake each other. */
 const waiters = new Map();
@@ -27,7 +29,7 @@ function rootKey(root) {
     return path.resolve(root);
 }
 function abortError() {
-    const err = new Error("slot lease aborted before a slot was free");
+    const err = new Error("the workspace request was stopped before one was free");
     err.name = "AbortError";
     return err;
 }
@@ -146,7 +148,7 @@ function logSlotWait(root, role, purpose, waitedMs) {
         return;
     const slots = readSlotsState(root).slots;
     logEventBestEffort(root, {
-        loop: role,
+        source: role,
         type: "slot_wait",
         role,
         purpose,
@@ -177,6 +179,11 @@ async function acquire(root, role, purpose, signal, slotBudget) {
             logSlotWait(root, role, purpose, Date.now() - startedAt);
             return chosen;
         }
+        // The pool-slot wait rule (plans/provider-concurrency.md §5 "No deadlock"): a lease never holds
+        // a provider key while it waits for a pool slot. Drop the calling lease's key (which never
+        // waits) before parking here, so this tick or verify holds no provider slot whose in-use a
+        // re-key waiter is waiting to drain; the next run re-takes the key as an ordinary re-key.
+        await dropProviderLeaseKey();
         const waiter = registerWaiter(root);
         try {
             await raceAbort(waiter.promise, signal);
@@ -258,7 +265,7 @@ export async function removeDroppedSlots(root, dirs, remove = removeWorktreeDir)
             await remove(root, dir);
         }
         catch (err) {
-            warnEventBestEffort(root, "harness", `could not remove idle worktree slot ${dir}: ${errorMessage(err)}`);
+            warnEventBestEffort(root, TUMWATER_SOURCE, `could not remove idle workspace ${dir}: ${errorMessage(err)}`);
         }
     }
 }
@@ -276,7 +283,7 @@ export async function removeDroppedSlots(root, dirs, remove = removeWorktreeDir)
  * are already updated, so a leaked directory is only a leak the next prune collects. */
 export async function retireLegacyRoleWorktrees(root, configured) {
     const dir = worktreesDir(root);
-    // A missing worktrees dir (a fleet that has not started) yields no names to migrate; the pin
+    // A missing worktrees dir (a team that has not started) yields no names to migrate; the pin
     // retirement pass below still runs over whatever slots.json holds.
     const names = subdirectoryNames(dir, (name) => name !== DIRECTOR_ROLE && !name.startsWith("_"));
     const configuredSet = new Set(configured);
@@ -289,7 +296,7 @@ export async function retireLegacyRoleWorktrees(root, configured) {
             const ownRecord = state.slots.find((slot) => slot.dir === legacyDir);
             if (resumable && configuredSet.has(role)) {
                 const owned = state.slots.find((slot) => slot.pinnedFor === role ||
-                    (slot.lease?.role === role && slot.lease.purpose === "tick"));
+                    (slot.lease?.role === role && slot.lease.purpose === "run"));
                 if (owned !== undefined) {
                     // The resume happens in the owned slot: drop the legacy record and remove its dir.
                     if (owned.dir !== legacyDir) {
@@ -343,7 +350,7 @@ export async function retireLegacyRoleWorktrees(root, configured) {
             await removeWorktreeDir(root, victim);
         }
         catch (err) {
-            warnEventBestEffort(root, "harness", `could not remove legacy role worktree ${victim}: ${errorMessage(err)}`);
+            warnEventBestEffort(root, TUMWATER_SOURCE, `could not remove legacy role workspace ${victim}: ${errorMessage(err)}`);
         }
     }
 }
@@ -363,7 +370,7 @@ export async function leaseSlot(root, options) {
             useRelease();
         }
         catch (err) {
-            warnEventBestEffort(root, "harness", `could not record use release for ${path.basename(dir)}: ${errorMessage(err)}`);
+            warnEventBestEffort(root, TUMWATER_SOURCE, `could not record use release for ${path.basename(dir)}: ${errorMessage(err)}`);
         }
     };
     if (!preserved) {

package/dist/src/git/worktree-use.js

@@ -1,8 +1,9 @@
-/** The worktree-use registry (plans/disk-floor.md, "Reclaiming build outputs", part 2/4):
- * which harness worktrees are in use right now, and when each was last used. The orchestrator
- * is the one process that runs ticks and landings, so a plain in-process map is enough for the
- * "in use" half; the "last used" half is persisted to `.tumwater/state/worktree-use.json` so
- * least-recently-used reclaim ordering survives a restart.
+// vocabulary: plain
+/** The worktree-use registry (plans/disk-floor.md, "Reclaiming build outputs", part 2/4): which
+ * harness worktrees are in use right now, and when each was last used. The orchestrator is the one
+ * process that runs ticks and merges, so a plain in-process map is enough for the "in use" half;
+ * the "last used" half is persisted to `.tumwater/state/worktree-use.json` so least-recently-used
+ * reclaim ordering survives a restart.
  *
  * A reclaim claims a worktree before it cleans it, so a `useWorktree` that arrives mid-clean
  * waits for the clean to finish instead of starting work in a half-emptied tree. Every wrapped
@@ -12,7 +13,7 @@ import path from "node:path";
 import { readJsonFile, writeJsonAtomic } from "../files/json-files.js";
 import { finiteNumber, isJsonObject } from "../files/json-object.js";
 import { withStateLock } from "../concurrency/lock.js";
-import { warnEventBestEffort } from "../events/events.js";
+import { warnEventBestEffort, TUMWATER_SOURCE } from "../events/events.js";
 import { errorMessage } from "../text/text.js";
 import { worktreeUseLockPath, worktreeUsePath } from "../paths.js";
 /** In-process state, keyed by the resolved directory so two roots' same-named worktrees never
@@ -37,7 +38,7 @@ function liveEntry(dir) {
  * produces one). An Infinity `lastUsedAt` would sort a worktree as used forever —
  * `now - Infinity` is below any idle window — so the worktree could never be idle-reclaimed;
  * an Infinity `reclaimedAt` would read as reclaimed after every use, blocking the same
- * reclaim. Either reads as absent, the same finiteNumber rule fleet-state.ts's and
+ * reclaim. Either reads as absent, the same finiteNumber rule team-state.ts's and
  * operator-requests.ts's persisted deadlines read by. */
 function readWorktreeRecord(value) {
     if (!isJsonObject(value))
@@ -83,19 +84,19 @@ export function updateWorktreeUse(root, change) {
         return registry;
     });
 }
-/** `updateWorktreeUse`, but best-effort: the durable registry only orders reclaim (see the
- * module doc), so a write that fails — the lock times out behind a CLI `tumwater reclaim`, the
- * state volume is full — is warned and dropped rather than thrown. Both release paths use it:
+/** `updateWorktreeUse`, but best-effort: the durable registry only orders reclaim (see the module
+ * doc), so a write that fails — the lock times out behind a CLI `tumwater reclaim`, the state
+ * volume is full — is warned and dropped rather than thrown. Both release paths use it:
  * `beginWorktreeUse`'s release and `releaseReclaim`, the latter in a `finally` after a reclaim.
- * Their bookkeeping must not become the caller's failure — a throw there would mask a
- * successful tick, landing, or clean with a registry error. The in-process `uses`/`reclaiming`
- * state is updated before this runs, so only reclaim ordering degrades. */
+ * Their bookkeeping must not become the caller's failure — a throw there would mask a successful
+ * tick, merge, or clean with a registry error. The in-process `uses`/`reclaiming` state is updated
+ * before this runs, so only reclaim ordering degrades. */
 function updateWorktreeUseBestEffort(root, change) {
     try {
         updateWorktreeUse(root, change);
     }
     catch (err) {
-        warnEventBestEffort(root, "harness", `could not update the worktree-use registry: ${errorMessage(err)}`);
+        warnEventBestEffort(root, TUMWATER_SOURCE, `could not update the worktree-use registry: ${errorMessage(err)}`);
     }
 }
 /** True while a `useWorktree` body holds this worktree. */

package/dist/src/git/worktree.js

@@ -53,13 +53,13 @@ function pruneStaleBuildDir(wt) {
 const setupQueues = new Map();
 /** Run `setup` — a clear-and-add of one worktree — after every earlier setup for the same
  * repository has finished. `git worktree add` creates the new registration's directory under
- * .git/worktrees a moment before it writes the `locked` file that shields it from prune, and a
- * `git worktree prune` landing in between deletes the registration: the add then dies with
- * "could not open '.git/worktrees/<name>/locked' for writing". The landing pipeline vets its
- * changes concurrently, each vet ensuring its own leased pool slot, so two vets' clear-and-add
- * steps did interleave — and the loser's vet ended in a terminal "error" that dropped its queue
- * entry. Serializing the harness's own setups per repository closes that; the usable-worktree
- * fast path never takes the queue. */
+ * .git/worktrees a moment before it writes the `locked` file that shields it from prune, and a `git
+ * worktree prune` running in between deletes the registration: the add then dies with "could not
+ * open '.git/worktrees/<name>/locked' for writing". The merge pipeline verifies its changes
+ * concurrently, each verify ensuring its own leased pool slot, so two verifies' clear-and-add steps
+ * did interleave — and the loser's verify ended in a terminal "error" that dropped its queue entry.
+ * Serializing the harness's own setups per repository closes that; the usable-worktree fast path
+ * never takes the queue. */
 async function serializeSetup(root, setup) {
     const key = path.resolve(root);
     const run = (setupQueues.get(key) ?? Promise.resolve()).then(setup);
@@ -73,11 +73,11 @@ async function serializeSetup(root, setup) {
             setupQueues.delete(key);
     }
 }
-/** Ensure a persistent worktree + branch exists for a role. Returns the worktree path.
- * Self-heals when the directory exists but is no longer a usable worktree: it removes and
- * re-adds the directory instead of failing every tick (see clearStaleWorktree). Since the
- * worktree pool landed (plans/worktree-pool.md, "Role ticks lease slots"), this serves the
- * director only; every other role leases a pooled `_slot-<n>` via leaseSlot instead. */
+/** Ensure a persistent worktree + branch exists for a role. Returns the worktree path. Self-heals
+ * when the directory exists but is no longer a usable worktree: it removes and re-adds the
+ * directory instead of failing every tick (see clearStaleWorktree). Since the worktree pool merged
+ * (plans/worktree-pool.md, "Role ticks lease slots"), this serves the director only; every other
+ * role leases a pooled `_slot-<n>` via leaseSlot instead. */
 export async function ensureWorktree(root, role, mainBranch) {
     const wt = worktreePath(root, role);
     const branch = branchName(role);
@@ -130,14 +130,14 @@ export async function removeWorktreeDir(root, dir) {
 export async function removeWorktree(root, role) {
     await removeWorktreeDir(root, worktreePath(root, role));
 }
-/** Remove lander checkouts left by a pre-pool build (`_land-<role>`): the pool's ticks keep
- * their commit on the role branch and a queued landing re-vets from its pinned ref, so the
- * checkout holds nothing to keep. Called once at orchestrator startup, before any tick; each
- * removal goes through removeWorktreeDir (force `worktree remove`, with the shared
- * dead-registration fallback), then one prune registers the vanished checkouts. */
+/** Remove the `_land-<role>` checkouts left by a pre-pool build: the pool's ticks keep their
+ * commit on the role branch and a queued merge re-verifies from its pinned ref, so the checkout
+ * holds nothing to keep. Called once at orchestrator startup, before any tick; each removal goes
+ * through removeWorktreeDir (force `worktree remove`, with the shared dead-registration fallback),
+ * then one prune registers the vanished checkouts. */
 export async function removeLegacyLandWorktrees(root) {
     const dir = worktreesDir(root);
-    // A missing worktrees dir (a fleet that has not started) yields no names to remove.
+    // A missing worktrees dir (a team that has not started) yields no names to remove.
     const names = subdirectoryNames(dir, (name) => name.startsWith("_land-"));
     for (const name of names)
         await removeWorktreeDir(root, path.join(dir, name));

package/dist/src/gui/gui-args.js

@@ -16,9 +16,9 @@ import { queueFileNameProblem } from "../inbox/inbox-cancel.js";
 import { DIRECTOR_ROLE } from "../roles/roles.js";
 import { gotSuffix, parseNonNegativeInt, parsePositiveInt } from "../text/text.js";
 import { typoSuffix } from "../text/suggest.js";
-import { sendJson } from "./http-body.js";
+import { badRequest, sendJson } from "./http-body.js";
 /** The role ids a loop-targeting endpoint accepts: when tumwater.json parses, catalog +
- * customLoops (knownRoleIds); a transiently broken file falls back to the built-in catalog
+ * customRoles (knownRoleIds); a transiently broken file falls back to the built-in catalog
  * rather than refusing every id — the rule config.knownRoleIdsCached owns. Shared by
  * /api/transcript and the two operator endpoints so their validation and 400 wording cannot
  * drift. */
@@ -41,13 +41,11 @@ export function rejectBadRole(root, res, role, allowMissing = false) {
         return false;
     const validIds = validRoleIds(root);
     if (role === undefined || role === null) {
-        sendJson(res, 400, { error: `role required (valid ids: ${validIds.join(", ")})` });
+        badRequest(res, `role required (valid ids: ${validIds.join(", ")})`);
         return true;
     }
     if (typeof role !== "string" || !validIds.includes(role)) {
-        sendJson(res, 400, {
-            error: `unknown role ${JSON.stringify(role)} (valid ids: ${validIds.join(", ")})${typeof role === "string" ? typoSuffix(role, validIds) : ""}`,
-        });
+        badRequest(res, `unknown role ${JSON.stringify(role)} (valid ids: ${validIds.join(", ")})${typeof role === "string" ? typoSuffix(role, validIds) : ""}`);
         return true;
     }
     return false;
@@ -61,7 +59,7 @@ export function rejectBadQueueFileName(res, name) {
     const problem = queueFileNameProblem(name);
     if (problem === null)
         return false;
-    sendJson(res, 400, { error: problem });
+    badRequest(res, problem);
     return true;
 }
 /** Read an integer query parameter with the GUI's established discipline for an explicit
@@ -77,7 +75,7 @@ export function intQuery(q, res, name, kind, fallback) {
     if (raw === null) {
         if (fallback !== undefined)
             return fallback;
-        sendJson(res, 400, { error: `${name} required` });
+        badRequest(res, `${name} required`);
         return null;
     }
     const parsed = kind === "positive" ? parsePositiveInt(raw) : parseNonNegativeInt(raw);
@@ -113,12 +111,12 @@ export function requirePromptText(res, body, role = DIRECTOR_ROLE) {
         return null;
     }
     if (!text.trim()) {
-        sendJson(res, 400, { error: "text required" });
+        badRequest(res, "text required");
         return null;
     }
     const tooLong = promptLengthProblem(text, role);
     if (tooLong) {
-        sendJson(res, 400, { error: tooLong });
+        badRequest(res, tooLong);
         return null;
     }
     return text;
@@ -137,7 +135,7 @@ export function sinceMsQuery(q, res, maxMs, overCap) {
     if (sinceMs === null)
         return null;
     if (sinceMs > maxMs) {
-        sendJson(res, 400, { error: overCap(sinceMs) });
+        badRequest(res, overCap(sinceMs));
         return null;
     }
     return sinceMs;
@@ -151,9 +149,7 @@ export function sinceMsQuery(q, res, maxMs, overCap) {
 export function requireConfigKey(res, body) {
     const key = body.key;
     if (typeof key !== "string" || !EDITABLE_CONFIG_KEYS.includes(key)) {
-        sendJson(res, 400, {
-            error: `key must be one of ${EDITABLE_CONFIG_KEYS.join(", ")}${key === undefined ? "" : gotSuffix(key)}`,
-        });
+        badRequest(res, `key must be one of ${EDITABLE_CONFIG_KEYS.join(", ")}${key === undefined ? "" : gotSuffix(key)}${typeof key === "string" ? typoSuffix(key, EDITABLE_CONFIG_KEYS) : ""}`);
         return null;
     }
     return key;