tumwater 0.3.0 → 0.4.0

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

@@ -261,6 +261,27 @@ export const PROBLEMS_FLAG = { names: ["--problems"] };
 /** The `--kill-orphans` flag spec, accepted by `doctor`: first kill the orphaned processes the
  * orphans check lists, each with its descendants. Value-less, like PROBLEMS_FLAG. */
 export const KILL_ORPHANS_FLAG = { names: ["--kill-orphans"] };
+/** The `--commit-backlog` flag spec, accepted by `doctor`: first commit each dirty tracked backlog
+ * or brief file on the base branch before the report, under the primary-worktree lock, through the
+ * operator backlog commit path. The second mutating doctor flag, after `--kill-orphans`.
+ * Value-less, like KILL_ORPHANS_FLAG. */
+export const COMMIT_BACKLOG_FLAG = { names: ["--commit-backlog"] };
+/** The `--resync-install` flag spec, accepted by `doctor`: re-sync the root checkout's install
+ * on demand, under the merge lock, before the report (part 1/2; the Health surfaces that expose
+ * it are part 2/2). The third mutating doctor flag, after `--kill-orphans` and `--commit-backlog`.
+ * Value-less, like COMMIT_BACKLOG_FLAG. */
+export const RESYNC_INSTALL_FLAG = { names: ["--resync-install"] };
+/** The `--drop-broken-pins` flag spec, accepted by `doctor`: first drop each `refs/tumwater/`
+ * pin whose commit is gone — the manual `git update-ref -d` the `tumwater pins` row names. The
+ * fourth mutating doctor flag, after `--kill-orphans`, `--commit-backlog` and `--resync-install`.
+ * Value-less, like RESYNC_INSTALL_FLAG. */
+export const DROP_BROKEN_PINS_FLAG = { names: ["--drop-broken-pins"] };
+/** The `--retire-leftovers` flag spec, accepted by `doctor`: first retire each disabled role's
+ * leftover worktree, branch and merge ref in one pass — the reap for the `leftover role
+ * branches` row, through the same `retireRole` core `tumwater retire --role <id>` uses. The
+ * fifth mutating doctor flag, after `--kill-orphans`, `--commit-backlog`, `--resync-install` and
+ * `--drop-broken-pins`. Value-less, like DROP_BROKEN_PINS_FLAG. */
+export const RETIRE_LEFTOVERS_FLAG = { names: ["--retire-leftovers"] };
 /** The `--stat` flag spec, accepted by `diff --role`: print each patch as its `git diff --stat`
  * summary. Value-less, like JSON_FLAG. */
 export const STAT_FLAG = { names: ["--stat"] };
@@ -292,6 +313,10 @@ export const SUMMARY_FLAG = { names: ["--summary"] };
 /** The `--count` flag spec, accepted by `logs`: tally the selected window's event types
  * instead of printing the rows. Value-less, like SUMMARY_FLAG. */
 export const COUNT_FLAG = { names: ["--count"] };
+/** `logs --notable`: cull routine bookkeeping events the way the dashboard Activity feed's
+ * Notable choice does, keeping only non-routine rows. Value-less like JSON_FLAG and COUNT_FLAG,
+ * and a rival of the --transcript transcript view with the rest of the feed flags. */
+export const NOTABLE_FLAG = { names: ["--notable"] };
 /** The `--force` flag spec, accepted by `retire` (the only override-the-rails command): one
  * definition of the flag's spelling beside ROLE_FLAG and JSON_FLAG, so the gate's accepted
  * vocabulary cannot drift from the command body's `args.includes("--force")`. */
