tumwater 0.2.0 → 0.3.0

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

@@ -0,0 +1,148 @@
+/** The write guard on a run's file-editing tools: pi's `edit`/`write` (src/pi-extension/
+ * write-guard.ts), claude's `Edit`/`Write` (src/agent/claude/write-guard-hook.ts) and OpenCode's
+ * `edit` permission (src/agent/opencode/write-guard-plugin/index.ts) refuse a write that would
+ * land under the team root but outside the run's own checkout.
+ *
+ * Why a guard and not only the prompt rule: every run's checkout sits inside the primary checkout
+ * (`<root>/.tumwater/worktrees/<name>`). An absolute path that drops that infix, or a relative one
+ * that climbs out with `../../..`, names a real file with the same contents in the primary
+ * checkout or in another run's slot, so the edit succeeds and nothing says it went astray. The run
+ * then commits its unchanged checkout. runner-run.ts's stray-write warning only notices afterwards
+ * and cannot say which run wrote. Refusing at the tool lets the model retry at the path the
+ * refusal names.
+ *
+ * Writes outside the team root (scratch files under `$TMPDIR`, `/tmp`) are not this guard's
+ * business and pass, as does every write from a run that is not in a team worktree. Bash is not
+ * covered: a shell command's writes cannot be read from its text. The codex backend is not
+ * covered yet.
+ *
+ * Pure apart from realpath lookups, so the rule is testable without pi or claude. */
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { roleNotesPath, STATE_DIR, worktreesDir } from "../paths.js";
+/** True when `p` is `dir` or inside it. Both are absolute and normalized. */
+function isWithin(p, dir) {
+    const rel = path.relative(dir, p);
+    return rel === "" || (rel !== ".." && !rel.startsWith(`..${path.sep}`) && !path.isAbsolute(rel));
+}
+/** `p` with its longest existing prefix resolved through realpath, so a symlink, a `/tmp` that is
+ * `/private/tmp`, or a path typed in the wrong case on a case-insensitive disk compares as the
+ * file it reaches. The part that does not exist yet (a file a write would create) is appended
+ * unchanged. */
+function realish(p) {
+    let existing = p;
+    const rest = [];
+    for (;;) {
+        try {
+            return path.join(fs.realpathSync.native(existing), ...rest);
+        }
+        catch {
+            const parent = path.dirname(existing);
+            if (parent === existing)
+                return p;
+            rest.unshift(path.basename(existing));
+            existing = parent;
+        }
+    }
+}
+/** A tool's path argument as pi's tools resolve it (pi `resolveToCwd`): a leading `@` dropped,
+ * `~` expanded to the home directory, and a relative path taken from `base`. */
+function resolveToolPath(target, base) {
+    let p = target.startsWith("@") ? target.slice(1) : target;
+    if (p === "~")
+        p = os.homedir();
+    else if (p.startsWith("~/"))
+        p = path.join(os.homedir(), p.slice(2));
+    return path.resolve(base, p);
+}
+/** The team checkout `dir` is in, or null when it is in none. Read from the path's shape: the
+ * innermost `<root>/.tumwater/worktrees/<name>` that holds `dir`. The nearest ancestor holding a
+ * `.tumwater` directory would not do, because a run's own tests can leave one inside its checkout
+ * (one sat in `_slot-3` on 2026-10-23), and then the primary checkout would read as outside the
+ * team and every write to it would pass. */
+function runCheckoutOf(dir) {
+    const real = realish(path.resolve(dir));
+    const marker = `${path.sep}${STATE_DIR}${path.sep}worktrees${path.sep}`;
+    const at = real.lastIndexOf(marker);
+    if (at < 0)
+        return null;
+    const root = real.slice(0, at) || path.sep;
+    const name = real.slice(at + marker.length).split(path.sep)[0];
+    if (!name)
+        return null;
+    return { root, checkout: path.join(worktreesDir(root), name) };
+}
+/** `s` single-quoted for sh (the `'…'` quoting every hook command in both backends embeds a path
+ * in). The one home of a POSIX-shell single-quote, shared by the claude and codex write-guard
+ * settings builders (src/agent/claude/claude-write-guard.ts, src/agent/codex/codex-write-guard.ts)
+ * so the escape cannot drift between the backends. A path with a single quote becomes
+ * `'…'\''…'`, which sh assembles back into the original. */
+export function shellQuote(s) {
+    return `'${s.replace(/'/g, `'\\''`)}'`;
+}
+/** The refusal text for a write to `target` from a run whose checkout holds `runDir`, or null when
+ * the write may go ahead. A relative `target` resolves from `resolveFrom` (default `runDir`): pi
+ * resolves from the run's directory, while claude resolves from its shell's current directory,
+ * which the hook receives separately. The text names the corrected path inside the checkout
+ * whenever the stray path has a twin there. */
+export function strayWriteRefusal(target, runDir, resolveFrom = runDir) {
+    const run = runCheckoutOf(runDir);
+    if (!run)
+        return null;
+    const abs = realish(resolveToolPath(target, resolveFrom));
+    if (isWithin(abs, run.checkout) || !isWithin(abs, run.root))
+        return null;
+    const { root, checkout } = run;
+    let where;
+    let rest = [];
+    let instead = null;
+    if (isWithin(abs, worktreesDir(root))) {
+        const [other, ...inside] = path.relative(worktreesDir(root), abs).split(path.sep);
+        where = `another checkout (${other ?? ""})`;
+        rest = inside;
+    }
+    else if (isWithin(abs, path.join(root, STATE_DIR))) {
+        where = "tumwater's own state";
+        if (isWithin(abs, path.dirname(roleNotesPath(root, "role")))) {
+            instead = "Save role notes with `tumwater-notes write` instead.";
+        }
+    }
+    else {
+        where = "the primary checkout";
+        rest = path.relative(root, abs).split(path.sep).filter(Boolean);
+        // The worktree borrows the primary's dependencies; a twin path would create a node_modules
+        // inside the worktree and break that borrowing.
+        if (rest[0] === "node_modules")
+            rest = [];
+    }
+    if (rest.length > 0) {
+        instead = `Write ${path.join(checkout, ...rest)} instead: your worktree has the same files.`;
+    }
+    return `Refused: ${abs} is in ${where}, outside this run's worktree ${checkout}. Only changes `
+        + `inside the worktree are committed, so this write would be lost. `
+        + (instead ?? "Leave it alone and work only inside the worktree.");
+}
+/** The stdin-driven guard-hook driver shared by the claude and codex PreToolUse hooks
+ * (src/agent/claude/write-guard-hook.ts, src/agent/codex/write-guard-hook.ts). Each hook runs as
+ * `node write-guard-hook.js` with the backend's hook payload JSON on stdin; this reads it in one
+ * place, asks `computeRefusal` for a refusal string (null lets the edit/patch run), and prints the
+ * `deny` decision only when there is a refusal. Any failure — unreadable stdin, malformed JSON, a
+ * throw — reads as "no refusal" (null), so a broken hook cannot stop every edit of a run; the
+ * stray-write warning in runner-run.ts still sees a write that slips through. The deny payload's
+ * shape (`hookSpecificOutput` with a `PreToolUse` deny and the refusal as its reason) lives only
+ * here so the two hooks cannot drift it apart. */
+export function runGuardHook(computeRefusal) {
+    let refusal = null;
+    try {
+        refusal = computeRefusal(JSON.parse(fs.readFileSync(0, "utf8")));
+    }
+    catch {
+        refusal = null;
+    }
+    if (refusal !== null) {
+        process.stdout.write(`${JSON.stringify({
+            hookSpecificOutput: { hookEventName: "PreToolUse", permissionDecision: "deny", permissionDecisionReason: refusal },
+        })}\n`);
+    }
+}

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

