tumwater 0.4.2 → 0.4.4

package/dist/src/doctor/doctor-backlog-plans.js

@@ -1,17 +1,17 @@
 import { andMore, quoteHeading, readDoc, readBacklogChecked, FIX_CLAIMS_CHECKED, REFUSAL_NOTE_MAX } from "./doctor-backlog.js";
+import { agree } from "../text/phrases.js";
 import { cachedByStat } from "../files/stat-cache.js";
 import { VALIDATION_GAP_TAGS } from "../roles/role-guidance.js";
 import path from "node:path";
 import { truncate } from "../text/text.js";
 import { donePlans, fixedBugEntries, openBugEntries, plannedPlanEntries } from "../backlog/backlog.js";
-import { entryHold, entryKindLabel, heldCount } from "../backlog/backlog-eligibility.js";
+import { entryHold, entryKindLabel, isPlanStalled } from "../backlog/backlog-eligibility.js";
 import { planDependencyProblems } from "../backlog/backlog-parts.js";
-import { BACKLOG_FILES, FINISHED_ARCHIVES, validationGapTag } from "../backlog/backlog-md.js";
-import { statOrNull } from "../files/files.js";
+import { BACKLOG_FILES, validationGapTag } from "../backlog/backlog-md.js";
 import { duplicateHeadings, strandedPlanEntriesFor } from "../backlog/backlog-structure.js";
 import { liveFinishedHistory, liveFinishedRowList } from "../backlog/backlog-archive.js";
