tumwater 0.1.2 → 0.1.3

package/README.md

@@ -28,7 +28,7 @@ spend on a subscription) and is not part of `npm test`, which stays green withou
 ## Status
 
 <!-- tumwater:status:start -->
-**v0.1.1**: working harness. The director and 14 of the 15 roles are enabled by default; `telemetry`,
+**v0.1.3**: working harness. The director and 14 of the 15 roles are enabled by default; `telemetry`,
 which files harness bugs from tumwater's own event log, is opt-in (`roles.telemetry.enabled`).
 
 Open work: [PLANS.md](PLANS.md) (planned), [BUGS.md](BUGS.md) (open bugs),
@@ -38,103 +38,34 @@ Open work: [PLANS.md](PLANS.md) (planned), [BUGS.md](BUGS.md) (open bugs),
 ## Usage
 
 ```bash
-cd your-project             # a new or existing directory
+cd your-project                 # a new or existing directory
 tumwater init "Build a tiny markdown-to-html converter CLI in Python."
-                            # add --template <id> to seed from a bundled starting point
-                            # (blank, python-cli, node-cli, static-site); --list-templates
-                            # prints the catalog
-                            # add --file <path> to read the brief from a file
-                            # add --adopt to adopt an existing repo as-is
-                            # a fresh/empty project is seeded with
-                            # "bootstrap": {"untilPlansDone": 5}, holding the maintenance
-                            # loops until 5 plans are done; remove "bootstrap" from
-                            # tumwater.json to end that early
-tumwater run                # start the loops (Ctrl+C to stop)
-tumwater run --gui          # ... and serve the browser dashboard at http://127.0.0.1:7180 from the same process
-tumwater run --for 2h       # run for a bounded window (capped at 90d), then drain and exit like Ctrl+C would
-tumwater run --once         # one full round of ticks, drains its landings, and exits (for cron/CI);
-                            # add --role <id> to scope the round to one loop
+                                # --template, --file, and --adopt pick a starting point (see docs/cli.md)
+tumwater run                    # start the loops (Ctrl+C to stop)
+tumwater run --gui              # ... and serve the browser dashboard at http://127.0.0.1:7180
+tumwater run --for 2h           # run for a bounded window, then drain, summarize, and exit
+tumwater run --once             # one round of ticks for cron/CI; exits 3 if a loop's tick failed
 ```
 
