tumwater 0.1.2 → 0.2.0

package/dist/src/cli/log-commands.js

@@ -1,16 +1,21 @@
+// vocabulary: plain
 import { fail, say, sayJsonLine } from "./cli-output.js";
-import { durationLabel, failRivalShapes, flagValue, parseCountFlag, parseGrepFlag, parseRoleScope, parseSinceFlag } from "./cli-args.js";
+import { durationLabel, failRivalShapes, flagValue, parseCountFlag, parseGrepFlag, parseRoleScope, parseSinceFlag, parseTypeFlag } from "./cli-args.js";
 import { LOGS_SINCE_MAX_MS, readEventsSince, SPARSE_WINDOW_NOTE, } from "../events/event-window.js";
+import { compareCodeUnits, increment, sortByValueDesc } from "../collections.js";
 import { parseEventLine, readEventsTailWithEnd } from "../events/event-read.js";
 import { eventMatchesGrep, formatEvent } from "../events/event-format.js";
+import { canonicalEventType } from "../events/event-legacy.js";
+import { EVENT_TYPE_LABELS, eventTypeLabel } from "../events/event-labels.js";
 import { followFile } from "../files/tail.js";
+import { typoSuffix } from "../text/suggest.js";
 import { createTranscriptRenderer } from "../ui/transcript.js";
 import { readTranscriptTail } from "../ui/transcript-tail.js";
 import { eventsLogPath, piLogPath } from "../paths.js";
 /** The read-only observing half of the CLI's non-dispatch commands: `tumwater logs` and its
  * `--role` transcript view, split out of cli.ts so the entry point stays a dispatch table. Unlike
  * operator/operator-commands.ts these write nothing but stdout — they only read the event log and
- * each loop's pi transcript. It lives beside the other CLI command bodies (history.ts,
+ * each loop's agent transcript. It lives beside the other CLI command bodies (history.ts,
  * cli/cli-query-commands.ts, operator/operator-commands.ts), which may import the ui/ rendering
  * layer they drive — here the event formatter and the transcript renderer — while src/ui/
  * itself stays off src/ module boundaries it does not own. */
@@ -25,36 +30,90 @@ function sayEventLine(e, json) {
     else
         say(formatEvent(e));
 }
+/** Render the `--count` tally: one `N × <type>` line per present event type, most-frequent
+ * first with ties broken alphabetically by type — the single shape shared by both window
+ * sources (-n and --since), so the print and the count cannot drift on which events count.
+ * In `--json` mode it emits one compact object mapping `type → count` with keys sorted, the
+ * machine-readable twin of the prose tally. */
+function sayTally(events, json) {
+    const counts = new Map();
+    for (const e of events)
+        increment(counts, e.type);
+    if (json) {
+        const obj = {};
+        for (const [type] of [...counts.entries()].sort((a, b) => compareCodeUnits(a[0], b[0])))
+            obj[type] = counts.get(type);
+        sayJsonLine(obj);
+        return;
+    }
+    for (const [type, n] of sortByValueDesc([...counts.entries()]))
+        say(`${n} × ${eventTypeLabel(type)} (${type})`);
+}
 /** The shared rival-shape guard for logs flags that only apply to the event-log feed:
- * `--role` swaps in a pi transcript rather than the event log (--prompt requires --role, so
+ * `--role` swaps in a transcript rather than the event log (--prompt requires --role, so
  * it is excluded with it), so each such flag fails naming both. One wording for all of them —
  * the --json, --grep, and --since checks cannot drift apart in what they say or why. `active`
  * is the flag's own presence — --json alone composes with nothing here but --role, while
  * --grep and --since call from inside their own presence guards. */
 function rejectRoleViewRival(rest, flag, active) {
     if (active && (rest.includes("--role") || rest.includes("--prompt")))
-        failRivalShapes(`logs ${flag}`, "--role", "the --role view is a pi transcript, not the event log; --prompt requires --role");
+        failRivalShapes(`logs ${flag}`, "--role", "the --role view is the role's agent transcript, not the event log; --prompt requires --role");
 }
 /** The missing-pattern error cmdLogs prints for a valueless `--grep`, exported so cli.ts's
  * rejectUnknownArgs spec for --grep can fail a trailing `logs --grep` with the same wording
  * (the gate runs before the ready-repo gate and this parser, so the wordings must not drift). */
 export const GREP_VALUE_ERROR = "logs --grep needs a pattern";
