tumwater 0.4.2 → 0.4.3

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-scoped.js

@@ -32,7 +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) {
+async function runScopedCheckWithRetry(root, role, scope, wt, runCheck, timeoutMs, config, sampleSleep, install, permitWait, cheaper, signal) {
     // 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.
     let durationMs = 0;
@@ -45,7 +45,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 +59,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 +84,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 +106,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 +118,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 +166,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/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-flag-specs.js

@@ -465,35 +465,55 @@ export const GUI_FLAG_SPECS = [PORT_FLAG, ALL_INTERFACES_FLAG, TOKEN_FLAG];
 export function rejectUnknownArgs(command, args, specs) {
     if (args.length === 0)
         return;
-    const claim = new Map();
-    for (const spec of specs)
-        for (const name of spec.names)
-            claim.set(name, spec);
+    const claim = flagClaims(specs);
     const seen = new Set();
     const consumed = new Array(args.length).fill(false);
     for (let i = 0; i < args.length; i++) {
         if (consumed[i])
             continue;
         const arg = args[i] ?? ""; // Unreachable fallback: the loop bound guarantees a token here.
-        const spec = claim.get(arg);
-        if (spec === undefined) {
-            // An equals-form token names a real flag; refuse it with its own message before the
-            // generic "unknown argument" misreports `--role=feature` as a misspelling.
-            rejectEqualsForm(arg, specs);
-            if (specs.length === 0)
-                fail(`tumwater ${command} takes no arguments${gotSuffix(arg)}`);
-            failUnknownArgument(command, arg, specs);
-        }
+        const spec = claim.get(arg) ?? rejectUnknownFlag(command, arg, specs);
         rejectRepeatFlag(seen.has(spec), spec.names[0]);
         seen.add(spec);
-        if (spec.value && i === args.length - 1)
-            fail(spec.missingValue ?? `${spec.names[0]} needs a value`);
-        // The value exists (the trailing-no-value case failed above): name a malformed one now,
-        // before the ready-repo gate or any environment check can mask it.
-        if (spec.value)
-            spec.validate?.(args[i + 1] ?? "");
-        const n = spec.value ? 2 : 1;
-        for (let j = 0; j < n && i + j < args.length; j++)
-            consumed[i + j] = true;
+        consumeFlagOccurrence(spec, args, i, consumed);
     }
 }
+/** The spelling-to-spec claim map rejectUnknownArgs keyed its loop on: every accepted flag
+ * spelling maps to the spec declaring it, alias spellings (-f and --follow) sharing one spec
+ * entry. Built once up front so a token look-up is a map get, not a scan. */
+function flagClaims(specs) {
+    const claim = new Map();
+    for (const spec of specs)
+        for (const name of spec.names)
+            claim.set(name, spec);
+    return claim;
+}
+/** The one refusal for a token naming no known flag: an equals-form token first reroutes
+ * through rejectEqualsForm, which names a REAL flag's offending `--flag=value` spelling
+ * before the generic "unknown argument" misreports `--role=feature` as a misspelling; then
+ * a command with no flags at all fails with the takes-no-arguments wording; otherwise the
+ * shared unknown-argument wording (with its did-you-mean hint) fires. Returns never, so the
+ * caller's `claim.get(arg) ?? rejectUnknownFlag(...)` narrows `spec` to a known FlagSpec. */
+function rejectUnknownFlag(command, arg, specs) {
+    // An equals-form token names a real flag; refuse it with its own message before the
+    // generic "unknown argument" misreports `--role=feature` as a misspelling.
+    rejectEqualsForm(arg, specs);
+    if (specs.length === 0)
+        fail(`tumwater ${command} takes no arguments${gotSuffix(arg)}`);
+    failUnknownArgument(command, arg, specs);
+}
+/** Consume one recognised flag occurrence: fail a valued flag left without its value, name a
+ * malformed value via the spec's validate call, and mark the one or two tokens (the flag and,
+ * for a valued flag, its value) as consumed so a later loop iteration skips them. The value
+ * is marked only after the value checks pass, so a failed value is never silently swallowed. */
+function consumeFlagOccurrence(spec, args, i, consumed) {
+    if (spec.value && i === args.length - 1)
+        fail(spec.missingValue ?? `${spec.names[0]} needs a value`);
+    // The value exists (the trailing-no-value case failed above): name a malformed one now,
+    // before the ready-repo gate or any environment check can mask it.
+    if (spec.value)
+        spec.validate?.(args[i + 1] ?? "");
+    const n = spec.value ? 2 : 1;
+    for (let j = 0; j < n && i + j < args.length; j++)
+        consumed[i + j] = true;
+}

package/dist/src/cli/cli-init.js

@@ -12,8 +12,7 @@ import { templateCatalog } from "../init/init-templates.js";
 export async function cmdInit(root, args) {
     const { prompt, branch, template, listTemplates, adopt, dryRun } = parseInitArgs(args);
     if (listTemplates) {
-        for (const { id, description } of templateCatalog())
-            say(`${id} — ${description}`);
+        printTemplateCatalog();
         return;
     }
     const result = await initProject(root, prompt, branch ?? undefined, {
@@ -21,21 +20,44 @@ export async function cmdInit(root, args) {
         dryRun,
         template: template ?? undefined,
     });
+    printInitIntro(result);
+    if (result.dryRun) {
+        printDryRun(result);
+        return;
+    }
+    printInitReport(result);
+}
+/** Print the `tumwater init --list-templates` catalog: one line per template. */
+function printTemplateCatalog() {
+    for (const { id, description } of templateCatalog())
+        say(`${id} — ${description}`);
+}
+/** Print the `template:`/adopt intro lines shared by the dry-run and completed paths. */
+function printInitIntro(result) {
     if (result.template !== "blank")
         say(`template: ${result.template}`);
     if (result.adopted) {
         say(`${result.dryRun ? "would adopt" : "adopting"} an existing repo: the project brief goes in TUMWATER.md and README.md is left untouched`);
     }
-    if (result.dryRun) {
-        if (result.repoInitialized && result.branch) {
-            say(`dry run — would initialize a new git repository on branch ${result.branch}`);
-        }
-        const list = (names) => (names.length > 0 ? names.join(", ") : "nothing");
-        say(`dry run — would create: ${list(result.created)}`);
-        say(`would leave alone: ${list(result.leftAlone)}`);
-        say("nothing written; re-run without --dry-run to apply");
-        return;
+}
+/** Print the dry-run preview: repo line, the would-create/would-leave-alone lists, and the
+ * "nothing written" line. */
+function printDryRun(result) {
+    if (result.repoInitialized && result.branch) {
+        say(`dry run — would initialize a new git repository on branch ${result.branch}`);
     }
+    const list = (names) => (names.length > 0 ? names.join(", ") : "nothing");
+    say(`dry run — would create: ${list(result.created)}`);
+    say(`would leave alone: ${list(result.leftAlone)}`);
+    say("nothing written; re-run without --dry-run to apply");
+}
+/** Format the created-files line, appending `(committed)` when the repo was seeded. */
+function createdLine(result) {
+    return `created ${result.created.join(", ")}${result.committed ? " (committed)" : ""}`;
+}
+/** Print the completed-init report: the already-initialized no-op, the repo line, the
+ * created-files line, the bootstrap note, and the "next:" line. */
+function printInitReport(result) {
     if (result.created.length === 0) {
         say("already initialized; nothing to do");
         return;
@@ -43,7 +65,7 @@ export async function cmdInit(root, args) {
     if (result.repoInitialized && result.branch) {
         say(`initialized a new git repository on branch ${result.branch}`);
     }
-    say(`created ${result.created.join(", ")}${result.committed ? " (committed)" : ""}`);
+    say(createdLine(result));
     if (result.bootstrap !== null) {
         say(`fresh project — maintenance roles wait until ${result.bootstrap} plans are done; remove "bootstrap" from tumwater.json to end that early`);
     }

package/dist/src/cli/cli-query-commands.js

@@ -25,7 +25,7 @@ import { renderMergeQueue, scopeMergeQueue } from "../merge/merge-queue-render.j
 import { mergeChanges } from "../merge/merge-slot.js";
 import { shortSha } from "../text/format.js";
 import { roleLabel } from "../roles/role-labels.js";
-import { orchestratorAlive } from "../team/orchestrator-info.js";
+import { orchestratorAlive } from "../team/team-orchestrator-info.js";
 import { queueInFlight } from "../status/status-polls.js";
 import { roleInScope } from "../roles/runner-ids.js";
 /** `tumwater status [-f/--follow]`: the team snapshot as rendered text or as the JSON

package/dist/src/cli/cli-repo-gate.js

@@ -1,12 +1,12 @@
 /** The repo-readiness gate every repo-bound command runs before its body reads state: fail
- * fast on the first unmet precondition (startup-gate.ts's repoNotReady — the repo half of
+ * fast on the first unmet precondition (startup-gates.ts's repoNotReady — the repo half of
  * `tumwater start`'s startup gate). One named home beside the argument gate (cli-flag-specs.ts):
  * the dispatcher (cli.ts), the marker commands (cli-marker-commands.ts), the write commands
  * (backlog/backlog-cli.ts), and the read-only command bodies (cli-query-commands.ts) all
  * import it, so a command layer never reaches into a sibling command module for a gate. */
 import { fail } from "./cli-output.js";
 import { teamWorkspaceMessage } from "../gates/readiness.js";
-import { repoNotReady } from "../gates/startup-gate.js";
+import { repoNotReady } from "../gates/startup-gates.js";
 import { owningTeamRoot } from "../paths.js";
 /** Fail (exit 1) on the first unmet repo precondition, naming the fix; return once the repo is
  * ready. */