mandrel 2.60.0 → 2.61.0

package/.agents/scripts/lib/worktree/git-hooks.js

@@ -1,23 +1,9 @@
 /**
- * worktree/git-hooks.js
- *
- * Materialize the repository's git hooks directory into a linked worktree.
- *
- * `core.hooksPath` is resolved by git against **each working tree's own
- * root**, not against the common git dir. A relative value therefore points
- * at a directory that only exists in the checkout that generated it — husky
- * writes `.husky/_` from its `prepare` script in the main checkout and
- * self-ignores it — so every linked worktree resolves the hooks path to a
- * directory that is not there. Git finds no hooks and proceeds silently:
- * `commit-msg`, `pre-commit` and `pre-push` do not run for any commit made in
- * a worktree, without anyone passing a bypass flag.
- *
- * This module closes that gap by copying the resolved hooks directory into
- * the worktree at the same relative path. It is deliberately total about the
- * cases where there is nothing to do — an unset or absolute `core.hooksPath`,
- * or a source directory that does not exist — because a consumer project
- * without husky must not fail worktree creation. Every other outcome either
- * materializes the hooks or throws: a silent skip is the defect being fixed.
+ * Materialize the git hooks directory into a linked worktree. Git resolves a
+ * relative `core.hooksPath` per working tree, and husky's gitignored `.husky/_`
+ * exists only in the main checkout, so without this no hook runs in a
+ * worktree. Nothing-to-do cases skip; every other outcome materializes or
+ * throws, never a silent skip.
  */
 
 import { execFileSync } from 'node:child_process';
@@ -26,27 +12,15 @@ import path from 'node:path';
 import * as defaultGit from '../git-utils.js';
 import { assertPathContainment } from '../path-security.js';
 