-import { fixSymbols, missingSymbolNames, cachedSourceHaystack, unbackedSymbols } from "../verdict/fix-claim.js";
-import { okOutcome, warnOutcome } from "./outcome.js";
+import { fixSymbols, isCommitRef, missingSymbolNames, cachedSourceHaystack, unbackedSymbols } from "../verdict/fix-claim.js";
+import { okOutcome, warnOutcome } from "./doctor-outcome.js";
 /** The doctor's PLANS.md-structure and fix-claim checks, split out of doctor-backlog.ts: the
  * checks that re-verify BUGS.md's newest Fixed records against the tree (checkFixClaims,
  * checkValidationGaps) and the PLANS.md / backlog-file integrity checks that read sections and
@@ -21,7 +21,7 @@ import { okOutcome, warnOutcome } from "./outcome.js";
  * heading-trim bounds,
  * and all of them warn instead of failing: damaged documentation is operator signal, not a
  * broken environment. doctor.ts composes them beside the open-item and queue checks; the shared
- * CheckOutcome shape is imported from outcome.ts. */
+ * CheckOutcome shape is imported from doctor-outcome.ts. */
 /** Fix claims — the standalone half of the merge gate's false-fix check (src/verdict/fix-claim.ts):
  * that gate fires only when an md-only diff moves a BUGS.md entry to Fixed, so a phantom fix that
  * reached main any other way (merged before the gate existed, or through a path it never sees) was
@@ -44,20 +44,22 @@ export function checkFixClaims(root) {
     const { heading, missing } = first;
     const names = missingSymbolNames(missing);
     // Every other suspect is still named, shortened: a doctor check is one line.
-    const more = andMore(rest, (p) => quoteHeading(p.heading), "record(s)");
+    const more = andMore(rest, (p) => quoteHeading(p.heading), agree(rest.length, "record", "records"));
     return warnOutcome(`BUGS.md records "${heading}" as Fixed, but none of the symbols its Fix paragraph names ` +
         `exist on this tree: ${names}${more} — land the fix or keep the bug Open / refresh a stale record`);
 }
-/** The fix-claim rows shared by the doctor's check and the always-on alert: each newest Fixed
+/** The fix-claim rows the doctor's check warns about: each newest Fixed
  * record classified through fixSymbols and unbackedSymbols — the gate's own parsing and
  * existence rules — against ONE cachedSourceHaystack built for the whole scan, keeping a record
  * only when EVERY symbol its Fix paragraph names is absent, and skipping a record that names no
- * symbols (pure-documentation fixes are legitimate). */
+ * symbols (pure-documentation fixes are legitimate). A commit id is a citation, not a symbol:
+ * this synchronous scan cannot ask git whether it exists (the gate does), so a record that cites
+ * only the commit it reviewed names nothing checkable. */
 function classifyFixClaims(records, root) {
     const problems = [];
     let haystack;
     for (const { title, body } of records) {
-        const symbols = fixSymbols(body);
+        const symbols = fixSymbols(body).filter((symbol) => !isCommitRef(symbol));
         if (symbols.length === 0)
             continue;
         haystack ??= cachedSourceHaystack(root);
@@ -70,24 +72,20 @@ function classifyFixClaims(records, root) {
 /** The ONE shared fix-claim scan: the newest Fixed records (bounded to FIX_CLAIMS_CHECKED so
  * pre-convention history never warns forever) as fixedBugEntries reads them — the stat-cached
  * section reader BUGS.md + BUGS-FIXED.md, bodies kept whole — classified through
- * classifyFixClaims. Reading through this same reader (and not a one-off fixedEntriesAt walk) is
- * what keeps the alert and the doctor on the identical problem set; there is only one scan. */
+ * classifyFixClaims. */
 function fixClaimRecords(root) {
     return fixedBugEntries(root).slice(0, FIX_CLAIMS_CHECKED);
 }
-/** The problems the ONE shared fix-claim scan found among the newest Fixed records at `root`
+/** The problems the ONE fix-claim scan found among the newest Fixed records at `root`
  * (empty when BUGS.md is unreadable or every newest Fixed record names at least one live
- * symbol). Feeds the always-on amber alert through the stat-cached fixedBugEntries reader and
- * cachedSourceHaystack, so it stays in step with the doctor and adds no re-read to the 1 Hz TUI
- * and status-poll path. */
+ * symbol). */
 export function fixClaimProblems(root) {
     return classifyFixClaims(fixClaimRecords(root), root);
 }
-/** The validation-gap rows shared by the doctor's check and the always-on alert: each newest
+/** The validation-gap rows the doctor's check warns about: each newest
  * Fixed record classified against the closed `**Validation gap:**` vocabulary through
  * validationGapTag, which is fence-aware — suspects (missing/unrecognized) first, then
- * `unpinned`, so the first row is the one the doctor's message names and the alert's reason
- * picks. */
+ * `unpinned`, so the first row is the one the doctor's message names. */
 function classifyValidationGaps(records) {
     const suspects = [];
     const unpinned = [];
@@ -102,22 +100,13 @@ function classifyValidationGaps(records) {
     }
     return [...suspects, ...unpinned];
 }
-/** The ONE scan the doctor's `validation gaps` check and the always-on alert both hand their
- * rows from: the newest Fixed records (bounded to FIX_CLAIMS_CHECKED so pre-convention history
- * never warns forever) as fixedBugEntries reads them — the stat-cached section reader BUGS.md +
- * BUGS-FIXED.md, bodies kept whole — classified through classifyValidationGaps. Reading both
- * through this same reader (and not the doctor's one-off fixedEntriesAt/fixedSection walk) is
- * what keeps the alert and the doctor on the identical problem set; there is only one scan. */
+/** The ONE scan the doctor's `validation gaps` check hands its rows from: the newest Fixed
+ * records (bounded to FIX_CLAIMS_CHECKED so pre-convention history never warns forever) as
+ * fixedBugEntries reads them — the stat-cached section reader BUGS.md + BUGS-FIXED.md, bodies
+ * kept whole — classified through classifyValidationGaps. */
 function validationGapRecords(root) {
     return fixedBugEntries(root).slice(0, FIX_CLAIMS_CHECKED);
 }
-/** The problems the ONE shared validation-gap scan found among the newest Fixed records at `root`
- * (empty when BUGS.md/BUGS-FIXED.md are unreadable or every newest Fixed record carries a known
- * tag/trace). Feeds the always-on amber alert through the stat-cached fixedBugEntries reader, so
- * it stays in step with the doctor and adds no re-read to the 1 Hz TUI and status-poll path. */
-export function validationGapProblems(root) {
-    return classifyValidationGaps(validationGapRecords(root));
-}
 /** The fixed-record validation-gap twin of checkFixClaims, standing in for plans/repair-traces.md's
  * invariant 2 ("the vocabulary is closed and lives in one place"): the bugfix guidance tells every
  * run to write exactly one `**Validation gap:**` line with a known tag, and `none` rather than no
@@ -135,8 +124,7 @@ export function validationGapProblems(root) {
 export function checkValidationGaps(root) {
     // The doctor's check reads BUGS.md itself so it can return its no-file outcome (a missing
     // BUGS.md — nothing to verify); the classification then runs on the SAME fixedBugEntries
-    // reader the always-on alert feeds from, so the two cannot drift on the problem set. There
-    // is only one scan (validationGapRecords).
+    // reader, so the problem set cannot drift. There is only one scan (validationGapRecords).
     const doc = readBacklogChecked(root, "BUGS.md");
     if (typeof doc !== "string")
         return doc;
@@ -147,14 +135,14 @@ export function checkValidationGaps(root) {
     if (!first) {
         if (unpinned.length > 0) {
             const up = unpinned[0];
-            const more = andMore(unpinned.slice(1), (s) => quoteHeading(s.title), "record(s)");
+            const more = andMore(unpinned.slice(1), (s) => quoteHeading(s.title), agree(unpinned.slice(1).length, "record", "records"));
             return warnOutcome(`BUGS.md record "${up.title}" is an \`unclear-invariant\` fix but names no ` +
                 `docs/invariants.md section — record the reconstructed guarantee there (a "Pinned by" line) in the ` +
                 `same commit so the next bug in that area does not reconstruct it again${more}`);
         }
         return okOutcome(`newest ${validationGapRecords(root).length} Fixed record(s) carry a known Validation gap tag`);
     }
-    const more = andMore(rest, (s) => quoteHeading(s.title), "record(s)");
+    const more = andMore(rest, (s) => quoteHeading(s.title), agree(rest.length, "record", "records"));
     const what = first.kind === "missing"
         ? `BUGS.md record "${first.title}" has no **Validation gap:** line`
         : `BUGS.md record "${first.title}" names unrecognized Validation gap tag "${first.tag}"`;
@@ -201,22 +189,17 @@ export function checkLiveFinished(root) {
     return warnOutcome(`${liveFinishedRowList(live)} — every run that reads the file pays for them; ` +
         "`tumwater archive` moves them to the archive files and commits them (a starting team does too)");
 }
-/** The always-on `backlog-headings` alert polls this on every observer surface and every
- * observer tick, so the per-file read must be stat-cached: a steady-state poll pays one stat
- * per file, not a full re-read of every BACKLOG_FILES member — the archives grow without bound
- * (PLANS-DONE.md and BUGS-FIXED.md run to MBs), and an uncached read on every poll would copy
- * them wholesale each time, unlike the stat-cached section readers the rest of the poll path
- * uses. cachedByStat serves an unchanged file from cache (dev/ino/mtime/size) and re-reads on
- * a change, so this shares the poll path's freshness contract. The one loop over BACKLOG_FILES
- * that feeds both checkBacklogHeadings and the always-on `backlog-headings` team alert: absent
+/** The one loop over BACKLOG_FILES the doctor's `backlog headings` check scans for duplicated
+ * `## ` titles. The per-file read is stat-cached (backlogHeadingFileCache) so repeated checks
+ * pay one stat per unchanged file rather than re-reading the whole BACKLOG_FILES member — the
+ * archives grow without bound (PLANS-DONE.md and BUGS-FIXED.md run to MBs) — and cachedByStat
+ * serves an unchanged file from cache (dev/ino/mtime/size) and re-reads on a change. Absent
  * files (an early repo) contribute nothing, an existing file that cannot be read adds
  * `${file} (unreadable)` to `rows` (its duplicate headings, if any, are invisible to every
- * reader), and each duplicate `## ` title joins both `duplicates` and, as
- * `${file} "## ${title}"`, `rows` — which therefore keeps BACKLOG_FILES order, the order the
- * doctor's `backlog headings` row lists its messages in. Two public functions share this so
- * they cannot drift on the file set, the unreadable clause, or the headings. */
+ * reader), and each duplicate `## ` title appears as `${file} "## ${title}"` in
+ * `rows` — which therefore keeps BACKLOG_FILES order, the order the doctor's `backlog
+ * headings` row lists its messages in. */
 function scanBacklogHeadings(root) {
-    const duplicates = [];
     const rows = [];
     for (const file of BACKLOG_FILES) {
         const p = path.join(root, file);
@@ -233,63 +216,14 @@ function scanBacklogHeadings(root) {
             continue;
         }
         for (const heading of scan.headings) {
-            duplicates.push({ file, heading });
             rows.push(`${file} "## ${heading}"`);
         }
     }
-    return { duplicates, rows };
+    return rows;
 }
-/** The module-level stat cache backing scanBacklogHeadings, shared by the doctor row and the
- * always-on alert so the poll path never re-reads an unchanged backlog or archive file. */
+/** The module-level stat cache backing scanBacklogHeadings, so a repeated check never re-reads
+ * an unchanged backlog or archive file. */
 const backlogHeadingFileCache = new Map();
-/** The duplicated `## ` headings already on main, exported so the always-on `backlog-headings`
- * team alert (src/ui/team-alert-backlog.ts) renders the same set the doctor's `backlog
- * headings` row warns about. */
-export function duplicatedBacklogHeadings(root) {
-    return scanBacklogHeadings(root).duplicates;
-}
-/** The module-level stat cache backing liveFinishedEntriesFor, keyed by root, so a steady-state
- * status poll pays four stat calls (two live files, two archives) instead of re-parsing the
- * live files and the unbounded archives (PLANS-DONE.md runs to MBs) on every poll. Keyed by a
- * combined stat signature rather than the shared cachedByStat because each row spans FOUR files
- * (a live file, its finished entries, and the archive it empties into), so no single-file
- * stat-keyed cache entry can serve it. */
-const liveFinishedCache = new Map();
-/** The finished-history rows already on main, exported so the always-on `backlog-archive` team
- * alert (src/ui/team-alert-backlog.ts) renders the same set the doctor's `backlog archive`
- * row warns about — stat-gated so a steady-state poll pays four stats, not a full re-parse.
- * The cache key is the stat identity (`dev:ino:mtimeMs:size`, `absent` when the stat is
- * null) of every
- * FINISHED_ARCHIVES live file and archive under `root`, so any write that changes finished
- * history or the archive refreshes the rows on the next call without a process restart. Returns
- * a copy on a hit; on a miss it recomputes via liveFinishedHistory, and returns `[]` (uncached)
- * when that throws, so an unreadable file stays checkLiveFinished's loud signal and never
- * breaks a status poll. checkLiveFinished keeps calling liveFinishedHistory directly and is
- * unchanged. */
-export function liveFinishedEntriesFor(root) {
-    const key = FINISHED_ARCHIVES
-        .flatMap((spec) => [path.join(root, spec.file), path.join(root, spec.archive)])
-        .map((p) => {
-        const st = statOrNull(p);
-        return st ? `${st.dev}:${st.ino}:${st.mtimeMs}:${st.size}` : "absent";
-    })
-        .join("|");
-    const cached = liveFinishedCache.get(root);
-    if (cached?.key === key)
-        return cached.rows.map((r) => ({ ...r }));
-    let rows;
-    try {
-        rows = liveFinishedHistory(root);
-    }
-    catch {
-        liveFinishedCache.delete(root); // Never serve a stale read for an unreadable tree.
-        return []; // Unreadable — checkLiveFinished's signal; a status poll must not throw.
-    }
-    if (liveFinishedCache.size >= 64)
-        liveFinishedCache.clear(); // Safety cap, like backlogHeadingFileCache.
-    liveFinishedCache.set(root, { key, rows });
-    return rows.map((r) => ({ ...r }));
-}
 /** Duplicated `## ` headings already on main (the duplicate-heading half of the backlog-structure
  * check, src/backlog/backlog-structure.ts): a `## Done` a past merge or conflict resolution added
  * twice leaves every later entry after the first section invisible to the section readers, and
