tumwater 0.2.0 → 0.3.0

package/dist/src/merge/merge-to-main.js

@@ -1,14 +1,17 @@
-// vocabulary: plain
 import { openQuestions } from "../backlog/backlog.js";
 import { logEventBestEffort, warnEventBestEffort } from "../events/events.js";
-import { changeBaseRev, commitMessage, headOf } from "../git/git.js";
+import { changeBaseRev, commitMessage, headOf, patchId } from "../git/git.js";
 import { aheadOfMainFiles, treeDiffFiles } from "../git/git-diff.js";
 import { resolvedDiffDiverges } from "./merge-diff.js";
-import { conflictedFileHunks, conflictedFiles, continueRebase, ffMainToOrWhy, hasConflictMarkers, mainCommitsTouching, rebaseOntoMain, rebaseOntoMainLeaveConflicts, } from "./merge-git.js";
+import { conflictedFileHunks, conflictedFiles, continueRebase, ffMainToOrWhy, overwriteBlockedReason, primaryCheckoutBlockers, hasConflictMarkers, mainCommitsTouching, rebaseOntoMain, rebaseOntoMainLeaveConflicts, } from "./merge-git.js";
 import { resolveBacklogInsertConflicts } from "./backlog-conflicts.js";
 import { abortSync } from "../git/worktree.js";
 import { runScopedBuildCheck } from "../build/build-check-scoped.js";
-import { detectBuildCheck, gateCommandOf } from "../build/build-check-detect.js";
+import { detectBuildCheck, gateCommandOf, mergeCommandOf } from "../build/build-check-detect.js";
+import { onlyKnownMainFailures } from "../baseline/main-watch.js";
+import { unverifiedTreeOutcome } from "../build/build-check-events.js";
+import { describeCheck, failureHeadline } from "../build/build-check-report.js";
+import { MERGE_FLAKY_WARNING_PREFIX, quarantineTests } from "../review/known-flakes.js";
 import { noteGreenBaseline, noteInheritedGreen } from "../baseline/main-baseline.js";
 import { isExemptDiff } from "../review/exemptions.js";
 import { falseFixReason } from "../verdict/fix-claim.js";
@@ -24,7 +27,7 @@ import { resolverConfig } from "../config/config-views.js";
  * history linear), verify the rebased tree when it differs from what was reviewed, and
  * fast-forward. On conflict, makes one pi-driven resolution attempt
  * (outside the lock) before giving up. A routine conflict is normal operation, not a warning:
- * success merges as an ordinary `merged` event and failure surfaces via the tick's merge_conflict
+ * success merges as an ordinary `merged` event and failure surfaces via the run's merge_conflict
  * result — no separate log line for the hand-off itself. A merged diff that adds entries under
  * QUESTIONS.md's ## Open also emits one `question_posted` per new heading alongside the `merged`
  * event, so `tumwater logs` shows what the team is asking for (plans/questions-outbox.md).