-Then, from another terminal:
-
-| To | Run |
-| --- | --- |
-| Watch the fleet | `tumwater tui`, or the browser dashboard at http://127.0.0.1:7180 — `tumwater gui` on its own, or `tumwater run --gui` to boot the fleet and the dashboard together |
-| Watch per-tick history | `tumwater history [--role <id>] [-n N] [--since <duration>] [--grep <text>] [--result <changes|none|problems>]`, or `tumwater history --json` for the rows as JSON; `tumwater tick <role> <n>` for one tick's full event trail (a summary header — when it ran, how long, result, usage — followed by the tick's events, oldest first; `--last` shows the newest completed tick's trail instead of numbering one; `--json` prints the payload as JSON, `null` when the log holds no such tick) |
-| Check state | `tumwater status`, `tumwater logs -f`, `tumwater logs --since <duration>`, `tumwater logs --grep <text>`, `tumwater logs --json` (the event feed as NDJSON, for scripts), `tumwater logs --role <id>`, `tumwater queue [--json]` (the durable land queue in execution order — one line per waiting landing with its position, loop, tick, pinned sha, age, and summary; `--json` for scripts), `tumwater backlog` (planned features, open bugs, open questions as Markdown, each held entry's heading marked `[refused]`, `[needs review]`, `[needs replan]`, or `[blocked: requires …]`), `tumwater backlog --json` (the backlog as JSON, for scripts, with a `holds.plans`/`holds.bugs` array parallel to `plans`/`bugs`), `tumwater role <id>` (one loop's standing prompt — find text, `instructions` override, resolved model and interval, enabled/paused state, its notebook — plus its next tick's assembled prompt, which shows the oldest queued prompt without consuming it (one is dequeued per tick; `--json` for scripts); `--clear-notes` clears that loop's notebook and `--notes-file <path>` (`-` for stdin) replaces it (4 KB cap); the dashboard's loop drawer edits or clears the notebook the same way, and the TUI's notebook view (Ctrl+N) clears it with Ctrl+X pressed twice) |
-| See a loop's pending change | `tumwater diff --role <id>` — that loop's branch's unlanded commits (with the patch) and its worktree's uncommitted edits (staged and unstaged); without `--role`, one line per loop holding pending work; `--json` prints the payload as data |
-| Steer the project | `tumwater prompt "prefer no third-party deps"` queues a request for the director; add `--role <id>` to aim it at one loop's next tick, `--file <path>` (`-` for stdin) to read the text from a file, or `--at <duration>` to defer it until the duration passes (45s, 90m, 1h30m, 1d; capped at 90d), `tumwater prompt --list` shows the queued prompts numbered and grouped by loop, with how long each has waited (`--json` for scripts), and `tumwater prompt --cancel <n>` removes the Nth entry as `--list` shows them, and `tumwater prompt --edit <n> "new text" [--attach <path>]` rewrites the Nth entry in place (or `--edit <n> --file <path>` takes the replacement from a file), keeping its position and wait time, and appends any `--attach` images after the ones it already carries (both take `--role <id>` when several loops share that number), and `--attach <path>` (repeatable, up to 4 images — png, jpg, jpeg, gif, webp, bmp, each at most 5 MiB) attaches an image the receiving loop reads at its next tick, whether it is queued or edited; `tumwater bug "<symptom>"` files a bug into BUGS.md's Open section and wakes the bugfix loop, `tumwater plan "<title>" [body...]` — or `--file <path>` (`-` for stdin) to file one from a markdown file, its first line the title and the rest the body, kept line for line — files a plan request into PLANS.md's Planned section and wakes the feature loop — both stamped as operator-reported (the other half of `tumwater backlog`), `--list` shows a command's own entries numbered with their eligibility marks (`--json` for scripts), and `--cancel <n>` retracts one or `--edit <n> "<text>"` rewrites one in place (or `--edit <n> --file <path>` takes the replacement from a file, keeping its lines), neither with a wake; the dashboard's plan/bug drawer cancels an entry the same way, after a confirming second click, and the TUI's backlog pane does too, with Ctrl+X pressed twice on the selected entry (Ctrl+E edits its title; Ctrl+N files a new plan or bug by title and wakes its loop), the drawer edits an entry's title and body in place, and the Plans/Bugs tabs' New form files one with an optional markdown body |
-| Answer open questions | `tumwater questions` lists QUESTIONS.md's open questions numbered (as the loops wrote them); `tumwater questions answer <n> "decision text"` moves the Nth entry to ## Answered with your dated answer (`--file <path>`, `-` for stdin, records a multiline decision with its lines kept; loops read the file back on their next tick); `--json` prints the list as data; the dashboard's question drawer records an answer with its lines kept, as `--file` does, and the TUI's backlog pane answers the selected question with Ctrl+A |
-| Control the loops | `tumwater pause [--for <duration>]` / `resume [--role <id>]` (fleet or one loop; `--for 2h` auto-resumes, capped at 90d; add `--reason <text>` on a fleet pause to state why — it shows on `status`, the TUI, and the dashboard; the TUI's Ctrl+F takes a duration and reason too, and its Ctrl+P on a loop's transcript takes a duration, and its Ctrl+W takes a duration or `cancel`), `tumwater wake` (skip backoff; `wake --in 45m` schedules the wake for 45 minutes from now — the marker is written immediately but consumed no earlier than the deadline, like `pause --for`'s auto-resume, and each scheduled wake stands on its own, so later wakes do not cancel it, while `tumwater wake --cancel [--role <id>]` drops the pending scheduled wakes (or that loop's share of them), `tumwater wake --list [--role <id>] [--json]` lists them, and the dashboard's Wake later menu and loop drawer cancel pending wakes the same way; the dashboard's loop drawer schedules one loop's wake the same way ("Wake later…"); `tumwater status` and the dashboard's loop rows show the pending wake until it fires), `tumwater reclaim [--dry-run]` (drop gitignored build outputs from every harness worktree; `--dry-run` lists the candidates and cleans nothing), `tumwater retire --role <id>` (remove a disabled loop's worktree, branch, and per-role state — use after setting `enabled: false` for that role; `--force` overrides the safety rails), `tumwater abort --role <id>`, `tumwater stop` (drain and exit, like Ctrl+C), `tumwater reset-counters [--role <id>]` (zero the per-loop counters the dashboards show, starting a fresh observation window — scheduling is untouched; the dashboard's Loops card and loop drawer reach the same reset) |
-| Audit | `tumwater doctor` (pre-flight, naming a standing fleet or per-role pause or quiet-hours window holding now, today's spend against the daily cap, and the maintenance allowance's rolling-24 h use; `--json` prints the report as JSON, for scripts; the dashboard's Settings view runs the same checks in its Health check card), `tumwater report` (usage and cost, with landed commits by role and the work/maintenance split; totals include landing runs — reviewer + conflict resolution), `tumwater report --role <id>` (scopes the day or `--since` report to one loop's ticks, tokens, cost, and commits; landing runs and backlog tallies are fleet-wide and omitted; with `--failures`, scopes the failure digest to that loop too), `tumwater report --since <duration>` (totals over a trailing window, capped at 7d; with `--failures`, the failure digest over that window instead), `tumwater report --json` (the `--days`/`--since`/`--failures` reports as JSON, for scripts), `tumwater report --failures` (the failure digest: per-role outcomes, each role's time and spend by outcome, and the top five loss causes ranked by agent-hours, with a marker naming how many were cut; `--since <duration>` windows the digest over a trailing span, capped at 7d, compared against the equal-length window before it) |
-
-`tumwater help` lists every command and flag; `tumwater help <command>` shows one command's
-usage. `gui --all-interfaces` exposes the dashboard, and with it the director prompt, to your
-whole network, so pair it with `--token <secret>`.
-
-Settings live in `tumwater.json`: enabled roles, model (either one selector or a map of tiers
-`small`/`default`/`strong` — omitted tiers inherit `default`; per-tier `fallback` overrides may
-name a model or `"pause"`, and a role's `model` may name a tier; see
-[plans/model-tiers.md](plans/model-tiers.md)),
-intervals, per-role `instances` (`feature` and `bugfix` may each run 1–8 parallel runners, every one
-with its own branch and state; default 1), the daily spend cap
-(`maxDailyCostUsd`, with optional per-role caps `maxDailyCostUsdPerRole` — a loop over its own
-cap starts no new ticks until the next local day or a live edit), a
-`maintenancePerWorkLanding` ratio (default 2; a rolling 24 h allowance of that many
-code-maintenance landings per feature/bugfix/director landing, plus a floor of 12 — when the
-window reaches it the scheduler holds the enabled maintenance loops until it rolls under, and a
-fresh `tumwater wake <role>` or a queued prompt for one admits a single tick anyway), a nightly
-`quietHours` window (e.g. `"23:00-07:00"` local time) during
-which role loops start no new ticks (the director is exempt), with optional per-role windows
-`quietHoursPerRole` — a loop inside its own window starts no new ticks, whether or not the
-fleet-wide window covers now — a `diskHoldGB` free-space floor (default 10; when the volume
-holding the worktrees drops below it, no new work starts until free space recovers 5 GB above it;
-0 disables), a `diskReclaimGB` pressure-reclaim threshold (default 40; below it idle worktrees
-drop their gitignored build outputs before the hold engages; 0 disables), and a
-`worktreeIdleReclaimHours` window (default 24; an hourly pass drops a worktree's gitignored build
-outputs once it has sat unused that long, whatever the free space; 0 disables), a
-`worktreeSlots` count of pooled checkouts shared by role ticks and landing vets (default
-`maxConcurrent` + 1; the director's worktree sits outside the pool) — user-defined
-`customLoops`, and an
-optional `notify` shell command run when the fleet needs a human (a budget pause, a budget warning
-at 80% of the cap while the gate is still open, an error-streak
-breaker trip, a failed landing, a blocked restart, a posted question — the command gets
-`TUMWATER_EVENT_TYPE`, `TUMWATER_EVENT_LOOP`, and `TUMWATER_EVENT_MESSAGE` in its environment;
-verify it with `tumwater notify --test`).
-Edits apply live while the fleet runs.
-From the terminal, `tumwater config` prints the effective config as JSON, `tumwater config get
-<key>` reads one resolved value, `tumwater config set <key> <value>` writes one top-level
-key, and `tumwater config unset <key>` removes one — the inverse of `set`, so a value reverts
-to its default or disappears from its map or section; dotted keys
-(`maxDailyCostUsdPerRole.feature 1.5`, `roles.qa.model x`) merge one entry into the existing
-map or role entry, while bare keys replace the whole value. `roles` always merges the built-in
-catalog per entry at load, so a bare `config set roles` replaces the file's section but cannot
-disable a role by omission — disable one with `tumwater config set roles.<id>.enabled false`.
-
-**Backends:** any OpenAI-compatible model pi can reach works; set `model` in `tumwater.json` to
-one `provider/id[:thinking]` selector (plus `fallback` to a free selector), or a map of tiers
-`small`/`default`/`strong`. A role whose primary keeps failing with provider-class errors
-(three consecutive 429s or backend failures) runs its next ticks on its tier's resolved
-`fallback` pair and probes the primary once the 5-minute cooldown elapses, returning to it
-when a probe answers; `tumwater status`, the TUI, the dashboard, and `tumwater role <id>` name
-the off-model episode. Set `agent` to run bare selectors and the no-model default on another
-backend — `claude` runs on Claude Code, with per-tier defaults (`claude-sonnet-5-5` and
-friends) and per-backend `agents.claude.bin`/`agents.claude.args` overrides; a selector whose
-provider names a backend id (`claude/claude-opus-5-5`) always routes there. A claude run's
-cost comes from the CLI's own price table. A run paid by a claude.ai subscription is exempt
-from the daily dollar cap: its API-equivalent cost is tracked as notional spend and shown on
-its own line in `tumwater report`, never in the cap; a run billed to an API key — or one that
-saw `isUsingOverage` — counts against the cap like a priced pi model. A subscription claude
-model with no overage also counts as free for the budget badge and fallback decisions, so at
-the cap it stays put while priced pi seams move to their fallback. A rejected claude.ai
-subscription usage window holds subscription claude seams until it resets (a first
-`allowed_warning` is logged too); `tumwater status`, the TUI, the dashboard, and
-`tumwater role <id>` show the window in place of the daily spend on a subscription-only fleet
-(or beside it on a mixed one, where the daily spend covers priced seams only), and a run cut off
-by a rejected window keeps its session and worktree edits and resumes once the window resets.
-See
-[docs/backends.md](docs/backends.md) for requirements and a worked setup.
+A fresh or empty project is seeded with `"bootstrap": {"untilPlansDone": 5}`, which holds the
+maintenance loops until 5 plans are done; remove it from `tumwater.json` to end that early.
+
+From another terminal, `tumwater tui` or the browser dashboard watches the fleet, `tumwater status`
+and `tumwater logs -f` check it, `tumwater brief --file <path>` replaces the initial prompt,
+`tumwater prompt "<text>"` queues a request for the director, `tumwater plan` and `tumwater bug`
+file backlog entries, and `tumwater pause`, `resume`, `wake`, and `stop` control the loops.
+`tumwater doctor` audits the fleet and `tumwater report` shows usage and cost. `gui
+--all-interfaces` exposes the dashboard, and with it the director prompt, to your whole network,
+so pair it with `--token <secret>`.
+
+Every command, flag, and TUI key is in [docs/cli.md](docs/cli.md); `tumwater help` prints the
+same list, and `tumwater completion bash|zsh` prints shell completion. Settings live in
+`tumwater.json` and edits apply live while the fleet runs; see [docs/config.md](docs/config.md).
+
+**Backends:** any OpenAI-compatible model pi can reach works, chosen by `model` in `tumwater.json`
+with a `fallback` that a failing role switches to. `agent: "claude"` runs bare selectors on Claude
+Code instead. Requirements, the fallback and usage-window behavior, and how subscription runs are
+billed (as notional spend, outside the daily cap) are in [docs/backends.md](docs/backends.md).
 
 For how the loops, review gate, scheduling, and self-redeploy work, see
 [docs/how-it-works.md](docs/how-it-works.md). For a measured comparison of tumwater's own

package/dist/build-info.json

@@ -1,5 +1,5 @@
 {
-  "sha": "90a6c2c27eb822740efee37d84a0518b76b4d7bb",
-  "builtAt": 1791821277046,
+  "sha": "e44157e8609091b848898ab0e370e0995d931404",
+  "builtAt": 1791912860508,
   "root": "/home/runner/work/tumwater/tumwater"
 }

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

@@ -0,0 +1,31 @@
+import { loadConfigSafe } from "../config/config.js";
+import { withStateLockAsync } from "../concurrency/lock.js";
+import { currentBranch, targetBranch } from "../git/git.js";
+import { COMMIT_IDENT, gitTry } from "../git/git-run.js";
+import { primaryWorktreeLockPath } from "../paths.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. */
+export async function commitOperatorBacklogEdit(root, file, subject) {
+    try {
+        // Yield first: a synchronous caller (the TUI key handler) may write again right after this
+        // call, and that write takes the same lock synchronously — a lock already held across our
+        // awaits would block its event loop until the lock times out.
+        await new Promise((resolve) => setImmediate(resolve));
+        return await withStateLockAsync(primaryWorktreeLockPath(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, ...COMMIT_IDENT, "commit", "--only", "-m", subject, "--", file)) !== null;
+        });
+    }
+    catch {
+        return false;
+    }
+}

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