@@ -300,7 +234,7 @@ export function liveFinishedEntriesFor(root) {
  * that leaves an existing duplicate alone passes and the duplicate itself needs a deliberate
  * removal edit. */
 export function checkBacklogHeadings(root) {
-    const { rows } = scanBacklogHeadings(root);
+    const rows = scanBacklogHeadings(root);
     if (rows.length === 0)
         return okOutcome("no duplicated ## section headings in the backlog files");
     const [first, ...rest] = rows;
@@ -309,24 +243,27 @@ export function checkBacklogHeadings(root) {
         `later entries are invisible; keep one heading per name (the gate blocks only a merge ` +
         `that adds another copy — remove the duplicate in a deliberate edit)`);
 }
-/** Stalled entries — plans or bugs held by a **Needs review …** note,
- * parked until the plan role splits or replans them, plus the held-for-operator entries
- * parked until the operator releases them. No role takes a held entry (the claim gate refuses
- * one) and nothing clears the note on its own, so the state is visible only as the
+/** Stalled entries — plans or bugs parked with the plan role by a **Needs review …** note
+ * that the plan role clears by splitting or replanning (the feature role's too-large note, the
+ * convergence hold, a final-round rejection). The bugfix role's wait-for-the-next-failure
+ * parks ("by bugfix:") are excluded — selfcheck lifts them, not the plan role, so they are
+ * not the plan role's stalled work. No role takes a held entry (the claim gate refuses one)
+ * and nothing clears a plan-role note on its own, so the state is visible only as the
  * `[needs review]` marks in the backlog listings; this names them so an
  * operator gets a single-line health signal from `tumwater doctor`. Reads the tree at `root`
  * — the primary checkout IS main's tree — like checkRefusedEntries, which is also where
- * refusal notes (a different hold) are surfaced. entryHold (src/backlog/backlog-eligibility.ts)
- * already classifies the notes, so this check adds no parsing: only the entries whose hold is
- * exactly needs-review or held-for-operator are collected, from both PLANS.md
+ * refusal notes (a different hold) are surfaced. entryHold + isPlanStalled
+ * (src/backlog/backlog-eligibility.ts) already classify the notes, so this check adds no
+ * parsing: only the entries whose hold is exactly needs-review and which isPlanStalled
+ * accepts are collected, from both PLANS.md
  * and BUGS.md. A warn, never a fail — the checkRefusedEntries precedent: a parked entry is
- * operator signal, not a broken environment; the plan role resolves the first itself, and
- * a held-for-operator entry is the operator's to release (`tumwater plan|bug --release`). */
+ * operator signal, not a broken environment; the plan role resolves it by splitting or
+ * replanning. */
 export function checkStalledEntries(root) {
     const planned = plannedPlanEntries(root);
     const collect = (entry, file) => {
         const hold = entryHold(entry, planned);
-        return hold === "needs-review" || hold === "held-for-operator" // vocabulary-ok: the held-for-operator hold's key
+        return hold === "needs-review" && isPlanStalled(entry)
             ? { file, entry }
             : null;
     };
@@ -336,15 +273,11 @@ export function checkStalledEntries(root) {
     ].filter((x) => x !== null);
     const [first, ...rest] = stalled;
     if (!first)
-        return okOutcome("no planned plan or open bug is held by a Needs-review or held-for-operator note"); // vocabulary-ok: names the held-for-operator hold
+        return okOutcome("no planned plan or open bug is held by a Needs-review note");
     const more = andMore(rest, (s) => quoteHeading(s.entry.title));
     const kind = entryKindLabel(first.file); // "Bug" | "Plan"
     const head = `${first.file === "bugs" ? "BUGS.md" : "PLANS.md"} ${kind.toLowerCase()}`;
-    const hold = entryHold(first.entry, planned);
     const note = (first.entry.body.split(/\n/).find((line) => line.trimStart().startsWith("**Needs review ")) ?? "").replace(/^\s*\*\*/, "").replace("**", "");
-    if (hold === "held-for-operator") { // vocabulary-ok: the held-for-operator hold's key
-        return warnOutcome(`${head} ${quoteHeading(first.entry.title)} is held for the operator ${heldCount(first.entry.body)} times${more} — release it with tumwater ${kind.toLowerCase()} --release`); // vocabulary-ok: a held-for-operator entry is the operator's to release
-    }
     return warnOutcome(`${head} ${quoteHeading(first.entry.title)} is held by a Needs review note ` +
         `(${truncate(note, REFUSAL_NOTE_MAX)})${more} — the plan role resolves it by splitting or replanning`);
 }
@@ -375,16 +308,16 @@ export function planDependencyProblem(root) {
     }
     if (firstDangling) {
         return { kind: "dangling", message: danglingMsg(firstDangling) +
-                andMore(restDangling, (d) => `${quote(d.title)} → ${d.ref}`, "ref(s)") +
+                andMore(restDangling, (d) => `${quote(d.title)} → ${d.ref}`, agree(restDangling.length, "ref", "refs")) +
                 others([[unparsed.length, "unparsed clause(s)"], [misworded.length, "misworded dependency(ies)"]]) };
     }
     if (firstUnparsed) {
-        return { kind: "unparsed", message: unparsedMsg(firstUnparsed) + andMore(restUnparsed, quote, "clause(s)") +
+        return { kind: "unparsed", message: unparsedMsg(firstUnparsed) + andMore(restUnparsed, quote, agree(restUnparsed.length, "clause", "clauses")) +
                 others([[misworded.length, "misworded dependency(ies)"]]) };
     }
     if (firstMisworded) {
         return { kind: "misworded", message: miswordedMsg(firstMisworded) +
-                andMore(restMisworded, (w) => `${quote(w.title)} → ${w.ref}`, "dependency(ies)") };
+                andMore(restMisworded, (w) => `${quote(w.title)} → ${w.ref}`, agree(restMisworded.length, "dependency", "dependencies")) };
     }
     return null;
 }

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