@@ -1,4 +1,3 @@
-// vocabulary: plain
 /** The backlog archive (plans/backlog-archive.md): finished entries leave the live backlog files.
  *
  * Every role run reads PLANS.md and BUGS.md to find work, and by 2026-10-18 nine tenths of both
@@ -16,21 +15,25 @@
  * - archiveFinishedOnMain, at team start and from `tumwater archive`: the whole live section —
  *   legacy entries, compressed one-line records, a hand commit's move — goes to the archive in
  *   one commit on main.
+ * Neither archives an entry twice: one whose heading the archive already holds is dropped from
+ * the live section when its text matches, and left there when it does not (archiveFinishedText).
  * Readers of finished entries read the live section first, then the archive (backlog.ts). */
 import fs from "node:fs";
 import path from "node:path";
-import { withLock, withStateLockAsync } from "../concurrency/lock.js";
+import { withLock, withPrimaryWorktreeLockAsync } from "../concurrency/lock.js";
 import { loadConfigSafe } from "../config/config.js";
 import { logEventBestEffort, TUMWATER_SOURCE, warnEventBestEffort } from "../events/events.js";
-import { readTextOrNull, writeTextAtomic } from "../files/files.js";
+import { readTextIfExists, readTextOrNull, writeTextAtomic } from "../files/files.js";
 import { changeBaseRev, currentBranch, fileContentAt, headOf, targetBranch } from "../git/git.js";
 import { stampedSubject } from "../git/commit-message.js";