-// Skip reasons. Deliberately not exported: they are part of the result
-// digest's observable contract, so callers and tests read them as the literal
-// strings they are printed as, not through a symbol that could be renamed
-// without anyone noticing the digest changed.
-//
-//   hooks-path-unset  — git uses the common `hooks` dir, already shared.
-//   hooks-path-absolute — resolves alike from every working tree already.
-//   source-absent     — no hooks directory to mirror (no husky in this project).
-//   same-checkout     — target is the source; copying it onto itself would
-//                       destroy the only copy.
+// Skip reasons are printed contract strings, so deliberately not exported.
+// same-checkout: copying the source onto itself would destroy the only copy.
 const SKIP_UNSET = 'hooks-path-unset';
 const SKIP_ABSOLUTE = 'hooks-path-absolute';
 const SKIP_SOURCE_ABSENT = 'source-absent';
 const SKIP_SAME_CHECKOUT = 'same-checkout';
 
 /**
- * Read `core.hooksPath` as configured for `repoRoot`.
- *
- * `git config --get` exits non-zero when the key is unset, which is a
- * legitimate state rather than an error, so this reports `null` for both an
- * unset key and an empty value.
+ * `core.hooksPath`, or `null` when unset or empty.
  *
  * @param {string} repoRoot
  * @param {{ gitSpawn: Function }} gitImpl
@@ -60,12 +34,7 @@ function readHooksPath(repoRoot, gitImpl) {
 }
 
 /**
- * Canonical form of `dir` for identity comparison.
- *
- * `realpathSync.native` is used so a symlinked temp root (macOS `/var` →
- * `/private/var`) does not make a checkout look distinct from itself. A path
- * that cannot be resolved falls back to `path.resolve`, which is enough for
- * the comparison to stay conservative.
+ * Realpath for identity comparison (macOS `/var` → `/private/var`).
  *
  * @param {string} dir
  * @param {typeof fs} fsImpl
@@ -81,8 +50,6 @@ function canonical(dir, fsImpl) {
 }
 
 /**
- * Names of the regular files directly inside `dir`, sorted.
- *
  * @param {string} dir
  * @param {typeof fs} fsImpl
  * @returns {string[]}
@@ -96,14 +63,11 @@ function hookFileNames(dir, fsImpl) {
 }
 
 /**
- * Materialize `repoRoot`'s resolved git hooks directory into `worktree`.
- *
- * Idempotent, and refreshing rather than preserving: an existing target is
- * replaced so an upgraded husky can never leave a stale shim behind.
+ * Idempotent; replaces an existing target so no stale shim survives.
  *
  * @param {object} opts
- * @param {string} opts.repoRoot   Absolute path to the checkout that owns the hooks.
- * @param {string} opts.worktree   Absolute path to the worktree to provision.
+ * @param {string} opts.repoRoot
+ * @param {string} opts.worktree
  * @param {{ gitSpawn: Function }} [opts.gitImpl]
  * @param {typeof fs} [opts.fsImpl]
  * @returns {{ action: 'materialized' | 'skipped', reason?: string,
@@ -145,9 +109,7 @@ export function materializeGitHooks({
   if (!fsImpl.existsSync(source)) return skip(SKIP_SOURCE_ABSENT, hooksPath);
 
   const target = path.resolve(worktree, hooksPath);
-  // `core.hooksPath` is repo configuration, but it still reaches a recursive
-  // remove below — a `../..` value must not be able to delete outside the
-  // worktree it claims to provision.
+  // The value reaches a recursive remove; `../..` must not escape the worktree.
   assertPathContainment(
     path.resolve(worktree),
     target,
@@ -165,9 +127,7 @@ export function materializeGitHooks({
     );
   }
 
-  // Verify rather than trust the copy. The whole point of this module is that
-  // a hooks directory which is absent behaves exactly like one that is
-  // present and empty — git runs neither, and says nothing either way.
+  // Verify: missing hooks fail silently in git.
   const expected = hookFileNames(source, fsImpl);
   const actual = new Set(
     fsImpl.existsSync(target) ? hookFileNames(target, fsImpl) : [],
@@ -183,12 +143,7 @@ export function materializeGitHooks({
 }
 
 /**
- * Resolve the checkout that owns the shared git config from `cwd`.
- *
- * `--git-common-dir` reports the common git dir from any working tree —
- * `.git` from the main checkout, an absolute path from a linked worktree —
- * so the owning checkout is its parent. This is what lets the standalone CLI
- * be run from inside a worktree with no arguments.
+ * The main checkout: parent of `--git-common-dir`, from any working tree.
  *
  * @param {string} cwd
  * @param {{ execFileSyncImpl?: typeof execFileSync }} [deps]

package/.agents/scripts/lib/worktree/lifecycle/force-drain.js

@@ -1,22 +1,8 @@
 /**
- * worktree/lifecycle/force-drain.js
- *
- * Stage 3 of the Windows worktree reap fallback: when Stage 2
- * (`drainPendingCleanup`) repeatedly fails to clear an entry because some
- * process is still holding handles inside the worktree, this module
- * enumerates the holding processes via PowerShell `Get-CimInstance
- * Win32_Process`, terminates them with `taskkill /T /F`, and re-runs the
- * Stage 2 drain.
- *
- * Detection is best-effort: it matches process `ExecutablePath` and
- * `CommandLine` against the worktree path. Kernel-held locks (Windows
- * Search indexer, AV scanners) won't show up — those entries stay in the
- * manifest and surface again on the next sweep, by which time the
- * indexer/AV has usually moved on.
- *
- * Non-Windows: this module is a no-op (`findHoldersInPath` returns `[]`),
- * so calling `forceDrainPendingCleanup` is safe everywhere — it just
- * degrades to the standard drain.
+ * Stage 3 of the reap fallback (Windows): find user-mode processes holding a
+ * stuck worktree, `taskkill /T /F` them, and re-drain. Kernel-held locks
+ * (indexer, AV) are invisible and wait for the next sweep. A no-op drain
+ * elsewhere.
  */
 
 import { spawnSync } from 'node:child_process';