@@ -4,11 +4,11 @@ import path from "node:path";
 import { errorMessage, truncate } from "../text/text.js";
 import { shortSha } from "../text/format.js";
 import { readPostReviews, POST_REVIEW_FAILURE_LIMIT } from "../review/post-merge-review.js";
-import { humanSeconds, secondsSince, HOUR_MS, DAY_MS } from "../text/datetime.js";
+import { humanSeconds, humanSince, HOUR_MS, DAY_MS } from "../text/datetime.js";
 import { eventsSince } from "../events/event-window.js";
 import { finiteNumber } from "../files/json-object.js";
-import { lowerMedian } from "../collections.js";
-import { plural, shortSpanPhrase } from "../text/phrases.js";
+import { distinctOrdered, lowerMedian } from "../collections.js";
+import { agree, plural, trailingDayMedianPhrase } from "../text/phrases.js";
 import { queuedMerges, unreadableMergeQueueFiles } from "../merge/merge-queue.js";
 import { mergeChanges, readMergeMarker } from "../merge/merge-slot.js";
 import { listWideScope, queuedListRows } from "../inbox/inbox.js";
@@ -19,7 +19,7 @@ import { stampedSubject } from "../git/commit-message.js";
 import { commitOperatorBacklogEdit } from "../backlog/backlog-commit.js";
 import { briefFile } from "../brief/brief.js";
 import { BACKLOG_FILES } from "../backlog/backlog-md.js";