@@ -80,6 +83,11 @@ async function tryMerge(ctx, wt, summary, verifiedHead) {
         // main moved between commit and merge, which under concurrency is the common case (review
         // runs outside this lock).
         const target = await headOf(wt, "HEAD");
+        const dirty = await primaryCheckoutBlockers(ctx.root, ctx.mainBranch, target);
+        if (dirty !== null) {
+            warnEventBestEffort(ctx.root, ctx.role, `merge blocked: ${overwriteBlockedReason(dirty)}`);
+            return "merge_blocked";
+        }
         if (!(await verifyMerge(ctx, wt, target, verifiedHead)))
             return "merge_blocked";
         const mainBefore = await headOf(ctx.root, ctx.mainBranch);
@@ -98,14 +106,28 @@ async function tryMerge(ctx, wt, summary, verifiedHead) {
         // Best-effort: main has already fast-forwarded, so an unwritable events feed must not turn
         // a completed merge into a rejected one and skip syncRootInstall below — the same
         // no-torn-feed policy as the orchestrator's other post-effect logging.
-        if (commit !== mainBefore)
-            logEventBestEffort(ctx.root, { source: ctx.role, type: "merged", commit, summary });
+        if (commit !== mainBefore) {
+            // The merged commit's patch-id (`mainBefore...commit`, src/git/git.ts patchId, -U0 so a
+            // re-landing onto a moved main keeps the id): the fast-merge guardrail G2 matches it
+            // against a main_revert's to spot a change that came back unchanged (plans/fast-merge.md).
+            // Computed here from the commit that actually merged (not the pre-merge pin) so a
+            // conflict-resolved merge carries the resolved change's id too. Computed after the ff
+            // because mainBefore/commit both live in the shared object store either way.
+            const mergedPatch = await patchId(wt, mainBefore, commit).catch(() => null);
+            logEventBestEffort(ctx.root, {
+                source: ctx.role,
+                type: "merged",
+                commit,
+                summary,
+                ...(mergedPatch ? { patchId: mergedPatch } : {}),
+            });
+        }
         logNewQuestions(ctx.root, before, ctx.role);
         // Still under the lock: a merge that moved main's lockfile re-syncs the root install
         // every worktree resolves through before the next merge's check runs (BUGS.md 2026-10-01).
         await syncRootInstall(ctx.root, ctx.role);
         return "changed";
-    });
+    }, ctx.lockTimeoutMs);
 }
 /** The backlog-structure cross-check both verifyMerge paths run (exempt and code diffs
  * alike): when the tree ahead of main duplicates or drops a `## ` section heading, warn on the
@@ -146,12 +168,16 @@ export async function exemptSkipBlockReason(ctx, wt, files) {
  * - a no-op rebase whose exact tree the gate verified (`rebasedHead === verifiedHead`): main
  *   did not move under us, so the merge tree is byte-identical to what the gate's pre-check
  *   already ran green. Seed the red-main baseline with the SHA that becomes main: every role's
- *   next fresh tick then hits the cache instead of re-running the full suite on an
+ *   next fresh run then hits the cache instead of re-running the full suite on an
  *   already-verified tree. A no-op rebase the gate did NOT verify — its pre-check was skipped
  *   (a timeout, a killed run) — falls through and runs the merge-scope check, which fails
  *   closed on the same timeout; an exempt diff or a project with no declared check falls
- *   through to its own arm below. Not taken when a `check.gateCommand` is configured: the gate
- *   then ran only that, not the full check.
+ *   through to its own arm below. Taken (Fast merge "Defaults") whenever a `check.mergeCommand`
+ *   resolves — to its own value or, when absent, to `check.gateCommand`. In the fallback case
+ *   (no separate `mergeCommand`) the in-lock command IS the gate command the gate already ran
+ *   green on the rebased head, so the in-lock run would add nothing; with a separate
+ *   `check.mergeCommand` the gate's green was the gate command, not the merge one. Either way
+ *   it skips and seeds nothing (the main watch decides main's verdict).
  * - doc-only delta ahead of main (the gate's own exemption test): cannot break the build.
  * - a code change whose rebased tree differs from the gate-verified one only in exempt paths
  *   (onlyExemptDriftFromVerified): main moved under the review by doc commits alone, so the
@@ -168,10 +194,15 @@ async function verifyMerge(ctx, wt, rebasedHead, verifiedHead) {
     // re-review sets verifiedHead to the resolved head, and that second rebase is then a no-op).
     // A no-op rebase the gate never verified — its pre-check timed out or was killed and left
     // GateResult.verifiedHead undefined — falls through and runs the merge-scope check, which
-    // fails closed on the same timeout. With a check.gateCommand configured the gate ran only
-    // that cheaper check, so even a verified no-op rebase must run the full check here: the
-    // merge scope is what verifies a single change (and each change of an abandoned stack),
-    // and a gateCommand green must never seed the baseline.
+    // fails closed on the same timeout. With a check.gateCommand or check.mergeCommand
+    // configured (Fast merge "Defaults": the lock runs the gate command when mergeCommand is
+    // absent): in the fallback case (no separate `mergeCommand`) the in-lock command IS the gate
+    // command the gate already ran green on the rebased head, so the verified no-op rebase adds
+    // nothing — skip it; with a separate `mergeCommand` the gate's green was the gate command.
+    // Either way it seeds nothing — a cheaper command's green never seeds the baseline: main's
+    // verdicts come from the main watch's full check on the tip.
+    if (rebasedHead === verifiedHead && mergeCommandOf(ctx.config) !== undefined)
+        return true;
     if (rebasedHead === verifiedHead && gateCommandOf(ctx.config) === undefined) {
         noteGreenBaseline(rebasedHead);
         return true;
@@ -204,19 +235,40 @@ async function verifyMerge(ctx, wt, rebasedHead, verifiedHead) {
     // runScopedBuildCheck, shared with the review gate's pre-check. The merge cell names the
     // check (or its wait for a permit) while it runs, then the merge again for the ff.
     setMergeStage(ctx.root, ctx.role, "build-check");
-    const check = await runScopedBuildCheck(ctx.root, ctx.role, "merge", wt, ctx.config, undefined, undefined, undefined, checkWaitStage(ctx.root, [ctx.role]));
+    const runMergeCheck = () => runScopedBuildCheck(ctx.root, ctx.role, "merge", wt, ctx.config, undefined, undefined, undefined, checkWaitStage(ctx.root, [ctx.role]));
+    let check = await runMergeCheck();
+    if (check?.outcome.status === "failed" && !unverifiedTreeOutcome(check.outcome) && !onlyKnownMainFailures(ctx.root, check.outcome.failingTests)) {
+        // One immediate re-run of the same tree: a pass makes the failed run a flake. The change
+        // merges and each test the failed run named is quarantined.
+        const failed = check.outcome;
+        const retry = await runMergeCheck();
+        if (retry?.outcome.status === "passed") {
+            warnEventBestEffort(ctx.root, ctx.role, `${MERGE_FLAKY_WARNING_PREFIX}${failureHeadline(failed.outputTail) ?? describeCheck(check.check)}`);
+            quarantineTests(ctx.root, failed.failingTests, failed.outputTail);
+            check = retry;
+        }
+    }
     setMergeStage(ctx.root, ctx.role, "merging");
     if (!check)
         return true; // No declared check: nothing to run, exactly like the gate skipping its pre-check.
     if (check.outcome.status === "failed") {
+        // Failing only what main already fails is not a red change: the fast-forward goes ahead, with
+        // no strike and no green seeded for a tree that did not pass.
+        const known = unverifiedTreeOutcome(check.outcome) ? null : onlyKnownMainFailures(ctx.root, check.outcome.failingTests);
+        if (known) {
+            warnEventBestEffort(ctx.root, ctx.role, `merge check fails only main's known failures: ${known.join(", ")}`);
+            return true;
+        }
         ctx.onMergeCheckRed?.(check.check, check.outcome);
         return false;
     }
     if (check.outcome.status === "skipped")
         return true; // No npm / broken toolchain — the helper already warned.
-    // Green on exactly the tree that becomes main: seed it so the next tick's red-main baseline
+    // Green on exactly the tree that becomes main: seed it so the next run's red-main baseline
     // check is a cache hit instead of one redundant full-suite run.
-    noteGreenBaseline(rebasedHead);
+    // A mergeCommand green is not the full check's: main's verdict comes from the main watch.
+    if (mergeCommandOf(ctx.config) === undefined)
+        noteGreenBaseline(rebasedHead);
     return true;
 }
 /** True, after seeding the red-main baseline, when the tree about to merge differs from the tree
@@ -229,14 +281,20 @@ async function verifyMerge(ctx, wt, rebasedHead, verifiedHead) {
  * that only rewrote SHAs) is the verified bytes themselves and seeds an observed green. Any
  * other drift seeds an inherited one, which attribution re-checks before trusting
  * (main-baseline.ts's observedOnly). Not taken without a verified head (the pre-check was skipped
- * or never ran) or with a `check.gateCommand`, for the same reasons the no-op skip above is not.
+ * or never ran). With an in-lock command configured (a gate or merge command — Fast merge
+ * "Defaults": the lock runs the gate command when mergeCommand is absent) the drift merges
+ * without a seed: the main watch decides main's verdict.
  * A git failure means "not proven" and the check runs. */
 async function onlyExemptDriftFromVerified(ctx, wt, rebasedHead, verifiedHead) {
-    if (verifiedHead === undefined || gateCommandOf(ctx.config) !== undefined)
+    if (verifiedHead === undefined)
+        return false;
+    if (gateCommandOf(ctx.config) !== undefined && mergeCommandOf(ctx.config) === undefined)
         return false;
     const drift = await treeDiffFiles(wt, verifiedHead, rebasedHead);
     if (drift === null || !isExemptDiff(drift, ctx.exemptPaths))
         return false;
+    if (mergeCommandOf(ctx.config) !== undefined)
+        return true; // no seed: the watch decides main's verdict
     if (drift.length === 0)
         noteGreenBaseline(rebasedHead);
     else
@@ -269,12 +327,13 @@ async function resolveConflict(ctx, wt, preMergeHead) {
     const files = await conflictedFiles(wt);
     // Deterministic first pass (plans/parallel-work-instances.md, part 3/7): insert-only
     // conflicts in the backlog markdown — two merges pasting different entries as the first
-    // under ## Done — carry no authored bytes, so they are settled without a model run. Only the
-    // files it could not resolve (code, or a same-entry edit) reach the resolver below.
+    // under ## Done, or new entries above an entry the other side deleted — carry no authored
+    // bytes, so they are settled without a model run. Only the files it could not resolve (code,
+    // or a same-entry edit) reach the resolver below.
     const remaining = await resolveBacklogInsertConflicts(wt, files);
     if (remaining.length === 0) {
         // A second stop is only possible when the branch holds more than the one insert-only
-        // commit. One attempt per tick.
+        // commit. One attempt per run.
         return continueOrAbortRebase(wt);
     }
     // The prompt names the project's own check, detected the way the in-lock re-check detects it,
@@ -299,10 +358,10 @@ async function resolveConflict(ctx, wt, preMergeHead) {
             change,
             main: commits,
             mainOmitted: omitted,
-        }), `tumwater-${ctx.role}-${ctx.tick}-conflict`, 
+        }), `tumwater-${ctx.role}-${ctx.runNumber}-conflict`, 
         // The resolver rides the strong tier (plans/model-tiers.md part 4/8): resolution is rare,
         // tolerant of latency, and edits code inside merge. Its spend still folds into the
