tumwater 0.4.1 → 0.4.2

package/dist/src/agent/image-input.js

@@ -1,17 +1,14 @@
 /** The seam's answer to "who in this team can read images" (plans/image-input.md
- * "Capability"). One resolver, `seamImageInput`, is the only place that rule lives; the doctor
- * (src/doctor/doctor-model-checks.ts) and the later reroute parts both read it, so the answer
- * is never reached two ways. It lives at runtime level because it needs the backend registry:
- * a claude seam is always capable through the AgentBackend.imageInput hook, a pi seam reads the
- * model's `input` in models.json, and any other backend answers null unless it declares a hook. */
-import { configForRole, roleSeamTier, withModelOverrides } from "../config/config-views.js";
-import { BORROW_ORDER, resolveTierFallbacks } from "../config/config-fallbacks.js";
+ * "Capability"). One resolver, `seamImageInput`, is the only place that rule lives, so the
+ * answer is never reached two ways. It lives at runtime level because it needs the backend
+ * registry: a claude seam is always capable through the AgentBackend.imageInput hook, a pi
+ * seam reads the model's `input` in models.json, and any other backend answers null unless it
+ * declares a hook. */
+import { configForRole } from "../config/config-views.js";
 import { seamAgent } from "../config/model-selector.js";
-import { modelLabel } from "./backend-traits.js";
-import { piModelImageInput, piPairFree, piModelsPath, readPiProviders } from "../pi/pi-models.js";
+import { piModelImageInput, piModelsPath, readPiProviders } from "../pi/pi-models.js";
 import { piListedImageInput } from "../pi/pi-listed-models.js";
 import { backendById } from "./agent-backend.js";
