tumwater 0.2.0 → 0.3.0

package/dist/src/build/build-check-report.js

@@ -1,4 +1,3 @@
-// vocabulary: plain
 /** Pure formatting and description of a build check's failure output — split out of build-check.ts,
  * which keeps the execution side (detect → run → classify, the toolchain probe, the process-group
  * runner). This module turns a check's raw combined output and a BuildCheckOutcome into the machine
@@ -6,7 +5,7 @@
  * review-verdict.ts's parseVerdict), the clipped output tail (clipBuildTail), the one-line headline
  * a warning names the failure by (failureHeadline), the check's human-facing command name
  * (describeCheck), and the reasons a red check hands its author (checkFailureReasons). Every
- * consumer of a check's tail — the review gate, the merge path, the red-main gate, the tick prompt
+ * consumer of a check's tail — the review gate, the merge path, the red-main gate, the run prompt
  * — imports from here, so "which line is the headline" and "how much output survives" have one
  * answer each. Type-only back-reference to build-check.ts for BuildCheckOutcome (no runtime cycle);
  * BuildCheck comes from build-check-detect.ts. */
@@ -30,17 +29,47 @@ const ERROR_MESSAGE_LINE = /^\S*Error\b[^:]*:\s/;
  * `✖` line but the `✖ failing tests:` section header. The run's LAST one is the failure whose
  * detail ends the output, so it names the test the tail's message and stack belong to. */
 const FAILED_TEST_LINE = /^✖ (?!failing tests:)/;
+/** A stack frame inside Node's own runtime (the test runner, the task queue): the same in every
+ * failure and silent about the code under test. Matches `at fn (node:internal/…)` and a bare
+ * `at node:internal/…`; not frames in other built-in modules (`node:fs`, `node:async_hooks`) nor
+ * in project files. */
+const NODE_INTERNAL_FRAME = /^at\s(?:.*\()?node:internal\//;
+/** How many failing test titles parseFailingTests keeps; a list that long may be cut short. */
+export const FAILING_TESTS_MAX = 50;
+/** The titles of the tests a check's COMPLETE output reports failed: every line FAILED_TEST_LINE
+ * matches, its trailing duration stripped, deduplicated (node:test prints a failure in the tree and
+ * again under `✖ failing tests:`), in output order, at most FAILING_TESTS_MAX. Read the full
+ * output, before clipBuildTail cuts it. Empty for output from another runner. */
+export function parseFailingTests(output) {
+    const titles = new Set();
+    for (const raw of output.split("\n")) {
+        const line = raw.trim();
+        if (!FAILED_TEST_LINE.test(line))
+            continue;
+        const title = line.slice(2).replace(/ \([\d.]+m?s\)$/, "").trim();
+        if (title !== "")
+            titles.add(title);
+        if (titles.size >= FAILING_TESTS_MAX)
+            break;
+    }
+    return [...titles];
+}
 /** Keep the TAIL of a build's combined output: last ≤10 meaningful lines, each via clipReason —
- * so a chatty build cannot bloat persisted state or the injected next-tick note. Blank lines
+ * so a chatty build cannot bloat persisted state or the injected next-run note. Blank lines
  * and npm's own script banner (`> pkg@1.0 script`, `> <command>`) are dropped: they name the
  * script that ran, not what broke in it. When the ten-line window cuts off the error-message
  * line that sits above the stack, the nearest such line is kept as well, so failureHeadline can
  * name the failure instead of a stack frame or an error property; likewise the failed test's
  * name line (FAILED_TEST_LINE) above it, so the headline says WHICH test — an assertion's
  * message alone (`Expected values to be strictly equal:`) names none, and a flake reported only
- * that way could not be traced (BUGS.md 2026-09-30). Twelve lines at most. */
+ * that way could not be traced (BUGS.md 2026-09-30). Frames NODE_INTERNAL_FRAME matches are dropped
+ * first so the window keeps more of the assertion's diff (output made only of them is kept as is);
+ * when the dropped frame is `at async Test.processPendingSubtests (…) {`, the property dump's
+ * opening `{` goes with it. Twelve lines at most. */
 export function clipBuildTail(output) {
-    const lines = output.split("\n").map((l) => l.trim()).filter((l) => l !== "" && !/^>\s/.test(l));
+    const meaningful = output.split("\n").map((l) => l.trim()).filter((l) => l !== "" && !/^>\s/.test(l));
+    const external = meaningful.filter((l) => !NODE_INTERNAL_FRAME.test(l));
+    const lines = external.length > 0 ? external : meaningful;
     const tail = lines.slice(-10);
     const cut = [...lines.slice(0, -10)].reverse();
     const message = cut.find((l) => ERROR_MESSAGE_LINE.test(l));
@@ -89,18 +118,21 @@ export function failureHeadline(tail) {
         return what !== undefined ? `${name} — ${what}` : name;
     return what ?? tail[0];
 }
-/** The human/prompt-facing name of a check (plans/portability.md §6/7): the tick prompt and
+/** The human/prompt-facing name of a check (plans/portability.md §6/7): the run prompt and
  * the gate's check reasons name the actual verification command instead of asserting npm —
  * "verify with `pytest -q`" in a Python repo, "`npm run test`" in an npm one. */
 export function describeCheck(check) {
     return check.kind === "npm" ? `\`npm run ${check.script}\`` : `\`${check.command}\``;
 }
 /** The machine-generated reasons a red check hands its author: the headline joined to the rest of
- * the clipped tail, so the compiler error sits right after it in the injected next-tick note. The
+ * the clipped tail, so the compiler error sits right after it in the injected next-run note. The
  * headline is failureHeadline's — the first line that is not a stack frame — not outputTail[0]: a
  * suite that dies on an unhandled rejection opens mid-stack, and naming the frame tells the author
  * where it broke, never what (BUGS.md 2026-09-19). One definition for every red that rejects a
- * change: the gate's pre-check, a batch's single-change red, and a single merge's in-lock check. */
+ * change: the gate's pre-check, a batch's single-change red, and a single merge's in-lock check.
+ * In the verified branch, tail lines the headline already carries are dropped: the headline
+ * itself, the test-name or marker line (duration removed) it opens with, and the message line it
+ * ends with. */
 export function checkFailureReasons(check, outcome) {
     const tail = outcome.outputTail ?? [];
     // An unverified rejection already says what happened — the check never finished, the tree is
@@ -114,6 +146,14 @@ export function checkFailureReasons(check, outcome) {
     const headline = failureHeadline(tail);
     const what = describeCheck(check);
     return headline !== undefined
-        ? [`check failed (${what}): ${headline}`, ...tail.filter((l) => l !== headline)]
+        ? [`check failed (${what}): ${headline}`, ...tail.filter((l) => !headlineCarries(headline, l))]
         : [`check failed (${what})`];
 }
+/** Whether a failureHeadline already says tail line `l`: equal to it, its name part (duration
+ * removed), or the message after its ` — `. */
+function headlineCarries(headline, l) {
+    if (l === headline || headline.endsWith(` — ${l}`))
+        return true;
+    const bare = l.replace(/ \([\d.]+m?s\)$/, "");
+    return bare === headline || headline.startsWith(`${bare} — `);
+}

package/dist/src/build/build-check-scoped.js

@@ -1,7 +1,7 @@
-import { BUILD_CHECK_TIMEOUT_MS, detectBuildCheck, gateCommandOf, } from "./build-check-detect.js";
+import { BUILD_CHECK_TIMEOUT_MS, detectBuildCheck, gateCommandOf, mergeCommandOf, } from "./build-check-detect.js";
 import { runBuildCheck, checkScriptName, checkTimeoutMs, } from "./build-check.js";
 import { logEventBestEffort, warnEventBestEffort } from "../events/events.js";
-import { MERGE_SCOPES, SCOPE_WORDS, buildCheckEvent, buildCheckSkipWarning, runWithCleanRetry, installFailedPhrase, killedPhrase, loadedHostPhrase, timedOutPhrase, DEADLINE_LATE_TOLERANCE_MS, SLEEP_SPAN_TOLERANCE_MS, sleptPhrase, starvedDeadlineMs, UNVERIFIED_TREE, } from "./build-check-events.js";
+import { MERGE_SCOPES, SCOPE_WORDS, buildCheckEvent, buildCheckSkipWarning, runWithCleanRetry, installFailedPhrase, killedPhrase, loadedHostPhrase, timedOutPhrase, DEADLINE_LATE_TOLERANCE_MS, logCheckWaitEvent, SLEEP_SPAN_TOLERANCE_MS, sleptPhrase, starvedDeadlineMs, UNVERIFIED_TREE, } from "./build-check-events.js";
 import { CHECK_TIER, withCheckPermit } from "../concurrency/check-permit.js";
 import { sampleHostLoad, sampleSleepClock } from "./host-sleep.js";
 import { npmInstall } from "./dep-install.js";
@@ -27,14 +27,17 @@ import { npmInstall } from "./dep-install.js";
  * own host-sleep evidence) earns that same one retry at any scope, and a failed run the host slept
  * through does too; each attempt is priced as its own build_check event, carrying when the check
  * itself ran (buildCheckRunFields). A configured `check.gateCommand` replaces the command at scope
- * "gate" only (same cwd and timeout); the merge and batch scopes — and the red-main baseline, which
- * detects on its own — keep running check.command. `permitWait` hears about a wait for the check
- * permit (the merge cell's "waiting for a check slot"). Never throws. */
+ * "gate" only (same cwd and timeout); the in-lock command (Fast merge "Defaults", mergeCommandOf) —
+ * `check.mergeCommand` when set, else `check.gateCommand`, else the full check — replaces it at the
+ * merge and batch scopes, and those events then carry `full: false`. The red-main baseline, which
+ * detects on its own, keeps running check.command. `permitWait` hears
+ * about a wait for the check permit (the merge cell's "waiting for a check slot"). Never throws. */
 export async function runScopedBuildCheck(root, role, scope, wt, config, timeoutMs = BUILD_CHECK_TIMEOUT_MS, sampleSleep = sampleSleepClock, install = npmInstall, permitWait, sampleLoad = sampleHostLoad) {
-    const gateCommand = scope === "gate" ? gateCommandOf(config) : undefined;
-    const check = detectBuildCheck(wt, gateCommand === undefined ? config : { check: { ...config?.check, command: gateCommand } });
+    const swapped = scope === "gate" ? gateCommandOf(config) : MERGE_SCOPES.has(scope) ? mergeCommandOf(config) : undefined;
+    const check = detectBuildCheck(wt, swapped === undefined ? config : { check: { ...config?.check, command: swapped } });
     if (!check)
         return null;
+    const cheaper = scope !== "gate" && swapped !== undefined;
     // A configured check.timeoutSeconds bounds either kind; otherwise an npm check runs under the
     // caller's bound. Effective here so the reason text and the skip warning agree with what
     // runBuildCheck enforced.
@@ -59,10 +62,14 @@ export async function runScopedBuildCheck(root, role, scope, wt, config, timeout
         // outcome stands (runWithCleanRetry). The verdict-less first attempt is priced as its own
         // event (the feed must answer how long a check took), then the final event below records
         // the retry's classified outcome.
-        const { outcome, durationMs: d } = await runWithCleanRetry(() => runBuildCheck(wt, runCheck, timeoutMs, undefined, sampleSleep, install), (first, dur) => logEventBestEffort(root, buildCheckEvent(role, scope, first, dur)));
+        const { outcome, durationMs: d } = await runWithCleanRetry(() => runBuildCheck(wt, runCheck, timeoutMs, undefined, sampleSleep, install), (first, dur) => logEventBestEffort(root, buildCheckEvent(role, scope, first, dur, cheaper)));
         durationMs = d;
         return outcome;
-    }, permitWait);
+    }, {
+        waiting: () => permitWait?.waiting?.(),
+        granted: () => permitWait?.granted?.(),
+        waited: (waitedMs, parked) => logCheckWaitEvent(root, role, scope, waitedMs, parked),
+    }, `${role} ${scope}`);
     // A signal kill at a merge scope, or a timeout whose deadline fired on time (real slowness, a
     // genuinely hung or oversized suite), made no verdict about the tree — and this is the check
     // whose whole job is to catch a semantic conflict before it merges, so it rejects
@@ -102,10 +109,10 @@ export async function runScopedBuildCheck(root, role, scope, wt, config, timeout
             ...(raw.install ? { install: raw.install } : {}),
         }
         : raw;
-    logEventBestEffort(root, buildCheckEvent(role, scope, outcome, durationMs));
+    logEventBestEffort(root, buildCheckEvent(role, scope, outcome, durationMs, cheaper));
     if (outcome.status === "skipped") {
         // Environmental — deliberately NOT fail-closed, so a hung build script cannot wedge every
-        // code tick into the 3-strike discard (gate) or a merge behind the merge lock.
+        // code run into the 3-strike discard (gate) or a merge behind the merge lock.
         const w = SCOPE_WORDS[scope];
         warnEventBestEffort(root, role, buildCheckSkipWarning(outcome.skipReason, w.label, w.proceeding, effectiveMs, outcome.skipReason === "killed" && outcome.killedBy
             ? { signal: outcome.killedBy, durationMs }

package/dist/src/build/build-check.js

@@ -1,7 +1,7 @@
 import { BUILD_CHECK_TIMEOUT_MS } from "./build-check-detect.js";
 import { EXEC_MAX_BUFFER, execFileAsync } from "../process/process.js";
 import { KILL_GRACE_MS, runScriptGroup } from "../process/process-group.js";
-import { clipBuildTail } from "./build-check-report.js";
+import { clipBuildTail, parseFailingTests } from "./build-check-report.js";
 import { parseTestCounts } from "./build-check-counts.js";
 import { sampleSleepClock, sleptMsBetween } from "./host-sleep.js";
 import { npmInstall, syncInstall } from "./dep-install.js";
@@ -168,6 +168,7 @@ async function runDeclaredCheck(wt, check, script, effectiveMs, killGraceMs, sam
             status: "failed",
             script,
             outputTail: clipBuildTail(output),
+            failingTests: parseFailingTests(output),
             run,
             counts: parseTestCounts(output),
         };

package/dist/src/build/build-info.js

@@ -1,10 +1,9 @@
-// vocabulary: plain
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { gitTry } from "../git/git-run.js";
 import { readJsonFile, writeJsonAtomic } from "../files/json-files.js";
 import { finiteNumber } from "../files/json-object.js";
-import { refSha } from "../git/git.js";
+import { commitExists, refSha } from "../git/git.js";
 /** The paths whose change makes a build stale — everything tsc compiles into dist/ plus the
  * files that steer the compile. Tests are compiled too but never loaded by the running
  * harness, so a test-only commit does not stale the build; docs and markdown never do. */
@@ -53,7 +52,7 @@ export async function stampBuild(root, dist, sha) {
 export async function isSelfHosted(root, info) {
     if (path.resolve(root) !== info.root)
         return false;
-    return (await gitTry(root, "cat-file", "-e", `${info.sha}^{commit}`)) !== null;
+    return commitExists(root, info.sha);
 }
 /** Compare a build's commit against main's head over the build inputs only: commits touching
  * just tests or markdown leave the running code unchanged and never count as stale. Null when

package/dist/src/build/build-stage.js

@@ -1,10 +1,9 @@
-// vocabulary: plain
 import fs from "node:fs";
 import path from "node:path";
 import { distDir, stampBuild } from "./build-info.js";
 import { clipBuildTail } from "./build-check-report.js";
 import { resolveFromNodeModules } from "./build-check-detect.js";
-import { ensureDir, removeTree } from "../files/files.js";
+import { ensureDir, removeTree, tryReadDirEntries } from "../files/files.js";
 import { stagingDir, stagingRootDir } from "../paths.js";
 import { execFileAsync } from "../process/process.js";
 import { warnEvent, warnEventBestEffort, TUMWATER_SOURCE } from "../events/events.js";
@@ -36,13 +35,9 @@ export const STAGED_PRUNE_AFTER_MS = 45 * 60_000;
 export function pruneStaleStagings(root, keep, now = Date.now()) {
     const stagingRoot = stagingRootDir(root);
     let removed = 0;
-    let entries;
-    try {
-        entries = fs.readdirSync(stagingRoot, { withFileTypes: true });
-    }
-    catch {
+    const entries = tryReadDirEntries(stagingRoot);
+    if (!entries)
         return 0; // No staging root yet (first compile) — nothing to prune.
-    }
     for (const entry of entries) {
         if (!entry.isDirectory() || !/^[0-9a-f]{40}$/.test(entry.name))
             continue;
@@ -61,7 +56,7 @@ export function pruneStaleStagings(root, keep, now = Date.now()) {
             removed += 1;
         }
         catch {
-            // Left for the next compile or swap: dead weight one tick longer is fine.
+            // Left for the next compile or swap: dead weight one run longer is fine.
         }
     }
     return removed;
@@ -216,9 +211,9 @@ export function swapDist(root, dist, mainHead) {
  * build aside to `dist.prev` and then moves the staged build into `dist`, and a process killed
  * (SIGKILL — the OOM killer) in that microsecond window leaves `dist` missing. Nothing in the
  * swap can close the window, because the survivor is the supervisor and it exits on the dead
- * generation; the next `tumwater run` then cannot even load `dist/src/cli.js` and fails with
+ * generation; the next `tumwater start` then cannot even load `dist/src/cli.js` and fails with
  * MODULE_NOT_FOUND, so the repo is wedged until someone renames `dist.prev` back by hand. The
- * supervisor calls this before it exits (src/cli/cli-run.ts, via superviseRun's onDone): while
+ * supervisor calls this before it exits (src/cli/cli-start.ts, via superviseStart's onDone): while
  * it is still up, it renames the preserved old build back into place so the next boot works.
  *
  * Only acts when `dist` is missing and a `dist.prev` exists — both conditions together are the
@@ -233,10 +228,10 @@ export function recoverInterruptedSwap(root, dist) {
     fs.renameSync(prev, dist); // Atomic: dist is either the restored old build or still missing.
     return true;
 }
-/** The supervisor's end-of-supervision repair (src/cli/cli-run.ts wires this into
- * superviseRun's onDone): recover dist/ after an interrupted swap and, either way, put the
+/** The supervisor's end-of-supervision repair (src/cli/cli-start.ts wires this into
+ * superviseStart's onDone): recover dist/ after an interrupted swap and, either way, put the
  * outcome on the event feed. Kept beside recoverInterruptedSwap so the CLI wiring is one call.
- * cli-run.ts imports this module statically, so the code is in memory before a swap can move
+ * cli-start.ts imports this module statically, so the code is in memory before a swap can move
  * dist/ away — recovering via an import at call time would fail ERR_MODULE_NOT_FOUND exactly
  * when it is needed, the window this closes. `dist` defaults to this process's own dist
  * (build-info.distDir, a pure path computation captured at load), overridable so a test can

package/dist/src/build/dep-install.js

@@ -1,4 +1,3 @@
-// vocabulary: plain
 import path from "node:path";
 import { resolveFromNodeModules } from "./build-check-detect.js";
 import { readJsonFile } from "../files/json-files.js";
@@ -9,7 +8,7 @@ import { errorMessage } from "../text/text.js";
 /** Keeping a tree's install in step with its lockfile (BUGS.md 2026-10-01). node_modules is
  * gitignored, so a tumwater worktree has none of its own: its toolchain and every import resolve by
  * walking UP to the root checkout's install (detectBuildCheck, resolveFromNodeModules). That
- * install predates any dependency a change adds, and no loop ever ran `npm install` — so a
+ * install predates any dependency a change adds, and no role ever ran `npm install` — so a
  * legitimate dependency-adding change failed its gate check with TS2307 every time, and had it
  * merged, every tree after it would have resolved against a root install missing the package. Two
  * callers close both halves: runBuildCheck installs into the checked tree when its lockfile's

package/dist/src/change/change-data.js

@@ -1,6 +1,6 @@
-/** The collector behind `tumwater diff --role <id>`: what change a loop holds between its commit
- * and its merge. The committed half is the loop branch's unmerged work (commits ahead of the
- * team's main branch, with the patch); the uncommitted half is the loop worktree's dirty state.
+/** The collector behind `tumwater diff --role <id>`: what change a role holds between its commit
+ * and its merge. The committed half is the role branch's unmerged work (commits ahead of the
+ * team's main branch, with the patch); the uncommitted half is the role worktree's dirty state.
  * Everything is read-only git plumbing already used elsewhere — this module only wires the pieces
  * into one operator view, degrading like `report` does when the team (or just this role's
  * worktree) does not exist yet. Lives beside the other collectors (src/report/report-data.ts,
@@ -9,35 +9,55 @@
 import { knownRoleIdsCached, loadConfigSafe } from "../config/config.js";
 import { aheadOfMain, branchExists, countCommitsInRange, currentBranch, targetBranch } from "../git/git.js";
 import { gitTry } from "../git/git-run.js";
-import { aheadOfMainDiff, changedFiles } from "../git/git-diff.js";
+import { aheadOfMainDiff, aheadOfMainFiles, changedFiles } from "../git/git-diff.js";
+import { isAbsolute } from "node:path";
 import { branchName } from "../paths.js";
 import { isUsableWorktree } from "../git/worktree.js";
 import { roleWorktreeDir } from "../git/slots-state.js";
-/** Collect the pending change of every known role (built-in plus custom loop ids, config
- * order — disabled roles included, since a loop stopped mid-flight still holds its branch).
- * Each entry goes through collectRoleChange, which keeps the absent/no-base degradation
- * logic single-homed and only computes the patch git-diffs for roles actually holding work
- * (both are "" when a role holds nothing); the team view then drops the patch fields. */
+/** Resolve the team-wide scope both collection entry points share: read the config once for a
+ * configured baseBranch, ask the primary checkout for its current branch once, and check the
+ * resolved main branch exists once. */
+async function resolveChangeScope(root) {
+    const { config } = loadConfigSafe(root);
+    const mainBranch = targetBranch(config?.baseBranch, await currentBranch(root));
+    return { mainBranch, mainPresent: await branchExists(root, mainBranch) };
+}
+/** Collect the pending change of every known role (built-in plus custom role ids, config
+ * order — disabled roles included, since a role stopped mid-flight still holds its branch).
+ * Each entry goes through collectRoleChangeAt with the team-wide scope resolved once up
+ * front, which keeps the absent/no-base degradation logic single-homed and only computes
+ * the patch git-diffs for roles actually holding work (both are "" when a role holds
+ * nothing); the team view then drops the patch fields. */
 export async function collectTeamChanges(root) {
+    const scope = await resolveChangeScope(root);
     const roles = await Promise.all(knownRoleIdsCached(root).map(async (role) => {
-        const view = await collectRoleChange(root, role);
+        const view = await collectRoleChangeAt(root, role, scope);
         const { diff: _diff, uncommittedDiff: _uncommittedDiff, ...team } = view;
         return team;
     }));
-    // mainBranch is team-wide: collectRoleChange resolves it once per role through the same
-    // targetBranch call, so the first entry's value is every entry's value.
-    return { mainBranch: roles[0]?.mainBranch ?? "main", roles };
+    return { mainBranch: scope.mainBranch, roles };
+}
+/** Collect each listed role's full change view, entries in the caller's order. */
+export async function collectRoleChanges(root, roles, opts = {}) {
+    const scope = await resolveChangeScope(root);
+    const views = await Promise.all(roles.map((role) => collectRoleChangeAt(root, role, scope, opts)));
+    return { mainBranch: scope.mainBranch, roles: views };
 }
 /** The uncommitted patch's cap, matching aheadOfMainDiff's — one shared bound so neither
  * half of the view can print unbounded text. */
 const DIFF_MAX_BYTES = 200_000;
-/** Collect the change the role's loop holds: both halves of the view, or a degraded state
+/** Collect the change the role holds: both halves of the view, or a degraded state
  * when the worktree or the base branch is missing. Never throws on a degraded team — a
- * query about a loop that has not run yet must answer, not fail (report's rationale). */
+ * query about a role that has not run yet must answer, not fail (report's rationale). */
 export async function collectRoleChange(root, role, opts = {}) {
+    return collectRoleChangeAt(root, role, await resolveChangeScope(root), opts);
+}
+/** One role's change against a pre-resolved team scope: the per-role body of every entry point.
+ * Shared so the team-wide mainBranch/branch-exists reads are spent once per collection instead
+ * of once per role (the roster and list forms pass a scope resolved before the Promise.all). */
+async function collectRoleChangeAt(root, role, scope, opts = {}) {
     const branch = branchName(role);
-    const { config } = loadConfigSafe(root);
-    const mainBranch = targetBranch(config?.baseBranch, await currentBranch(root));
+    const mainBranch = scope.mainBranch;
     const empty = {
         role,
         branch,
@@ -49,31 +69,45 @@ export async function collectRoleChange(root, role, opts = {}) {
         dirtyFiles: [],
         uncommittedDiff: "",
     };
-    if (!(await branchExists(root, mainBranch)))
+    if (!scope.mainPresent)
         return { ...empty, state: "no-base" };
     // The role's checkout comes from the pool resolver (slots-state.ts): a slot leased for its
-    // tick or pinned for it, else the legacy worktree. A null or unusable directory is the same
-    // operator situation — this loop holds nothing inspectable yet — so worktree.ts's shared
+    // run or pinned for it, else the legacy worktree. A null or unusable directory is the same
+    // operator situation — this role holds nothing inspectable yet — so worktree.ts's shared
     // usability probe still answers the final question.
     const wt = await roleWorktreeDir(root, role);
     if (wt === null || !(await isUsableWorktree(wt)))
         return { ...empty, state: "absent" };
     const ahead = await aheadOfMain(wt, mainBranch);
     const behind = await countCommitsInRange(wt, `HEAD..${mainBranch}`);
-    const commits = parseOnelineLog(await gitTry(wt, "log", "--oneline", `${mainBranch}..HEAD`));
+    // Under opts.path every git call below is limited to that path through a literal pathspec.
+    const spec = opts.path === undefined ? [] : ["--", `:(literal)${opts.path}`];
+    const commits = parseOnelineLog(await gitTry(wt, "log", "--oneline", `${mainBranch}..HEAD`, ...spec));
     // Under opts.stat both halves hold the uncapped `git diff --stat` summary (one line per file).
-    const diff = ahead === 0
+    // A view: a diff git fails to produce shows empty, as it always did.
+    const diff = commits.length === 0
         ? ""
         : opts.stat
-            ? ((await gitTry(wt, "diff", "--stat", `${mainBranch}...HEAD`)) ?? "")
-            : await aheadOfMainDiff(wt, mainBranch);
-    const dirtyFiles = await changedFiles(wt);
+            ? ((await gitTry(wt, "diff", "--stat", `${mainBranch}...HEAD`, ...spec)) ?? "")
+            : await aheadOfMainDiff(wt, mainBranch, DIFF_MAX_BYTES, spec).catch(() => "");
+    // A view: a git that fails to answer shows no uncommitted edits, as it always did.
+    const dirtyFiles = (await changedFiles(wt).catch(() => [])).filter((f) => inPath(f, opts.path));
     const uncommittedDiff = dirtyFiles.length === 0
         ? ""
         : opts.stat
-            ? ((await gitTry(wt, "diff", "--stat", "HEAD")) ?? "")
-            : await cappedWorkingDiff(wt);
-    return { ...empty, state: "ready", ahead, behind, commits, diff, dirtyFiles, uncommittedDiff };
+            ? ((await gitTry(wt, "diff", "--stat", "HEAD", ...spec)) ?? "")
+            : await cappedWorkingDiff(wt, spec);
+    return {
+        ...empty,
+        state: "ready",
+        ahead,
+        behind,
+        commits,
+        diff,
+        dirtyFiles,
+        uncommittedDiff,
+        ...(opts.path === undefined ? {} : { path: opts.path }),
+    };
 }
 /** Parse `git log --oneline` output into {sha, subject} pairs — sha up to the first space,
  * the rest of the line the subject. Blank trailing lines (runGit's trimEnd makes them
@@ -89,16 +123,74 @@ function parseOnelineLog(out) {
         return cut < 0 ? { sha: line, subject: "" } : { sha: line.slice(0, cut), subject: line.slice(cut + 1) };
     });
 }
+/** The normalised repo-relative `path` scope of a role's change view (shared by `diff --role
+ * --path` and the dashboard's `GET /api/diff?role&path`): leading `./` pieces and trailing `/`
+ * characters stripped; null for an empty, `.`, absolute or `..`-bearing result. */
+export function normalizeDiffPath(raw) {
+    const norm = raw.replace(/^(\.\/)+/, "").replace(/\/+$/, "");
+    const bad = norm === "" || norm === "." || isAbsolute(norm) || norm.split("/").includes("..");
+    return bad ? null : norm;
+}
+/** Whether a porcelain path lies under the `--path` scope (always true without one): the path
+ * itself, a file below it, or an untracked-directory entry (trailing `/`) that contains it. */
+function inPath(f, path) {
+    if (path === undefined)
+        return true;
+    return f === path || f.startsWith(path + "/") || (f.endsWith("/") && path.startsWith(f));
+}
 /** The worktree's uncommitted tracked-change patch, capped at DIFF_MAX_BYTES like
  * aheadOfMainDiff: over the cap, a truncation note plus the --stat summary — bounded
  * output that still names every changed file. `git diff HEAD` covers staged and unstaged
  * tracked edits in one patch (plain `git diff` would show unstaged only, dropping a staged
  * edit the dirtyFiles list already counts); untracked paths have no diff content anywhere,
  * so they appear in the file list alone. */
-async function cappedWorkingDiff(wt) {
-    const full = (await gitTry(wt, "diff", "HEAD")) ?? "";
+async function cappedWorkingDiff(wt, spec = []) {
+    const full = (await gitTry(wt, "diff", "HEAD", ...spec)) ?? "";
     if (full.length <= DIFF_MAX_BYTES)
         return full;
-    const stat = (await gitTry(wt, "diff", "--stat", "HEAD")) ?? "";
+    const stat = (await gitTry(wt, "diff", "--stat", "HEAD", ...spec)) ?? "";
     return (`[uncommitted diff truncated: the full diff is ${full.length} bytes; showing --stat]\n\n` + stat);
 }
+/** The paths two or more distinct roles hold: a role's duplicate path counts once, roles stay
+ * in holdings order, paths sort by plain `<` comparison. */
+export function fileOverlaps(holdings) {
+    const byPath = new Map();
+    for (const { role, files } of holdings) {
+        for (const path of new Set(files)) {
+            const roles = byPath.get(path);
+            if (roles === undefined)
+                byPath.set(path, [role]);
+            else
+                roles.push(role);
+        }
+    }
+    return [...byPath.entries()]
+        .filter(([, roles]) => roles.length >= 2)
+        .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+        .map(([path, roles]) => ({ path, roles }));
+}
+/** Keep only the overlaps naming a listed role; each kept entry still names every holder. */
+export function scopeChangeOverlaps(view, roles) {
+    return { ...view, overlaps: view.overlaps.filter((o) => o.roles.some((r) => roles.includes(r))) };
+}
+/** Keep only the overlaps at or under `path` (normalized), by the `inPath` rule
+ * `diff --role --path` uses. */
+export function scopeChangeOverlapsToPath(view, path) {
+    return { ...view, overlaps: view.overlaps.filter((o) => inPath(o.path, path)) };
+}
+/** Collect the files two or more roles hold, committed ahead of main or uncommitted. Computes
+ * file names only — no patch — and skips a role with no usable checkout. */
+export async function collectChangeOverlaps(root) {
+    const { mainBranch, mainPresent } = await resolveChangeScope(root);
+    if (!mainPresent)
+        return { mainBranch, state: "no-base", overlaps: [] };
+    const held = await Promise.all(knownRoleIdsCached(root).map(async (role) => {
+        const wt = await roleWorktreeDir(root, role);
+        if (wt === null || !(await isUsableWorktree(wt)))
+            return null;
+        const committed = (await aheadOfMain(wt, mainBranch)) > 0 ? await aheadOfMainFiles(wt, mainBranch).catch(() => []) : [];
+        return { role, files: [...committed, ...(await changedFiles(wt).catch(() => []))] };
+    }));
+    const holdings = held.filter((h) => h !== null);
+    return { mainBranch, state: "ready", overlaps: fileOverlaps(holdings) };
+}

package/dist/src/change/change-render.js

@@ -13,14 +13,25 @@ function workSummary(ahead, behind, mainBranch, dirtyFiles) {
         (behind > 0 ? `, ${plural(behind, "commit")} behind` : "") +
         (dirtyFiles.length > 0 ? `, ${plural(dirtyFiles.length, "uncommitted file")}` : ""));
 }
+/** The one-line phrase a change view prints when the resolved main branch is absent — shared
+ * by the roster, the per-role view, the list of roles, and the overlaps view so the operator
+ * wording the tests pin cannot drift between them (the workSummary precedent). */
+function mainMissingPhrase(mainBranch) {
+    return `main branch ${mainBranch} does not exist`;
+}
+/** True when a team-wide roster is all no-base (every role found the same missing main branch)
+ * and holds at least one role, so it opens with the single baseline phrase instead of a column
+ * of per-role "does not exist" lines. */
+function allRolesNoBase(roles) {
+    return roles.length > 0 && roles.every((r) => r.state === "no-base");
+}
 /** Render the roster as the operator-facing text `tumwater diff` (no --role) prints: one
  * line per role that holds pending work, in roster order; roles with no worktree and roles
  * holding nothing are skipped. Every entry no-base means the baseline itself is gone — the
  * per-role view's line says so, team-wide, exit 0 like every other degraded case. */
 export function renderTeamChange(view) {
-    if (view.roles.length > 0 && view.roles.every((r) => r.state === "no-base")) {
-        return `main branch ${view.mainBranch} does not exist`;
-    }
+    if (allRolesNoBase(view.roles))
+        return mainMissingPhrase(view.mainBranch);
     const lines = view.roles
         .filter((r) => r.state !== "no-base" && (r.ahead > 0 || r.dirtyFiles.length > 0))
         .map((r) => `${r.role}: ${workSummary(r.ahead, r.behind, view.mainBranch, r.dirtyFiles)}`);
@@ -31,11 +42,15 @@ export function renderRoleChange(view) {
     if (view.state === "absent")
         return `no worktree for ${view.role}`;
     if (view.state === "no-base")
-        return `main branch ${view.mainBranch} does not exist`;
+        return mainMissingPhrase(view.mainBranch);
+    if (view.path !== undefined && view.commits.length === 0 && view.dirtyFiles.length === 0) {
+        return `no pending change to ${view.path} for ${view.role}`;
+    }
     if (view.ahead === 0 && view.dirtyFiles.length === 0)
         return `no pending change for ${view.role}`;
     const lines = [
-        `${view.role}: ${view.branch}, ${workSummary(view.ahead, view.behind, view.mainBranch, view.dirtyFiles)}`,
+        `${view.role}: ${view.branch}, ${workSummary(view.ahead, view.behind, view.mainBranch, view.dirtyFiles)}` +
+            (view.path === undefined ? "" : `; limited to ${view.path}`),
     ];
     for (const c of view.commits)
         lines.push(`${c.sha} ${c.subject}`);
@@ -48,3 +63,29 @@ export function renderRoleChange(view) {
     }
     return lines.join("\n");
 }
+/** Render several roles' views in the listed order, a blank line apart; every block opens with
+ * its role's name, so the blank line separates them. */
+export function renderRoleChanges(view) {
+    if (allRolesNoBase(view.roles))
+        return mainMissingPhrase(view.mainBranch);
+    return view.roles.map(renderRoleChange).join("\n\n");
+}
+/** Render the overlaps view as the operator-facing text `tumwater diff --overlaps` prints:
+ * one `<path>: <role>, <role>` line per shared file. `scope` is the `--role` list the view was
+ * narrowed to and `path` the `--path` it was narrowed to; they only change the empty-list
+ * wording. */
+export function renderChangeOverlaps(view, scope, path) {
+    if (view.state === "no-base")
+        return mainMissingPhrase(view.mainBranch);
+    if (view.overlaps.length === 0 && path !== undefined) {
+        return scope !== undefined
+            ? `no file under ${path} held by ${scope.join(", ")} is touched by another pending change`
+            : `no file under ${path} is touched by two pending changes`;
+    }
+    if (view.overlaps.length === 0 && scope !== undefined) {
+        return `no file held by ${scope.join(", ")} is touched by another pending change`;
+    }
+    if (view.overlaps.length === 0)
+        return "no file is touched by two pending changes";
+    return view.overlaps.map((o) => `${o.path}: ${o.roles.join(", ")}`).join("\n");
+}

package/dist/src/cli/brief-command.js

@@ -1,7 +1,6 @@
-// vocabulary: plain
 import path from "node:path";
 import { readBrief, renderBrief } from "../brief/brief.js";
-import { editInitialPrompt } from "../brief/brief-edit.js";
+import { editBriefText } from "../brief/brief-edit.js";
 import { editInEditor } from "./cli-editor.js";
 import { readPromptFileArg } from "./cli-command-args.js";
 import { JSON_FLAG, rejectUnknownArgs } from "./cli-flag-specs.js";
@@ -11,7 +10,7 @@ import { requireReadyRepo } from "./cli-repo-gate.js";
 const FILE_SPEC = { names: ["--file"], value: true, valueName: "<path>" };
 /** `brief`'s `--edit` flag: open the prompt in `$VISUAL`/`$EDITOR`. */
 const EDIT_SPEC = { names: ["--edit"] };
-/** `tumwater brief`: show the initial prompt and the file holding it, or with `--file <path>` to
+/** `tumwater brief`: show the brief text and the file holding it, or with `--file <path>` to
  * replace it (or with `--edit`, open it in the editor) under the checks init applies and commit
  * that one file on main. */
 export async function cmdBrief(root, args) {
@@ -45,7 +44,7 @@ export async function cmdBrief(root, args) {
     }
     else
         text = readPromptFileArg(args[fileIdx + 1]);
-    const outcome = await editInitialPrompt(root, text);
+    const outcome = await editBriefText(root, text);
     if (!outcome.ok)
         fail(outcome.error);
     const { file: name, changed, committed } = outcome;