-        // authoring role's usage — the fold belongs to the loop's wiring, not to the config.
+        // authoring role's usage — the fold belongs to the runner's wiring, not to the config.
         resolverConfig(ctx.config));
     }
     finally {
@@ -312,7 +371,7 @@ async function resolveConflict(ctx, wt, preMergeHead) {
         await abortSync(wt);
         return false;
     }
-    // A second stop is only possible when pi itself authored extra commits during the tick.
-    // One resolution attempt per tick.
+    // A second stop is only possible when pi itself authored extra commits during the run.
+    // One resolution attempt per run.
     return continueOrAbortRebase(wt);
 }

package/dist/src/merge/merge-top.js

@@ -0,0 +1,69 @@
+/** Operator reordering of a waiting merge (PLANS.md `tumwater queue --top <n>`): moving the
+ * Nth queued merge to the head of the execution order. Split out of merge-queue.ts so the
+ * queue stays the pure reader/writer it is: this module owns the reorder half of an
+ * unattempted entry, renaming its queue file to a stamp one below the queue's minimum — the
+ * merge-queue twin of inbox-top.ts (which does the same for the prompt queue). It mirrors
+ * inbox-top.ts's rename-and-event pairing and merge-cancel.ts's stance: no lock, one file per
+ * entry, tolerant of a concurrent drop. */
+import path from "node:path";
+import fs from "node:fs";
+import { logEventBestEffort } from "../events/events.js";
+import { errCode } from "../errno.js";
+import { queueFileName, queueFileStamp } from "../files/file-queue.js";
+import { queuedMergeFiles } from "./merge-queue.js";
+/** Move the Nth queued merge — 1-based, as `tumwater queue` numbers it and `--cancel`
+ * resolves it — to the head of the execution order, so it is the next due entry the queue
+ * takes when ready. Position 1 reports `already-first` and changes nothing; an out-of-range
+ * position (below 1 or past the readable depth) reports `out-of-range` with the current
+ * depth and changes nothing. The move is one rename: the entry JSON is never rewritten, so
+ * every field (`enqueuedAt`, `notBefore`, `retry`, `revisionRound`, `priorReview`) is
+ * unchanged; giving the file a stamp one below the queue's readable minimum sorts it first
+ * (falling back to `Date.now()` when no stamp parses), stepping one lower while the
+ * destination exists (a concurrent writer may have just taken the name we computed). One
+ * `merge_topped` event is logged under the entry's role. The rename is guarded: if the
+ * target vanished between the list and the rename (a concurrent drain took the change), the
+ * move answers `gone` and changes nothing rather than throwing. No lock and no pin write:
+ * the module mirrors merge-cancel.ts's "one file per entry, tolerant of a concurrent drop"
+ * stance. */
+export function moveQueuedMergeToTop(root, position) {
+    const files = queuedMergeFiles(root);
+    if (position < 1 || position > files.length)
+        return { status: "out-of-range", depth: files.length };
+    const target = files[position - 1];
+    if (position === 1) {
+        return {
+            status: "already-first",
+            role: target.entry.role,
+            sha: target.entry.sha,
+            summary: target.entry.summary,
+        };
+    }
+    const stamps = files
+        .map((q) => queueFileStamp(path.basename(q.file)))
+        .filter((s) => s !== null);
+    let stamp = (stamps.length > 0 ? Math.min(...stamps) : Date.now()) - 1;
+    const dir = path.dirname(target.file);
+    let newFile = path.join(dir, queueFileName(stamp, 0, ".json"));
+    while (fs.existsSync(newFile)) {
+        stamp--;
+        newFile = path.join(dir, queueFileName(stamp, 0, ".json"));
+    }
+    try {
+        fs.renameSync(target.file, newFile);
+    }
+    catch (err) {
+        // The queue drained the target between our list and this rename (an orchestrator took
+        // the change): a concurrent drop is a normal race, never an error — the entry has
+        // already left the queue, so there is nothing to top. Any other rename failure is real.
+        if (errCode(err) === "ENOENT")
+            return { status: "gone" };
+        throw err;
+    }
+    logEventBestEffort(root, {
+        source: target.entry.role,
+        type: "merge_topped",
+        commit: target.entry.sha,
+        summary: target.entry.summary,
+    });
+    return { status: "topped", role: target.entry.role, sha: target.entry.sha, summary: target.entry.summary };
+}

