tumwater 0.4.0 → 0.4.2

package/dist/src/gates/gate-polls.js

@@ -40,17 +40,45 @@ export function newTeamGateStates(config) {
 }
 /** Poll every team-wide gate and alarm, advancing `states` in place. */
 export function pollTeamGates(states, ctx) {
-    const { root, runners, liveConfig, modelsPath, now, info } = ctx;
+    const { root, now } = ctx;
     // The per-backend subscription account lookup (part 2e/9): each backend's account is read on
     // demand — the window hold/reserve/warning loop, the window-move and the handback reads each
     // call accounts fresh — so a second subscription backend is judged from its own account, never
     // from claude's.
     const accounts = (backend) => readAccount(root, backend, now);
-    // Daily cost budget gate (src/gates/budget-gates.ts owns the reads, the edge-triggered
-    // budget_* events, and the breaker re-key; the fallback config view it derives lives in
-    // src/budget/budget-fallback-view.ts): the orchestrator
-    // owns only the wiring — the demotion publish below and the per-runner assignment at
-    // the bottom of this block.
+    const budget = pollBudgetPhase(states, ctx, accounts);
+    const holds = pollHoldGates(states, ctx);
+    const quietDisk = pollQuietAndDiskGates(states, ctx);
+    pollTeamFailureAlarms(states, ctx, accounts, budget.windowTiers);
+    return {
+        gate: budget.gate,
+        roleConfig: budget.roleConfig,
+        directorConfig: budget.directorConfig,
+        userPaused: holds.userPaused,
+        pausedRoles: holds.pausedRoles,
+        capPaused: holds.capPaused,
+        maintenanceQuota: holds.maintenanceQuota,
+        bootstrapHeld: holds.bootstrapHeld,
+        budgetPausedRoles: budget.budgetPausedRoles,
+        servingResolved: budget.servingResolved,
+        priceResolved: budget.priceResolved,
+        budgetActive: budget.budgetActive,
+        windowMovedRoles: budget.windowMovedRoles,
+        roleQuietHeld: quietDisk.roleQuietHeld,
+        quietNow: quietDisk.quietNow,
+        diskHeld: quietDisk.diskHeld,
+    };
+}
+// Daily cost budget gate (src/gates/budget-gates.ts owns the reads, the edge-triggered
+// budget_* events, and the breaker re-key; the fallback config view it derives lives in
+// src/budget/budget-fallback-view.ts): the orchestrator
+// owns only the wiring — the demotion publish below and the per-runner assignment at
+// the bottom of this block — and the per-tier budget pause (src/budget/budget-wiring.ts,
+// part 5c/8): a role whose model tier resolved to no usable free pair while the cap is
+// reached starts no new runs, and a role on a window-moved tier whose own backend owns
+// the out window is moved off it.
+function pollBudgetPhase(states, ctx, accounts) {
+    const { root, runners, liveConfig, modelsPath, info } = ctx;
     const { gate, roleConfig, spentUsd, capUsd, onFallback, resumed: gateResumed, pairs: fallbackPairs, priceResolved, servingResolved, budgetActive, windowTiers, windowResumedBackends, directorConfig, chain, } = pollBudgetGate(states.budget, {
         root,
         states: runners.map((r) => r.state),
@@ -82,9 +110,40 @@ export function pollTeamGates(states, ctx) {
             capUsd,
         },
     });
-    // The pause gates (src/gates/pause-gates.ts owns the reads, the edge-triggered pause/resume
-    // events, and the cross-poll bookkeeping): the operator pause's marker and the per-role pause's
-    // set, both read fresh per cycle so a marker change takes effect on the next poll.
+    // The per-tier budget pause (src/budget/budget-wiring.ts, part 5c/8): a role whose model
+    // tier resolved to no usable free pair while the cap is reached starts no new runs, and a
+    // role on a window-moved tier whose own backend owns the out window is moved off it — the
+    // stateless verdict recomputed every poll from the SAME resolution the gate's value came
+    // from, beside `capPaused` (the scheduling pass folds the sets; the director is exempt, as
+    // under every autonomous gate, and the demoted pair's probe pierces the set for its own
+    // tier's roles only — probeRoles in the orchestrator's scheduling pass).
+    const { budgetPausedRoles, windowMovedRoles } = budgetPausedSubjects({
+        runners,
+        liveConfig,
+        accounts,
+        budgetActive,
+        servingResolved,
+        windowTiers,
+    });
+    return {
+        gate,
+        roleConfig,
+        directorConfig,
+        budgetPausedRoles,
+        windowMovedRoles,
+        servingResolved,
+        priceResolved,
+        budgetActive,
+        windowTiers,
+    };
+}
+// The pause gates (src/gates/pause-gates.ts owns the reads, the edge-triggered pause/resume
+// events, and the cross-poll bookkeeping): the operator pause's marker and the per-role pause's
+// set, both read fresh per cycle so a marker change takes effect on the next poll — then the
+// error-streak circuit breaker, the per-role daily cost cap, the maintenance allowance and the
+// new-project bootstrap, each a stateless verdict folded into this poll's hold views.
+function pollHoldGates(states, ctx) {
+    const { root, runners, liveConfig, now } = ctx;
     const { userPaused, pausedRoles } = pollPauseGates(root, states.pause);
     // The error-streak circuit breaker (src/gates/streak-gate.ts): a role past ERROR_STREAK_BREAKER
     // consecutive failed runs is paused through the same per-role marker the operator's
@@ -101,21 +160,6 @@ export function pollTeamGates(states, ctx) {
     for (const role of streakPaused)
         states.pause.prevPausedRoles.add(role);
     const pausedRolesNow = streakPaused.length > 0 ? new Set([...pausedRoles, ...streakPaused]) : pausedRoles;
-    // The per-tier budget pause (src/budget/budget-wiring.ts, part 5c/8): a role whose model
-    // tier resolved to no usable free pair while the cap is reached starts no new runs, and a
-    // role on a window-moved tier whose own backend owns the out window is moved off it — the
-    // stateless verdict recomputed every poll from the SAME resolution the gate's value came
-    // from, beside `capPaused` (the scheduling pass folds the sets; the director is exempt, as
-    // under every autonomous gate, and the demoted pair's probe pierces the set for its own
-    // tier's roles only — probeRoles in the orchestrator's scheduling pass).
-    const { budgetPausedRoles, windowMovedRoles } = budgetPausedSubjects({
-        runners,
-        liveConfig,
-        accounts,
-        budgetActive,
-        servingResolved,
-        windowTiers,
-    });
     // The per-role daily cost cap (src/gates/role-cap-gates.ts): a role whose local-day spend has
     // reached its own maxDailyCostUsdPerRole entry starts no new runs — the stateless verdict
     // recomputed every poll, no pause marker written (the marker is anonymous; a cap pause must
@@ -143,12 +187,16 @@ export function pollTeamGates(states, ctx) {
     // pass folds the held set in beside capPaused (with the fresh-wake/queued-prompt override the
     // need-based deferral honors).
     const bootstrapHeld = pollBootstrapGate(root, states.bootstrap, runners, liveConfig, now);
-    // Per-role quiet hours (src/scheduling/quiet-hours.ts): a role whose own quietHoursPerRole window
-    // covers `now` starts no new runs — the team window's semantics scoped to one role, the
-    // director exempt like every autonomous gate. Stateless, recomputed per poll exactly like
-    // capPaused: no crossing events, no state — a live config edit applies on the next poll
-    // by construction. A role held by BOTH windows is held once: the scheduling pass folds
-    // both verdicts into one hold condition, nothing counts a role twice.
+    return { userPaused, pausedRoles: pausedRolesNow, capPaused, maintenanceQuota, bootstrapHeld };
+}
+// Per-role quiet hours (src/scheduling/quiet-hours.ts): a role whose own quietHoursPerRole window
+// covers `now` starts no new runs — the team window's semantics scoped to one role, the
+// director exempt like every autonomous gate. Stateless, recomputed per poll exactly like
+// capPaused: no crossing events, no state — a live config edit applies on the next poll
+// by construction. A role held by BOTH windows is held once: the scheduling pass folds
+// both verdicts into one hold condition, nothing counts a role twice.
+function pollQuietAndDiskGates(states, ctx) {
+    const { root, runners, liveConfig, now, info } = ctx;
     const roleQuietHeld = new Set();
     for (const r of runners) {
         if (r.role === DIRECTOR_ROLE)
@@ -188,19 +236,20 @@ export function pollTeamGates(states, ctx) {
             ...(ctx.reclaim?.lastReclaim ? { lastReclaim: ctx.reclaim.lastReclaim } : {}),
         };
     publishInfoFields(root, info, [["disk", disk]]);
-    // Each runner as the two provider-failure polls read it (HoldInputs): the role, its two
-    // episodic fields, and the provider its NEXT run will run on (runProvider — the tier
-    // fallback pair while a model-fallback episode is active, else the role's resolved config;
-    // undefined when pi's default is in charge). Built ONCE per poll so the hold and the spread
-    // read the same list, like holdObservations on the reducer side. Keying on the effective
-    // provider is what lets a storm on the fallback pair form its own hold while the abandoned
-    // primary stays clear (PLANS.md "Model failure fallback, part 1/2").
-    //
-    // Each stamp (lastRateLimit/lastBackendFailure) carries the hold key of the backend that
-    // ACTUALLY failed — a reviewer run folded through the author's role stamps `claude`, not
-    // the pi author's provider — and the polls' observation mapper files each stamp under that
-    // key, falling back to runProvider here for a stamp without one (PLANS.md "Mixed claude +
-    // pi fleets, part 2/4"). The spreads below carry the stamps wholesale, provider included.
+    return { roleQuietHeld, quietNow, diskHeld };
+}
+// Each runner as the two provider-failure polls read it (HoldInputs) is built ONCE here so
+// the hold and the spread read the same list, like holdObservations on the reducer side.
+// Keying on the effective provider is what lets a storm on the fallback pair form its own
+// hold while the abandoned primary stays clear (PLANS.md "Model failure fallback, part 1/2").
+//
+// Each stamp (lastRateLimit/lastBackendFailure) carries the hold key of the backend that
+// ACTUALLY failed — a reviewer run folded through the author's role stamps `claude`, not
+// the pi author's provider — and the polls' observation mapper files each stamp under that
+// key, falling back to runProvider here for a stamp without one (PLANS.md "Mixed claude +
+// pi fleets, part 2/4"). The spreads below carry the stamps wholesale, provider included.
+function pollTeamFailureAlarms(states, ctx, accounts, windowTiers) {
+    const { root, runners, liveConfig, now, info } = ctx;
     const holdInputs = (rs) => rs.map((r) => ({
         role: r.role,
         provider: r.runProvider(now),
@@ -268,22 +317,4 @@ export function pollTeamGates(states, ctx) {
     // so a degraded backend that fails the team widely and shallowly still names itself.
     // Observational only, like the error storm: it gates nothing.
     states.failureSpread = pollFailureSpread(root, states.failureSpread, holdInputs(runners), now);
-    return {
-        gate,
-        roleConfig,
-        directorConfig,
-        userPaused,
-        pausedRoles: pausedRolesNow,
-        capPaused,
-        maintenanceQuota,
-        bootstrapHeld,
-        budgetPausedRoles,
-        servingResolved,
-        priceResolved,
-        budgetActive,
-        windowMovedRoles,
-        roleQuietHeld,
-        quietNow,
-        diskHeld,
-    };
 }

package/dist/src/gates/role-cap-gates.js

@@ -16,7 +16,7 @@
  *   set instead, and `resume --role` has no marker to touch (none is needed: the lift is a
  *   config edit or midnight).
  * - An unknown role id in the caps map is a config-validation error
- *   (src/config/config-validation.ts, the `roles.<id>` idiom): explicit misconfiguration
+ *   (src/config/config-validation-roles.ts, the per-role map checks): explicit misconfiguration
  *   never silently no-ops a cap.
  *
  * Shape, like every gate in the family (src/gates/gate-polls.ts): the pure verdict and the

package/dist/src/gates/startup-gate.js

@@ -78,42 +78,28 @@ opencodeSeed = {}) {
     }
     // Seed the claude account state before the first run (plans/agent-backends.md part 6a):
     // `claude auth status` decides subscription vs API key, and an existing file is left alone.
-    // Gated on a claude seam so a pi-only team spawns nothing, and attempted once per root per
-    // process: runStartupCheck is also the redeploy/supervisor poll's ask (runStartupProblem),
-    // and a logged-out claude would otherwise spawn a bounded probe on every poll. If the seed
-    // fails, the first claude run's observation fills the file in.
-    if (!claudeSeedAttempted.has(root) && backendsInUse(config).includes("claude")) {
-        claudeSeedAttempted.add(root);
-        seedClaudeAccount(root, config);
-    }
+    // If the seed fails, the first claude run's observation fills the file in.
+    seedOnce(root, config, "claude", claudeSeedAttempted, () => seedClaudeAccount(root, config));
     // Seed the codex account state before the first codex run (plans/codex-backend.md §7):
     // `codex login status` decides subscription vs API key, and an existing file is left alone.
-    // Gated on a codex seam like the claude seed above, and attempted once per root per process.
     // API-key billing is refused (decision 5): Codex reports no cost, so per-token billing would
     // spend money the cap cannot see. If the seed fails or reads something else, the first codex
     // run's observation fills the file in.
-    if (!codexSeedAttempted.has(root) && backendsInUse(config).includes("codex")) {
-        codexSeedAttempted.add(root);
-        const codexAccount = seedCodexAccount(root, config);
-        if (codexAccount?.billing === "api") {
-            return {
-                problem: "Codex is logged in with an API key; tumwater runs Codex on a ChatGPT subscription only — run `CODEX_HOME=<home> codex login --device-auth`",
-            };
-        }
+    const codexAccount = seedOnce(root, config, "codex", codexSeedAttempted, () => seedCodexAccount(root, config));
+    if (codexAccount?.billing === "api") {
+        return {
+            problem: "Codex is logged in with an API key; tumwater runs Codex on a ChatGPT subscription only — run `CODEX_HOME=<home> codex login --device-auth`",
+        };
     }
     // Seed the opencode models catalog (part 6b/7) before the first run: the poll surfaces price
     // opencode seams from the cached `.tumwater/state/opencode-models.json`, and an absent cache
-    // reads every opencode seam NOT free (the safe direction for the budget gate). Mirroring the
-    // claude seed above, it runs once per root per process when a model job routes to opencode;
-    // a failed fetch keeps the last good cache (or an empty one) and never blocks startup; a
-    // failed fetch or cache write logs one warning event.
-    if (!opencodeSeedAttempted.has(root) && backendsInUse(config).includes("opencode")) {
-        opencodeSeedAttempted.add(root);
-        await seedOpencodeCatalog(root, config, {
-            ...opencodeSeed,
-            warn: (message) => warnEventBestEffort(root, TUMWATER_SOURCE, message),
-        });
-    }
+    // reads every opencode seam NOT free (the safe direction for the budget gate). A failed fetch
+    // keeps the last good cache (or an empty one) and never blocks startup; a failed fetch or
+    // cache write logs one warning event.
+    await seedOnce(root, config, "opencode", opencodeSeedAttempted, () => seedOpencodeCatalog(root, config, {
+        ...opencodeSeed,
+        warn: (message) => warnEventBestEffort(root, TUMWATER_SOURCE, message),
+    }));
     const branch = await resolveMainBranch(root, config, branchArg);
     if ("problem" in branch)
         return branch;
@@ -159,6 +145,20 @@ export function newOpencodeCatalogRefresh(root, seed, warn) {
         },
     };
 }
+/** Run a per-backend seed at most once per root per process, and only when that backend is in
+ * use — the guard the claude-account, codex-account and opencode-catalog seeds share
+ * (runStartupCheck is also the redeploy/supervisor poll's ask runStartupProblem, and a seed
+ * would otherwise spawn a bounded probe on every poll). Returns the seed body's value when it
+ * ran, undefined when the backend is unused or was already attempted this process; each caller
+ * decides what to do with the value (refuse on a codex API-key billing, ignore for claude and
+ * opencode). */
+function seedOnce(root, config, backend, attempted, seed) {
+    if (!attempted.has(root) && backendsInUse(config).includes(backend)) {
+        attempted.add(root);
+        return seed();
+    }
+    return undefined;
+}
 /** Roots this process has already attempted a claude-account seed for (see runStartupCheck),
  * so the supervisor's and redeploy's repeated startup checks do not respawn `claude auth
  * status` on every poll when the probe fails. */

package/dist/src/gates/streak-gate.js

@@ -29,7 +29,7 @@
  * ERROR_STREAK_BREAKER failures.
  *
  * Accepted behavior, stated here and not fixed in this change: the dashboards' "failing run after
- * run" alert (src/ui/team-alerts.ts) reads consecutiveErrors regardless of pause, so it keeps
+ * run" alert (src/ui/team-alert-status.ts) reads consecutiveErrors regardless of pause, so it keeps
  * listing a breaker-paused role until the streak clears; the role cell's paused badge explains why
  * it is not running, and the role_streak_paused event tells the operator why. */
 import { ERROR_STREAK_BREAKER } from "../run/run-apply.js";

package/dist/src/git/git.js

@@ -463,7 +463,7 @@ export async function commitMessage(cwd, sha) {
 /** The subject (first line) of one commit, trimmed, or "" when it cannot be read — the
  * non-throwing sibling of `commitMessage` and the one home of the `log -1 --format=%s`
  * read, so the path that names a commit in a message (the post-merge reviewer naming the
- * fix it landed, src/merge/merge-post-review.ts) cannot drift on its git spelling
+ * fix it landed, src/merge/merge-post-review-drain.ts) cannot drift on its git spelling
  * or its trim. Its call is through gitTry, so an unreadable repo yields a "" subject, never a
  * throw; it treats that as an honest degradation, not an error. (Distinct from
  * commit-message.ts's commitSubject, which parses a subject out of a message string instead of

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

@@ -24,18 +24,18 @@ 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 { ensureDir, 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 { pad2 } from "../text/datetime.js";
+import { formatDate, pad2 } from "../text/datetime.js";
+import { plural } from "../text/phrases.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 stamp = `${now.getFullYear()}-${pad2(now.getMonth() + 1)}-${pad2(now.getDate())}` +
-        `-${pad2(now.getHours())}${pad2(now.getMinutes())}${pad2(now.getSeconds())}`;
+    const stamp = `${formatDate(now)}-${pad2(now.getHours())}${pad2(now.getMinutes())}${pad2(now.getSeconds())}`;
     return `${stamp}-${path.basename(slotDir)}-${leftBy ?? "unknown"}.patch`;
 }
 /** Save the uncommitted changes in `dir` (modified, deleted and untracked files, ignored ones
@@ -76,24 +76,24 @@ export async function salvageSlotLeftovers(root, dir, { leftBy, recoverFor, forR
         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 });
+        ensureDir(home);
         // 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` +
+        writeTextAtomic(file, `# ${plural(files, "uncommitted file")} ${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}`);
+            ? `workspace ${slot} still held ${plural(files, "uncommitted file")} ${by} left behind; saved them to ${saved} and reset it for ${forRole}`
+            : `workspace ${slot} still held ${plural(files, "uncommitted file")} 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`);
+        warnEventBestEffort(root, TUMWATER_SOURCE, `workspace ${slot} still held ${plural(files, "uncommitted file")} ${by} left behind, and saving them failed (${errorMessage(err)}); resetting it for ${forRole} discards them`);
         return null;
     }
     finally {

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

@@ -72,14 +72,23 @@ function readSlotRecord(slot) {
         ...slot,
         dir: slot.dir,
         lease: isSlotLease(slot.lease) ? readSlotLease(slot.lease) : null,
-        pinnedFor: typeof slot.pinnedFor === "string" ? canonicalRoleId(slot.pinnedFor) : null,
+        pinnedFor: roleIdOrNull(slot.pinnedFor),
         // 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" ? canonicalRoleId(slot.lastRole) : null,
+        lastRole: roleIdOrNull(slot.lastRole),
         lastReleasedAt: finiteNumber(slot.lastReleasedAt, null),
-        unsettledRun: typeof slot.unsettledRun === "string" ? canonicalRoleId(slot.unsettledRun) : null,
+        unsettledRun: roleIdOrNull(slot.unsettledRun),
     };
 }
+/** A string role id read from a persisted slot record, canonicalized, or null when absent
+ * or foreign. The three canonical-id fields of SlotRecord (pinnedFor, lastRole,
+ * unsettledRun) share this one read, so they cannot drift on how a non-string or legacy id
+ * reads: a non-string rides along as null (a hand edit or older writer that dropped the
+ * field must not name a role), and a legacy id resolves through canonicalRoleId like every
+ * reader here. */
+function roleIdOrNull(value) {
+    return typeof value === "string" ? canonicalRoleId(value) : null;
+}
 function writeSlotsStateUnlocked(root, state) {
     writeJsonAtomic(slotsStatePath(root), state);
 }

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

@@ -0,0 +1,127 @@
+/** The worktree pool's one-time startup layout migration (plans/worktree-pool.md, parts 4c/5):
+ * move the pre-pool `.tumwater/worktrees/<role>` checkouts onto the pooled `_slot-<n>` layout, and
+ * pin the slots a previous process died in. Split out of worktree-pool.ts so that module — the
+ * runtime lease machinery every run and verify calls — does not also carry the passes the
+ * orchestrator runs exactly once on a team's start. These two passes read and rewrite the same
+ * persisted slots.json (updateSlotsState) and run after every RoleRunner is constructed but
+ * before any run can lease; they are exported only for orchestrator.ts and the worktree-pool
+ * tests. */
+import path from "node:path";
+import { worktreesDir, isCanonicalSlotDir } from "../paths.js";
+import { loadRunnerState } from "../runner/runner-state-load.js";
+import { DIRECTOR_ROLE } from "../roles/roles.js";
+import { updateSlotsState } from "./slots-state.js";
+import { removeWorktreeDir } from "./worktree.js";
+import { warnEventBestEffort, TUMWATER_SOURCE } from "../events/events.js";
+import { errorMessage } from "../text/text.js";
+import { subdirectoryNames } from "../files/files.js";
+/** One-time startup migration (plans/worktree-pool.md "Legacy role worktrees", part 4c/5):
+ * 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 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
+ * `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) {
+    const dir = worktreesDir(root);
+    // 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);
+    const toRemove = new Set();
+    updateSlotsState(root, (state) => {
+        for (const role of names) {
+            const legacyDir = path.join(dir, 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)) {
+                const owned = state.slots.find((slot) => slot.pinnedFor === role ||
+                    (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) {
+                        state.slots = state.slots.filter((slot) => slot.dir !== legacyDir);
+                        toRemove.add(legacyDir);
+                    }
+                    if (owned.pinnedFor !== role)
+                        owned.pinnedAt = Date.now();
+                    owned.pinnedFor = role;
+                }
+                else if (ownRecord !== undefined) {
+                    // Already migrated (a restart before the resume ran): keep it pinned and inert,
+                    // preserving the pin's original age for the doctor's stuck-pin warning.
+                    ownRecord.lease = null;
+                    if (ownRecord.pinnedFor !== role)
+                        ownRecord.pinnedAt = Date.now();
+                    ownRecord.pinnedFor = role;
+                    ownRecord.lastRole = null;
+                    ownRecord.lastReleasedAt = null;
+                }
+                else {
+                    state.slots.push({
+                        dir: legacyDir,
+                        lease: null,
+                        pinnedFor: role,
+                        pinnedAt: Date.now(),
+                        lastRole: null,
+                        lastReleasedAt: null,
+                    });
+                }
+            }
+            else {
+                state.slots = state.slots.filter((slot) => slot.dir !== legacyDir);
+                toRemove.add(legacyDir);
+            }
+        }
+        // A paused or removed role must not leak a permanently pinned checkout.
+        for (const slot of [...state.slots]) {
+            if (slot.pinnedFor === null || configuredSet.has(slot.pinnedFor))
+                continue;
+            slot.pinnedFor = null;
+            slot.pinnedAt = null;
+            if (!isCanonicalSlotDir(slot.dir)) {
+                state.slots = state.slots.filter((s) => s !== slot);
+                toRemove.add(slot.dir);
+            }
+        }
+    });
+    for (const victim of toRemove) {
+        try {
+            await removeWorktreeDir(root, victim);
+        }
+        catch (err) {
+            warnEventBestEffort(root, TUMWATER_SOURCE, `could not remove legacy role workspace ${victim}: ${errorMessage(err)}`);
+        }
+    }
+}
+/** 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();
+        }
+    });
+}