tumwater 0.4.2 → 0.4.4

package/dist/src/agent/subscription-account.js

@@ -3,8 +3,7 @@
  * "Billing" and §8 "The subscription usage window"). Persisted at
  * `.tumwater/state/<backend>-account.json` (plan design grounds/codex-backend.md "Groundwork:
  * the subscription account is per backend", item 1), written only by the orchestrator process,
- * so the sibling parts that throttle or display the subscription window read one answer instead
- * of re-deriving it per surface.
+ * so the sibling parts read one answer instead of re-deriving it per surface.
  *
  * The file is a cache, never a source of truth: a run that reports billing overwrites it, and a
  * missing or unreadable file reads as "no subscription". `resetsAt` is stored as epoch
@@ -28,85 +27,6 @@ export function subscriptionWindowRejected(run) {
         run.billing === "subscription" &&
         (run.rateWindows ?? []).some((w) => w.status === "rejected" && w.isUsingOverage !== true));
 }
-/** The subscription account's used-up usage window, or null: a window reading `rejected` with
- * no overage, or (with `includeOverage`, the default) a window whose current reading shows
- * `isUsingOverage`, and a `resetsAt` still ahead of `now`; among several, the one that resets
- * last. With a `reserve` (config `backends.<id>.windowReserve`), a window whose utilization
- * has reached its type's fraction counts too, and comes back with `reserve: true`; a rejected
- * or overage window outranks a reserve one, so the flag is set only when no window is used up
- * for real. The budget gate's window move (pollBudgetGate) reads the default; the team hold
- * (windowObservation) passes `includeOverage: false`, because overage never holds a
- * seam. Only subscription billing produces one; a missing account reads null. */
-export function windowUsedUp(account, now, includeOverage = true, reserve) {
-    if (account?.billing !== "subscription")
-        return null;
-    let furthest = null;
-    let reserved = null;
-    for (const [type, w] of Object.entries(account.windows)) {
-        if (typeof w.resetsAt !== "number" || w.resetsAt <= now)
-            continue;
-        const used = w.isUsingOverage === true ? includeOverage : w.status === "rejected";
-        if (used) {
-            if (furthest === null || w.resetsAt > furthest.resetsAt)
-                furthest = { type, resetsAt: w.resetsAt };
-            continue;
-        }
-        if (windowReserved(w, reserve?.[type]) && (reserved === null || w.resetsAt > reserved.resetsAt))
-            reserved = { type, resetsAt: w.resetsAt, reserve: true };
-    }
-    return furthest ?? reserved;
-}
-/** Has this window's utilization reached its reserve fraction? False without a fraction or a
- * reading. */
-export function windowReserved(w, fraction) {
-    return fraction !== undefined && typeof w.utilization === "number" && w.utilization >= fraction;
-}
-/** Status severity for ordering: a rejected window limits, an allowed_warning nears its limit,
- * every other reading (allowed/ok) rides at the bottom, and a reset one no longer limits. */
-const WINDOW_RANK = { rejected: 3, allowed_warning: 2, reset: 0 };
-/** The window type as a compact label: `five_hour` → `5h`, `seven_day` → `7d`; an unknown
- * type falls back to its words with underscores as spaces. The one home of the window spelling
- * the status badge and the role view share. */
-export function windowLabel(type) {
-    const m = /^(\w+)_(hour|day|week)$/.exec(type);
-    if (!m)
-        return type.replace(/_/g, " ");
-    const words = { one: "1", two: "2", three: "3", four: "4", five: "5", six: "6", seven: "7", eight: "8", nine: "9", ten: "10" };
-    const unit = m[2] === "hour" ? "h" : m[2] === "day" ? "d" : "w";
-    const word = m[1] ?? "";
-    return `${words[word] ?? word}${unit}`;
-}
-/** The fraction of a subscription usage window consumed (0–1) as a whole-number percent: a
- * `0.64` utilization reads `64`. The one home of the fraction→percent conversion, shared by
- * the status badge, the doctor's hold reason and the event formatter so they render a window's
- * fill identically (the browser dashboard's own window line is embedded client-side and keeps
- * its inline copy). */
-export function utilizationPct(utilization) {
-    return Math.round(utilization * 100);
-}
-/** Order two window entries by the windowEntries rule: status severity, then the reported
- * utilization (a missing reading sorts below any number), then the earlier reset, then the
- * type name. Exported so a list of per-backend blocks can be ordered by their primary entry
- * the same way windowEntries orders one account's windows (part 3a/9). */
-export function compareWindowEntries(a, b) {
-    const rank = (WINDOW_RANK[b.status] ?? 1) - (WINDOW_RANK[a.status] ?? 1);
-    if (rank !== 0)
-        return rank;
-    const util = (b.utilization ?? -1) - (a.utilization ?? -1);
-    if (util !== 0)
-        return util;
-    const reset = (a.resetsAt ?? Number.POSITIVE_INFINITY) - (b.resetsAt ?? Number.POSITIVE_INFINITY);
-    if (reset !== 0)
-        return reset;
-    return a.type.localeCompare(b.type);
-}
-/** The account's windows as a list, most constrained first (by compareWindowEntries). Empty
- * when the account reported none. */
-export function windowEntries(account) {
-    return Object.entries(account.windows)
-        .map(([type, w]) => ({ type, ...w }))
-        .sort((a, b) => compareWindowEntries(a, b));
-}
 /** Read the persisted account state for a backend, or null when it is absent or unreadable. A
  * file without a usable top-level `observedAt` reads as absent (the plan's torn-file rule),
  * and a window whose `resetsAt` is at or before `now` reads back with `status: "reset"` — the
@@ -144,8 +64,7 @@ function readWindow(value, fileObservedAt, now) {
     const resetsAt = finiteNumber(value.resetsAt, Number.NaN);
     const resets = Number.isFinite(resetsAt);
     // utilization heals like the two stamps above: JSON's `1e999` parses to Infinity, and a
-    // non-finite fraction would render as `Infinity%` in the badges and poison the
-    // windowEntries comparator (Infinity - Infinity is NaN).
+    // non-finite fraction would poison any consumer's utilization read.
     const utilization = finiteNumber(value.utilization, undefined);
     const reset = resets && resetsAt <= now;
     const window = {

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

@@ -319,10 +319,9 @@ function archiveCommitWhat(plan) {
 }
 /** One live backlog file's finished-history rows as liveFinishedHistory reports them, phrased
  * and joined: `file ## <section> holds N finished entries (X KB)` rows separated by "; " — the
- * shared detail head the doctor's `backlog archive` check (checkLiveFinished) and the always-on
- * `backlog-archive` alert (src/ui/team-alert-backlog.ts) both render, so the row shape, the
- * plural, and the KB rounding cannot drift between the two. Each caller appends its own trailing
- * explanation, so the two texts stay byte-identical up to that suffix. */
+ * detail head the doctor's `backlog archive` check (checkLiveFinished) renders, so the row
+ * shape, the plural, and the KB rounding stay stable. Each caller appends its own trailing
+ * explanation. */
 export function liveFinishedRowList(rows) {
     return rows.map((l) => `${l.file} ## ${l.section} holds ${plural(l.entries, "finished entry", "finished entries")} (${Math.round(l.bytes / 1024)} KB)`).join("; ");
 }

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