package/dist/src/merge/merge-verify.js

@@ -1,11 +1,10 @@
-// vocabulary: plain
 import fs from "node:fs";
 import path from "node:path";
 import { gateRoleConfig } from "../gates/budget-gates.js";
 import { reviewRunConfig, seamConcurrencyKey } from "../config/config-views.js";
 import { providerWaitStage } from "./merge-slot.js";
 import { withProviderLease } from "../concurrency/provider-lease.js";
-import { LoopRunner } from "../loop/loop.js";
+import { RoleRunner } from "../runner/runner.js";
 import { branchHead, isMergedInto } from "../git/git.js";
 import { addMergeChange, mergeUsage, removeMergeChange, setMergeChangeStatus } from "./merge-slot.js";
 import { dropMerge, entryRevisionFields, queuedMergeFiles, staleHeadFile } from "./merge-queue.js";
@@ -28,21 +27,21 @@ export function verifyLimit(maxConcurrent) {
 /** Resolve a merge entry's authoring runner: the live runner when the role is enabled
  * (runners are never removed from the array on disable — only a warning event fires); a role
  * disabled before this process started has no runner, so a throwaway one supplies the same
- * wiring (loop-pi.ts, runMergePi, foldMergeUsage) and a disk-loaded state to fold and save
+ * wiring (runner-pi.ts, runMergePi, foldMergeUsage) and a disk-loaded state to fold and save
  * on. Both share the live config, like every runner — the director takes directorConfig (the live
  * config, its budget-gate exemption, unless a used-up window moved it), every other role takes
  * roleConfig (gateRoleConfig's single home for the rule; the scheduler assigns the live runners
  * by it every poll). */
-function resolveAuthor(ctx, role) {
+export function resolveAuthor(ctx, role) {
     const { root, mainBranch, signal, runners, liveConfig, roleConfig, directorConfig } = ctx;
     return (runners.find((r) => r.role === role) ??
-        new LoopRunner(root, role, gateRoleConfig(role, liveConfig, roleConfig, directorConfig), mainBranch, signal));
+        new RoleRunner(root, role, gateRoleConfig(role, liveConfig, roleConfig, directorConfig), mainBranch, signal));
 }
 /** Drop a torn queue head. A torn head (torn or foreign — a partial write an older build left,
  * a hand-placed file) makes headMerge read null forever — nothing else drops it, stranding
- * every live entry behind it and pinning their authors' ticks via the interlock. Drop it with
+ * every live entry behind it and pinning their authors' runs via the interlock. Drop it with
  * one warning; the healthy entries behind it are verified in the same poll. The crashed
- * entry's commit, if any, still rides its merge ref into next-tick leftover recovery
+ * entry's commit, if any, still rides its merge ref into next-run leftover recovery
  * (BUGS.md 2026-09-17). */
 function dropTornHead(root) {
     const stale = staleHeadFile(root);
@@ -98,6 +97,9 @@ export async function drainVerify(ctx, p) {
             return;
         if (liveRoles(p).has(entry.role))
             continue;
+        // A re-queued review_error waits out its delay; the entry stays queued and holds its author.
+        if (entry.notBefore !== undefined && Date.now() < entry.notBefore)
+            continue;
         if (await mergedIntoMain(ctx.root, entry.sha, ctx.mainBranch, mainHead)) {
             dropMerge(file);
             removeMergeChange(ctx.root, entry.role);
@@ -163,10 +165,10 @@ export function startVerify(ctx, p, entry, file) {
                 // so a review run that lands on a different provider than the verification's review seam
                 // re-keys it there, and a re-key park is shown by providerWaitStage; its slot wait drops
                 // the key (pool-slot rule).
-                verdict = await withProviderLease(lease, semaphore, () => verifyRequest({ root, mainBranch, config: author.config, signal: () => verify.controller.signal, runGatePi: (opts) => author.runGatePi(opts) }, {
+                verdict = await withProviderLease(lease, semaphore, () => verifyRequest({ root, mainBranch, config: author.config, signal: () => verify.controller.signal, runGatePi: (opts) => author.runGatePi(opts), reviewHeld: () => ctx.startHeld() }, {
                     role,
                     sha: entry.sha,
-                    tick: entry.run,
+                    runNumber: entry.run,
                     summary: entry.summary,
                     body: entry.body,
                     highFriction: entry.highFriction,
@@ -198,7 +200,7 @@ export function startVerify(ctx, p, entry, file) {
             }
             else {
                 const result = verdict.kind === "stack" ? "aborted" : verdict.result;
-                await settleMergeOutcome(root, entry, author.state, result, Date.now() - startedAt, usage, file);
+                await settleMergeOutcome(root, entry, author.state, result, Date.now() - startedAt, usage, file, mainBranch);
                 if (verify.userAborted)
                     await discardPinnedRefs(root, [role]);
             }

package/dist/src/notes-cli.js

@@ -1,5 +1,4 @@
 #!/usr/bin/env node
-// vocabulary: plain
 /** The `tumwater-notes` command — the second bin entry (dist/src/notes-cli.js), the one
  * carrier for writing a role's note on every backend (plans/notes-command.md "The
  * `tumwater-notes` command"). A run finds it on its PATH (src/agent/notes-shim.ts) and hands
@@ -14,9 +13,12 @@
  *   show             print the note (nothing when there is none)
  *   clear            empty the note
  *
- * Exits 0 on success, 1 on a refusal (empty input, over-cap note, or no
- * TUMWATER_NOTES_PATH), and 2 with usage for anything else. */
+ * Exits 0 on success, 1 on a refusal (empty input, over-cap note, a note file that cannot be
+ * written or read, or no TUMWATER_NOTES_PATH), and 2 with usage for an unknown subcommand (a
+ * known subcommand with bad arguments refuses with usage and exit 1). */
 import fs from "node:fs";
+import { readTextIfExists } from "./files/files.js";
+import { errorMessage } from "./text/text.js";
 import { validateRoleNote, writeRoleNote } from "./agent/role-notes-write.js";
 /** The note's path, read ONLY from the environment — never from an argument. */
 const NOTES_PATH = process.env.TUMWATER_NOTES_PATH;
@@ -29,14 +31,10 @@ const USAGE = [
 function readStdin() {
     return fs.readFileSync(0, "utf8");
 }
-/** Read the note's current text; a missing note reads as empty (show prints nothing). */
+/** Read the note's current text; a missing note reads as empty (show prints nothing). Any
+ * other read failure (EACCES, EISDIR) throws, so it is never mistaken for an empty note. */
 function readNote() {
-    try {
-        return fs.readFileSync(NOTES_PATH, "utf8");
-    }
-    catch {
-        return "";
-    }
+    return readTextIfExists(NOTES_PATH) ?? "";
 }
 /** Refuse with `message` on stderr and exit 1 — the exit code for every expected refusal. */
 function refuse(message) {
@@ -51,7 +49,12 @@ function writeNote(text) {
     const error = validateRoleNote(text);
     if (error)
         return refuse(error);
-    writeRoleNote(NOTES_PATH, text);
+    try {
+        writeRoleNote(NOTES_PATH, text);
+    }
+    catch (err) {
+        return refuse(`could not save the note: ${errorMessage(err)}`);
+    }
     process.stdout.write(`notes saved (${Buffer.byteLength(text, "utf8")} bytes)\n`);
     return 0;
 }
@@ -72,8 +75,8 @@ function main() {
                 try {
                     text = fs.readFileSync(flagArg, "utf8");
                 }
-                catch {
-                    return refuse(`cannot read ${flagArg}`);
+                catch (err) {
+                    return refuse(`cannot read ${flagArg}: ${errorMessage(err)}`);
                 }
                 return writeNote(text);
             }
@@ -81,12 +84,24 @@ function main() {
         case "show":
             if (flag !== undefined)
                 return refuse(USAGE);
-            process.stdout.write(readNote());
+            let note;
+            try {
+                note = readNote();
+            }
+            catch (err) {
+                return refuse(`could not read the note: ${errorMessage(err)}`);
+            }
+            process.stdout.write(note);
             return 0;
         case "clear":
             if (flag !== undefined)
                 return refuse(USAGE);
-            writeRoleNote(NOTES_PATH, "");
+            try {
+                writeRoleNote(NOTES_PATH, "");
+            }
+            catch (err) {
+                return refuse(`could not clear the note: ${errorMessage(err)}`);
+            }
             process.stdout.write("notes cleared\n");
             return 0;
         default: