tumwater 0.4.4 → 0.4.6

package/README.md

@@ -42,7 +42,7 @@ and is also outside `npm test`.
 ## Status
 
 <!-- tumwater:status:start -->
-**v0.4.4**: working tumwater. The director and 15 of the 17 roles are enabled by default; `selfcheck`,
+**v0.4.6**: 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": "1f6978ed5d8061b12afc907b017f0164426f49ee",
-  "builtAt": 1793345933702,
+  "sha": "e8bba8ae0464d05115b3eb917425d5d8d7629f66",
+  "builtAt": 1793691627357,
   "root": "/home/runner/work/tumwater/tumwater"
 }

package/dist/src/agent/agent-run.js

@@ -122,6 +122,7 @@ export function runAgent(opts) {
                 extendOnProgress: opts.kind === "gate",
                 kill: () => terminateChild(child),
                 onStallWarning: opts.onStallWarning,
+                onUnansweredReply: opts.onUnansweredReply,
             });
             let aborted = false;
             // A blind image read on an authoring run deliberately kills it, like the watchdogs do.

package/dist/src/agent/opencode/write-guard-plugin/index.js

@@ -4,20 +4,23 @@
  *
  * OpenCode 2.x has no hook that blocks a tool from running. It has a permission `evaluate` hook
  * that may turn a decision to `deny` with a `message`, which reaches the model as the tool's error
- * while the run goes on. Every file-writing tool asks for the `edit` action with the absolute
- * paths it writes as `resources`, and the hook runs under `--auto` too, since `--auto` only
- * answers what would otherwise be asked. Checked live on opencode 2.1.0 on 2026-10-23. A
- * configured plugin path must be a directory, which is why this is `index.js` in a directory of
- * its own.
+ * while the run goes on. The file-writing tools ask for the `edit` action (edit in place) and the
+ * `write` action (create or overwrite a file — a new path a `../` climb can point outside the
+ * checkout) with the absolute paths they write as `resources`, and the hook runs under `--auto`
+ * too, since `--auto` only answers what would otherwise be asked. Checked live on opencode 2.1.0
+ * on 2026-10-23. A configured plugin path must be a directory, which is why this is `index.js` in
+ * a directory of its own.
  *
  * The plugin's context names the run's directory (`location.directory`, the worktree OpenCode
  * runs in), which is the run directory the rule reads its checkout from. A failure of its own
  * leaves the decision alone, so a broken guard cannot stop every edit of a run. */
 import { strayWriteRefusal } from "../../write-guard.js";
