tumwater 0.2.0 → 0.3.0

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

@@ -1,24 +1,64 @@
-// vocabulary: plain
-/** Backlog eligibility: which PLANS.md / BUGS.md entries a work loop may take now (plans,
+/** Backlog eligibility: which PLANS.md / BUGS.md entries a work role may take now (plans,
  * parallel-work-instances, part 2/7). An entry is held when its body carries a **Refused …**,
  * **Needs review …**, **Needs replan …** or **Waiting for the next failure …** note, or when
  * its heading's trailing parenthetical
  * (or a parenthetical left open by a wrapped heading) names a prerequisite (`requires parts
  * 1/5–3/5 landed`) that is itself still listed under `## Planned`. The parsers are pure over
  * markdown text; `eligibleEntries` is the stat-backed reader for a caller that wants the list.
- * The backlog index marks every held entry so a loop
+ * The backlog index marks every held entry so a role
  * skips it without re-deriving the rule. */
 import path from "node:path";
 import { statOrNull } from "../files/files.js";
-import { allLiveClaims } from "../loop/loop-state.js";
-import { collapseWhitespace } from "../text/text.js";
-import { NEEDS_REPLAN_PREFIX, NEEDS_REVIEW_PREFIX, WAITING_FOR_FAILURE_PREFIX } from "../roles/role-guidance.js";
-import { baseRoleOf } from "../roles/loop-ids.js";
+import { allLiveClaims } from "../runner/runner-state-load.js";
+import { firstTrimmedLineStartingWith } from "../text/text.js";
+import { HELD_TAG_PREFIX, NEEDS_REPLAN_PREFIX, NEEDS_REVIEW_PREFIX, PRIOR_HELD_PREFIX, WAITING_FOR_FAILURE_PREFIX } from "../roles/role-guidance.js";
+import { baseRoleOf } from "../roles/runner-ids.js";
 import { roleLabel } from "../roles/role-labels.js";
-import { openParenthetical, trailingParenthetical } from "./backlog-md.js";
-import { actionableEntryRangesFor, stripEntryStamp } from "./backlog-structure.js";
+import { actionableEntryRangesFor } from "./backlog-structure.js";
+import { entryKey, partKey, plannedPartKeys, plansWaitingOn, requiredParts, seriesPart } from "./backlog-parts.js";
 import { finishedFiles, openBugEntries, plannedPlanEntries } from "./backlog.js";
-/** The `**Refused …` note prefix a refusing tick writes. Every hold note — this one and the
+/** The number of holds an entry's count must reach before a Needs-review/Needs-replan 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 or Needs-replan note
+ * line's `(held N)` tag, else the integer in a `**Previously held N**` line, 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. */
+export function heldCount(body) {
+    const tagRe = new RegExp(`${HELD_TAG_PREFIX.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}(\\d+)\\)`);
+    for (const raw of body.split("\n")) {
+        const line = raw.trimStart();
+        const note = line.startsWith(NEEDS_REVIEW_PREFIX) || line.startsWith(NEEDS_REPLAN_PREFIX);
+        if (!note)
+            continue;
+        const tag = tagRe.exec(line);
+        if (tag !== null)
+            return Number(tag[1]);
+        if (line.includes(HELD_TAG_PREFIX))
+            return 0;
+    }
+    for (const raw of body.split("\n")) {
+        const line = raw.trimStart();
+        if (!line.startsWith(PRIOR_HELD_PREFIX))
+            continue;
+        const count = /\d+/.exec(line.slice(PRIOR_HELD_PREFIX.length));
+        return count === null ? 0 : Number(count[0]);
+    }
+    return 0;
+}
+/** The `(held N)` count on a single Needs-review or Needs-replan 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) || trimmed.startsWith(NEEDS_REPLAN_PREFIX);
+    if (!isNote)
+        return undefined;
+    const tag = new RegExp(`${HELD_TAG_PREFIX.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}(\\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 and Needs-replan prefixes — is matched as a line prefix (hasNoteLine)
  * so a mention in prose never holds an entry. */
 const REFUSED_PREFIX = "**Refused ";
