tumwater 0.2.0 → 0.3.0

package/dist/src/cli/completion.js

@@ -1,12 +1,13 @@
-// vocabulary: plain
 /** Shell completion derived from the help text. The spec is parsed from the same HELP stanzas
  * `tumwater help <command>` and the unknown-command suggestion use, so a new command or flag
  * completes the moment it gains a help stanza and can never drift from the listing. */
-import { customLoopNames, knownRoleIds, loadConfig } from "../config/config.js";
-import { AGENT_IDS, AGENT_KEYS, CLAUDE_AGENT_KEYS, MODEL_TIERS, ROLE_ENTRY_KEYS, TOP_LEVEL_KEYS } from "../config/config-schema.js";
-import { DOTTED_MAP_KEYS } from "../config/config-keys.js";
-import { HISTORY_RESULT_FLAG_NAMES } from "../history/history-data.js";
+import { customRoleNames, knownRoleIds, loadConfig } from "../config/config.js";
+import { BACKEND_IDS, BACKEND_KEYS, CLAUDE_AGENT_KEYS, CODEX_BACKEND_KEYS, MODEL_TIERS, ROLE_ENTRY_KEYS, THINKING_LEVELS, TOP_LEVEL_KEYS } from "../config/config-schema.js";
+import { DOTTED_MAP_KEYS, DOTTED_SECTION_FIELDS } from "../config/config-keys.js";
+import { compareCodeUnits } from "../collections.js";
+import { HISTORY_MAX_RUNS, HISTORY_RESULT_FLAG_NAMES, HISTORY_SUMMARY_GROUPS, readRunRows } from "../history/history-data.js";
 import { templateIds } from "../init/init-templates.js";
+import { DOCTOR_CHECK_NAMES } from "../doctor/doctor-check-names.js";
 import { allRoleIds } from "../roles/roles.js";
 import { EVENT_TYPE_LABELS } from "../events/event-labels.js";
 import { HELP, helpStanzas } from "./help.js";