-import { imageProbeEntryFresh, imageProbeKey } from "../doctor/image-probe.js";
 /** One seam's image-input capability (plans/image-input.md "Capability"): `true` when the
  * seam's backend declares image support, `false` when it is text-only, `null` when it cannot
  * be answered from what the team knows (a pair neither models.json nor the pi listing names, a
@@ -21,11 +18,10 @@ import { imageProbeEntryFresh, imageProbeKey } from "../doctor/image-probe.js";
  * the default pi backend leaves it to models.json's `input` field, where absent means text-only
  * (pi's own default for a custom model); a pair absent from models.json answers what
  * `pi --list-models` last said (src/pi/pi-listed-models.ts), else null.
- * `probes` is the doctor's live-probe cache (part 2/5): a claimed pi seam whose probe FAILED
- * reads false — a claim is only as good as the verified
- * answer — while a cached pass (or an unprobed claim) stands on the catalog. claude seams are
- * never probed, so the hook answer is never overridden. */
-export function seamImageInput(seam, providers, probes, listed = null) {
+ * A claim in models.json is trusted without a live probe (the doctor's live probe was
+ * subtracted): a claimed pi seam reads true on the catalog. claude seams are answered by the
+ * hook. */
+export function seamImageInput(seam, providers, listed = null) {
     const backendId = seamAgent(seam);
     const backend = backendById(backendId);
     // A backend with an imageInput hook owns the answer outright (claude: true for every model).
@@ -34,79 +30,14 @@ export function seamImageInput(seam, providers, probes, listed = null) {
     // An unknown backend without a hook has no catalog to consult — unknown, never assume.
     if (backendId !== "pi")
         return null;
-    const base = piModelImageInput(providers, seam.provider, seam.model) ?? piListedImageInput(listed, seam.provider, seam.model);
-    if (base !== true)
-        return base;
-    // A claimed pi seam whose live probe failed (fresh, claim unchanged) reads false. Only pi is
-    // probed, so the probe key carries the pi backend.
-    const entry = probes?.[imageProbeKey(backendId, seam.provider, seam.model)];
-    if (entry?.verdict === "fail" && imageProbeEntryFresh(entry))
-        return false;
-    return true;
+    return piModelImageInput(providers, seam.provider, seam.model) ?? piListedImageInput(listed, seam.provider, seam.model);
 }
-/** The image-capable reroute target for `role`, or null when no peer tier can read images
- * (plans/image-input.md "Reroute target"). Walks the role's seam tier through BORROW_ORDER,
- * skipping the tier itself — small → default → strong, default → strong → small, strong →
- * default (a strong-tier seam never drops to small, the same rule as the budget fallback) —
- * and takes the first tier whose model reads images. `regime` picks the pair set (see
- * RerouteRegime); `modelsPath` and `account` are injectable so tests need no real pi install
- * or account. */
-export function imageReroute(config, role, regime = "primary", modelsPath = piModelsPath(), account = null, probes, providers = null, listed = null) {
-    const tier = roleSeamTier(config, role);
-    const candidates = BORROW_ORDER[tier].filter((t) => t !== tier);
-    if (candidates.length === 0)
-        return null;
-    const providerMap = providers ?? readPiProviders(modelsPath);
-    const capable = (rc) => seamImageInput(rc, providerMap, probes, listed) === true;
-    if (regime === "primary") {
-        for (const t of candidates) {
-            const rc = withModelOverrides(config, t, {});
-            if (capable(rc))
-                return { tier: t, config: rc };
-        }
-        return null;
-    }
-    // Fallback regime: only the tiers' free fallback pairs qualify (resolveTierFallbacks over the
-    // price check), never a priced primary model — a reroute must not spend past the cap.
-    const resolved = resolveTierFallbacks(config, (p) => 
-    // The free-ness lookup reads the one claude account held here (part 2a/9).
-    piPairFree(providerMap, p, (b) => (b === "claude" ? account : null)));
-    for (const t of candidates) {
-        const pair = resolved[t].pair;
-        if (!pair)
-            continue;
-        const rc = withModelOverrides(config, t, {
-            provider: pair.provider,
-            model: pair.model,
-            thinking: pair.thinking,
-        });
-        if (capable(rc))
-            return { tier: t, config: rc };
-    }
-    return null;
-}
-/** The config of imageReroute, for callers that want only the target model. */
-export function imageRerouteTarget(config, role, regime = "primary", modelsPath = piModelsPath(), account = null, probes, providers = null, listed = null) {
-    return imageReroute(config, role, regime, modelsPath, account, probes, providers, listed)?.config ?? null;
-}
-/** A seam's model as one readable token, the same label the doctor's `image input` check uses
- * (`claude/<id>` for a claude seam, `provider/model` for pi). The one home of the label, so
- * the surface strings (the images alert, the role page, the status rows) and the doctor report
- * cannot drift, and delegates to backend-traits' modelLabel. */
-export function seamImageLabel(backend, provider, model) {
-    return modelLabel(backend, provider, model);
-}
-/** Compute RoleImageInfo for one role. `modelsPath` and `probes` are injectable; the providers
- * catalog is read (stat-cached) here and also handed to imageReroute so a poll that asks many
- * roles still parses the catalog once. All reads mirror the doctor's `image input` check, so
- * the surface and the check agree about capability. */
-export function roleImageInfo(config, role, modelsPath = piModelsPath(), probes, listed = null) {
+/** Compute RoleImageInfo for one role. `modelsPath` and `listed` are injectable; the providers
+ * catalog is read (stat-cached) here. The reroute field is a literal null — the peer-tier image
+ * reroute was subtracted (part 5g/6), so no role names a reroute target; 5h removes the field. */
+export function roleImageInfo(config, role, modelsPath = piModelsPath(), listed = null) {
     const providers = readPiProviders(modelsPath);
     const rc = configForRole(config, role);
-    const imageInput = seamImageInput(rc, providers, probes, listed);
-    const rr = imageReroute(config, role, "primary", modelsPath, null, probes, providers, listed);
-    const imageRerouteStr = rr
-        ? `${rr.tier} (${seamImageLabel(rr.config.agent, rr.config.provider, rr.config.model)})`
-        : null;
-    return { imageInput, imageReroute: imageRerouteStr };
+    const imageInput = seamImageInput(rc, providers, listed);
+    return { imageInput, imageReroute: null };
 }

package/dist/src/agent/opencode/opencode-catalog.js

@@ -4,8 +4,8 @@
  * `.tumwater/state/opencode-models.json` that survives a failed fetch, and
  * `opencodeModelFree` as the one predicate part 6b/7's seam reads. No seam is wired here: that
  * is part 6b/7 (the budget gate), part 6c/7 (a billedAt demotion on an observed cost) and
- * part 7/7 (a startup-cache seed and doctor), so this module's only callers today are its own
- * tests. */
+ * part 7/7 (a startup-cache seed and doctor), so this module only publishes the data and
+ * predicates those seam consumers read. */
 import { spawnSync } from "node:child_process";
 import { isJsonObject, validEntries } from "../../files/json-object.js";
 import { readJsonFile, writeJsonAtomic } from "../../files/json-files.js";

package/dist/src/agent/opencode/opencode-stream.js

@@ -16,6 +16,7 @@
  * `opencode_free_tier_refused` is added there once when any step was refused. `--thinking` is
  * never passed, so no `reasoning` event appears; the mapping below still recognizes one so a
  * future `--thinking` run degrades gracefully. */
+import { transientProseKind } from "../backend-traits.js";
 import { canonicalUsageBlock, isJsonObject, nonNegativeNumber, objectOrEmpty, parseJsonObject } from "../../files/json-object.js";
 /** opencode's tool names → the canonical pi names the readers already know. `shell`→`bash` and
  * `patch`→`edit` (pi has one edit tool); anything else is lower-cased so a future tool still
@@ -66,10 +67,9 @@ function classifyError(err) {
     // Transient server, connection and timeout failures.
     if (/\b(500|501|502|503|504|529)\b|internal server error|bad gateway|service unavailable|gateway timeout|overloaded/i.test(message))
         return { kind: "transientBackend", backendKind: "server" };
-    if (/connection|econn|refused|reset|terminated/i.test(message))
-        return { kind: "transientBackend", backendKind: "connection" };
-    if (/timed out|timeout/i.test(message))
-        return { kind: "transientBackend", backendKind: "timeout" };
+    const prose = transientProseKind(message);
+    if (prose)
+        return prose;
     return {};
 }
 /** The step's token counts and cost → pi's canonical usage block: the four counts, their sum

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

@@ -15,7 +15,7 @@
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
-import { ensureDir } from "../files/files.js";
+import { ensureDir, removeTree } from "../files/files.js";
 import { runOnAbort, terminateChild } from "../process/process.js";
 import { startPiWatchdogs } from "../pi/pi-watchdogs.js";
 import { DEFAULT_BACKEND, backendById, registerAgentBackend } from "./agent-backend.js";
@@ -208,7 +208,16 @@ export function runAgent(opts) {
         catch (err) {
             // A synchronous throw in the run's build-and-spawn stage (claude's invocation rejects a
             // run with no resolved model) rejects the run, preserving the contract a synchronous
-            // executor's throw used to get from the Promise constructor.
+            // executor's throw used to get from the Promise constructor. No child was spawned, so no
+            // `error`/`close` ever fires and the settle path that removes the private TMPDIR
+            // (run-stream.ts's finish) never runs — remove it here, best-effort like finish does, so
+            // a broken run does not leave a `tumwater-run-*` temp dir behind.
+            try {
+                removeTree(runTmp);
+            }
+            catch {
+                /* left for the OS temp sweep */
+            }
             reject(err instanceof Error ? err : new Error(`runAgent: ${String(err)}`));
         }
     });

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

