tumwater 0.4.2 → 0.4.4

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

@@ -7,7 +7,7 @@
  * and nothing can get stuck"): the verdict is recomputed from the runner state every poll, no
  * marker is written, and local midnight lifts it by itself.
  *
- * Deliberate differences from the streak gate's shape (src/gates/streak-gate.ts), stated in
+ * Deliberate differences from the streak gate's shape (src/gates/streak-gates.ts), stated in
  * the plan so no implementer re-litigates them:
  * - This gate writes NOTHING to the shared per-role pause marker (src/team/team-state.ts's
  *   pauseRole). The marker is anonymous — after a restart across midnight the harness could
@@ -24,7 +24,7 @@
  * module owns the only event emission — the orchestrator's poll owns only the wiring. The
  * in-memory `prev` and `warned` sets are the whole cross-poll memory: a restart with a
  * still-over-cap role re-logs one `role_cap_paused` on the first poll, and a role already past
- * 80% re-logs one `role_cap_warning` (the durable-cause honest report the streak-gate doc
+ * 80% re-logs one `role_cap_warning` (the durable-cause honest report the streak-gates doc
  * accepts). */
 import { groupBy } from "../collections.js";
 import { budgetWarning, dailyCost, todayStamp } from "../budget/budget.js";
@@ -50,7 +50,7 @@ export function roleCapPaused(state, cap, now = Date.now()) {
  * ids so a caller can log the base (the gate) or flatten the ids (the observer). */
 export function roleCapVerdicts(runners, caps, now) {
     // Group by base role via the shared Map-of-arrays step (collections.groupBy, which
-    // time-spend, history-data, and team-polls also fold), then drop the exempt director's
+    // failure-time-spend, history-data, and team-polls also fold), then drop the exempt director's
     // group so it never holds a verdict; first-appearance order is preserved.
     const groups = groupBy(runners, (r) => baseRoleOf(r.role));
     groups.delete(DIRECTOR_ROLE);
@@ -71,6 +71,45 @@ export function roleCapVerdicts(runners, caps, now) {
 export function newRoleCapGateState() {
     return { prev: new Set(), warned: new Set() };
 }
+/** One base role's pause/resume edge, logged by the poll's loop: reads whether the role was
+ * already judged over its cap at the last poll (`state.prev`) and on ENTER logs one
+ * `role_cap_paused` (role, spentUsd, capUsd); on EXIT logs one `role_cap_resumed` (role). */
+function logCapCrossing(root, base, verdict, cap, state) {
+    const was = state.prev.has(base);
+    if (verdict.over && !was) {
+        logEventBestEffort(root, {
+            source: TUMWATER_SOURCE,
+            type: "role_cap_paused",
+            role: base,
+            spentUsd: verdict.spentUsd,
+            capUsd: cap,
+        });
+    }
+    else if (!verdict.over && was) {
+        logEventBestEffort(root, { source: TUMWATER_SOURCE, type: "role_cap_resumed", role: base });
+    }
+}
+/** The 80% early warning (PLANS.md 2026-10-09), the per-role twin of the team's
+ * budget_warning and edge-triggered with the same reset-on-below: crossing the threshold
+ * while still under the cap logs one `role_cap_warning`, a dip back under re-arms it. Warn
+ * only while the cap is open — a poll that jumps straight to the cap already logs its own
+ * `role_cap_paused`, so the warning never doubles the page on the poll the cap is reached. */
+function logCapWarning(root, base, verdict, cap, state) {
+    const warn = !verdict.over && cap !== undefined && budgetWarning({ spentUsd: verdict.spentUsd, capUsd: cap });
+    if (warn && !state.warned.has(base)) {
+        logEventBestEffort(root, {
+            source: TUMWATER_SOURCE,
+            type: "role_cap_warning",
+            role: base,
+            spentUsd: verdict.spentUsd,
+            capUsd: cap,
+        });
+        state.warned.add(base);
+    }
+    else if (!warn) {
+        state.warned.delete(base);
+    }
+}
 /** Step the gate by one orchestrator poll. Per runner (the director exempt, like every
  * autonomous gate): judge `roleCapPaused` against its configured cap; on ENTER log one
  * `role_cap_paused` carrying the role, its spend, and its cap; on EXIT log one
@@ -86,39 +125,9 @@ export function pollRoleCapGate(root, state, runners, caps, now) {
     const paused = new Set();
     const overBases = new Set();
     for (const [base, verdict] of verdicts) {
-        const was = state.prev.has(base);
-        if (verdict.over && !was) {
-            logEventBestEffort(root, {
-                source: TUMWATER_SOURCE,
-                type: "role_cap_paused",
-                role: base,
-                spentUsd: verdict.spentUsd,
-                capUsd: caps?.[base],
-            });
-        }
-        else if (!verdict.over && was) {
-            logEventBestEffort(root, { source: TUMWATER_SOURCE, type: "role_cap_resumed", role: base });
-        }
-        // The 80% early warning (PLANS.md 2026-10-09), the per-role twin of the team's
-        // budget_warning and edge-triggered with the same reset-on-below: crossing the threshold
-        // while still under the cap logs one role_cap_warning, a dip back under re-arms it. Warn
-        // only while the cap is open — a poll that jumps straight to the cap already logs its own
-        // role_cap_paused, so the warning never doubles the page on the poll the cap is reached.
         const cap = caps?.[base];
-        const warn = !verdict.over && cap !== undefined && budgetWarning({ spentUsd: verdict.spentUsd, capUsd: cap });
-        if (warn && !state.warned.has(base)) {
-            logEventBestEffort(root, {
-                source: TUMWATER_SOURCE,
-                type: "role_cap_warning",
-                role: base,
-                spentUsd: verdict.spentUsd,
-                capUsd: cap,
-            });
-            state.warned.add(base);
-        }
-        else if (!warn) {
-            state.warned.delete(base);
-        }
+        logCapCrossing(root, base, verdict, cap, state);
+        logCapWarning(root, base, verdict, cap, state);
         if (verdict.over) {
             overBases.add(base);
             for (const id of verdict.roleIds)

package/dist/src/gates/{startup-gate.js → startup-gates.js}

@@ -9,15 +9,16 @@ import { DETACHED_HEAD_MESSAGE, NOT_A_REPO_MESSAGE, NOT_INITIALIZED_MESSAGE, NO_
 import { owningTeamRoot } from "../paths.js";
 import { backendMissingMessage, findBackendBinary, resolveBackendBin } from "../pi/pi-bin.js";
 import { seedClaudeAccount } from "../agent/claude/claude-account.js";
-import { seedCodexAccount } from "../agent/codex/codex-account.js";
+import { codexApiKeyRefusalMessage, seedCodexAccount } from "../agent/codex/codex-account.js";
+import { distinctOrdered } from "../collections.js";
 import { opencodeCatalogStale, readOpencodeCache, refreshOpencodeCatalog, } from "../agent/opencode/opencode-catalog.js";
 import { warnEventBestEffort, TUMWATER_SOURCE } from "../events/events.js";
 import { HOUR_MS } from "../text/datetime.js";
 import { errorMessage } from "../text/text.js";
 import { backendById } from "../agent/agent-backend.js";
 // Register the built-in pi and claude adapters into the registry this module reads (see
-// unregisteredBackendInUse) — importing run-agent.ts is the one place they register.
-import "../agent/run-agent.js";
+// unregisteredBackendInUse) — importing agent-run.ts is the one place they register.
+import "../agent/agent-run.js";
 /** The repo-level preconditions every repo-bound command shares (requireReadyRepo in
  * cli/cli-repo-gate.ts): git
  * on PATH, a repository, tumwater.json present, at least one commit. The first unmet one's
@@ -58,7 +59,7 @@ opencodeSeed = {}) {
     // A backend an enabled seam routes to that this build has no registered adapter for cannot
     // run its jobs: refuse to start rather than letting the run fall through to pi with a model
     // id pi cannot serve (plans/opencode-backend.md part 2/7). Read the registry through
-    // run-agent.ts, whose module scope registers the built-in pi and claude adapters.
+    // agent-run.ts, whose module scope registers the built-in pi and claude adapters.
     const unregistered = unregisteredBackendInUse(config);
     if (unregistered !== undefined) {
         return { problem: `backend ${unregistered} is configured but this build has no adapter for it` };
@@ -88,7 +89,7 @@ opencodeSeed = {}) {
     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`",
+            problem: codexApiKeyRefusalMessage("<home>"),
         };
     }
     // Seed the opencode models catalog (part 6b/7) before the first run: the poll surfaces price
@@ -189,16 +190,16 @@ export function opencodeProviders(config) {
     return [...providers];
 }
 /** Every agent backend an enabled seam resolves to — the distinct agents of the one
- * seamsInUse list (startup-gate's consumer of it), so a claude or pi clause that exists only
+ * seamsInUse list (startup-gates's consumer of it), so a claude or pi clause that exists only
  * as a fallback, the resolver, or the director is checked exactly like a primary seam.
  * One list the startup gate and doctor's binary check share, so a route the harness would
  * spawn is checked on both surfaces. */
 export function backendsInUse(config) {
-    return [...new Set(seamsInUse(config).map((s) => s.agent ?? "pi"))];
+    return distinctOrdered(seamsInUse(config).map((s) => s.agent ?? "pi"));
 }
 /** The first backend an enabled seam routes to that this build has no registered adapter for,
  * or undefined when every seam's backend is registered. The built-in pi and claude adapters
- * are registered by importing src/agent/run-agent.ts (see the import above); a seam backend
+ * are registered by importing src/agent/agent-run.ts (see the import above); a seam backend
  * that is not in the registry is one this build cannot run. Doctor's binary check asks the
  * same question, so the startup gate and doctor cannot disagree about which backend a build
  * can serve. opencode's and codex's adapters now register like pi's and claude's, so only a

package/dist/src/gates/{streak-gate.js → streak-gates.js}

@@ -1,9 +1,10 @@
 /** The error-streak circuit breaker (PLANS.md 2026-09-30): a role whose runs keep failing
  * consecutively is warned at ERROR_STREAK_WARN (src/run/run-apply.ts) and named by the team-wide
- * storm alarms (src/team/error-storm.ts, src/team/failure-spread.ts), but both only talk — the
- * role keeps running on the error ladder's 600 s max backoff forever, burning a model slot and
- * spend on a role that cannot succeed. Past ERROR_STREAK_BREAKER consecutive failed runs this gate
- * pauses the role through the same per-role pause marker the operator's `tumwater pause --role
+ * storm alarms (src/team/team-error-storm.ts, src/team/team-failure-spread.ts), but both
+ * only talk — the role keeps running on the error ladder's 600 s max backoff forever,
+ * burning a model slot and spend on a role that cannot succeed. Past ERROR_STREAK_BREAKER
+ * consecutive failed runs this gate pauses the role through the same per-role pause marker
+ * the operator's `tumwater pause --role
  * <id>` writes (src/team/team-state.ts's pauseRole — the marker, lock, and idempotence come
  * free), so the scheduler's existing pausedRolesSet skip blocks new runs with zero scheduler
  * changes. The director is NOT exempt: a failing director cannot process prompts anyway, and one
@@ -44,6 +45,73 @@ import { logEventBestEffort, TUMWATER_SOURCE } from "../events/events.js";
 export function newStreakGateState() {
     return { acked: new Map() };
 }
+/** Seed a fresh in-run ack cache from the persisted excused streak, so a restart keeps the
+ * grace the breaker (and a later operator resume) relies on instead of re-pausing a role
+ * whose frozen streak never ran down (BUGS.md 2026-10-23). */
+function seedStreakAck(state, role, s) {
+    if (!state.acked.has(role) && s.streakAcked !== undefined) {
+        state.acked.set(role, s.streakAcked);
+    }
+}
+/** Ack while paused: the marker is the ack carrier. The streak is frozen while a role is
+ * paused (no new runs start), so recording it here is exactly the level the resume excuses. */
+function ackPausedStreak(root, role, streak, s, state) {
+    if ((state.acked.get(role) ?? 0) !== streak) {
+        state.acked.set(role, streak);
+        s.streakAcked = streak;
+        saveRunnerStateBestEffort(root, s);
+    }
+}
+/** A streak that reset through the role's own success ends the excused episode: the next one
+ * must climb a fresh ERROR_STREAK_BREAKER of its own, so drop the durable ack too. */
+function clearResetStreak(root, role, s, state) {
+    if (state.acked.get(role) !== undefined) {
+        state.acked.delete(role);
+        delete s.streakAcked;
+        saveRunnerStateBestEffort(root, s);
+    }
+}
+/** Ack at trip time, before the pause is observed: the bar for the next trip is
+ * ERROR_STREAK_BREAKER more failures from this level, whether or not any poll sees the role
+ * paused in between (an operator resume racing the next poll must not re-trip). The durable
+ * copy is written only once the pause is confirmed below — a failed or crashed pauseRole must
+ * not leave a permanent excused ack with no marker behind it. Returns the pause key when the
+ * pause was written, undefined when pauseRole failed. */
+function tripStreakPause(root, role, streak, s, state, pauseKey) {
+    state.acked.set(role, streak);
+    if (!pauseRole(root, pauseKey(role)))
+        return undefined;
+    s.streakAcked = streak;
+    saveRunnerStateBestEffort(root, s);
+    logEventBestEffort(root, {
+        source: TUMWATER_SOURCE,
+        type: "role_streak_paused",
+        role: pauseKey(role),
+        streak,
+        ...(s.lastError ? { lastError: s.lastError } : {}),
+    });
+    return pauseKey(role);
+}
+/** One runner's turn in the poll: seed the in-run ack, ack while paused, clear on a reset,
+ * and trip past the bar. Returns the pause key when this poll tripped the role, undefined
+ * otherwise. The order is forced and unchanged: seed, then paused, then reset, then the bar,
+ * then trip. */
+function pollStreakRunner(root, role, s, state, pausedRoles, pauseKey) {
+    const streak = s.consecutiveErrors ?? 0;
+    seedStreakAck(state, role, s);
+    if (runnerPaused(pausedRoles, role)) {
+        ackPausedStreak(root, role, streak, s, state);
+        return undefined;
+    }
+    if (streak === 0) {
+        clearResetStreak(root, role, s, state);
+        return undefined;
+    }
+    const ack = state.acked.get(role) ?? 0;
+    if (streak < ERROR_STREAK_BREAKER + ack)
+        return undefined;
+    return tripStreakPause(root, role, streak, s, state, pauseKey);
+}
 /** Step the gate by one orchestrator poll. For each runner whose consecutive error streak
  * has reached ERROR_STREAK_BREAKER plus what its ack already excused, and whose role is not
  * in `pausedRoles`: write the per-role pause marker and log one `role_streak_paused` event
@@ -59,54 +127,9 @@ export function newStreakGateState() {
 export function pollStreakGate(root, state, runners, pausedRoles, pauseKey = (r) => r) {
     const tripped = [];
     for (const { role, state: s } of runners) {
-        const streak = s.consecutiveErrors ?? 0;
-        // Seed a fresh in-run ack cache from the persisted excused streak, so a restart keeps the
-        // grace the breaker (and a later operator resume) relies on instead of re-pausing a role
-        // whose frozen streak never ran down (BUGS.md 2026-10-23).
-        if (!state.acked.has(role) && s.streakAcked !== undefined) {
-            state.acked.set(role, s.streakAcked);
-        }
-        // Ack while paused: the marker is the ack carrier. The streak is frozen while a role is
-        // paused (no new runs start), so recording it here is exactly the level the resume excuses.
-        if (runnerPaused(pausedRoles, role)) {
-            if ((state.acked.get(role) ?? 0) !== streak) {
-                state.acked.set(role, streak);
-                s.streakAcked = streak;
-                saveRunnerStateBestEffort(root, s);
-            }
-            continue;
-        }
-        if (streak === 0) {
-            // A streak that reset through the role's own success ends the excused episode: the
-            // next one must climb a fresh ERROR_STREAK_BREAKER of its own, so drop the durable ack too.
-            if (state.acked.get(role) !== undefined) {
-                state.acked.delete(role);
-                delete s.streakAcked;
-                saveRunnerStateBestEffort(root, s);
-            }
-            continue;
-        }
-        const ack = state.acked.get(role) ?? 0;
-        if (streak < ERROR_STREAK_BREAKER + ack)
-            continue;
-        // Ack at trip time, before the pause is observed: the bar for the next trip is
-        // ERROR_STREAK_BREAKER more failures from this level, whether or not any poll sees the
-        // role paused in between (an operator resume racing the next poll must not re-trip). The
-        // durable copy is written only once the pause is confirmed below — a failed or crashed
-        // pauseRole must not leave a permanent excused ack with no marker behind it.
-        state.acked.set(role, streak);
-        if (pauseRole(root, pauseKey(role))) {
-            s.streakAcked = streak;
-            saveRunnerStateBestEffort(root, s);
-            logEventBestEffort(root, {
-                source: TUMWATER_SOURCE,
-                type: "role_streak_paused",
-                role: pauseKey(role),
-                streak,
-                ...(s.lastError ? { lastError: s.lastError } : {}),
-            });
-            tripped.push(pauseKey(role));
-        }
+        const key = pollStreakRunner(root, role, s, state, pausedRoles, pauseKey);
+        if (key !== undefined)
+            tripped.push(key);
     }
     return tripped;
 }

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

@@ -5,6 +5,10 @@
 import { changeBaseRev, gitLines } from "./git.js";
 import { git, gitTry } from "./git-run.js";
 import { cutSplitsSurrogatePair } from "../text/text.js";
+/** The one cap on a fetched change diff, shared by the repo-relative patch (aheadOfMainDiff,
+ * revisionInterdiff) and the view half's uncommitted patch (change-data.ts) so neither side
+ * of a reviewed change can print unbounded text and one bound is all they agree on. */
+export const DIFF_MAX_BYTES = 200_000;
 /** Git's C-quoting short escapes (its `sq_lookup` table) and the byte each decodes to. The
  * mapping was a nine-case switch that repeated `bytes += …; break;` per entry; keeping it as
  * data lets the decoder below handle the octal and literal fallbacks in one place. */
@@ -153,7 +157,7 @@ function splitDiffByFile(diff) {
  * see, and a binary file's short "Binary files differ" stub naturally ranks below any real text
  * change. A failed `git diff` throws: the reviewer handed an empty diff judged no change at
  * all. A view catches it itself. */
-export async function aheadOfMainDiff(wt, mainBranch, maxBytes = 200_000, pathspec = []) {
+export async function aheadOfMainDiff(wt, mainBranch, maxBytes = DIFF_MAX_BYTES, pathspec = []) {
     const range = `${mainBranch}...HEAD`;
     const full = await git(wt, "diff", range, ...pathspec);
     if (full.length <= maxBytes)
@@ -181,7 +185,7 @@ export async function aheadOfMainDiff(wt, mainBranch, maxBytes = 200_000, pathsp
  * the two versions even when the change is tiny: at the default 60% a two-line addition can
  * fail to pair and render as two unrelated commits (`<`/`>`), which is exactly the case a
  * small revision is. */
-export async function revisionInterdiff(wt, mainBranch, priorSha, head, maxBytes = 200_000) {
+export async function revisionInterdiff(wt, mainBranch, priorSha, head, maxBytes = DIFF_MAX_BYTES) {
     try {
         const priorBase = await changeBaseRev(wt, mainBranch, priorSha);
         const headBase = await changeBaseRev(wt, mainBranch, head);

package/dist/src/git/git.js

@@ -64,40 +64,57 @@ const GIT_REDIRECT_ENV = ["GIT_DIR", "GIT_COMMON_DIR", "GIT_WORK_TREE", "GIT_NAM
 /** Refs git keeps per worktree (in the worktree's own git dir, not the common one). They are
  * left to git. */
 const PER_WORKTREE_REF = /^refs\/(?:bisect|worktree|rewritten)\//;
-/** `dir`'s git dirs when its `.git` resolves from files to a files-backend repository this
- * process's user owns, or undefined when git should decide. */
-function repoFiles(dir) {
-    if (GIT_REDIRECT_ENV.some((name) => process.env[name]))
-        return undefined;
-    const uid = process.getuid?.();
-    if (uid === undefined)
-        return undefined;
-    const gitdir = resolveGitDir(dir);
-    if (gitdir === undefined)
-        return undefined;
-    let commondir = gitdir;
+/** Whether an environment variable makes git look somewhere other than the files `dir` holds. */
+function gitRedirectsSet() {
+    return GIT_REDIRECT_ENV.some((name) => process.env[name]);
+}
+/** The shared refs/objects dir a gitdir points at via its `commondir` file: the gitdir itself
+ * when there is no file (a primary checkout), the resolved pointer when there is, and
+ * undefined when the file is blank or unreadable for any reason but absence. */
+function resolveCommondir(gitdir) {
     try {
         const pointer = fs.readFileSync(path.join(gitdir, "commondir"), "utf8").trim();
         if (pointer === "")
             return undefined;
-        commondir = path.resolve(gitdir, pointer);
+        return path.resolve(gitdir, pointer);
     }
     catch (err) {
         if (errCode(err) !== "ENOENT")
             return undefined; // A primary checkout has none.
+        return gitdir;
     }
+}
+/** Whether the files-backend trust checks hold: this process's user owns both dirs, the
+ * objects dir and HEAD are present, and no reftable store shadows them. */
+function filesBackendTrusted(dir, gitdir, commondir, uid) {
     try {
         if (fs.statSync(dir).uid !== uid || fs.statSync(gitdir).uid !== uid)
-            return undefined;
+            return false;
         if (!fs.statSync(path.join(commondir, "objects")).isDirectory())
-            return undefined;
+            return false;
         if (!fs.statSync(path.join(gitdir, "HEAD")).isFile())
-            return undefined;
+            return false;
     }
     catch {
-        return undefined;
+        return false;
     }
-    if (fs.existsSync(path.join(commondir, "reftable")))
+    return !fs.existsSync(path.join(commondir, "reftable"));
+}
+/** `dir`'s git dirs when its `.git` resolves from files to a files-backend repository this
+ * process's user owns, or undefined when git should decide. */
+function repoFiles(dir) {
+    if (gitRedirectsSet())
+        return undefined;
+    const uid = process.getuid?.();
+    if (uid === undefined)
+        return undefined;
+    const gitdir = resolveGitDir(dir);
+    if (gitdir === undefined)
+        return undefined;
+    const commondir = resolveCommondir(gitdir);
+    if (commondir === undefined)
+        return undefined;
+    if (!filesBackendTrusted(dir, gitdir, commondir, uid))
         return undefined;
     return { gitdir, commondir };
 }
@@ -147,35 +164,33 @@ function storedRef(commondir, ref) {
     }
     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`
- * is HEAD (followed when it is a branch symref or a detached SHA), a full `refs/…` name, or a
- * short branch name, taken only when git's DWIM order could not resolve it to anything else
- * first (`<gitdir>/<name>`, `refs/<name>`, `refs/tags/<name>` all absent). */
-export function refShaFromFiles(dir, ref) {
-    const repo = repoFiles(dir);
-    if (repo === undefined)
-        return undefined;
-    if (ref === "HEAD") {
-        let head;
-        try {
-            head = fs.readFileSync(path.join(repo.gitdir, "HEAD"), "utf8").trim();
-        }
-        catch {
-            return undefined;
-        }
-        if (isSha(head))
-            return head;
-        const target = head.startsWith("ref: ") ? head.slice("ref: ".length).trim() : "";
-        if (!target.startsWith("refs/heads/") || !isPlainRefName(target))
-            return undefined;
-        return storedRef(repo.commondir, target) ?? undefined;
+/** The HEAD read: the detached SHA held in `<repo.gitdir>/HEAD`, else the SHA its `ref: `
+ * branch symref (a plain `refs/heads/…` name) resolves to, or undefined when the files do not
+ * settle it. */
+function refShaFromHead(repo) {
+    let head;
+    try {
+        head = fs.readFileSync(path.join(repo.gitdir, "HEAD"), "utf8").trim();
     }
-    if (ref.startsWith("refs/")) {
-        if (!isPlainRefName(ref) || PER_WORKTREE_REF.test(ref))
-            return undefined;
-        return storedRef(repo.commondir, ref) ?? undefined;
+    catch {
+        return undefined;
     }
+    if (isSha(head))
+        return head;
+    const target = head.startsWith("ref: ") ? head.slice("ref: ".length).trim() : "";
+    if (!target.startsWith("refs/heads/") || !isPlainRefName(target))
+        return undefined;
+    return storedRef(repo.commondir, target) ?? undefined;
+}
+/** A full `refs/…` name: its plain-name and per-worktree guards, then the stored read. */
+function refShaFromFullRefName(repo, ref) {
+    if (!isPlainRefName(ref) || PER_WORKTREE_REF.test(ref))
+        return undefined;
+    return storedRef(repo.commondir, ref) ?? undefined;
+}
+/** A short branch name: the DWIM-order guards (`<gitdir>/<name>`, `refs/<name>` and
+ * `refs/tags/<name>` all outrank the branch), then `refs/heads/<name>`. */
+function refShaFromShortName(repo, ref) {
     // A full object name means the object to git, ahead of any same-named ref.
     if (isSha(ref) || !isPlainRefName(`refs/heads/${ref}`))
         return undefined;
@@ -189,6 +204,21 @@ export function refShaFromFiles(dir, ref) {
     }
     return storedRef(repo.commondir, `refs/heads/${ref}`) ?? undefined;
 }
+/** 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`
+ * is HEAD (followed when it is a branch symref or a detached SHA), a full `refs/…` name, or a
+ * short branch name, taken only when git's DWIM order could not resolve it to anything else
+ * first (`<gitdir>/<name>`, `refs/<name>`, `refs/tags/<name>` all absent). */
+export function refShaFromFiles(dir, ref) {
+    const repo = repoFiles(dir);
+    if (repo === undefined)
+        return undefined;
+    if (ref === "HEAD")
+        return refShaFromHead(repo);
+    if (ref.startsWith("refs/"))
+        return refShaFromFullRefName(repo, ref);
+    return refShaFromShortName(repo, ref);
+}
 /** False when the files settle that `root`'s repository has no linked-worktree registrations
  * (its `<commondir>/worktrees` admin dir is absent or empty), so `git worktree prune` has
  * nothing to do. True when there are some, and undefined when git should decide. */

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

@@ -19,7 +19,6 @@ import { beginWorktreeUse } from "./worktree-use.js";
 import { ensureDetachedWorktree, removeWorktreeDir } from "./worktree.js";
 import { logEventBestEffort, warnEventBestEffort, tryOrWarn, TUMWATER_SOURCE } from "../events/events.js";
 import { errorMessage } from "../text/text.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();
@@ -192,11 +191,9 @@ 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 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();
+        // The pool-slot wait needs no permit dropped: a run or verify holds only the one team
+        // permit (no provider key any more), so it parks on the busy pool like any other slot
+        // waiter.
         const waiter = registerWaiter(root);
         try {
             await raceAbort(waiter.promise, signal);

package/dist/src/gui/gui-admin-endpoints.js

@@ -2,13 +2,13 @@
  * The dashboard's GET settings/admin handlers (src/gui/gui-server.ts routes to them):
  * prompt-text, doctor, config, retire-list, and brief. Each answers its request and touches no
  * socket beyond its own `res`; the domain work lives one layer down (doctor/doctor.js,
- * config/config.js, operator/retire.js), so this module only adapts HTTP onto it. Barrelled
- * into gui/gui-endpoints.ts beside the other per-family GET endpoint modules.
+ * config/config.js, operator/operator-retire.js), so this module only adapts HTTP onto it.
+ * it is barrelled into gui/gui-endpoints.ts beside the other per-family GET endpoint modules.
  */
 import { runDoctor } from "../doctor/doctor.js";
 import { knownRoleIds, loadConfigSafe } from "../config/config.js";
 import { runnerEnabled } from "../roles/runner-ids.js";
-import { artifactPhrase, previewRetire } from "../operator/retire.js";
+import { artifactPhrase, previewRetire } from "../operator/operator-retire.js";
 import { EDITABLE_CONFIG_KEYS } from "../config/config-editable-keys.js";
 import { readBrief } from "../brief/brief.js";
 import { readQueuedPromptBody } from "../inbox/inbox-edit.js";

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

@@ -80,6 +80,18 @@ export function rejectBadQueueFileName(res, name) {
     badRequest(res, problem);
     return true;
 }
+/** Pull a required `sha` commit id out of a POST body by the rule the History revert, the
+ * merge-queue cancel/top, and the post-review accept endpoints share: a value that is not a
+ * 4-64 hex-digit commit id (so never a flag or a ref name) is refused as a 400 naming the
+ * value. Returns the validated commit id, or null once the 400 is sent — the body-sha twin of
+ * requireStringField / requirePausedFlag, so the four operators' validation and 400 wording
+ * cannot drift. */
+export function requireSha(res, sha) {
+    if (typeof sha === "string" && /^[0-9a-f]{4,64}$/i.test(sha))
+        return sha;
+    badRequest(res, `"sha" must be a hex commit id of 4-64 digits${gotSuffix(sha)}`);
+    return null;
+}
 /** Read an integer query parameter with the GUI's established discipline for an explicit
  * count: absent → `fallback` (or, when no fallback is given, the parameter is required and
  * its absence is its own 400 — "<name> required"); present but not a plain decimal integer

package/dist/src/gui/gui-backlog-commands.js

@@ -4,7 +4,7 @@
  * question-answer, backlog-file, backlog-cancel, backlog-release, backlog-top, and
  * backlog-edit — the `checkedBacklogKind` / `checkedEntryPositionAndTitle` validators they share
  * ride with them. Each handler adapts
- * HTTP onto the domain work one layer down (backlog-write, question-answer, backlog-commit)
+ * HTTP onto the domain work one layer down (backlog-write, backlog-question-answer, backlog-commit)
  * and touches no socket beyond its own `res`.
  */
 import { backlogHolds, cancelledClaimNote, stillHeldNote } from "../backlog/backlog-eligibility.js";
@@ -15,7 +15,7 @@ import { commitOperatorBacklogEdit } from "../backlog/backlog-commit.js";
 import { stampedSubject } from "../git/commit-message.js";
 import { fileEntryWithBody, normalizeEntryBody, OPERATOR_FILE_KINDS, tryCancelEntry, tryEditEntry, bodyStructureProblem } from "../backlog/backlog-write.js";
 import { tryMoveEntryToTop, tryReleaseEntry } from "../backlog/backlog-release.js";
-import { tryAnswerQuestion, UNCLOSED_FENCE_MESSAGE } from "../backlog/question-answer.js";
+import { tryAnswerQuestion, UNCLOSED_FENCE_MESSAGE } from "../backlog/backlog-question-answer.js";
 import { promptLengthProblem } from "../inbox/inbox-submit.js";
 import { requestWake, submitRolePromptAndWake, wakeQuestionAsker } from "../operator/operator-intent.js";
 import { badRequest, okGone, sendJson } from "./gui-http-body.js";
@@ -202,8 +202,8 @@ async function respondBacklogWrite(res, root, kind, position, outcome, verb, sta
  * `tumwater plan|bug --release <n>` through the non-exiting tryReleaseEntry. Body as
  * backlog-cancel's. A released entry that is not still held is newly eligible, so the kind's
  * role is woken (a held one wakes no role and carries `heldNote`); `gone` and `moved` answer
- * okGone, and an entry with none of the Refused or
- * held-for-operator notes answers status "not_refused" with no write and no wake. */
+ * okGone, and an entry with no Refused or Needs review note answers status "not_refused" with no
+ * write and no wake. */
 export async function handleBacklogRelease(req, res, root) {
     const body = await readPostBody(req, res, '{"kind": "bug", "position": 1, "title": "<heading>"}');
     if (!body)