@@ -24,9 +10,7 @@ import path from 'node:path';
 import { NOOP_LOGGER } from '../../Logger.js';
 import { drainPendingCleanup, readManifest } from './pending-cleanup.js';
 
-/** Initial wait after `taskkill` before retrying `drainPendingCleanup`. */
 const SETTLE_MS = 1500;
-/** If entries remain stuck after the first post-kill drain, wait again and drain once more. */
 const POST_KILL_RETRY_SETTLE_MS = 800;
 
 /**
@@ -52,15 +36,13 @@ function mergeDrainPasses(prev, next) {
 }
 
 /**
- * Enumerate Windows processes whose ExecutablePath or CommandLine is rooted
- * inside `wtPath`. On non-Windows, returns `[]`. Any PowerShell failure
- * (timeout, parse error, exit !=0) also returns `[]` — this is best-effort
- * escalation, never a hard error path.
+ * Windows processes whose executable or command line references `wtPath`.
+ * Best-effort: any failure, or non-Windows, returns `[]`.
  *
- * @param {string} wtPath Absolute path to the worktree directory.
+ * @param {string} wtPath
  * @param {object} [opts]
- * @param {Function} [opts.spawn] Injection point for tests (default `spawnSync`).
- * @param {string} [opts.platform] Override `process.platform` for tests.
+ * @param {Function} [opts.spawn]
+ * @param {string} [opts.platform]
  * @returns {Array<{pid:number, name:string, path?:string, commandLine?:string}>}
  */
 export function findHoldersInPath(wtPath, opts = {}) {
@@ -70,7 +52,6 @@ export function findHoldersInPath(wtPath, opts = {}) {
   if (!wtPath) return [];
 
   const normalized = path.resolve(wtPath);
-  // Single-quote escape for PowerShell: double any embedded single quote.
   const psNeedle = normalized.replace(/'/g, "''");
 
   const script = [
@@ -119,11 +100,8 @@ export function findHoldersInPath(wtPath, opts = {}) {
 }
 
 /**
- * Pure: compute the set of pids that must never be killed — `selfPid` plus
- * its full ancestor chain — from a process table of `{ pid, ppid }` rows.
- * Cycle-guarded (a corrupt/raced table cannot loop forever). `selfPid` is
- * always included even when the table is empty or missing its row, so the
- * guard fails safe.
+ * Pids never to kill: `selfPid` (always, even with an empty table) plus its
+ * ancestor chain. Cycle-guarded.
  *
  * @param {number} selfPid
  * @param {Array<{ pid: number, ppid?: number }>} table
@@ -149,13 +127,11 @@ export function computeProtectedPids(selfPid, table) {
 }
 
 /**
- * Enumerate the full Windows process table as `{ pid, ppid }` rows so the
- * kill set can exclude the invoking shell / orchestrator ancestry.
- * Best-effort: any failure returns `[]` (callers still protect `selfPid`).
+ * Windows process table as `{ pid, ppid }`; `[]` on any failure.
  *
  * @param {object} [opts]
- * @param {Function} [opts.spawn] Injection point for tests (default `spawnSync`).
- * @param {string} [opts.platform] Override `process.platform` for tests.
+ * @param {Function} [opts.spawn]
+ * @param {string} [opts.platform]
  * @returns {Array<{ pid: number, ppid: number }>}
  */
 export function fetchProcessTable(opts = {}) {
@@ -192,15 +168,9 @@ export function fetchProcessTable(opts = {}) {
 }
 
 /**
- * `taskkill /T /F /PID <pid>` for each holder. Returns the pids reported
- * as terminated. Per-pid failures are logged but do not throw — caller
- * decides whether the partial kill is enough to retry.
- *
- * Self-preservation (Story #4018): holders are matched by command-line
- * substring, which can select the invoking shell or the orchestrator's own
- * ancestor chain (any ancestor whose command line mentions the worktree
- * path). Before any `taskkill /T /F`, the kill set excludes `selfPid` and
- * its full ancestor chain — `/T` on an ancestor would kill this process too.
+ * `taskkill /T /F` each holder; returns killed pids, never throws. Excludes
+ * self and ancestors: a command-line match can select the invoking shell, and
+ * `/T` on an ancestor would kill this process too.
  */
 export function terminateHolders(holders, opts = {}) {
   const spawn = opts.spawn ?? spawnSync;
@@ -251,19 +221,9 @@ export function terminateHolders(holders, opts = {}) {
 }
 
 /**
- * Drain the pending-cleanup manifest with escalation. Runs the standard
- * `drainPendingCleanup` first; for any entry left in `stillPending` or
- * `persistent`, enumerates handle-holders inside the worktree path,
- * terminates them, and re-drains.
- *
- * Result extends the standard drain shape with:
- *   - `escalated`:  storyIds where holders were detected AND killed.
- *   - `killedPids`: { [storyId]: number[] } pids terminated per entry.
- *   - `noHolders`:  storyIds whose lock could not be attributed to a
- *                   user-mode process (likely indexer/AV/kernel).
- *
- * Escalation is gated on `escalate: true` (default); pass `false` to
- * mirror the legacy `drainPendingCleanup` behaviour exactly.
+ * Drain, then for still-stuck entries kill their holders and re-drain. Adds
+ * `escalated`, `killedPids` and `noHolders` (no user-mode holder found) to the
+ * drain result; `escalate: false` is a plain drain.
  */
 export async function forceDrainPendingCleanup({
   repoRoot,

package/.agents/scripts/lib/worktree/lifecycle/merge-reachability.js

@@ -1,34 +1,10 @@
 /**
- * worktree/lifecycle/merge-reachability.js
- *
- * The "is the worktree's work integrated upstream?" half of
- * `isSafeToRemove`. Runs the two-phase reachability gate the parent
- * documents: primary `merge-base --is-ancestor HEAD baseRef`, and a
- * `git cherry` patch-equivalence fallback when the ancestry check returns
- * "not an ancestor".
- *
- * The fallback exists because a post-merge rebase or force-push can drop
- * the local branch ref off the merged tip, so SHA reachability alone
- * under-reports integration.
- *
- * A third phase used to sit between the two: a `git log --merges
- * --grep=resolves #<storyId>` probe for the `(resolves #N)` token on the
- * Epic's `--no-ff` merge commit. Story #5006 removed it — v2 lands every
- * Story as a **squash** merge onto `main`, which never writes that token,
- * and the `--no-ff` emitter (`story-close/merge-runner.js`) went with the
- * Epic pipeline. The probe could only ever return `false`.
- *
- * Pure with respect to the supplied `ctx` bag; the only side effects are
- * the `gitSpawn` calls.
+ * Whether a worktree's work is integrated upstream: HEAD is an ancestor of
+ * the base ref, or (after a rebase/force-push moved the tip) every branch
+ * commit is patch-equivalent upstream.
  */
 
 /**
- * Resolve a worktree's `HEAD` to a full commit SHA via
- * `git rev-parse HEAD` (run inside the worktree). Returns
- * `{ ok: true, sha, short }` on success, or `{ ok: false, reason }` when
- * the spawn fails. The short form is sliced from the full SHA so callers
- * can build operator-facing reason strings without a second round-trip.
- *
  * @param {object} ctx
  * @param {string} wtPath
  * @returns {{ok: true, sha: string, short: string} | {ok: false, reason: string}}
@@ -43,13 +19,7 @@ export function resolveHeadSha(ctx, wtPath) {
 }
 
 /**
- * Run `git merge-base --is-ancestor headSha epicRef` from the main
- * checkout. Returns one of:
- *
- *   - `{ outcome: 'ancestor' }` — exit 0, head is reachable.
- *   - `{ outcome: 'not-ancestor' }` — exit 1, head is not reachable; the
- *     caller should fall back to the merge-commit-grep path.
- *   - `{ outcome: 'error', reason }` — any other exit; treat as unsafe.
+ * `merge-base --is-ancestor`: exit 0 ancestor, 1 not, else error (unsafe).
  *
  * @param {object} ctx
  * @param {string} headSha
@@ -73,30 +43,12 @@ export function checkHeadAncestor(ctx, headSha, epicRef) {
 }
 
 /**
- * Predicate: are every commit on `branch` patch-equivalent to a commit
- * already on `epicRef`? Runs `git cherry <epicRef> <branch>` and returns
- * `true` when every output line starts with `- ` (already upstream by
- * patch-id). Returns `false` when:
- *
- *   - `git cherry` exits non-zero,
- *   - the output is empty (no commits to compare — the trivial-ancestor
- *     case is already covered by `checkHeadAncestor`), or
- *   - any output line starts with `+ ` (a commit on `branch` whose
- *     patch-id is not present upstream).
- *
- * Surfaces the "Story diff already integrated as rebased equivalents"
- * recovery case: operator manually rebased the Story's content onto
- * `epic/<id>` during recovery, so the diff is on the Epic branch as
- * commits with **different SHAs** but the same patch-ids. The ancestor
- * check returns `false` (Story tip's own commits are not ancestors), and
- * no `(resolves #<id>)` merge commit exists — but the work is
- * functionally integrated.
- *
- * Story #3161 — surfaced during Epic #3078 delivery on Story #3122.
+ * True when `git cherry` lists at least one commit and all are `- ` (already
+ * upstream by patch-id under different SHAs).
  *
  * @param {object} ctx
- * @param {string} branch Branch with commits to test (e.g. `story-3122`).
- * @param {string} epicRef Epic ref to test against (e.g. `origin/epic/3078`).
+ * @param {string} branch
+ * @param {string} epicRef
  * @returns {boolean}
  */
 export function hasRebasedEquivalents(ctx, branch, epicRef) {
@@ -111,14 +63,10 @@ export function hasRebasedEquivalents(ctx, branch, epicRef) {
 }
 
 /**
- * Run the full two-phase merge-reachability gate. Returns the same
- * `{ safe, reason }` envelope `isSafeToRemove` does, so callers can chain
- * the verdict directly into the parent return value.
- *
  * @param {object} ctx
  * @param {string} wtPath
- * @param {string} branch Working branch name from the precheck.
- * @param {string} epicRef Epic ref (e.g. `epic/1831`).
+ * @param {string} branch
+ * @param {string} epicRef Base ref the work must be integrated into.
  * @returns {Promise<{safe: boolean, reason: string}>}
  */
 export async function checkMergeReachability(ctx, wtPath, branch, epicRef) {

package/.agents/scripts/lib/worktree/lifecycle/pending-cleanup.js

@@ -1,36 +1,11 @@
 /**
- * worktree/lifecycle/pending-cleanup.js
+ * Stage 2 of the reap fallback: worktrees whose removal exhausted Stage 1
+ * are recorded in the gitignored `.worktrees/.pending-cleanup.json` and
+ * retried by the next plan-time sweep, once OS file locks have usually gone.
  *
- * Stage 2 of the Windows worktree reap fallback (see #386).
- *
- * When Stage 1 (`removeWorktreeWithRecovery` → `fs.rm`) exhausts its retries
- * on a Windows lock-class failure, the entry is appended to
- * `.worktrees/.pending-cleanup.json`. The plan-time `worktree-sweep.js`
- * reader (shipped in Epic #349) picks up the manifest on the next
- * `/mandrel-plan` run and retries removal
- * (`git worktree remove` then `fs.rm`) — by then the live file handles from Node / AV / the Windows
- * Search indexer are almost always gone. If `MAX_SWEEP_ATTEMPTS` elapses
- * without clearing, an `OPERATOR ACTION REQUIRED: persistent-lock` line
- * fires and the entry stays in the manifest so the signal persists.
- *
- * The manifest itself lives under `.worktrees/`, which is already
- * git-ignored; no tracked state is mutated.
- *
- * **Story #5112 — the manifest is shared mutable state.** `recordPendingCleanup`
- * runs from the close reap and `drainPendingCleanup` runs from the `/mandrel-plan`
- * boot, so two concurrent delivery sessions can read-modify-write the same
- * file. Three properties close that:
- *
- *   1. **Atomic write.** Every write lands in a pid-scoped temp file and is
- *      then `rename`d over the manifest, so a reader never observes a half-
- *      written array (`readManifest` treats a torn or absent file as empty,
- *      which used to silently *drop* the backlog).
- *   2. **Mutual exclusion.** Read-modify-write runs under the shared
- *      `acquireSweepLock` primitive on a manifest-adjacent lockfile.
- *   3. **Merge before write.** The drain holds its snapshot across awaited
- *      removals, so it re-reads and merges by `storyId` before its final
- *      write — an entry recorded mid-drain survives instead of being erased
- *      by a stale snapshot.
+ * Concurrent sessions read-modify-write this manifest, so every write is
+ * atomic (temp + rename), runs under a lock, and the drain merges by
+ * `storyId` against the current file before writing.
  */
 
 import fs from 'node:fs';
@@ -42,18 +17,9 @@ import { acquireSweepLock } from '../../single-story-sweep/sweep-lock.js';
 const MANIFEST_FILENAME = '.pending-cleanup.json';
 const MANIFEST_LOCK_FILENAME = '.pending-cleanup.lock';
 
-/**
- * Staleness threshold for the manifest lock. Deliberately short: the guarded
- * section is a read, an in-memory merge and a rename — milliseconds — so a
- * lockfile older than this is a crashed holder, not a slow one.
- */
+/** Short: the guarded section takes milliseconds, so older means crashed. */
 const MANIFEST_LOCK_TIMEOUT_MS = 5_000;
-/**
- * After a reap hands off to the manifest, `attempts` counts failed
- * `drainPendingCleanup` passes (initial hand-off uses `attempts: 0`). The entry
- * becomes `persistent` when `attempts` reaches this threshold after another
- * failed drain (i.e. three consecutive sweep failures).
- */
+/** Failed drains (hand-off starts at 0) before an entry is `persistent`. */
 export const MAX_SWEEP_ATTEMPTS = 3;
 
 export function manifestPath(worktreeRoot) {
@@ -61,12 +27,6 @@ export function manifestPath(worktreeRoot) {
 }
 
 /**
- * Path of the lockfile guarding manifest read-modify-write. Manifest-adjacent
- * (same gitignored `.worktrees/` directory) so it needs no extra config and
- * shares the manifest's lifetime. Module-private: the lock is internal to
- * this manifest's read-modify-write, and callers only ever observe that a
- * mutation completed and left nothing behind.
- *
  * @param {string} worktreeRoot
  * @returns {string}
  */
@@ -75,10 +35,9 @@ function manifestLockPath(worktreeRoot) {
 }
 
 /**
- * Run `fn` under the manifest lock. Best-effort in the same sense as every
- * other use of this primitive: on contention the work still runs (the
- * merge-before-write below is what makes a lost race non-destructive), so a
- * stuck lockfile can never wedge a reap. Always releases.
+ * Run `fn` under the manifest lock. Best-effort: on contention `fn` still
+ * runs (merge-before-write keeps a lost race harmless), so a stuck lockfile
+ * never wedges a reap.
  *
  * @template T
  * @param {string} worktreeRoot
@@ -116,11 +75,7 @@ export function readManifest(worktreeRoot) {
 }
 
 /**
- * Write the manifest atomically: serialize into a pid-scoped temp file in the
- * same directory (so `rename` stays within one filesystem and is therefore
- * atomic), then rename it over the manifest. A concurrent reader sees either
- * the whole previous manifest or the whole new one — never a truncated array
- * that `readManifest`'s catch would silently turn into "no pending cleanups".
+ * Atomic write: a torn file would read as empty and silently drop the backlog.
  */
 function writeManifest(worktreeRoot, entries) {
   const p = manifestPath(worktreeRoot);
@@ -137,11 +92,8 @@ function writeManifest(worktreeRoot, entries) {
 }
 
 /**
- * Write `contents` to `targetPath` atomically: serialize into a pid-scoped
- * temp file beside it (same directory, so the rename stays within one
- * filesystem and is therefore atomic), then rename it into place. On failure
- * the temp file is reaped and the error propagates — a half-written file is
- * never left where a reader could pick it up.
+ * Pid-scoped temp file in the same directory (so rename is atomic), renamed
+ * into place; on failure the temp is reaped and the error propagates.
  *
  * @param {string} targetPath
  * @param {string} contents
@@ -157,28 +109,21 @@ function writeFileAtomic(targetPath, contents) {
   }
 }
 
-/** Best-effort removal of an abandoned atomic-write temp file. */
 function reapTempFile(tmp) {
   try {
     fs.unlinkSync(tmp);
   } catch {
-    // Temp file already gone (or never created) — nothing to reap.
+    // Already gone.
   }
 }
 
 /**
- * Upsert a pending-cleanup entry by storyId. Preserves `firstFailedAt` on
- * repeated failures; always updates `lastFailedAt` and increments
- * `attempts`. New rows start at `attempts: 0` (hand-off, not yet a failed
- * sweep). Called by Stage 1 when fs.rm exhausts its retries.
+ * Upsert by storyId, keeping `firstFailedAt`; new rows start at `attempts: 0`.
  */
 export function recordPendingCleanup(
   worktreeRoot,
   { storyId, branch, path: wtPath, push = false },
 ) {
-  // The read, the merge and the write are one critical section: without the
-  // lock a concurrent drain's write can land between our read and our write
-  // and erase this hand-off entirely.
   return withManifestLock(worktreeRoot, () => {
     const now = new Date().toISOString();
     const entries = readManifest(worktreeRoot);
@@ -289,18 +234,12 @@ async function retryStage1ForEntry(entry, ctx) {
 }
 
 /**
- * Write the drain's result, merged against whatever the manifest holds *now*.
- *
- * The drain awaits a removal per entry, so its `entries` snapshot can be
- * minutes old by the time it writes. Writing that snapshot back wholesale
- * erased any entry a concurrent `recordPendingCleanup` added mid-drain — the
- * exact hand-off that reap had just decided it could not complete. Merging by
- * `storyId` keeps it: rows this pass re-computed win, rows it successfully
- * drained are dropped, and everything else the manifest has gained survives.
+ * Write the drain result merged by `storyId` against the manifest as it is
+ * now, so an entry recorded during the (slow) drain survives.
  *
  * @param {string} worktreeRoot
- * @param {object[]} next          Rows this drain re-computed (still pending).
- * @param {Set<number|string>} drainedIds Story ids this drain cleared.
+ * @param {object[]} next          Rows still pending after this drain.
+ * @param {Set<number|string>} drainedIds
  */
 function commitDrainedManifest(worktreeRoot, next, drainedIds) {
   withManifestLock(worktreeRoot, () => {
@@ -315,11 +254,8 @@ function commitDrainedManifest(worktreeRoot, next, drainedIds) {
 }
 
 /**
- * Drain the pending-cleanup manifest: for each entry, retry Stage 1
- * cleanup. Successful entries are removed; failing entries have their
- * `attempts` incremented. Entries whose attempts reach `MAX_SWEEP_ATTEMPTS`
- * trigger an `OPERATOR ACTION REQUIRED: persistent-lock` log line but
- * remain in the manifest so the signal persists across subsequent sweeps.
+ * Retry each entry; persistent entries log OPERATOR ACTION REQUIRED but stay
+ * in the manifest so the signal persists.
  */
 export async function drainPendingCleanup({
   repoRoot,