tumwater 0.4.2 → 0.4.3

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

@@ -4,11 +4,11 @@ import { unknownRoleMessage } from "../roles/roles.js";
 import { fail, say, sayJson } from "./cli-output.js";
 import { durationLabel, failRivalShapes, parseBranchFlag, parsePortFlag, parseRoleListFlag, tokenValueProblem, } from "./cli-args.js";
 import { cancelScheduledStop, scheduledStopAt } from "../team/team-state.js";
-import { orchestratorAlive, readOrchestratorInfo } from "../team/orchestrator-info.js";
-import { runStartupCheck, runStartupProblem } from "../gates/startup-gate.js";
+import { orchestratorAlive, readOrchestratorInfo } from "../team/team-orchestrator-info.js";
+import { runStartupCheck, runStartupProblem } from "../gates/startup-gates.js";
 import { repairInterruptedSwap } from "../build/build-stage.js";
 import { logEvent, subscribeEvents } from "../events/events.js";
-import { notifyTeamDown } from "../events/notify.js";
+import { notifyTeamDown } from "../events/event-notify.js";
 import { formatEvent } from "../events/event-format.js";
 import { RESTART_EXIT_CODE } from "../redeploy/redeploy-policy.js";
 import { runStartupMigrations } from "../orchestrator/startup-migration-steps.js";
@@ -151,13 +151,11 @@ async function parseStartInvocation(root, args) {
     assertNoRunningOrchestrator(root);
     return { once, json, forMs, branchArg, roleFilter, config, mainBranch };
 }