+/** The missing-type error cmdLogs prints for a valueless `--type`, exported so cli.ts's
+ * rejectUnknownArgs spec for --type can fail a trailing `logs --type` with the same wording
+ * (the gate runs before the ready-repo gate and this parser, so the wordings must not drift). */
+export const TYPE_VALUE_ERROR = "logs --type needs an event type";
+/** The exact-type empty-match prose: the same no-match shape `--grep` uses, naming the type
+ * whose value matched nothing, so the two filters' empty replies cannot drift in form. Past the
+ * names, a value that is not itself a real event type picks up a did-you-mean hint (the shell
+ * completion already offers the valid codes, so a bare no-match for a near-miss reads as a silent
+ * mystery) — while a VALID type that merely has no matching events stays hint-free, a legitimate
+ * empty result rather than a typo. A valid type or a legacy alias (canonicalEventType maps the
+ * alias onto the current code, which is a label key) never hints. */
+function typeEmpty(type) {
+    const canonical = canonicalEventType(type);
+    const hint = Object.hasOwn(EVENT_TYPE_LABELS, canonical)
+        ? ""
+        : typoSuffix(type, Object.keys(EVENT_TYPE_LABELS));
+    return `no events matching "${type}"${hint}`;
+}
 /** `tumwater logs [-f] [-n <count>] [--since <duration>] [--role <id>] [--prompt]`: follow or
  * dump the harness event log, with `--since` a bounded past window of it, or with `--role` one
- * loop's pi transcript (see cmdLogsTranscript). */
+ * loop's agent transcript (see cmdLogsTranscript). */
 export async function cmdLogs(root, args) {
     // `--grep <text>` filters the event feed (the -n view and its follow): case-insensitive
     // substring against `${e.type} ${formatEvent(e)}` — the rendered line is what the operator
     // would otherwise read (WYSIWYG), and prefixing the raw type id lets stable ids
-    // (review_rejected, land_failed) be filtered even where the rendering paraphrases them.
-    // Rival shapes stay exclusive — --role swaps in a pi transcript rather than this event log
+    // (review_rejected, merge_failed) be filtered even where the rendering paraphrases them.
+    // Rival shapes stay exclusive — --role swaps in a transcript rather than this event log
     // (--prompt requires --role, so it is excluded with it), and --since is a filter of its own
     // rather than a window to filter — and each failure names both flags. The flag scan itself
     // (the value lookup, the `rest` construction that keeps a flag-shaped pattern from
     // impersonating a rival flag, and the empty-value fail) is cli/cli-args.ts's parseGrepFlag,
     // the one home shared with history's identical preamble.
-    const { rest, pattern: grepPattern } = parseGrepFlag(args, GREP_VALUE_ERROR);
+    const { rest: grepped, pattern: grepPattern } = parseGrepFlag(args, GREP_VALUE_ERROR);
+    // `--type <eventType>` filters the event feed by EXACT event type (e.type === value):
+    // deterministic where --grep substrings — a merge_failed whose rendered line quotes
+    // "merge_failed" matches --grep but not --type. Unlike --grep it composes with --since
+    // (the window, not a filter of its own) as well as -n, -f, --json, and --grep; like --json
+    // it is a rival only of the --role/--prompt transcript view. The value scan (keeping a
+    // flag-shaped value like --since as text, the empty-value fail) mirrors parseGrepFlag via
+    // parseTypeFlag, so the two cannot drift; `rest` here has both flags' value tokens removed.
+    const { rest, type } = parseTypeFlag(grepped, TYPE_VALUE_ERROR);
     const grepLower = grepPattern === null ? null : grepPattern.toLowerCase();
+    // An older event name matches its current one; the empty-match prose still names what was typed.
+    const wantedType = type === null ? null : canonicalEventType(type);
+    const typeFilter = type === null ? null : (e) => e.type === wantedType;
+    // The composed feed rule every emit site threads today's grep-only predicate through:
+    // an event passes when it is absent-or-matches the --grep substring AND absent-or-equals
+    // the --type id, held in one place so the --since window, the -n tally, and the follow
+    // cannot drift on what an event must satisfy.
+    const feedFilter = (e) => (grepLower === null || eventMatchesGrep(e, grepLower)) &&
+        (typeFilter === null || typeFilter(e));
     const follow = rest.includes("-f") || rest.includes("--follow");
     // `--json` switches the feed from formatEvent rendering to one JSON.stringify(e) per line —
     // the raw HarnessEvent objects exactly as stored in the log — so scripts read the canonical
@@ -65,6 +124,15 @@ export async function cmdLogs(root, args) {
     // excluded with it).
     const json = rest.includes("--json");
     rejectRoleViewRival(rest, "--json", json);
+    // `--count` tallies the window's present event types instead of printing the rows. Rival
+    // shapes stay exclusive: counting implies a bounded window (so -f/--follow is rejected)
+    // and the --role view is the role's agent transcript rather than the event log.
+    const count = rest.includes("--count");
+    rejectRoleViewRival(rest, "--count", count);
+    if (count && follow)
+        failRivalShapes("logs --count", "-f/--follow", "counting implies a bounded window; -f follows from now on");
+    if (type !== null)
+        rejectRoleViewRival(rest, "--type", true);
     if (grepPattern !== null) {
         rejectRoleViewRival(rest, "--grep", true);
         if (rest.includes("--since"))
@@ -74,7 +142,7 @@ export async function cmdLogs(root, args) {
     // it reads a bounded past window (event-window.ts's day-keyed backwards scan) and prints the
     // survivors oldest-first, so an operator can ask for "the hour around that 429 storm" without
     // guessing a count. Rival shapes stay exclusive — follow means "from now on", -n means "last
-    // N", and --role swaps in a pi transcript rather than this event log — and each failure names
+    // N", and --role swaps in a transcript rather than this log — and each failure names
     // both flags. (--prompt requires --role, so it is excluded with it.)
     const ms = parseSinceFlag(rest, "logs --since", LOGS_SINCE_MAX_MS);
     if (ms !== null) {
@@ -86,16 +154,29 @@ export async function cmdLogs(root, args) {
         // covered is only consulted below when the window has rows (an empty window returns
         // earlier), so the helper's vacuous empty-log branch never reaches the note here.
         const { events, covered } = readEventsSince(root, ms);
-        if (events.length === 0) {
-            // In JSON mode an empty window answers silently — an empty output IS the machine-readable
+        // `--type` composes with the window (it is NOT the --since rival --grep is): only the
+        // window events of the exact type are printed, and an all-filtered window answers with
+        // the no-match prose (the type's own line) instead of the generic empty-window one —
+        // "which merge_failed in the last hour" filters the same as it would the -n view.
+        const filtered = type === null ? events : events.filter((e) => e.type === wantedType);
+        if (filtered.length === 0) {
+            // In JSON mode an empty result answers silently — an empty output IS the machine-readable
             // answer, and prose would corrupt a consumer's NDJSON stream.
             if (!json)
-                say(`no events in ${durationLabel(ms)}`);
+                say(type === null ? `no events in ${durationLabel(ms)}` : typeEmpty(type));
             return;
         }
-        for (const e of events)
+        // `--count` composes with the window: the tally covers exactly the filtered window rows
+        // the plain view would print (and answers the empty window with the plain view's own
+        // prose above), so the two cannot disagree on which events count. Never printed with the
+        // sparse-window note below: the note rides rows, and a count has none.
+        if (count) {
+            sayTally(filtered, json);
+            return;
+        }
+        for (const e of filtered)
             sayEventLine(e, json);
-        // A sparse window is never mistaken for a quiet fleet — but the note only ever rides rows:
+        // A sparse window is never mistaken for a quiet team — but the note only ever rides rows:
         // with no rows at all (a fresh install's missing log among them) there is nothing sparse to
         // explain, and a flat "rotated out" claim would be false for a log that never had events.
         // The hedged phrasing stays true whenever it prints: the oldest retained event being inside
@@ -117,17 +198,42 @@ export async function cmdLogs(root, args) {
         return;
     }
     // -n bounds the scan, not the print: the matched subset of the last `limit` events is what
-    // appears, so `-n 200 --grep land_failed` may print 3 rows from 200 scanned. The read is
+    // appears, so `-n 200 --grep merge_failed` may print 3 rows from 200 scanned. The read is
     // the tail-with-end shape (not the per-poll cached readEvents) so the follow below can seed
     // from the byte end this very read covered instead of a later stat of the file.
     const tail = readEventsTailWithEnd(root, limit);
-    const shown = grepLower ? tail.events.filter((e) => eventMatchesGrep(e, grepLower)) : tail.events;
+    const shown = grepLower !== null || type !== null ? tail.events.filter(feedFilter) : tail.events;
+    // `--count` over the -n view answers with the tally of exactly the filtered rows the plain
+    // view would print, and carries over the plain view's empty-match prose below (a `--type`
+    // or `--grep` that matches nothing names its value; an empty unfiltered -n view prints
+    // nothing, as the plain view does). In JSON mode the empty output is the answer.
+    if (count) {
+        if (shown.length !== 0)
+            sayTally(shown, json);
+        else if (!json && (grepPattern !== null || type !== null)) {
+            if (grepPattern !== null && type !== null)
+                say(`no events matching "${grepPattern}" or ${typeEmpty(type)}`);
+            // Type-empty gets the hint (only the type branch); a grep-only empty stays the bare
+            // no-match line, because a free-text pattern is not an event type to suggest against.
+            else
+                say(type !== null ? typeEmpty(type) : `no events matching "${grepPattern ?? ""}"`);
+        }
+        return;
+    }
     for (const e of shown)
         sayEventLine(e, json);
     if (!follow) {
-        // The empty-match line is prose: in JSON mode the empty output is the answer.
-        if (grepPattern !== null && shown.length === 0 && !json)
-            say(`no events matching "${grepPattern}"`);
+        // The empty-match line is prose: in JSON mode the empty output is the answer. It fires
+        // for either filter, naming the flag's value(s) whose match came up empty so the operator
+        // knows what to loosen.
+        if (shown.length === 0 && !json && (grepPattern !== null || type !== null)) {
+            if (grepPattern !== null && type !== null)
+                say(`no events matching "${grepPattern}" or ${typeEmpty(type)}`);
+            // Type-empty gets the hint (only the type branch); a grep-only empty stays the bare
+            // no-match line, because a free-text pattern is not an event type to suggest against.
+            else
+                say(type !== null ? typeEmpty(type) : `no events matching "${grepPattern ?? ""}"`);
+        }
         return;
     }
     const file = eventsLogPath(root);
@@ -144,13 +250,13 @@ export async function cmdLogs(root, args) {
             const e = parseEventLine(line);
             // The filter holds across rotation: every event the follow callback sees goes through
             // the same match rule as the seeded window.
-            if (e && (grepLower === null || eventMatchesGrep(e, grepLower)))
+            if (e && feedFilter(e))
                 sayEventLine(e, json);
         }
     });
     await new Promise(() => { }); // Follow until Ctrl+C.
 }
-/** `tumwater logs --role <id>`: print (and optionally follow) one loop's pi transcript —
+/** `tumwater logs --role <id>`: print (and optionally follow) one loop's agent transcript —
  * run separators, abbreviated thinking, assistant text, and tool calls; with `--prompt` also
  * each run's exact prompt text. Read-only; the raw log is pi's streaming event stream, so only
  * complete renderable events are shown. */

package/dist/src/cli/notify-command.js

@@ -1,12 +1,13 @@
 import { spawn } from "node:child_process";
 import { fail, say } from "./cli-output.js";
 import { loadConfig } from "../config/config.js";
-import { notifyCommandEnv } from "../events/notify.js";
-/** The one representative allowlisted event `tumwater notify --test` fires: a failed landing
- * with loop `harness`. Fixed and opinionated — the goal is to prove the hook runs, not to
+import { TUMWATER_SOURCE } from "../events/events.js";
+import { notifyCommandEnv, notifyExitGloss } from "../events/notify.js";
+/** The one representative allowlisted event `tumwater notify --test` fires: a failed merge
+ * with source `tumwater`. Fixed and opinionated — the goal is to prove the hook runs, not to
  * replay a specific page, so there are no per-type or per-message flags. */
-const NOTIFY_TEST_TYPE = "land_failed";
-const NOTIFY_TEST_LOOP = "harness";
+const NOTIFY_TEST_TYPE = "merge_failed";
+const NOTIFY_TEST_SOURCE = TUMWATER_SOURCE;
 const NOTIFY_TEST_MESSAGE = "tumwater notify --test";
 /** How long `tumwater notify --test` waits for the hook before giving up. A hook still running
  * after this long cannot usefully page anyone — the notify channel is meant to be a quick
@@ -15,15 +16,16 @@ const NOTIFY_TEST_MESSAGE = "tumwater notify --test";
  * Generous enough not to misclassify a hook that is merely slow. */
 export const NOTIFY_TEST_TIMEOUT_MS = 10_000;
 /** Run one notify hook to completion, returning its exit code. Unlike the notifier's detached
- * fire-and-forget spawn (src/events/notify.ts), this waits with inherited stdio, so the
+ * fire-and-forget spawn (src/events/notify.ts), this waits with inherited stdio by
+ * default (the dashboard passes "ignore"), so the
  * operator sees the hook's own output and its exit. A shell that cannot start resolves 127 —
  * the conventional "command not found" code. A hook that does not finish within `timeoutMs`
  * is SIGKILLed and reported as `{ timedOut: true }` rather than awaited forever; the timer is
  * cleared on every outcome so a fast hook never keeps the CLI alive. `timeoutMs` is a test
  * seam; production callers leave it at NOTIFY_TEST_TIMEOUT_MS. */
-export function runNotifyHook(command, env, timeoutMs = NOTIFY_TEST_TIMEOUT_MS) {
+export function runNotifyHook(command, env, timeoutMs = NOTIFY_TEST_TIMEOUT_MS, stdio = "inherit") {
     return new Promise((resolve) => {
-        const child = spawn(command, [], { shell: true, stdio: "inherit", env });
+        const child = spawn(command, [], { shell: true, stdio, env });
         let settled = false;
         let timer;
         const finish = (result) => {
@@ -43,6 +45,23 @@ export function runNotifyHook(command, env, timeoutMs = NOTIFY_TEST_TIMEOUT_MS)
         child.on("error", () => finish({ code: 127 }));
     });
 }
+/** Run the saved notify hook once with the synthetic test event, under the NOTIFY_TEST_TIMEOUT_MS
+ * bound. Shared by `tumwater notify --test` (inherited stdio) and the dashboard's "Send test"
+ * (`"ignore"`, so the hook's output never lands in the server's terminal). */
+export async function testNotifyHook(root, stdio = "inherit") {
+    const command = loadConfig(root).notify;
+    if (typeof command !== "string" || command === "")
+        return { status: "not_configured" };
+    const result = await runNotifyHook(command, notifyCommandEnv(NOTIFY_TEST_TYPE, NOTIFY_TEST_SOURCE, NOTIFY_TEST_MESSAGE), NOTIFY_TEST_TIMEOUT_MS, stdio);
+    if ("timedOut" in result)
+        return { status: "ran", passed: false, message: `notify hook did not finish within ${NOTIFY_TEST_TIMEOUT_MS / 1000}s and was killed` };
+    if (result.code === 0)
+        return { status: "ran", passed: true, message: "notify hook exited 0" };
+    // The sh launch-failure gloss (same wording the real notifier warns with) names the fix
+    // for a hook that could not start: a typo'd `notify` command reads as a bare `code 127`
+    // without it.
+    return { status: "ran", passed: false, message: `notify hook exited with code ${result.code}${notifyExitGloss(result.code)}` };
+}
 /** `tumwater notify --test`: run the configured notify hook once with a synthetic event so an
  * operator can check the push channel before a real page. Read-only toward harness state — no
  * event is logged — and the exit code reflects the hook's own (0 passes, anything else fails). */
@@ -53,16 +72,12 @@ export async function cmdNotify(root, args) {
     if (typeof command !== "string" || command === "")
         fail("notify is not configured (set `notify` in tumwater.json)");
     say(`running the notify hook (TUMWATER_EVENT_TYPE=${NOTIFY_TEST_TYPE}) …`);
-    const result = await runNotifyHook(command, notifyCommandEnv(NOTIFY_TEST_TYPE, NOTIFY_TEST_LOOP, NOTIFY_TEST_MESSAGE));
-    if ("timedOut" in result) {
-        say(`notify hook did not finish within ${NOTIFY_TEST_TIMEOUT_MS / 1000}s and was killed`);
-        process.exitCode = 1;
-    }
-    else if (result.code === 0) {
-        say("notify hook exited 0");
-    }
+    const outcome = await testNotifyHook(root);
+    if (outcome.status === "not_configured")
+        fail("notify is not configured (set `notify` in tumwater.json)");
     else {
-        say(`notify hook exited with code ${result.code}`);
-        process.exitCode = 1;
+        say(outcome.message);
+        if (!outcome.passed)
+            process.exitCode = 1;
     }
 }

package/dist/src/cli/question-commands.js

@@ -1,110 +1,14 @@
-/** The CLI layer of `tumwater questions` — the open-question outbox command: list the open
- * questions in QUESTIONS.md numbered, or `answer <n> <decision>` one, which moves its entry
- * from `## Open` to `## Answered` with a dated operator answer. Split out of cli.ts because
- * the markdown surgery it performs is more than a dispatch case: the answer path must cut
- * exactly one `### ` block (fence-aware, like every backlog reader in backlog-md.ts) and extend
- * a missing `## Answered` section with the file's documented skeleton, so the loop→human→loop
- * round trip never corrupts the file the loops read at their next tick. */
-import path from "node:path";
+/** The CLI layer of `tumwater questions` — the `tumwater questions` command body: list the open
+ * questions in QUESTIONS.md numbered, or `answer <n> <decision>` one, which moves its entry from
+ * `## Open` to `## Answered` with a dated operator answer. The markdown surgery itself — the
+ * fence-aware `### ` block cut and the `## Answered` skeleton — lives in src/backlog/
+ * question-answer.ts (the shared QUESTIONS.md core the TUI and dashboard also call); this module
+ * is only the command's say/fail/editor jacket over that core, imported by src/cli/
+ * cli-query-commands.ts.
+ */
 import { fail, say, sayJson } from "./cli-output.js";
-import { fencedHeadingTitle, fenceTracker, nextSectionHeading } from "../backlog/backlog-md.js";
-import { openQuestionEntries } from "../backlog/backlog.js";
+import { openQuestionList, questionListPayload, UNCLOSED_FENCE_MESSAGE, tryAnswerQuestion } from "../backlog/question-answer.js";
 import { bodyStructureProblem, normalizeEntryBody } from "../backlog/backlog-write.js";
-import { collapseWhitespace, trimLeadingBlankLines, trimTrailingBlankLines, truncate } from "../text/text.js";
-import { readTextOrNull, writeTextAtomic } from "../files/files.js";
-import { formatDate } from "../text/datetime.js";
-import { numberedList } from "../text/markdown.js";
-import { withStateLock } from "../concurrency/lock.js";
-import { primaryWorktreeLockPath } from "../paths.js";
-/** Cap on a question's one-line body preview, so one very long first line cannot dominate
- * the `questions` list. */
-const BODY_PREVIEW_MAX = 100;
-/** The ` -- <ellipsized body>` suffix one prose list line carries for its question's first
- * body line: the `prompt --list` numbered shape, so an operator can tell two open questions
- * apart without opening the file. Truncated through text.ts's truncate — the one ellipsis
- * rule — so the preview is never longer than BODY_PREVIEW_MAX and never splits a surrogate
- * pair. Omitted for a heading-only entry. */
-function firstBodySuffix(body) {
-    const line = body
-        .split("\n")
-        .map((l) => l.trim())
-        .find((l) => l !== "");
-    if (line === undefined)
-        return "";
-    return ` — ${truncate(line, BODY_PREVIEW_MAX)}`;
-}
-/** `tumwater questions` with no arguments: the open questions numbered from 1 in file order,
- * one line each (`prompt --list`'s shape), or one line when none are open. Reads through
- * openQuestionEntries, so a missing or unreadable QUESTIONS.md degrades to "no open
- * questions" like every backlog reader. */
-export function openQuestionList(root) {
-    const questions = openQuestionEntries(root);
-    if (questions.length === 0)
-        return "no open questions";
-    return numberedList(questions.map((q) => `${q.title}${firstBodySuffix(q.body)}`));
-}
-/** The same list as data for `--json` (the backlog --json pattern: a JSON document in every
- * exit-0 case, never prose): each entry's 1-based position (the number `answer` consumes),
- * its verbatim heading text, and its full body. */
-export function questionListPayload(root) {
-    return {
-        questions: openQuestionEntries(root).map((q, i) => ({
-            position: i + 1,
-            title: q.title,
-            body: q.body,
-        })),
-    };
-}
-/** Locate QUESTIONS.md's `## Open` and `## Answered` section heading lines (fence-aware) and
- * every open entry's block between them. Returns null when the file has no `## Open` section
- * at all — then there is nothing to answer, whatever the position. */
-function scanQuestions(lines) {
-    const fenced = fenceTracker();
-    let openIdx = -1;
-    let answeredIdx = -1;
-    for (let i = 0; i < lines.length; i++) {
-        const line = lines[i] ?? "";
-        const title = fencedHeadingTitle(line, fenced, "## ");
-        if (title !== null) {
-            if (title === "Open" && openIdx === -1)
-                openIdx = i;
-            else if (title === "Answered" && answeredIdx === -1)
-                answeredIdx = i;
-        }
-    }
-    if (openIdx === -1)
-        return null;
-    // A fresh tracker for this walk: the first loop consumed every line and left the tracker in
-    // its end-of-file state, so reusing it here would quote all Open headings whenever a fence
-    // after the Open section runs unclosed to EOF — and `answer` would refuse a question the
-    // list just showed.
-    const fencedBlocks = fenceTracker();
-    // The section's end is the next `## ` heading of ANY title, fence-aware — the same boundary
-    // rule sectionLines applies, so the entries `--list` numbers (sectionEntries →
-    // parseEntryDetails) and the blocks `answer` moves can never disagree about where Open
-    // stops. Ending at the first `## Answered` instead would run the walk through any
-    // intermediate section and let one answer move another section's entries.
-    const openEnd = nextSectionHeading(lines, openIdx + 1, fencedBlocks);
-    const blocks = [];
-    // A fresh tracker for this walk too: the openEnd walk consumed the lines up to the section's
-    // end, so a fence in Open left unclosed at that boundary (an unclosed fence runs openEnd to
-    // EOF) would leave the shared tracker inside and quote every `### ` heading — answer would
-    // then see no blocks, or answer a later entry, on a file `--list` just numbered.
-    const fencedEntries = fenceTracker();
-    let current = null;
-    for (let i = openIdx + 1; i < openEnd; i++) {
-        const line = lines[i] ?? "";
-        const entryTitle = fencedHeadingTitle(line, fencedEntries, "### ");
-        if (entryTitle !== null) {
-            if (current !== null)
-                current.end = i;
-            current = { start: i, end: openEnd, title: entryTitle };
-            blocks.push(current);
-        }
-    }
-    return { openIdx, answeredIdx, openEnd, fenceOpen: fencedEntries.open(), blocks };
-}
-export const UNCLOSED_FENCE_MESSAGE = "QUESTIONS.md's ## Open section holds an unclosed code fence — every reader quotes the rest of the file as that entry's body, so answering would corrupt the file; close or remove the fence and re-run";
 /** The `tumwater questions answer` entry point: `tryAnswerQuestion` without a title check, its
  * refusals mapped to `fail` (exit 1) with the CLI's wording. Returns the answered question's
  * title plus the collapsed decision that landed in the file. */
@@ -113,10 +17,14 @@ export function answerQuestion(root, n, rawDecision) {
 }
 /** Map a non-answered outcome to the CLI's `fail` wording; shared by both CLI entry points. */
 function answeredOrFail(n, outcome) {
-    if (outcome.status === "missing")
-        fail(`no question at position ${n} (${outcome.open} open)`);
+    if (outcome.status === "missing") {
+        const range = outcome.open > 0 ? ` — valid: 1-${outcome.open}` : "";
+        fail(`no question at position ${n} (${outcome.open} open)${range}`);
+    }
     if (outcome.status === "fenced")
         fail(UNCLOSED_FENCE_MESSAGE);
+    if (outcome.status === "moved")
+        fail(`question ${n} is now "${outcome.title}" — the list changed while you edited; nothing changed`);
     if (outcome.status !== "answered")
         fail(`no question at position ${n}`);
     return { title: outcome.title, decision: outcome.decision };
@@ -124,131 +32,28 @@ function answeredOrFail(n, outcome) {
 /** `tumwater questions answer <n> --file <path>`: the decision's lines kept (normalizeEntryBody),
  * behind the same structural guard `plan --file` uses, so a stray `## ` line cannot grow a
  * phantom section. Refusals exit 1 through `fail`. */
-export function answerQuestionFromText(root, n, text) {
+export function answerQuestionFromText(root, n, text, expectedTitle) {
     const body = normalizeEntryBody(text);
     if (body === "")
         fail("questions answer needs a decision: the file is blank");
     const problem = bodyStructureProblem(body);
     if (problem !== null)
         fail(`questions answer --file: ${problem}`);
-    return answeredOrFail(n, tryAnswerQuestion(root, n, body, undefined, true));
+    return answeredOrFail(n, tryAnswerQuestion(root, n, body, expectedTitle, true));
 }
-/** The non-exiting answer core, for callers (the dashboard server) that must not end the
- * process: runs the whole read-modify-write under the cross-process primary-worktree lock
- * (paths.ts), shared with `tumwater bug`/`plan` and a landing's working-tree fast-forward, so an
- * answer and a landed change to QUESTIONS.md cannot each overwrite the other's whole-file write.
- * With `expectedTitle`, a block at position `n` titled otherwise is `moved` and nothing is
- * written; the comparison runs inside the lock, after the scan. */
-export function tryAnswerQuestion(root, n, rawDecision, expectedTitle, keepLines = false) {
-    return withStateLock(primaryWorktreeLockPath(root), () => answerQuestionLocked(root, n, rawDecision, expectedTitle, keepLines));
+/** The line that ends the decision area of the `questions answer <n>` editor buffer. */
+export const ANSWER_EDITOR_CUT = "<!-- tumwater: write your decision above this line; this line and everything below it are dropped -->";
+/** The editor buffer for bare `questions answer <n>`: an empty decision area, the cut line, then
+ * the question's heading and body for reference. */
+export function answerEditorBuffer(title, body) {
+    return ["", "", ANSWER_EDITOR_CUT, `### ${title}`, body].join("\n");
 }
-/** `tumwater questions answer <n> <decision>`: move the Nth open question's full block —
- * heading plus body, verbatim — from `## Open` to the end of `## Answered`, followed by a
- * `**Answered <today> by operator:** <decision>` paragraph stamped with the local date — the
- * positional decision is free-form operator prose, so it folds to one line (collapseWhitespace,
- * the pause `--reason` precedent): verbatim multi-line text could carry a line that starts with
- * `## ` or `### ` and grow a phantom section no reader wrote. The `--file` form (`keepLines`)
- * keeps the lines, behind bodyStructureProblem — the guard `plan --file` uses — applied by its
- * caller; a multi-line decision follows the stamp after a blank line. The Open section that is left empty regains
- * its `_None yet._` placeholder; a file with no
- * `## Answered` section gains one. Returns the outcome (see `AnswerOutcome`); on `answered`
- * the title for the confirmation line, plus the collapsed decision that actually landed in the file so callers
- * report what was written rather than the caller's raw whitespace. */
-function answerQuestionLocked(root, n, rawDecision, expectedTitle, keepLines) {
-    const decision = keepLines ? normalizeEntryBody(rawDecision) : collapseWhitespace(rawDecision);
-    const file = path.join(root, "QUESTIONS.md");
-    const md = readTextOrNull(file);
-    const lines = md === null ? null : md.split("\n");
-    const scan = lines === null ? null : scanQuestions(lines);
-    const openCount = scan === null ? 0 : scan.blocks.length;
-    if (scan === null || n < 1 || n > scan.blocks.length) {
-        return { status: "missing", open: openCount };
-    }
-    const scanned = scan;
-    // A fence inside ## Open left unclosed runs to EOF (CommonMark), so the whole tail — the
-    // real ## Answered section included — reads as quoted body of the still-open entry. Acting
-    // on that degraded read moves Answered content inside the moved block's fence and grows a
-    // second ## Answered at the file's end, while the question still lists as open: refuse
-    // instead, and tell the operator the one local repair (close or remove the fence).
-    if (scanned.fenceOpen) {
-        return { status: "fenced" };
-    }
-    const block = scanned.blocks[n - 1];
-    if (expectedTitle !== undefined && block.title !== expectedTitle)
-        return { status: "moved", title: block.title };
-    const moved = lines.slice(block.start, block.end);
-    trimTrailingBlankLines(moved);
-    // Cut the block out of ## Open: everything before it, everything from its end on. When the
-    // section is left with no content at all, restore the `_None yet._` placeholder the skeleton
-    // carries, so an empty outbox still reads as an intentionally empty section.
-    // Emptiness is judged against the Open section only (openIdx+1 .. openEnd): with an
-    // intermediate section between Open and Answered, judging against answeredIdx would keep
-    // the placeholder from returning and, worse, the empty rebuild would drop that section.
-    const openContent = lines.slice(scanned.openIdx + 1, scanned.openEnd);
-    const remaining = openContent.filter((_, i) => i < block.start - scanned.openIdx - 1 || i >= block.end - scanned.openIdx - 1);
-    const openEmpty = remaining.every((l) => l.trim() === "");
-    const rebuilt = [];
-    if (openEmpty) {
-        rebuilt.push(...lines.slice(0, scanned.openIdx + 1), "", "_None yet._", 
-        // Resume at the section that followed Open (openEnd, not answeredIdx — an intermediate
-        // section between the two must survive) with the blank separator line the dropped Open
-        // content used to carry, so `_None yet._` never reads as a paragraph glued to a heading.
-        "", ...lines.slice(scanned.openEnd));
-    }
-    else {
-        rebuilt.push(...lines.slice(0, block.start), ...lines.slice(block.end));
-    }
-    // Append the block at the end of ## Answered: before the next `## ` heading when one
-    // follows, at the file's end otherwise — the section is last in the documented skeleton.
-    const stamp = `**Answered ${formatDate(new Date())} by operator:**`;
-    const stamped = decision.includes("\n") ? [stamp, "", ...decision.split("\n")] : [`${stamp} ${decision}`];
-    const answerLines = moved.concat("", ...stamped, "");
-    if (scanned.answeredIdx === -1) {
-        // No ## Answered section: grow the file's end with the skeleton section plus the block.
-        let out = rebuilt.join("\n");
-        if (out !== "" && !out.endsWith("\n"))
-            out += "\n";
-        out += `\n## Answered\n\n${answerLines.join("\n")}`;
-        writeTextAtomic(file, out);
-        return { status: "answered", title: block.title, decision };
-    }
-    const fenced2 = fenceTracker();
-    let answeredAt = -1;
-    const placeholderAt = [];
-    for (let i = 0; i < rebuilt.length; i++) {
-        const line = rebuilt[i] ?? "";
-        if (fenced2.inside(line))
-            continue;
-        if (answeredAt === -1) {
-            if (fencedHeadingTitle(line, fenced2, "## ") === "Answered")
-                answeredAt = i;
-        }
-        else if (fencedHeadingTitle(line, fenced2, "## ") !== null) {
-            break; // The Answered section's end: a placeholder beyond it is another section's.
-        }
-        else if (line.trim() === "_None yet._") {
-            placeholderAt.push(i);
-        }
-    }
-    // A section holding only its `_None yet._` skeleton placeholder must lose the placeholder
-    // when a real entry lands there: the placeholder means "no entries", so leaving it above
-    // the moved block makes ## Answered claim to be empty while holding an answered question.
-    // Fence-aware: a `_None yet._` line quoted inside a fenced block is quoted content, never
-    // the placeholder.
-    if (placeholderAt.length > 0) {
-        const dropped = new Set(placeholderAt);
-        const stripped = rebuilt.filter((_, i) => !dropped.has(i));
-        rebuilt.length = 0;
-        rebuilt.push(...stripped);
-    }
-    const insertAt = nextSectionHeading(rebuilt, answeredAt + 1, fenced2);
-    const head = rebuilt.slice(0, insertAt);
-    const tail = rebuilt.slice(insertAt);
-    trimTrailingBlankLines(head);
-    trimLeadingBlankLines(tail);
-    const result = head.concat("", answerLines, tail);
-    writeTextAtomic(file, result.join("\n"));
-    return { status: "answered", title: block.title, decision };
+/** The decision an edited `answerEditorBuffer` holds: the text before the first cut line (all of
+ * it when the operator deleted the line). */
+export function decisionFromEditorBuffer(text) {
+    const lines = text.split("\n");
+    const cut = lines.findIndex((l) => l.trim() === ANSWER_EDITOR_CUT);
+    return (cut === -1 ? lines : lines.slice(0, cut)).join("\n");
 }
 /** The one confirmation line `questions answer` prints in prose mode: which position was
  * answered and which entry moved — `--json` swaps it for the answer result payload. */