tumwater 0.4.5 → 0.4.6

package/README.md

@@ -42,7 +42,7 @@ and is also outside `npm test`.
 ## Status
 
 <!-- tumwater:status:start -->
-**v0.4.5**: working tumwater. The director and 15 of the 17 roles are enabled by default; `selfcheck`,
+**v0.4.6**: working tumwater. The director and 15 of the 17 roles are enabled by default; `selfcheck`,
 which files tumwater bugs from tumwater's own event log, and `feedback`, which files them as GitHub
 issues on znation/tumwater, are opt-in (`roles.selfcheck.enabled`, `roles.feedback.enabled`).
 

package/dist/build-info.json

@@ -1,5 +1,5 @@
 {
-  "sha": "6440aaa1705f2accb491fa2155a5da6aadee05d8",
-  "builtAt": 1793604373395,
+  "sha": "e8bba8ae0464d05115b3eb917425d5d8d7629f66",
+  "builtAt": 1793691627357,
   "root": "/home/runner/work/tumwater/tumwater"
 }

package/dist/src/backlog/backlog-md.js

@@ -52,27 +52,42 @@ export function fenceTracker() {
             return fence !== null;
         },
         inside(line) {
-            const fenceLine = /^ {0,3}(`{3,}|~{3,})/.exec(line);
-            if (fenceLine) {
-                const marker = fenceLine[1] ?? ""; // The group always participates; "" keeps types honest.
-                if (fence === null) {
-                    // CommonMark: an info string for a backtick fence cannot contain a backtick, so a
-                    // line like ````md / ## Done / ````` quoted in prose is paragraph text, not a fence
-                    // opener — taken as one, no later bare fence line can close it and the fence runs to
-                    // EOF, swallowing the rest of the document as fenced content.
-                    const info = line.replace(/^ {0,3}/, "").slice(marker.length);
-                    if (marker.startsWith("`") && info.includes("`"))
-                        return false;
-                    fence = { char: marker.charAt(0), length: marker.length };
-                }
-                else if (marker.startsWith(fence.char) && marker.length >= fence.length && line.trim() === marker)
-                    fence = null;
-                return true; // The fence line itself is fence syntax, never structure.
+            if (fence === null) {
+                fence = fenceOpener(line);
+                return fence !== null; // An opener is fence syntax, never structure.
             }
-            return fence !== null;
+            if (closesFence(line, fence))
+                fence = null;
+            return true; // Inside a fence, every line (its closer too) is fence syntax or content.
         },
     };
 }