@@ -14,7 +15,7 @@ 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 notebook`) adds nothing. */
+ * a single-space description (`role <id> --clear-notes Clear that notes`) adds nothing. */
 function usageWords(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
@@ -66,7 +67,7 @@ export function completionSpec(help = HELP) {
     }
     return { commands, subcommands, flags };
 }
-/** The ids `--role` completes: this repo's loop ids, or the built-in catalog when tumwater.json is
+/** The ids `--role` completes: this repo's role ids, or the built-in catalog when tumwater.json is
  * unreadable (a broken config must not write errors into the operator's prompt). */
 export function completionRoleIds(root) {
     try {
@@ -76,14 +77,29 @@ export function completionRoleIds(root) {
         return allRoleIds();
     }
 }
+/** The selectors `history --model` completes: the distinct models recent runs started on, in the
+ * order `history --summary --by model` lists them. An unreadable or absent log must not write
+ * errors into the operator's prompt, and outside a repo it prints nothing. */
+export function completionModels(root) {
+    try {
+        const models = new Set();
+        for (const row of readRunRows(root, HISTORY_MAX_RUNS, null))
+            if (row.model !== null)
+                models.add(row.model);
+        return [...models].sort(compareCodeUnits);
+    }
+    catch {
+        return [];
+    }
+}
 /** The keys `config get|set|unset` complete: every form parseConfigKey accepts, with the
- * role-scoped keys of this repo's base roles and custom loops (not instance ids like
+ * role-scoped keys of this repo's base roles and custom roles (not instance ids like
  * `feature-2`). A broken tumwater.json falls back to the built-in catalog rather than writing
  * errors into the prompt. */
 export function completionConfigKeys(root) {
     let roleIds;
     try {
-        roleIds = [...allRoleIds(), ...customLoopNames(loadConfig(root))];
+        roleIds = [...allRoleIds(), ...customRoleNames(loadConfig(root))];
     }
     catch {
         roleIds = allRoleIds();
@@ -91,19 +107,64 @@ export function completionConfigKeys(root) {
     const keys = [
         ...TOP_LEVEL_KEYS,
         ...MODEL_TIERS.map((tier) => `model.${tier}`),
-        ...AGENT_IDS.flatMap((id) => (id === "claude" ? CLAUDE_AGENT_KEYS : AGENT_KEYS).map((field) => `backends.${id}.${field}`)),
+        ...BACKEND_IDS.flatMap((id) => (id === "claude" ? CLAUDE_AGENT_KEYS : id === "codex" ? CODEX_BACKEND_KEYS : BACKEND_KEYS).map((field) => `backends.${id}.${field}`)),
         ...DOTTED_MAP_KEYS.flatMap((map) => roleIds.map((id) => `${map}.${id}`)),
+        ...Object.entries(DOTTED_SECTION_FIELDS).flatMap(([section, fields]) => fields.map((field) => `${section}.${field}`)),
         ...roleIds.flatMap((id) => ROLE_ENTRY_KEYS.map((field) => `roles.${id}.${field}`)),
     ];
     return [...new Set(keys)];
 }
+/** The value vocabulary `config set <key> <value>` completes for one key, or [] when the
+ * field is free-form. The discrete-valued keys source the SAME closed constants the config
+ * validation accepts — BACKEND_IDS for a `.backend` field or the top-level `backend`,
+ * MODEL_TIERS for a `.model` field (the tier-name shorthand checkModelTripleField/review
+ * allow), THINKING_LEVELS for a `.thinking` field or the top-level `thinking`, and
+ * `true|false` for the always-boolean `.enabled` — so a domain changes the moment its
+ * constant does. `provider` (top-level, `roles.<id>.provider`, `review.provider`) is a
+ * free-form pi provider name, NOT a backend id — the ids validation rejects as the retired
+ * backend namespace on the default pi backend — so it completes nothing rather than offering
+ * ids that `set` would refuse. Number/free-text values (instances, minRunIntervalSeconds,
+ * maxDailyCostUsd, backends' bin/args, a full model id) are not worth a TAB either. The
+ * `config set` value-position arm in bashScript shells out here, so the vocabulary lives in
+ * exactly one place on every shell. */
+export function configValueWords(key) {
+    const dot = key.lastIndexOf(".");
+    if (dot < 0) {
+        // A dot-less key is a whole top-level key (TOP_LEVEL_KEYS); `backend` and `thinking` are
+        // the two discrete-valued ones, the rest are free-form numbers/strings/objects.
+        switch (key) {
+            case "backend": return [...BACKEND_IDS];
+            case "thinking": return [...THINKING_LEVELS];
+            default: return [];
+        }
+    }
+    switch (key.slice(dot + 1)) {
+        case "enabled": return ["true", "false"];
+        case "backend": return [...BACKEND_IDS];
+        case "model": return [...MODEL_TIERS];
+        case "thinking": return [...THINKING_LEVELS];
+        default: return [];
+    }
+}
+/** Commands whose first positional (word 2) is a role id, so completion offers
+ * `tumwater completion --roles` there. */
+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"];
+const PATH_FLAGS = ["--file", "--attach", "--notes-file", "--instructions-file", "--path"];
 /** 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
  * `--result` complete their values. */
 const EVENT_TYPE_CODES = Object.keys(EVENT_TYPE_LABELS).sort();
+/** The pi `--thinking` levels `role <id> --thinking <level>` accepts: the canonical
+ * THINKING_LEVELS set, Set spread preserving its insertion order (= the order the
+ * role-help and config-field-checks message list them), so `--thinking` completes its
+ * vocabulary the way `--type` and `--result` complete theirs. One source, so a new level
+ * completes the moment THINKING_LEVELS grows. */
+const THINKING_LEVEL_WORDS = [...THINKING_LEVELS];
+/** The doctor check names, each in plain double quotes, for the scripts to loop over. The names
+ * hold no `"`, `$`, backtick or `\`, so plain double quotes are exact; a test pins this. */
+const DOCTOR_CHECK_WORDS = DOCTOR_CHECK_NAMES.map((n) => `"${n}"`).join(" ");
 function bashScript(help) {
     const spec = completionSpec(help);
     const arms = spec.commands.map((command) => {
@@ -125,12 +186,32 @@ function bashScript(help) {
     });
     return [
         `# tumwater completion (generated from \`tumwater help\`)`,
+        `# Completes the item after the last comma of a comma-list value, keeping the items before it and dropping those already listed.`,
+        `_tumwater_list() {`,
+        `  local head="" word words=""`,
+        `  [[ "$2" == *,* ]] && head="\${2%,*},"`,
+        `  for word in $(printf '%s\\n' "$1"); do`,
+        `    [[ ",$head" == *",$word,"* ]] || words+="$word "`,
+        `  done`,
+        `  COMPREPLY=( $(compgen -P "$head" -W "$words" -- "\${2##*,}") )`,
+        `}`,
         `_tumwater() {`,
         `  local cur="\${COMP_WORDS[COMP_CWORD]}"`,
         `  local prev="\${COMP_WORDS[COMP_CWORD-1]}"`,
         `  COMPREPLY=()`,
-        `  if [ "$prev" = "--role" ] || { [ "$COMP_CWORD" -eq 2 ] && [[ "\${COMP_WORDS[1]}" == role || "\${COMP_WORDS[1]}" == history ]] && [[ "$cur" != -* ]]; }; then`,
-        `    COMPREPLY=( $(compgen -W "$(tumwater completion --roles 2>/dev/null)" -- "$cur") )`,
+        `  if [ "\${COMP_WORDS[1]}" = doctor ] && [ "$COMP_CWORD" -ge 2 ] && [[ "$cur" != -* ]]; then`,
+        `    local word="$cur" quote="" name`,
+        `    case "$word" in \\"*|\\'*) quote="\${word:0:1}"; word="\${word:1}";; esac`,
+        `    word="\${word//\\\\/}"`,
+        `    for name in ${DOCTOR_CHECK_WORDS}; do`,
+        `      if [[ "$name" == "$word"* ]]; then`,
+        `        if [ -n "$quote" ]; then COMPREPLY+=("$name"); else COMPREPLY+=("$(printf '%q' "$name")"); fi`,
+        `      fi`,
+        `    done`,
+        `    return 0`,
+        `  fi`,
+        `  if [ "$prev" = "--role" ] || { [ "$prev" = "--transcript" ] && [ "\${COMP_WORDS[1]}" = logs ]; } || { [ "$COMP_CWORD" -eq 2 ] && [[ ${ROLE_POSITIONAL_COMMANDS.map((c) => `"\${COMP_WORDS[1]}" == ${c}`).join(" || ")} ]] && [[ "$cur" != -* ]]; }; then`,
+        `    _tumwater_list "$(tumwater completion --roles 2>/dev/null)" "$cur"`,
         `    return 0`,
         `  fi`,
         `  case "$prev" in ${PATH_FLAGS.join("|")})`,
@@ -143,17 +224,44 @@ function bashScript(help) {
         `    return 0`,
         `  fi`,
         `  if [ "$prev" = "--result" ]; then`,
-        `    COMPREPLY=( $(compgen -W "${Object.values(HISTORY_RESULT_FLAG_NAMES).join(" ")}" -- "$cur") )`,
+        `    _tumwater_list "${Object.values(HISTORY_RESULT_FLAG_NAMES).join(" ")}" "$cur"`,
         `    return 0`,
         `  fi`,
         `  if [ "$prev" = "--type" ]; then`,
-        `    COMPREPLY=( $(compgen -W "${EVENT_TYPE_CODES.join(" ")}" -- "$cur") )`,
+        `    _tumwater_list "${EVENT_TYPE_CODES.join(" ")}" "$cur"`,
+        `    return 0`,
+        `  fi`,
+        `  if [ "$prev" = "--thinking" ]; then`,
+        `    COMPREPLY=( $(compgen -W "${THINKING_LEVEL_WORDS.join(" ")}" -- "$cur") )`,
+        `    return 0`,
+        `  fi`,
+        `  if [ "$prev" = "--by" ]; then`,
+        `    COMPREPLY=( $(compgen -W "${HISTORY_SUMMARY_GROUPS.join(" ")}" -- "$cur") )`,
+        `    return 0`,
+        `  fi`,
+        `  if [ "$prev" = "--model" ] && [ "\${COMP_WORDS[1]}" = role ]; then`,
+        `    COMPREPLY=( $(compgen -W "${MODEL_TIERS.join(" ")}" -- "$cur") )`,
+        `    return 0`,
+        `  fi`,
+        // bash splits at `:`; past a selector's colon `prev` is not --model, so nothing completes.
+        // A comma list, like --role, so it completes per item.
+        `  if [ "$prev" = "--model" ] && [ "\${COMP_WORDS[1]}" = history ]; then`,
+        `    _tumwater_list "$(tumwater completion --models 2>/dev/null)" "$cur"`,
         `    return 0`,
         `  fi`,
         `  if [ "$COMP_CWORD" -eq 3 ] && [ "\${COMP_WORDS[1]}" = config ] && [[ "\${COMP_WORDS[2]}" == get || "\${COMP_WORDS[2]}" == set || "\${COMP_WORDS[2]}" == unset ]] && [[ "$cur" != -* ]]; then`,
         `    COMPREPLY=( $(compgen -W "$(tumwater completion --config-keys 2>/dev/null)" -- "$cur") )`,
         `    return 0`,
         `  fi`,
+        // config set's VALUE sits at word 4, after the key a set write scopes (get/unset take no
+        // value, so only set reaches here). It shells out for the key's discrete vocabulary — the
+        // dotted fields (roles.<id>.<field>, review.<field>) and the top-level `backend`/`thinking`
+        // keys — and resolves to nothing for a free-form value, all decided in configValueWords so
+        // the vocabulary lives in exactly one place on every shell.
+        `  if [ "$COMP_CWORD" -eq 4 ] && [ "\${COMP_WORDS[1]}" = config ] && [ "\${COMP_WORDS[2]}" = set ] && [[ "$cur" != -* ]]; then`,
+        `    COMPREPLY=( $(compgen -W "$(tumwater completion --config-value "\${COMP_WORDS[3]}" 2>/dev/null)" -- "$cur") )`,
+        `    return 0`,
+        `  fi`,
         `  if [ "$COMP_CWORD" -eq 1 ]; then`,
         `    COMPREPLY=( $(compgen -W "${spec.commands.join(" ")}" -- "$cur") )`,
         `    return 0`,
@@ -167,18 +275,31 @@ function bashScript(help) {
         ``,
     ].join("\n");
 }
-/** The value suffix a fish flag line carries: what completes after the flag. */
-function fishFlagValue(flag) {
+/** The value suffix a fish flag line carries: what completes after the flag. `--role`, `--result`
+ * and `--type` 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 "(tumwater completion --roles 2>/dev/null)"`;
+        return ` -x -a "(__fish_complete_list , __tumwater_roles)"`;
+    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 "${Object.values(HISTORY_RESULT_FLAG_NAMES).join(" ")}"`;
+        return ` -x -a "(__fish_complete_list , __tumwater_results)"`;
     if (flag === "--type")
-        return ` -x -a "${EVENT_TYPE_CODES.join(" ")}"`;
+        return ` -x -a "(__fish_complete_list , __tumwater_types)"`;
+    if (flag === "--thinking")
+        return ` -x -a "${THINKING_LEVEL_WORDS.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.
+    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 "";
 }
 function fishScript(help) {
@@ -187,6 +308,12 @@ function fishScript(help) {
         `# tumwater completion (generated from \`tumwater help\`)`,
         `complete -c tumwater -f`,
         `function __tumwater_argc; count (commandline -opc); end`,
+        `function __tumwater_doctor_checks; printf '%s\\n' ${DOCTOR_CHECK_WORDS}; end`,
+        `function __tumwater_unlisted; set -l typed (string split , -- (string match -r '^.*,' -- (commandline -ct))); while read -l word; contains -- $word $typed; or echo $word; end; end`,
+        `function __tumwater_roles; tumwater completion --roles 2>/dev/null | __tumwater_unlisted; end`,
+        `function __tumwater_results; printf '%s\\n' ${Object.values(HISTORY_RESULT_FLAG_NAMES).join(" ")} | __tumwater_unlisted; end`,
+        `function __tumwater_models; tumwater completion --models 2>/dev/null | __tumwater_unlisted; end`,
+        `function __tumwater_types; printf '%s\\n' ${EVENT_TYPE_CODES.join(" ")} | __tumwater_unlisted; end`,
         `complete -c tumwater -n __fish_use_subcommand -a "${spec.commands.join(" ")}"`,
     ];
     for (const command of spec.commands) {
@@ -194,9 +321,9 @@ function fishScript(help) {
         if (subs.length > 0)
             lines.push(`complete -c tumwater -n "__fish_seen_subcommand_from ${command}; and test (__tumwater_argc) -eq 2" -a "${subs.join(" ")}"`);
         for (const flag of spec.flags[command] ?? [])
-            lines.push(`complete -c tumwater -n "__fish_seen_subcommand_from ${command}" -l ${flag.slice(2)}${fishFlagValue(flag)}`);
+            lines.push(`complete -c tumwater -n "__fish_seen_subcommand_from ${command}" -l ${flag.slice(2)}${fishFlagValue(command, flag)}`);
     }
-    lines.push(`complete -c tumwater -n "__fish_seen_subcommand_from role history; and test (__tumwater_argc) -eq 2" -a "(tumwater completion --roles 2>/dev/null)"`, `complete -c tumwater -n "__fish_seen_subcommand_from config; and __fish_seen_subcommand_from get set unset; and test (__tumwater_argc) -eq 3" -a "(tumwater completion --config-keys 2>/dev/null)"`, ``);
+    lines.push(`complete -c tumwater -n "__fish_seen_subcommand_from ${ROLE_POSITIONAL_COMMANDS.join(" ")}; and test (__tumwater_argc) -eq 2" -a "(tumwater completion --roles 2>/dev/null)"`, `complete -c tumwater -n "__fish_seen_subcommand_from config; and __fish_seen_subcommand_from get set unset; and test (__tumwater_argc) -eq 3" -a "(tumwater completion --config-keys 2>/dev/null)"`, `complete -c tumwater -n "__fish_seen_subcommand_from config; and __fish_seen_subcommand_from set; and test (__tumwater_argc) -eq 4" -a "(tumwater completion --config-value (commandline -opc)[4] 2>/dev/null)"`, `complete -c tumwater -n "__fish_seen_subcommand_from doctor" -a "(__tumwater_doctor_checks)"`, ``);
     return lines.join("\n");
 }
 export function completionScript(shell, help = HELP) {

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

@@ -1,4 +1,3 @@
-// vocabulary: plain
 import { loadConfigSafe, knownRoleIds } from "../config/config.js";
 import { fail, say, sayJson, sayJsonLine } from "./cli-output.js";
 import { setConfigKey, unsetConfigKey, } from "../config/config-write.js";
@@ -9,10 +8,10 @@ import { unknownRoleMessage } from "../roles/roles.js";
 /** The `tumwater config` command's CLI layer (split out of operator/operator-commands.ts, which
  * keeps the other operator-command bodies): with no arguments, print the effective merged
  * config — exactly what `loadConfig(root)` returns — as pretty JSON, so an operator
- * debugging scheduling or custom-loop wiring sees what the team would actually load instead
+ * debugging scheduling or custom-role wiring sees what the team would actually load instead
  * of overlaying defaults onto tumwater.json by hand. A query, not a writer: no redaction (the
  * config holds no secrets — provider keys belong to pi's own env) and no transformation,
- * including the per-role entries custom loops merge into. `get <key>` prints that one key's
+ * including the per-role entries custom roles merge into. `get <key>` prints that one key's
  * resolved value (defaults merged in, exactly what the no-arg dump prints) as JSON, failing
  * with the valid top-level keys on an unknown one. An optional key nothing sets (model,
  * provider, fallbackModel, …) prints `null` — JSON's no-value — because JSON.stringify of an
@@ -28,7 +27,7 @@ import { unknownRoleMessage } from "../roles/roles.js";
 /** The config command's malformed-shapes usage line: cli.ts's arity gate fails a non-get/set
  * or wrongly-shaped subcommand with it, and cmdConfig repeats it as the defensive tail for an
  * argument the gate somehow missed. One constant so the synopsis cannot drift between the two
- * sites (mirrors tick-detail.ts's TICK_USAGE). */
+ * sites (mirrors run-detail.ts's RUN_DETAIL_USAGE). */
 export const CONFIG_USAGE = "usage: tumwater config [get <key> | set <key> <value> | unset <key>] (bare config prints the whole resolved config)";
 /** The key screens `config get` and `config unset` run before resolving or removing a value:
  * the shape parser's own error; the shared unknown-top-level-key message; then, for a dotted
@@ -64,22 +63,30 @@ function screenOperableKey(root, key) {
     }
     return { parsed, config };
 }
+/** The resolved value of one screened key in a loaded config (defaults merged in): what `config
+ * get` prints and what `config unset` reports the key now resolves to. Undefined when nothing
+ * sets it. */
+function resolvedConfigValue(config, parsed, key) {
+    const record = config;
+    return parsed.kind === "map"
+        ? record[parsed.map]?.[parsed.role]
+        : parsed.kind === "tier"
+            ? modelTierMap(record.model)[parsed.tier] // a string is shorthand for { default }
+            : parsed.kind === "agent"
+                ? record.backends?.[parsed.id]?.[parsed.field]
+                : parsed.kind === "section"
+                    ? record[parsed.section]?.[parsed.field]
+                    : parsed.kind === "role"
+                        ? 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 record = config;
-        const value = parsed.kind === "map"
-            ? record[parsed.map]?.[parsed.role]
-            : parsed.kind === "tier"
-                ? modelTierMap(record.model)[parsed.tier] // a string is shorthand for { default }
-                : parsed.kind === "agent"
-                    ? record.backends?.[parsed.id]?.[parsed.field]
-                    : parsed.kind === "role"
-                        ? record.roles?.[parsed.id]?.[parsed.field]
-                        : record[canonicalConfigKey(key ?? "")];
+        const value = resolvedConfigValue(config, parsed, key ?? "");
         sayJsonLine(value === undefined ? null : value); // Absent optional key → JSON null.
         return;
     }
@@ -92,13 +99,22 @@ export async function cmdConfig(root, args = []) {
         // 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.
-        screenOperableKey(root, k);
+        const { parsed } = screenOperableKey(root, k);
         const result = unsetConfigKey(root, k);
         if (!result.ok)
             fail(result.error);
-        say(result.oldValue === undefined
-            ? `unset ${k}`
-            : `unset ${k} (was ${JSON.stringify(result.oldValue)})`);
+        // 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;
     }
     if (sub === "set") {
@@ -115,7 +131,14 @@ export async function cmdConfig(root, args = []) {
         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.

package/dist/src/cli/follow-view.js

@@ -0,0 +1,75 @@
+/** The repaint loop every `-f/--follow` view shares (`status -f`, `queue -f`,
+ * `backlog -f`, `report -f`, `diff -f`): render once, then repaint on a fixed interval until
+ * Ctrl+C or the process that started the command exits. Lifted out of
+ * cli-query-commands.ts when `report -f` landed so the follow views have one leaf
+ * home instead of a per-command copy. */
+import { startParentDeathWatch } from "../process/supervisor.js";
+import { stripTerminalControls } from "../text/text.js";
+/** The default repaint interval for a follow view — a fixed cadence, no knob. */
+const FOLLOW_VIEW_INTERVAL_MS = 2000;
+/** A follow view's live loop: render once, then repaint on an interval until Ctrl+C or the
+ * process that started this one is gone (the same parent-death rule `logs -f` uses).
+ * Repaints in place with the `watch` clear-screen shape on a TTY, and prints frames
+ * separated by a blank line when stdout is not a TTY so a piped follow stays readable.
+ * The frame text may be read synchronously or async (a `diff -f` frame re-reads the change
+ * by running git plumbing). A sync read paints synchronously — each interval tick paints
+ * exactly one frame, the deterministic shape the mock-clock follow tests (status, queue,
+ * backlog) depend on; an async read is guarded so a slow frame is not stacked by the ticks
+ * that arrive while it is still painting. */
+export async function followView(frameText, seams) {
+    const tty = seams.tty ?? process.stdout.isTTY;
+    const interval = seams.intervalMs ?? FOLLOW_VIEW_INTERVAL_MS;
+    // The frame's text is rendered from model-written data (role live progress, run
+    // summaries, backlog titles) that can carry terminal escape sequences. The one-shot
+    // forms of these commands sanitize at say(); this live reprint writes raw to the
+    // terminal while rerendering its own clear-screen prefix, so it must strip controls
+    // itself — the display-boundary rule stripTerminalControls documents, applied here.
+    const paint = (text) => {
+        const clean = stripTerminalControls(text);
+        process.stdout.write(tty ? "\x1b[H\x1b[2J" + clean + "\n" : clean + "\n\n");
+    };
+    // First paint: render once before the repaint loop's interval is registered, awaiting a
+    // slow async read so the first frame is on screen before the loop begins. Guarded exactly
+    // like the loop below (a failed frame is skipped, not fatal): the first read of a follow
+    // view can strike the same transient failure (a git read, a snapshot whose file is
+    // momentarily unreadable) as any later tick, and killing the whole interactive follow on
+    // it — while the identical failure a tick later is skipped and retried — is the same fault
+    // with a different outcome based only on which tick it lands on. `Promise.resolve()`
+    // first so a synchronous frame-throw is caught too.
+    await Promise.resolve()
+        .then(frameText)
+        .then(paint)
+        .catch(() => { });
+    // Repaint on the interval. `painting` guards an async read against stacking frames: while
+    // one async frame is in flight, a tick that arrives skips its repaint rather than queueing
+    // a second write on top of the first. The guard is checked BEFORE the read, so a tick that
+    // lands mid-frame does not start another (git-spawning) read just to discard it — which
+    // would also leave that read's rejections unhandled. Sync callers never set `painting`, so
+    // the check is a no-op for them: each of their ticks still paints exactly one frame.
+    let painting = false;
+    await new Promise((resolve) => {
+        const timer = setInterval(() => {
+            if (painting)
+                return;
+            const result = frameText();
+            if (result instanceof Promise) {
+                painting = true;
+                void result
+                    .then(paint)
+                    .catch(() => { })
+                    .finally(() => {
+                    painting = false;
+                });
+                return;
+            }
+            paint(result);
+        }, interval);
+        startParentDeathWatch(() => {
+            clearInterval(timer);
+            resolve();
+        }, {
+            ...(seams.ppid ? { ppid: seams.ppid } : {}),
+            ...(seams.intervalMs !== undefined ? { intervalMs: seams.intervalMs } : {}),
+        });
+    });
+}