tumwater 0.4.4 → 0.4.6

package/dist/src/build/build-check.js

@@ -1,7 +1,7 @@
 import { BUILD_CHECK_TIMEOUT_MS } from "./build-check-detect.js";
 import { EXEC_MAX_BUFFER, execFileAsync } from "../process/process.js";
 import { KILL_GRACE_MS, runScriptGroup } from "../process/process-group.js";
-import { clipBuildTail, parseFailingTests } from "./build-check-report.js";
+import { clipBuildTail, parseFailingTestFiles, parseFailingTests } from "./build-check-report.js";
 import { parseTestCounts } from "./build-check-counts.js";
 import { sampleSleepClock, sleptMsBetween } from "./host-sleep.js";
 import { npmInstall, syncInstall } from "./dep-install.js";
@@ -177,6 +177,7 @@ async function runDeclaredCheck(wt, check, script, effectiveMs, killGraceMs, sam
             script,
             outputTail: clipBuildTail(output),
             failingTests: parseFailingTests(output),
+            failingTestFiles: parseFailingTestFiles(output),
             run,
             counts: parseTestCounts(output),
         };

package/dist/src/build/build-info.js

@@ -54,6 +54,10 @@ export async function isSelfHosted(root, info) {
         return false;
     return commitExists(root, info.sha);
 }
+/** The steps a self-redeploy holds new runs through, in order: main's check of the target head
+ * has not answered yet, the staged build of it is compiling, then the built update waits while
+ * the runs already in flight finish. */
+export const RESTART_HOLD_STAGES = ["checking", "compiling", "finishing"];
 /** Compare a build's commit against main's head over the build inputs only: commits touching
  * just tests or markdown leave the running code unchanged and never count as stale. Null when
  * `buildSha` is not a commit of this repo (the build came from somewhere else — see

package/dist/src/build/dep-install.js

@@ -106,8 +106,7 @@ export async function syncRootInstall(root, role, install = npmInstall) {
     if (!r)
         return;
     // Best-effort: the root install already ran and the ff that prompted it already moved main, so an
-    // unwritable feed must not reject the merge that awaited this (merge-to-main.ts's tryMerge,
-    // merge-stack.ts's ffStackToMain).
+    // unwritable feed must not reject the merge that awaited this (merge-to-main.ts's tryMerge).
     logEventBestEffort(root, {
         source: role,
         type: "dep_install",

package/dist/src/build/host-sleep.js

@@ -85,4 +85,13 @@ export function sleptMsBetween(a, b) {
     }
     return undefined;
 }
+/** Is the host starved — its one-minute load average above the core count? The one bar for
+ * "the team's own load, not the work": the merge-scope deadline stretch and its on-time-kill
+ * note (starvedDeadlineMs / loadedHostPhrase in build-check-events.ts) and the doctor's
+ * check-slot contention advice (doctor-contention-checks.ts) all read the host through this,
+ * so the surfaces cannot drift on what "starved" means. A core count of zero or below is not
+ * starved: there is no denominator for the ratio to exceed. */
+export function hostLoadStarved(load) {
+    return load.cpus > 0 && load.load1 > load.cpus;
+}
 export const sampleHostLoad = () => ({ load1: os.loadavg()[0] ?? 0, cpus: os.cpus().length });

package/dist/src/change/change-render.js

@@ -2,6 +2,7 @@
  * collector (change-data.ts, beside src/report/report-data.ts and history-data.ts) gathers: one
  * role's pending work (`--role <id>`) and the team-wide roster (no --role). Pure function of the
  * collected view — no I/O, no clock reads. */