@@ -144,6 +144,27 @@ export function settleExit(state) {
     })
         .catch(() => { });
 }
+/** Settle the run's `lastError` text in priority order: a failed blind image read names both
+ * the file and the model (plans/image-input.md "Failing the run"), then the abort, quiet-kill
+ * and timeout causes the watchdogs and signal path set, then the parser's own event-derived
+ * error, else the raw stderr tail. Undefined for a run that simply ended with a message. */
+function settleErrorMessage(state, blindRead, failed, stderr, code) {
+    if (blindRead !== undefined) {
+        return `read ${blindRead}, but ${state.config.model ?? "the model"} cannot read images`;
+    }
+    if (state.aborted())
+        return "stopped by tumwater shutdown";
+    if (state.wd.quietKilled) {
+        return `killed as hung: no agent progress for over ${state.config.quietTimeoutSeconds}s`;
+    }
+    if (state.wd.timedOut) {
+        return state.wd.timedOutProgressing
+            ? `timed out after ${state.wd.timeoutBudgetMs / 1000}s while still making progress — session and worktree edits preserved for resume`
+            : `timed out after ${state.wd.timeoutBudgetMs / 1000}s`;
+    }
+    return (state.parser.errorMessage ??
+        (failed ? stderr.trim().slice(-500) || `the agent exited ${code}` : undefined));
+}
 /** The run's `close` event: the process died and all its streams closed. Flush what the
  * decoders held back, reconcile the backend's post-run work, classify the exit cause, and
  * settle the run's result. */