-/** Boot the supervised generation: the stop closure and SIGINT/SIGTERM handlers, the --for
- * deadline timer and scheduled-stop watch, the parent-death watch, the baseline/redeploy/
- * launch-services imports, the banner, the event subscription, runOrchestrator, and the
- * once/window summaries and exit codes. */
-async function runSupervisedGeneration(input) {
-    const { root, once, json, forMs, branchArg, roleFilter, config, mainBranch } = input;
-    const { RUN_WINDOW_START_ENV, ONCE_FAILED_EXIT_CODE, startParentDeathWatch, expectedSupervisorPid } = await import("../process/supervisor.js");
+/** Create the abort handle and the graceful-stop closure a supervised generation passes to
+ * every watchdog, and register the SIGINT/SIGTERM handlers that trigger it. Returns an
+ * `isStopping` query so the later once-exit check reads the live flag instead of a captured
+ * boolean. */
+function installStopHandlers(json) {
     const controller = new AbortController();
     let stopping = false;
     const stop = () => {
@@ -173,6 +171,12 @@ async function runSupervisedGeneration(input) {
     };
     process.on("SIGINT", stop);
     process.on("SIGTERM", stop);
+    return { controller, stop, isStopping: () => stopping };
+}
+/** Arm the windowed run's deadline timer and the scheduled-stop watch, both of which run the
+ * same graceful `stop` a Ctrl+C runs. Returns the window start and the two clearable handles. */
+async function armRunWatchdogs(root, json, forMs, stop, isStopping) {
+    const { RUN_WINDOW_START_ENV } = await import("../process/supervisor.js");
     // A windowed run's deadline arms the same graceful stop a Ctrl+C runs — the identical `stop`
     // closure, so the drain path is one code path either way. clearTimeout in the finally below
     // retracts it when the run ends first (an early Ctrl+C), so no stray timer outlives the run.
@@ -185,22 +189,13 @@ async function runSupervisedGeneration(input) {
         stop();
     }) : null;
     const scheduledStopWatch = armScheduledStopWatch(root, () => {
-        if (!stopping)
+        if (!isStopping())
             stop(); // A drain already under way must not be turned into a force-kill.
     }, json);
-    // A supervisor that dies without forwarding — SIGKILL (the OOM killer, `kill -9`) cannot be
-    // trapped or forwarded, and an uncaught supervisor crash forwards nothing either — leaves this
-    // generation reparented and running the team unattended. The parent-death watch polls for the
-    // reparent and runs the same graceful stop a forwarded SIGTERM would have run, so a killed
-    // supervisor takes its team down with it (BUGS.md 2026-09-30). The spawner hands its pid
-    // down (SUPERVISOR_PID_ENV), so a supervisor killed during this child's startup — before the
-    // watch's first ppid read — still counts as gone. Everything below runs only in
-    // the supervised generation: an unsupervised `run` became the supervisor above and returned.
-    const expectedPpid = expectedSupervisorPid();
-    startParentDeathWatch(stop, expectedPpid !== undefined ? { expectedPpid } : {});
-    const enabled = runnerIds(config);
-    // A scoped round's role list is exactly the filter; otherwise every enabled role runs.
-    const roles = roleFilter ?? enabled;
+    return { windowStart, deadlineTimer, scheduledStopWatch };
+}
+/** Persist the baseline verdicts and boot the once-gated redeployer and launch-services watch. */
+async function bootGenerationParts(root, branchArg, once) {
     // Main's green verdicts outlive this generation: the redeployer and baseline's surviving readers
     // (`mainTipVerdict`, the ci hand-off's `mainRedHealNote`) start from the ones the previous
     // generation verified instead of re-running the suite.
@@ -210,10 +205,13 @@ async function runSupervisedGeneration(input) {
     const redeploy = once
         ? null
         : await (await import("../redeploy/redeploy.js")).createRedeployer(root, (e) => logEvent(root, e), () => runStartupProblem(root, branchArg));
-    const build = redeploy ? ` · build ${shortSha(redeploy.build.sha)}` : "";
     // A long-running team watches launchservicesd's port count (a no-op off macOS); a once round
     // is over long before a leak could matter.
     const launchServicesWatch = once ? null : new (await import("../process/launch-services.js")).LaunchServicesWatch(root);
+    return { redeploy, launchServicesWatch };
+}
+/** Print the supervised generation's banner and subscribe to its event stream on non-json runs. */
+function announceGeneration(roles, mainBranch, once, json, forMs, root, build) {
     // Name the resolved root when it differs from the cwd: an operator who started the team
     // from a subdirectory must see where .tumwater/ actually lives.
     const rootNote = root !== process.cwd() ? ` · root ${root}` : "";
@@ -229,38 +227,17 @@ async function runSupervisedGeneration(input) {
         say(`roles: ${roles.join(", ")}`);
         say("watch: `tumwater tui` or `tumwater logs -f` in another terminal; events stream below\n");
     }
-    const unsubscribe = json ? () => { } : subscribeEvents((e) => say(formatEvent(e)));
-    // Snapshot each role's run counter so the once summary can tell this round's runs from
-    // the persisted history (the state file accumulates across rounds).
-    await runStartupMigrations(root); // so the snapshot reads a migrated state/<new>.json
-    const runsBefore = new Map(roles.map((role) => [role, loadRunnerState(root, role).runs]));
-    let exit;
-    try {
-        exit = await (await import("../orchestrator/orchestrator.js")).runOrchestrator({
-            root,
-            config,
-            mainBranch,
-            signal: controller.signal,
-            redeploy,
-            launchServicesWatch,
-            once,
-            roleFilter: roleFilter ?? undefined,
-            stopsAt: forMs !== null ? windowStart + forMs : undefined,
-        });
-    }
-    finally {
-        if (deadlineTimer)
-            deadlineTimer.clear();
-        scheduledStopWatch.clear();
-        unsubscribe();
-    }
+    return json ? () => { } : subscribeEvents((e) => say(formatEvent(e)));
+}
+/** Print the round summary: the once report/summary, or a windowed run's window report. */
+function printRoundSummary(root, roles, runsBefore, once, json, forMs, windowStart, settled, runsDone, restart) {
     if (once) {
         if (json)
-            sayJson(onceReport(root, roles, runsBefore, exit.settled, exit.runsDone));
+            sayJson(onceReport(root, roles, runsBefore, settled, runsDone));
         else
-            say(onceSummary(root, roles, runsBefore, exit.settled, exit.runsDone));
+            say(onceSummary(root, roles, runsBefore, settled, runsDone));
     }
-    else if (forMs !== null && !exit.restart) {
+    else if (forMs !== null && !restart) {
         const { rows, covered } = readRunRowsSince(root, Date.now() - windowStart, null);
         const summary = summarizeRunRows(rows);
         if (json)
@@ -268,8 +245,12 @@ async function runSupervisedGeneration(input) {
         else
             say(windowSummary(durationLabel(forMs), summary, covered));
     }
+}
+/** Set the process exit code for a once round that failed or was cut short before completion. */
+async function applyOnceExitCode(root, roles, runsBefore, runsDone, once, json, isStopping) {
+    const { ONCE_FAILED_EXIT_CODE } = await import("../process/supervisor.js");
     if (once) {
-        const failures = onceFailures(root, roles, runsBefore, exit.runsDone);
+        const failures = onceFailures(root, roles, runsBefore, runsDone);
         if (failures.length > 0) {
             // In --json mode the failure facts already ride in the report's `failures`; the exit
             // code is the contract a CI caller needs, so only the prose line is suppressed.
@@ -281,21 +262,73 @@ async function runSupervisedGeneration(input) {
         // not read as success (0) to the CI caller parsing the JSON: the document still carries
         // the round's partial facts, but the truncated round exits non-zero. Non-json once keeps
         // its historical behavior (prose + 0 unless a role failed).
-        if (json && stopping)
+        if (json && isStopping())
             process.exitCode = ONCE_FAILED_EXIT_CODE;
     }
+}
+/** Boot the supervised generation: the stop closure and SIGINT/SIGTERM handlers, the --for
+ * deadline timer and scheduled-stop watch, the parent-death watch, the baseline/redeploy/
+ * launch-services imports, the banner, the event subscription, runOrchestrator, and the
+ * once/window summaries and exit codes. */
+async function runSupervisedGeneration(input) {
+    const { root, once, json, forMs, branchArg, roleFilter, config, mainBranch } = input;
+    const { startParentDeathWatch, expectedSupervisorPid } = await import("../process/supervisor.js");
+    const { controller, stop, isStopping } = installStopHandlers(json);
+    const { windowStart, deadlineTimer, scheduledStopWatch } = await armRunWatchdogs(root, json, forMs, stop, isStopping);
+    // A supervisor that dies without forwarding — SIGKILL (the OOM killer, `kill -9`) cannot be
+    // trapped or forwarded, and an uncaught supervisor crash forwards nothing either — leaves this
+    // generation reparented and running the team unattended. The parent-death watch polls for the
+    // reparent and runs the same graceful stop a forwarded SIGTERM would have run, so a killed
+    // supervisor takes its team down with it (BUGS.md 2026-09-30). The spawner hands its pid
+    // down (SUPERVISOR_PID_ENV), so a supervisor killed during this child's startup — before the
+    // watch's first ppid read — still counts as gone. Everything below runs only in
+    // the supervised generation: an unsupervised `run` became the supervisor above and returned.
+    const expectedPpid = expectedSupervisorPid();
+    startParentDeathWatch(stop, expectedPpid !== undefined ? { expectedPpid } : {});
+    const enabled = runnerIds(config);
+    // A scoped round's role list is exactly the filter; otherwise every enabled role runs.
+    const roles = roleFilter ?? enabled;
+    const { redeploy, launchServicesWatch } = await bootGenerationParts(root, branchArg, once);
+    const build = redeploy ? ` · build ${shortSha(redeploy.build.sha)}` : "";
+    const unsubscribe = announceGeneration(roles, mainBranch, once, json, forMs, root, build);
+    // Snapshot each role's run counter so the once summary can tell this round's runs from
+    // the persisted history (the state file accumulates across rounds).
+    await runStartupMigrations(root); // so the snapshot reads a migrated state/<new>.json
+    const runsBefore = new Map(roles.map((role) => [role, loadRunnerState(root, role).runs]));
+    let exit;
+    try {
+        exit = await (await import("../orchestrator/orchestrator.js")).runOrchestrator({
+            root,
+            config,
+            mainBranch,
+            signal: controller.signal,
+            redeploy,
+            launchServicesWatch,
+            once,
+            roleFilter: roleFilter ?? undefined,
+            stopsAt: forMs !== null ? windowStart + forMs : undefined,
+        });
+    }
+    finally {
+        if (deadlineTimer)
+            deadlineTimer.clear();
+        scheduledStopWatch.clear();
+        unsubscribe();
+    }
+    printRoundSummary(root, roles, runsBefore, once, json, forMs, windowStart, exit.settled, exit.runsDone, exit.restart);
+    await applyOnceExitCode(root, roles, runsBefore, exit.runsDone, once, json, isStopping);
     // A self-redeploy swapped the new build into dist/: hand the terminal back to the supervisor,
     // which respawns this same script — now the new code — as the next generation.
     if (exit.restart)
         process.exit(RESTART_EXIT_CODE);
     // A windowed (--for) run that did not self-redeploy is done the moment its summary is out:
     // exit deterministically instead of trusting the event loop to drain. This supervised
-    // generation runs a whole team, and any ref'd handle a shutdown misses (a watcher, marker,
+    // generation runs a whole team, and any ref'd handle a shutdown missed (a watcher, marker,
     // or notifier handle a join missed) would otherwise pin this process's loop open, so the
     // supervisor — which waits on this child's exit — never exits and the run reads as a hang:
     // summary printed, exit code null (BUGS.md 2026-10-26). The summary above was the last
-    // output and nothing after depends on this loop, so an explicit exit is equivalent to a
-    // natural one with code 0, just guaranteed.
+    // output and nothing after depends on this loop, so an explicit exit is equivalent to the
+    // natural exit 0 this replaces, just guaranteed.
     if (forMs !== null)
         process.exit(0);
 }

package/dist/src/cli/completion.js

@@ -13,41 +13,68 @@ import { EVENT_TYPE_LABELS } from "../events/event-labels.js";
 import { POST_REVIEW_STATES } from "../review/post-merge-review-render.js";
 import { HELP, helpStanzas } from "./help.js";
 export const SUPPORTED_SHELLS = ["bash", "zsh", "fish"];
-/** The completable words of a stanza's usage part: the text after `tumwater <command>` up to the
- * description column (two or more spaces). Bare lowercase words count inside `[...]` and as the
- * leading run directly after the command; outside brackets the first other token ends the run, so
- * a single-space description (`role <id> --clear-notes Clear that notes`) adds nothing. */
-function usageWords(firstLine, command) {
+/** The usage text of a stanza first line: the part after `tumwater <command>` up to the
+ * description column (two or more spaces). */
+function usagePortion(firstLine, command) {
     const rest = firstLine.replace(new RegExp(`^ {2}tumwater ${command}`), "");
     // Usage arguments follow the command after a single space; two or more spaces start the
     // description.
-    const usage = /^ {2,}/.test(rest) ? "" : (rest.split(/ {2,}/)[0] ?? "");
+    return /^ {2,}/.test(rest) ? "" : (rest.split(/ {2,}/)[0] ?? "");
+}
+/** An angle-bracket alternation of plain words — `<bash|zsh|fish>`, the completion command's
+ * shell positional — expands to each alternative as a subcommand word, so `tumwater completion
+ * <TAB>` lists exactly the shells the command accepts. A bare placeholder like `<id>` or `<k>`
+ * carries no `|` and so stays a placeholder, skipped as before (its `<`/`>` never leave the
+ * token, so it never looked like a word). The expansion only fires while the leading run is
+ * open; the returned words contribute as the leading words of the usage part. */
+function alternationWords(token, leading) {
+    const alternation = /^<([a-z][a-z-]*(?:\|[a-z][a-z-]*)+)>$/.exec(token);
+    return alternation && leading ? alternation[1].split("|") : null;
+}
+/** Whether a token counts as a completable bare word: it is a plain lowercase word and either
+ * sits inside brackets, opens a bracket itself, or is still within the leading run. */
+function isCompletableWord(bare, token, depth, leading) {
+    return /^[a-z][a-z-]*$/.test(bare) && (depth > 0 || token.startsWith("[") || leading);
+}
+/** Whether a token ends the leading run: outside brackets, not opening a bracket, and not
+ * blank once its brackets and bars are stripped (so an angle-bracket placeholder closes it). */
+function endsLeadingRun(bare, token, depth) {
+    return depth === 0 && !token.startsWith("[") && bare !== "";
+}
+/** The bracket-depth delta of a token: `[` +1 and `]` -1 per character, everything else 0. */
+function bracketDelta(token) {
+    let delta = 0;
+    for (const ch of token)
+        delta += ch === "[" ? 1 : ch === "]" ? -1 : 0;
+    return delta;
+}
+/** The completable words of a usage text: the angle-bracket alternation expands, bare lowercase
+ * words count inside `[...]` and as the leading run directly after the command, and outside
+ * brackets the first other token ends the run. */
+function usageWordsIn(usage) {
     const words = [];
     let depth = 0;
     let leading = true;
     for (const token of usage.split(/\s+/).filter(Boolean)) {
-        // An angle-bracket alternation of plain words — `<bash|zsh|fish>`, the completion
-        // command's shell positional — expands to each alternative as a subcommand word, so
-        // `tumwater completion <TAB>` lists exactly the shells the command accepts. A bare
-        // placeholder like `<id>` or `<k>` carries no `|` and so stays a placeholder, skipped
-        // as before (its `<`/`>` never leave the token, so it never looked like a word).
-        const alternation = /^<([a-z][a-z-]*(?:\|[a-z][a-z-]*)+)>$/.exec(token);
-        if (alternation && leading) {
-            for (const alt of alternation[1].split("|"))
-                words.push(alt);
+        const alternates = alternationWords(token, leading);
+        if (alternates) {
+            words.push(...alternates);
             continue;
         }
         const bare = token.replace(/[[\]|]/g, "");
-        const isWord = /^[a-z][a-z-]*$/.test(bare);
-        if (isWord && (depth > 0 || token.startsWith("[") || leading))
+        if (isCompletableWord(bare, token, depth, leading))
             words.push(bare);
-        else if (depth === 0 && !token.startsWith("[") && bare !== "")
+        else if (endsLeadingRun(bare, token, depth))
             leading = false;
-        for (const ch of token)
-            depth += ch === "[" ? 1 : ch === "]" ? -1 : 0;
+        depth += bracketDelta(token);
     }
     return words;
 }
+/** The completable words of a stanza's usage part: the text after `tumwater <command>` up to the
+ * description column (two or more spaces). */
+function usageWords(firstLine, command) {
+    return usageWordsIn(usagePortion(firstLine, command));
+}
 export function completionSpec(help = HELP) {
     const stanzas = helpStanzas(help);
     const commands = [...new Set(stanzas.map((s) => s.command))];
@@ -152,6 +179,15 @@ export function configValueWords(key) {
 const ROLE_POSITIONAL_COMMANDS = ["role", "history", "revert"];
 /** Flags whose value is a file path: completion offers file names after them. */
 const PATH_FLAGS = ["--file", "--attach", "--notes-file", "--instructions-file", "--path"];
+/** The constant fish value suffix for the flags whose candidates are a fixed `__tumwater_*` list:
+ * `--role`, `--result`, `--type` and `--status` take comma lists, so they complete per item through
+ * `__fish_complete_list`, skipping the items already listed. */
+const FISH_LIST_FLAG_SUFFIXES = {
+    "--role": ` -x -a "(__fish_complete_list , __tumwater_roles)"`,
+    "--result": ` -x -a "(__fish_complete_list , __tumwater_results)"`,
+    "--type": ` -x -a "(__fish_complete_list , __tumwater_types)"`,
+    "--status": ` -x -a "(__fish_complete_list , __tumwater_review_states)"`,
+};
 /** The event-type codes `logs --type` filters by: the keys of the labels map, so a new event
  * type completes the moment it gains a label. Sorted for a stable, alphabetical offer of a
  * vocabulary too large to recall offhand — the same reason `--role`, `--template`, and
@@ -289,37 +325,37 @@ function bashScript(help) {
         ``,
     ].join("\n");
 }
-/** The value suffix a fish flag line carries: what completes after the flag. `--role`, `--result`
- * `--type` and `--status` take comma lists, so they complete per item through
- * `__fish_complete_list`,
- * skipping the items already listed. */
-function fishFlagValue(command, flag) {
-    if (flag === "--role")
-        return ` -x -a "(__fish_complete_list , __tumwater_roles)"`;
+/** The fish value suffix for the flags whose value depends on the command: `--transcript` has role
+ * ids only under `logs`, and `--model` completes the closed tier set under `role` but the log's
+ * selectors under `history`. Undefined for a flag this helper does not own. */
+function fishScopedFlagSuffix(command, flag) {
     if (flag === "--transcript" && command === "logs")
-        return ` -x -a "(__fish_complete_list , __tumwater_roles)"`;
-    if (PATH_FLAGS.includes(flag))
-        return ` -r -F`;
-    if (flag === "--template")
-        return ` -x -a "${templateIds().join(" ")}"`;
-    if (flag === "--result")
-        return ` -x -a "(__fish_complete_list , __tumwater_results)"`;
-    if (flag === "--type")
-        return ` -x -a "(__fish_complete_list , __tumwater_types)"`;
-    if (flag === "--status")
-        return ` -x -a "(__fish_complete_list , __tumwater_review_states)"`;
-    if (flag === "--thinking")
-        return ` -x -a "${THINKING_LEVEL_WORDS.join(" ")}"`;
-    if (flag === "--backend")
-        return ` -x -a "${BACKEND_IDS.join(" ")}"`;
-    if (flag === "--by")
-        return ` -x -a "${HISTORY_SUMMARY_GROUPS.join(" ")}"`;
-    // `role --model` completes the closed tier set; `history --model` completes the log's selectors.
+        return FISH_LIST_FLAG_SUFFIXES["--role"];
     if (flag === "--model" && command === "role")
         return ` -x -a "${MODEL_TIERS.join(" ")}"`;
     if (flag === "--model" && command === "history")
         return ` -x -a "(__fish_complete_list , __tumwater_models)"`;
-    return "";
+    return undefined;
+}
+/** The fish value suffix for the flags whose candidates are a joined literal list. Undefined for a
+ * flag this helper does not own. */
+function fishWordSuffix(flag) {
+    switch (flag) {
+        case "--template": return ` -x -a "${templateIds().join(" ")}"`;
+        case "--thinking": return ` -x -a "${THINKING_LEVEL_WORDS.join(" ")}"`;
+        case "--backend": return ` -x -a "${BACKEND_IDS.join(" ")}"`;
+        case "--by": return ` -x -a "${HISTORY_SUMMARY_GROUPS.join(" ")}"`;
+        default: return undefined;
+    }
+}
+/** The value suffix a fish flag line carries: what completes after the flag. `--role`, `--result`
+ * `--type` and `--status` take comma lists, so they complete per item through
+ * `__fish_complete_list`,
+ * skipping the items already listed. Tries the command-scoped flags, then the fixed
+ * `__tumwater_*` list table, then the joined literal-word flags, and finally the path flags, in
+ * the same order the ladder did. */
+function fishFlagValue(command, flag) {
+    return fishScopedFlagSuffix(command, flag) ?? FISH_LIST_FLAG_SUFFIXES[flag] ?? fishWordSuffix(flag) ?? (PATH_FLAGS.includes(flag) ? " -r -F" : "");
 }
 function fishScript(help) {
     const spec = completionSpec(help);

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

@@ -59,16 +59,11 @@ function screenOperableKey(root, key) {
             fail(fieldError);
     }
     else if (parsed.kind === "map") {
-        // Only role-keyed maps check the role catalog. `maxConcurrentPerProvider.<provider>` is
-        // keyed by provider, not a role id, and `config set` writes it without the role check —
-        // so get/unset must agree, or set would succeed while get/unset refused the provider as
-        // an "unknown role". A typo'd role id in the other two maps is refused the same way set's
+        // Role-keyed maps check the role catalog: a typo'd role id is refused the way set's
         // validator treats it.
-        if (parsed.map !== "maxConcurrentPerProvider") {
-            const ids = knownRoleIds(config);
-            if (!ids.includes(parsed.role))
-                fail(unknownRoleMessage(parsed.role, ids));
-        }
+        const ids = knownRoleIds(config);
+        if (!ids.includes(parsed.role))
+            fail(unknownRoleMessage(parsed.role, ids));
     }
     return { parsed, config };
 }
@@ -89,72 +84,74 @@ function resolvedConfigValue(config, parsed, key) {
                         ? record.roles?.[parsed.id]?.[parsed.field]
                         : record[canonicalConfigKey(key)];
 }
-/** The `tumwater config` command body: bare prints the resolved config; `get` and `unset`
- * screen their key through screenOperableKey, while `set` writes through setConfigKey. */
-export async function cmdConfig(root, args = []) {
-    const [sub, key, ...rest] = args;
-    if (sub === "get") {
-        const { parsed, config } = screenOperableKey(root, key ?? "");
-        const value = resolvedConfigValue(config, parsed, key ?? "");
-        sayJsonLine(value === undefined ? null : value); // Absent optional key → JSON null.
-        return;
+/** The `config get` verb: screen the key through screenOperableKey, then print its resolved
+ * value (defaults merged in) as JSON, or JSON null when nothing sets it. */
+async function configGet(root, key) {
+    const { parsed, config } = screenOperableKey(root, key ?? "");
+    const value = resolvedConfigValue(config, parsed, key ?? "");
+    sayJsonLine(value === undefined ? null : value); // Absent optional key → JSON null.
+}
+/** The `config unset` verb: screen the key, remove it, and confirm what, if anything, was
+ * removed (or what the key now resolves to). */
+async function configUnset(root, key) {
+    // cli.ts's arity gate requires exactly two args (`unset <key>`) before cmdConfig runs;
+    // this is the defensive tail for a direct caller, matching the bare-config tail below.
+    if (key === undefined)
+        fail(CONFIG_USAGE);
+    const k = canonicalConfigKey(key);
+    // The same screens get runs first, so a typo'd top-level key, role id, or role field
+    // fails identically — unsetConfigKey's own parse/field checks are the mutation-side
+    // backstop, not the wording the operator sees.
+    const { parsed } = screenOperableKey(root, k);
+    const result = unsetConfigKey(root, k);
+    if (!result.ok)
+        fail(result.error);
+    // The reload only feeds the message, so a failed one leaves `now` undefined.
+    const reloaded = loadConfigSafe(root).config;
+    const now = reloaded === undefined ? undefined : resolvedConfigValue(reloaded, parsed, k);
+    const resolves = now === undefined ? "" : JSON.stringify(now);
+    if (result.oldValue === undefined) {
+        say(`${k} is not set in tumwater.json, so nothing was removed` +
+            (now === undefined ? "" : ` (it resolves to ${resolves})`));
     }
-    if (sub === "unset") {
-        // cli.ts's arity gate requires exactly two args (`unset <key>`) before cmdConfig runs;
-        // this is the defensive tail for a direct caller, matching the bare-config tail below.
-        if (key === undefined)
-            fail(CONFIG_USAGE);
-        const k = canonicalConfigKey(key);
-        // The same screens get runs first, so a typo'd top-level key, role id, or role field
-        // fails identically — unsetConfigKey's own parse/field checks are the mutation-side
-        // backstop, not the wording the operator sees.
-        const { parsed } = screenOperableKey(root, k);
-        const result = unsetConfigKey(root, k);
-        if (!result.ok)
-            fail(result.error);
-        // The reload only feeds the message, so a failed one leaves `now` undefined.
-        const reloaded = loadConfigSafe(root).config;
-        const now = reloaded === undefined ? undefined : resolvedConfigValue(reloaded, parsed, k);
-        const resolves = now === undefined ? "" : JSON.stringify(now);
-        if (result.oldValue === undefined) {
-            say(`${k} is not set in tumwater.json, so nothing was removed` +
-                (now === undefined ? "" : ` (it resolves to ${resolves})`));
-        }
-        else {
-            const was = JSON.stringify(result.oldValue);
-            say(`unset ${k} (was ${was}${now === undefined ? "" : `; now resolves to ${resolves}`})`);
-        }
-        return;
+    else {
+        const was = JSON.stringify(result.oldValue);
+        say(`unset ${k} (was ${was}${now === undefined ? "" : `; now resolves to ${resolves}`})`);
     }
-    if (sub === "set") {
-        // A flag-looking value is a dropped `--` in disguise: `config set model --json` would
-        // otherwise take the literal string "--json" as the value (the JSON-parse fallback
-        // swallows any token) and validateConfig's string keys accept it silently — the same
-        // shape gui/gui-command.ts's --token gate refuses, where the value the next flag holds is never
-        // what the operator meant. Refuse before setConfigKey reads it; a value that really
-        // does begin with `--` has no legitimate shape among the config keys' values
-        // (identifiers, durations, windows, JSON scalars and arrays), so nothing is lost.
-        const raw = rest[0] ?? "";
-        if (raw.startsWith("--"))
-            fail(`config set got the flag-looking value ${JSON.stringify(raw)} instead of a value — is a flag missing its value, or did a token slip into the value's position? (e.g. \`tumwater config set model gpt-5\`)`);
-        const result = setConfigKey(root, key ?? "", raw);
-        if (!result.ok)
-            fail(result.error);
-        if (result.unchanged) {
-            say(`${canonicalConfigKey(key ?? "")} is already ${JSON.stringify(result.value)}, so tumwater.json was not written`);
-            return;
-        }
-        say(`set ${canonicalConfigKey(key ?? "")} to ${JSON.stringify(result.value)}`);
-        const note = result.note;
-        if (note)
-            say(`note: ${note}`);
-        // A bare `roles` set replaces the FILE's section, but the built-in catalog always merges
-        // per entry at load, so the replacement cannot disable a role by omission. Say so here
-        // rather than let the confirmation imply the role is gone.
-        if (key === "roles")
-            say("note: the built-in role catalog still merges per entry — disable a role with `tumwater config set roles.<id>.enabled false`, not by omitting it");
+}
+/** The `config set` verb: write one value through setConfigKey (refusing a flag-looking
+ * value first) and confirm the write or that it was already that value. */
+async function configSet(root, key, rest) {
+    // A flag-looking value is a dropped `--` in disguise: `config set model --json` would
+    // otherwise take the literal string "--json" as the value (the JSON-parse fallback
+    // swallows any token) and validateConfig's string keys accept it silently — the same
+    // shape gui/gui-command.ts's --token gate refuses, where the value the next flag holds is never
+    // what the operator meant. Refuse before setConfigKey reads it; a value that really
+    // does begin with `--` has no legitimate shape among the config keys' values
+    // (identifiers, durations, windows, JSON scalars and arrays), so nothing is lost.
+    const raw = rest[0] ?? "";
+    if (raw.startsWith("--"))
+        fail(`config set got the flag-looking value ${JSON.stringify(raw)} instead of a value — is a flag missing its value, or did a token slip into the value's position? (e.g. \`tumwater config set model gpt-5\`)`);
+    const result = setConfigKey(root, key ?? "", raw);
+    if (!result.ok)
+        fail(result.error);
+    if (result.unchanged) {
+        say(`${canonicalConfigKey(key ?? "")} is already ${JSON.stringify(result.value)}, so tumwater.json was not written`);
         return;
     }
+    say(`set ${canonicalConfigKey(key ?? "")} to ${JSON.stringify(result.value)}`);
+    const note = result.note;
+    if (note)
+        say(`note: ${note}`);
+    // A bare `roles` set replaces the FILE's section, but the built-in catalog always merges
+    // per entry at load, so the replacement cannot disable a role by omission. Say so here
+    // rather than let the confirmation imply the role is gone.
+    if (key === "roles")
+        say("note: the built-in role catalog still merges per entry — disable a role with `tumwater config set roles.<id>.enabled false`, not by omitting it");
+}
+/** The bare-config tail: the whole resolved config as pretty JSON, refusing a surplus
+ * subcommand the arity gate somehow missed. */
+async function configDump(root, sub) {
     // Bare config, or anything else: the whole-config dump is the default, and cli.ts's arity
     // check has already rejected a malformed get/set — this usage line is the defensive tail.
     if (sub !== undefined)
@@ -164,3 +161,17 @@ export async function cmdConfig(root, args = []) {
         fail(error); // validateConfig's message, via the standard fail()
     sayJson(config);
 }
+/** The `tumwater config` command body: bare prints the resolved config; `get` and `unset`
+ * screen their key through screenOperableKey, while `set` writes through setConfigKey. Each
+ * verb's guards and confirmation wording live in one named helper — configGet, configUnset,
+ * configSet, configDump — that this dispatcher delegates to. */
+export async function cmdConfig(root, args = []) {
+    const [sub, key, ...rest] = args;
+    if (sub === "get")
+        return configGet(root, key);
+    if (sub === "unset")
+        return configUnset(root, key);
+    if (sub === "set")
+        return configSet(root, key, rest);
+    return configDump(root, sub);
+}

package/dist/src/cli/help.js

@@ -313,9 +313,8 @@ Usage:
                                    non-blank line is the symptom, the rest is the body kept
                                    line for line; wakes the bugfix role
   tumwater bug --release <n> [--json]
-                                   Lift the Refused or a
-                                   Needs-review note held past its threshold
-                                   (one per run) from the Nth entry in BUGS.md ## Open (as
+                                   Lift the Refused or the
+                                   Needs review notes from the Nth entry in BUGS.md ## Open (as
                                    \`tumwater bug --list\` lists it), commit it on main, and wake
                                    the bugfix role; --json prints {file, title, lifted}
   tumwater bug --top <n> [--json]
@@ -370,9 +369,8 @@ Usage:
                                    the first non-blank line is the title, the rest is the body
                                    kept line for line; wakes the feature role
   tumwater plan --release <n> [--json]
-                                   Lift the Refused or a
-                                   Needs-review note held past its threshold
-                                   (one per run) from the Nth entry in PLANS.md ## Planned
+                                   Lift the Refused or the
+                                   Needs review notes from the Nth entry in PLANS.md ## Planned
                                    (as \`tumwater plan --list\` lists it), commit it on main,
                                    and wake the feature role; --json prints {file, title, lifted}
   tumwater plan --top <n> [--json]