@@ -1,14 +1,14 @@
 /** Backlog eligibility: which PLANS.md / BUGS.md entries a work loop may take now (plans,
  * parallel-work-instances, part 2/7). An entry is held when its body carries a **Refused …**,
  * **Needs review …** or **Needs replan …** note, or when its heading's trailing parenthetical
- * names a prerequisite (`requires parts 1/5–3/5 landed`) that is itself still listed under
+ * (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
  * skips it without re-deriving the rule. */
 import { collapseWhitespace } from "../text/text.js";
 import { NEEDS_REPLAN_PREFIX, NEEDS_REVIEW_PREFIX } from "../roles/role-guidance.js";
 import { baseRoleOf } from "../roles/loop-ids.js";
-import { trailingParenthetical } from "./backlog-md.js";
+import { openParenthetical, trailingParenthetical } from "./backlog-md.js";
 import { actionableEntryRangesFor, stripEntryStamp } from "./backlog-structure.js";
 import { openBugEntries, plannedPlanEntries } from "./backlog.js";
 /** The `**Refused …` note prefix a refusing tick writes. Every hold note — this one and the
@@ -21,6 +21,30 @@ const REFUSED_PREFIX = "**Refused ";
 function hasNoteLine(body, prefix) {
     return body.split("\n").some((line) => line.trimStart().startsWith(prefix));
 }
+/** The text of `body`'s Refused note: the first line (ignoring leading indentation) that begins
+ * with REFUSED_PREFIX, trimmed, with the leading `**` and the first closing `**` removed. Null
+ * when no line matches — the same line-prefix rule entryHold's "refused" hold uses. */
+export function refusalNote(body) {
+    const line = body.split("\n").map((l) => l.trim()).find((l) => l.startsWith(REFUSED_PREFIX));
+    return line === undefined ? null : line.replace(/^\*\*/, "").replace("**", "");
+}
+/** `lines` without any Refused note line (the same line-prefix rule hasNoteLine applies). When a
+ * dropped note sat between two blank lines, the blank line after it goes too, so releasing
+ * leaves one blank line where the note was. Every other line, Needs-review and needs-replan
+ * notes included, is kept. */
+export function withoutRefusalNotes(lines) {
+    const out = [];
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        if (!line.trimStart().startsWith(REFUSED_PREFIX)) {
+            out.push(line);
+            continue;
+        }
+        if ((lines[i - 1] ?? "x").trim() === "" && (lines[i + 1] ?? "x").trim() === "")
+            i++;
+    }
+    return out;
+}
 /** 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, "");
@@ -83,12 +107,15 @@ export function plannedPartKeys(planned) {
     }
     return keys;
 }
-/** The prerequisite parts a plan heading's trailing parenthetical names through the clause
+/** 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 meta = trailingParenthetical(title);
+    let meta = trailingParenthetical(title);
+    if (meta === "")
+        meta = openParenthetical(title);
     if (meta === "")
         return [];
     const m = /requires\s+(.+?)\s+landed\b/i.exec(meta);
@@ -100,12 +127,20 @@ export function requiredParts(title) {
         refs.push(...parseRef(chunk, ownSeries));
     return refs;
 }
+/** 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 prerequisitesLanded(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
  * `planned` ({ blockedBy }). Series compare case-insensitively; part tokens compare verbatim.
- * Bodies mentioning "requires" are never consulted — only the heading's trailing
- * parenthetical. */
+ * Bodies mentioning "requires" are never consulted — only the heading's trailing or
+ * still-open parenthetical. */
 export function entryHold(entry, planned) {
     return entryHoldAgainst(entry, plannedPartKeys(planned));
 }

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