-import { okOutcome, warnOutcome } from "./outcome.js";
+import { okOutcome, warnOutcome } from "./doctor-outcome.js";
 /** The doctor's backlog modules' shared scaffolding and the check groups that do not read a
  * single backlog document: the merge-queue, post-merge-review and queued-prompt checks
  * (checkStaleQueuedMerges, checkMergeQueueFiles, checkPostReviews, checkStalePrompts and the
@@ -30,7 +30,8 @@ import { okOutcome, warnOutcome } from "./outcome.js";
  * checks live in doctor-backlog-plans.ts (the plan-document structure and fix-claim checks) and
  * doctor-backlog-bugs.ts (open bugs, questions and holds). All of them warn instead of failing:
  * damaged documentation is operator signal, not a broken environment. doctor.ts composes them
- * beside the environment checks; the shared CheckOutcome shape is imported from outcome.ts. */
+ * beside the environment checks; the shared CheckOutcome shape is imported from
+ * doctor-outcome.ts. */
 /** How many Fixed records the two newest-first Fixed-record checks (fix claims and validation
  * gaps) verify: the newest, since the section is newest-first by template convention. Older
  * records drift as the code evolves — a symbol legitimately fixed long ago gets renamed later,
@@ -55,7 +56,8 @@ export const STALE_BUG_DAYS = 3;
  * shortened, since a doctor check renders one line. `render` makes each extra item's short
  * form — the fix-claim and stranded-plan sites quote a heading trimmed to
  * FIX_CLAIM_HEADING_MAX, the duplicate-headings site passes its items through as built;
- * `noun` names what the extras are ("record(s)" for fix claims, empty for the other two).
+ * `noun` names what the extras are and must already agree with `rest.length` — callers pass
+ * `agree(rest.length, "record", "records")`, or empty where no noun is named.
  * Empty string when there are no extras. */
 export function andMore(rest, render, noun = "") {
     return rest.length > 0
@@ -134,7 +136,7 @@ export function checkStaleQueuedMerges(root, now) {
         }
         return phrase ? { ...out, detail: `${out.detail} · ${phrase}` } : out;
     };