-import { COMMIT_IDENT, git, gitTry } from "../git/git-run.js";
-import { mergeLockDir, primaryWorktreeLockPath } from "../paths.js";
+import { commitAuthorArgs, committerIdentArgs, git, gitTry } from "../git/git-run.js";
+import { mergeLockDir } from "../paths.js";
 import { plural } from "../text/phrases.js";
-import { collapseWhitespace, errorMessage } from "../text/text.js";
-import { FINISHED_ARCHIVES, fenceTracker, fencedHeadingTitle } from "./backlog-md.js";
-import { actionableEntryRanges } from "./backlog-structure.js";
+import { collapseWhitespace, errorFirstLine, errorMessage } from "../text/text.js";
+import { FINISHED_ARCHIVES, fenceTracker, fencedHeadingTitle, parseEntryDetails } from "./backlog-md.js";
+import { actionableEntryRanges, strandedPlanEntries } from "./backlog-structure.js";
+import { appendBugEntryLocked } from "./backlog-write.js";
+import { formatDate } from "../text/datetime.js";
 /** The placeholder a role leaves under an emptied section: never archived content. */
 const PLACEHOLDER = /^_None yet\._$/;
 /** The text a new archive file starts with: a title, how to read the file, and the section
@@ -94,9 +97,46 @@ function withSectionBody(lines, span, body) {
 function entriesIn(md, span, section) {
     return actionableEntryRanges(md, section).filter((e) => e.start - 1 > span.heading && e.start - 1 < span.end);
 }
+/** An entry's text for the already-archived comparison: its lines without the blank lines around
+ * them, each without trailing whitespace. */
+function entryText(lines, e) {
+    return trimBlank(lines.slice(e.start - 1, e.end)).map((l) => l.trimEnd()).join("\n");
+}
+/** The fate of each of `selected` (entries of `lines`), in order, against the archive's entries:
+ * every text the archive holds under each heading key. */
+function entryFates(lines, selected, archiveMd, archiveSpan, section) {
+    if (selected.length === 0)
+        return [];
+    const wanted = new Set(selected.map((e) => archiveKey(e.title)));
+    const archiveLines = archiveMd.split("\n");
+    const archived = new Map();
+    for (const e of entriesIn(archiveMd, archiveSpan, section)) {
+        const key = archiveKey(e.title);
+        if (wanted.has(key))
+            archived.set(key, [...(archived.get(key) ?? []), entryText(archiveLines, e)]);
+    }
+    return selected.map((e) => {
+        const held = archived.get(archiveKey(e.title));
+        if (held === undefined)
+            return "move";
+        return held.includes(entryText(lines, e)) ? "drop" : "stay";
+    });
+}
+/** The trimmed lines of `entries`, one blank line between entries. */
+function entryBlocks(lines, entries) {
+    const out = [];
+    for (const e of entries) {
+        if (out.length > 0)
+            out.push("");
+        out.push(...trimBlank(lines.slice(e.start - 1, e.end)));
+    }
+    return out;
+}
 /** Move the selected part of `liveMd`'s finished section to the top of `archiveMd`'s (a new
- * archive starts from archiveTemplate), keeping the moved lines' order. null when nothing moves,
- * when either file lacks the section heading, or — for the commit-time sweep — when there is no
+ * archive starts from archiveTemplate), keeping the moved lines' order. A selected entry whose
+ * heading the archive already holds never moves (EntryFate): with the same text it is dropped
+ * from the live section, with other text it stays there. null when nothing moves or drops, when
+ * either file lacks the section heading, or — for the commit-time sweep — when there is no
  * archive yet and the live section holds other content: a repository that has not been archived
  * keeps today's layout until `tumwater archive` (or the next team start) moves its history, so an
  * archive never sits above older live entries. Pure. */