@@ -262,7 +262,8 @@ export function headingMetadata(lines, start) {
  * and silently dropped the epitaph's date from the day report (BUGS.md 2026-09-29). Unbalanced
  * text (no matching open paren) yields "" — the guard then treats the bullet as body text, as
  * before. The one home for this rule: entryDates reads it for `- ` epitaphs and
- * backlog-eligibility.ts's requiredParts for a heading's prerequisite clause. */
+ * backlog-eligibility.ts's requiredParts for a heading's prerequisite clause (falling back to
+ * openParenthetical when the heading's parenthetical wraps past the line). */
 export function trailingParenthetical(line) {
     if (!line.endsWith(")"))
         return "";
@@ -276,6 +277,23 @@ export function trailingParenthetical(line) {
     }
     return "";
 }
+/** The text after the outermost "(" still open at the end of `line`, or "" when every group
+ * closes: a wrapped `### ` heading's stamp parenthetical continues on the following lines, so
+ * the heading line has no closing ")". A ")" at depth 0 is ignored. */
+export function openParenthetical(line) {
+    let depth = 0;
+    let open = -1;
+    for (let i = 0; i < line.length; i++) {
+        const ch = line[i];
+        if (ch === "(") {
+            if (depth++ === 0)
+                open = i;
+        }
+        else if (ch === ")" && depth > 0)
+            depth--;
+    }
+    return depth > 0 ? line.slice(open + 1) : "";
+}
 /** A text's LAST `<dateRe>` capture — the completion rule both branches of entryDates share:
  * an entry's completion is its LAST dated verb, not the first, because found-by,
  * decomposition, and sibling mentions ("decomposed from the X bug fixed <date>") all precede

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

@@ -13,20 +13,23 @@ import { fencedHeadingTitle, fenceTracker, headingMetadata, nextSectionHeading }
 import { actionableEntryRanges, stripEntryStamp } from "./backlog-structure.js";
 import { readTextIfExists, writeTextAtomic } from "../files/files.js";
 import { formatDate } from "../text/datetime.js";
-import { fail, say, sayJson } from "../cli/cli-output.js";
+import { fail, say, sayJson, warnIfUncommitted } from "../cli/cli-output.js";
 import { parsePositionFlag, rejectRepeatFlag } from "../cli/cli-args.js";
 import { promptFileValue, readPromptFileArg } from "../cli/cli-command-args.js";
 import { plannedPlanEntries, openBugEntries } from "./backlog.js";
-import { backlogHolds, holdMark } from "./backlog-eligibility.js";
+import { backlogHolds, holdMark, withoutRefusalNotes } from "./backlog-eligibility.js";
 import { numberedList } from "../text/markdown.js";
 import { collapseWhitespace, trimLeadingBlankLines, trimTrailingBlankLines } from "../text/text.js";
 import { BUGS_TEMPLATE, PLANS_TEMPLATE } from "../init/init.js";
 import { JSON_FLAG, rejectUnknownArgs } from "../cli/cli-flag-specs.js";
 import { requireReadyRepo } from "../cli/cli-repo-gate.js";
-import { submitRolePromptAndWake } from "../operator/operator-intent.js";
+import { editInEditor } from "../cli/cli-editor.js";
+import { requestWake, submitRolePromptAndWake } from "../operator/operator-intent.js";
 import { promptLengthProblem } from "../inbox/inbox-submit.js";
 import { withStateLock } from "../concurrency/lock.js";
 import { primaryWorktreeLockPath } from "../paths.js";
+import { commitOperatorBacklogEdit } from "./backlog-commit.js";
+import { stampedSubject } from "../git/commit-message.js";
 /** Today's stamp body every operator-filed entry carries, parenthesized by the caller that
  * builds the heading. Computed once per call (not module load) so a long-lived process
  * stamps with the date it filed on. */
@@ -337,7 +340,7 @@ export async function fileAndAnnounce(root, args, command, file, role, wakeText,
         const wakeProblem = promptLengthProblem(wakeText(splitEntryFile(text).title), role);
         if (wakeProblem)
             fail(wakeProblem);
-        announceFiled(root, command, fileText(text), role, wakeText, json);
+        await announceFiled(root, command, fileText(text), role, wakeText, json);
         return;
     }
     // peelPositionals cannot serve this command: bug/plan's text is operator prose, and a
@@ -350,11 +353,12 @@ export async function fileAndAnnounce(root, args, command, file, role, wakeText,
     const wakeProblem = promptLengthProblem(wakeText(titleOf(positionals)), role);
     if (wakeProblem)
         fail(wakeProblem);
-    announceFiled(root, command, file(positionals), role, wakeText, json);
+    await announceFiled(root, command, file(positionals), role, wakeText, json);
 }
-/** The tail both fileAndAnnounce forms share: wake the `role` loop with the filed entry's
+/** The tail both fileAndAnnounce forms share: commit the entry on main, wake the `role` loop with the filed entry's
  * title, then print the confirmation (the wake line rides the prose output only). */
-function announceFiled(root, command, filed, role, wakeText, json) {
+async function announceFiled(root, command, filed, role, wakeText, json) {
+    warnIfUncommitted(await commitOperatorBacklogEdit(root, filed.file, stampedSubject("operator", `File ${command}: ${filed.title}`)), filed.file);
     const wake = submitRolePromptAndWake(root, role, wakeText(filed.title));
     sayFiled(command, filed, json);
     if (!json)
@@ -470,7 +474,9 @@ export function cancelPlan(root, n) {
  * title and body kept line for line (splitEntryFile), position and original stamp kept. A body
  * that would grow a phantom section writes nothing. */
 export function editPlanFromText(root, n, text, usage) {
-    const { title, body } = splitEntryFile(text);
+    const { title: rawTitle, body } = splitEntryFile(text);
+    // A first line pasted back as the full heading carries the entry's stamp; the splice re-adds it.
+    const title = stripEntryStamp(rawTitle);
     if (title === "")
         fail(`plan needs a title: ${usage}`);
     const problem = bodyStructureProblem(body);
@@ -481,7 +487,8 @@ export function editPlanFromText(root, n, text, usage) {
 /** `tumwater bug --edit <n> --file`: the bug twin of editPlanFromText over `## Open`. The body is
  * written as the file gives it, so a bug filed with `--file` can be revised with its body. */
 export function editBugFromText(root, n, text, usage) {
-    const { title, body } = splitEntryFile(text);
+    const { title: rawTitle, body } = splitEntryFile(text);
+    const title = stripEntryStamp(rawTitle);
     if (title === "")
         fail(`bug needs a symptom: ${usage}`);
     const problem = bodyStructureProblem(body);
@@ -547,11 +554,70 @@ export async function cancelAndAnnounce(root, args, command, cancel) {
         fail(`--cancel needs a position (usage: tumwater ${command} --cancel <n>)`);
     await requireReadyRepo(root);
     const removed = cancel(position);
+    warnIfUncommitted(await commitOperatorBacklogEdit(root, removed.file, stampedSubject("operator", `Cancel ${command}: ${removed.title}`)), removed.file);
     if (json)
         sayJson({ file: removed.file, title: removed.title });
     else
         say(`cancelled ${command} in ${removed.file}: ${removed.title}`);
 }
+/** Lift the Refused note from the `n`th entry (1-based, as `--list` numbers them) of the
+ * kind's open section and write the file, under the same lock the cancel and edit writers hold.
+ * An out-of-range position fails with locateEntry's wording; an entry without a Refused note
+ * fails too, writing nothing. */
+export function releaseEntry(root, kind, n) {
+    const fileName = kind === "bug" ? "BUGS.md" : "PLANS.md";
+    const sectionTitle = kind === "bug" ? "Open" : "Planned";
+    return withStateLock(primaryWorktreeLockPath(root), () => {
+        const { file, lines, entry } = readEntryLines(root, fileName, sectionTitle, n);
+        const slice = lines.slice(entry.start - 1, entry.end);
+        const kept = withoutRefusalNotes(slice);
+        if (kept.length === slice.length)
+            fail(`${kind} #${n} "${entry.title}" carries no Refused note`);
+        lines.splice(entry.start - 1, slice.length, ...kept);
+        writeTextAtomic(file, lines.join("\n"));
+        return { file: fileName, title: entry.title };
+    });
+}
+/** The shell of the `bug --release` and `plan --release` CLI cases, parsed as cancelAndAnnounce
+ * parses `--cancel`: `--release <n>`, an optional `--json`, anything else refused. After
+ * requireReadyRepo it releases the entry, commits the file on main, and wakes `role` (the
+ * released entry is eligible now, and that loop may be backed off) with no queued prompt. Prints
+ * `released <command> in <file>: <title>` plus the wake line, or only the `--json` payload. */
+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);
+    }
+    rejectUnknownArgs(command, rest, []);
+    if (position === null)
+        fail(`--release needs a position (usage: tumwater ${command} --release <n>)`);
+    await requireReadyRepo(root);
+    const released = release(position);
+    warnIfUncommitted(await commitOperatorBacklogEdit(root, released.file, stampedSubject("operator", `Release ${command}: ${released.title}`)), released.file);
+    const wake = requestWake(root, [role]);
+    if (json)
+        sayJson({ file: released.file, title: released.title });
+    else {
+        say(`released ${command} in ${released.file}: ${released.title}`);
+        say(wake);
+    }
+}
 /** The shared shell of the `bug --list` and `plan --list` CLI cases — the read half of the
  * operator queue whose `--edit`/`--cancel` flags address entries by position. Reads the same
  * entries, in the same file order, that locateEntry numbers for `--edit`/`--cancel`, pairs
@@ -607,6 +673,59 @@ export function listAndAnnounce(root, args, command, fileName, sectionTitle) {
     const numbered = entries.map((entry, i) => `${entry.title}${holdMark(entryHolds[i] ?? null)}`);
     say(`${noun}s in ${fileName}:\n${numberedList(numbered)}`);
 }
+/** The nth entry as the markdown file `--edit <n> --file` reads back: the stamp-stripped title
+ * and the body with its indentation kept (read from the raw lines, not the trimmed
+ * BacklogEntry.body), plus the entry's eligibility hold. Read-only. */
+function showEntry(root, kind, n) {
+    const fileName = kind === "bug" ? "BUGS.md" : "PLANS.md";
+    const sectionTitle = kind === "bug" ? "Open" : "Planned";
+    const { lines, entry } = readEntryLines(root, fileName, sectionTitle, n);
+    const meta = headingMetadata(lines, entry.start - 1);
+    const title = collapseWhitespace(stripEntryStamp(meta.text.replace(/^### /, "")));
+    const body = normalizeEntryBody(lines.slice(meta.next, entry.end).join("\n"));
+    const holds = backlogHolds(root);
+    const hold = (kind === "bug" ? holds.bugs : holds.plans)[n - 1] ?? null;
+    return { position: n, title, body, hold };
+}
+/** The shell of `bug --show` and `plan --show`: `--show <n>` (once), an optional `--json`
+ * (once), `--help`/`-h` tolerated, anything else refused through rejectUnknownArgs. Read-only
+ * like `--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;
+    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 === "--show") {
+            rejectRepeatFlag(position !== null, "--show");
+            position = parsePositionFlag("--show", args[i + 1], "--show 2");
+            i++;
+            continue;
+        }
+        if (arg === "--help" || arg === "-h")
+            continue;
+        rest.push(arg);
+    }
+    rejectUnknownArgs(command, rest, []);
+    if (position === null)
+        fail(`--show needs a position (usage: tumwater ${command} --show <n>)`);
+    const shown = showEntry(root, command, position);
+    if (json)
+        sayJson(shown);
+    else
+        say(renderShownEntry(shown));
+}
+/** The prose `--show` prints: the title, a blank line, then the body (the title alone when the
+ * body is empty). */
+function renderShownEntry(shown) {
+    return shown.body === "" ? shown.title : `${shown.title}\n\n${shown.body}`;
+}
 /** The shared shell of the `bug --edit` and `plan --edit` CLI cases, mirroring
  * fileAndAnnounce's prose classification and cancelAndAnnounce's flag handling: `--edit <n>` is
  * the one valued flag, `--json` the one boolean (at most once), `--help`/`-h` ride into the new
@@ -616,7 +735,11 @@ export function listAndAnnounce(root, args, command, fileName, sectionTitle) {
  * `edited <command> in <file>: <title>` or the `--json` payload {file, title}. Unlike
  * fileAndAnnounce there is no wake: an edit adds no work for a loop to pick up. With
  * `--file <path>` (`-` reads stdin) the new entry comes from a markdown file instead of
- * positionals: `editText` receives its text, and any positional alongside --file is refused. */
+ * positionals: `editText` receives its text, and any positional alongside --file is refused.
+ * With neither positionals nor --file the entry, rendered as `--show` prints it, opens in
+ * $VISUAL/$EDITOR and the saved buffer goes through `editText`; an unchanged buffer writes and
+ * commits nothing (`unchanged <command> <n>: <title>`), and an out-of-range position fails
+ * before the editor launches. */
 export async function editAndAnnounce(root, args, command, edit, editText) {
     const fileFlag = args.indexOf("--file");
     const path = fileFlag >= 0 ? promptFileValue(args[fileFlag + 1]) : null;
@@ -635,7 +758,25 @@ export async function editAndAnnounce(root, args, command, edit, editText) {
     if (position === null)
         fail(`--edit needs a position (usage: tumwater ${command} --edit <n>)`);
     await requireReadyRepo(root);
-    const edited = path === null ? edit(position, positionals) : editText(position, readPromptFileArg(path));
+    let text = null;
+    if (path === null && positionals.length === 0) {
+        const shown = showEntry(root, command, position);
+        const before = renderShownEntry(shown);
+        const after = editInEditor(before, `${command}-${position}.md`);
+        if (after.trim() === before.trim()) {
+            const file = command === "bug" ? "BUGS.md" : "PLANS.md";
+            if (json)
+                sayJson({ file, title: shown.title, changed: false });
+            else
+                say(`unchanged ${command} ${position}: ${shown.title}`);
+            return;
+        }
+        text = after;
+    }
+    else if (path !== null)
+        text = readPromptFileArg(path);
+    const edited = text === null ? edit(position, positionals) : editText(position, text);
+    warnIfUncommitted(await commitOperatorBacklogEdit(root, edited.file, stampedSubject("operator", `Edit ${command}: ${edited.title}`)), edited.file);
     if (json)
         sayJson({ file: edited.file, title: edited.title });
     else

package/dist/src/baseline/main-red.js

@@ -18,11 +18,11 @@ import { ensureDetachedWorktree } from "../git/worktree.js";
  * and "Tests red on main" entries), so while a SHA is known red the blocked roles skip authoring
  * instead of burning runs that are guaranteed to fail. Split out of loop.ts — which keeps the
  * tick lifecycle around it — because this is a self-contained policy with its own per-process
- * state (one harness-level warning per newly-discovered red SHA) and its own event contract; what
+ * state (one harness-level `main_red_hold` event per newly-discovered red SHA) and its own event contract; what
  * it borrows from the loop is identity and the role's worktree, and it consumes
  * build/build-check.ts's checkMainBaseline machinery (detection + execution + per-SHA cache),
  * which stays unaware of ticks. */
-/** The last main SHA for which this process logged a red-main warning (the baseline check):
+/** The last main SHA for which this process logged a red-main hold event (the baseline check):
  * one harness-level warning per newly-discovered red SHA, not one per blocked role's tick —
  * module-level so every runner in the fleet shares it. A restart re-logs once: the cache is
  * cold then too, and an operator restarting into a still-red main should see why nothing lands. */
@@ -34,14 +34,20 @@ function redMainMessage(red, action) {
     const firstLine = failureHeadline(red.outputTail);
     return `${mainRedPhrase(red.sha)} (${red.script}${firstLine ? `: ${firstLine}` : ""}) — ${action}`;
 }
-/** Log the fleet-wide red-main warning for `red`'s SHA at most once per process. Module-level
+/** Log the fleet-wide `main_red_hold` event (the notify hook pages it) for `red`'s SHA at most once per process. Module-level
  * (with lastMainRedSha) so the gate and the bugfix handoff share one guard: whichever observes
  * the red first logs it, the other stays silent. */
 function warnMainRedOnce(root, red) {
     if (lastMainRedSha === red.sha)
         return;
     lastMainRedSha = red.sha;
-    warnEventBestEffort(root, "harness", redMainMessage(red, "code merges blocked until main is green"));
+    logEventBestEffort(root, {
+        loop: "harness",
+        type: "main_red_hold",
+        sha: red.sha,
+        script: red.script,
+        message: redMainMessage(red, "code merges blocked until main is green"),
+    });
 }
 /** checkMainBaseline's per-run hook: log the one run per SHA (cache misses only) under the role
  * that paid for it, with its duration — the gate's build_check sibling, so both halves of the