@@ -182,20 +203,8 @@ export function settleClose(state, code) {
         cls.transientPiCrash !== true &&
         stderrBackend === undefined &&
         (state.parser.configError || cls.configError === true);
-    // The blind-read failure names both the file and the model (plans/image-input.md
-    // "Failing the run"): take it over any generic exit text so lastError is actionable.
     const blindRead = state.blindRead();
-    const errorMessage = blindRead !== undefined
-        ? `read ${blindRead}, but ${state.config.model ?? "the model"} cannot read images`
-        : state.aborted()
-            ? "stopped by tumwater shutdown"
-            : state.wd.quietKilled
-                ? `killed as hung: no agent progress for over ${state.config.quietTimeoutSeconds}s`
-                : state.wd.timedOut
-                    ? state.wd.timedOutProgressing
-                        ? `timed out after ${state.wd.timeoutBudgetMs / 1000}s while still making progress — session and worktree edits preserved for resume`
-                        : `timed out after ${state.wd.timeoutBudgetMs / 1000}s`
-                    : (state.parser.errorMessage ?? (failed ? stderr.trim().slice(-500) || `the agent exited ${code}` : undefined));
+    const errorMessage = settleErrorMessage(state, blindRead, failed, stderr, code);
     state.finish(resultFromParser(state, {
         ok: !failed,
         transientPiCrash: cls.transientPiCrash === true,

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

@@ -15,7 +15,7 @@ import { ensureParentDir, rotateIfLarge } from "../files/files.js";
 import { terminateChild } from "../process/process.js";
 import { makeRunMarker } from "../process/run-marker.js";
 import { PiStreamParser } from "../pi/pi-stream.js";
-import { recordSession } from "./session-ledger.js";
+import { recordSession, sessionRecordFor } from "./session-ledger.js";
 import { errorMessage } from "../text/text.js";
 import { warnEventBestEffort, TUMWATER_SOURCE } from "../events/events.js";
 import { seamImageInput } from "./image-input.js";
@@ -44,15 +44,7 @@ function buildAndSpawn(backend, opts, pre) {
     // session of its own kind instead of whatever file is newest in the dir. The id is the backend's
     // own when it mints one ahead of the run (claude's UUID, or the resumed record's id); pi mints
     // none and keeps the session name.
-    recordSession(opts.sessionDir, {
-        agent: backend.id,
-        id: preSpawnSessionId,
-        kind: opts.kind,
-        name: opts.sessionName,
-        cwd: opts.cwd,
-        ...(opts.config.model !== undefined ? { model: opts.config.model } : {}),
-        at: Date.now(),
-    });
+    recordSession(opts.sessionDir, sessionRecordFor(backend.id, preSpawnSessionId, opts));
     const translator = backend.translator();
     // Decode stdout incrementally instead of per chunk: a raw Buffer.toString("utf8") replaces any
     // multi-byte character whose bytes straddle two 'data' events with U+FFFD, corrupting that
@@ -146,8 +138,7 @@ export function spawnPiRun(backend, logs, runTmp, opts) {
     }
     const parser = new PiStreamParser(opts.onToolCallStart, {
         // The seam's effective image input (src/agent/image-input.ts): a text-only seam makes every
-        // image read blind even when pi adds no note — a claim its doctor probe proved false — which
-        // the parser checks against its own note rule.
+        // image read blind even when pi adds no note — the parser checks against its own note rule.
         imageInput: seamImageInput(opts.config, readPiProviders(piModelsPath())),
         onBlindRead: (path) => {
             // Kill an authoring run at once, before the agent goes on working from a picture it never

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

@@ -9,7 +9,7 @@
  * `error`/`exit`/`close` listeners itself. This module imports only run-agent's, run-spawn's
  * and run-settle's type surfaces, so there is no runtime import cycle. */
 import { removeTree } from "../files/files.js";
-import { recordSession } from "./session-ledger.js";
+import { recordSession, sessionRecordFor } from "./session-ledger.js";
 /** How many trailing stderr characters are carried into the next chunk's warning match, so a
  * warning split across two `data` events is still seen. The warnings are short lines, so a few
  * hundred characters always cover a straddle. */
@@ -60,15 +60,7 @@ export function createAgentStream(input) {
         const sid = translator.sessionId?.();
         if (sid !== undefined && sid !== preSpawnSessionId && !streamMintedSession) {
             streamMintedSession = true;
-            recordSession(opts.sessionDir, {
-                agent: backend.id,
-                id: sid,
-                kind: opts.kind,
-                name: opts.sessionName,
-                cwd: opts.cwd,
-                ...(opts.config.model !== undefined ? { model: opts.config.model } : {}),
-                at: Date.now(),
-            });
+            recordSession(opts.sessionDir, sessionRecordFor(backend.id, sid, opts));
         }
     };
     // Split native stdout into complete lines, translate each, and feed the canonical lines to

package/dist/src/agent/session-ledger.js

@@ -38,6 +38,22 @@ export function recordSession(dir, record) {
         // Best effort: a lost ledger line costs resumability, not the run.
     }
 }
+/** The one run's ledger record, minus the id the two recording sites mint differently — the
+ * pre-spawn id in run-spawn.ts, or the stream-minted session id in run-stream.ts. One place
+ * for the record's non-id shape (agent, kind, name, cwd, the optional model and the stamp), so
+ * the two appends cannot drift on the model spread or the required fields. `agent` is the
+ * owning backend's id; the run options supply the rest. */
+export function sessionRecordFor(agent, id, opts) {
+    return {
+        agent,
+        id,
+        kind: opts.kind,
+        name: opts.sessionName,
+        cwd: opts.cwd,
+        ...(opts.config.model !== undefined ? { model: opts.config.model } : {}),
+        at: Date.now(),
+    };
+}
 /** True when `dir` holds at least one session file a backend could resume by directory. This is
  * the backend-neutral filesystem check behind pi's `--continue` and the fallback for an
  * unregistered backend. The ledger file shares the dir and is a `.jsonl` too, so it is

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

@@ -30,11 +30,9 @@ import { commitAuthorArgs, committerIdentArgs, git, gitTry } from "../git/git-ru
 import { mergeLockDir } from "../paths.js";
 import { plural } from "../text/phrases.js";
 import { collapseWhitespace, errorFirstLine, errorMessage } from "../text/text.js";
-import { FINISHED_ARCHIVES, fenceTracker, fencedHeadingTitle, parseEntryDetails } from "./backlog-md.js";
+import { FINISHED_ARCHIVES, fenceTracker, fencedHeadingTitle } from "./backlog-md.js";
 import { actionableEntryRanges } from "./backlog-index-data.js";
 import { 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
@@ -133,6 +131,57 @@ function entryBlocks(lines, entries) {
     }
     return out;
 }
+/** The selected entries of `entries`: the keep slice, or the baseKeys/park filter. */
+function selectArchiveEntries(entries, select) {
+    return "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));
+}
+/** Add the 0-based live lines of `entries` to `into`. */
+function addEntryLines(entries, into) {
+    for (const e of entries)
+        for (let i = e.start - 1; i < e.end; i++)
+            into.add(i);
+}
+/** The bulk-archive split: the tail past the kept entries moves but for the dropped and staying
+ * entries, and a `_None yet._` placeholder stays in the live section, never in the archive.
+ * null when no entry sits past the kept ones. */
+function splitByKeep(lines, span, entries, keep, staying, droppedLine) {
+    const from = keep <= 0 ? span.heading + 1 : (entries[keep]?.start ?? 0) - 1;
+    if (from < 0)
+        return null; // no entry past the kept ones
+    // 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();
+    addEntryLines(staying, stayLine);
+    const tail = [];
+    for (let i = from; i < span.end; i++)
+        if (!droppedLine.has(i) && !stayLine.has(i))
+            tail.push(lines[i] ?? "");
+    const moved = trimBlank(tail.filter((l) => !PLACEHOLDER.test(l.trim())));
+    const stayingBlocks = entryBlocks(lines, staying);
+    const head = keep <= 0 ? [] : trimBlank(lines.slice(span.heading + 1, from));
+    const kept = head.length > 0 && stayingBlocks.length > 0 ? [...head, "", ...stayingBlocks] : [...head, ...stayingBlocks];
+    return {
+        kept: kept.length === 0 ? tail.filter((l) => PLACEHOLDER.test(l.trim())).slice(0, 1) : kept,
+        moved,
+    };
+}
+/** The commit-time-sweep split: the kept body drops the moved and dropped lines, refusing when
+ * no archive exists and other content would stay in the live section. */
+function splitByBaseKeys(lines, span, archiveMd, moving, droppedLine) {
+    const leaves = new Set(droppedLine);
+    addEntryLines(moving, leaves);
+    let kept = [];
+    for (let i = span.heading + 1; i < span.end; 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;
+    const moved = entryBlocks(lines, moving);
+    return { kept, moved };
+}
 /** 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. A selected entry whose
  * heading the archive already holds never moves (EntryFate): with the same text it is dropped
@@ -147,9 +196,7 @@ 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));
+    const selected = selectArchiveEntries(entries, select);
     if (!("keep" in select) && selected.length === 0)
         return null;
     const archiveText = archiveMd ?? archiveTemplate(spec);
@@ -161,46 +208,14 @@ export function archiveFinishedText(liveMd, archiveMd, spec, select) {
     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;
-    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
-        // 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())));
-        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);
-    }
-    else {
-        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 (!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 = entryBlocks(lines, withFate("move"));
-    }
+    addEntryLines(withFate("drop"), droppedLine);
+    const split = "keep" in select
+        ? splitByKeep(lines, span, entries, select.keep, withFate("stay"), droppedLine)
+        : splitByBaseKeys(lines, span, archiveMd, withFate("move"), droppedLine);
+    if (split === null)
+        return null;
+    const moved = split.moved;
+    const kept = split.kept;
     const dropped = withFate("drop").map((e) => e.title);
     if (moved.length === 0 && dropped.length === 0)
         return null;
@@ -327,9 +342,9 @@ function planOrSkip(root, keep) {
     }
 }
 /** If the primary checkout is not on the base branch, the reason a main-side write should be
- * skipped, else null. Both `archiveFinishedOnMain` and `fileBugsOnMain` guard on this before
- * committing a backlog file. */
-async function primaryOffBaseBranchReason(root) {
+ * skipped, else null. Both `archiveFinishedOnMain` and `fileBugsOnMain` (backlog-file-bugs.ts)
+ * guard on this before committing a backlog file. */
+export async function primaryOffBaseBranchReason(root) {
     const primary = await currentBranch(root);
     const base = targetBranch(loadConfigSafe(root).config?.baseBranch, primary);
     if (primary !== base) {
@@ -421,119 +436,3 @@ 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 given entry and commit BUGS.md on the base branch as one
- * `tumwater(operator):` commit (the subject built from the number of entries actually appended is
- * stamped under the operator role), 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.
- * Every entry is appended verbatim as its own `## Open` heading — unless its `ifOpen` dedupe
- * matches an existing heading, which is reused instead — and the returned headings are the
- * entry headings in input order. */
-export async function fileBugsOnMain(root, entries, subject, opts = {}) {
-    return withLock(mergeLockDir(root), () => withPrimaryWorktreeLockAsync(root, async () => {
-        const offBase = await primaryOffBaseBranchReason(root);
-        if (offBase !== null)
-            return { status: "skipped", reason: offBase };
-        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 open = before === null ? [] : parseEntryDetails(before, "Open").map((e) => e.title);
-        const headings = [];
-        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 entry of entries) {
-                if (entry.ifOpen !== undefined) {
-                    const existing = entry.ifOpen(open);
-                    if (existing !== undefined) {
-                        headings.push(existing);
-                        continue;
-                    }
-                }
-                headings.push(appendBugEntryLocked(root, entry.title, entry.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", headings };
-        const commitSubject = stampedSubject("operator", // vocabulary-ok: the tumwater(operator): commit prefix is a machine string
-        subject(appended));
-        try {
-            await git(root, "add", "--", "BUGS.md");
-            await git(root, ...(await committerIdentArgs(root)), "commit", ...commitAuthorArgs(), "--only", "-m", commitSubject, "--", "BUGS.md");
-        }
-        catch (err) {
-            await restoreBugs();
-            return { status: "skipped", reason: `the commit failed: ${errorFirstLine(err)}` };
-        }
-        return { status: "filed", headings };
-    }), opts.lockTimeoutMs);
-}
-/** File one BUGS.md `## Open` entry per newly quarantined test and commit BUGS.md on the base
- * branch as one `tumwater(operator):` commit, delegating the locked write/commit to
- * fileBugsOnMain and preserving the existing subject. 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 — the dedupe runs inside fileBugsOnMain under the merge lock (via
- * each entry's `ifOpen`), so concurrent quarantine filings cannot both append a duplicate, and
- * the real skip on a dirty or off-base BUGS.md is enforced under the same lock. */
-export async function fileQuarantineBugsOnMain(root, tests, opts = {}) {
-    const date = formatDate(new Date());
-    const toFile = [];
-    for (const { test, tail } of tests) {
-        const prefix = quarantineTitlePrefix(test);
-        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");
-        toFile.push({
-            title: `${prefix}${date})`,
-            body,
-            // Dedupe under the lock, against the headings fileBugsOnMain reads: the reused heading
-            // (not a duplicate) is returned in headings and zipped back to this test below.
-            ifOpen: (open) => open.find((t) => t.startsWith(prefix)),
-        });
-    }
-    const outcome = await fileBugsOnMain(root, toFile, 
-    // Size the subject by what was actually appended: tests whose `## Open` entry was already
-    // present are reused, not filed, so a mixed batch keeps the original "File N …" wording
-    // with N the count of new entries only.
-    (appended) => `File ${plural(appended, "quarantined flaky test", "quarantined flaky tests")} in BUGS.md`, opts);
-    if (outcome.status === "skipped")
-        return { status: "skipped", reason: outcome.reason };
-    // fileBugsOnMain's headings align with `tests` in order (reused headings or appended titles).
-    const bugs = new Map();
-    outcome.headings.forEach((heading, i) => bugs.set(tests[i].test, heading));
-    return { status: "filed", bugs };
-}