tumwater 0.2.0 → 0.3.0

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

@@ -1,24 +1,25 @@
-// 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
+ * of `.tumwater/worktrees/_slot-<n>` checkouts that runs 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.
+ * it back. Since part 4/5 landed, a role's run (runner-run.ts) and a verify (merge-batch.ts's
+ * verifyRequest) both acquire one through leaseSlot.
  *
  * 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
+ * one Node process runs every run 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";
-import { loadLoopState } from "../loop/loop-state.js";
+import { loadRunnerState } from "../runner/runner-state-load.js";
 import { DIRECTOR_ROLE } from "../roles/roles.js";
 import { readSlotsState, slotForDir, updateSlotsState } from "./slots-state.js";
+import { salvageSlotLeftovers } from "./slot-salvage.js";
 import { beginWorktreeUse } from "./worktree-use.js";
 import { ensureDetachedWorktree, removeWorktreeDir } from "./worktree.js";
-import { logEventBestEffort, warnEventBestEffort, TUMWATER_SOURCE } from "../events/events.js";
+import { logEventBestEffort, warnEventBestEffort, tryOrWarn, 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";
@@ -84,11 +85,16 @@ function raceAbort(wait, signal) {
     });
 }
 /** Clear leases owned by any process other than this one: their runs are dead (design "Leases").
- * Pins are kept, and the freed slots become candidates for the current claim. */
+ * Pins are kept, and the freed slots become candidates for the current claim. A dead lease never
+ * released, so its role is recorded as the slot's last holder here, and a dead run as unsettled:
+ * whatever it left in the slot is that role's unfinished work (slot-salvage.ts). */
 function clearDeadLeases(state, pid) {
     for (const slot of state.slots) {
-        if (slot.lease !== null && slot.lease.pid !== pid)
-            slot.lease = null;
+        if (slot.lease === null || slot.lease.pid === pid)
+            continue;
+        slot.lastRole = slot.lease.role;
+        slot.unsettledRun = slot.lease.purpose === "run" ? slot.lease.role : null;
+        slot.lease = null;
     }
 }
 function claim(slot, role, purpose, now, pid) {
@@ -107,7 +113,9 @@ function mostRecentlyReleased(slots) {
 function chooseSlot(root, state, role, purpose, count, now, pid) {
     clearDeadLeases(state, pid);
     const free = state.slots.filter((slot) => slot.lease === null);
-    const eligible = free.filter((slot) => slot.pinnedFor === null || slot.pinnedFor === role);
+    // A check slot is a scratch checkout: it never takes a slot pinned for any role, the leasing
+    // role's own included (that pin holds the author's resumable work).
+    const eligible = free.filter((slot) => purpose === "verify-check" ? slot.pinnedFor === null : slot.pinnedFor === null || slot.pinnedFor === role);
     const pinned = eligible.find((slot) => slot.pinnedFor === role);
     if (pinned !== undefined)
         return claim(pinned, role, purpose, now, pid);
@@ -159,15 +167,23 @@ function logSlotWait(root, role, purpose, waitedMs) {
 }
 function tryClaim(root, role, purpose, count) {
     let chosen = null;
+    const key = rootKey(root);
+    const unsaved = unsavedReleases.get(key);
     updateSlotsState(root, (state) => {
+        for (const slot of state.slots) {
+            if (unsaved?.has(slot.dir) && slot.lease?.pid === process.pid)
+                slot.lease = null;
+        }
         chosen = chooseSlot(root, state, role, purpose, count, Date.now(), process.pid);
     });
+    // The write landed, so the reclaim of every unsaved release is on disk.
+    unsavedReleases.delete(key);
     return chosen;
 }
 async function acquire(root, role, purpose, signal, slotBudget) {
     // The caller's live budget when given; else liveCount's tolerance — a broken or missing
     // tumwater.json degrades to the default budget rather than erroring the lease with a raw
-    // load failure (2026-10-08: a mid-run broken config errored every tick via this read even
+    // load failure (2026-10-08: a mid-run broken config errored every run via this read even
     // while the orchestrator held last-known-good).
     const count = slotBudget ?? liveCount(root);
     const startedAt = Date.now();
@@ -181,7 +197,7 @@ async function acquire(root, role, purpose, signal, slotBudget) {
         }
         // 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
+        // waits) before parking here, so this run 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);
@@ -194,6 +210,15 @@ async function acquire(root, role, purpose, signal, slotBudget) {
         }
     }
 }
+/** The pool's live state for observers (status, TUI, dashboard): slots leased by this process out
+ * of the configured budget, and the leases waiting for one. A lease held by another pid is dead
+ * (see `SlotLease`), so it is not counted. `wakeWaiters` empties the waiter set before woken
+ * waiters re-register, so `waiting` can read low for one turn; observers poll, so the next poll
+ * corrects it. */
+export function slotPoolSnapshot(root) {
+    const leased = readSlotsState(root).slots.filter((s) => s.lease !== null && s.lease.pid === process.pid).length;
+    return { leased, limit: liveCount(root), waiting: waiters.get(rootKey(root))?.size ?? 0 };
+}
 /** The live slot budget, or an unbounded one when the config is unreadable: an invalid config
  * must not stop a held slot from being freed. */
 function liveCount(root) {
@@ -210,12 +235,33 @@ function liveCount(root) {
 function isCanonicalSlotDir(dir) {
     return /^_slot-\d+$/.test(path.basename(dir));
 }
-/** Free `dir` in slots.json, record `lastRole`/`lastReleasedAt`, and return the idle unpinned
- * slot dirs to remove because the live slot budget shrank below them (oldest-released first).
- * `pin` keeps the slot pinned for `role`; otherwise a pin this role held is cleared. A
- * non-canonical (migrated legacy) slot is dropped the moment it is unpinned, so the one resume
- * it was kept for runs in it and the dir is removed on that first release. */
-function releaseSlot(root, dir, role, count, pin) {
+/** Slot dirs per root whose release write to slots.json failed in this process; the next claim
+ * clears their stale lease. */
+const unsavedReleases = new Map();
+/** `releaseSlot` that never throws: a failed slots.json write (ENOSPC, EACCES, a lock timeout)
+ * warns and remembers the slot so the next `tryClaim` here reclaims it, instead of masking the
+ * caller's own outcome and leaving the slot leased by this live pid. The pin and `lastRole` the
+ * failed release would have recorded are not replayed; a lost pin only means the next resume
+ * gets a fresh checkout. */
+function freeSlot(root, dir, role, count, pin, unsettledRun = null) {
+    try {
+        return releaseSlot(root, dir, role, count, pin, unsettledRun);
+    }
+    catch (err) {
+        const key = rootKey(root);
+        const dirs = unsavedReleases.get(key) ?? new Set();
+        dirs.add(dir);
+        unsavedReleases.set(key, dirs);
+        warnEventBestEffort(root, TUMWATER_SOURCE, `could not free slot ${path.basename(dir)}: ${errorMessage(err)}; the next lease reclaims it`);
+        return [];
+    }
+}
+/** Free `dir` in slots.json, record `lastRole`/`lastReleasedAt`/`unsettledRun`, and return the
+ * idle unpinned slot dirs to remove because the live slot budget shrank below them
+ * (oldest-released first). `pin` keeps the slot pinned for `role`; otherwise a pin this role held
+ * is cleared. A non-canonical (migrated legacy) slot is dropped the moment it is unpinned, so the
+ * one resume it was kept for runs in it and the dir is removed on that first release. */
+function releaseSlot(root, dir, role, count, pin, unsettledRun) {
     const toRemove = [];
     updateSlotsState(root, (state) => {
         const slot = state.slots.find((s) => s.dir === dir);
@@ -223,6 +269,7 @@ function releaseSlot(root, dir, role, count, pin) {
             slot.lease = null;
             slot.lastRole = role;
             slot.lastReleasedAt = Date.now();
+            slot.unsettledRun = unsettledRun;
             if (pin) {
                 if (slot.pinnedFor !== role)
                     slot.pinnedAt = Date.now();
@@ -270,15 +317,15 @@ export async function removeDroppedSlots(root, dirs, remove = removeWorktreeDir)
     }
 }
 /** One-time startup migration (plans/worktree-pool.md "Legacy role worktrees", part 4c/5):
- * retire the pre-pool `.tumwater/worktrees/<role>` checkouts now that ticks lease pooled slots.
+ * retire the pre-pool `.tumwater/worktrees/<role>` checkouts now that runs lease pooled slots.
  * A resumable enabled role keeps its legacy dir as a pinned slot so its pending resume runs in
  * the same cwd; every other legacy dir is removed (its branch keeps any commit), and pins for
- * roles outside `configured` are cleared. `configured` is every loop id the config's roles
- * enable (`loopIds`), never a `--once --role` filter: a scoped run must leave the other roles'
+ * roles outside `configured` are cleared. `configured` is every role id the config's roles
+ * enable (`runnerIds`), never a `--once --role` filter: a scoped run must leave the other roles'
  * legacy dirs and pins alone, or it silently loses their pending resumes. It runs after
  * `runOrchestrator` constructs every
- * `LoopRunner` but before any tick can call `leaseSlot`: the constructor infers `resumePending`
- * from the on-disk `running` flag only in memory (it does not save it), so `loadLoopState` here
+ * `RoleRunner` but before any run can call `leaseSlot`: the constructor infers `resumePending`
+ * from the on-disk `running` flag only in memory (it does not save it), so `loadRunnerState` here
  * still reports the on-disk flags. *Removing* a dir is best-effort and logged: the slot records
  * are already updated, so a leaked directory is only a leak the next prune collects. */
 export async function retireLegacyRoleWorktrees(root, configured) {
@@ -291,7 +338,7 @@ export async function retireLegacyRoleWorktrees(root, configured) {
     updateSlotsState(root, (state) => {
         for (const role of names) {
             const legacyDir = path.join(dir, role);
-            const legacy = loadLoopState(root, role);
+            const legacy = loadRunnerState(root, role);
             const resumable = legacy.resumePending === true || legacy.running === true;
             const ownRecord = state.slots.find((slot) => slot.dir === legacyDir);
             if (resumable && configuredSet.has(role)) {
@@ -354,35 +401,81 @@ export async function retireLegacyRoleWorktrees(root, configured) {
         }
     }
 }
+/** Startup pass for runs the previous process died in (crash, kill -9, power loss): such a run's
+ * lease is still in slots.json with the dead pid, and its RoleRunner reads the persisted
+ * `running` flag as a resume that must run in the same checkout, the cwd its session used. Pin
+ * each such slot for its role, as the graceful shutdown's abort pin would have, unless the role
+ * already holds a pin; the next claim then clears the dead lease (marking the run unsettled) and
+ * the resume leases the pinned slot with its edits in place. Only configured roles count, as in
+ * retireLegacyRoleWorktrees, so a removed role never leaks a pin. Like that pass, it runs before
+ * any run can lease, while loadRunnerState still reports the on-disk flags. */
+export function pinCrashedRuns(root, configured) {
+    const configuredSet = new Set(configured);
+    updateSlotsState(root, (state) => {
+        for (const slot of state.slots) {
+            const lease = slot.lease;
+            if (lease === null || lease.pid === process.pid || lease.purpose !== "run")
+                continue;
+            if (!configuredSet.has(lease.role) || state.slots.some((s) => s.pinnedFor === lease.role))
+                continue;
+            const runner = loadRunnerState(root, lease.role);
+            if (runner.running !== true && runner.resumePending !== true)
+                continue;
+            slot.pinnedFor = lease.role;
+            slot.pinnedAt = Date.now();
+        }
+    });
+}
 /** Lease a pooled slot for `role`, prepared at `ref`. Resolves once a slot is held and reset to
- * `ref`; rejects on a `signal` abort while waiting. The returned `release` is idempotent. */
+ * `ref`, any uncommitted edits its last holder left saved first (salvageSlotLeftovers), as work
+ * to hand back when that holder was a run that never settled them; rejects on a `signal` abort
+ * while waiting. The returned `release` is idempotent. */
 export async function leaseSlot(root, options) {
-    const { role, purpose, ref, signal, keep, slotBudget } = options;
-    const dir = await acquire(root, role, purpose, signal, slotBudget);
-    const preserved = keep === true && slotForDir(root, dir)?.pinnedFor === role;
+    const dir = await acquire(root, options.role, options.purpose, options.signal, options.slotBudget);
+    return prepareLeased(root, dir, options);
+}
+/** Lease a pooled slot only when one is free right now: resolves null instead of waiting, so a
+ * caller that can do without a second checkout (a verify's check slot) never queues behind
+ * the pool. Otherwise as leaseSlot. */
+export async function tryLeaseSlot(root, options) {
+    const dir = tryClaim(root, options.role, options.purpose, options.slotBudget ?? liveCount(root));
+    return dir === null ? null : prepareLeased(root, dir, options);
+}
+/** Prepare the slot `dir` this process just claimed at `options.ref` and hand back its handle. */
+async function prepareLeased(root, dir, options) {
+    const { role, purpose, ref, keep } = options;
+    const record = slotForDir(root, dir);
+    // A run that gave the slot up unsettled is the one its leftovers belong to, even when a
+    // failed prepare has since recorded another role as the last holder.
+    const unsettledRun = record?.unsettledRun ?? null;
+    const preserved = keep === true && record?.pinnedFor === role;
     const useRelease = await beginWorktreeUse(root, dir);
     // The use registry is LRU bookkeeping; freeing the slot is the real work of a release, so a
     // failed registry write here (ENOSPC, a lock timeout) must not escape: the dead-lease reaper
     // only clears another process's lease, so the slot would stay leased by this live pid and the
     // pool would shrink by one every time. Warn so the failure stays visible, then free anyway.
     const releaseUse = () => {
-        try {
-            useRelease();
-        }
-        catch (err) {
-            warnEventBestEffort(root, TUMWATER_SOURCE, `could not record use release for ${path.basename(dir)}: ${errorMessage(err)}`);
-        }
+        tryOrWarn(root, TUMWATER_SOURCE, `record use release for ${path.basename(dir)}`, useRelease);
     };
     if (!preserved) {
         try {
+            // A run the harness could not clean up after may have left uncommitted edits here; save
+            // them before the reset discards them, for that role's next run when it left them
+            // unsettled (slot-salvage.ts).
+            await salvageSlotLeftovers(root, dir, {
+                leftBy: unsettledRun ?? record?.lastRole ?? null,
+                recoverFor: unsettledRun,
+                forRole: role,
+            });
             await ensureDetachedWorktree(root, dir, ref);
         }
         catch (err) {
             releaseUse();
             // Free the claim without shrinking. releaseSlot retires a migrated legacy slot on this
             // unpinned release, so hand its removal to removeDroppedSlots; a canonical slot survives
-            // for reuse on the next lease.
-            const toRemove = releaseSlot(root, dir, role, Number.MAX_SAFE_INTEGER, false);
+            // for reuse on the next lease. This lease never used the slot, so an unsettled run's
+            // claim on what is left there stands.
+            const toRemove = freeSlot(root, dir, role, Number.MAX_SAFE_INTEGER, false, unsettledRun);
             wakeWaiters(root);
             void removeDroppedSlots(root, toRemove);
             throw err;
@@ -392,12 +485,13 @@ export async function leaseSlot(root, options) {
     return {
         dir,
         preserved,
-        release: (options) => {
+        release: (how) => {
             if (released)
                 return;
             released = true;
             releaseUse();
-            const toRemove = releaseSlot(root, dir, role, liveCount(root), options?.pin === true);
+            const unsettled = how?.unsettled === true && purpose === "run" ? role : null;
+            const toRemove = freeSlot(root, dir, role, liveCount(root), how?.pin === true, unsettled);
             wakeWaiters(root);
             // Best-effort: a slot whose directory is already gone is unregistered by the prune.
             void removeDroppedSlots(root, toRemove);

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

@@ -1,7 +1,6 @@
-// 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;
+ * process that launches runs 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.
  *
@@ -13,8 +12,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, TUMWATER_SOURCE } from "../events/events.js";
-import { errorMessage } from "../text/text.js";
+import { tryOrWarn, TUMWATER_SOURCE } from "../events/events.js";
 import { worktreeUseLockPath, worktreeUsePath } from "../paths.js";
 /** In-process state, keyed by the resolved directory so two roots' same-named worktrees never
  * collide. */
@@ -89,15 +87,10 @@ export function updateWorktreeUse(root, change) {
  * 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, merge, or clean with a registry error. The in-process `uses`/`reclaiming` state is updated
+ * run, 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, TUMWATER_SOURCE, `could not update the worktree-use registry: ${errorMessage(err)}`);
-    }
+    tryOrWarn(root, TUMWATER_SOURCE, "update the worktree-use registry", () => updateWorktreeUse(root, change));
 }
 /** True while a `useWorktree` body holds this worktree. */
 export function isWorktreeInUse(dir) {

package/dist/src/git/worktree.js

@@ -1,19 +1,21 @@
 import fs from "node:fs";
 import path from "node:path";
 import { GIT_TIMEOUT_MS, git, gitTry } from "./git-run.js";
-import { branchExists, hasWorktreeRegistrations, isGitRepo, resolveGitDir } from "./git.js";
-import { pruneOldDirectory, removeTree, subdirectoryNames } from "../files/files.js";
+import { branchExists, commitExists, deleteRef, hasWorktreeRegistrations, isGitRepo, refShaFromFiles, refsUnder, resolveGitDir } from "./git.js";
+import { logEventBestEffort, TUMWATER_SOURCE } from "../events/events.js";
+import { isDirectory, pruneOldDirectory, removeTree, subdirectoryNames } from "../files/files.js";
 import { KILL_GRACE_MS } from "../process/process-group.js";
 import { branchName, worktreePath, worktreesDir } from "../paths.js";
-/** Persistent-worktree lifecycle for the harness: role worktrees (one per loop, reset to main
- * on every fresh tick) and the detached mirror worktree redeploy.ts verifies and compiles.
+import { shortSha } from "../text/format.js";
+/** Persistent-worktree lifecycle for the harness: role worktrees (one per role, reset to main
+ * on every fresh run) and the detached mirror worktree redeploy.ts verifies and compiles.
  * The generic git plumbing these build on lives in git/git.ts; this module owns creating,
  * self-healing, resetting, and abort-syncing those worktrees. */
 /** True when `dir` exists and is still a usable git worktree — its .git pointer file present
  * and resolvable via rev-parse. The shared usability probe of both ensure* functions below;
  * a directory that fails it (pointer lost, or admin-side registration under <root>/.git/
  * worktrees/ pruned by outside git maintenance) is rebuilt from scratch instead of failing
- * every tick. Also exported for read-only viewers that must classify a worktree as absent
+ * every run. Also exported for read-only viewers that must classify a worktree as absent
  * rather than fail (change/change-data.ts's collectRoleChange), so the probe's exact
  * conditions live in one place. */
 export async function isUsableWorktree(dir) {
@@ -30,7 +32,7 @@ async function pruneWorktrees(root) {
 /** Clear the way for `worktree add` at `dir`: prune stale registrations first (a registration
  * whose directory was deleted still blocks the add), then remove a leftover unusable directory
  * and prune again so no registration points at it. The removed content is harness scratch only
- * — role worktrees are reset to main on every fresh tick, and branch commits survive in
+ * — role worktrees are reset to main on every fresh run, and branch commits survive in
  * refs/heads either way. Call only inside serializeSetup: a prune deletes any registration
  * another `worktree add` is still creating. */
 async function clearStaleWorktree(root, dir) {
@@ -75,8 +77,8 @@ async function serializeSetup(root, setup) {
 }
 /** 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
+ * directory instead of failing every run (see clearStaleWorktree). Since the worktree pool merged
+ * (plans/worktree-pool.md, "Role runs 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);
@@ -130,9 +132,9 @@ export async function removeWorktreeDir(root, dir) {
 export async function removeWorktree(root, role) {
     await removeWorktreeDir(root, worktreePath(root, role));
 }
-/** Remove the `_land-<role>` checkouts left by a pre-pool build: the pool's ticks keep their
+/** Remove the `_land-<role>` checkouts left by a pre-pool build: the pool's runs 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
+ * holds nothing to keep. Called once at orchestrator startup, before any run; 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) {
@@ -144,6 +146,22 @@ export async function removeLegacyLandWorktrees(root) {
     if (names.length > 0)
         await gitTry(root, "worktree", "prune");
 }
+/** Delete every `refs/tumwater/` ref whose commit is missing, loose or packed, logging a warning
+ * for each, and return the dropped names in refsUnder order: a dangling pin makes `git gc` exit
+ * 128 until someone deletes it. Uses the unguarded deleteRef, as checkoutDetached does, so
+ * the delete does not depend on the sha read. Runs at team start, before any run, while nothing
+ * else writes pins; refs outside `refs/tumwater/` are never touched. */
+export async function dropDanglingTumwaterPins(root) {
+    const dropped = [];
+    for (const { ref, sha } of await refsUnder(root, "refs/tumwater/")) {
+        if (await commitExists(root, sha))
+            continue;
+        logDroppedRef(root, ref, "at team start");
+        await deleteRef(root, ref);
+        dropped.push(ref);
+    }
+    return dropped;
+}
 /** Cheap file-existence shape probe for removeWorktreeDir: resolveGitDir needs the `.git` pointer,
  * and probing it for a directory that does not exist would only produce a caught throw — the
  * existence check keeps the common absent case allocation-free. Not a usability check; that
@@ -156,7 +174,7 @@ function isUsableWorktreeSyncPath(dir) {
  * exactly `ref`'s tree. A stale index.lock left by a killed git is cleared first, or the
  * checkout/reset below would fail on it forever. Used by redeploy.ts as the pristine copy of main
  * it verifies and compiles — the primary checkout may be dirty or on another branch, a role
- * worktree is never pristine while its loop works. */
+ * worktree is never pristine while its role works. */
 export async function ensureDetachedWorktree(root, dir, ref) {
     if (!(await isUsableWorktree(dir))) {
         const created = await serializeSetup(root, async () => {
@@ -169,7 +187,7 @@ export async function ensureDetachedWorktree(root, dir, ref) {
         if (created)
             return dir;
     }
-    await hardResetWorktree(dir, ref, true);
+    await hardResetWorktree(dir, ref, root);
     return dir;
 }
 /** True when no merge and no rebase is in progress in `wt`, checked from the state files
@@ -177,19 +195,14 @@ export async function ensureDetachedWorktree(root, dir, ref) {
  * rebase — instead of spawning two aborts that can only fail. Returns false ("run the
  * aborts anyway") whenever either is running OR the gitdir cannot be resolved from files:
  * false is always safe, it just means "do exactly what the old spawn-based check did".
- * Synchronous and microsecond-scale: this exists because abortSync runs on every fresh tick
+ * Synchronous and microsecond-scale: this exists because abortSync runs on every fresh run
  * and the common case used to cost two ~10ms subprocess spawns that were guaranteed no-ops. */
 function syncStateClear(wt) {
     const gitdir = resolveGitDir(wt);
     if (gitdir === undefined)
         return false; // Not a repo we can inspect — fall back to the spawns.
-    try {
-        if (!fs.statSync(gitdir).isDirectory())
-            return false; // Pointer target gone: uncertain.
-    }
-    catch {
-        return false;
-    }
+    if (!isDirectory(gitdir))
+        return false; // Pointer target gone: uncertain.
     try {
         fs.statSync(path.join(gitdir, "MERGE_HEAD"));
         return false;
@@ -198,13 +211,8 @@ function syncStateClear(wt) {
         // No merge in progress — rebase state next.
     }
     for (const dir of ["rebase-merge", "rebase-apply"]) {
-        try {
-            if (fs.statSync(path.join(gitdir, dir)).isDirectory())
-                return false;
-        }
-        catch {
-            // This backend's rebase state is absent.
-        }
+        if (isDirectory(path.join(gitdir, dir)))
+            return false;
     }
     return true;
 }
@@ -225,7 +233,7 @@ const STALE_GIT_LOCK_MS = GIT_TIMEOUT_MS + KILL_GRACE_MS;
 /** Remove a stale `index.lock` from `wt`'s gitdir. A git killed mid-write — our own group
  * deadline's SIGKILL after a SIGTERM it could not handle, a crashed harness, an operator kill —
  * leaves index.lock behind, and every later `git reset --hard` then fails "Unable to create
- * '…/index.lock': File exists" with no self-heal, wedging the loop on every tick. A *fresh*
+ * '…/index.lock': File exists" with no self-heal, wedging the role on every run. A *fresh*
  * lock is left alone: it may belong to a git still running, so this clears wreckage, never a
  * live writer. */
 function clearStaleIndexLock(wt) {
@@ -241,23 +249,72 @@ function clearStaleIndexLock(wt) {
         // No lock file (the common case), or an unreadable gitdir: nothing to clear.
     }
 }
+/** `git checkout --detach --force ref`, tolerating a dangling tumwater pin. `--force` because every
+ * caller hard-resets to `ref` right after: without it, uncommitted edits a killed run left in the
+ * worktree failed the checkout ("Your local changes … would be overwritten") on every later reset,
+ * so a pooled slot holding them failed each role it was handed (2026-10-21). A pooled slot's
+ * edits are saved first (slot-salvage.ts); the harness's own scratch worktrees hold nothing to
+ * keep. Leaving a detached HEAD makes
+ * git walk every ref to report orphaned commits, so one `refs/tumwater/…` pin (merge, rejected,
+ * legacy landing) whose object is gone fails the checkout "fatal: bad object <ref>" (128) and
+ * errors the role's run. The pin is unusable either way, so the named ref is deleted and the
+ * checkout retried, after a `warning` event records its name, sha and file age as evidence; any
+ * other failure, or a bad ref outside refs/tumwater/, still throws. */
+async function checkoutDetached(root, wt, ref) {
+    for (;;) {
+        try {
+            await git(wt, "checkout", "--detach", "--force", ref);
+            return;
+        }
+        catch (err) {
+            const dangling = /fatal: bad object (refs\/tumwater\/\S+)/.exec(String(err instanceof Error ? err.message : err));
+            if (dangling === null)
+                throw err;
+            const bad = dangling[1];
+            logDroppedRef(root, bad, "so a worktree checkout could proceed");
+            await git(wt, "update-ref", "-d", bad);
+        }
+    }
+}
+/** Record a dangling pin about to be deleted: its ref, the sha it named and, for a loose ref
+ * file, when it was last written (omitted when the ref was packed). */
+function logDroppedRef(root, ref, why) {
+    const sha = refShaFromFiles(root, ref);
+    const gitDir = resolveGitDir(root);
+    let refWrittenAt;
+    try {
+        if (gitDir !== undefined)
+            refWrittenAt = new Date(fs.statSync(path.join(gitDir, ref)).mtimeMs).toISOString();
+    }
+    catch {
+        // Packed ref, or the file is already gone: no age to report.
+    }
+    logEventBestEffort(root, {
+        source: TUMWATER_SOURCE,
+        type: "warning",
+        message: `dropped dangling ref ${ref} (${sha ? shortSha(sha) : "unknown sha"}, object missing) ${why}`,
+        ref,
+        sha,
+        ...(refWrittenAt === undefined ? {} : { refWrittenAt }),
+    });
+}
 /** Hard-reset a worktree to `ref`, self-healing the two wedges a killed git leaves behind: a
  * stale index.lock is cleared first (or the reset fails "Unable to create '…/index.lock'"
- * forever), and an interrupted merge or rebase is aborted (or the tick wedges on "you are
- * already rebasing"). With `detach`, the worktree is checked out detached at `ref` first —
- * ensureDetachedWorktree's repair path for a worktree left on a branch; resetWorktreeToMain
- * leaves its branch checked out. Untracked files are dropped (ignored files survive; the stale
- * `dist/` build dir is reaped by age). */
-async function hardResetWorktree(wt, ref, detach = false) {
+ * forever), and an interrupted merge or rebase is aborted (or the run wedges on "you are
+ * already rebasing"). With `detachRoot` (the repository root), the worktree is checked out
+ * detached at `ref` first — ensureDetachedWorktree's repair path for a worktree left on a
+ * branch; resetWorktreeToMain leaves its branch checked out. Untracked files are
+ * dropped (ignored files survive; the stale `dist/` build dir is reaped by age). */
+async function hardResetWorktree(wt, ref, detachRoot) {
     clearStaleIndexLock(wt);
     await abortSync(wt);
-    if (detach)
-        await git(wt, "checkout", "--detach", ref);
+    if (detachRoot !== undefined)
+        await checkoutDetached(detachRoot, wt, ref);
     await git(wt, "reset", "--hard", ref);
     await git(wt, "clean", "-fd");
     pruneStaleBuildDir(wt);
 }
-/** Hard-reset a worktree's branch to main — the fresh-tick reset. */
+/** Hard-reset a worktree's branch to main — the fresh-run reset. */
 export async function resetWorktreeToMain(wt, mainBranch) {
     await hardResetWorktree(wt, mainBranch);
 }