+/** A CommonMark fence line's leading marker run, or null: ```` ``` ```` or `~~~` (three or more)
+ * after at most three spaces of indent. */
+function fenceMarkerRun(line) {
+    return /^ {0,3}(`{3,}|~{3,})/.exec(line)?.[1] ?? null;
+}
+/** The fence `line` opens, or null when it opens none — CommonMark's opening rule, shared by
+ * fenceTracker and review-verdict.ts's quoted-code stripping. An info string may follow the
+ * marker, except that a backtick fence's info string may not contain a backtick: a line like
+ * ````md / ## Done / ````` quoted in prose is paragraph text. Taken as an opener, no later bare
+ * fence line could close it and the fence would run to EOF, swallowing the rest of the document
+ * as fenced content. */
+export function fenceOpener(line) {
+    const marker = fenceMarkerRun(line);
+    if (!marker)
+        return null;
+    const info = line.replace(/^ {0,3}/, "").slice(marker.length);
+    if (marker.startsWith("`") && info.includes("`"))
+        return null;
+    return { char: marker.charAt(0), length: marker.length };
+}
+/** Whether `line` closes `fence` — CommonMark's closing rule: a bare fence line (no info
+ * string) of the same character, at least as long as the opener. */
+export function closesFence(line, fence) {
+    const marker = fenceMarkerRun(line);
+    return marker !== null && marker.startsWith(fence.char) && marker.length >= fence.length && line.trim() === marker;
+}
 /** The title of a markdown heading line at `prefix` level — or the empty string when the heading
  * carries no text. The prefix's own length drives the slice (never a hard-coded `3`/`4`), so the
  * two heading levels cannot drift. The single home of the heading-title slice, shared by

package/dist/src/baseline/main-red.js

@@ -1,5 +1,7 @@
+import path from "node:path";
 import { baseRoleOf } from "../roles/runner-ids.js";
-import { enqueueRolePrompt } from "../inbox/inbox.js";
+import { enqueueRolePrompt, queuedRolePromptRecords } from "../inbox/inbox.js";
+import { cancelQueuedFile } from "../inbox/inbox-cancel.js";
 import { liveConfig } from "../config/config.js";
 import { mergeCommandOf, rerunCommandOf } from "../build/build-check-detect.js";
 import { canRerun, rerunCommandLine, rerunTests } from "../build/build-check-rerun.js";
@@ -37,7 +39,8 @@ let lastMainRedSha = null;
  * names, or the red SHA when the red names none. Two red commits with the same failing set send
  * one heal prompt, not one per commit; a green main observed by the ci handoff
  * (`mainRedHealNote`) or the main watch (`clearHealKeyOnGreen`) clears it, so a set that
- * returns after green is healed again. */
+ * returns after green is healed again. The key is per process; what bounds ci's inbox across
+ * restarts is queueHealPrompt's replacement of a waiting heal prompt. */
 let lastHealKey = null;
 /** The failing tests a red verdict names, when the list is complete — non-empty and short of
  * FAILING_TESTS_MAX, which may have been cut short (the same rule as onlyKnownMainFailures).
@@ -60,7 +63,8 @@ function redMainMessage(red, action) {
  * lastMainRedSha) so the ci handoff (`mainRedHealNote`) and mainTipVerdict share one guard:
  * whichever observes the red first logs it, the other stays silent. `foundBy` is the role
  * whose path verified the red — when that role is not ci itself, one prompt is enqueued to
- * ci's own inbox so the healer runs on the orchestrator's next poll instead of waiting out
+ * ci's own inbox (replacing a heal prompt already waiting there, queueHealPrompt) so the
+ * healer runs on the orchestrator's next poll instead of waiting out
  * its own interval or deferral; ci finding its own red skips the enqueue because its running
  * run already carries the note and IS the heal (and enqueuing from inside it would queue a
  * second run). A queued per-role prompt makes the role due by itself (`isEligible`,
@@ -95,7 +99,7 @@ function warnMainRedOnce(root, red, foundBy) {
     lastHealKey = healKey;
     if (baseRoleOf(foundBy) !== "ci") {
         try {
-            enqueueRolePrompt(root, "ci", mainRedHealPrompt(red.sha));
+            queueHealPrompt(root, mainRedHealPrompt(red.sha));
         }
         catch (err) {
             // Clear the key so a later verification retries the heal. lastMainRedSha stays set, so a
@@ -113,7 +117,7 @@ function warnMainRedOnce(root, red, foundBy) {
  * before the healer consumes the prompt, mainRedHealNote returns undefined (no `<main-red>`
  * note is appended) and the "verify green" clause makes the run a no-op. */
 export function mainRedHealPrompt(sha, detail) {
-    const base = `Main was reported red at commit ${shortSha(sha)}. Verify main is green now; if it is still red, reproduce the failure and land the fix.`;
+    const base = `${HEAL_PROMPT_OPENING}${shortSha(sha)}. Verify main is green now; if it is still red, reproduce the failure and land the fix.`;
     if (!detail)
         return base;
     const tests = detail.failingTests.length > 0 ? ` Failing: ${detail.failingTests.join("; ")}.` : "";
@@ -126,6 +130,63 @@ export function mainRedHealPrompt(sha, detail) {
 function rerunAdvice(command) {
     return `Run only the failing tests, to reproduce them and again to prove the fix, with: ${command}`;
 }
+/** How every heal prompt opens: mainRedHealPrompt writes it, and queuedHealPrompts recognizes a
+ * waiting heal prompt in ci's inbox by it and reads back the SHA that follows. */
+const HEAL_PROMPT_OPENING = "Main was reported red at commit ";
+/** The heal prompts waiting in ci's inbox, oldest first: each queue file's basename and the
+ * short SHA it was reported red at. Every other prompt in the inbox (an operator's, a resume's
+ * re-queued non-heal request) is left out. An inbox that cannot be listed is warned and reads
+ * as holding none. */
+function queuedHealPrompts(root) {
+    try {
+        return queuedRolePromptRecords(root, "ci").flatMap((e) => {
+            if (!e.text.startsWith(HEAL_PROMPT_OPENING))
+                return [];
+            const sha = /^[0-9a-f]+(?=\.)/.exec(e.text.slice(HEAL_PROMPT_OPENING.length))?.[0];
+            return sha ? [{ file: e.file, sha }] : [];
+        });
+    }
+    catch (err) {
+        warnEventBestEffort(root, TUMWATER_SOURCE, `could not list ci's inbox for waiting heal prompts: ${errorMessage(err)}`);
+        return [];
+    }
+}
+/** Remove waiting heal prompts from ci's inbox, each logged as a prompt_cancelled under ci
+ * (cancelQueuedFile). Best-effort: a prompt that cannot be removed is warned and stays queued,
+ * so the heal just queued or the green just settled never fails on it. */
+function dropHealPrompts(root, files) {
+    for (const file of files) {
+        try {
+            cancelQueuedFile(root, "ci", file);
+        }
+        catch (err) {
+            warnEventBestEffort(root, TUMWATER_SOURCE, `could not drop the stale heal prompt ${file} from ci's inbox: ${errorMessage(err)}`);
+        }
+    }
+}
+/** Queue `prompt` for the ci healer in place of every heal prompt already waiting. A waiting one
+ * names an older red, and the healer verifies main as it is now whichever prompt it reads, so
+ * one waiting heal prompt is enough: without the replacement each red commit on a long red
+ * added one, and a healer that clears one per run fell 69 behind (2026-10-30 to 11-01). The new
+ * prompt is written first, so a write that fails throws with the older prompts still queued. */
+function queueHealPrompt(root, prompt) {
+    const queued = path.basename(enqueueRolePrompt(root, "ci", prompt));
+    dropHealPrompts(root, queuedHealPrompts(root).filter((p) => p.file !== queued).map((p) => p.file));
+}
+/** Drop each heal prompt waiting in ci's inbox whose red commit `greenSha` contains: main has
+ * passed its check since that red, so the run the prompt would start could only find main
+ * green. A prompt naming a commit `greenSha` does not contain (a red reported on a newer tip)
+ * stays queued. `wt` is any checkout of the repository, for the ancestry check. Called beside
+ * clearHealKeyOnGreen by the main watch's settled green and the ci hand-off's own green.
+ * Never throws. */
+export async function dropHealPromptsCoveredBy(root, wt, greenSha) {
+    const covered = [];
+    for (const { file, sha } of queuedHealPrompts(root)) {
+        if (await isMergedInto(wt, sha, greenSha))
+            covered.push(file);
+    }
+    dropHealPrompts(root, covered);
+}
 /** The command line that re-runs `red`'s named failures on their own (rerunCommandLine), or
  * undefined when they cannot be re-run alone (canRerun) — the healer is then left to the full
  * check. */
@@ -137,14 +198,15 @@ function healRerunLine(root, config, red) {
 /** Queue the heal prompt for ci with the culprit's detail: the one way a named red-main culprit
  * is answered (Forward, never back, part 4/6): the watch's onCulprit hand-off routes through
  * this, and nothing is ever reverted. (The ci gate's own red-main hand-off is the separate
- * direct `enqueueRolePrompt` in warnMainRedOnce.) Never throws: a prompt that cannot be
+ * queueHealPrompt call in warnMainRedOnce; both replace a heal prompt already waiting.) Never
+ * throws: a prompt that cannot be
  * queued (an unwritable inbox) is warned, like that hand-off guard in warnMainRedOnce — so
  * the watch's onCulprit (whose caller discards the result) cannot derail a watch run or end
  * the orchestrator. */
 export function queueCulpritHeal(root, tip, detail) {
     try {
         const rerun = healRerunLine(root, liveConfig(root), { failingTests: [...detail.failingTests], failingTestFiles: detail.failingTestFiles });
-        enqueueRolePrompt(root, "ci", mainRedHealPrompt(tip, { ...detail, ...(rerun ? { rerun } : {}) }));
+        queueHealPrompt(root, mainRedHealPrompt(tip, { ...detail, ...(rerun ? { rerun } : {}) }));
     }
     catch (err) {
         warnEventBestEffort(root, TUMWATER_SOURCE, `could not queue the heal prompt for ci: ${errorMessage(err)}`);
@@ -180,8 +242,10 @@ export async function mainRedHealNote(root, role, wt) {
         ? { baseline: await watchedBaseline(wt) }
         : await checkMainBaseline(wt, config, baselineCheckLogger(root, role));
     const red = baseline.baseline;
-    if (red?.status === "green")
+    if (red?.status === "green") {
         clearHealKeyOnGreen();
+        await dropHealPromptsCoveredBy(root, wt, red.sha);
+    }
     if (red?.status !== "red")
         return undefined;
     warnMainRedOnce(root, red, role);

package/dist/src/baseline/main-watch.js

@@ -1,7 +1,7 @@
 import { distinctOrdered } from "../collections.js";
 import { checkMainBaseline, settleRedByRerun } from "./main-baseline.js";
 import { canRerun, rerunTests } from "../build/build-check-rerun.js";
-import { baselineCheckLogger, clearHealKeyOnGreen, withMainTipWorktree } from "./main-red.js";
+import { baselineCheckLogger, clearHealKeyOnGreen, dropHealPromptsCoveredBy, withMainTipWorktree } from "./main-red.js";
 import { CHECK_TIER } from "../concurrency/check-permit.js";
 import { FAILING_TESTS_MAX } from "../build/build-check-report.js";
 import { detectBuildCheck } from "../build/build-check-detect.js";
@@ -267,11 +267,12 @@ export function createMainWatch(root, mainBranch, onCulprit) {
             // names the whole tip as the culprit, so the two red kinds are judged independently.
             await watchRules(wt, previous, baseline.sha);
             // A settled non-red verdict (a green, or a red naming only quarantined tests) clears the
-            // heal-dedup key, so a failing set that returns after a green main is healed again. A
-            // settled red verdict below does NOT clear it: the heal-dedup key stays set while main
-            // is red.
+            // heal-dedup key, so a failing set that returns after a green main is healed again, and
+            // drops the heal prompts still waiting for a red this tip has passed. A settled red
+            // verdict below does NOT clear it: the heal-dedup key stays set while main is red.
             if (!red) {
                 clearHealKeyOnGreen();
+                await dropHealPromptsCoveredBy(root, wt, baseline.sha);
                 redSpellOpeners.delete(root); // a green closes the red spell; the next red names its own opener
                 return;
             }

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

@@ -398,6 +398,14 @@ export function failOverDurationCap(flag, ms, maxMs, hint) {
 export function failRivalShapes(subject, rival, why) {
     fail(`${subject} cannot be combined with ${rival} (${why})`);
 }
+/** The shared why-clause for a trailing-window view's `-f/--follow` rival: follow is an
+ * unbounded "from now on" read, while `--since` opens a bounded past window, so the two are
+ * mutually exclusive on the same grounds in all three windowed views (logs, history, report).
+ * One clause so the three sites cannot drift on what follow means and why it excludes
+ * `--since`; the subject keeps the command's own name. */
+export function failFollowSinceRival(command) {
+    return failRivalShapes(`${command} --since`, "-f/--follow", 'follow means "from now on"; --since shows a bounded past window');
+}
 /** Guard a trailing-window command's `--until <window>` against its `--since <window>` pair —
  * the shared fail sentences the three windowed views (logs, history, report) print, so the
  * wording cannot drift per command. When `--until` is present but `--since` is not, it fails
@@ -459,11 +467,16 @@ export function parseRoleFlag(args, validIds, flag = "--role", missingValue = RO
 }
 /** Parse an optional `--branch <name>` flag: the named branch, or null when absent — the same
  * shape as parseRoleFlag, so every command that scopes to one branch validates identically.
- * A missing value fails fast instead of silently falling back to the checked-out branch. */
+ * A missing value fails fast instead of silently falling back to the checked-out branch. A
+ * `--`-token in the slot is the operator's slipped next flag (`run --branch --json`), never a
+ * branch name — a branch name never starts with `-` — so refuse it up front with
+ * rejectFlagLookingValue's shared wording, the same guard every other value slot applies,
+ * instead of reporting the next flag as a missing name. */
 export function parseBranchFlag(args) {
     const branch = flagValue(args, "--branch");
     if (branch === null)
         return null;
+    rejectFlagLookingValue("--branch", branch);
     if (!branch || branch.startsWith("-"))
         fail(BRANCH_VALUE_ERROR);
     return branch;

package/dist/src/cli/cli-flag-specs.js

@@ -240,7 +240,8 @@ export const N_FLAG = {
  * whole spec, and the render-vs-JSON switch stays in each command body beside its render. */
 export const JSON_FLAG = { names: ["--json"] };
 /** The `-f/--follow` flag spec, shared by every command with a follow view (logs, history,
- * status, queue, report, backlog and diff — each snapshot command's `-f/--follow` twin): one
+ * status, queue, report, backlog, diff and quarantine — each snapshot command's `-f/--follow`
+ * twin): one
  * definition of the flag's spelling, beside ROLE_FLAG and JSON_FLAG, so the gate's accepted
  * vocabulary cannot drift apart. It takes no value, like JSON_FLAG; each body renders its
  * own live view, and detects the flag through hasFollowFlag, so the spelling lives in exactly
@@ -248,8 +249,9 @@ export const JSON_FLAG = { names: ["--json"] };
 export const FOLLOW_FLAG = { names: ["-f", "--follow"] };
 /** Whether an arg array carries the `-f/--follow` flag — the detection every follow-capable
  * command body spelled out as an `includes("-f") || includes("--follow")` one-liner over
- * its own arg array (`args` for status, queue, report and diff; `rest` for logs, history and
- * backlog). Now derived from FOLLOW_FLAG's own spelling, so the detection cannot drift from
+ * its own arg array (`args` for status, queue, report, diff and quarantine; `rest` for logs,
+ * history and backlog). Now derived from FOLLOW_FLAG's own spelling, so the detection cannot
+ * drift from
  * the gate's accepted vocabulary. */
 export function hasFollowFlag(args) {
     return FOLLOW_FLAG.names.some((name) => args.includes(name));

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

@@ -1,6 +1,6 @@
 import { fail, say, sayJsonLine } from "./cli-output.js";
 import { hasFollowFlag, LOGS_TRANSCRIPT_VALUE_ERROR } from "./cli-flag-specs.js";
-import { betweenWindow, durationLabel, failRivalShapes, failUntilShorterThanSince, flagValue, parseCountFlag, parseGrepFlag, parseRoleListScope, parseRoleScope, parseSinceFlag, parseTypeFlag } from "./cli-args.js";
+import { betweenWindow, durationLabel, failFollowSinceRival, failRivalShapes, failUntilShorterThanSince, flagValue, parseCountFlag, parseGrepFlag, parseRoleListScope, parseRoleScope, parseSinceFlag, parseTypeFlag } from "./cli-args.js";
 import { LOGS_SINCE_MAX_MS, readEventsSince, SPARSE_WINDOW_NOTE, } from "../events/event-window.js";
 import { compareCodeUnits, increment } from "../collections.js";
 import { eventTypeTally } from "../events/event-tally.js";
@@ -229,7 +229,7 @@ function parseLogsFeed(root, args) {
  * prose, the `--count` tally, the per-event print and the sparse-window note. */
 function sayLogsWindow(root, feed, ms, untilMs) {
     if (feed.follow)
-        failRivalShapes("logs --since", "-f/--follow", 'follow means "from now on"; --since shows a bounded past window');
+        failFollowSinceRival("logs");
     if (feed.rest.includes("-n"))
         failRivalShapes("logs --since", "-n", "a count and a window are rival shapes");
     rejectTranscriptViewRival(feed.rest, "--since", true);

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

@@ -342,22 +342,34 @@ export async function cmdBacklog(root, args, seams = {}) {
     const result = readBacklog();
     sayJsonOrRender(rest, result.view, () => renderBacklogText(result));
 }
-// `tumwater quarantine [--release <n>] [--json]` — the view of the review gate's flake
-// quarantine, read-only except the one destructive `--release <n>` mode that removes the Nth
-// entry the list prints at the operator's request. The read path keeps its no-gate
-// refuseTeamWorkspace stance: loadQuarantine degrades an absent or malformed file to the empty
-// list, so the command prints the empty line in any directory and the read never writes
-// quarantine.json (a test otherwise leaves the list through releaseQuarantine). --json serves
-// the same positioned rows to scripts.
-export async function cmdQuarantine(root, args) {
+// `tumwater quarantine [-f/--follow] [--release <n>] [--json]` — the view of the review
+// gate's flake quarantine, read-only except the one destructive `--release <n>` mode that
+// removes the Nth entry the list prints at the operator's request. `-f/--follow` repaints the
+// list every couple of seconds until Ctrl+C or the process that started it exits, so a
+// backgrounded follow does not outlive its parent (the same rule `queue -f` uses). The read
+// path keeps its no-gate refuseTeamWorkspace stance: loadQuarantine degrades an absent or
+// malformed file to the empty list, so the command prints the empty line in any directory and
+// the read never writes quarantine.json (a test otherwise leaves the list through
+// releaseQuarantine). --json serves the same positioned rows to scripts.
+export async function cmdQuarantine(root, args, seams = {}) {
     // `--release <n>` is the read-only command's one destructive mode: route it to its own
     // branch before the read gate, exactly as cmdReviews routes `--accept`.
     if (args.includes("--release")) {
         await cmdQuarantineRelease(root, args);
         return;
     }
-    rejectUnknownArgs("quarantine", args, [JSON_FLAG]);
+    rejectUnknownArgs("quarantine", args, [JSON_FLAG, FOLLOW_FLAG]);
     refuseTeamWorkspace(root);
+    const follow = hasFollowFlag(args);
+    if (follow && args.includes("--json"))
+        fail("quarantine --json prints one document; -f/--follow repaints a live view — drop one of them");
+    // Each frame re-reads the quarantine file and reads the clock once, so an entry that
+    // appears, ages toward the ceiling, or leaves when its bug closes shows up in the next
+    // repaint — the same per-frame read `queue -f` uses.
+    if (follow) {
+        await followView(() => renderQuarantine(quarantineRows(loadQuarantine(root)), Date.now()), seams);
+        return;
+    }
     const rows = quarantineRows(loadQuarantine(root));
     sayJsonOrRender(args, { tests: rows }, () => renderQuarantine(rows, Date.now()));
 }

package/dist/src/cli/help.js

@@ -287,14 +287,17 @@ Usage:
                                    -f/--follow repaints the backlog every couple of seconds until
                                    Ctrl+C or the process that started it exits, so a backgrounded
                                    follow does not outlive its parent; it refuses --json
-  tumwater quarantine [--release <n>] [--json]
+  tumwater quarantine [-f/--follow] [--release <n>] [--json]
                                    List the flake quarantine — the tests the review gate recorded
                                    as failing then passing on the same tree
                                    (.tumwater/state/quarantine.json), oldest first, each naming
                                    its first-seen and last-seen age, flake count, and the BUGS.md
                                    entry filed for it (or "not filed"); empty prints
                                    "flake quarantine is empty"; --json prints the same rows as
-                                   { tests: [...] }; read-only except --release <n>, which
+                                   { tests: [...] }; -f/--follow repaints the list every couple of
+                                   seconds until Ctrl+C or the process that started it exits, so a
+                                   backgrounded follow does not outlive its parent, and it refuses
+                                   --json; read-only except --release <n>, which
                                    removes the Nth entry the list prints at the user's
                                    request, logging a warning — for a flake fixed or judged gone
                                    before its bug closes; otherwise a test leaves the list when

package/dist/src/cli.js

@@ -33,7 +33,7 @@ import { PACKAGE_JSON, nodeFloorProblem, packageEnginesNode, packageVersion } fr
  * Arity is gated before the ready-repo check so a malformed call fails with its usage in any
  * directory; cmdRunDetail owns the value validation and the --last/numbered rivals. */
 async function runTrailCommand(root, args) {
-    const { cmdRunDetail, RUN_DETAIL_USAGE } = await import("./run/run-detail.js");
+    const { cmdRunDetail, RUN_DETAIL_USAGE } = await import("./history/run-detail.js");
     const { HISTORY_GREP_VALUE_ERROR, HISTORY_RESULT_VALUE_ERROR, HISTORY_MODEL_VALUE_ERROR } = await import("./history/history.js");
     // parseGrepFlag removes the pattern token, so `--grep two` cannot read "two" as a positional.
     const { rest: ungrepped, pattern: grep } = parseGrepFlag(args, HISTORY_GREP_VALUE_ERROR);

package/dist/src/config/config-write.js

@@ -68,6 +68,70 @@ const PLAIN_INTEGER_TOP_LEVEL_KEYS = new Set([
     "maxConcurrentChecks",
     "worktreeSlots",
 ]);
+/** The duration-typed team keys whose value is a plain decimal second count (validateConfig's
+ * DURATION_* rules, config-validation.ts): the top-level run-timing knobs plus the section
+ * fields a dotted key names (`review.timeoutSeconds`, `check.timeoutSeconds`,
+ * `idleBackoff.initialSeconds`/`maxSeconds`) and the per-role
+ * `roles.<id>.minRunIntervalSeconds`. For these, an exponent spelling like "1e2" is itself a
+ * JSON number (100) that setConfigKey's JSON.parse would read past validateConfig's numeric
+ * check and silently write as the misread — the same silent misread the TUI Ctrl+S interval
+ * editor, the CLI's `role --min-run-interval` and the GUI interval drawer refuse — so
+ * setConfigKey refuses it, naming the key and writing nothing. `idleBackoff.factor` is a
+ * multiplier, not a second count, so it is not in this set. */
+const PLAIN_DURATION_KEYS = new Set([
+    "minRunIntervalSeconds",
+    "runTimeoutSeconds",
+    "quietTimeoutSeconds",
+    "toolCallStallSeconds",
+]);
+// The key-shape predicates for exponentRefusal's two numeric families, lifted out of its
+// body so "which keys take a plain integer or a plain second count" is read from the
+// key families instead of inline OR chains over `parsed`.
+/** The integer-bound keys: the top-level run-concurrency knobs (see
+ * PLAIN_INTEGER_TOP_LEVEL_KEYS), the per-role `instances` count and the
+ * `bootstrap.untilPlansDone` section field. For these, an exponent spelling is refused
+ * with the "plain integer" message. */
+function isPlainIntegerKey(parsed, key) {
+    return ((parsed.kind === "top" && PLAIN_INTEGER_TOP_LEVEL_KEYS.has(key)) ||
+        (parsed.kind === "role" && parsed.field === "instances") ||
+        (parsed.kind === "section" && parsed.section === "bootstrap" && parsed.field === "untilPlansDone"));
+}
+/** The duration-typed keys: a top-level second-count knob, the section fields a dotted
+ * key names (review/check's timeoutSeconds, idleBackoff's second counts), or the
+ * per-role minRunIntervalSeconds. They take plain decimals, not integers, so the
+ * refusal says "plain second count" — the wording the TUI interval editor, the CLI's
+ * `role --min-run-interval`, and the GUI drawer all use for the same misread. */
+function isPlainDurationKey(parsed) {
+    return ((parsed.kind === "top" && PLAIN_DURATION_KEYS.has(parsed.key)) ||
+        (parsed.kind === "section" &&
+            ((parsed.section === "review" && parsed.field === "timeoutSeconds") ||
+                (parsed.section === "check" && parsed.field === "timeoutSeconds") ||
+                (parsed.section === "idleBackoff" && (parsed.field === "initialSeconds" || parsed.field === "maxSeconds")))) ||
+        (parsed.kind === "role" && parsed.field === "minRunIntervalSeconds"));
+}
+/** The dollar-typed keys: the team-wide daily cost cap and the per-role cap map. For
+ * these, an exponent spelling is refused with the "plain dollar amount" message. */
+function isPlainDollarKey(parsed) {
+    return ((parsed.kind === "top" && parsed.key === "maxDailyCostUsd") ||
+        (parsed.kind === "map" && parsed.map === "maxDailyCostUsdPerRole"));
+}
+// The shape screen that stops setConfigKey's JSON.parse from silently writing an exponent
+// spelling ("4e1" → 40, "1e2" → 100) past a plain-integer, plain-second-count or
+// plain-dollar key's numeric check: each family's refusal names the key and writes
+// nothing — the twin of the per-role guards, the TUI team-key and budget editors, and the
+// GUI Settings rows and cap drawer. A blank or non-exponent spelling passes through to
+// the parse below (a non-exponent invalid is left for validateConfig's own message).
+function exponentRefusal(parsed, key, trimmed) {
+    if (trimmed === "" || !isExponentSpelling(trimmed))
+        return null;
+    if (isPlainIntegerKey(parsed, key))
+        return `${key} must be a plain integer — no exponent notation`;
+    if (isPlainDurationKey(parsed))
+        return `${key} must be a plain second count like 300, 0.5, or .5 — no +/-, exponent, or hex notation`;
+    if (isPlainDollarKey(parsed))
+        return `${key} must be a plain dollar amount like 25, 12.50, or .5 — no +/-, exponent, or hex notation`;
+    return null;
+}
 /** Set ONE top-level key of tumwater.json from its raw CLI text (`tumwater config set`'s
  * engine): the key must be a member of TOP_LEVEL_KEYS — the same protection checkKnownKeys
  * gives the file itself, so `config set modle x` cannot write a dead key the runtime would
@@ -89,14 +153,6 @@ export function setConfigKey(root, key, rawValue) {
     // The helpers are declared here — above the body — so they close over `root`; the two
     // write dispatches (writeDottedKey / writeTopLevelKey) each own one writeConfigMutation
     // and the per-kind merge groups close over that call's `value`/`unchanged`/`oldValue`.
-    const exponentRefusal = (parsed, key, trimmed) => {
-        const isPlainIntegerKey = (parsed.kind === "top" && PLAIN_INTEGER_TOP_LEVEL_KEYS.has(key)) ||
-            (parsed.kind === "role" && parsed.field === "instances") ||
-            (parsed.kind === "section" && parsed.section === "bootstrap" && parsed.field === "untilPlansDone");
-        if (isPlainIntegerKey && trimmed !== "" && isExponentSpelling(trimmed))
-            return `${key} must be a plain integer — no exponent notation`;
-        return null;
-    };
     // One named handler per parsed dotted-key kind: the shape/validator screen, then one
     // writeConfigMutation whose callback is the `switch (parsed.kind)` over the merge helpers.
     const writeDottedKey = (parsed, value) => {
@@ -303,14 +359,18 @@ export function setConfigKey(root, key, rawValue) {
     const parsed = parseConfigKey(key);
     if (parsed.kind === "error")
         return fail(parsed.error);
-    // Shape, before the JSON.parse, for every plain-positive-integer key this verb can write —
-    // the top-level run-concurrency knobs and legacy merge batch cap, plus the integer-bound
-    // team-scope keys that arrive as a dotted key (`roles.<id>.instances`, the
-    // `bootstrap.untilPlansDone` section field): refuse an exponent
-    // spelling ("4e1" → 40) that JSON.parse would read past validateConfig's integer check and
-    // silently write, naming the key and writing nothing — the twin of the per-role guards, the
-    // TUI team-key editors, and the GUI Settings rows. A non-exponent invalid falls through for
-    // validateConfig (whose message names the key). Empty clears the key below.
+    // Shape, before the JSON.parse, for every plain-positive-integer, plain-second-count or
+    // plain-dollar key this verb can write — the top-level run-concurrency knobs and legacy
+    // merge batch cap, the integer-bound team-scope keys that arrive as a dotted key
+    // (`roles.<id>.instances`, the `bootstrap.untilPlansDone` section field), the duration-typed
+    // keys (the top-level second-count knobs plus `review`/`check`/`idleBackoff`'s second fields
+    // and `roles.<id>.minRunIntervalSeconds`), and the dollar-typed keys
+    // (`maxDailyCostUsd`, the `maxDailyCostUsdPerRole.<role>` map entry): refuse an exponent
+    // spelling ("4e1" → 40, "1e2" → 100) that JSON.parse would read past the key's numeric
+    // check and silently write, naming the key and writing nothing — the twin of the per-role
+    // guards, the TUI team-key and budget editors, and the GUI Settings rows and cap drawer.
+    // A non-exponent invalid falls through for validateConfig (whose message names the key).
+    // Empty clears the key below.
     const trimmed = rawValue.trim();
     const refusal = exponentRefusal(parsed, key, trimmed);
     if (refusal)

package/dist/src/doctor/doctor-claude-checks.js

@@ -8,7 +8,7 @@ import { resolvedBackendConfig } from "../config/config-views.js";
 import { envPath } from "../files/files.js";
 import { belowNodeFloor } from "../version.js";
 import { failOutcome, okOutcome, warnOutcome } from "./doctor-outcome.js";
-import { claudeSeamsInUse, loadConfigForCheck, seamStandDown, versionFromProbe, seamedModels, } from "./doctor-model-checks.js";
+import { claudeSeamsInUse, loadConfigForCheck, probeUnreadableWarning, seamStandDown, versionFromProbe, seamedModels, } from "./doctor-model-checks.js";
 /** The doctor's claude credential and version readiness checks, split out of
  * doctor-model-checks.ts (whose shared seam/model framework and the pi and tier-models
  * checks stay there): checkClaudeAuth, checkAnthroApiKey and checkClaudeVersion.
@@ -62,13 +62,6 @@ async function claudeAuthProbe(config, pathEnv, timeoutMs) {
         return null;
     return parseClaudeAuthStatus(result.stdout);
 }
-/** The warn verdict both auth-driven claude rows return when `claude auth status` could not
- * run or its reply was unreadable — the one home of the wording so checkClaudeAuth and
- * checkAnthroApiKey cannot drift on the unreadable-probe message. Each caller makes its own
- * solitary `claudeAuthProbe` call and branches on null through it. */
-function claudeAuthUnreadable() {
-    return warnOutcome("could not check — `claude auth status` did not run or its output was unreadable");
-}
 /** claude credential readiness (plans/agent-backends.md "Every seam, checked"): a claude seam
  * whose login is gone fails every run before it can work, so doctor runs `claude auth status`
  * under the scrubbed run environment and fails when it reports `loggedIn: false`. An ok detail
@@ -82,7 +75,7 @@ export async function checkClaudeAuth(root, pathEnv = envPath(), timeoutMs = AUT
         return config;
     const auth = await claudeAuthProbe(config, pathEnv, timeoutMs);
     if (auth === null)
-        return claudeAuthUnreadable();
+        return probeUnreadableWarning("claude auth status");
     if (!auth.loggedIn)
         return failOutcome("claude reports logged in: false — run `claude auth login`");
     const subscription = claudeAuthUsesSubscription(auth);
@@ -108,7 +101,7 @@ export async function checkAnthroApiKey(root, env = process.env, pathEnv = envPa
         return okOutcome("no ANTHROPIC_API_KEY set");
     const auth = await claudeAuthProbe(config, pathEnv, timeoutMs);
     if (auth === null)
-        return claudeAuthUnreadable();
+        return probeUnreadableWarning("claude auth status");
     if (!auth.loggedIn || !claudeAuthUsesSubscription(auth))
         return okOutcome("ANTHROPIC_API_KEY is set, but claude reports no claude.ai login");
     return warnOutcome("ANTHROPIC_API_KEY is set while claude reports a claude.ai login — model jobs on claude will bill the API key, not the subscription; unset it or route every anthropic model job on pi explicitly");
@@ -171,6 +164,6 @@ export async function checkClaudeVersion(root, pathEnv = envPath(), timeoutMs =
     const result = await claudeProbe(config, ["--version"], pathEnv, timeoutMs);
     const found = versionFromProbe(result);
     if (found === undefined)
-        return warnOutcome("could not check — `claude --version` did not run or its output was unreadable");
+        return probeUnreadableWarning("claude --version");
     return claudeVersionOutcome(found, floors, claudeVersionClampNote(seams));
 }

package/dist/src/doctor/doctor-codex-checks.js

@@ -14,7 +14,7 @@ import { envPath, isDirectory, readTextOrNull, statOrNull, treeBytes, walkFiles
 import { formatBytes, tokenWindowLabel } from "../text/format.js";
 import { errorMessage } from "../text/text.js";
 import { failOutcome, okOutcome, warnOutcome } from "./doctor-outcome.js";
-import { codexSeamsInUse, loadConfigForCheck, minVersionOutcome, versionFromProbe, seamedModels, } from "./doctor-model-checks.js";
+import { codexSeamsInUse, loadConfigForCheck, minVersionOutcome, probeUnreadableWarning, versionFromProbe, seamedModels, } from "./doctor-model-checks.js";
 /** The doctor's codex rows (part 9a/9, plans/codex-backend.md §4, §7, "Hand steps"): one
  * exported check per row — install/version, login, home, models, account, leaks, sessions
  * size and the write guard. These are the doctor's only checks that spawn the `codex` CLI and
@@ -78,7 +78,7 @@ export async function checkCodexAuth(root, pathEnv = envPath(), timeoutMs = AUTH
     const { home } = base;
     const result = await codexProbe(base.config, ["login", "status"], pathEnv, timeoutMs);
     if (result?.code !== 0)
-        return warnOutcome("could not check — `codex login status` did not run or its output was unreadable");
+        return probeUnreadableWarning("codex login status");
     const status = parseCodexLoginStatus(result.stdout);
     if (status === "subscription")
         return okOutcome("logged in using ChatGPT — billing: subscription");

package/dist/src/doctor/doctor-model-checks.js

@@ -107,11 +107,19 @@ export function versionFromProbe(result, requireVPrefix = false) {
  * two backends' version verdicts from drifting. */
 export function minVersionOutcome(name, found, min, upgradeHint) {
     if (found === undefined)
-        return warnOutcome(`could not check — \`${name} --version\` did not run or its output was unreadable`);
+        return probeUnreadableWarning(`${name} --version`);
     if (belowNodeFloor(found, `>=${min}`))
         return failOutcome(`${name} ${found} is older than ${min} — ${upgradeHint}`);
     return okOutcome(`${name} ${found} (>= ${min})`);
 }
+/** The warn a backend probe that could not run or whose output was unreadable earns: it says
+ * the check could not happen, naming the command, rather than guessing a verdict. The one home
+ * of that phrase, shared by minVersionOutcome (this file), the claude auth and version rows
+ * (doctor-claude-checks.ts) and the codex login row (doctor-codex-checks.ts), so the wording
+ * cannot drift between the backends' probes. */
+export function probeUnreadableWarning(command) {
+    return warnOutcome(`could not check — \`${command}\` did not run or its output was unreadable`);
+}
 /** Whether any seam runs on the claude backend — the doctor's claude checks stand down when
  * none does (a pi-only team reads no `~/.claude` state and spawns no claude). */
 export function claudeSeamsInUse(config) {