@@ -328,6 +353,14 @@ export function typeFlagSpec(missingValue) {
 export function resultFlagSpec(missingValue) {
     return { names: ["--result"], value: true, valueName: "<class>", missingValue };
 }
+/** The `--status <state>` flag spec of `reviews`' state filter, beside resultFlagSpec: one
+ * definition of the flag's spelling and value shape, so the gate's accepted vocabulary cannot
+ * drift. The missing-value wording names the command, so the spec is a factory taking it — the
+ * same string the body fails with; which states are accepted is the command body's rule
+ * (post-merge-review-render.ts's POST_REVIEW_STATES). */
+export function statusFlagSpec(missingValue) {
+    return { names: ["--status"], value: true, valueName: "<state>", missingValue };
+}
 /** `history --model <selector>[,...]`: keeps the runs that started on the listed models;
  * `missingValue` is the same string the command body fails with. */
 export function modelFlagSpec(missingValue) {

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

@@ -7,7 +7,7 @@ import { fail, say, sayJson, sayJsonOrRender } from "./cli-output.js";
 import { cancelQueuedMerge } from "../merge/merge-cancel.js";
 import { moveQueuedMergeToTop } from "../merge/merge-top.js";
 import { followView } from "./follow-view.js";
-import { flagValue, parseGrepFlag, parsePositionFlag, parseRoleListScope, rejectRepeatFlag } from "./cli-args.js";
+import { flagValue, parseGrepFlag, parseRoleListScope, rejectRepeatFlag, scanPositionArgs } from "./cli-args.js";
 import { DIFF_PATH_FLAG, FOLLOW_FLAG, hasFollowFlag, JSON_FLAG, READY_FLAG, grepFlagSpec, rejectUnknownArgs, OVERLAPS_FLAG, ROLE_FLAG, STAT_FLAG } from "./cli-flag-specs.js";
 import { refuseTeamWorkspace, requireReadyRepo } from "./cli-repo-gate.js";
 import { scopeSnapshotToRoles, snapshot } from "../status/status-data.js";
@@ -16,6 +16,8 @@ import { renderStatus } from "../ui/status-render.js";
 import { backlogPayload } from "../backlog/backlog.js";
 import { backlogHolds, backlogInProgress } from "../backlog/backlog-eligibility.js";
 import { readyBacklog, grepBacklog, renderBacklogMarkdown } from "../backlog/backlog-render.js";
+import { loadQuarantine } from "../review/known-flakes.js";
+import { quarantineRows, renderQuarantine } from "../review/quarantine-render.js";
 import { collectChangeOverlaps, scopeChangeOverlaps, scopeChangeOverlapsToPath, collectTeamChanges, collectRoleChange, collectRoleChanges, normalizeDiffPath } from "../change/change-data.js";
 import { renderChangeOverlaps, renderTeamChange, renderRoleChange, renderRoleChanges } from "../change/change-render.js";
 import { readMergeQueue } from "../merge/merge-queue.js";
@@ -198,26 +200,7 @@ export async function cmdQueue(root, args, seams = {}) {
  * `tumwater queue`'s. An entry a live merge marker names for this sha is refused (wait for it
  * to land, then revert); an out-of-range position fails naming the current depth. */
 async function cmdQueueCancel(root, args) {
-    let position = null;
-    let json = false;
-    const rest = [];
-    for (let i = 0; i < args.length; i++) {
-        const arg = args[i];
-        if (arg === "--json") {
-            rejectRepeatFlag(json, "--json");
-            json = true;
-            continue;
-        }
-        if (arg === "--cancel") {
-            rejectRepeatFlag(position !== null, "--cancel");
-            position = parsePositionFlag("--cancel", args[i + 1], "--cancel 2");
-            i++;
-            continue;
-        }
-        if (arg === "--help" || arg === "-h")
-            continue;
-        rest.push(arg);
-    }
+    const { json, position, rest } = scanPositionArgs(args, "--cancel", "--cancel 2");
     // The vocabulary a cancel invocation accepts is exactly --cancel and --json, both consumed
     // above; --role and -f/--follow are refused with the queue-specific wording the tests pin.
     if (rest.includes("--role"))
@@ -259,26 +242,7 @@ async function cmdQueueCancel(root, args) {
  * out-of-range position fails naming the current depth; position 1 prints the already-first
  * line and exits 0; a concurrently-drained entry prints the gone line and exits 0. */
 async function cmdQueueTop(root, args) {
-    let position = null;
-    let json = false;
-    const rest = [];
-    for (let i = 0; i < args.length; i++) {
-        const arg = args[i];
-        if (arg === "--json") {
-            rejectRepeatFlag(json, "--json");
-            json = true;
-            continue;
-        }
-        if (arg === "--top") {
-            rejectRepeatFlag(position !== null, "--top");
-            position = parsePositionFlag("--top", args[i + 1], "--top 2");
-            i++;
-            continue;
-        }
-        if (arg === "--help" || arg === "-h")
-            continue;
-        rest.push(arg);
-    }
+    const { json, position, rest } = scanPositionArgs(args, "--top", "--top 2");
     // The vocabulary a top invocation accepts is exactly --top and --json, both consumed
     // above; --role and -f/--follow are refused with the queue-specific wording the tests pin.
     if (rest.includes("--role"))
@@ -374,3 +338,14 @@ export async function cmdBacklog(root, args, seams = {}) {
     const result = readBacklog();
     sayJsonOrRender(rest, result.view, () => renderBacklogText(result));
 }
+// `tumwater quarantine [--json]` — the read-only view of the review gate's flake
+// quarantine. No requireReadyRepo gate: loadQuarantine degrades an absent or malformed
+// file to the empty list (the cmdBacklog rationale), so the command prints the empty line
+// in any directory, and it never writes quarantine.json (a test leaves the list only
+// through releaseQuarantine). --json serves the same positioned rows to scripts.
+export async function cmdQuarantine(root, args) {
+    rejectUnknownArgs("quarantine", args, [JSON_FLAG]);
+    refuseTeamWorkspace(root);
+    const rows = quarantineRows(loadQuarantine(root));
+    sayJsonOrRender(args, { tests: rows }, () => renderQuarantine(rows, Date.now()));
+}

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

@@ -0,0 +1,113 @@
+/** `tumwater reviews` — the operator-facing twin of `tumwater queue` for the post-merge review
+ * queue (.tumwater/state/post-review.json): list every well-formed entry in FIFO order, or the
+ * same list as JSON (`--json`). It does not require a ready repo (the `cmdBacklog` rationale):
+ * `readPostReviews` reads a missing, torn or hand-edited file as the well-formed subset (or `[]`),
+ * so the command prints the empty line in any directory. Read-only except the one destructive
+ * `--accept <n>` mode, which removes the Nth entry the operator deliberately accepts unreviewed
+ * (the action the at-risk alert's advice names); that mode adds no new ready-repo requirement to
+ * the read path and gates the write with `requireReadyRepo`. Unlike `cmdQueue`'s `--cancel`, the
+ * read case still writes no file. */
+import { JSON_FLAG, ROLE_FLAG, rejectUnknownArgs, statusFlagSpec } from "./cli-flag-specs.js";
+import { sayJsonOrRender, say, sayJson, fail } from "./cli-output.js";
+import { refuseTeamWorkspace, requireReadyRepo } from "./cli-repo-gate.js";
+import { parseRoleListScope, parseStatusFlag, scanPositionArgs } from "./cli-args.js";
+import { readPostReviews } from "../review/post-merge-review.js";
+import { acceptPostReview } from "../review/post-merge-review-accept.js";
+import { POST_REVIEW_STATES, postReviewState, renderPostReviews, scopePostReviews, } from "../review/post-merge-review-render.js";
+import { roleInScope } from "../roles/runner-ids.js";
+import { roleLabel } from "../roles/role-labels.js";
+import { shortSha } from "../text/format.js";
+import { gotSuffix, splitCommaList } from "../text/text.js";
+import { typoSuffix } from "../text/suggest.js";
+/** The missing-value wording of `reviews --status` (shared by the gate's statusFlagSpec and
+ * parseStatusFlag's own fail, so the two cannot drift). */
+const REVIEWS_STATUS_VALUE_ERROR = "reviews --status needs a value";
+/** Parse a `--status` value: a comma list of post-merge review states, deduplicated in
+ * first-seen order, accepting only `POST_REVIEW_STATES` members. The first unknown piece fails
+ * naming the accepted states, mirroring parseHistoryResultList's gotSuffix/typoSuffix shape. */
+function parseReviewStatusList(raw) {
+    if (raw === "")
+        fail(REVIEWS_STATUS_VALUE_ERROR);
+    const pieces = splitCommaList(raw);
+    if (pieces.length === 0)
+        fail(REVIEWS_STATUS_VALUE_ERROR);
+    const spellings = [...POST_REVIEW_STATES];
+    const out = [];
+    for (const piece of pieces) {
+        if (!POST_REVIEW_STATES.includes(piece))
+            fail(`reviews --status must be one of ${spellings.join(", ")}${gotSuffix(piece)}${typoSuffix(piece, spellings)}`);
+        if (!out.includes(piece))
+            out.push(piece);
+    }
+    return out;
+}
+/** `tumwater reviews [--json]`: the post-merge review queue, oldest first.*/
+export async function cmdReviews(root, args) {
+    // `tumwater reviews --accept <n>` is the read-only command's one destructive mode: route it
+    // to its own branch before the read gate, so --accept never leaks into the view parsing.
+    if (args.includes("--accept")) {
+        await cmdReviewsAccept(root, args);
+        return;
+    }
+    rejectUnknownArgs("reviews", args, [ROLE_FLAG, statusFlagSpec(REVIEWS_STATUS_VALUE_ERROR), JSON_FLAG]);
+    refuseTeamWorkspace(root);
+    // `--role` keeps only the listed roles' entries (a base id taking its instances too) under
+    // their whole-queue positions, so `--accept <n>` still addresses the position the unscoped
+    // read prints. Absent a ready config `parseRoleListScope` falls back to the built-in catalog.
+    const roles = parseRoleListScope(root, args);
+    const { raw: statusRaw } = parseStatusFlag(args, REVIEWS_STATUS_VALUE_ERROR);
+    const whole = readPostReviews(root);
+    let entries = whole;
+    let scope;
+    if (statusRaw === null) {
+        const scoped = roles ? scopePostReviews(whole, roles, (e) => roleInScope(e.role, roles)) : undefined;
+        entries = scoped ? scoped.entries : whole;
+        scope = scoped?.scope;
+    }
+    else {
+        // `--status <state>[,...]` keeps only the listed states (the same precedence
+        // postReviewStatusLabel prints: a rejected-and-failing entry is rejected) under their
+        // whole-queue positions, composing with `--role`. roles=[] when unscoped.
+        const states = parseReviewStatusList(statusRaw);
+        const keep = (e) => (!roles || roleInScope(e.role, roles)) && states.includes(postReviewState(e));
+        const filterText = [roles ? `--role ${roles.join(",")}` : "", `--status ${states.join(",")}`]
+            .filter(Boolean)
+            .join(" ");
+        const scoped = scopePostReviews(whole, roles ?? [], keep, filterText);
+        entries = scoped.entries;
+        scope = scoped.scope;
+    }
+    sayJsonOrRender(args, { pending: entries }, () => renderPostReviews(entries, scope, Date.now()));
+}
+/** The `tumwater reviews --accept <n>` branch (PLANS.md): remove the Nth pending post-merge
+ * review `tumwater reviews` lists, accepting the commit unreviewed at the operator's request.
+ * Parsed the way `cmdQueueCancel` parses `--cancel`: `--accept <n>` the one valued flag,
+ * `--json` the one boolean (at most once), `--help`/`-h` tolerated, anything else refused. An
+ * out-of-range position fails naming the current depth; an entry whose repair already merged
+ * (`fixed`) is refused. A rejected entry waits on nothing and is accepted like any pending one. */
+async function cmdReviewsAccept(root, args) {
+    const { json, position, rest } = scanPositionArgs(args, "--accept", "--accept 2");
+    // The vocabulary an accept invocation accepts is exactly --accept and --json, both consumed
+    // above; --role is refused by name (as cmdQueueCancel refuses it): accept addresses a
+    // whole-queue position `tumwater reviews` printed, and a scoped read must never renumber it.
+    if (rest.includes("--role") || rest.includes("--status"))
+        fail("reviews --accept accepts by whole-queue position from `tumwater reviews`; --role and --status scope a read only — drop them");
+    // Everything else is refused with the generic wording, so `--bogus` is named.
+    rejectUnknownArgs("reviews", rest, []);
+    if (position === null)
+        fail("--accept needs a position (usage: tumwater reviews --accept <n>)");
+    await requireReadyRepo(root);
+    const outcome = acceptPostReview(root, position);
+    if (outcome.status === "out-of-range") {
+        fail(`no post-merge review at position ${position} (post-merge review queue holds ${outcome.depth})`);
+    }
+    if (outcome.status === "settled") {
+        fail(`post-merge review ${position} already merged its fix on main — nothing to accept`);
+    }
+    if (json) {
+        sayJson({ accepted: { role: outcome.role, commit: outcome.commit, summary: outcome.summary } });
+    }
+    else {
+        say(`accepted post-merge review entry ${position} unreviewed: ${roleLabel(outcome.role)} ${shortSha(outcome.commit)} — ${outcome.summary}`);
+    }
+}

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

@@ -2,9 +2,9 @@
  * keeps only the read-only query commands (status, diff, queue, backlog). cli.ts's dispatcher
  * routes to cmdRole here exactly as it routes cmdStatus to cli-query-commands or cmdConfig to
  * config-commands. cmdRole is the one query-named command that also writes: it renders a
- * role's standing and next-run prompts and carries ten per-role write flags (notes,
+ * role's standing and next-run prompts and carries eleven per-role write flags (notes,
  * instructions, quiet-hours, daily cap, min-run-interval, instances, enable/disable, and the
- * provider/model/thinking triple), each through the same setConfigKey/unsetConfigKey core
+ * provider/model/thinking/backend), each through the same setConfigKey/unsetConfigKey core
  * `config set`/`config unset` use. It lives in its own file because its mixed
  * positional/flag vocabulary and its write branches are its own, not the query commands'. */
 import { fail, say, sayJsonOrRender } from "./cli-output.js";
@@ -44,6 +44,12 @@ const CAP_SPEC = { names: ["--cap"], value: true, valueName: "<usd>" };
 function plainDecimalToJson(raw) {
     return /^\d*\.?\d+$/.test(raw) ? String(Number(raw)) : null;
 }
+/** Detect exponent spellings that the cap, interval and instances writes must reject
+ * before JSON parsing can turn them into otherwise valid numeric config values. Other
+ * invalid spellings fall through to the config validator, which names the key. */
+function isExponentSpelling(raw) {
+    return raw.trim() !== "" && plainDecimalToJson(raw) === null && /^\d+(\.\d+)?[eE][+-]?\d+$/.test(raw.trim());
+}
 /** `role`'s min-run-interval write flags: clear it, or set it to a second count (0 is
  * back-to-back). */
 const CLEAR_MIN_RUN_INTERVAL_SPEC = { names: ["--clear-min-run-interval"] };
@@ -56,6 +62,10 @@ const INSTANCES_SPEC = { names: ["--instances"], value: true, valueName: "<n>" }
  * roles.<base>.enabled. */
 const ENABLE_SPEC = { names: ["--enable"] };
 const DISABLE_SPEC = { names: ["--disable"] };
+/** `role`'s review-after-merge write flags: add the role to, or remove it from,
+ * review.afterMerge (written for the base id). */
+const REVIEW_AFTER_MERGE_SPEC = { names: ["--review-after-merge"] };
+const CLEAR_REVIEW_AFTER_MERGE_SPEC = { names: ["--clear-review-after-merge"] };
 /** `role`'s model-triple write flags: clear the field, or set it, written to
  * roles.<base>.provider/.model/.thinking. model and provider take an id; thinking takes a
  * pi `--thinking` level (off|minimal|low|medium|high|xhigh|max). */
@@ -65,18 +75,21 @@ const CLEAR_MODEL_SPEC = { names: ["--clear-model"] };
 const MODEL_SPEC = { names: ["--model"], value: true, valueName: "<id>" };
 const CLEAR_THINKING_SPEC = { names: ["--clear-thinking"] };
 const THINKING_SPEC = { names: ["--thinking"], value: true, valueName: "<level>" };
+const CLEAR_BACKEND_SPEC = { names: ["--clear-backend"] };
+const BACKEND_SPEC = { names: ["--backend"], value: true, valueName: "<id>" };
 /** Peel `tumwater role <id>`'s positional id off the argument list: the first token that is
  * neither a flag nor the value of a --role, --notes-file, --instructions-file,
- * --quiet-hours, --cap, --min-run-interval, --instances, --provider, --model or
- * --thinking flag. Returns the id (null when absent) and the remaining arguments — flags
- * only, ready for rejectUnknownArgs and sayJsonOrRender. The id may also arrive as
+ * --quiet-hours, --cap, --min-run-interval, --instances, --provider, --model,
+ * --thinking or --backend flag. Returns the id (null when absent) and the remaining
+ * arguments — flags only, ready for rejectUnknownArgs and sayJsonOrRender. The id may
+ * also arrive as
  * --role <id>, the flag spelling every other role-targeting command shares; the
  * collector's caller rejects both spellings at once rather than silently picking one.
  * Lives here because it exists only for this one
  * command's mixed positional/flag vocabulary. */
 function peelRolePositional(args) {
     const valueIdx = new Set();
-    for (const flag of ["--role", "--notes-file", "--instructions-file", "--quiet-hours", "--cap", "--min-run-interval", "--instances", "--provider", "--model", "--thinking"]) {
+    for (const flag of ["--role", "--notes-file", "--instructions-file", "--quiet-hours", "--cap", "--min-run-interval", "--instances", "--provider", "--model", "--thinking", "--backend"]) {
         const at = args.indexOf(flag);
         if (at >= 0)
             valueIdx.add(at + 1);
@@ -106,9 +119,10 @@ function requireKnownRole(root, id) {
     if (!knownRoleIds(cfg).includes(id))
         throw new Error(unknownRoleMessage(id, knownRoleIds(cfg)));
 }
-/** The config-key write the six per-role hold branches (quiet hours, daily cap, min run
- * interval, provider, model and thinking) share: with `clear`, or an empty typed value, unset
- * `key` under `base`; else set it. `serialize` shapes the value `setConfigKey` stores (it
+/** The config-key write the seven per-role hold branches (quiet hours, daily cap, min run
+ * interval, provider, model, thinking and backend) share: with `clear`, or an empty typed
+ * value, unset `key` under `base`; else set it. `serialize` shapes the value `setConfigKey`
+ * stores (it
  * JSON-encodes nothing itself) and `display` gives the human phrase for the confirmation
  * line. The caller returns right after. The instructions branch keeps its own block: its
  * value is a file's text, so an empty value is a legitimate write, not a clear. A no-op (a
@@ -148,13 +162,13 @@ export async function cmdRole(root, args) {
     // Only a `--` (double-dash) token reads as a flag: a single-dash token like `-1` is a
     // negative-number value that must reach the setters' own bound checks, and the file flags'
     // `-` stdin value is not in this set at all.
-    for (const flag of ["--provider", "--model", "--thinking", "--cap", "--min-run-interval", "--instances", "--quiet-hours"]) {
+    for (const flag of ["--provider", "--model", "--thinking", "--backend", "--cap", "--min-run-interval", "--instances", "--quiet-hours"]) {
         const at = rest.indexOf(flag);
         const next = at >= 0 ? rest[at + 1] : undefined;
         if (next?.startsWith("--"))
             fail(`${flag} needs a value (the next token ${JSON.stringify(next)} is a flag, not a value)`);
     }
-    rejectUnknownArgs("role", rest, [ROLE_FLAG, JSON_FLAG, CLEAR_NOTES_SPEC, NOTES_FILE_SPEC, CLEAR_INSTRUCTIONS_SPEC, INSTRUCTIONS_FILE_SPEC, CLEAR_QUIET_HOURS_SPEC, QUIET_HOURS_SPEC, ENABLE_SPEC, DISABLE_SPEC, CLEAR_CAP_SPEC, CAP_SPEC, CLEAR_MIN_RUN_INTERVAL_SPEC, MIN_RUN_INTERVAL_SPEC, CLEAR_INSTANCES_SPEC, INSTANCES_SPEC, CLEAR_PROVIDER_SPEC, PROVIDER_SPEC, CLEAR_MODEL_SPEC, MODEL_SPEC, CLEAR_THINKING_SPEC, THINKING_SPEC]);
+    rejectUnknownArgs("role", rest, [ROLE_FLAG, JSON_FLAG, CLEAR_NOTES_SPEC, NOTES_FILE_SPEC, CLEAR_INSTRUCTIONS_SPEC, INSTRUCTIONS_FILE_SPEC, CLEAR_QUIET_HOURS_SPEC, QUIET_HOURS_SPEC, ENABLE_SPEC, DISABLE_SPEC, CLEAR_CAP_SPEC, CAP_SPEC, CLEAR_MIN_RUN_INTERVAL_SPEC, MIN_RUN_INTERVAL_SPEC, CLEAR_INSTANCES_SPEC, INSTANCES_SPEC, CLEAR_PROVIDER_SPEC, PROVIDER_SPEC, CLEAR_MODEL_SPEC, MODEL_SPEC, CLEAR_THINKING_SPEC, THINKING_SPEC, CLEAR_BACKEND_SPEC, BACKEND_SPEC, REVIEW_AFTER_MERGE_SPEC, CLEAR_REVIEW_AFTER_MERGE_SPEC]);
     refuseTeamWorkspace(root);
     // The id is required: positional (`tumwater role <id>`) or --role <id> (the flag
     // spelling every other role-targeting command shares). Both at once is a mistake, not
@@ -177,6 +191,7 @@ export async function cmdRole(root, args) {
     const clearProvider = rest.includes("--clear-provider");
     const clearModel = rest.includes("--clear-model");
     const clearThinking = rest.includes("--clear-thinking");
+    const clearBackend = rest.includes("--clear-backend");
     const notesWrite = clear || rest.includes("--notes-file");
     const instructionsWrite = clearInst || rest.includes("--instructions-file");
     const quietWrite = clearQuiet || rest.includes("--quiet-hours");
@@ -186,8 +201,12 @@ export async function cmdRole(root, args) {
     const providerWrite = clearProvider || rest.includes("--provider");
     const modelWrite = clearModel || rest.includes("--model");
     const thinkingWrite = clearThinking || rest.includes("--thinking");
+    const backendWrite = clearBackend || rest.includes("--backend");
     const enable = rest.includes("--enable");
     const disable = rest.includes("--disable");
+    const reviewAfterMerge = rest.includes("--review-after-merge");
+    const clearReviewAfterMerge = rest.includes("--clear-review-after-merge");
+    const reviewAfterMergeWrite = reviewAfterMerge || clearReviewAfterMerge;
     const writes = [];
     if (notesWrite)
         writes.push("notes");
@@ -207,10 +226,14 @@ export async function cmdRole(root, args) {
         writes.push("model");
     if (thinkingWrite)
         writes.push("thinking");
+    if (backendWrite)
+        writes.push("backend");
     if (enable)
         writes.push("enable");
     if (disable)
         writes.push("disable");
+    if (reviewAfterMergeWrite)
+        writes.push("review-after-merge");
     if (writes.length > 1)
         fail(`${writes.join(" and ")} writes cannot share one invocation`);
     if (notesWrite) {
@@ -292,8 +315,20 @@ export async function cmdRole(root, args) {
         if (id === DIRECTOR_ROLE)
             fail("the director has no daily cap");
         const base = baseRoleOf(id);
+        const cfgKey = `maxDailyCostUsdPerRole.${base}`;
         const cap = flagValue(rest, "--cap") ?? "";
-        writeRoleConfigKey(root, base, clearCap, cap, `maxDailyCostUsdPerRole.${base}`, "daily cap", (v) => plainDecimalToJson(v) ?? v, (v) => v);
+        // Shape, before the write: a spelling that is not a plain decimal but that JSON.parse
+        // would still read as a non-negative USD amount (an exponent like "1e2" → 100) would
+        // otherwise sail past both plainDecimalToJson (which only rewrites JSON-unparseable
+        // spellings like `05`) and checkDailyBudgetUsd's non-negative check and silently write
+        // the misread — the same silent misread the TUI Ctrl+B budget editor and the GUI cap
+        // drawer now reject. Every non-exponent spelling JSON reads as a non-negative USD is
+        // already a plain decimal, so the exponent form is exactly the silent-write set; hex,
+        // negative and non-numeric spellings fall through to the write path, whose
+        // validateConfig message names the key.
+        if (isExponentSpelling(cap))
+            fail(`${cfgKey} must be a plain dollar amount like 25, 12.50, or .5 — no +/-, exponent, or hex notation`);
+        writeRoleConfigKey(root, base, clearCap, cap, cfgKey, "daily cap", (v) => plainDecimalToJson(v) ?? v, (v) => v);
         return;
     }
     // The min-run-interval write: the terminal twin of `config set
@@ -310,8 +345,20 @@ export async function cmdRole(root, args) {
             fail("--json does not apply to a min-run-interval write");
         requireKnownRole(root, id);
         const base = baseRoleOf(id);
+        const cfgKey = `roles.${base}.minRunIntervalSeconds`;
         const secs = flagValue(rest, "--min-run-interval") ?? "";
-        writeRoleConfigKey(root, base, clearInterval, secs, `roles.${base}.minRunIntervalSeconds`, "min run interval", (v) => plainDecimalToJson(v) ?? v, (v) => `${v}s`);
+        // Shape, before the write: a spelling that is not a plain decimal but that JSON.parse
+        // would still read as a non-negative second count (an exponent like "1e2" → 100) would
+        // otherwise sail past both plainDecimalToJson (which only rewrites JSON-unparseable
+        // spellings like `05`) and validateConfig's non-negative check and silently write the
+        // misread — the same silent misread the TUI Ctrl+S editor and the GUI interval drawer
+        // now reject. Every non-exponent spelling JSON reads as a non-negative count is already a
+        // plain decimal, so the exponent form is exactly the silent-write set; hex, negative and
+        // non-numeric spellings fall through to the write path, whose validateConfig message
+        // names the key.
+        if (isExponentSpelling(secs))
+            fail(`${cfgKey} must be a plain second count like 300, 0.5, or .5 — no +/-, exponent, or hex notation`);
+        writeRoleConfigKey(root, base, clearInterval, secs, cfgKey, "min run interval", (v) => plainDecimalToJson(v) ?? v, (v) => `${v}s`);
         return;
     }
     // The instances write: the terminal twin of `config set roles.<base>.instances <n>`, the
@@ -331,7 +378,19 @@ export async function cmdRole(root, args) {
         if (!knownRoleIds(cfg).includes(id))
             throw new Error(unknownRoleMessage(id, knownRoleIds(cfg)));
         const base = baseRoleOf(id);
+        const cfgKey = `roles.${base}.instances`;
         const n = flagValue(rest, "--instances") ?? "";
+        // Shape, before the write: a spelling that is not a plain integer but that JSON.parse
+        // would still read as a 1–8 count (an exponent like "2e0" → 2) would otherwise sail past
+        // both plainDecimalToJson and validateConfig's INSTANCE_COUNT integer check and silently
+        // write the misread — the same silent misread the cap and min-run-interval writes refuse.
+        // Every non-exponent spelling that JSON reads as an integer in range is already a plain
+        // integer, so the exponent form is exactly the silent-write set; every exponent — in range
+        // or out ("9e0" → 9 too) — is refused here, while fractional, hex, negative and plain
+        // out-of-range integer spellings fall through to the write path, whose validateConfig
+        // message names the key.
+        if (isExponentSpelling(n))
+            fail(`${cfgKey} must be a plain integer from 1 to 8 — no exponent notation`);
         // An absent count already means 1 (instanceCount's default), so asking for 1 is a no-op —
         // but only for a role that may split; any other role falls through to validateConfig's refusal.
         // A tumwater.json that fails to load is no basis for "already": fall through to the failure.
@@ -387,6 +446,22 @@ export async function cmdRole(root, args) {
         writeRoleConfigKey(root, base, clearThinking, level, `roles.${base}.thinking`, "thinking", (v) => JSON.stringify(v), (v) => v);
         return;
     }
+    // The backend write: the twin of the provider/model/thinking writes, landing the role's
+    // backend (`pi`, `claude`, `opencode` or `codex`) in roles.<base>.backend through the same
+    // setConfigKey/unsetConfigKey core, so validateConfig's checkEntryBackend owns the id
+    // (rejecting an unknown one, and a `model` that cannot pair with the named backend) and
+    // the write stays atomic. An instance id writes its base role's key, like the others.
+    if (backendWrite) {
+        if (clearBackend && rest.includes("--backend"))
+            fail("give --clear-backend or --backend, not both");
+        if (rest.includes("--json"))
+            fail("--json does not apply to a backend write");
+        requireKnownRole(root, id);
+        const base = baseRoleOf(id);
+        const backend = flagValue(rest, "--backend") ?? "";
+        writeRoleConfigKey(root, base, clearBackend, backend, `roles.${base}.backend`, "backend", (v) => JSON.stringify(v), (v) => v);
+        return;
+    }
     // The enable/disable write: the scoped write for the enabled state `tumwater role <id>`
     // already renders, the terminal twin of `config set roles.<base>.enabled true|false`. The
     // value lands in roles.<base>.enabled through the same setConfigKey core config set uses, so
@@ -414,6 +489,36 @@ export async function cmdRole(root, args) {
         say(`${base}: ${state}`);
         return;
     }
+    // The review-after-merge write: the one command the post-merge churn alert's remedy
+    // needs — add the role to, or remove it from, review.afterMerge for the base id, the
+    // membership test reviewedAfterMerge shares. The whole-list value lands through the same
+    // setConfigKey core `config set review.afterMerge <json>` uses, so validateConfig owns the
+    // string-array shape, the known-role-id check and the `review.afterMerge must not be
+    // "director"` refusal, and the write is atomic. A role already in the asked-for state is
+    // reported as such and the file is left alone (the section branch compares the value
+    // against the resolved list, so a no-op reports unchanged and writes nothing).
+    if (reviewAfterMergeWrite) {
+        if (reviewAfterMerge && clearReviewAfterMerge)
+            fail("give --review-after-merge or --clear-review-after-merge, not both");
+        if (rest.includes("--json"))
+            fail("--json does not apply to a review-after-merge write");
+        requireKnownRole(root, id);
+        const base = baseRoleOf(id);
+        const list = loadConfigSafe(root).config?.review.afterMerge ?? [];
+        const has = list.includes(base);
+        const next = has === reviewAfterMerge ? list : reviewAfterMerge ? [...list, base] : list.filter((r) => r !== base);
+        const result = setConfigKey(root, "review.afterMerge", JSON.stringify(next));
+        if (!result.ok)
+            fail(result.error);
+        say(result.unchanged
+            ? reviewAfterMerge
+                ? `${base}: already in review.afterMerge, so tumwater.json was not written`
+                : `${base}: not in review.afterMerge, so nothing was cleared`
+            : reviewAfterMerge
+                ? `${base}: added to review.afterMerge`
+                : `${base}: removed from review.afterMerge`);
+        return;
+    }
     // The unknown-role answer (exit 1, unknownRoleMessage's wording) lives in the
     // collector; here the id just has to be non-null for the thunk's types.
     sayJsonOrRender(rest, () => rolePayload(root, id), renderRoleMarkdown);

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

@@ -11,16 +11,23 @@ import { plural } from "../text/phrases.js";
 import { SPARSE_WINDOW_NOTE } from "../events/event-window.js";
 import { renderSummary } from "../history/history-render.js";
 import { failOverDurationCap, failRivalShapes, flagValue, parseDurationFlag, } from "./cli-args.js";
+import { parsePositiveInt } from "../text/text.js";
 import { PAUSE_FOR_MAX_MS } from "../operator/operator-intent.js";
 import { loadRunnerState } from "../runner/runner-state-load.js";
 import { stateSkipReason } from "../runner/runner-state.js";
 import { isTeamPaused, pausedRoles } from "../team/team-state.js";
 import { runnerPaused } from "../roles/runner-ids.js";
 /** The window start a generation adopts: the supervisor's RUN_WINDOW_START_ENV mark when it is a
- * positive integer no later than `now`, else `now` (absent, malformed, or in the future). */
+ * positive integer no later than `now`, else `now` (absent, malformed, or in the future). The
+ * mark is read through the shared plain-decimal rule (parsePositiveInt) rather than bare
+ * Number(), which would silently coerce a hex/exponent/signed spelling ("0x10" → 16, "1e3" →
+ * 1000) into a window start the supervisor never wrote — the same plain-decimal discipline the
+ * CLI count/position flags apply to every other string boundary. */
 export function inheritedWindowStart(raw, now) {
-    const n = Number(raw);
-    return raw !== undefined && Number.isInteger(n) && n > 0 && n <= now ? n : now;
+    if (raw === undefined)
+        return now;
+    const n = parsePositiveInt(raw);
+    return n !== null && n <= now ? n : now;
 }
 /** The `run --for` exit summary: a window line, then the `history --summary` table for the runs
  * that ended since the window opened — every run counted once by its outcome class. Only the

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

@@ -16,6 +16,13 @@ import { loadRunnerState } from "../runner/runner-state-load.js";
 import { shortSha } from "../text/format.js";
 import { readRunRowsSince, summarizeRunRows } from "../history/history-data.js";
 import { ONCE_FAILURE_RESULTS, inheritedWindowStart, onceFailures, onceReport, onceSummary, parseRunWindow, renderOnceSummary, windowReport, windowSummary, } from "./cli-start-summary.js";
+/** The env var that carries the dashboard gate token between a supervisor and its dashboard
+ * child (and across a re-exec'd dashboard generation), for the `run --gui`/`start --gui`
+ * supervisor's own use. Defined here rather than imported from gui-command.js so this module
+ * (and every `start`/`run` invocation) never pulls the GUI server graph onto the page; it
+ * must stay the same literal as gui-command's GUI_TOKEN_ENV, and a merge that renames one
+ * renames the other. */
+const GUI_TOKEN_ENV = "TUMWATER_GUI_TOKEN";
 export { ONCE_FAILURE_RESULTS, inheritedWindowStart, onceFailures, onceReport, onceSummary, parseRunWindow, renderOnceSummary, windowReport, windowSummary, };
 /** `tumwater start`: boot the team and stream its event feed to this terminal until it stops.
  * Three layers cooperate here: without SUPERVISED_ENV this process becomes the supervisor
@@ -64,6 +71,17 @@ export async function cmdStart(root, args) {
     const tokenProblem = tokenValueProblem(args, "tumwater start --gui");
     if (tokenProblem)
         fail(tokenProblem);
+    // The supervisor (this process, when run without SUPERVISED_ENV) is long-lived and the OS
+    // process table (ps, /proc/<pid>/cmdline) is world-readable, so an operator-typed secret must
+    // not sit in this process's argv for the whole run. guiChildPlan has already extracted the
+    // token into `plan.guiToken` for the dashboard child's env (see superviseDashboard), so take
+    // `--token <value>` off the command line here — the env rides every spawn and reexecSelf
+    // re-run, so no dashboard child or reloaded generation loses the gate — and say it is gone.
+    const argvToken = process.argv.indexOf("--token");
+    if (argvToken >= 0) {
+        process.argv.splice(argvToken, 2);
+        say(`removed --token from this process's command line; prefer the ${GUI_TOKEN_ENV} env var`);
+    }
     const forMs = parseRunWindow(args, once);
     const branchArg = parseBranchFlag(args);
     const startup = await runStartupCheck(root, branchArg);
@@ -328,12 +346,16 @@ export function guiChildPlan(runArgs) {
         guiArgs.push("--port", String(port));
     if (runArgs.includes("--all-interfaces"))
         guiArgs.push("--all-interfaces");
-    if (tokenRaw !== undefined)
-        guiArgs.push("--token", tokenRaw);
+    // The token is returned separately (guiToken) and reaches the child through its env, never
+    // guiArgs/argv: a secret on the command line is world-readable (/proc/<pid>/cmdline) and is
+    // re-run verbatim by a self-reload onto each new generation. The skip set still drops the
+    // operator's --token pair from the orchestrator generation (its cmdStart would refuse a
+    // dashboard flag without --gui, and a self-redeploy hand-off must never forward it).
     return {
         spawnGui: runArgs.includes("--gui"),
         spawnTui: runArgs.includes("--tui"),
         guiArgs,
+        guiToken: tokenRaw,
         orchestratorArgs: runArgs.filter((arg, i) => arg !== "--gui" && arg !== "--tui" && arg !== "--all-interfaces" && !skip.has(i)),
         childStdio: runArgs.includes("--tui") ? ["ignore", "ignore", "ignore"] : "inherit",
     };
@@ -344,11 +366,17 @@ export function guiChildPlan(runArgs) {
  * redeploy and exits on its own if this supervisor dies outright (SIGKILL, a crash) — a killed
  * supervisor never leaves a dashboard holding its port. Any other dashboard exit (a failed bind
  * prints its own message and exits) ends this loop and leaves the team running. */
-async function superviseDashboard(signal, stdio = "inherit", guiArgs = []) {
+async function superviseDashboard(signal, guiToken, stdio = "inherit", guiArgs = []) {
     const { DASHBOARD_CHILD_ENV } = await import("../redeploy/self-reload.js");
     const { spawnGuiChild } = await import("../process/supervisor.js");
+    const env = { [DASHBOARD_CHILD_ENV]: String(process.pid) };
+    // The gate token rides in the child's env, not its argv: /proc/<pid>/cmdline is world-readable,
+    // and the child's self-reload (reexecSelf, which propagates env via childEnv) would otherwise
+    // re-run the secret onto each fresh generation.
+    if (guiToken !== undefined)
+        env[GUI_TOKEN_ENV] = guiToken;
     for (;;) {
-        const exit = await spawnGuiChild(signal, { [DASHBOARD_CHILD_ENV]: String(process.pid) }, stdio, guiArgs);
+        const exit = await spawnGuiChild(signal, env, stdio, guiArgs);
         if (signal.aborted || exit.code !== RESTART_EXIT_CODE)
             return;
     }
@@ -409,7 +437,7 @@ async function superviseStartCommand(root, runArgs, branchArg, forMs) {
             guiController.abort();
         })
         : Promise.resolve();
-    const gui = plan.spawnGui ? superviseDashboard(guiController.signal, plan.childStdio, plan.guiArgs) : Promise.resolve();
+    const gui = plan.spawnGui ? superviseDashboard(guiController.signal, plan.guiToken, plan.childStdio, plan.guiArgs) : Promise.resolve();
     const code = await superviseStart({
         spawnChild: (signal) => spawnStartChild(signal, plan.orchestratorArgs, windowEnv, plan.childStdio),
         stopping: () => stopping,