tumwater 0.4.2 → 0.4.3

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

@@ -9,15 +9,15 @@ 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 { 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 +58,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 +88,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,7 +189,7 @@ 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. */
@@ -198,7 +198,7 @@ export function backendsInUse(config) {
 }
 /** 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.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-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)

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

@@ -87,6 +87,62 @@ export function handleBacklogMatch(q, res, root) {
         .map((row) => ({ role: row.role, file: row.file }));
     sendJson(res, 200, out);
 }
+/** Normalise an optional `?path=` query arg to `{ path }` (absent → `{ path: undefined }`),
+ * answering the shared 400 when the raw value does not name a repo-relative path. Shared by
+ * the `?overlaps` and `?role` arms; `null` means the 400 was sent, so the caller returns. */
+function diffPathParam(res, rawPath) {
+    if (rawPath === null)
+        return { path: undefined };
+    const path = normalizeDiffPath(rawPath);
+    if (path === null) {
+        badRequest(res, "path takes a repo-relative path such as src/cli.ts (as overlaps lists it)");
+        return null;
+    }
+    return { path };
+}
+/** The `?overlaps` view: refuse stat, normalise the path, resolve the comma-separated role
+ * list, collect the overlaps and scope them by roles then by path, then send. */
+async function handleDiffOverlaps(q, res, root, rawPath, stat) {
+    if (stat) {
+        badRequest(res, "overlaps lists paths, not patches; drop stat");
+        return;
+    }
+    const opath = diffPathParam(res, rawPath);
+    if (opath === null)
+        return;
+    const roles = roleListQuery(q, res, root);
+    if (roles === null)
+        return;
+    let view = await collectChangeOverlaps(root);
+    if (roles !== undefined)
+        view = scopeChangeOverlaps(view, roles);
+    if (opath.path !== undefined)
+        view = scopeChangeOverlapsToPath(view, opath.path);
+    sendJson(res, 200, view);
+}
+/** The role-less team roster: refuse stat and path with their own 400s, then send
+ * collectTeamChanges's document. */
+async function handleDiffTeam(res, root, rawPath, stat) {
+    if (stat) {
+        badRequest(res, "stat needs role (the team roster carries no patch)");
+        return;
+    }
+    if (rawPath !== null) {
+        badRequest(res, "path needs role (the team roster carries no patch)");
+        return;
+    }
+    sendJson(res, 200, await collectTeamChanges(root));
+}
+/** The `?role=<id>` per-role view: validate through rejectBadRole, normalise the shared path,
+ * then send collectRoleChange with its path and stat options. */
+async function handleDiffRole(res, root, role, rawPath, stat) {
+    if (rejectBadRole(root, res, role))
+        return;
+    const path = diffPathParam(res, rawPath);
+    if (path === null)
+        return;
+    sendJson(res, 200, await collectRoleChange(root, role, { ...(path.path === undefined ? {} : { path: path.path }), ...(stat ? { stat: true } : {}) }));
+}
 /** Handle GET /api/diff[?role=<id>]: the unmerged-change view the CLI prints from the same
  * collectors — no `role` → collectTeamChanges (exactly `tumwater diff --json`'s document:
  * `{ mainBranch, roles }`, no per-role patch halves); `?role=<id>` → collectRoleChange (the
@@ -105,46 +161,10 @@ export function handleBacklogMatch(q, res, root) {
 export async function handleDiff(q, res, root) {
     const rawPath = q.get("path");
     const stat = q.get("stat") !== null;
-    if (q.get("overlaps") !== null) {
-        if (stat) {
-            badRequest(res, "overlaps lists paths, not patches; drop stat");
-            return;
-        }
-        const opath = rawPath === null ? undefined : normalizeDiffPath(rawPath);
-        if (opath === null) {
-            badRequest(res, "path takes a repo-relative path such as src/cli.ts (as overlaps lists it)");
-            return;
-        }
-        const roles = roleListQuery(q, res, root);
-        if (roles === null)
-            return;
-        let view = await collectChangeOverlaps(root);
-        if (roles !== undefined)
-            view = scopeChangeOverlaps(view, roles);
-        if (opath !== undefined)
-            view = scopeChangeOverlapsToPath(view, opath);
-        sendJson(res, 200, view);
-        return;
-    }
+    if (q.get("overlaps") !== null)
+        return handleDiffOverlaps(q, res, root, rawPath, stat);
     const role = q.get("role");
-    if (role === null) {
-        if (stat) {
-            badRequest(res, "stat needs role (the team roster carries no patch)");
-            return;
-        }
-        if (rawPath !== null) {
-            badRequest(res, "path needs role (the team roster carries no patch)");
-            return;
-        }
-        sendJson(res, 200, await collectTeamChanges(root));
-        return;
-    }
-    if (rejectBadRole(root, res, role))
-        return;
-    const path = rawPath === null ? undefined : normalizeDiffPath(rawPath);
-    if (path === null) {
-        badRequest(res, "path takes a repo-relative path such as src/cli.ts (as overlaps lists it)");
-        return;
-    }
-    sendJson(res, 200, await collectRoleChange(root, role, { ...(path === undefined ? {} : { path }), ...(stat ? { stat: true } : {}) }));
+    if (role === null)
+        return handleDiffTeam(res, root, rawPath, stat);
+    return handleDiffRole(res, root, role, rawPath, stat);
 }

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

@@ -32,29 +32,19 @@ export function lanAddresses(interfaces = os.networkInterfaces()) {
  * /proc/<pid>/cmdline exposes to every local user and what a reload re-runs verbatim — so the
  * secret must travel by env, never argv. */
 export const GUI_TOKEN_ENV = "TUMWATER_GUI_TOKEN";
-/** The `tumwater gui` command: parse the --port/--all-interfaces/--token flags, start the
- * server, print the banner, and serve until Ctrl+C. Lives beside startGui (gui/gui-server.ts) so
- * the CLI's gui-specific policy (token validation, the listen-failure messages, the LAN
- * announcement) cannot drift from the server it drives. Flag-vocabulary rejection stays in
- * cli.ts with the other cases; everything gui-specific after that gate is this function's job.
- * A failed listen throws (cli.ts's main catch renders it as the same `tumwater: …` line and
- * exit 1 fail() would) so the listen-failure wordings stay assertable in-process. */
-export async function cmdGui(root, args, seams = {}) {
-    const start = seams.startGui ?? startGui;
-    const lan = seams.lanAddresses ?? lanAddresses;
-    const print = seams.say ?? say;
-    const serve = seams.serve ?? (() => new Promise(() => { }));
-    const portRaw = flagValue(args, "--port");
-    const port = portRaw !== null ? parsePortFlag(portRaw) : 7180;
-    const allInterfaces = args.includes("--all-interfaces");
-    // A valueless or empty --token is a CLI error, not an open server: an operator who
-    // asked for protection must never silently get none. The validation and its wording
-    // live in tokenValueProblem, shared with `start --gui` so the two callers cannot
-    // drift; its flag-looking-value case names `tumwater gui` here.
-    const problem = tokenValueProblem(args, "tumwater gui");
-    if (problem)
-        fail(problem);
-    const flagToken = flagValue(args, "--token");
+/** Resolve cmdGui's four injectable seams to their runnable forms: the server it starts, the
+ * LAN address source the banner names, the printer for the banner and warnings, and the
+ * serve-until-Ctrl+C wait. Production callers omit every seam and get the real server,
+ * interfaces, stdout, and wait. */
+function resolveGuiSeams(seams) {
+    return {
+        start: seams.startGui ?? startGui,
+        lan: seams.lanAddresses ?? lanAddresses,
+        print: seams.say ?? say,
+        serve: seams.serve ?? (() => new Promise(() => { })),
+    };
+}
+function adoptGuiToken(flagToken, print) {
     // A direct `tumwater gui --token` puts the secret on its own argv — readable by any local
     // user and re-run verbatim by reexecSelf onto every reloaded generation — so fold it into
     // the env and take it off the command line before a redeploy can re-expose it. A child
@@ -66,7 +56,10 @@ export async function cmdGui(root, args, seams = {}) {
         process.argv.splice(argvToken, 2);
         print(`--token is visible to every local user in this process's command line (\`ps\`, /proc/<pid>/cmdline) and is re-run onto each reloaded generation — prefer the ${GUI_TOKEN_ENV} env var`);
     }
-    const token = flagToken ?? process.env[GUI_TOKEN_ENV] ?? "";
+    return flagToken ?? process.env[GUI_TOKEN_ENV] ?? "";
+}
+/** Start the server and translate the two common listen failures into hints naming their fix. */
+async function startGuiOrExplain(start, root, port, allInterfaces, token) {
     try {
         await start(root, port, allInterfaces, token);
     }
@@ -83,6 +76,9 @@ export async function cmdGui(root, args, seams = {}) {
             throw new Error(`port ${port} could not be opened (permission denied) — ports below 1024 need root; pick an unprivileged port with \`tumwater gui --port <n>\``);
         throw err;
     }
+}
+/** Print the localhost banner and, under --all-interfaces, the LAN URLs and exposure wording. */
+function printGuiBanner(print, lan, port, allInterfaces, token) {
     const tokenSuffix = token ? `/?token=${encodeURIComponent(token)}` : "";
     print(`tumwater gui at http://127.0.0.1:${port}${tokenSuffix} — Ctrl+C to stop`);
     if (allInterfaces) {
@@ -95,5 +91,28 @@ export async function cmdGui(root, args, seams = {}) {
             ? "listening on ALL interfaces — token-protected; prompting the director requires the token"
             : "listening on ALL interfaces — no auth; anyone reaching it can prompt the director");
     }
+}
+/** The `tumwater gui` command: parse the --port/--all-interfaces/--token flags, start the
+ * server, print the banner, and serve until Ctrl+C. Lives beside startGui (gui/gui-server.ts) so
+ * the CLI's gui-specific policy (token validation, the listen-failure messages, the LAN
+ * announcement) cannot drift from the server it drives. Flag-vocabulary rejection stays in
+ * cli.ts with the other cases; everything gui-specific after that gate is this function's job.
+ * A failed listen throws (cli.ts's main catch renders it as the same `tumwater: …` line and
+ * exit 1 fail() would) so the listen-failure wordings stay assertable in-process. */
+export async function cmdGui(root, args, seams = {}) {
+    const { start, lan, print, serve } = resolveGuiSeams(seams);
+    const portRaw = flagValue(args, "--port");
+    const port = portRaw !== null ? parsePortFlag(portRaw) : 7180;
+    const allInterfaces = args.includes("--all-interfaces");
+    // A valueless or empty --token is a CLI error, not an open server: an operator who
+    // asked for protection must never silently get none. The validation and its wording
+    // live in tokenValueProblem, shared with `start --gui` so the two callers cannot
+    // drift; its flag-looking-value case names `tumwater gui` here.
+    const problem = tokenValueProblem(args, "tumwater gui");
+    if (problem)
+        fail(problem);
+    const token = adoptGuiToken(flagValue(args, "--token") ?? null, print);
+    await startGuiOrExplain(start, root, port, allInterfaces, token);
+    printGuiBanner(print, lan, port, allInterfaces, token);
     await serve(); // Serve until Ctrl+C.
 }