-/** Deny an `edit` decision whose resources include a stray path from a run in `runDir`, naming
- * the first such path's refusal. Every other decision is left as it is. Exported for tests. */
+/** Deny an `edit` or `write` decision whose resources include a stray path from a run in
+ * `runDir`, naming the first such path's refusal. Every other decision is left as it is. Exported
+ * for tests. */
+const FILE_WRITE_ACTIONS = new Set(["edit", "write"]);
 export function guardEvaluate(event, runDir) {
-    if (event.action !== "edit" || !Array.isArray(event.resources))
+    if (!FILE_WRITE_ACTIONS.has(event.action) || !Array.isArray(event.resources))
         return;
     for (const resource of event.resources) {
         if (typeof resource !== "string" || resource === "")

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

@@ -3,7 +3,8 @@
  * "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 read one answer instead of re-deriving it per surface.
+ * so the free-ness rule and the window displays 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
@@ -14,6 +15,7 @@
  * keeps today's shape. */
 import { readJsonFile, writeJsonAtomic } from "../files/json-files.js";
 import { finiteNumber, isJsonObject, setOwn } from "../files/json-object.js";
+import { cachedByStat } from "../files/stat-cache.js";
 import { accountPath } from "../paths.js";
 /** True when a failed run ended on a subscription usage window the account reported as
  * `rejected` without overage — the signal the team hold throttles on (plans/agent-backends.md
@@ -27,12 +29,74 @@ export function subscriptionWindowRejected(run) {
         run.billing === "subscription" &&
         (run.rateWindows ?? []).some((w) => w.status === "rejected" && w.isUsingOverage !== true));
 }
+/** 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 (the browser dashboard keeps its inline copy). */
+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 node-side home of the fraction→percent conversion
+ * (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));
+}
+/** The parsed raw body of one backend's account file, keyed by that file's own stat — the same
+ * stat-keyed contract cachedByStat gives every observer that polls a slowly-changing file. The
+ * account file is written only by the orchestrator on a run's billing/window report, so it
+ * changes no faster than runs; on the status snapshot path readAccount ran per backend per poll
+ * as one more readJsonFile (read + parse) alongside the already stat-cached marker reads, and
+ * budget-gates/role-view read it on other polling surfaces. Writes go through writeJsonAtomic's
+ * tmp+rename (writeAccount), which bumps dev/ino/mtime/size, so a refresh invalidates like any
+ * edit. The `now`-dependent heal is NOT cached: only the raw body is, and readAccount reapplies
+ * its window/observedAt rules against each call's own `now` on a per-call copy, so a window
+ * whose `resetsAt` lapses still reads back as reset on the very call it does. Bounded inside
+ * cachedByStat. */
+const accountBodyCache = new Map();
+/** Serve `file`'s parsed raw JSON-object body from accountBodyCache: null when the file is
+ * missing, unreadable, torn, or not a plain object — the same no-data policy as readJsonFile —
+ * and a fresh per-call copy so readAccount's owns the object it reads fields off. Never throws. */
+function readAccountBody(file) {
+    return cachedByStat(accountBodyCache, file, file, () => readJsonFile(file), (body) => ({ ...body }));
+}
 /** 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
  * reader, not every consumer, decides that the window no longer limits. */
 export function readAccount(root, backend, now = Date.now()) {
-    const doc = readJsonFile(accountPath(root, backend));
+    const doc = readAccountBody(accountPath(root, backend));
     if (doc === null)
         return null;
     const billing = doc.billing === "subscription" || doc.billing === "api" ? (doc.billing) : undefined;
@@ -64,7 +128,8 @@ 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 poison any consumer's utilization read.
+    // non-finite fraction would render as `Infinity%` in the badges and poison the
+    // windowEntries comparator (Infinity - Infinity is NaN).
     const utilization = finiteNumber(value.utilization, undefined);
     const reset = resets && resetsAt <= now;
     const window = {

package/dist/src/agent/write-guard.js

@@ -27,25 +27,62 @@ function isWithin(p, dir) {
     const rel = path.relative(dir, p);
     return rel === "" || (rel !== ".." && !rel.startsWith(`..${path.sep}`) && !path.isAbsolute(rel));
 }
-/** `p` with its longest existing prefix resolved through realpath, so a symlink, a `/tmp` that is
- * `/private/tmp`, or a path typed in the wrong case on a case-insensitive disk compares as the
- * file it reaches. The part that does not exist yet (a file a write would create) is appended
- * unchanged. */
+/** `p` with its symlinks resolved as the file it reaches: each component is peeled and a
+ * symlink is followed to its target, so a symlinked checkout or a `/tmp` that is `/private/tmp`
+ * compares as the path it reaches. The not-yet-existing tail (a file a write would create) is
+ * appended unchanged. A broken symlink — target absent, the write/create case, where
+ * `realpathSync` throws ENOENT and the old longest-existing-prefix walk read the link as its
+ * own location inside the checkout — is followed to its target instead: the write would follow
+ * it, so the guard must see where it points. */
 function realish(p) {
-    let existing = p;
-    const rest = [];
-    for (;;) {
+    // Peel the path component by component, exactly as `realpath` does: a regular component is
+    // kept, a symlink is replaced by the components its target resolves to, and the first absent
+    // component ends the walk, so a not-yet-existing tail is appended unchanged. Replacing the
+    // link with its target — instead of keeping the link's own path — is what catches a broken
+    // symlink: its target is absent (the write/create case, where `realpathSync` throws ENOENT
+    // and the old longest-existing-prefix walk read the link as its location inside the
+    // checkout), yet the write would still follow it, so the guard must see where it points. A
+    // depth bound stops a symlink cycle (a → b → a) from looping instead of escaping through the
+    // tail.
+    let q = path.resolve(p).split(path.sep).filter(Boolean);
+    const out = [];
+    let depth = 0;
+    while (q.length > 0) {
+        const part = q[0]; // the loop's length check guarantees a first component
+        const here = path.join(path.sep, ...out, part);
+        let st;
         try {
-            return path.join(fs.realpathSync.native(existing), ...rest);
+            st = fs.lstatSync(here);
         }
         catch {
-            const parent = path.dirname(existing);
-            if (parent === existing)
-                return p;
-            rest.unshift(path.basename(existing));
-            existing = parent;
+            out.push(part, ...q.slice(1)); // absent: this and the rest are the not-yet-existing tail
+            break;
+        }
+        if (!st.isSymbolicLink()) {
+            out.push(part);
+            q = q.slice(1);
+        }
+        else if (depth++ > 100) {
+            out.push(part, ...q.slice(1)); // cycle: give up rather than loop
+            break;
+        }
+        else {
+            let raw;
+            try {
+                raw = fs.readlinkSync(here); // a relative target is relative to the link's dir
+            }
+            catch {
+                out.push(part, ...q.slice(1)); // unreadable: treat as the not-yet-existing tail
+                break;
+            }
+            // The target, absolute-resolved, becomes the whole remaining path to peel: the link's
+            // own directory is dropped and replaced by wherever the link points.
+            const target = path.isAbsolute(raw) ? raw : path.resolve(path.join(path.sep, ...out), raw);
+            q = [...target.split(path.sep).filter(Boolean), ...q.slice(1)];
+            out.length = 0;
         }
     }
+    return path.join(path.sep, ...out);
 }
 /** A tool's path argument as pi's tools resolve it (pi `resolveToCwd`): a leading `@` dropped,
  * `~` expanded to the home directory, and a relative path taken from `base`. */

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

@@ -53,8 +53,11 @@ export function needsReviewNote(body) {
  * 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
+ * role can act on until then, and for the director's user fallback ("by director: …", the
+ * director-request handoff's final park) — the director has already reviewed the entry and the
+ * park names what the user must decide, so it is not plan-role work either. 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
@@ -63,8 +66,9 @@ 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");
+    // A "by bugfix:" note is a wait for evidence that selfcheck clears, and a "by director:"
+    // note is the director's reviewed user fallback (INV-B8) — neither is plan-role work.
+    return !note.includes("by bugfix") && !note.includes("by director");
 }
 /** `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,

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

@@ -15,7 +15,7 @@ import { collapseWhitespace, truncate } from "../text/text.js";
 import { actionableEntryRanges, groupBlockedSeries, partsLabel, } from "./backlog-index-data.js";
 import { stripEntryStamp } from "./backlog-structure.js";
 import { entryHoldAgainst, holdMark } from "./backlog-eligibility.js";
-import { plannedPartKeys } from "./backlog-parts.js";
+import { entryKey, 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. */
@@ -110,7 +110,7 @@ export function renderBacklogIndexBlock(root) {
         // 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();
+            const key = entryKey(e.title);
             return {
                 start: e.start,
                 end: e.end,

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

@@ -52,27 +52,42 @@ export function fenceTracker() {
             return fence !== null;
         },
         inside(line) {
-            const fenceLine = /^ {0,3}(`{3,}|~{3,})/.exec(line);
-            if (fenceLine) {
-                const marker = fenceLine[1] ?? ""; // The group always participates; "" keeps types honest.
-                if (fence === null) {
-                    // CommonMark: an info string for a backtick fence cannot contain a backtick, so a
-                    // line like ````md / ## Done / ````` quoted in prose is paragraph text, not a fence
-                    // opener — taken as one, no later bare fence line can close it and the fence runs to
-                    // EOF, swallowing the rest of the document as fenced content.
-                    const info = line.replace(/^ {0,3}/, "").slice(marker.length);
-                    if (marker.startsWith("`") && info.includes("`"))
-                        return false;
-                    fence = { char: marker.charAt(0), length: marker.length };
-                }
-                else if (marker.startsWith(fence.char) && marker.length >= fence.length && line.trim() === marker)
-                    fence = null;
-                return true; // The fence line itself is fence syntax, never structure.
+            if (fence === null) {
+                fence = fenceOpener(line);
+                return fence !== null; // An opener is fence syntax, never structure.
             }
-            return fence !== null;
+            if (closesFence(line, fence))
+                fence = null;
+            return true; // Inside a fence, every line (its closer too) is fence syntax or content.
         },
     };
 }
+/** A CommonMark fence line's leading marker run, or null: ```` ``` ```` or `~~~` (three or more)
+ * after at most three spaces of indent. */
+function fenceMarkerRun(line) {
+    return /^ {0,3}(`{3,}|~{3,})/.exec(line)?.[1] ?? null;
+}
+/** The fence `line` opens, or null when it opens none — CommonMark's opening rule, shared by
+ * fenceTracker and review-verdict.ts's quoted-code stripping. An info string may follow the
+ * marker, except that a backtick fence's info string may not contain a backtick: a line like
+ * ````md / ## Done / ````` quoted in prose is paragraph text. Taken as an opener, no later bare
+ * fence line could close it and the fence would run to EOF, swallowing the rest of the document
+ * as fenced content. */
+export function fenceOpener(line) {
+    const marker = fenceMarkerRun(line);
+    if (!marker)
+        return null;
+    const info = line.replace(/^ {0,3}/, "").slice(marker.length);
+    if (marker.startsWith("`") && info.includes("`"))
+        return null;
+    return { char: marker.charAt(0), length: marker.length };
+}
+/** Whether `line` closes `fence` — CommonMark's closing rule: a bare fence line (no info
+ * string) of the same character, at least as long as the opener. */
+export function closesFence(line, fence) {
+    const marker = fenceMarkerRun(line);
+    return marker !== null && marker.startsWith(fence.char) && marker.length >= fence.length && line.trim() === marker;
+}
 /** The title of a markdown heading line at `prefix` level — or the empty string when the heading
  * carries no text. The prefix's own length drives the slice (never a hard-coded `3`/`4`), so the
  * two heading levels cannot drift. The single home of the heading-title slice, shared by
@@ -342,9 +357,20 @@ export function entryLags(md, sectionTitle, dateRe, filingRe) {
 export function headingMetadata(lines, start) {
     const line = lines[start] ?? "";
     const meta = [line];
+    const j = collectHeadingContinuation(lines, start, meta, headingIsWrapped(line));
+    return { text: meta.join(" "), next: j };
+}
+/** Whether a `### ` heading line opens an unbalanced parenthetical: the only shape whose
+ * metadata runs beyond its first line. */
+function headingIsWrapped(line) {
     // A wrapped heading's first line opens a parenthetical its continuation will close; an
     // unbalanced count is therefore the only shape that has metadata beyond the first line.
-    const wrapped = (line.match(/\(/g) ?? []).length > (line.match(/\)/g) ?? []).length;
+    return (line.match(/\(/g) ?? []).length > (line.match(/\)/g) ?? []).length;
+}
+/** Append a wrapped `### ` heading's continuation lines to `meta`, stopping at the next entry
+ * start, the 3-line cap, or a line ending in `)`; returns the first line index not consumed. */
+function collectHeadingContinuation(lines, start, meta, wrapped) {
+    const line = lines[start] ?? "";
     let closed = line.endsWith(")");
     let j = start + 1;
     // Continuation is a heading-only concern (wrapped headings); bullets are single-line.
@@ -356,7 +382,7 @@ export function headingMetadata(lines, start) {
         j++;
         closed = next.endsWith(")");
     }
-    return { text: meta.join(" "), next: j };
+    return j;
 }
 /** A `- ` line's or `### ` heading's trailing parenthetical's inner text, nesting-aware: a
  * backward scan from the text's closing ")" to its matching "(" returns the group's FULL inner

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

@@ -4,7 +4,7 @@
  * section. Each comes as an exiting writer (the CLI) and a non-exiting `try…` core that refuses as
  * data (the TUI and dashboard); entry lookup and the section's file target are
  * backlog-write.ts's. */
-import { backlogTarget, findEntry, locateDashboardEntry, readEntryLines } from "./backlog-write.js";
+import { backlogTarget, findEntry, readEntryLines, withLocatedEntry } from "./backlog-write.js";
 import { withoutNeedsReviewNotes, withoutRefusalNotes } from "./backlog-eligibility.js";
 import { writeTextAtomic } from "../files/files.js";
 import { fail } from "../cli/cli-output.js";
@@ -38,11 +38,7 @@ function liftRefusal(lines, entry) {
  * title check, all decided inside the lock. */
 export function tryReleaseEntry(root, kind, n, expectedTitle) {
     const { fileName, sectionTitle } = backlogTarget(kind);
-    return withPrimaryWorktreeLock(root, () => {
-        const located = locateDashboardEntry(root, fileName, sectionTitle, n, expectedTitle);
-        if (located.status !== "ok")
-            return located;
-        const { file, md, entry } = located;
+    return withLocatedEntry(root, fileName, sectionTitle, n, expectedTitle, ({ file, md, entry }) => {
         const lines = md.split("\n");
         const lifted = liftRefusal(lines, entry);
         if (lifted === null)
@@ -104,11 +100,7 @@ function spliceEntryToTop(lines, sectionTitle, entry) {
  * title check, all decided inside the lock. */
 export function tryMoveEntryToTop(root, kind, n, expectedTitle) {
     const { fileName, sectionTitle } = backlogTarget(kind);
-    return withPrimaryWorktreeLock(root, () => {
-        const located = locateDashboardEntry(root, fileName, sectionTitle, n, expectedTitle);
-        if (located.status !== "ok")
-            return located;
-        const { file, md, entry } = located;
+    return withLocatedEntry(root, fileName, sectionTitle, n, expectedTitle, ({ file, md, entry }) => {
         if (n === 1)
             return { status: "already_first", title: entry.title };
         const lines = md.split("\n");

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

@@ -147,7 +147,7 @@ export function readEntryLines(root, fileName, sectionTitle, n) {
  * refuse as data without writing; on success returns the `ok` file path, raw markdown and entry
  * for the caller to splice and write its own outcome. A pure lookup, decided inside the caller's
  * lock. */
-export function locateDashboardEntry(root, fileName, sectionTitle, n, expectedTitle) {
+function locateDashboardEntry(root, fileName, sectionTitle, n, expectedTitle) {
     const file = path.join(root, fileName);
     const md = readTextIfExists(file) ?? "";
     const entry = findEntry(md, sectionTitle, n);
@@ -157,6 +157,22 @@ export function locateDashboardEntry(root, fileName, sectionTitle, n, expectedTi
         return { status: "moved", title: entry.title };
     return { status: "ok", file, md, entry };
 }
+/** The shared lock-and-locate prologue of the four non-exiting dashboard writers (tryCancelEntry
+ * and tryEditEntry here; tryReleaseEntry and tryMoveEntryToTop in backlog-release.ts): take the
+ * cross-process lock, locate the `n`th entry by position and expected title, and refuse as data —
+ * returning `located`'s `gone`/`moved` verbatim when the lookup fails — without writing. On a
+ * match it calls `splice` with the located file, markdown and entry and returns whatever the
+ * splice returns, so each writer keeps its own `ok`-branch outcome; the return is the union of the
+ * two refusals and `splice`'s own return, which is exactly each writer's outcome type. The
+ * `splice` runs inside the lock, the same window the inline prologue held. */
+export function withLocatedEntry(root, fileName, sectionTitle, n, expectedTitle, splice) {
+    return withPrimaryWorktreeLock(root, () => {
+        const located = locateDashboardEntry(root, fileName, sectionTitle, n, expectedTitle);
+        if (located.status !== "ok")
+            return located;
+        return splice({ file: located.file, md: located.md, entry: located.entry });
+    });
+}
 /** The section-remove entry point, the appendEntry analogue: the same cross-process lock, so a
  * cancel and a merge's working-tree fast-forward cannot each clobber the other's
  * read-modify-write. */
@@ -189,11 +205,7 @@ function spliceOutEntry(file, lines, entry) {
  * `plans`/`bugs` strings, the same `### ` text as ActionableEntryRange.title). */
 export function tryCancelEntry(root, kind, n, expectedTitle) {
     const { fileName, sectionTitle } = backlogTarget(kind);
-    return withPrimaryWorktreeLock(root, () => {
-        const located = locateDashboardEntry(root, fileName, sectionTitle, n, expectedTitle);
-        if (located.status !== "ok")
-            return located;
-        const { file, md, entry } = located;
+    return withLocatedEntry(root, fileName, sectionTitle, n, expectedTitle, ({ file, md, entry }) => {
         spliceOutEntry(file, md.split("\n"), entry);
         return { status: "cancelled", file: fileName, title: entry.title };
     });
@@ -264,11 +276,7 @@ export function tryEditEntry(root, kind, n, expectedTitle, rawTitle, rawBody) {
     const { fileName, sectionTitle } = backlogTarget(kind);
     const title = stripEntryStamp(collapseWhitespace(rawTitle));
     const body = rawBody.replace(/\r\n?/g, "\n").trim();
-    return withPrimaryWorktreeLock(root, () => {
-        const located = locateDashboardEntry(root, fileName, sectionTitle, n, expectedTitle);
-        if (located.status !== "ok")
-            return located;
-        const { file, md, entry } = located;
+    return withLocatedEntry(root, fileName, sectionTitle, n, expectedTitle, ({ file, md, entry }) => {
         const wrote = spliceInEditedEntry(file, md.split("\n"), entry, title, body);
         return { status: wrote ? "edited" : "unchanged", file: fileName, title };
     });