@@ -32,7 +72,7 @@ function hasNoteLine(body, prefix) {
  * begins with it, trimmed, with the leading `**` and the first closing `**` removed. Null when
  * no line matches — the same line-prefix rule entryHold uses. */
 function noteText(body, prefix) {
-    const line = body.split("\n").map((l) => l.trim()).find((l) => l.startsWith(prefix));
+    const line = firstTrimmedLineStartingWith(body, prefix);
     return line === undefined ? null : line.replace(/^\*\*/, "").replace("**", "");
 }
 /** The text of `body`'s Refused note, or null when it has none (entryHold's "refused" hold). */
@@ -69,53 +109,51 @@ export function withoutRefusalNotes(lines) {
 export function withoutWaitingNotes(lines) {
     return withoutNoteLines(lines, WAITING_FOR_FAILURE_PREFIX);
 }
-/** One prerequisite ref, resolved against the entry's own series when it names none. */
-function parseRef(chunk, ownSeries) {
-    const text = chunk.trim().replace(/^parts?\s+/i, "");
-    if (text === "")
-        return [];
-    const m = /^(?:([\s\S]+?)\s+)?([0-9]+[a-z]?)\/(\d+)(?:\s*[–-]\s*(\d+)\/(\d+))?$/i.exec(text);
-    if (m === null)
-        return [];
-    const series = (m[1]?.trim() ?? "") || ownSeries;
-    if (series === null || series === "")
-        return [];
-    const of = Number(m[3]);
-    const start = m[2].toLowerCase();
-    if (!Number.isInteger(of) || of < 1)
-        return [];
-    if (m[4] === undefined)
-        return [{ series, part: start, of }];
-    // A range is numeric on both ends (the lettered parts never range); expand it inclusively.
-    const from = Number(start);
-    const to = Number(m[4]);
-    if (!Number.isInteger(from) || !Number.isInteger(to) || to < from)
-        return [];
-    const parts = [];
-    for (let p = from; p <= to; p++)
-        parts.push({ series, part: String(p), of });
-    return parts;
-}
-/** The stable identity of an entry heading: its `(planned …)`/`(done …)` stamp suffix
- * removed through the shared stripEntryStamp, whitespace collapsed, lowercased. Adding a
- * done stamp or a Refused note therefore leaves the key unchanged. */
-export function entryKey(title) {
-    return collapseWhitespace(stripEntryStamp(title)).toLowerCase();
-}
-/** An entry's own series and part from its heading, or null when the heading is not a
- * `<Series>, part i/n: …` title. The series is the text before `, part i/n:`. */
-export function seriesPart(title) {
-    const m = /^(.+?),\s*part\s+([0-9]+[a-z]?)\/(\d+)\s*:/i.exec(stripEntryStamp(title));
-    if (m === null)
-        return null;
-    const series = m[1].trim();
-    if (series === "")
-        return null;
-    return { series, part: m[2].toLowerCase(), of: Number(m[3]) };
-}
-/** The one identity a PartRef matches by: lowercased series, verbatim part token. */
-function partKey(series, part) {
-    return `${series.toLowerCase()}\u0000${part}`;
+/** `lines` with every Needs-review/Needs-replan 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)
+        return lines;
+    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])))
+            drop.add(i);
+    });
+    const out = [];
+    for (let i = 0; i < lines.length; i++) {
+        if (!drop.has(i)) {
+            out.push(lines[i]);
+            continue;
+        }
+        let j = i;
+        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).
+        if (j < lines.length && (lines[i - 1] ?? "x").trim() === "" && (lines[j] ?? "x").trim() === "")
+            j++;
+        i = j - 1;
+    }
+    return out;
 }
 /** The Done entries of the parts `title` requires, in the order its requires clause names them:
  * for each requiredParts ref, the first `## Done` entry whose seriesPart has the same partKey,
@@ -164,178 +202,9 @@ export function waitingPartRanges(root, title) {
     }
     return out;
 }
-/** The prerequisite-set identities of the still-planned entries — seriesPart(title) of each,
- * keyed by partKey — built once for a batch and reused across every entry judged against it, so
- * judging n entries is n seriesPart parses rather than n² (entryHold rebuilt the set per entry).
- * Series compare case-insensitively and part tokens verbatim, exactly as entryHoldAgainst
- * matches them. */
-export function plannedPartKeys(planned) {
-    const keys = new Set();
-    for (const p of planned) {
-        const part = seriesPart(p.title);
-        if (part !== null)
-            keys.add(partKey(part.series, part.part));
-    }
-    return keys;
-}
-/** The doctor's count of a refusal's stranded dependents: the ascending indexes into `planned` of
- * the entries that require `planned[index]`'s own part, directly or through a chain of parts.
- * Matching is by partKey, as entryHoldAgainst matches. [] when that entry has no series part. A
- * dependency cycle ends the walk, and `index` itself is never listed. */
-export function plansWaitingOn(planned, index) {
-    const root = planned[index];
-    const own = root === undefined ? null : seriesPart(root.title);
-    if (own === null)
-        return [];
-    const dependents = new Map();
-    planned.forEach((entry, i) => {
-        if (seriesPart(entry.title) === null)
-            return;
-        for (const ref of requiredParts(entry.title)) {
-            const key = partKey(ref.series, ref.part);
-            dependents.set(key, [...(dependents.get(key) ?? []), i]);
-        }
-    });
-    const seen = new Set([index]);
-    const queue = [partKey(own.series, own.part)];
-    for (let key = queue.shift(); key !== undefined; key = queue.shift()) {
-        for (const i of dependents.get(key) ?? []) {
-            if (seen.has(i))
-                continue;
-            seen.add(i);
-            const part = seriesPart(planned[i].title);
-            queue.push(partKey(part.series, part.part));
-        }
-    }
-    seen.delete(index);
-    return [...seen].sort((a, b) => a - b);
-}
-/** The prerequisite parts a plan heading's trailing parenthetical (or, when the heading wraps
- * and the parenthetical stays open past the line, its open parenthetical) names through the clause
- * `requires <ref>((, | and )<ref>)* landed`, with each range (e.g. `parts 1/5–3/5`) expanded.
- * Returns [] when the heading has no such clause or the clause does not parse — an agent judges
- * an unparseable clause, exactly as it does today. Only the heading is read, never the body. */
-export function requiredParts(title) {
-    const clause = requiresClause(title);
-    if (clause === null)
-        return [];
-    const ownSeries = seriesPart(title)?.series ?? null;
-    const refs = [];
-    for (const chunk of clause.split(/\s*,\s*|\s+and\s+/i))
-        refs.push(...parseRef(chunk, ownSeries));
-    return refs;
-}
-/** The ref text a heading's `requires <refs> landed` clause captures — read from the trailing
- * parenthetical, or the open one of a wrapped heading — or null when the heading has no such
- * clause. requiredParts parses it; planDependencyProblems uses it to spot a clause that parses to
- * nothing. */
-function requiresClause(title) {
-    let meta = trailingParenthetical(title);
-    if (meta === "")
-        meta = openParenthetical(title);
-    if (meta === "")
-        return null;
-    const m = /requires\s+(.+?)\s+landed\b/i.exec(meta); // vocabulary-ok: parses the requires … landed heading syntax
-    return m === null ? null : m[1];
-}
-/** A dependency verb followed by a series part ref in a heading's parenthetical — the wording the
- * claim allocator ignores (BUGS.md 2026-10-14: a part headed "blocked by part 1/2 above" was handed
- * out six times while part 1/2 was in flight). planDependencyProblems reports each such ref. */
-const MISWORDED_DEPENDENCY_RE = /\b(?:blocked by|blocked on|after|follows|depends on|waits on|waits for|once)\s+(?:the\s+)?(parts?\s+[0-9]+[a-z]?\/[0-9]+)/gi;
-/** The mistakes in the planned entries' `requires … landed` clauses that the claim allocator
- * cannot see: `dangling` — a ref naming a part no planned or done heading carries (its hold is
- * void), `unparsed` — titles whose clause yields no refs, and `cycle` — the first dependency cycle
- * among planned `Series, part i/n:` entries as `Series i/n` names in walk order, first name
- * repeated last (a self-reference is a one-hop cycle), or null — and `misworded`: a series part
- * whose heading parenthetical names a still-planned part through a dependency verb ("blocked by
- * part 1/2") with no requires clause holding that part, so the allocator hands it out now.
- * Refused and needs-review entries count like the rest, since their clauses still decide when
- * they unblock. */
-export function planDependencyProblems(planned, doneTitles) {
-    const known = plannedPartKeys(planned);
-    for (const t of doneTitles) {
-        const part = seriesPart(t);
-        if (part !== null)
-            known.add(partKey(part.series, part.part));
-    }
-    const dangling = [];
-    const unparsed = [];
-    const misworded = [];
-    const plannedKeys = plannedPartKeys(planned);
-    const nodes = new Map();
-    for (const entry of planned) {
-        const refs = requiredParts(entry.title);
-        if (refs.length === 0 && requiresClause(entry.title) !== null)
-            unparsed.push(entry.title);
-        for (const ref of refs) {
-            if (!known.has(partKey(ref.series, ref.part)))
-                dangling.push({ title: entry.title, ref: `${ref.series} ${ref.part}/${ref.of}` });
-        }
-        const own = seriesPart(entry.title);
-        if (own === null)
-            continue;
-        let meta = trailingParenthetical(entry.title);
-        if (meta === "")
-            meta = openParenthetical(entry.title);
-        const held = new Set(refs.map((ref) => partKey(ref.series, ref.part)));
-        for (const m of meta.matchAll(MISWORDED_DEPENDENCY_RE)) {
-            for (const ref of parseRef(m[1], own.series)) {
-                const key = partKey(ref.series, ref.part);
-                if (!plannedKeys.has(key) || held.has(key))
-                    continue;
-                const name = `${ref.series} ${ref.part}/${ref.of}`;
-                if (!misworded.some((w) => w.title === entry.title && w.ref === name))
-                    misworded.push({ title: entry.title, ref: name });
-            }
-        }
-        nodes.set(partKey(own.series, own.part), {
-            name: `${own.series} ${own.part}/${own.of}`,
-            deps: refs.map((ref) => partKey(ref.series, ref.part)),
-        });
-    }
-    const state = new Map();
-    const stack = [];
-    const visit = (key) => {
-        state.set(key, "open");
-        stack.push(key);
-        for (const dep of nodes.get(key).deps) {
-            if (!nodes.has(dep))
-                continue;
-            const seen = state.get(dep);
-            if (seen === "open") {
-                return [...stack.slice(stack.indexOf(dep)), dep].map((k) => nodes.get(k).name);
-            }
-            if (seen === undefined) {
-                const found = visit(dep);
-                if (found !== null)
-                    return found;
-            }
-        }
-        stack.pop();
-        state.set(key, "done");
-        return null;
-    };
-    let cycle = null;
-    for (const key of nodes.keys()) {
-        if (state.has(key))
-            continue;
-        cycle = visit(key);
-        if (cycle !== null)
-            break;
-    }
-    return { cycle, dangling, unparsed, misworded };
-}
-/** The prerequisite refs of `title`'s `requires … landed` clause when none of them is still in
- * `plannedParts` (built by plannedPartKeys), else []. A heading with no parseable clause is never
- * reported, so only a refusal whose named prerequisites have all left `## Planned` reads as
- * possibly stale. */
-export function prerequisitesMerged(title, plannedParts) {
-    const refs = requiredParts(title);
-    return refs.some((ref) => plannedParts.has(partKey(ref.series, ref.part))) ? [] : refs;
-}
 /** Why `entry` is held against the still-`planned` entries, or null when it may be taken: a
  * `**Refused …` line (refused), a Needs-review line (needs-review), a Needs-replan line
- * (needs-replan — the plan loop owns it), or a prerequisite `(series, part)` still among
+ * (needs-replan — the plan role owns it), or a prerequisite `(series, part)` still among
  * `planned` ({ blockedBy }). Series compare case-insensitively; part tokens compare verbatim.
  * Bodies mentioning "requires" are never consulted — only the heading's trailing or
  * still-open parenthetical. */
@@ -348,10 +217,15 @@ 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))
-        return "needs-review";
-    if (hasNoteLine(entry.body, NEEDS_REPLAN_PREFIX))
-        return "needs-replan";
+    if (hasNoteLine(entry.body, NEEDS_REVIEW_PREFIX) || hasNoteLine(entry.body, NEEDS_REPLAN_PREFIX)) {
+        // A note whose held count reached OPERATOR_HOLD_THRESHOLD stops out of the role loop:
+        // neither the plan role (planBacklogFull tests only these two) 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
+            : hasNoteLine(entry.body, NEEDS_REVIEW_PREFIX)
+                ? "needs-review"
+                : "needs-replan";
+    }
     if (hasNoteLine(entry.body, WAITING_FOR_FAILURE_PREFIX))
         return "waiting-for-failure";
     const refs = requiredParts(entry.title);
@@ -375,12 +249,22 @@ export function holdMark(hold) {
         return " [blocked: needs review]";
     if (hold === "needs-replan")
         return " [blocked: needs replan]";
+    if (hold === "held-for-operator")
+        return " [blocked: held for operator]"; // vocabulary-ok: this hold names the operator-held wording for the operator decision
     if (hold === "waiting-for-failure")
         return " [blocked: waiting for the next failure]";
     return ` [blocked: requires ${hold.blockedBy.join(", ")}]`;
 }
+/** The line `plan|bug --release` and `--top` print when the entry they touched is still held:
+ * empty for no hold, else the hold in holdMark wording and that no role takes the entry until it
+ * clears. */
+export function stillHeldNote(hold) {
+    if (hold === null)
+        return "";
+    return `still held ${holdMark(hold).trim()}: no role takes it until that clears`;
+}
 /** `/api/status` polls the holds on the 1-second dashboard poll and the TUI recomputes them each
- * frame while PLANS.md/BUGS.md change only when a loop merges an edit. The file reads beneath are
+ * frame while PLANS.md/BUGS.md change only when a role merges an edit. The file reads beneath are
  * already stat-cached (plannedPlanEntries/openBugEntries), but the per-entry eligibility walk
  * (entryHoldAgainst's body scan + heading clause) is pure CPU re-derived on every call, growing
  * with the append-only backlog. Cache the derived holds keyed on both files' stat identities — the
@@ -447,16 +331,57 @@ export function backlogMarks(root) {
         bugs: holds.bugs.map((h, i) => mark(h, working.bugs[i])),
     };
 }
-/** The verbatim titles of 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). Pairs backlogHolds' arrays with the entries the same readers return, like
+/** The planned plans whose hold is `"held-for-operator"`, in file order: the plans parked
+ * until the operator lifts them with `tumwater plan --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. Only
+ * plans — Needs-review/Needs-replan notes are a plan note, so a bug is never held this way.
+ * A missing file yields `[]`. */
+export function operatorHeldEntries(root) {
+    const holds = backlogHolds(root);
+    const out = [];
+    plannedPlanEntries(root).forEach((e, i) => {
+        if (holds.plans[i] === "held-for-operator")
+            out.push({ file: "plans", index: i, title: e.title }); // vocabulary-ok: the held-for-operator hold's key
+    });
+    return out;
+}
+/** The planned plans whose hold is exactly `"needs-review"` or `"needs-replan"`, in file
+ * order: the plans parked by a Needs-review/Needs-replan note until the plan role splits or
+ * replans them (the `stalled-plans` team alert's input), each carrying the 0-based PLANS.md
+ * index and the hold. Same `backlogHolds(root)` + `plannedPlanEntries(root)` pair
+ * `operatorHeldEntries` uses, so the alert and the doctor's `stalled plans` row classify
+ * through the same `entryHold` and cannot disagree on which holds are role-resolvable. A
+ * held-for-operator plan (a note at the held threshold) is excluded — it feeds
+ * `operatorHeldEntries` and the `operator-held` alert instead. A missing file yields `[]`. */
+export function stalledPlanEntries(root) {
+    const holds = backlogHolds(root);
+    const out = [];
+    plannedPlanEntries(root).forEach((e, i) => {
+        const hold = holds.plans[i];
+        if (hold === "needs-review" || hold === "needs-replan")
+            out.push({ index: i, title: e.title, hold });
+    });
+    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.
+ * Pairs backlogHolds' arrays with the entries the same readers return, like
  * backlogInProgress. A missing file yields `[]`. */
-export function refusedEntryTitles(root) {
+export function refusedEntries(root) {
     const holds = backlogHolds(root);
-    const titlesOf = (entries, held) => entries.filter((_, i) => held[i] === "refused").map((e) => e.title);
+    const entriesOf = (entries, held, file) => {
+        const out = [];
+        entries.forEach((e, i) => {
+            if (held[i] === "refused")
+                out.push({ file, index: i, title: e.title });
+        });
+        return out;
+    };
     return [
-        ...titlesOf(plannedPlanEntries(root), holds.plans),
-        ...titlesOf(openBugEntries(root), holds.bugs),
+        ...entriesOf(plannedPlanEntries(root), holds.plans, "plans"),
+        ...entriesOf(openBugEntries(root), holds.bugs, "bugs"),
     ];
 }
 /** The runner id holding a live claim on each planned plan and open bug, two arrays parallel
@@ -475,7 +400,15 @@ export function backlogInProgress(root) {
 export function inProgressMark(runner) {
     return runner === null ? "" : ` [working on it: ${roleLabel(runner)}]`;
 }
-/** The entries a `role` loop may take now, in file order: PLANS.md's `## Planned` entries for
+/** The note a cancel surface adds when the cancelled entry was claimed: empty for `null`, else
+ * names the role (through roleLabel) and the `abort` that stops its run, which the cancel itself
+ * leaves going. */
+export function cancelledClaimNote(runner) {
+    return runner === null
+        ? ""
+        : `${roleLabel(runner)} is still working on it — its run goes on; \`tumwater abort --role ${runner}\` stops it`;
+}
+/** The entries `role` may take now, in file order: PLANS.md's `## Planned` entries for
  * feature, BUGS.md's `## Open` entries for bugfix, minus every entry entryHold holds, each with
  * its stamp-free key, verbatim title and 1-based line range. Reads the primary checkout through
  * the same stat-cached readers the index uses; a missing or unreadable file yields []. */
@@ -491,7 +424,7 @@ export function eligibleEntries(root, role) {
     const parts = plannedPartKeys(planned);
     // The cross-role in-flight hold (BUGS.md 2026-10-09): an entry another role's base has
     // claimed is not eligible here. Same-base claims are excluded from the hold — the scheduling
-    // pass's claim groups and tick-stage's staged claims already hold those — so the queried
+    // pass's claim groups and run-stage's staged claims already hold those — so the queried
     // role's own claim (and a sibling instance's) stays eligible and its release rules are
     // unchanged; only a plan another base currently owns is taken off this base's hands.
     const ownBase = baseRoleOf(role);

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

@@ -0,0 +1,149 @@
+/** Renders the `<backlog-index>` prompt block every role prompt carries — each actionable
+ * entry (PLANS.md ## Planned, BUGS.md ## Open, QUESTIONS.md ## Open) plus the newest closed
+ * ones, each with the 1-based line range it occupies in its file — the bounded replacement for
+ * the per-run `grep -n '^##'` heading map. The entry-range parsing (actionableEntryRanges) and
+ * series collapsing (groupBlockedSeries, partsLabel) it builds on live in backlog-structure.ts
+ * alongside the stranded-plan checks; this module holds only the block's rendering and its
+ * per-file stat caches. Extracted from backlog-structure.ts (organized 2026-10-19) so that
+ * module no longer carries a second responsibility. */
+import path from "node:path";
+import { cachedTextByStat } from "../files/stat-cache.js";
+import { FINISHED_ARCHIVES } from "./backlog-md.js";
+import { allLiveClaims } from "../runner/runner-state-load.js";
+import { collapseWhitespace, truncate } from "../text/text.js";
+import { actionableEntryRanges, groupBlockedSeries, partsLabel, stripEntryStamp, } from "./backlog-structure.js";
+import { entryHoldAgainst, holdMark } from "./backlog-eligibility.js";
+import { plannedPartKeys } from "./backlog-parts.js";
+import { plannedPlanEntries } from "./backlog.js";
+/** Max characters an index title keeps before a trailing ellipsis, so one very long BUGS.md
+ * heading cannot dominate the block. */
+const INDEX_TITLE_MAX = 160;
+/** The index title for a `### ` heading: its stamp suffix (`(reported … 2026-…)`) removed via
+ * the shared stripEntryStamp and whitespace collapsed, then clipped to INDEX_TITLE_MAX
+ * through text.ts's truncate — the one ellipsis rule, so the cut cannot drift from the
+ * other trimmed labels and never splits a surrogate pair. */
+function indexTitle(heading) {
+    return truncate(collapseWhitespace(stripEntryStamp(heading)), INDEX_TITLE_MAX);
+}
+/** The files and sections the actionable index covers, in the order roles read them: PLANS.md's
+ * planned features, BUGS.md's open bugs, QUESTIONS.md's open questions. */
+const INDEX_SECTIONS = [
+    { file: "PLANS.md", section: "Planned" },
+    { file: "BUGS.md", section: "Open" },
+    { file: "QUESTIONS.md", section: "Open" },
+];
+/** How many closed entries per closed section the index lists. */
+const RECENT_CLOSED_MAX = 5;
+/** The closed sections whose newest entries the index also lists, each read from the live file
+ * and then its archive (FINISHED_ARCHIVES, plans/backlog-archive.md); every one keeps its entries
+ * newest first, so the first entries in file order are the recent ones. */
+const CLOSED_SECTIONS = FINISHED_ARCHIVES.map((a) => ({
+    files: [a.file, a.archive],
+    section: a.section,
+}));
+/** Per-file cache of the parsed actionable entries (indexSectionCache). */
+const indexSectionCache = new Map();
+/** Per-file cache of the newest closed entries' ranges; separate from indexSectionCache, which is
+ * keyed by the file path alone and PLANS.md would collide. */
+const closedSectionCache = new Map();
+/** One `IndexRow` as an ordinary index line: range, truncated stamp-free title, hold mark, and
+ * the in-flight suffix when a live claim names it. The collapsed-series line is built by
+ * collapseBlockedSeries, returned alongside these. */
+function renderIndexRow(row) {
+    return `- ${row.start}-${row.end}: ${indexTitle(row.title)}${row.mark}${row.claimer ? ` [in flight by ${row.claimer}]` : ""}`;
+}
+function collapseBlockedSeries(rows) {
+    return groupBlockedSeries(rows).map((g) => {
+        if (g.kind === "row")
+            return renderIndexRow(g.row);
+        const first = g.rows[0];
+        const last = g.rows[g.rows.length - 1];
+        return (`- ${first.start}-${last.end}: ${indexTitle(g.series)}, ${g.rows.length} blocked parts ` +
+            `(${partsLabel(g.rows)}) [blocked: each waits on an earlier part]`);
+    });
+}
+/** The `<backlog-index>` prompt block: each actionable entry (PLANS.md ## Planned, BUGS.md
+ * ## Open, QUESTIONS.md ## Open) with its 1-based line range, rendered from the primary
+ * checkout `root`. Replaces the per-run `grep -n '^##'` heading map, whose pattern also matched
+ * every `###` title in BUGS.md's closed history and so re-sent ~108 KB on every turn (BUGS.md
+ * 2026-10-06). A missing or unreadable file contributes no sections; undefined when no section
+ * has entries, so an empty backlog leaves the prompt unchanged. The per-file actionable entries
+ * are stat-cached (indexSectionCache), so an unchanged backlog file is not re-read or re-walked. */
+export function renderBacklogIndexBlock(root) {
+    // The still-planned set every section's holds are judged against. A prerequisite clause rides
+    // in the entry heading, and the eligibility gate (backlog-eligibility.ts's eligibleEntries)
+    // and `tumwater backlog`'s holds read it for BUGS.md's Open entries too, so the same set must
+    // reach this block's Open section as well — otherwise a held bug reads as eligible here while
+    // the gate skips it. plannedPlanEntries is stat-cached by sectionEntries, so an unchanged
+    // PLANS.md costs one stat per call.
+    const planned = plannedPlanEntries(root);
+    const plannedParts = plannedPartKeys(planned);
+    // The cross-role in-flight hold (BUGS.md 2026-10-09): every role's prompts share this one
+    // section-agnostic index, and the role it is assembled for is not available here, so an entry
+    // claimed by ANY role is marked in flight — the owner's own index marks it too, which is harmless
+    // (its assignment note is the instruction), and every other role reads it as taken instead of
+    // re-implementing a change someone's merge is already carrying to main.
+    const claimed = allLiveClaims(root);
+    const listed = [];
+    for (const { file, section } of INDEX_SECTIONS) {
+        const full = path.join(root, file);
+        const entries = cachedTextByStat(indexSectionCache, full, full, (md) => {
+            const ranges = actionableEntryRanges(md, section);
+            if (ranges.length === 0)
+                return [];
+            const lines = md.split(/\r?\n/);
+            // The body slice is the lines after the heading through the last body line, so a note
+            // is found whether it sits first or last (the heading is at 1-based line e.start).
+            return ranges.map((e) => ({
+                start: e.start,
+                end: e.end,
+                title: e.title,
+                body: lines.slice(e.start, e.end).join("\n"),
+            }));
+        }, (v) => v.slice());
+        if (entries === null || entries.length === 0)
+            continue;
+        listed.push(`${file} ## ${section}`);
+        // Build the rows once per section, then collapse a PLANS.md series' blocked parts (this
+        // plan) — BUGS.md and QUESTIONS.md sections keep every entry on its own line.
+        const rows = entries.map((e) => {
+            const hold = entryHoldAgainst({ title: e.title, body: e.body }, plannedParts);
+            const key = collapseWhitespace(stripEntryStamp(e.title)).toLowerCase();
+            return {
+                start: e.start,
+                end: e.end,
+                title: e.title,
+                hold,
+                mark: holdMark(hold),
+                claimer: claimed.get(key),
+            };
+        });
+        const isPlans = file === "PLANS.md" && section === "Planned";
+        listed.push(...(isPlans ? collapseBlockedSeries(rows) : rows.map(renderIndexRow)));
+    }
+    for (const { files, section } of CLOSED_SECTIONS) {
+        // The newest RECENT_CLOSED_MAX across the live section (normally empty) and the archive.
+        let room = RECENT_CLOSED_MAX;
+        for (const file of files) {
+            if (room <= 0)
+                break;
+            const full = path.join(root, file);
+            const entries = cachedTextByStat(closedSectionCache, full, full, (md) => actionableEntryRanges(md, section).slice(0, RECENT_CLOSED_MAX), (v) => v.slice())?.slice(0, room);
+            if (entries === undefined || entries.length === 0)
+                continue;
+            room -= entries.length;
+            listed.push(`${file} ## ${section} (newest ${entries.length})`);
+            for (const e of entries)
+                listed.push(`- ${e.start}-${e.end}: ${indexTitle(e.title)}`);
+        }
+    }
+    if (listed.length === 0)
+        return undefined;
+    return `Backlog index — each actionable entry, then the newest closed ones, with the 1-based line range it occupies in its file.
+Read the entries you need by those ranges; the archive files (PLANS-DONE.md, BUGS-FIXED.md) grow
+with every merge, so search them rather than reading them. Blocked parts of a multi-part series are
+shown as one line per series.
+<backlog-index>
+${listed.join("\n")}
+</backlog-index>`;
+}