-    const stale = staleQueuedMergeRows(root, now).map((e) => ({ ...e, age: humanSeconds(secondsSince(now - e.waitedMs, now)) }));
+    const stale = staleQueuedMergeRows(root, now).map((e) => ({ ...e, age: humanSince(now - e.waitedMs, now) }));
     const [first, ...rest] = stale;
     if (!first)
         return withWait(okOutcome(`no merge-queue entry has waited more than ${humanSeconds(MERGE_QUEUE_STALE_MS / 1000)} to start`));
@@ -175,7 +177,7 @@ export function checkMergeQueueFiles(root) {
     if (files.length === 0)
         return okOutcome("the queue reader skips no merge-queue file");
     const [first, ...rest] = files;
-    const more = andMore(rest, (f) => f, "file(s)");
+    const more = andMore(rest, (f) => f, agree(rest.length, "file", "files"));
     return warnOutcome(`the merge queue holds ${plural(files.length, "file")} the reader skips — ${first}${more}; ` +
         `a torn or foreign file is never cleared, so nothing ages it or surfaces its merge — remove it (a crashed enqueue's merge ref still recovers on the next run)`);
 }
@@ -260,7 +262,7 @@ export function checkStalePrompts(root, now) {
     if (!first)
         return okOutcome("no queued prompt has waited more than 1 day for a role to dequeue it");
     const more = andMore(rest, (p) => `${p.role} #${p.position}`);
-    return warnOutcome(`inbox prompt for ${roleLabel(first.role)} #${first.position} has waited ${humanSeconds(secondsSince(first.queuedAtMs, now))} — ` +
+    return warnOutcome(`inbox prompt for ${roleLabel(first.role)} #${first.position} has waited ${humanSince(first.queuedAtMs, now)} — ` +
         "the role is not dequeuing it (paused, disabled, or failing); resume or enable it, or drop the prompt with " +
         `\`tumwater prompt --cancel ${first.position} --role ${first.role}\`${more}`);
 }
@@ -277,7 +279,7 @@ export function mergeWaitPhrase(events) {
         return undefined;
     const median = lowerMedian(waits);
     const longest = Math.max(...waits);
-    return `merges in the last 24h waited ${shortSpanPhrase(median)} median, ${shortSpanPhrase(longest)} longest (${plural(waits.length, "merge")})`;
+    return `merges in the last 24h waited ${trailingDayMedianPhrase(median, longest, "longest", waits.length, "merge")}`;
 }
 /** Discover the tracked backlog/brief files with uncommitted edits in the primary checkout (the
  * shared discovery behind checkUncommittedBacklog and commitUncommittedBacklog). A primary off
@@ -299,7 +301,7 @@ export async function dirtyBacklogFiles(root, config) {
         // An unreadable brief is a doctor finding of its own; it must not abort the uncommitted-backlog
         // check or `--commit-backlog`, so the tracked backlog set is watched without it.
     }
-    const watched = [...new Set([...BACKLOG_FILES, ...(brief ? [brief] : [])])];
+    const watched = distinctOrdered([...BACKLOG_FILES, ...(brief ? [brief] : [])]);
     const out = await gitTry(root, "status", "--porcelain", "--", ...watched);
     if (out === null)
         return { base, primary, watched, dirty: null };
@@ -357,9 +359,9 @@ export async function commitUncommittedBacklog(root, config) {
  * for a BacklogCommitReport, so the three surfaces cannot drift: one `committed <file> on
  * <base>` line per committed file, one `could not commit <file> — commit it by hand` line per
  * failed file, then the skipped sentence when set. `[]` when the report committed nothing,
- * failed nothing, and carried no skip sentence. `tumwater doctor --commit-backlog` (src/cli.ts),
- * the dashboard Health card's Commit backlog (handleCommitBacklog) and the TUI Health tab's
- * Ctrl+A all render from this one source. */
+ * failed nothing, and carried no skip sentence. `tumwater doctor --commit-backlog`
+ * (src/cli/cli-doctor-command.ts), the dashboard Health card's Commit backlog
+ * (handleCommitBacklog) and the TUI Health tab's Ctrl+A all render from this one source. */
 export function backlogCommitLines(report) {
     const lines = [
         ...report.committed.map((file) => `committed ${file} on ${report.base}`),

package/dist/src/doctor/doctor-check-names.js

@@ -1,9 +1,8 @@
 /** Every row name `tumwater doctor` can print, in report order — the names `tumwater doctor
  * <check>...` accepts. A leaf with no imports: cli.ts loads doctor.ts with a dynamic import()
  * while cli-command-args.ts is imported eagerly, so the argument parser reads the names from
- * here instead of pulling every check module into each CLI start. `pi extensions`, `funes`, and
- * the `claude window`/`codex window` subscription rows are conditional: a named one whose check
- * returns null leaves no row. */
+ * here instead of pulling every check module into each CLI start. `pi extensions` and `funes`
+ * are conditional: a named one whose check returns null leaves no row. */
 export const DOCTOR_CHECK_NAMES = [
     "node",
     "node binary",
@@ -17,11 +16,8 @@ export const DOCTOR_CHECK_NAMES = [
     "pause",
     "quiet hours",
     "budget",
-    "claude window",
-    "codex window",
     "provider waits",
     "maintenance allowance",
-    "provider concurrency",
     "provider contention",
     "check contention",
     "repeated failures",
@@ -29,6 +25,7 @@ export const DOCTOR_CHECK_NAMES = [
     "over-cap model",
     "fallback chain",
     "models for each tier",
+    "image input",
     "claude auth",
     "claude api key",
     "claude version",

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

@@ -17,13 +17,13 @@ import { errorMessage } from "../text/text.js";
 import { formatBytes } from "../text/format.js";
 import { BRIEF_TEXT_MAX_CHARS, briefFile, promptBlockOf, readBrief } from "../brief/brief.js";
 import { plural } from "../text/phrases.js";
-import { backendsInUse, unregisteredBackendInUse } from "../gates/startup-gate.js";
-import { claudeSeamsInUse, minVersionOutcome, opencodeSeamsInUse, versionFromProbe, piSeamsInUse } from "./doctor-model-checks.js";
+import { backendsInUse, unregisteredBackendInUse } from "../gates/startup-gates.js";
+import { claudeSeamsInUse, loadConfigForCheck, minVersionOutcome, opencodeSeamsInUse, versionFromProbe, piSeamsInUse } from "./doctor-model-checks.js";
 import { claudeConfigDir } from "../agent/claude/claude-backend.js";
-import { AUTH_CHECK_MAX_OUTPUT_BYTES, AUTH_CHECK_TIMEOUT_MS, boundedProbe } from "./probe.js";
+import { AUTH_CHECK_MAX_OUTPUT_BYTES, AUTH_CHECK_TIMEOUT_MS, boundedProbe } from "./doctor-probe.js";
 import { childEnv } from "../process/process.js";
 import { opencodeBackend, OPENCODE_MIN_VERSION } from "../agent/opencode/opencode-backend.js";
-import { failOutcome, okOutcome, warnOutcome } from "./outcome.js";
+import { failOutcome, noConfigOutcome, okOutcome, warnOutcome } from "./doctor-outcome.js";
 import { spawnSync } from "node:child_process";
 /** The floor doctor falls back to when package.json — the one source of the declared
  * engines.node spec, read below — cannot be read (a broken install, the version command's
@@ -236,9 +236,9 @@ export function checkBackendBinary(root, pathEnv = envPath()) {
  * (a 1.x binary included) fails naming `brew install opencode`; at or above it reads the
  * version. Stands down when no seam routes to opencode, so a pi-only team spawns no opencode. */
 export async function checkOpencodeVersion(root, pathEnv = envPath(), timeoutMs = AUTH_CHECK_TIMEOUT_MS) {
-    const { config } = loadConfigSafe(root);
-    if (config === undefined)
-        return okOutcome("no readable tumwater.json — nothing to verify");
+    const config = loadConfigForCheck(root);
+    if ("level" in config)
+        return config;
     if (!opencodeSeamsInUse(config))
         return okOutcome("no model jobs run on opencode");
     const resolved = opencodeBackend.resolveBin(config);
@@ -255,7 +255,7 @@ export async function checkOpencodeVersion(root, pathEnv = envPath(), timeoutMs
  * `homeDir` and `env` are test seams. */
 export function checkClaudeTranscripts(config, homeDir = os.homedir(), env = process.env) {
     if (!config)
-        return okOutcome("no readable tumwater.json — nothing to verify");
+        return noConfigOutcome();
     if (!claudeSeamsInUse(config))
         return okOutcome("no model jobs run on claude");
     const configDir = resolvedBackendConfig(config, "claude").configDir;