@@ -10,6 +10,12 @@ import { groupBlockedSeries, partsLabel } from "./backlog-index-data.js";
 import { rejectUnknownArgs } from "../cli/cli-flag-specs.js";
 import { refuseTeamWorkspace } from "../cli/cli-repo-gate.js";
 import { sectionNoun, showEntry } from "./backlog-write.js";
+/** `bug --list --done -n` / `plan --list --done -n` ceiling: bounds how many finished
+ * entries one list shows, so a typo'd huge count fails fast with the shared `must be between
+ * 1 and <max>` wording (the logs/history/report pattern) instead of silently meaning
+ * "everything". The finished lists are small (PLANS.md/BUGS.md), so the cap never meaningfully
+ * binds — it exists for the uniform count-flag contract and the clear over-range rebuke. */
+const BACKLOG_MAX_LISTED = 100_000;
 /** Ascending positions as runs: consecutive ones join with an en dash (`13–17`), runs separate
  * with commas (`13–15, 18`). */
 function positionRuns(positions) {
@@ -59,7 +65,7 @@ function parseListArgs(args, command) {
         }
         if (arg === "-n") {
             rejectRepeatFlag(count !== null, "-n");
-            count = parseCountFlag("-n", args[++i]);
+            count = parseCountFlag("-n", args[++i], BACKLOG_MAX_LISTED);
             continue;
         }
         if (arg === "--list") {
@@ -114,10 +120,10 @@ function announceFinishedList(root, fileName, bugSection, grep, count, json) {
     const header = pattern === null ? `${what} in ${fileName}, newest first:` : `${what} in ${fileName} matching "${pattern}", newest first:`;
     say(`${header}\n${lines.join("\n")}`);
 }
-/** The active half of the list shell: the open entries with their holds, in-progress claim
- * marks and age suffixes, optionally reduced to the ready ones, as `--json` or prose, grouping
- * a plan's blocked parts into one line (groupBlockedSeries). */
-function announceActiveList(root, fileName, command, bugSection, sectionTitle, grep, ready, json) {
+/** The active list's read-and-filter phase: reads the section's entries and each position's
+ * hold and live claimer, numbers them unfiltered, keeps the `--grep` matches under those
+ * positions, drops to the `--ready` survivors, counts what `--ready` hid, and names the noun. */
+function activeListView(root, bugSection, sectionTitle, grep, ready) {
     const entries = bugSection ? openBugEntries(root) : plannedPlanEntries(root);
     const holds = backlogHolds(root);
     const entryHolds = bugSection ? holds.bugs : holds.plans;
@@ -128,47 +134,62 @@ function announceActiveList(root, fileName, command, bugSection, sectionTitle, g
     const numbered = entries.map((entry, i) => ({ entry, position: i + 1 }));
     const matches = grep === null ? numbered : numbered.filter((m) => entryMatches(m.entry, grep));
     const kept = ready ? matches.filter((m) => (entryHolds[m.position - 1] ?? null) === null) : matches;
-    const hidden = matches.length - kept.length;
-    if (json) {
-        sayJson({
-            entries: kept.map(({ entry, position }) => {
-                const since = filingDate(entry.title);
-                return {
-                    position,
-                    title: entry.title,
-                    body: entry.body,
-                    hold: entryHolds[position - 1] ?? null,
-                    inProgress: entryRunners[position - 1] ?? null,
-                    // The filing stamp the entry's own heading carries, and how many days it has waited
-                    // since then (both present only when the heading names a stamp — an undated entry
-                    // keeps the pre-existing shape with neither key).
-                    ...(since === null ? {} : { since, ageDays: ageInDays(since) }),
-                };
-            }),
-        });
-        return;
-    }
-    const noun = sectionNoun(sectionTitle);
-    if (grep === null && entries.length === 0) {
-        say(`no ${noun}s`);
-        return;
-    }
-    if (matches.length === 0) {
-        say(`no ${noun}s match "${grep}"`);
-        return;
-    }
-    if (ready && kept.length === 0) {
-        say(`no ${noun}s ready (${hidden} held; run \`tumwater ${command} --list\` to see them)`);
-        return;
-    }
+    return {
+        entries,
+        entryHolds,
+        entryRunners,
+        matches,
+        kept,
+        hidden: matches.length - kept.length,
+        noun: sectionNoun(sectionTitle),
+        grep,
+        ready,
+    };
+}
+/** The `--json` body: each kept entry as its position, title, verbatim body, hold,
+ * in-progress claim and — only when the heading names a filing stamp — its `since`/`ageDays`. */
+function activeListJson(view) {
+    const { kept, entryHolds, entryRunners } = view;
+    return {
+        entries: kept.map(({ entry, position }) => {
+            const since = filingDate(entry.title);
+            return {
+                position,
+                title: entry.title,
+                body: entry.body,
+                hold: entryHolds[position - 1] ?? null,
+                inProgress: entryRunners[position - 1] ?? null,
+                // The filing stamp the entry's own heading carries, and how many days it has waited
+                // since then (both present only when the heading names a stamp — an undated entry
+                // keeps the pre-existing shape with neither key).
+                ...(since === null ? {} : { since, ageDays: ageInDays(since) }),
+            };
+        }),
+    };
+}
+/** The prose `no …` line for an empty list, a `--grep` with no match, or a `--ready` list
+ * whose every match is held; null when `view.kept` has rows to print. */
+function activeListEmptyLine(view, command) {
+    const { entries, matches, kept, hidden, noun, grep, ready } = view;
+    if (grep === null && entries.length === 0)
+        return `no ${noun}s`;
+    if (matches.length === 0)
+        return `no ${noun}s match "${grep}"`;
+    if (ready && kept.length === 0)
+        return `no ${noun}s ready (${hidden} held; run \`tumwater ${command} --list\` to see them)`;
+    return null;
+}
+/** The prose body of a non-empty active list: the bug list's numbered `line` rows, or the
+ * plan list's `groupBlockedSeries` rows, each with the hidden-held notice when `hidden > 0`. */
+function activeListProse(view, fileName, command, bugSection) {
+    const { kept, entryHolds, entryRunners, hidden, noun } = view;
     const hiddenNote = `(${hidden} held entries hidden; run \`tumwater ${command} --list\` to see them)`;
     const line = (entry, i) => `${entry.title}${holdMark(entryHolds[i] ?? null)}${inProgressMark(entryRunners[i] ?? null)}${entryAgeSuffix(entry.title)}`;
     if (bugSection) {
         const bugLines = kept.map(({ entry, position }) => `${position}. ${line(entry, position - 1)}`);
         if (hidden > 0)
             bugLines.push(hiddenNote);
-        say(`${noun}s in ${fileName}:\n${bugLines.join("\n")}`);
-        return;
+        return `${noun}s in ${fileName}:\n${bugLines.join("\n")}`;
     }
     // Plans: a series' blocked parts show as one line naming their positions, as the prompt's
     // backlog index does; numbering is unchanged so --show/--edit/--cancel <n> reach every part.
@@ -189,7 +210,26 @@ function announceActiveList(root, fileName, command, bugSection, sectionTitle, g
         lines.push("(each blocked series is one line; --show <n> prints a part, --json lists every entry)");
     if (hidden > 0)
         lines.push(hiddenNote);
-    say(`${noun}s in ${fileName}:\n${lines.join("\n")}`);
+    return `${noun}s in ${fileName}:\n${lines.join("\n")}`;
+}
+/** The active half of the list shell: the open entries with their holds, in-progress claim
+ * marks and age suffixes, optionally reduced to the ready ones, as `--json` or prose, grouping
+ * a plan's blocked parts into one line (groupBlockedSeries). Orchestrates the four named
+ * phases below — the read-and-filter view (activeListView), the `--json` body (activeListJson),
+ * the empty-list prose line (activeListEmptyLine) and the bug/plan prose body
+ * (activeListProse). */
+function announceActiveList(root, fileName, command, bugSection, sectionTitle, grep, ready, json) {
+    const view = activeListView(root, bugSection, sectionTitle, grep, ready);
+    if (json) {
+        sayJson(activeListJson(view));
+        return;
+    }
+    const empty = activeListEmptyLine(view, command);
+    if (empty !== null) {
+        say(empty);
+        return;
+    }
+    say(activeListProse(view, fileName, command, bugSection));
 }
 /** The shared shell of the `bug --list` and `plan --list` CLI cases — the read half of the
  * operator queue whose `--edit`/`--cancel` flags address entries by position. Reads the same

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

@@ -238,8 +238,35 @@ export async function topAndAnnounce(root, args, command, top) {
  * $VISUAL/$EDITOR and the saved buffer goes through `editText`. A saved buffer, positional or
  * `--file` text that rebuilds the entry byte-for-byte writes and commits nothing (`unchanged
  * <command> <n>: <title>`), and an out-of-range position fails
- * before the editor launches. */
+ * before the editor launches. The flag vocabulary, editor round-trip, unchanged report and
+ * commit-plus-hold announcement each live in their own named helper below. */
 export async function editAndAnnounce(root, args, command, edit, editText) {
+    const { path, json, positionals, position } = parseEditArgs(args, command);
+    await requireReadyRepo(root);
+    let text = null;
+    if (path === null && positionals.length === 0) {
+        const opened = openEditInEditor(root, command, position);
+        if (!opened.changed) {
+            sayUnchangedEdit(command, position, json, opened.file, opened.title);
+            return;
+        }
+        text = opened.text;
+    }
+    else if (path !== null)
+        text = readPromptFileArg(path);
+    const edited = text === null ? edit(position, positionals) : editText(position, text);
+    if (edited.unchanged) {
+        sayUnchangedEdit(command, position, json, edited.file, edited.title);
+        return;
+    }
+    await announceEdited(root, command, position, json, edited);
+}
+/** The flag vocabulary of the `--edit` shell: `--file <path>` is extracted and the repeat
+ * of the flag refused; the remaining tokens go through scanProseFlags (the `--json` boolean
+ * at most once, an `--edit <n>` position required here through scanProseFlags' one valued
+ * flag), and a stray positional alongside `--file` is refused. `fail` returns never, so on
+ * return `position` is a `number`. */
+function parseEditArgs(args, command) {
     const fileFlag = args.indexOf("--file");
     const path = fileFlag >= 0 ? promptFileValue(args[fileFlag + 1]) : null;
     const rest = path === null ? args : args.filter((_, i) => i !== fileFlag && i !== fileFlag + 1);
@@ -253,32 +280,36 @@ export async function editAndAnnounce(root, args, command, edit, editText) {
         rejectStrayWithFile(positionals[0]);
     if (position === null)
         fail(`--edit needs a position (usage: tumwater ${command} --edit <n>)`);
-    await requireReadyRepo(root);
-    const sayUnchanged = (file, title) => {
-        if (json)
-            sayJson({ file, title, changed: false });
-        else
-            say(`unchanged ${command} ${position}: ${title}`);
-    };
-    let text = null;
-    if (path === null && positionals.length === 0) {
-        const shown = showEntry(root, command, position);
-        const before = renderShownEntry(shown);
-        const after = editInEditor(before, `${command}-${position}.md`);
-        if (after.trim() === before.trim()) {
-            const file = command === "bug" ? "BUGS.md" : "PLANS.md";
-            sayUnchanged(file, shown.title);
-            return;
-        }
-        text = after;
-    }
-    else if (path !== null)
-        text = readPromptFileArg(path);
-    const edited = text === null ? edit(position, positionals) : editText(position, text);
-    if (edited.unchanged) {
-        sayUnchanged(edited.file, edited.title);
-        return;
+    return { path, json, positionals, position };
+}
+/** The no-op wording when an edit changes nothing: a `--json` `{ file, title, changed: false }`
+ * payload, else a single `unchanged <command> <n>: <title>` line. */
+function sayUnchangedEdit(command, position, json, file, title) {
+    if (json)
+        sayJson({ file, title, changed: false });
+    else
+        say(`unchanged ${command} ${position}: ${title}`);
+}
+/** The editor round-trip taken when the `--edit` shell has neither `--file` nor positionals:
+ * the entry rendered as `--show` prints it (showEntry/renderShownEntry) opens in
+ * $VISUAL/$EDITOR, and a saved buffer that trims to the same text reports `{ changed: false }`
+ * with the backing file's name and the shown title; otherwise the saved text is returned as
+ * `{ changed: true, text }`. */
+function openEditInEditor(root, command, position) {
+    const shown = showEntry(root, command, position);
+    const before = renderShownEntry(shown);
+    const after = editInEditor(before, `${command}-${position}.md`);
+    if (after.trim() === before.trim()) {
+        return { changed: false, file: command === "bug" ? "BUGS.md" : "PLANS.md", title: shown.title };
     }
+    return { changed: true, text: after };
+}
+/** The commit-and-announce tail of the `--edit` shell: the changed entry is committed through
+ * commitOperatorBacklogEdit with the `Edit <command>: <title>` subject (warned on an
+ * uncommitted worktree), the still-held role from the one before `position` is picked for the
+ * hold report, and the `--json` payload (with `hold` when held) or the prose `edited …` line
+ * plus stillHeldNote is printed. */
+async function announceEdited(root, command, position, json, edited) {
     warnIfUncommitted(await commitOperatorBacklogEdit(root, edited.file, stampedSubject("operator", `Edit ${command}: ${edited.title}`)), edited.file); // vocabulary-ok: the tumwater(operator): commit prefix is a machine string
     const holds = backlogHolds(root);
     const hold = (command === "bug" ? holds.bugs : holds.plans)[position - 1] ?? null;

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

@@ -10,53 +10,21 @@
 import path from "node:path";
 import { statOrNull } from "../files/files.js";
 import { allLiveClaims } from "../runner/runner-state-load.js";
-import { escapeRegExp, firstTrimmedLineStartingWith } from "../text/text.js";
-import { HELD_TAG_PREFIX, NEEDS_REVIEW_PREFIX, PRIOR_HELD_PREFIX } from "../roles/role-guidance.js";
+import { firstTrimmedLineStartingWith } from "../text/text.js";
+import { NEEDS_REVIEW_PREFIX } from "../roles/role-guidance.js";
 import { baseRoleOf } from "../roles/runner-ids.js";
 import { roleLabel } from "../roles/role-labels.js";
 import { actionableEntryRangesFor } from "./backlog-index-data.js";
 import { entryKey, partKey, plannedPartKeys, plansWaitingOn, requiredParts, seriesPart } from "./backlog-parts.js";
 import { finishedFiles, openBugEntries, plannedPlanEntries } from "./backlog.js";
-/** The number of holds an entry's count must reach before a Needs-review note
- * becomes a `held-for-operator` hold (the operator's decision, surfaced by parts 2/3 and 3/3). */
-export const OPERATOR_HOLD_THRESHOLD = 3;
-/** The held count a body records: the integer in the first Needs-review note
- * line's `(held N)` tag, else 0. A present but non-numeric `(held …)` tag is 0 (and stops the
- * scan), so a malformed tag never throws. Pure over the body text — the data-layer read half of
- * the convergence backstop. No writer emits a `(held N)` tag anymore and the `**Previously held
- * N**` markers left on disk are never read, so a freshly written flat note always reads 0 and a
- * new hold never escalates to the operator's desk. */
-export function heldCount(body) {
-    const tagRe = new RegExp(`${escapeRegExp(HELD_TAG_PREFIX)}(\\d+)\\)`);
-    for (const raw of body.split("\n")) {
-        const line = raw.trimStart();
-        const note = line.startsWith(NEEDS_REVIEW_PREFIX);
-        if (!note)
-            continue;
-        const tag = tagRe.exec(line);
-        if (tag !== null)
-            return Number(tag[1]);
-        if (line.includes(HELD_TAG_PREFIX))
-            return 0;
-    }
-    return 0;
-}
-/** The `(held N)` count on a single Needs-review note line, or undefined when the
- * line is not such a note or carries no numeric tag. The per-line form of heldCount, so a writer
- * that drops notes (withoutHeldForOperatorNotes) can gate on the same threshold without scanning
- * the whole body. */
-function lineHeldCount(line) {
-    const trimmed = line.trimStart();
-    const isNote = trimmed.startsWith(NEEDS_REVIEW_PREFIX);
-    if (!isNote)
-        return undefined;
-    const tag = new RegExp(`${escapeRegExp(HELD_TAG_PREFIX)}(\\d+)\\)`).exec(trimmed);
-    return tag === null ? undefined : Number(tag[1]);
-}
 /** The `**Refused …` note prefix a refusing run writes. Every hold note — this one and the
  * imported Needs-review prefix — is matched as a line prefix (hasNoteLine)
  * so a mention in prose never holds an entry. */
 const REFUSED_PREFIX = "**Refused ";
+/** The legacy marker the old increment rule left beside a Needs-review note's prior held count
+ * (`**Previously held N−1**` beside the live `(held N)`), dropped by withoutNeedsReviewNotes so
+ * a release leaves no orphan. No writer emits it anymore; only survives on live notes. */
+const PRIOR_HELD_PREFIX = "**Previously held ";
 /** True when `body` carries a line (ignoring leading indentation) that begins with `prefix`.
  * The one home of the hold-note rule: a note holds its entry only when written as its own
  * line, never when its prefix is quoted inside prose. */
@@ -80,6 +48,24 @@ export function refusalNote(body) {
 export function needsReviewNote(body) {
     return noteText(body, NEEDS_REVIEW_PREFIX);
 }
+/** True when `entry` is parked with the plan role — its Needs-review note is the feature
+ * role's too-large note, the automatic convergence hold, or a final-round rejection, all of
+ * which the plan role clears by splitting or replanning (role-catalog.ts `plan` find). False
+ * for the bugfix role's wait-for-the-next-failure note ("by bugfix: …"), which parks the
+ * entry for selfcheck to lift when the cluster fails again (selfcheck step 4) and which no
+ * role can act on until then. entryHold returns "needs-review" for every such note (all of
+ * them park the entry), so the doctor's `stalled entries` row (checkStalledEntries) — the
+ * stalled-with-the-plan-role surface — classifies by this agreed subset, keeping the bugfix
+ * parks out of the plan-role blame. Reads the note's text after the NEEDS_REVIEW_PREFIX once,
+ * so the row cannot disagree on which notes the plan role clears; the eligibility mark
+ * (holdMark) continues to hold every needs-review note, a by-bugfix park included. */
+export function isPlanStalled(entry) {
+    const note = needsReviewNote(entry.body);
+    if (note === null)
+        return false;
+    // A "by bugfix:" note is a wait for evidence that selfcheck clears, not plan-role work.
+    return !note.includes("by bugfix");
+}
 /** `lines` without any line starting with `prefix` (the same line-prefix rule hasNoteLine
  * applies). When a dropped note sat between two blank lines, the blank line after it goes too,
  * so releasing leaves one blank line where the note was. Every other line is kept. */
@@ -101,33 +87,25 @@ function withoutNoteLines(lines, prefix) {
 export function withoutRefusalNotes(lines) {
     return withoutNoteLines(lines, REFUSED_PREFIX);
 }
-/** `lines` with every Needs-review note whose `(held N)` count reached
- * OPERATOR_HOLD_THRESHOLD removed, together with its `**Previously held N−1**` line (the prior
- * count the increment rule recorded beside the live `(held N)`), so a `--release` lift leaves
- * neither behind and the entry becomes eligible. Drops nothing when no note is at or past the
- * threshold, so release still cannot lift a live first/second Needs-review hold. Consecutive
- * dropped lines are collapsed to one blank line, the same rule withoutNoteLines applies to a
- * single dropped note. */
-export function withoutHeldForOperatorNotes(lines) {
-    const drop = new Set();
-    const priorHeld = new Set();
-    lines.forEach((raw, i) => {
-        const c = lineHeldCount(raw);
-        if (c !== undefined && c >= OPERATOR_HOLD_THRESHOLD) {
-            priorHeld.add(c - 1);
-            drop.add(i);
-        }
-    });
-    if (priorHeld.size === 0)
+/** `lines` without its Needs-review note lines and the legacy `**Previously held N**`
+ * markers the old increment rule left beside them, the release's lift when the entry has no
+ * Refused note: a `--release` that finds no Refused note drops every Needs-review note line so
+ * the entry becomes eligible, and takes each `**Previously held N**` marker in the slice with
+ * it, so the lift leaves no orphan whether or not the note still carries a `(held N)` tag.
+ * Nothing changes when the slice carries no Needs-review note, so a marker that sits on an
+ * eligible entry stays put. Every other line, Refused notes included, is kept, so the
+ * Needs-review lift never lifts a refusal. */
+export function withoutNeedsReviewNotes(lines) {
+    // A lift only happens when the slice carries a Needs-review note; without one, the slice
+    // (and any legacy prior-held marker on it) is left byte for byte.
+    if (!lines.some((raw) => raw.trimStart().startsWith(NEEDS_REVIEW_PREFIX)))
         return lines;
+    const drop = new Set();
     lines.forEach((raw, i) => {
-        if (drop.has(i))
-            return;
         const trimmed = raw.trimStart();
-        if (!trimmed.startsWith(PRIOR_HELD_PREFIX))
-            return;
-        const count = /\d+/.exec(trimmed.slice(PRIOR_HELD_PREFIX.length));
-        if (count !== null && priorHeld.has(Number(count[0])))
+        // Every Needs-review note goes, and so does each `**Previously held N**` marker the old
+        // increment rule wrote with it.
+        if (trimmed.startsWith(NEEDS_REVIEW_PREFIX) || trimmed.startsWith(PRIOR_HELD_PREFIX))
             drop.add(i);
     });
     const out = [];
@@ -140,7 +118,7 @@ export function withoutHeldForOperatorNotes(lines) {
         while (j < lines.length && drop.has(j))
             j++;
         // A dropped run between two blank lines drops the blank after it too, so the lift leaves
-        // one blank line where the note was (the same rule withoutNoteLines applies to one).
+        // one blank line where the note was (the same rule withoutNoteLines applies to one note).
         if (j < lines.length && (lines[i - 1] ?? "x").trim() === "" && (lines[j] ?? "x").trim() === "")
             j++;
         i = j - 1;
@@ -209,13 +187,10 @@ export function entryHold(entry, planned) {
 export function entryHoldAgainst(entry, plannedParts) {
     if (hasNoteLine(entry.body, REFUSED_PREFIX))
         return "refused";
-    if (hasNoteLine(entry.body, NEEDS_REVIEW_PREFIX)) {
-        // A note whose held count reached OPERATOR_HOLD_THRESHOLD stops out of the role loop:
-        // neither the plan role (planBacklogFull) nor this role takes it.
-        return heldCount(entry.body) >= OPERATOR_HOLD_THRESHOLD
-            ? "held-for-operator" // vocabulary-ok: the operator-held string names the operator hold decision
-            : "needs-review";
-    }
+    // A Needs-review note — the feature role's too-large note or the convergence hold's — parks the
+    // entry for the plan role to split or replan, at any count: nothing escalates to the operator.
+    if (hasNoteLine(entry.body, NEEDS_REVIEW_PREFIX))
+        return "needs-review";
     const refs = requiredParts(entry.title);
     if (refs.length === 0)
         return null;
@@ -235,8 +210,6 @@ export function holdMark(hold) {
         return " [blocked: refused]";
     if (hold === "needs-review")
         return " [blocked: needs review]";
-    if (hold === "held-for-operator")
-        return " [blocked: held for operator]"; // vocabulary-ok: this hold names the operator-held wording for the operator decision
     return ` [blocked: requires ${hold.blockedBy.join(", ")}]`;
 }
 /** The line `plan|bug --release` and `--top` print when the entry they touched is still held:
@@ -305,67 +278,28 @@ export function backlogHolds(root) {
  * `tumwater backlog` prints. A surface derives its marks from the one hold decision and the
  * one claim lookup rather than re-walking the entries. An eligible entry nobody is working on
  * renders as the empty string, so a client can append the mark without a separate check.
- * Questions carry no holds. backlogHolds alone still drives the allocator. */
-export function backlogMarks(root) {
+ * Questions carry no holds. backlogHolds alone still drives the allocator. A caller that
+ * already resolved the claim lookup (for the same poll's marks AND its own parallel checks,
+ * e.g. statusPayload's `working` or the TUI's `runners`) passes it as `working` so the claims
+ * walk is done once, not re-run inside both calls — the same shared single read the module's
+ * other single-home polls observe. */
+export function backlogMarks(root, working) {
     const holds = backlogHolds(root);
-    const working = backlogInProgress(root);
+    const inProgress = working ?? backlogInProgress(root);
     const mark = (hold, runner) => holdMark(hold) + inProgressMark(runner ?? null);
     return {
-        plans: holds.plans.map((h, i) => mark(h, working.plans[i])),
-        bugs: holds.bugs.map((h, i) => mark(h, working.bugs[i])),
-    };
-}
-/** A planned plan or open bug whose hold is `"held-for-operator"`, in file order: the
- * entries parked until the operator lifts them with `tumwater plan --release` or `tumwater
- * bug --release` (the `operator-held` team alert's input), each carrying the backlog file
- * and its 0-based position so a surface opening the row can land on it, the same RefusedEntry
- * shape refusedEntries returns. The convergence hold writes only on plans, but a role's own
- * too-large note can sit on a bug and reach this threshold, so a bug can be held this way too.
- * A missing file yields `[]`. */
-export function operatorHeldEntries(root) {
-    const holds = backlogHolds(root);
-    const out = [];
-    const entriesOf = (entries, held, file) => {
-        entries.forEach((e, i) => {
-            if (held[i] === "held-for-operator")
-                out.push({ file, index: i, title: e.title }); // vocabulary-ok: the held-for-operator hold's key
-        });
+        plans: holds.plans.map((h, i) => mark(h, inProgress.plans[i])),
+        bugs: holds.bugs.map((h, i) => mark(h, inProgress.bugs[i])),
     };
-    entriesOf(plannedPlanEntries(root), holds.plans, "plans");
-    entriesOf(openBugEntries(root), holds.bugs, "bugs");
-    return out;
 }
 /** The display noun for a backlog-file discriminator — the `"plans" | "bugs"` `file` on
- * RefusedEntry and StalledEntry (and the same discriminator the prompt's named-hold wording
+ * RefusedEntry (and the same discriminator the prompt's named-hold wording
  * and the doctor's Stalled row take): BUGS.md is a "Bug" and PLANS.md a "Plan", and the
  * lowercase form is the `Refused plan|bug:` label and the `tumwater plan|bug --release`
- * command noun the operator-held alert body interpolates. */
+ * command noun. */
 export function entryKindLabel(file) {
     return file === "bugs" ? "Bug" : "Plan";
 }
-/** The planned plans and open bugs whose hold is exactly `"needs-review"`, in file order: the
- * entries parked by a Needs-review note until the plan role splits or replans them (the
- * `stalled-entries` team alert's input), each carrying its backlog file, 0-based index and the
- * hold. Same `backlogHolds(root)` + the planned/`openBugEntries` readers `operatorHeldEntries`
- * uses, so the alert and the doctor's `stalled entries` row classify through the same
- * `entryHold` and cannot disagree on which holds are role-resolvable. A held-for-operator
- * entry (a note at the held threshold) is
- * excluded — it feeds `operatorHeldEntries` and the `operator-held` alert instead. A missing
- * file yields `[]`. */
-export function stalledEntries(root) {
-    const holds = backlogHolds(root);
-    const out = [];
-    const entriesOf = (entries, held, file) => {
-        entries.forEach((e, i) => {
-            const hold = held[i];
-            if (hold === "needs-review")
-                out.push({ file, index: i, title: e.title, hold });
-        });
-    };
-    entriesOf(plannedPlanEntries(root), holds.plans, "plans");
-    entriesOf(openBugEntries(root), holds.bugs, "bugs");
-    return out;
-}
 /** The planned plans, then the open bugs, whose hold is `"refused"`, in file order: the
  * entries that wait on an operator decision (the `refused` team alert's input), each carrying
  * the backlog file and its 0-based position so a surface opening the row can land on it.