+import { joinOr } from "../text/format.js";
 import { plural } from "../text/phrases.js";
 /** The work-summary phrase both change views open their work lines with — `N commits ahead
  * of <main>` plus `, K commits behind` when the branch lags main, plus `, M uncommitted
@@ -35,7 +36,7 @@ export function renderTeamChange(view) {
     const lines = view.roles
         .filter((r) => r.state !== "no-base" && (r.ahead > 0 || r.dirtyFiles.length > 0))
         .map((r) => `${r.role}: ${workSummary(r.ahead, r.behind, view.mainBranch, r.dirtyFiles)}`);
-    return lines.length > 0 ? lines.join("\n") : "no pending changes";
+    return joinOr(lines, "\n", "no pending changes");
 }
 /** Render the view as the operator-facing text `tumwater diff --role <id>` prints. */
 export function renderRoleChange(view) {

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

@@ -4,6 +4,7 @@ import { knownRoleIdsCached } from "../config/config.js";
 import { allRoleIds, unknownRoleMessage } from "../roles/roles.js";
 import { gotSuffix, parsePositiveInt, splitCommaList } from "../text/text.js";
 import { canonicalRoleId } from "../roles/legacy-role-ids.js";
+import { HOUR_MS, DAY_MS } from "../text/datetime.js";
 /** CLI argument parsing and validation, shared by every command in cli.ts. The execution
  * layer calls these before running a command, so a bad flag fails fast with an actionable
  * message instead of the command silently running with default behavior. The plain-decimal
@@ -150,6 +151,12 @@ export function parseModelFlag(args, missingValueError) {
 export function parseCountFlag(flag, raw, max) {
     if (raw === undefined)
         fail(`${flag} needs a value`);
+    // A `--`-token in the count's slot is the operator's slipped value (`logs -n --json`, a
+    // `--cancel --json`), never a count — counts never start with `-`, so refuse it up front
+    // with rejectFlagLookingValue's shared wording instead of reporting the dropped flag as a
+    // malformed count ("got \"--json\""). A single-dash token like `-5` is a malformed count
+    // and still reads as one. The sibling parsePositionFlag applies the same guard.
+    rejectFlagLookingValue(flag, raw);
     const n = parsePositiveInt(raw);
     if (n === null)
         fail(`${flag} needs a positive integer${gotSuffix(raw)}`);
@@ -168,6 +175,10 @@ export function parseCountFlag(flag, raw, max) {
 export function parsePositionFlag(flag, raw, example) {
     if (raw === undefined)
         fail(`${flag} needs a position number (e.g. \`${example}\`)`);
+    // The same slipped-`--`-flag guard parseCountFlag applies: a position never starts with
+    // `-`, so `--cancel --json` (or any `--`-token) names its own slipped flag rather than
+    // reporting "(got \"--json\")" as a malformed position number.
+    rejectFlagLookingValue(flag, raw);
     const n = parsePositiveInt(raw);
     if (n === null)
         fail(`${flag} needs a positive integer${gotSuffix(raw)}`);
@@ -240,6 +251,7 @@ export function parseRoleListFlag(args, validIds) {
     const typed = flagValue(args, "--role");
     if (typed === null)
         return null;
+    rejectFlagLookingValue("--role", typed);
     const pieces = splitCommaList(typed ?? "");
     if (pieces.length === 0)
         fail(ROLE_VALUE_ERROR);
@@ -260,13 +272,22 @@ export function parseRoleListFlag(args, validIds) {
 export function parsePortFlag(raw) {
     if (raw === undefined)
         fail("--port needs a value");
+    // A `--`-token in the slot is the operator's slipped next flag (`gui --port --json`),
+    // never a port number — a port never starts with `-` — so refuse it up front with
+    // rejectFlagLookingValue's shared wording, the same guard history's --result/--model/--by
+    // and the count/position/duration/role flag homes apply, instead of reporting the next
+    // flag as a malformed number.
+    rejectFlagLookingValue("--port", raw);
     const n = parsePositiveInt(raw);
     if (n === null || n > 65535)
         fail(`--port must be an integer between 1 and 65535${gotSuffix(raw)}`);
     return n;
 }
-/** Milliseconds per unit, the multiplier parseDurationFlag's regex group is applied to. */
-const UNIT_MS = { s: 1_000, m: 60_000, h: 3_600_000, d: 86_400_000 };
+/** Milliseconds per unit, the multiplier parseDurationFlag's regex group is applied to.
+ * The hour and day multipliers are HOUR_MS / DAY_MS (text/datetime.ts's shared units, the
+ * convention that records why no two sites may spell them differently); second and minute
+ * keep their own literals as there is no shared MINUTE_MS/SECOND_MS constant to fold onto. */
+const UNIT_MS = { s: 1_000, m: 60_000, h: HOUR_MS, d: DAY_MS };
 /** The position of each unit in the descending order a composite duration must follow
  * (d → h → m → s), so `30m1h` and `1h30m1h` fail instead of parsing to a surprising total. */
 const UNIT_ORDER = { d: 0, h: 1, m: 2, s: 3 };
@@ -310,6 +331,12 @@ export function parseDurationMs(raw) {
 export function parseDurationFlag(flag, raw) {
     if (raw === undefined)
         fail(`${flag} needs a value`);
+    // A `--`-token in the value slot is the operator's slipped value (`start --for --json`),
+    // never a duration — durations never start with `-` — so refuse it up front with
+    // rejectFlagLookingValue's shared wording, the same guard history's --result/--model/--by,
+    // reviews --status and role-command's write flags apply, instead of misreading the next
+    // flag as a duration and reporting it as malformed ("got \"--json\"").
+    rejectFlagLookingValue(flag, raw);
     const ms = parseDurationMs(raw);
     if (ms === null)
         fail(`${flag} needs a duration like 45s, 90m, 1h30m, or 2d${gotSuffix(raw)}`);
@@ -371,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
@@ -417,6 +452,11 @@ export function parseRoleFlag(args, validIds, flag = "--role", missingValue = RO
     const typed = flagValue(args, flag);
     if (typed === null)
         return null;
+    // A `--`-token in the id's slot is the operator's slipped value (`--role --json`), never a
+    // role id — role ids are bare words that never start with `-` — so refuse it up front with
+    // rejectFlagLookingValue's shared wording, the same guard history's --result/--model/--by
+    // and reviews --status apply, instead of reporting the next flag as an "unknown role".
+    rejectFlagLookingValue(flag, typed);
     if (!typed)
         fail(missingValue);
     const role = canonicalRoleId(typed);
@@ -427,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-command-args.js

@@ -8,7 +8,7 @@
  * apart from cli/cli-args.ts's generic machinery — which also keeps that module, minus these
  * two, free of I/O: --file's readFileSync is the one read in the CLI's arg layer. */
 import fs from "node:fs";
-import { failOverDurationCap, parseBranchFlag, parseDurationFlag, parsePositionFlag, rejectRepeatFlag } from "./cli-args.js";
+import { failOverDurationCap, parseBranchFlag, parseDurationFlag, parsePositionFlag, rejectFlagLookingValue, rejectRepeatFlag } from "./cli-args.js";
 import { PAUSE_FOR_MAX_MS } from "../operator/operator-intent.js";
 import { JSON_FLAG, ROLE_FLAG, ROLE_VALUE_ERROR, rejectUnknownDoubleDash, } from "./cli-flag-specs.js";
 import { fail } from "./cli-output.js";
@@ -99,8 +99,11 @@ function readPromptFile(file) {
  * shared by every `--file`-taking parser — init, prompt's edit and enqueue branches, plan/bug
  * add and edit (fileAndAnnounce / editAndAnnounce), and the questions command — so the wording
  * cannot drift between them. The flag token itself is claimed by each parser's stray-argument
- * accounting; this helper only owns the value. */
+ * accounting; this helper only owns the value. A flag-shaped token (`--file --json`) is
+ * refused up front via rejectFlagLookingValue instead of being read as a path that fails deep
+ * with a misleading "cannot read prompt file" about a flag nobody intended as a file. */
 export function promptFileValue(file) {
+    rejectFlagLookingValue("--file", file);
     if (!file)
         fail("--file needs a path");
     return file;
@@ -386,13 +389,18 @@ function assertPromptQueueOnlyFlags(scan) {
  * with the missing-value refusal, verbatim. */
 function parsePromptAttachments(args, attachFlags) {
     // Each --attach pair claims the flag and its value; a trailing flag with no value names the
-    // flag here, like --cancel's missing-value wording, before any queue write.
-    const attachPaths = attachFlags.map((i) => args[i + 1]);
+    // flag here, like --cancel's missing-value wording, before any queue write. A `--`-shaped
+    // token in the value slot is the operator's slip (`--attach --role qa`), so it is refused up
+    // front with rejectFlagLookingValue's shared wording — the same guard history's
+    // --result/--model and role <id>'s write flags apply — instead of failing deep in image
+    // reading with a misleading message about a path nobody intended.
     const attachClaims = attachFlags.flatMap((i) => [i, i + 1]);
     for (const i of attachFlags) {
         if (args[i + 1] === undefined)
             fail(`--attach needs a path (e.g. \`--attach shot.png\`)`);
+        rejectFlagLookingValue("--attach", args[i + 1]);
     }
+    const attachPaths = attachFlags.map((i) => args[i + 1]);
     return { attachPaths, attachClaims };
 }
 /** The `--at <duration>` parse and its 90-day cap, verbatim. */

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

@@ -37,7 +37,11 @@ function printInitIntro(result) {
     if (result.template !== "blank")
         say(`template: ${result.template}`);
     if (result.adopted) {
-        say(`${result.dryRun ? "would adopt" : "adopting"} an existing repo: the project brief goes in TUMWATER.md and README.md is left untouched`);
+        // Adoption preserves the project's own README.md; the "existing repo" claim holds only when
+        // the directory already was a repo — when init seeds one itself, naming it "existing" would
+        // contradict the "initialized a new git repository" line the report prints right after.
+        const target = result.repoInitialized ? "the existing README.md" : "an existing repo";
+        say(`${result.dryRun ? "would adopt" : "adopting"} ${target}: the project brief goes in TUMWATER.md and README.md is left untouched`);
     }
 }
 /** Print the dry-run preview: repo line, the would-create/would-leave-alone lists, and the

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

@@ -7,12 +7,13 @@ 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, parseRoleListScope, rejectRepeatFlag, scanPositionArgs } from "./cli-args.js";
+import { flagValue, parseGrepFlag, parseRoleListScope, rejectFlagLookingValue, 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";
 import { statusPayload } from "../ui/status-payload.js";
 import { renderStatus } from "../ui/status-render.js";
+import { gotSuffix } from "../text/text.js";
 import { backlogPayload } from "../backlog/backlog.js";
 import { backlogHolds, backlogInProgress } from "../backlog/backlog-eligibility.js";
 import { readyBacklog, grepBacklog, renderBacklogMarkdown } from "../backlog/backlog-render.js";
@@ -22,7 +23,7 @@ import { collectChangeOverlaps, scopeChangeOverlaps, scopeChangeOverlapsToPath,
 import { renderChangeOverlaps, renderTeamChange, renderRoleChange, renderRoleChanges } from "../change/change-render.js";
 import { readMergeQueue } from "../merge/merge-queue.js";
 import { renderMergeQueue, scopeMergeQueue } from "../merge/merge-queue-render.js";
-import { mergeChanges } from "../merge/merge-slot.js";
+import { mergeHoldsSha } from "../merge/merge-slot.js";
 import { shortSha } from "../text/format.js";
 import { roleLabel } from "../roles/role-labels.js";
 import { orchestratorAlive } from "../team/team-orchestrator-info.js";
@@ -135,14 +136,17 @@ export async function cmdDiff(root, args, seams = {}) {
     sayJsonOrRender(args, view, () => render());
 }
 /** The normalised `--path` value of `diff --role` (undefined when absent): leading `./` pieces
- * and trailing `/` characters stripped, failing on an empty, absolute or `..`-bearing result. */
+ * and trailing `/` characters stripped, failing on an empty, absolute or `..`-bearing result.
+ * A `--` token in the value slot is refused via rejectFlagLookingValue first, so `diff --role
+ * feature --path --json` names the flag instead of failing downstream as a path nobody meant. */
 function diffPathArg(args) {
     const raw = flagValue(args, "--path");
     if (raw === null || raw === undefined)
         return undefined;
+    rejectFlagLookingValue("--path", raw);
     const norm = normalizeDiffPath(raw);
     if (norm === null)
-        fail("diff --path takes a repo-relative path such as src/cli.ts (as diff --overlaps prints it)");
+        fail(`diff --path takes a repo-relative path such as src/cli.ts (as diff --overlaps prints it)${gotSuffix(raw)}`);
     return norm;
 }
 /** `tumwater queue [-f/--follow]`: the durable merge queue in execution order, as text or as
@@ -216,7 +220,7 @@ async function cmdQueueCancel(root, args) {
     const view = readMergeQueue(root);
     const inFlight = queueInFlight(root, view.entries, orchestratorAlive(root));
     const target = view.entries[position - 1];
-    if (inFlight && target && (target.sha === inFlight.sha || mergeChanges(inFlight).some((c) => c.sha === target.sha))) {
+    if (inFlight && target && mergeHoldsSha(inFlight, target.sha)) {
         fail(`queue entry ${position} is being merged right now — wait for it to land, then \`tumwater revert ${shortSha(target.sha)}\``);
     }
     const outcome = await cancelQueuedMerge(root, position);
@@ -258,7 +262,7 @@ async function cmdQueueTop(root, args) {
     const view = readMergeQueue(root);
     const inFlight = queueInFlight(root, view.entries, orchestratorAlive(root));
     const target = view.entries[position - 1];
-    if (inFlight && target && (target.sha === inFlight.sha || mergeChanges(inFlight).some((c) => c.sha === target.sha))) {
+    if (inFlight && target && mergeHoldsSha(inFlight, target.sha)) {
         fail(`queue entry ${position} is being merged right now — it's already heading into the merge, so there's nothing to top`);
     }
     const outcome = moveQueuedMergeToTop(root, position);
@@ -338,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/cli-review-commands.js

@@ -18,8 +18,8 @@ import { POST_REVIEW_STATES, postReviewState, renderPostReviews, scopePostReview
 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";
+import { splitCommaList } from "../text/text.js";
+import { oneOfMessage } 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";
@@ -36,7 +36,7 @@ function parseReviewStatusList(raw) {
     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)}`);
+            fail(`reviews --status ${oneOfMessage(spellings)(piece)}`);
         if (!out.includes(piece))
             out.push(piece);
     }