tumwater 0.3.0 → 0.4.0

package/README.md

@@ -42,7 +42,7 @@ and is also outside `npm test`.
 ## Status
 
 <!-- tumwater:status:start -->
-**v0.3.0**: working tumwater. The director and 14 of the 16 roles are enabled by default; `selfcheck`,
+**v0.4.0**: working tumwater. The director and 15 of the 17 roles are enabled by default; `selfcheck`,
 which files tumwater bugs from tumwater's own event log, and `feedback`, which files them as GitHub
 issues on znation/tumwater, are opt-in (`roles.selfcheck.enabled`, `roles.feedback.enabled`).
 

package/dist/build-info.json

@@ -1,5 +1,5 @@
 {
-  "sha": "d36bf79c535e10fe228f058ecc1ca839f3af61b1",
-  "builtAt": 1792789212458,
+  "sha": "4d2bccd84735720b529ab2695a5d274df2e48bbb",
+  "builtAt": 1792915702889,
   "root": "/home/runner/work/tumwater/tumwater"
 }

package/dist/src/agent/backend-traits.js

@@ -75,3 +75,16 @@ export function modelLabel(backend, provider, model) {
 export function backendDisplayName(id) {
     return id.charAt(0).toUpperCase() + id.slice(1);
 }
+/** A seam's own-default label when neither a provider nor a model resolves:
+ * `<backend> default` — pi's historical `pi default` for the pi backend (and an unknown id,
+ * which reads as pi), `claude default` for claude, and so on. The one home of the label
+ * `role-render.ts`'s Model line and the status rows share, so the two surfaces cannot
+ * disagree about what a seam without a model is named. */
+export function backendDefaultLabel(backend) {
+    // Only claude, opencode and codex carry their own `<backend> default`; pi, an absent
+    // backend and any unregistered id (which reads as pi) all carry pi's historical `pi
+    // default`, matching streamsToolOutput's reads-as-pi window.
+    if (backend === "claude" || backend === "opencode" || backend === "codex")
+        return `${backend} default`;
+    return "pi default";
+}

package/dist/src/agent/claude/claude-backend.js

@@ -20,7 +20,7 @@ import { randomUUID } from "node:crypto";
 import { resolvedBackendConfig } from "../../config/config-views.js";
 import { MODEL_TIERS } from "../../config/config-schema.js";
 import { routeModel } from "../../config/model-selector.js";
-import { backendBaseEnv, withNotesPath } from "../../process/run-marker.js";
+import { backendRunEnv } from "../../process/run-marker.js";
 import { resolveBinForBackend } from "../../pi/pi-bin.js";
 import { expandHomeTilde } from "../../files/files.js";
 import { claudeArgs } from "./claude-args.js";
@@ -147,7 +147,7 @@ export const claudeBackend = {
         // the marker the same way pi's adapter carries it (withNotesPath); from part 2/4 the run
         // saves its note through the `tumwater-notes` command on PATH, so no MCP server reaches the
         // run and `--strict-mcp-config` (always in claude-args.ts) keeps it that way.
-        const base = withNotesPath(backendBaseEnv(run.runMarker, undefined, run.binDir), run.notesPath);
+        const base = backendRunEnv(run);
         const env = claudeEnv(base, {
             quietTimeoutSeconds: run.config.quietTimeoutSeconds,
             ...(expandedConfigDir !== undefined ? { configDir: expandedConfigDir } : {}),

package/dist/src/agent/claude/claude-stream.js

@@ -15,6 +15,7 @@
  * `agent_unknown_event` warning after the run. `cost_unknown` is recorded the same way when a
  * run produced no authoritative `run_cost`. */
 import { joinParts } from "../../text/text.js";
+import { secondsUntil } from "../../text/datetime.js";
 import { canonicalUsageBlock, isJsonObject, objectOrEmpty, nonNegativeNumber, parseJsonObject } from "../../files/json-object.js";
 /** claude's tool names → the canonical pi names the readers already know. Glob/Grep are kept
  * lower-cased; MultiEdit collapses onto edit (pi has one edit tool). Anything else is
@@ -295,8 +296,8 @@ export function claudeTranslator(opts = {}) {
                 if (info.isUsingOverage === true)
                     out.isUsingOverage = true;
                 if (status === "rejected" && resetsAt !== undefined) {
-                    // resetsAt is a unix-seconds stamp; retryAfterSeconds is the wait the runner honors.
-                    out.retryAfterSeconds = Math.max(0, Math.round(resetsAt - Date.now() / 1000));
+                    // resetsAt is a unix-seconds stamp; secondsUntil folds it (×1000) to whole seconds.
+                    out.retryAfterSeconds = secondsUntil(resetsAt * 1000, Date.now());
                 }
                 return [JSON.stringify(out), ...windows];
             }

package/dist/src/agent/codex/codex-backend.js

@@ -19,7 +19,7 @@
 import fs from "node:fs";
 import { loadConfigSafe } from "../../config/config.js";
 import { resolvedBackendConfig } from "../../config/config-views.js";
-import { backendBaseEnv, withNotesPath } from "../../process/run-marker.js";
+import { backendRunEnv } from "../../process/run-marker.js";
 import { resolveBinForBackend } from "../../pi/pi-bin.js";
 import { teamRootOf, nearestTumwaterRoot } from "../../paths.js";
 import { warnEventBestEffort, TUMWATER_SOURCE } from "../../events/events.js";
@@ -120,7 +120,7 @@ export const codexBackend = {
         // The notes path rides beside the run marker, as the pi and claude adapters' envs do
         // (withNotesPath); from part 2/4 the run saves its note through the `tumwater-notes`
         // command on PATH, so codex configures no MCP server for notes.
-        const base = withNotesPath(backendBaseEnv(run.runMarker, undefined, run.binDir), run.notesPath);
+        const base = backendRunEnv(run);
         // A team home of its own (`CODEX_HOME`) keeps team sessions and trust entries out of the
         // operator's `~/.codex` (design §4, finding 10); unset leaves the operator's home.
         const home = codexHome(resolvedBackendConfig(run.config, "codex"));
@@ -162,7 +162,7 @@ export const codexBackend = {
         // invocation later reads was looked up under the run's own config. It never throws a run
         // away: a failed lookup records `off` (and warns once) and the run continues without the
         // guard's trust.
-        const base = withNotesPath(backendBaseEnv(run.runMarker, undefined, run.binDir), run.notesPath);
+        const base = backendRunEnv(run);
         const home = codexHome(resolvedBackendConfig(run.config, "codex"));
         const env = codexEnv(base, { home });
         const root = nearestTumwaterRoot(run.sessionDir);

package/dist/src/agent/codex/codex-stream.js

@@ -15,6 +15,7 @@
  */
 import { nonNegativeNumber, objectOrEmpty, parseJsonObject } from "../../files/json-object.js";
 import { boundText, outputLimits } from "../../pi-extension/bounded-output.js";
+import { secondsUntil } from "../../text/datetime.js";
 /** How codex wraps every shell command — the prefix to strip (with its quoting) so the
  * canonical `bash` call carries the model's own command, which suite-rerun detection matches. */
 const SHELL_WRAPPER = /^\/(?:bin\/)?(?:zsh|bash) -lc '(.*)'$/s;
@@ -76,7 +77,8 @@ function classifyTurnFailed(parsed) {
         const minutes = nonNegativeNumber(parsed.rate_limit_reached_type, undefined);
         const named = typeof parsed.rate_limit_reached_type === "string" ? parsed.rate_limit_reached_type : undefined;
         const resetsAt = nonNegativeNumber(parsed.resets_at, undefined);
-        const retryAfter = resetsAt === undefined ? undefined : Math.max(0, Math.round(resetsAt - Date.now() / 1000));
+        // secondsUntil folds the unix-seconds resets stamp (×1000 to epoch-ms), clamped at 0.
+        const retryAfter = resetsAt === undefined ? undefined : secondsUntil(resetsAt * 1000, Date.now());
         kind.kind = "transientRateLimit";
         kind.rateLimit = {
             type: "rate_limit",

package/dist/src/agent/opencode/opencode-backend.js

@@ -23,7 +23,7 @@ import path from "node:path";
 import { ensureParentDir } from "../../files/files.js";
 import { loadConfigSafe } from "../../config/config.js";
 import { resolvedBackendConfig } from "../../config/config-views.js";
-import { backendBaseEnv, withNotesPath } from "../../process/run-marker.js";
+import { backendRunEnv } from "../../process/run-marker.js";
 import { resolveBinForBackend } from "../../pi/pi-bin.js";
 import { opencodeDbPath, teamRootOf } from "../../paths.js";
 import { resumableSession } from "../session-ledger.js";
@@ -189,7 +189,7 @@ export const opencodeBackend = {
         // The notes path rides beside the run marker, as the pi and claude adapters' envs do
         // (withNotesPath); from part 2/4 the run saves its note through the `tumwater-notes` command
         // on PATH, so OpenCode configures no tumwater MCP server for notes.
-        const base = withNotesPath(backendBaseEnv(run.runMarker, undefined, run.binDir), run.notesPath);
+        const base = backendRunEnv(run);
         const env = opencodeEnv(base, { dbPath, configContent });
         const { sessionId } = resolveOpencodeSession(run, env);
         // The thinking variant (part 6d/7): ride the catalog's effort levels for the resolved

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

@@ -412,14 +412,16 @@ function quarantineTitlePrefix(test) {
 function fencedTail(tail) {
     return ["~~~~", ...tail.replaceAll("~~~~", "~~~").split("\n").slice(-30), "~~~~"].join("\n");
 }
-/** File one BUGS.md `## Open` entry per newly quarantined test and commit BUGS.md on the base
- * branch as one `tumwater(operator):` commit, under the merge lock and the primary-worktree lock
- * exactly as archiveFinishedOnMain does. Skipped, writing nothing, when the primary checkout is
- * off the base branch, BUGS.md has uncommitted changes, or BUGS.md exists but cannot be read; a
- * failed append or commit restores BUGS.md. A test whose quarantine entry is already under
- * `## Open` (a filing whose markQuarantineFiled failed after the commit) gets that heading back
- * and is not filed again. */
-export async function fileQuarantineBugsOnMain(root, tests, opts = {}) {
+/** File one BUGS.md `## Open` entry per given entry and commit BUGS.md on the base branch as one
+ * `tumwater(operator):` commit (the subject built from the number of entries actually appended is
+ * stamped under the operator role), under the merge lock and the primary-worktree lock exactly as
+ * archiveFinishedOnMain does. Skipped,
+ * writing nothing, when the primary checkout is off the base branch, BUGS.md has uncommitted
+ * changes, or BUGS.md exists but cannot be read; a failed append or commit restores BUGS.md.
+ * Every entry is appended verbatim as its own `## Open` heading — unless its `ifOpen` dedupe
+ * matches an existing heading, which is reused instead — and the returned headings are the
+ * entry headings in input order. */
+export async function fileBugsOnMain(root, entries, subject, opts = {}) {
     return withLock(mergeLockDir(root), () => withPrimaryWorktreeLockAsync(root, async () => {
         const primary = await currentBranch(root);
         const base = targetBranch(loadConfigSafe(root).config?.baseBranch, primary);
@@ -440,9 +442,8 @@ export async function fileQuarantineBugsOnMain(root, tests, opts = {}) {
         catch (err) {
             return { status: "skipped", reason: `BUGS.md could not be read: ${errorFirstLine(err)}` };
         }
-        const date = formatDate(new Date());
         const open = before === null ? [] : parseEntryDetails(before, "Open").map((e) => e.title);
-        const bugs = new Map();
+        const headings = [];
         let appended = 0;
         const restoreBugs = async () => {
             await gitTry(root, "reset", "-q", "--", "BUGS.md");
@@ -452,17 +453,15 @@ export async function fileQuarantineBugsOnMain(root, tests, opts = {}) {
                 writeTextAtomic(file, before);
         };
         try {
-            for (const { test, tail } of tests) {
-                const existing = open.find((t) => t.startsWith(quarantineTitlePrefix(test)));
-                if (existing !== undefined) {
-                    bugs.set(test, existing);
-                    continue;
+            for (const entry of entries) {
+                if (entry.ifOpen !== undefined) {
+                    const existing = entry.ifOpen(open);
+                    if (existing !== undefined) {
+                        headings.push(existing);
+                        continue;
+                    }
                 }
-                const body = [
-                    `The check failed on this test and then passed on a re-run of the same tree, so tumwater quarantined it: it counts as a known failure until this entry leaves \`## Open\`. Find why it is unstable and fix it.`,
-                    ...(tail ? ["", fencedTail(tail)] : []),
-                ].join("\n");
-                bugs.set(test, appendBugEntryLocked(root, `${quarantineTitlePrefix(test)}${date})`, body));
+                headings.push(appendBugEntryLocked(root, entry.title, entry.body));
                 appended++;
             }
         }
@@ -471,17 +470,53 @@ export async function fileQuarantineBugsOnMain(root, tests, opts = {}) {
             return { status: "skipped", reason: `a BUGS.md entry could not be written: ${errorFirstLine(err)}` };
         }
         if (appended === 0)
-            return { status: "filed", bugs };
-        const subject = stampedSubject("operator", // vocabulary-ok: the tumwater(operator): commit prefix is a machine string
-        `File ${plural(appended, "quarantined flaky test", "quarantined flaky tests")} in BUGS.md`);
+            return { status: "filed", headings };
+        const commitSubject = stampedSubject("operator", // vocabulary-ok: the tumwater(operator): commit prefix is a machine string
+        subject(appended));
         try {
             await git(root, "add", "--", "BUGS.md");
-            await git(root, ...(await committerIdentArgs(root)), "commit", ...commitAuthorArgs(), "--only", "-m", subject, "--", "BUGS.md");
+            await git(root, ...(await committerIdentArgs(root)), "commit", ...commitAuthorArgs(), "--only", "-m", commitSubject, "--", "BUGS.md");
         }
         catch (err) {
             await restoreBugs();
             return { status: "skipped", reason: `the commit failed: ${errorFirstLine(err)}` };
         }
-        return { status: "filed", bugs };
+        return { status: "filed", headings };
     }), opts.lockTimeoutMs);
 }
+/** File one BUGS.md `## Open` entry per newly quarantined test and commit BUGS.md on the base
+ * branch as one `tumwater(operator):` commit, delegating the locked write/commit to
+ * fileBugsOnMain and preserving the existing subject. A test whose quarantine entry is already
+ * under `## Open` (a filing whose markQuarantineFiled failed after the commit) gets that heading
+ * back and is not filed again — the dedupe runs inside fileBugsOnMain under the merge lock (via
+ * each entry's `ifOpen`), so concurrent quarantine filings cannot both append a duplicate, and
+ * the real skip on a dirty or off-base BUGS.md is enforced under the same lock. */
+export async function fileQuarantineBugsOnMain(root, tests, opts = {}) {
+    const date = formatDate(new Date());
+    const toFile = [];
+    for (const { test, tail } of tests) {
+        const prefix = quarantineTitlePrefix(test);
+        const body = [
+            `The check failed on this test and then passed on a re-run of the same tree, so tumwater quarantined it: it counts as a known failure until this entry leaves \`## Open\`. Find why it is unstable and fix it.`,
+            ...(tail ? ["", fencedTail(tail)] : []),
+        ].join("\n");
+        toFile.push({
+            title: `${prefix}${date})`,
+            body,
+            // Dedupe under the lock, against the headings fileBugsOnMain reads: the reused heading
+            // (not a duplicate) is returned in headings and zipped back to this test below.
+            ifOpen: (open) => open.find((t) => t.startsWith(prefix)),
+        });
+    }
+    const outcome = await fileBugsOnMain(root, toFile, 
+    // Size the subject by what was actually appended: tests whose `## Open` entry was already
+    // present are reused, not filed, so a mixed batch keeps the original "File N …" wording
+    // with N the count of new entries only.
+    (appended) => `File ${plural(appended, "quarantined flaky test", "quarantined flaky tests")} in BUGS.md`, opts);
+    if (outcome.status === "skipped")
+        return { status: "skipped", reason: outcome.reason };
+    // fileBugsOnMain's headings align with `tests` in order (reused headings or appended titles).
+    const bugs = new Map();
+    outcome.headings.forEach((heading, i) => bugs.set(tests[i].test, heading));
+    return { status: "filed", bugs };
+}

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

@@ -3,7 +3,7 @@
  * shells (file, cancel, release, top, edit). Neither shell gates on a ready repo, commits, or
  * wakes a role. cli.ts reaches them through listAndAnnounce and showAndAnnounce. */
 import { fail, say, sayJson } from "../cli/cli-output.js";
-import { parseCountFlag, parsePositionFlag, rejectRepeatFlag } from "../cli/cli-args.js";
+import { parseCountFlag, rejectRepeatFlag, scanPositionArgs } from "../cli/cli-args.js";
 import { DONE_DATE_RE, FIXED_DATE_RE, completionDate, donePlanEntries, fixedBugEntries, openBugEntries, plannedPlanEntries, ageInDays, entryAgeSuffix, entryMatches, filingDate, } from "./backlog.js";
 import { backlogHolds, backlogInProgress, holdMark, inProgressMark } from "./backlog-eligibility.js";
 import { groupBlockedSeries, partsLabel } from "./backlog-structure.js";
@@ -221,37 +221,12 @@ export function listAndAnnounce(root, args, command, fileName, sectionTitle) {
  * `--list`: no repo gate, commit, or wake. Prose is the title, a blank line, then the body, so
  * stdout is the file `--edit <n> --file` takes back. */
 export function showAndAnnounce(root, args, command) {
-    let position = null;
-    let json = false;
-    let done = false;
-    const rest = [];
-    for (let i = 0; i < args.length; i++) {
-        const arg = args[i];
-        if (arg === "--done") {
-            rejectRepeatFlag(done, "--done");
-            done = true;
-            continue;
-        }
-        if (arg === "--json") {
-            rejectRepeatFlag(json, "--json");
-            json = true;
-            continue;
-        }
-        if (arg === "--show") {
-            rejectRepeatFlag(position !== null, "--show");
-            position = parsePositionFlag("--show", args[i + 1], "--show 2");
-            i++;
-            continue;
-        }
-        if (arg === "--help" || arg === "-h")
-            continue;
-        rest.push(arg);
-    }
+    const { json, flags, position, rest } = scanPositionArgs(args, "--show", "--show 2", ["--done"]);
     rejectUnknownArgs(command, rest, []);
     refuseTeamWorkspace(root);
     if (position === null)
         fail(`--show needs a position (usage: tumwater ${command} --show <n>)`);
-    if (done) {
+    if (flags["--done"]) {
         const bug = command === "bug";
         const all = bug ? fixedBugEntries(root) : donePlanEntries(root);
         const entry = all[position - 1];

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

@@ -6,12 +6,13 @@
  * surgery and the locked read-modify-write live in backlog-write.ts. The wake of the role that
  * should act stays in cli.ts beside the other command bodies. */
 import { fail, say, sayJson, warnIfUncommitted } from "../cli/cli-output.js";
-import { parsePositionFlag, rejectRepeatFlag } from "../cli/cli-args.js";
+import { parsePositionFlag, rejectRepeatFlag, scanPositionArgs } from "../cli/cli-args.js";
 import { promptFileValue, readPromptFileArg } from "../cli/cli-command-args.js";
 import { plannedPlanEntries } from "./backlog.js";
 import { allLiveClaims } from "../runner/runner-state-load.js";
 import { backlogHolds, cancelledClaimNote, stillHeldNote } from "./backlog-eligibility.js";
 import { entryKey, plansReleasedBy, releasedPartsNote } from "./backlog-parts.js";
+import { liftedNotePhrase } from "./backlog-release.js";
 import { collapseWhitespace } from "../text/text.js";
 import { JSON_FLAG, rejectUnknownArgs } from "../cli/cli-flag-specs.js";
 import { requireReadyRepo } from "../cli/cli-repo-gate.js";
@@ -148,26 +149,7 @@ async function announceFiled(root, command, filed, role, wakeText, json) {
  * `cancelled <command> in <file>: <title>` or the `--json` payload {file, title}. Unlike
  * fileAndAnnounce there is no wake: removing work must not wake a role. */
 export async function cancelAndAnnounce(root, args, command, cancel) {
-    let position = null;
-    let json = false;
-    const rest = [];
-    for (let i = 0; i < args.length; i++) {
-        const arg = args[i];
-        if (arg === "--json") {
-            rejectRepeatFlag(json, "--json");
-            json = true;
-            continue;
-        }
-        if (arg === "--cancel") {
-            rejectRepeatFlag(position !== null, "--cancel");
-            position = parsePositionFlag("--cancel", args[i + 1], "--cancel 2");
-            i++;
-            continue;
-        }
-        if (arg === "--help" || arg === "-h")
-            continue;
-        rest.push(arg);
-    }
+    const { json, position, rest } = scanPositionArgs(args, "--cancel", "--cancel 2");
     // rejectUnknownArgs names both a stray positional and an unknown flag, with this command's
     // (empty) valid-flag list — the vocabulary a cancel invocation accepts is exactly --cancel
     // and --json, both consumed above.
@@ -197,28 +179,10 @@ export async function cancelAndAnnounce(root, args, command, cancel) {
  * released entry is eligible now, and that role may be backed off) with no queued prompt. An
  * entry still held after the release (another note, an unmerged prerequisite) wakes no one and
  * gets stillHeldNote instead of the wake line. Prints `released <command> in <file>: <title>`
- * plus that line, or only the `--json` payload (with `hold` when still held). */
+ * naming the note it lifted, plus that line, or only the `--json` payload (with `lifted`, and
+ * `hold` when still held). */
 export async function releaseAndAnnounce(root, args, command, release, role) {
-    let position = null;
-    let json = false;
-    const rest = [];
-    for (let i = 0; i < args.length; i++) {
-        const arg = args[i];
-        if (arg === "--json") {
-            rejectRepeatFlag(json, "--json");
-            json = true;
-            continue;
-        }
-        if (arg === "--release") {
-            rejectRepeatFlag(position !== null, "--release");
-            position = parsePositionFlag("--release", args[i + 1], "--release 2");
-            i++;
-            continue;
-        }
-        if (arg === "--help" || arg === "-h")
-            continue;
-        rest.push(arg);
-    }
+    const { json, position, rest } = scanPositionArgs(args, "--release", "--release 2");
     rejectUnknownArgs(command, rest, []);
     if (position === null)
         fail(`--release needs a position (usage: tumwater ${command} --release <n>)`);
@@ -229,9 +193,9 @@ export async function releaseAndAnnounce(root, args, command, release, role) {
     const hold = (command === "bug" ? holds.bugs : holds.plans)[position - 1] ?? null;
     const wake = hold === null ? requestWake(root, [role]) : "";
     if (json)
-        sayJson({ file: released.file, title: released.title, ...(hold === null ? {} : { hold }) });
+        sayJson({ file: released.file, title: released.title, lifted: released.lifted, ...(hold === null ? {} : { hold }) });
     else {
-        say(`released ${command} in ${released.file}: ${released.title}`);
+        say(`released ${command} in ${released.file}: ${released.title} (lifted ${liftedNotePhrase(released.lifted)})`);
         say(hold === null ? wake : stillHeldNote(hold));
     }
 }
@@ -242,26 +206,7 @@ export async function releaseAndAnnounce(root, args, command, release, role) {
  * (then stillHeldNote when the entry is held) or only the `--json` payload (with `hold` when
  * held). */
 export async function topAndAnnounce(root, args, command, top) {
-    let position = null;
-    let json = false;
-    const rest = [];
-    for (let i = 0; i < args.length; i++) {
-        const arg = args[i];
-        if (arg === "--json") {
-            rejectRepeatFlag(json, "--json");
-            json = true;
-            continue;
-        }
-        if (arg === "--top") {
-            rejectRepeatFlag(position !== null, "--top");
-            position = parsePositionFlag("--top", args[i + 1], "--top 2");
-            i++;
-            continue;
-        }
-        if (arg === "--help" || arg === "-h")
-            continue;
-        rest.push(arg);
-    }
+    const { json, position, rest } = scanPositionArgs(args, "--top", "--top 2");
     rejectUnknownArgs(command, rest, []);
     if (position === null)
         fail(`--top needs a position (usage: tumwater ${command} --top <n>)`);

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

@@ -5,10 +5,12 @@ import { commitAuthorArgs, committerIdentArgs, gitTry } from "../git/git-run.js"
 /** Commit one operator-written backlog file on main, so the entry reaches the worktrees that
  * branch from main and the primary checkout stays clean for the next fast-forward. Runs under
  * the primary-worktree lock `ffMainTo`'s working-tree arm takes, so the commit and a
- * fast-forward cannot interleave. Returns false, writing nothing, when the primary is not on
- * the base branch (the ref-push arm: the working tree is not main's) or when git fails; it
- * never throws, and the entry stays written either way. `--only` with a pathspec commits just
- * that file's working-tree content and leaves other staged or dirty paths alone. */
+ * fast-forward cannot interleave. Returns false when the commit did not land — the primary is
+ * not on the base branch (the ref-push arm: the working tree is not main's), or git failed —
+ * and in that case restores the file to its committed state so the primary checkout does not
+ * stay dirty and block every merge touching it with "the merge would overwrite files in the
+ * primary checkout". It never throws. `--only` with a pathspec commits just that file's
+ * working-tree content and leaves other staged or dirty paths alone. */
 export async function commitOperatorBacklogEdit(root, file, subject) {
     try {
         // Yield first: a synchronous caller (the TUI key handler) may write again right after this
@@ -17,11 +19,17 @@ export async function commitOperatorBacklogEdit(root, file, subject) {
         await new Promise((resolve) => setImmediate(resolve));
         return await withPrimaryWorktreeLockAsync(root, async () => {
             const primary = await currentBranch(root);
-            if (primary === null)
-                return false;
-            if (targetBranch(loadConfigSafe(root).config?.baseBranch, primary) !== primary)
-                return false;
-            return (await gitTry(root, ...(await committerIdentArgs(root)), "commit", ...commitAuthorArgs(), "--only", "-m", subject, "--", file)) !== null;
+            let committed = primary !== null &&
+                targetBranch(loadConfigSafe(root).config?.baseBranch, primary) === primary &&
+                (await gitTry(root, ...(await committerIdentArgs(root)), "commit", ...commitAuthorArgs(), "--only", "-m", subject, "--", file)) !== null;
+            if (!committed) {
+                // The write landed in the working tree but could not be committed to the base branch:
+                // roll the file back to its committed state (HEAD) so the primary checkout stays clean
+                // for the next fast-forward instead of refusing every merge that touches it. Only this
+                // file is touched; other staged or dirty paths are left alone.
+                await gitTry(root, "checkout", "HEAD", "--", file);
+            }
+            return committed;
         });
     }
     catch {

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

@@ -10,7 +10,7 @@
 import path from "node:path";
 import { statOrNull } from "../files/files.js";
 import { allLiveClaims } from "../runner/runner-state-load.js";
-import { firstTrimmedLineStartingWith } from "../text/text.js";
+import { escapeRegExp, 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";
@@ -25,7 +25,7 @@ export const OPERATOR_HOLD_THRESHOLD = 3;
  * 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+)\\)`);
+    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) || line.startsWith(NEEDS_REPLAN_PREFIX);
@@ -55,7 +55,7 @@ function lineHeldCount(line) {
     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);
+    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
@@ -331,37 +331,55 @@ export function backlogMarks(root) {
         bugs: holds.bugs.map((h, i) => mark(h, working.bugs[i])),
     };
 }
-/** 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 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 = [];
-    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
-    });
+    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
+        });
+    };
+    entriesOf(plannedPlanEntries(root), holds.plans, "plans");
+    entriesOf(openBugEntries(root), holds.bugs, "bugs");
     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) {
+/** 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
+ * 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. */
+export function entryKindLabel(file) {
+    return file === "bugs" ? "Bug" : "Plan";
+}
+/** The planned plans and open bugs whose hold is exactly `"needs-review"` or
+ * `"needs-replan"`, in file order: the entries parked by a Needs-review/Needs-replan 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 = [];
-    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 });
-    });
+    const entriesOf = (entries, held, file) => {
+        entries.forEach((e, i) => {
+            const hold = held[i];
+            if (hold === "needs-review" || hold === "needs-replan")
+                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