@@ -106,52 +146,71 @@ export function archiveFinishedText(liveMd, archiveMd, spec, select) {
     if (span === null)
         return null;
     const entries = entriesIn(liveMd, span, spec.section);
+    const selected = "keep" in select
+        ? entries.slice(Math.max(0, select.keep))
+        : entries.filter((e) => !select.baseKeys.has(archiveKey(e.title)) && !(select.park?.has(archiveKey(e.title)) ?? false));
+    if (!("keep" in select) && selected.length === 0)
+        return null;
+    const archiveText = archiveMd ?? archiveTemplate(spec);
+    const archiveLines = archiveText.split("\n");
+    const archiveSpan = sectionSpan(archiveLines, spec.section);
+    if (archiveSpan === null)
+        return null;
+    const fates = entryFates(lines, selected, archiveText, archiveSpan, spec.section);
+    const withFate = (fate) => selected.filter((_, i) => fates[i] === fate);
+    // The 0-based live lines of the entries that leave the live section without moving.
+    const droppedLine = new Set();
+    for (const e of withFate("drop"))
+        for (let i = e.start - 1; i < e.end; i++)
+            droppedLine.add(i);
     let moved;
     let kept;
-    let titles;
     if ("keep" in select) {
         const from = select.keep <= 0 ? span.heading + 1 : (entries[select.keep]?.start ?? 0) - 1;
         if (from < 0)
             return null; // no entry past the kept ones
-        // A `_None yet._` placeholder stays in the live section, never in the archive.
-        const tail = lines.slice(from, span.end);
+        // The tail moves but for the dropped and staying entries; a `_None yet._` placeholder stays
+        // in the live section, never in the archive. Staying entries follow the kept ones.
+        const stayLine = new Set();
+        for (const e of withFate("stay"))
+            for (let i = e.start - 1; i < e.end; i++)
+                stayLine.add(i);
+        const tail = [];
+        for (let i = from; i < span.end; i++)
+            if (!droppedLine.has(i) && !stayLine.has(i))
+                tail.push(lines[i] ?? "");
         moved = trimBlank(tail.filter((l) => !PLACEHOLDER.test(l.trim())));
-        kept = select.keep <= 0 ? [] : trimBlank(lines.slice(span.heading + 1, from));
+        const staying = entryBlocks(lines, withFate("stay"));
+        const head = select.keep <= 0 ? [] : trimBlank(lines.slice(span.heading + 1, from));
+        kept = head.length > 0 && staying.length > 0 ? [...head, "", ...staying] : [...head, ...staying];
         if (kept.length === 0)
             kept = tail.filter((l) => PLACEHOLDER.test(l.trim())).slice(0, 1);
-        titles = entries.slice(Math.max(0, select.keep)).map((e) => e.title);
     }
     else {
-        const fresh = entries.filter((e) => !select.baseKeys.has(archiveKey(e.title)));
-        if (fresh.length === 0)
-            return null;
-        const inFresh = (i) => fresh.some((e) => i >= e.start - 1 && i < e.end);
+        const leaves = new Set(droppedLine);
+        for (const e of withFate("move"))
+            for (let i = e.start - 1; i < e.end; i++)
+                leaves.add(i);
         kept = [];
         for (let i = span.heading + 1; i < span.end; i++)
-            if (!inFresh(i))
+            if (!leaves.has(i))
                 kept.push(lines[i] ?? "");
         kept = trimBlank(kept);
         if (archiveMd === null && kept.some((l) => l.trim() !== "" && !PLACEHOLDER.test(l.trim())))
             return null;
-        moved = [];
-        for (const e of fresh) {
-            if (moved.length > 0)
-                moved.push("");
-            moved.push(...trimBlank(lines.slice(e.start - 1, e.end)));
-        }
-        titles = fresh.map((e) => e.title);
+        moved = entryBlocks(lines, withFate("move"));
     }
-    if (moved.length === 0)
-        return null;
-    const archiveLines = (archiveMd ?? archiveTemplate(spec)).split("\n");
-    const archiveSpan = sectionSpan(archiveLines, spec.section);
-    if (archiveSpan === null)
+    const dropped = withFate("drop").map((e) => e.title);
+    if (moved.length === 0 && dropped.length === 0)
         return null;
     const existing = trimBlank(archiveLines.slice(archiveSpan.heading + 1, archiveSpan.end));
     return {
         live: withSectionBody(lines, span, kept),
-        archive: withSectionBody(archiveLines, archiveSpan, existing.length > 0 ? [...moved, "", ...existing] : moved),
-        titles,
+        archive: moved.length === 0
+            ? archiveText
+            : withSectionBody(archiveLines, archiveSpan, existing.length > 0 ? [...moved, "", ...existing] : moved),
+        titles: withFate("move").map((e) => e.title),
+        dropped,
     };
 }
 /** Write one move: the archive first, so a crash in between leaves the entries in both files —
@@ -163,22 +222,38 @@ function writeMove(root, spec, move) {
 /** The commit-time sweep: move the entries this change added to a live finished section of the
  * worktree `wt` — those whose heading its merge-base with `mainBranch` did not hold there — to
  * the top of the archive file, writing both files. Runs right before a run's commit, so the
- * commit, the review and the merge see the archived form. Returns what moved; a file whose
- * section is missing, or a repository not yet archived (archiveFinishedText), moves nothing. */
+ * commit, the review and the merge see the archived form. An added entry the archive already
+ * holds is dropped or left in place instead (archiveFinishedText), never archived twice. Returns
+ * what moved; a file whose section is missing, or a repository not yet archived, moves nothing. */
 export async function archiveNewFinishedEntries(wt, mainBranch) {
     const baseRev = await changeBaseRev(wt, mainBranch);
     const out = [];
     for (const spec of FINISHED_ARCHIVES) {
-        const live = readTextOrNull(path.join(wt, spec.file));
+        const live = readTextIfExists(path.join(wt, spec.file));
         if (live === null)
             continue;
         const base = await fileContentAt(wt, baseRev, spec.file);
         const baseKeys = new Set(actionableEntryRanges(base, spec.section).map((e) => archiveKey(e.title)));
-        const move = archiveFinishedText(live, readTextOrNull(path.join(wt, spec.archive)), spec, { baseKeys });
+        // The gate's new-plan-under-Done rule (backlog-structure.ts part 4/4) rejects a PLANS.md
+        // ### entry under ## Done that carries `(planned …)` but no `done YYYY-MM-DD`; archiving such
+        // an entry would name only PLANS-DONE.md — a file the role may not edit — for a fault the
+        // gate judges against its archive form. Park those stranded entries in the live file instead,
+        // so the stage self-check, the fix-up turn and the gate all name PLANS.md and the author can
+        // fix the missing done stamp (BUGS.md 2026-10-21).
+        const park = new Set((spec.file === "PLANS.md" ? strandedPlanEntries(live) : [])
+            .filter((s) => s.section === spec.section)
+            .map((s) => archiveKey(s.title)));
+        const move = archiveFinishedText(live, readTextIfExists(path.join(wt, spec.archive)), spec, {
+            baseKeys,
+            park,
+        });
+        if (park.size > 0) {
+            warnEventBestEffort(wt, TUMWATER_SOURCE, `the commit-time sweep left ${plural(park.size, "Done plan without a done date", "Done plans without a done date")} in ${spec.file} instead of archiving: the review gate would reject the archived form; add the missing done date to its heading`);
+        }
         if (move === null)
             continue;
         writeMove(wt, spec, move);
-        out.push({ file: spec.file, archive: spec.archive, titles: move.titles });
+        out.push({ file: spec.file, archive: spec.archive, titles: move.titles, dropped: move.dropped });
     }
     return out;
 }
