tumwater 0.4.2 → 0.4.4

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

@@ -54,6 +54,43 @@ function isCheckScript(s, key) {
     const v = s[key];
     return isNonBlankString(v);
 }
+/** Resolve the configured check timeout to cap the run: `check.timeoutSeconds` × 1000 when it is a
+ * positive number, else undefined. check.timeoutSeconds bounds the npm walk-up's check too: it is
+ * how a repo whose suite outgrows 300 s under load says so (the team's own gate runs were timing
+ * out there). Same result as today for every config shape (absent config, absent `check`, a
+ * non-number, zero and a positive number). */
+function configuredCheckTimeoutMs(config) {
+    const seconds = config?.check?.timeoutSeconds;
+    return typeof seconds === "number" && seconds > 0 ? seconds * 1000 : undefined;
+}
+/** A configured `check.command` (plans/portability.md §6/7) wins over the walk-up: the right way to
+ * verify a repo is a property of the repo, and the walk cannot know it — a Python, Rust, or Go repo
+ * has no npm install for the walk to find, which silently turned every safety gate off there. Null
+ * when the command is blank (validation rejects one, but a degraded default config could still
+ * carry it), so a blank command falls through to the walk-up instead of disabling the check. */
+function configuredCommandCheck(startDir, check, timeoutMs) {
+    if (!isNonBlankString(check.command))
+        return null;
+    return {
+        kind: "command",
+        command: check.command,
+        cwd: path.resolve(startDir, isNonBlankString(check.cwd) ? check.cwd : "."),
+        timeoutMs: timeoutMs ?? BUILD_CHECK_TIMEOUT_MS,
+    };
+}
+/** The npm walk-up: climb to the nearest ancestor holding both package.json and node_modules (the
+ * FIRST qualifying directory is the project — if its package.json has neither script, there is no
+ * check, and an unrelated ancestor further up must never be used), prefer `test` then `typecheck`
+ * then `build`, and stamp the configured timeout onto the npm result. The walk is required:
+ * tumwater worktrees live under `<repo>/.tumwater/worktrees/<role>` with no install of their own
+ * (node_modules is gitignored — it exists only where someone ran npm install), so a literal
+ * startDir check would silently disable the pre-check forever in dogfood. Returns null when no
+ * ancestor within `maxLevels` qualifies or the file is missing/unreadable/malformed. */
+function detectNpmCheck(startDir, maxLevels, timeoutMs) {
+    const root = walkUp(startDir, maxLevels, (dir) => (hasInstall(dir) ? dir : null));
+    const found = root === null ? null : buildCheckFrom(root);
+    return found !== null && found.kind === "npm" && timeoutMs !== undefined ? { ...found, timeoutMs } : found;
+}
 /** Find the project's deterministic check from `startDir` — at most `maxLevels` ancestors
  * (default 5) — to the nearest directory containing BOTH a package.json and a node_modules/
  * directory, then preferring scripts.test over scripts.typecheck and scripts.build (npm convention:
@@ -71,21 +108,13 @@ function isCheckScript(s, key) {
  * be used). Returns null when no ancestor qualifies or the file is missing/unreadable/malformed —
  * detection never throws into the gate. */
 export function detectBuildCheck(startDir, config, maxLevels = WALK_UP_LEVELS) {
-    const c = config?.check;
-    // check.timeoutSeconds bounds the npm walk-up's check too: it is how a repo whose suite
-    // outgrows 300 s under load says so (the team's own gate runs were timing out there).
-    const configuredMs = typeof c?.timeoutSeconds === "number" && c.timeoutSeconds > 0 ? c.timeoutSeconds * 1000 : undefined;
-    if (c && isNonBlankString(c.command)) {
-        return {
-            kind: "command",
-            command: c.command,
-            cwd: path.resolve(startDir, isNonBlankString(c.cwd) ? c.cwd : "."),
-            timeoutMs: configuredMs ?? BUILD_CHECK_TIMEOUT_MS,
-        };
+    const timeoutMs = configuredCheckTimeoutMs(config);
+    if (config?.check) {
+        const command = configuredCommandCheck(startDir, config.check, timeoutMs);
+        if (command !== null)
+            return command;
     }
-    const root = walkUp(startDir, maxLevels, (dir) => (hasInstall(dir) ? dir : null));
-    const found = root === null ? null : buildCheckFrom(root);
-    return found !== null && found.kind === "npm" && configuredMs !== undefined ? { ...found, timeoutMs: configuredMs } : found;
+    return detectNpmCheck(startDir, maxLevels, timeoutMs);
 }
 /** The configured per-change gate command (`check.gateCommand`, PLANS.md Land-queue speed 3e) when
  * it is a non-blank string, else undefined — off. Opt-in: when no `mergeCommand` is declared, a

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

@@ -13,8 +13,8 @@ import { logEventBestEffort } from "../events/events.js";
  * full-suite check. The one vocabulary the three predicates that recognize a full-suite check
  * select on — isPassingFullCheck, isRedFullCheck, and the status polls' newest-merge-check
  * scan (status-polls.ts) — so they cannot drift on which scopes count. The deadline-killed
- * failure costing in time-spend.ts is a narrower pair (merge/batch only, with a status and a
- * timeout required), so it keeps its own check. `full` is the event's `full` field: false
+ * failure costing in failure-time-spend.ts is a narrower pair (merge/batch only, with a status
+ * and a timeout required), so it keeps its own check. `full` is the event's `full` field: false
  * (a check.mergeCommand run) is never a full-suite check. */
 export function isFullCheckScope(scope, full) {
     // A merge or batch run of check.mergeCommand carries `full: false` (buildCheckEvent): it ran

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

@@ -125,6 +125,16 @@ export function failureHeadline(tail) {
 export function describeCheck(check) {
     return check.kind === "npm" ? `\`npm run ${check.script}\`` : `\`${check.command}\``;
 }
+/** The single-line headline of a red check — the failureHeadline when the tail has one to
+ * offer (a test name or marker plus a non-framing message), else the check's describeCheck
+ * command name — the name the gate, merge, and review warnings print for a failed check.
+ * One definition for every red that names itself to a human: review-precheck's two
+ * flake/failure warnings, merge-to-main's merge-retry quarantine warning, and
+ * merge-check-failures's kept-pin headline record and attributeRedCheck absent-tail headline.
+ */
+export function redCheckHeadline(check, tail) {
+    return failureHeadline(tail) ?? describeCheck(check);
+}
 /** 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-run note. The
  * headline is failureHeadline's — the first line that is not a stack frame — not outputTail[0]: a

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

@@ -32,9 +32,7 @@ function resolveScopedCheck(wt, scope, config, timeoutMs, sampleLoad) {
 /** Run the resolved check under one permit, with the one clean retry for a verdict-less death —
  * the one-permit-two-attempt rule. Prices the first attempt as its own build_check event and
  * returns the final outcome and its run duration. */
-async function runScopedCheckWithRetry(root, role, scope, wt, runCheck, timeoutMs, config, sampleSleep, install, permitWait, cheaper) {
-    // One permit covers both attempts (the killed-check retry re-runs under the permit it
-    // holds); durationMs prices the run itself, not the wait for a permit.
+async function runScopedCheckWithRetry(root, role, scope, wt, runCheck, timeoutMs, config, sampleSleep, install, permitWait, cheaper, signal) {
     let durationMs = 0;
     const raw = await withCheckPermit(config, MERGE_SCOPES.has(scope) ? CHECK_TIER.merge : CHECK_TIER.other, async () => {
         // One permit covers both attempts (the killed-check retry re-runs under the permit it
@@ -45,7 +43,7 @@ async function runScopedCheckWithRetry(root, role, scope, wt, runCheck, timeoutM
         // 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, cheaper)));
+        const { outcome, durationMs: d } = await runWithCleanRetry(() => runBuildCheck(wt, runCheck, timeoutMs, undefined, sampleSleep, install, signal), (first, dur) => logEventBestEffort(root, buildCheckEvent(role, scope, first, dur, cheaper)));
         durationMs = d;
         return outcome;
     }, {
@@ -59,6 +57,23 @@ async function runScopedCheckWithRetry(root, role, scope, wt, runCheck, timeoutM
  * unverified reject; anything else passes through. Never logs — the caller warns (see
  * warnScopedCheck). Returns the unverified reason only when a rule fired. */
 function unverifiedOutcomeFor(scope, check, raw, effectiveMs, load, durationMs) {
+    const sleepFailed = sleptThroughRun(raw);
+    if (!unverifiedSkipFor(scope, raw, sleepFailed))
+        return { outcome: raw, unverifiedReason: null };
+    const unverifiedReason = unverifiedReasonFor(scope, raw, effectiveMs, load, durationMs, sleepFailed);
+    return { outcome: unverifiedFailOutcome(check, raw, unverifiedReason), unverifiedReason };
+}
+/** True when the failed run slept past the tolerance — the slept-through rule. */
+function sleptThroughRun(raw) {
+    // A retry that ALSO slept made no clean verdict either: it is recorded as unverified — not
+    // attributed to the change, not cached as a red baseline — rather than read as a second
+    // deterministic failure (BUGS.md 2026-09-30). A retry that passed stands: the tree went green
+    // under the project's own check, even if the host napped through parts of it.
+    return raw.status === "failed" && (raw.run?.sleptMs ?? 0) > SLEEP_SPAN_TOLERANCE_MS;
+}
+/** Whether a merge scope classifies this raw outcome as a deterministic unverified reject — the
+ * merge-scope skip rule. */
+function unverifiedSkipFor(scope, raw, sleepFailed) {
     // 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
@@ -67,20 +82,19 @@ function unverifiedOutcomeFor(scope, check, raw, effectiveMs, load, durationMs)
     // slept, so a second verdict-less attempt is recorded as unverified rather than read again as
     // weather (BUGS.md 2026-09-28). no-npm and a broken toolchain still say nothing about the tree,
     // and the gate scope still proceeds to the model reviewer, which the merge path's own check backs
-    // up. A retry that ALSO slept made no clean verdict either: it is recorded as unverified — not
-    // attributed to the change, not cached as a red baseline — rather than read as a second
-    // deterministic failure (BUGS.md 2026-09-30). A retry that passed stands: the tree went green
-    // under the project's own check, even if the host napped through parts of it.
-    const sleepFailed = raw.status === "failed" && (raw.run?.sleptMs ?? 0) > SLEEP_SPAN_TOLERANCE_MS;
+    // up.
     // A failed dependency install is the same at a merge scope: nothing ran against the tree as its
     // lockfile pins it, so it must not merge (BUGS.md 2026-10-01).
-    const unverifiedSkip = MERGE_SCOPES.has(scope) &&
-        (((raw.status === "skipped" &&
+    return (MERGE_SCOPES.has(scope) &&
+        ((raw.status === "skipped" &&
             (raw.skipReason === "timeout" || raw.skipReason === "killed" || raw.skipReason === "install")) ||
             sleepFailed));
-    if (!unverifiedSkip)
-        return { outcome: raw, unverifiedReason: null };
-    const unverifiedReason = raw.skipReason === "install"
+}
+/** The unverified reason phrase for the rule's four arms — the reason chain, with the optional
+ * starved-host tail. The reason names the starved host only when the load says the team was the
+ * check's competition (a late-deadline wording already names its own cause). */
+function unverifiedReasonFor(scope, raw, effectiveMs, load, durationMs, sleepFailed) {
+    return raw.skipReason === "install"
         ? installFailedPhrase(SCOPE_WORDS[scope].label, raw.install, UNVERIFIED_TREE)
         : raw.skipReason === "killed"
             ? killedPhrase(SCOPE_WORDS[scope].label, raw.killedBy ? { signal: raw.killedBy, durationMs } : undefined, UNVERIFIED_TREE)
@@ -90,7 +104,11 @@ function unverifiedOutcomeFor(scope, check, raw, effectiveMs, load, durationMs)
                 // An on-time kill (the late-deadline wording already names its own cause) names the
                 // starved host when the load average says the team was the check's competition.
                 (raw.run?.deadlineLateMs ?? 0) > DEADLINE_LATE_TOLERANCE_MS ? "" : loadedHostPhrase(load)}`;
-    const outcome = {
+}
+/** Assemble the deterministic `failed` outcome that carries the unverified reason — the
+ * failed-outcome assembly. */
+function unverifiedFailOutcome(check, raw, unverifiedReason) {
+    return {
         status: "failed",
         script: checkScriptName(check),
         outputTail: [unverifiedReason],
@@ -98,12 +116,16 @@ function unverifiedOutcomeFor(scope, check, raw, effectiveMs, load, durationMs)
         unverified: true,
         ...(raw.install ? { install: raw.install } : {}),
     };
-    return { outcome, unverifiedReason };
 }
 /** Warn for the two verdict-less roads: a skipped check (buildCheckSkipWarning) or an unverified
  * merge reject. Reads the scope word table and the killed signal. */
 function warnScopedCheck(root, role, scope, outcome, effectiveMs, durationMs, unverifiedReason) {
     if (outcome.status === "skipped") {
+        // A check the harness stopped on an abort signal is neither weather nor a skip to warn
+        // about: the caller (the gate pre-check) fails closed as aborted on its way out, so no
+        // "proceeding to model review" warning may suggest the check still stands.
+        if (outcome.skipReason === "aborted")
+            return;
         // Environmental — deliberately NOT fail-closed, so a hung build script cannot wedge every
         // code run into the 3-strike discard (gate) or a merge behind the merge lock.
         const w = SCOPE_WORDS[scope];
@@ -142,11 +164,11 @@ function warnScopedCheck(root, role, scope, outcome, effectiveMs, durationMs, un
  * 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) {
+export async function runScopedBuildCheck(root, role, scope, wt, config, timeoutMs = BUILD_CHECK_TIMEOUT_MS, sampleSleep = sampleSleepClock, install = npmInstall, permitWait, sampleLoad = sampleHostLoad, signal) {
     const r = resolveScopedCheck(wt, scope, config, timeoutMs, sampleLoad);
     if (!r)
         return null;
-    const { raw, durationMs } = await runScopedCheckWithRetry(root, role, scope, wt, r.runCheck, timeoutMs, config, sampleSleep, install, permitWait, r.cheaper);
+    const { raw, durationMs } = await runScopedCheckWithRetry(root, role, scope, wt, r.runCheck, timeoutMs, config, sampleSleep, install, permitWait, r.cheaper, signal);
     const { outcome, unverifiedReason } = unverifiedOutcomeFor(scope, r.check, raw, r.effectiveMs, r.load, durationMs);
     logEventBestEffort(root, buildCheckEvent(role, scope, outcome, durationMs, r.cheaper));
     warnScopedCheck(root, role, scope, outcome, r.effectiveMs, durationMs, unverifiedReason);

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

@@ -72,7 +72,7 @@ export function checkScriptName(check) {
  * branch state — which is what this check exists for; build-check.test.ts pins the
  * no-node_modules-worktree resolution. A configured command's cwd is resolved by
  * detectBuildCheck against the worktree the detection started from. */
-export async function runBuildCheck(wt, check, timeoutMs = BUILD_CHECK_TIMEOUT_MS, killGraceMs = KILL_GRACE_MS, sampleSleep = sampleSleepClock, install = npmInstall) {
+export async function runBuildCheck(wt, check, timeoutMs = BUILD_CHECK_TIMEOUT_MS, killGraceMs = KILL_GRACE_MS, sampleSleep = sampleSleepClock, install = npmInstall, signal) {
     const script = checkScriptName(check);
     const effectiveMs = checkTimeoutMs(check, timeoutMs);
     // Environmental probe first: a toolchain broken below the project (git exiting 69 on an
@@ -105,13 +105,13 @@ export async function runBuildCheck(wt, check, timeoutMs = BUILD_CHECK_TIMEOUT_M
         if (r)
             installed = { packages: r.packages, durationMs: r.durationMs };
     }
-    const outcome = await runDeclaredCheck(wt, check, script, effectiveMs, killGraceMs, sampleSleep);
+    const outcome = await runDeclaredCheck(wt, check, script, effectiveMs, killGraceMs, sampleSleep, signal);
     return installed ? { ...outcome, install: installed } : outcome;
 }
 /** runBuildCheck's run-and-classify step, once the probe and any owed install are done: spawn
- * the declared check as a process group under its deadline, bracketed by sleep samples, and
- * classify what it did. */
-async function runDeclaredCheck(wt, check, script, effectiveMs, killGraceMs, sampleSleep) {
+ * the declared check as a process group under its deadline — or, when `signal` fires, stopped
+ * by the harness as its own abort — bracketed by sleep samples, and classify what it did. */
+async function runDeclaredCheck(wt, check, script, effectiveMs, killGraceMs, sampleSleep, signal) {
     // Sleep evidence brackets the spawn: the opening sample is taken while the host is provably
     // awake (this code is running), so any sleep the closing sample can attribute began inside
     // the run's window. A platform with no readable clock leaves run.sleptMs unset — no evidence
@@ -123,12 +123,14 @@ async function runDeclaredCheck(wt, check, script, effectiveMs, killGraceMs, sam
             timeoutMs: effectiveMs,
             killGraceMs,
             maxBuffer: EXEC_MAX_BUFFER,
+            signal,
         })
         : await runScriptGroup("npm", ["run", check.script], {
             cwd: wt,
             timeoutMs: effectiveMs,
             killGraceMs,
             maxBuffer: EXEC_MAX_BUFFER,
+            signal,
         });
     // Spawn failed before anything ran — the runner is missing from PATH.
     if (r.spawnError)
@@ -143,6 +145,12 @@ async function runDeclaredCheck(wt, check, script, effectiveMs, killGraceMs, sam
     // deadline actually fired, which the warning reports when it was late.
     if (r.timedOut)
         return { status: "skipped", script, skipReason: "timeout", run };
+    // The harness stopped the tree on an abort signal (a user abort or a shutdown) — its own
+    // stop, not weather and not a verdict about the tree: classify it separately from a timeout
+    // and from an external killed signal so runScopedBuildCheck neither retries it nor warns it
+    // as a skip.
+    if (r.aborted)
+        return { status: "skipped", script, skipReason: "aborted", run };
     // The tree died on a signal the harness did NOT send (runScriptGroup resolves its own
     // timeout with timedOut already set, so a signal reaching this line is external — another
     // run's `pkill`, an operator's cleanup): the outcome says nothing about the tree, but it is

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

@@ -213,7 +213,8 @@ export function swapDist(root, dist, mainHead) {
  * swap can close the window, because the survivor is the supervisor and it exits on the dead
  * 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-start.ts, via superviseStart's onDone): while
+ * supervisor calls this before it exits (src/cli/cli-start-supervisor.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
@@ -228,11 +229,12 @@ 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-start.ts wires this into
+/** The supervisor's end-of-supervision repair (src/cli/cli-start-supervisor.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-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
+ * cli-start-supervisor.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
  * point it at a temp root. A failed restore is reported, never thrown: the hook runs on the

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

@@ -9,7 +9,7 @@
 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, aheadOfMainFiles, changedFiles } from "../git/git-diff.js";
+import { aheadOfMainDiff, aheadOfMainFiles, changedFiles, DIFF_MAX_BYTES } from "../git/git-diff.js";
 import { compareCodeUnits } from "../collections.js";
 import { isAbsolute } from "node:path";
 import { branchName } from "../paths.js";
@@ -44,9 +44,6 @@ export async function collectRoleChanges(root, roles, opts = {}) {
     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 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 role that has not run yet must answer, not fail (report's rationale). */

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

@@ -72,6 +72,15 @@ function failStrayArg(args, reason, ...claimed) {
     if (extra !== undefined)
         fail(`unexpected argument ${JSON.stringify(extra)} — ${reason}`);
 }
+/** The two positions a valued flag claims for a free-form-prompt parser's stray-argument
+ * accounting: the flag token and its value — the flag and its value are never prompt content.
+ * Empty when the flag is absent, so a negative index never over-claims a real token. The one
+ * shape every valued-flag pair claims for the parsePromptFlags/parsePromptArgs stray-argument
+ * accounting — `--role`, `--grep`, `--at` in parsePromptFlags and `--file` in editPromptArgs
+ * ("claimed like --role's": each site is this same pair) — so no site can drift from the others. */
+function pairClaim(flagIndex) {
+    return flagIndex >= 0 ? [flagIndex, flagIndex + 1] : [];
+}
 /** Read a `--file <path>` prompt file: fail naming the file when it cannot be read. A raw
  * ENOENT/EISDIR names the path but not its role, so the message says this was the --file
  * prompt. Shared by the init and prompt parsers' path branches; the prompt parser's stdin
@@ -141,25 +150,22 @@ function rejectDuplicateFlags(args, flags) {
     for (const flag of flags)
         rejectRepeatFlag(args.filter((a) => a === flag).length > 1, flag);
 }
-/** `tumwater init` argument handling. Init's positionals are free-form prompt text, so
- * rejectUnknownArgs (which rejects ANY unconsumed token) can't be used wholesale. The rules
- * instead: a double-dash token must be a known flag from INIT_FLAG_SPECS (`--file`,
- * `--branch`, `--template`, `--adopt`, `--dry-run` or `--list-templates`), each given at most
- * once; with `--file` present nothing but the other flags may accompany it; a `--branch
- * <name>` pair and the valueless flags are never prompt content; single-dash positionals are
- * prompt content, not flags. Without these checks a misspelled --file would be baked into the
- * brief text — injected into every run of every role until someone edits the project
+/** The flag-vocabulary gate for `tumwater init`: every double-dash token must be a known
+ * INIT_FLAG_SPECS flag, each given at most once. Without it a misspelled --file would be baked
+ * into the brief text — injected into every run of every role until someone edits the project
  * brief. */
-export function parseInitArgs(args) {
+function assertInitFlags(args) {
     const known = INIT_FLAG_SPECS.flatMap((s) => s.names);
     // The unknown-double-dash gate reads the specs, so the list its error names admits exactly
     // what the duplicate-flag check below accepts — one vocabulary, one message renderer.
     rejectUnknownDoubleDash("init", args, INIT_FLAG_SPECS);
     rejectDuplicateFlags(args, known);
-    const branch = parseBranchFlag(args);
-    const adopt = args.includes("--adopt");
-    const dryRun = args.includes("--dry-run");
-    const listTemplates = args.includes("--list-templates");
+}
+/** Resolve `--template <id>` from the argument list, refusing an empty id, an id unknown to
+ * the catalog, and a `--template` given alongside `--list-templates`. Validated here so an
+ * unknown id fails before initProject runs any side effect — before a half-seeded repo can
+ * result from a typo'd id. */
+function resolveInitTemplate(args, listTemplates) {
     // Validate the template id here, so an unknown one fails before initProject runs any side
     // effect — and before a half-seeded repo can result from a typo'd id.
     const templateFlag = args.indexOf("--template");
@@ -175,29 +181,40 @@ export function parseInitArgs(args) {
     if (listTemplates && templateFlag >= 0) {
         fail("--list-templates takes no --template — it lists the catalog, it does not use one");
     }
+    return template;
+}
+/** The `--file` branch of `parseInitArgs`: when the flag is present the prompt comes from the
+ * file, so every other positional is claimed (refused as stray) and the file's exact contents
+ * are read as the prompt — unless `--list-templates` conflicts, which takes no prompt at all.
+ * Returns null when no `--file` flag is present. */
+function resolveInitFileArg(args, base) {
     const fileFlag = args.indexOf("--file");
-    if (fileFlag >= 0) {
-        const file = promptFileValue(args[fileFlag + 1]);
-        const claimed = [fileFlag, fileFlag + 1];
-        const branchFlag = args.indexOf("--branch");
-        if (branchFlag >= 0)
-            claimed.push(branchFlag, branchFlag + 1);
-        if (templateFlag >= 0)
-            claimed.push(templateFlag, templateFlag + 1);
-        for (const flag of INIT_BOOLEAN_FLAGS) {
-            if (args.includes(flag))
-                claimed.push(args.indexOf(flag));
-        }
-        failStrayArg(args, "with --file the prompt comes from the file", ...claimed);
-        const contents = readPromptFileChecked(file);
-        if (listTemplates) {
-            fail(LIST_TEMPLATES_PROMPT_ERROR);
-        }
-        return { prompt: contents, branch, template, listTemplates, adopt, dryRun };
+    if (fileFlag < 0)
+        return null;
+    const file = promptFileValue(args[fileFlag + 1]);
+    const claimed = [fileFlag, fileFlag + 1];
+    const branchFlag = args.indexOf("--branch");
+    if (branchFlag >= 0)
+        claimed.push(branchFlag, branchFlag + 1);
+    const templateFlag = args.indexOf("--template");
+    if (templateFlag >= 0)
+        claimed.push(templateFlag, templateFlag + 1);
+    for (const flag of INIT_BOOLEAN_FLAGS) {
+        if (args.includes(flag))
+            claimed.push(args.indexOf(flag));
+    }
+    failStrayArg(args, "with --file the prompt comes from the file", ...claimed);
+    const contents = readPromptFileChecked(file);
+    if (base.listTemplates) {
+        fail(LIST_TEMPLATES_PROMPT_ERROR);
     }
-    // Everything except the --branch/--template pairs and the booleans is prompt text; the join
-    // keeps single-dash tokens as content, exactly as before — with no flag present this is the
-    // old args.join(" ").
+    return { ...base, prompt: contents };
+}
+/** Reconstruct the positional prompt text for `tumwater init`: everything except the
+ * `--branch`/`--template` pairs and the valueless flags is prompt text. The join keeps
+ * single-dash tokens as content, exactly as before — with no flag present this is the old
+ * args.join(" "). */
+function joinInitPrompt(args) {
     const promptTokens = [];
     for (let i = 0; i < args.length; i++) {
         const arg = args[i];
@@ -206,11 +223,29 @@ export function parseInitArgs(args) {
         else if (!INIT_BOOLEAN_FLAGS.includes(arg))
             promptTokens.push(arg);
     }
-    const prompt = promptTokens.join(" ");
-    if (listTemplates && prompt.trim() !== "") {
+    return promptTokens.join(" ");
+}
+/** `tumwater init` argument handling. Init's positionals are free-form prompt text, so
+ * rejectUnknownArgs (which rejects ANY unconsumed token) can't be used wholesale. The rules
+ * instead: a double-dash token must be a known flag from INIT_FLAG_SPECS, each given at most
+ * once; with `--file` present nothing but the other flags may accompany it; a `--branch
+ * <name>` pair and the valueless flags are never prompt content; single-dash positionals are
+ * prompt content, not flags. */
+export function parseInitArgs(args) {
+    assertInitFlags(args);
+    const branch = parseBranchFlag(args);
+    const adopt = args.includes("--adopt");
+    const dryRun = args.includes("--dry-run");
+    const listTemplates = args.includes("--list-templates");
+    const template = resolveInitTemplate(args, listTemplates);
+    const base = { branch, template, listTemplates, adopt, dryRun };
+    const fromFile = resolveInitFileArg(args, base);
+    if (fromFile !== null)
+        return fromFile;
+    const prompt = joinInitPrompt(args);
+    if (listTemplates && prompt.trim() !== "")
         fail(LIST_TEMPLATES_PROMPT_ERROR);
-    }
-    return { prompt, branch, template, listTemplates, adopt, dryRun };
+    return { ...base, prompt };
 }
 /** The stdin prompt read once per process: cli.ts pre-parses prompt's args and cmdPrompt
  * re-parses them, and a second readFileSync(0) on a drained pipe would see an empty prompt. */
@@ -306,7 +341,7 @@ function parsePromptRole(args, roleFlag) {
     const role = roleRaw ?? null;
     // The flag and its value are never prompt content: --role is a scope, not text. Only claimed
     // when actually present — negative indexes would over-claim real tokens.
-    const roleClaim = roleFlag >= 0 ? [roleFlag, roleFlag + 1] : [];
+    const roleClaim = pairClaim(roleFlag);
     return { role, roleClaim };
 }
 /** The `--json` list-only refusal: in enqueue or cancel mode it must never silently ride
@@ -325,7 +360,7 @@ function parsePromptGrep(args, scan) {
     if (scan.grepFlag >= 0 && (!grepRaw || grepRaw.startsWith("--"))) {
         fail("--grep needs text (usage: tumwater prompt --list --grep <text>)");
     }
-    const grepClaim = scan.grepFlag >= 0 ? [scan.grepFlag, scan.grepFlag + 1] : [];
+    const grepClaim = pairClaim(scan.grepFlag);
     return { grepRaw, grepClaim };
 }
 /** The queue-only-mode refusals: --file and --at have nothing to mean except in the enqueue
@@ -365,7 +400,7 @@ function parsePromptDeferral(args, atFlag) {
     // An edit keeps the target prompt's existing deferral exactly as it was (the marker is
     // plumbing the edit carries over), so a --at alongside it has nothing to mean.
     // The pair is claimed like --role's: the flag and its value are never prompt content.
-    const atClaim = atFlag >= 0 ? [atFlag, atFlag + 1] : [];
+    const atClaim = pairClaim(atFlag);
     let atDelayMs = null;
     if (atFlag >= 0) {
         atDelayMs = parseDurationFlag("--at", args[atFlag + 1]);
@@ -415,13 +450,19 @@ function listPromptArgs(args, f) {
     failStrayArg(args, "with --list there is no prompt text", f.listFlag, ...f.jsonFlags, ...f.roleClaim, ...f.grepClaim);
     return { mode: "list", role: f.role, json: f.jsonFlags.length > 0, grep: f.grepRaw ?? null };
 }
+/** The shared `--cancel <n>` / `--top <n>` mode: each takes exactly one 1-based position
+ * and refuses any other token — these modes have no prompt text. Shared so the two cannot
+ * drift; `mode` drives both the refusal wording and the returned mode. */
+function positionOnlyPromptArgs(args, f, mode, flag, flagIndex) {
+    const n = parsePositionFlag(flag, args[flagIndex + 1], `${flag} 2`);
+    // The position is the only token this mode may carry; anything else alongside it would be
+    // prompt text, and this mode has none.
+    failStrayArg(args, `with ${flag} there is no prompt text`, flagIndex, flagIndex + 1, ...f.roleClaim);
+    return { mode, role: f.role, position: n };
+}
 /** `--cancel <n>`: remove one entry by its 1-based queue position. */
 function cancelPromptArgs(args, f) {
-    const n = parsePositionFlag("--cancel", args[f.cancelFlag + 1], "--cancel 2");
-    // The position is the only token --cancel may carry; anything else alongside it would be
-    // prompt text, and this mode has none.
-    failStrayArg(args, "with --cancel there is no prompt text", f.cancelFlag, f.cancelFlag + 1, ...f.roleClaim);
-    return { mode: "cancel", role: f.role, position: n };
+    return positionOnlyPromptArgs(args, f, "cancel", "--cancel", f.cancelFlag);
 }
 /** `--edit <n>`: rewrite one entry's text in place — the replacement is the --file contents,
  * the tokens after the position, or (with neither) an editor open in the caller. */
@@ -432,7 +473,7 @@ function editPromptArgs(args, f) {
     // a mistyped command would edit prompt N with only the trailing fragment — so they are
     // refused here by the same stray-argument wording the sibling modes use; tokens after the
     // position are the replacement text, minus any claimed attach pair (none: edit in $EDITOR).
-    const fileClaim = f.fileFlag >= 0 ? [f.fileFlag, f.fileFlag + 1] : [];
+    const fileClaim = pairClaim(f.fileFlag);
     for (let i = 0; i < f.editFlag; i++) {
         if (f.roleClaim.includes(i) || f.attachClaims.includes(i) || fileClaim.includes(i))
             continue;
@@ -457,11 +498,7 @@ function editPromptArgs(args, f) {
 }
 /** `--top <n>`: move one entry to the head of its role's queue. */
 function topPromptArgs(args, f) {
-    const n = parsePositionFlag("--top", args[f.topFlag + 1], "--top 2");
-    // The position is the only token --top may carry; anything else alongside it would be
-    // prompt text, and this mode has none.
-    failStrayArg(args, "with --top there is no prompt text", f.topFlag, f.topFlag + 1, ...f.roleClaim);
-    return { mode: "top", role: f.role, position: n };
+    return positionOnlyPromptArgs(args, f, "top", "--top", f.topFlag);
 }
 /** `--file <path>`: enqueue the file's (or stdin's) whole contents as the prompt. */
 function filePromptArgs(args, f) {

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

@@ -0,0 +1,75 @@
+import { completionConfigKeys, completionModels, completionRoleIds, completionScript, configValueWords, SUPPORTED_SHELLS, } from "./completion.js";
+import { say, fail } from "./cli-output.js";
+import { gotSuffix } from "../text/text.js";
+import { typoSuffix } from "../text/suggest.js";
+/** `tumwater completion`'s command body — the shell-completion script and its --roles/
+ * --config-keys/--config-value/--models listing shapes. The completion data lives in
+ * src/cli/completion.ts (the spec parser, the completionScript emitter and the read-only
+ * listing helpers); this module answers a `completion` invocation, split out of cli.ts so the
+ * dispatcher stays the pure shared sequence and this command body sits beside its data the
+ * way every other command body does. Imported lazily by cli.ts like each command body. */
+function printCompletionRoles(root) {
+    for (const id of completionRoleIds(root))
+        say(id);
+}
+function printCompletionConfigKeys(root) {
+    for (const key of completionConfigKeys(root))
+        say(key);
+}
+function printCompletionConfigValue(key) {
+    // The vocabulary `config set <key> <value>` completes for a discrete-valued key
+    // (boolean/backend/model/thinking); free-form keys print nothing, so a `set` on one
+    // completes nothing instead of offering a wrong vocabulary.
+    for (const word of configValueWords(key))
+        say(word);
+}
+function printCompletionModels(root) {
+    for (const m of completionModels(root))
+        say(m);
+}
+const COMPLETION_LISTING_SHAPES = {
+    "--roles": "roles",
+    "--config-keys": "config-keys",
+    "--models": "models",
+};
+function completionListShape(args) {
+    if (args.length === 1 && args[0] in COMPLETION_LISTING_SHAPES)
+        return COMPLETION_LISTING_SHAPES[args[0]];
+    if (args.length === 2 && args[0] === "--config-value")
+        return "config-value";
+    return null;
+}
+function completionShell(args) {
+    const shell = args[0];
+    // A wrong word count names the count, not a bad shell. A single near-miss shell word gets
+    // the same typoSuffix `logs --type`/`history --result` give, so `completion zs` reads
+    // "did you mean `zsh`?" while a far-off value (`tcsh`) stays hint-free.
+    if (args.length === 0)
+        fail("completion needs a shell: bash, zsh, or fish");
+    if (args.length > 1)
+        fail(`completion takes one shell: bash, zsh, or fish (got ${args.length} words: ${args.join(" ")})`);
+    if (!SUPPORTED_SHELLS.includes(shell))
+        fail(`completion takes one shell: bash, zsh, or fish${gotSuffix(shell)}${typoSuffix(shell ?? "", SUPPORTED_SHELLS)}`);
+    return shell;
+}
+/** Answer a `tumwater completion` invocation. Works outside a repo (no requireReadyRepo). */
+export async function cmdCompletion(root, args) {
+    const shape = completionListShape(args);
+    if (shape === "roles") {
+        printCompletionRoles(root);
+        return;
+    }
+    if (shape === "config-keys") {
+        printCompletionConfigKeys(root);
+        return;
+    }
+    if (shape === "config-value") {
+        printCompletionConfigValue(args[1]);
+        return;
+    }
+    if (shape === "models") {
+        printCompletionModels(root);
+        return;
+    }
+    say(completionScript(completionShell(args)));
+}