@@ -187,10 +262,10 @@ export async function archiveNewFinishedEntries(wt, mainBranch) {
 function planArchiveAll(root, keep) {
     const plan = [];
     for (const spec of FINISHED_ARCHIVES) {
-        const live = readTextOrNull(path.join(root, spec.file));
+        const live = readTextIfExists(path.join(root, spec.file));
         if (live === null)
             continue;
-        const move = archiveFinishedText(live, readTextOrNull(path.join(root, spec.archive)), spec, { keep });
+        const move = archiveFinishedText(live, readTextIfExists(path.join(root, spec.archive)), spec, { keep });
         if (move !== null)
             plan.push({ spec, move });
     }
@@ -207,24 +282,56 @@ export function liveFinishedHistory(root) {
             file: spec.file,
             section: spec.section,
             archive: spec.archive,
-            entries: move.titles.length,
+            entries: move.titles.length + move.dropped.length,
             bytes: Buffer.byteLength(live) - Buffer.byteLength(move.live),
         });
     }
     return out;
 }
+/** The bulk archive's commit subject after its `tumwater(operator):` prefix: how many entries
+ * moved to which archives, and how many already-archived ones left the live files (ArchiveMove). */
+function archiveCommitWhat(plan) {
+    const count = plan.reduce((n, { move }) => n + move.titles.length, 0);
+    const dropped = plan.reduce((n, { move }) => n + move.dropped.length, 0);
+    const drop = plural(dropped, "already-archived entry", "already-archived entries");
+    if (count === 0 && dropped > 0)
+        return `Drop ${drop} from ${plan.map(({ spec }) => spec.file).join(" and ")}`;
+    // A file that only dropped entries left its archive untouched.
+    const archives = plan.filter(({ move }) => move.titles.length > 0 || move.dropped.length === 0).map(({ spec }) => spec.archive);
+    const archived = `Archive ${plural(count, "finished entry", "finished entries")} to ${archives.join(" and ")}`;
+    return dropped > 0 ? `${archived}; drop ${drop}` : archived;
+}
+/** One archived file as a line of `tumwater archive`'s output and the team-start event: what
+ * moved where, and what was dropped because the archive already held it. */
+export function describeArchivedFile(f) {
+    const dropped = f.dropped.length > 0 ? ` (${plural(f.dropped.length, "already-archived entry", "already-archived entries")} dropped)` : "";
+    return `${f.file} → ${f.archive}: ${plural(f.titles.length, "entry", "entries")}${dropped}`;
+}
+/** planArchiveAll, or `skipped` when a live or archive file exists but cannot be read. */
+function planOrSkip(root, keep) {
+    try {
+        return planArchiveAll(root, keep);
+    }
+    catch (err) {
+        return { status: "skipped", reason: `a backlog file could not be read: ${errorFirstLine(err)}` };
+    }
+}
 /** The bulk archive, committed: move every live finished section of the primary checkout at
  * `root` (past its newest `keep` entries) to its archive file and commit the touched files on the
  * base branch as one `tumwater(operator):` commit. Holds the team's merge lock, so a merge
  * cannot lose its fast-forward to this commit, and the primary-worktree lock the CLI backlog
  * writers and the fast-forward share. Writes nothing when there is nothing to move, when the
- * primary checkout is not on the base branch, or when any of the files has uncommitted changes;
- * a failed commit restores the files. `tumwater archive` and team start call it. */
+ * primary checkout is not on the base branch, when any of the files has uncommitted changes, or
+ * when one exists but cannot be read; a failed write or commit restores the files.
+ * `tumwater archive` and team start call it. */
 export async function archiveFinishedOnMain(root, opts = {}) {
     const keep = opts.keep ?? 0;
-    if (planArchiveAll(root, keep).length === 0)
+    const pre = planOrSkip(root, keep);
+    if ("status" in pre)
+        return pre;
+    if (pre.length === 0)
         return { status: "nothing" };
-    return withLock(mergeLockDir(root), () => withStateLockAsync(primaryWorktreeLockPath(root), async () => {
+    return withLock(mergeLockDir(root), () => withPrimaryWorktreeLockAsync(root, async () => {
         const primary = await currentBranch(root);
         const base = targetBranch(loadConfigSafe(root).config?.baseBranch, primary);
         if (primary !== base) {
@@ -239,19 +346,20 @@ export async function archiveFinishedOnMain(root, opts = {}) {
             return { status: "skipped", reason: `${dirty.join(", ")} ${dirty.length > 1 ? "have" : "has"} uncommitted changes` };
         }
         // Re-planned under the locks: a merge may have moved main since the pre-check.
-        const plan = planArchiveAll(root, keep);
+        const plan = planOrSkip(root, keep);
+        if ("status" in plan)
+            return plan;
         if (plan.length === 0)
             return { status: "nothing" };
         const touched = plan.flatMap(({ spec }) => [spec.file, spec.archive]);
         const created = plan.map(({ spec }) => spec.archive).filter((f) => !fs.existsSync(path.join(root, f)));
-        for (const { spec, move } of plan)
-            writeMove(root, spec, move);
-        const count = plan.reduce((n, { move }) => n + move.titles.length, 0);
         const subject = stampedSubject("operator", // vocabulary-ok: the tumwater(operator): commit prefix is a machine string
-        `Archive ${plural(count, "finished entry", "finished entries")} to ${plan.map(({ spec }) => spec.archive).join(" and ")}`);
+        archiveCommitWhat(plan));
         try {
+            for (const { spec, move } of plan)
+                writeMove(root, spec, move);
             await git(root, "add", "--", ...touched);
-            await git(root, ...COMMIT_IDENT, "commit", "--only", "-m", subject, "--", ...touched);
+            await git(root, ...(await committerIdentArgs(root)), "commit", ...commitAuthorArgs(), "--only", "-m", subject, "--", ...touched);
         }
         catch (err) {
             await gitTry(root, "reset", "-q", "--", ...touched);
@@ -259,12 +367,12 @@ export async function archiveFinishedOnMain(root, opts = {}) {
             await gitTry(root, "checkout", "--", ...tracked);
             for (const f of created)
                 fs.rmSync(path.join(root, f), { force: true });
-            return { status: "skipped", reason: `the commit failed: ${errorMessage(err).trim().split("\n")[0]}` };
+            return { status: "skipped", reason: `the move could not be written or committed: ${errorFirstLine(err)}` };
         }
         return {
             status: "archived",
             commit: await headOf(root, "HEAD"),
-            moved: plan.map(({ spec, move }) => ({ file: spec.file, archive: spec.archive, titles: move.titles })),
+            moved: plan.map(({ spec, move }) => ({ file: spec.file, archive: spec.archive, titles: move.titles, dropped: move.dropped })),
         };
     }), opts.lockTimeoutMs);
 }
@@ -283,7 +391,7 @@ export async function archiveAtTeamStart(root) {
                 type: "state_migrated",
                 step: "backlogArchive",
                 moved: outcome.moved.reduce((n, f) => n + f.titles.length, 0),
-                detail: outcome.moved.map((f) => `${f.file} → ${f.archive}: ${plural(f.titles.length, "entry", "entries")}`).join("; "),
+                detail: outcome.moved.map(describeArchivedFile).join("; "),
             });
         }
         else if (outcome.status === "skipped") {
@@ -294,3 +402,86 @@ export async function archiveAtTeamStart(root) {
         warnEventBestEffort(root, TUMWATER_SOURCE, `finished backlog entries were not archived: ${errorMessage(err)}`);
     }
 }
+/** The start of a quarantine entry's title for `test`, up to the date. appendBugEntryLocked
+ * collapses whitespace in the title, so the test part is collapsed the same way; collapsing the
+ * whole prefix would trim its trailing space. */
+function quarantineTitlePrefix(test) {
+    return collapseWhitespace(`\`${test}\` failed, then passed on the same tree`) + " (quarantined by tumwater ";
+}
+/** Output fenced into a bug body: a fence of its own length cannot be closed by the quoted text. */
+function fencedTail(tail) {
+    return ["~~~~", ...tail.replaceAll("~~~~", "~~~").split("\n").slice(-30), "~~~~"].join("\n");
+}
+/** File one BUGS.md `## Open` entry per newly quarantined test and commit BUGS.md on the base
+ * branch as one `tumwater(operator):` commit, under the merge lock and the primary-worktree lock
+ * exactly as archiveFinishedOnMain does. Skipped, writing nothing, when the primary checkout is
+ * off the base branch, BUGS.md has uncommitted changes, or BUGS.md exists but cannot be read; a
+ * failed append or commit restores BUGS.md. A test whose quarantine entry is already under
+ * `## Open` (a filing whose markQuarantineFiled failed after the commit) gets that heading back
+ * and is not filed again. */
+export async function fileQuarantineBugsOnMain(root, tests, opts = {}) {
+    return withLock(mergeLockDir(root), () => withPrimaryWorktreeLockAsync(root, async () => {
+        const primary = await currentBranch(root);
+        const base = targetBranch(loadConfigSafe(root).config?.baseBranch, primary);
+        if (primary !== base) {
+            return { status: "skipped", reason: `your checkout is on ${primary ?? "a detached HEAD"}, not ${base}` };
+        }
+        const status = await gitTry(root, "status", "--porcelain", "--", "BUGS.md");
+        if (status === null)
+            return { status: "skipped", reason: "could not read git status" };
+        if (status.trim() !== "" && !status.startsWith("??")) {
+            return { status: "skipped", reason: "BUGS.md has uncommitted changes" };
+        }
+        const file = path.join(root, "BUGS.md");
+        let before;
+        try {
+            before = readTextIfExists(file);
+        }
+        catch (err) {
+            return { status: "skipped", reason: `BUGS.md could not be read: ${errorFirstLine(err)}` };
+        }
+        const date = formatDate(new Date());
+        const open = before === null ? [] : parseEntryDetails(before, "Open").map((e) => e.title);
+        const bugs = new Map();
+        let appended = 0;
+        const restoreBugs = async () => {
+            await gitTry(root, "reset", "-q", "--", "BUGS.md");
+            if (before === null)
+                fs.rmSync(file, { force: true });
+            else
+                writeTextAtomic(file, before);
+        };
+        try {
+            for (const { test, tail } of tests) {
+                const existing = open.find((t) => t.startsWith(quarantineTitlePrefix(test)));
+                if (existing !== undefined) {
+                    bugs.set(test, existing);
+                    continue;
+                }
+                const body = [
+                    `The check failed on this test and then passed on a re-run of the same tree, so tumwater quarantined it: it counts as a known failure until this entry leaves \`## Open\`. Find why it is unstable and fix it.`,
+                    ...(tail ? ["", fencedTail(tail)] : []),
+                ].join("\n");
+                bugs.set(test, appendBugEntryLocked(root, `${quarantineTitlePrefix(test)}${date})`, body));
+                appended++;
+            }
+        }
+        catch (err) {
+            await restoreBugs();
+            return { status: "skipped", reason: `a BUGS.md entry could not be written: ${errorFirstLine(err)}` };
+        }
+        if (appended === 0)
+            return { status: "filed", bugs };
+        const subject = stampedSubject("operator", // vocabulary-ok: the tumwater(operator): commit prefix is a machine string
+        `File ${plural(appended, "quarantined flaky test", "quarantined flaky tests")} in BUGS.md`);
+        try {
+            await git(root, "add", "--", "BUGS.md");
+            await git(root, ...(await committerIdentArgs(root)), "commit", ...commitAuthorArgs(), "--only", "-m", subject, "--", "BUGS.md");
+        }
+        catch (err) {
+            await restoreBugs();
+            return { status: "skipped", reason: `the commit failed: ${errorFirstLine(err)}` };
+        }
+        return { status: "filed", bugs };
+    }), opts.lockTimeoutMs);
+}