mandrel 2.59.0 → 2.61.0

package/.agents/scripts/lib/orchestration/git-cleanup/phases/branches-reap.js

@@ -1,36 +1,6 @@
 /**
- * branches-reap.js — per-candidate reap helpers for the branches phase
- * of git-cleanup (Story #2466).
- *
- * Split out of `branches.js` so each phase file stays under Story
- * #2466's 200-LOC ceiling. Exports four small functions that the
- * branches-phase orchestrator (`executeCleanup`) composes:
- *
- *   - `reapWorktree({ cand, … })` — `git worktree remove` (with force
- *     fallback) and push the result onto `worktrees`.
- *   - `reapLocalRef({ cand, … })` — `git branch -D`, skipped on
- *     remote-only candidates.
- *   - `reapRemoteRef({ cand, … })` — `git push --delete <remote>`.
- *   - `buildPruneSummary({ … })` — trailing `git fetch --prune` to
- *     drop tracking refs left behind by remote deletes.
- *
- * Every helper records its outcome on the supplied accumulator arrays
- * and pushes hard failures onto `failures`.
- *
- * ## Ref-reap is decoupled from worktree-reap (Story #3598)
- *
- * The candidate set is, by construction, already-merged (the planner
- * resolves each candidate's merged PR / `git merge-base` state). A
- * failure to physically remove the worktree *directory* must NOT strand
- * the merged branch *ref*: a leftover directory is recoverable garbage,
- * a stranded merged ref clutters every subsequent run. So `reapWorktree`
- * no longer gates the ref reap — `executeCleanup` always proceeds to
- * `reapLocalRef` / `reapRemoteRef` after it, regardless of the worktree
- * outcome. Lock-class removal failures (Windows handles on
- * `node_modules` / test artifacts) are recorded as **deferred** entries
- * and handed off to the `pending-cleanup` manifest rather than pushed
- * onto `failures`, so an OS file lock on an already-merged branch's
- * directory does not make `git-cleanup` exit non-zero.
+ * Per-candidate reap helpers for git-cleanup's branches phase. Each records
+ * its outcome on the supplied accumulators and hard failures on `failures`.
  *
  * @module lib/orchestration/git-cleanup/phases/branches-reap
  */
@@ -38,20 +8,10 @@
 const TAG = '[git-cleanup]';
 
 /**
- * Attempt to remove a candidate's worktree directory. Records the outcome
- * on `worktrees`. A successful (or absent) removal is silent. A failed
- * removal is split by class:
- *
- *   - **lock-class** (`wtRes.lockClass`) → recorded on `deferred` and, when
- *     a `recordPendingCleanupFn` + `worktreeRoot` are supplied, handed off
- *     to the pending-cleanup manifest. Non-fatal — the run does not exit 1.
- *   - **non-lock** → pushed onto `failures` (a genuine, operator-visible
- *     git error worth surfacing as a failure).
- *
- * Unlike the pre-#3598 contract, the return value does **not** gate the
- * subsequent ref reap; `executeCleanup` always proceeds to delete the
- * (already-merged) ref. The boolean is retained only as a "removal
- * succeeded" signal for callers that want it.
+ * Remove a candidate's worktree. A lock-class failure is deferred to the
+ * pending-cleanup manifest (non-fatal); any other failure is a hard failure.
+ * The return value never gates the ref reap: a leftover directory must not
+ * strand an already-merged ref.
  */
 export function reapWorktree({
   cand,
@@ -98,12 +58,6 @@ export function reapWorktree({
   return false;
 }
 
-/**
- * Record a lock-class worktree-removal failure as a non-fatal deferred
- * entry and hand it off to the pending-cleanup manifest when wired. The
- * merged branch ref is still reaped by `executeCleanup`; only the locked
- * directory is left for the next plan-time worktree-sweep to drain.
- */
 function recordDeferredWorktree({
   cand,
   wtRes,
@@ -141,11 +95,7 @@ function recordDeferredWorktree({
   );
 }
 
-/**
- * Parse the numeric story id out of a `story-<id>` branch name. Returns
- * `null` for non-story branches (the pending-cleanup manifest is keyed by
- * `storyId`, so only `story-*` candidates get a manifest handoff).
- */
+/** Story id of a `story-<id>` branch (the manifest key), else `null`. */
 function storyIdFromBranch(branch) {
   const m = /^story-(\d+)$/.exec(branch ?? '');
   return m ? Number(m[1]) : null;

package/.agents/scripts/lib/orchestration/git-cleanup/phases/branches.js

@@ -1,8 +1,5 @@
 /**
- * branches.js — branch-reap phase of git-cleanup (Story #2466).
- * Owns `planCleanup` + `executeCleanup`. Reap helpers live in
- * `branches-reap.js`; the non-PR detection signals and the remote-only
- * walk live in `branches-detect.js`.
+ * Branch-reap phase of git-cleanup: `planCleanup` + `executeCleanup`.
  * @module lib/orchestration/git-cleanup/phases/branches
  */
 
@@ -51,14 +48,8 @@ import { parsePrunedRefs } from './prune.js';
 const TAG = '[git-cleanup]';
 
 /**
- * The detection signal the weak-signal guard withholds on, and the reason
- * it records (Story #5283). `content-merged` comes from
- * `git merge-tree --write-tree` finding the branch's changes already
- * present in the base by *some* route — it cannot tell a squash-merge
- * from a branch whose every change was independently reverted, so it is
- * the one signal an unattended `--yes` run must not delete a remote ref
- * on. Named here so the guard, the renderer and the tests share one
- * spelling.
+ * `content-merged` cannot tell a squash-merge from independently reverted
+ * changes, so an unattended `--yes` run must not delete a remote ref on it.
  */
 const WEAK_SIGNAL_DETECTOR = 'content-merged';
 const WEAK_SIGNAL_REASON = 'weak-signal-needs-confirmation';
@@ -128,68 +119,8 @@ function evaluateLocalBranch({
 }
 
 /**
- * Pure-ish: enumerate merged-branch candidates.
- *
- * The PR probe classifies each candidate by the **latest** PR on the head
- * ref rather than any historical merge. Branches whose latest PR is OPEN
- * or CLOSED-not-merged are skipped with `reason: 'latest-pr-open'` /
- * `reason: 'latest-pr-closed-not-merged'`. A MERGED PR whose `headRefOid`
- * differs from the branch tip is resolved by ancestry in
- * `merged-tip.js` — a tip *behind* the merged head becomes a candidate
- * carrying `behindMerge: true`, a tip *ahead* of it keeps the
- * `tip-diverged-from-merge` force-push skip, and an unresolvable rev
- * skips as `unverifiable`.
- *
- * Performance (Story #3333): when the caller does not inject its own
- * `prProbe`, the planner fires **one** bulk `gh pr list --state all`
- * (via {@link probeAllPrs}) up front and indexes the page by
- * `headRefName`. Each branch loop then reads its PR signal from that Map
- * instead of spawning a per-branch `gh`. {@link probeLatestPr} remains
- * the per-branch fallback for head refs absent from the bulk page (a PR
- * that fell outside the fetch window), so correctness is preserved for
- * every branch. Injecting `prProbe` bypasses the bulk fetch entirely.
- *
- * Story #4395 adds three refinements:
- *   - **Content-equivalence signal.** A local branch with no reapable PR
- *     verdict and no ancestry match gets one more chance via
- *     {@link probeContentEquivalent} (`git merge-tree --write-tree`):
- *     when merging it into `baseBranch` would be a content no-op, it is
- *     classified `detectedBy: 'content-merged'` instead of skipped.
- *   - **Fresh ancestry anchor.** The ancestry signal (`git branch --merged`)
- *     is unioned against `origin/<base>` (via `refExistsFn` + `mergedLister`)
- *     whenever that remote-tracking ref exists, so a stale local `<base>`
- *     no longer hides a branch already merged on the remote.
- *   - **Graceful `gh` degradation.** A throwing `gh` runner (auth failure,
- *     rate limit, missing binary) inside the bulk index fetch or the
- *     per-branch fallback is caught, logged once, and degrades to
- *     git-only signals (ancestry + content-equivalence) rather than
- *     aborting the whole plan. The returned envelope's `ghDegraded` flag
- *     records whether this happened.
- *
- * Story #5188 makes the **remote-only** walk total (it now lives in
- * `branches-detect.js`). It used to classify by
- * the latest-PR verdict alone and return early on a `no-pr` verdict,
- * recording neither a candidate nor a skip — so a remote ref no PR record
- * covered was absent from `candidates[]`, `skipped[]`, the rendered log
- * and the `--json` envelope alike. It now runs the same three-signal
- * cascade the local walk does (PR verdict → ancestry → content
- * -equivalence → `not-merged` skip), over its own remote-namespace
- * ancestry source and with every git probe handed the qualified
- * `<remote>/<branch>` rev. Every enumerated branch that passes the
- * protected and filter checks therefore lands in exactly one of the two
- * collections. Deletion is unchanged: a remote-only candidate still needs
- * `--remote`, whichever signal detected it.
- */
-/**
- * Normalize whatever `prIndexFn` returned into the
- * `{ index, complete }` pair {@link probeAllPrs} emits (Story #5283).
- *
- * The seam is injectable, and a caller that hands back a bare `Map` —
- * every pre-#5283 double does — means "here is the page" without
- * claiming it was exhaustive. That reads as `complete: false`, which
- * keeps the per-branch fallback armed: the conservative direction, since
- * a wrongly-complete page suppresses a probe that would have found a
- * real PR.
+ * Normalize `prIndexFn`'s result to `{ index, complete }`. A bare `Map` reads
+ * as incomplete, keeping the per-branch fallback armed (the safe direction).
  *
  * @param {unknown} value
  * @returns {{ index: Map, complete: boolean }}
@@ -213,11 +144,7 @@ function buildGuardedPrProbe({ cwd, prIndexFn, prFallback, onDegrade }) {
   const { index: prIndex, complete } = bulk;
   return (branch, c) => {
     if (prIndex.has(branch)) return prIndex.get(branch);
-    // Story #5283: a complete page listed every PR in the repo, so this
-    // head ref demonstrably has none. Probing it per-branch spends a `gh`
-    // spawn to be told the same thing — once per PR-less branch, which on
-    // a checkout full of local scratch branches is the whole point of the
-    // bulk fetch undone.
+    // A complete page proves this head ref has no PR; skip the `gh` spawn.
     if (complete) return null;
     try {
       return prFallback(branch, c);
@@ -228,6 +155,13 @@ function buildGuardedPrProbe({ cwd, prIndexFn, prFallback, onDegrade }) {
   };
 }
 
+/**
+ * Enumerate merged-branch candidates. Signals cascade: latest PR on the head
+ * ref (one bulk `gh` fetch, per-branch fallback) → ancestry against local and
+ * `<remote>/<base>` → content-equivalence. A failing `gh` degrades once to
+ * git-only signals (`ghDegraded`). Every enumerated branch lands in exactly
+ * one of `candidates` / `skipped`.
+ */
 export function planCleanup(ctx) {
   const {
     cwd,
@@ -329,45 +263,18 @@ export function planCleanup(ctx) {
   return { candidates, skipped, ghDegraded };
 }
 
-/**
- * Derive the pending-cleanup manifest root from a candidate's worktree
- * path. The manifest lives in the worktree root (`.worktrees/`), and a
- * candidate's `worktreePath` is `<root>/story-<id>`, so the parent
- * directory is the root. Returns `null` when the candidate has no
- * worktree path (remote-only / no-worktree candidate).
- */
+/** Pending-cleanup manifest root: the worktree's parent dir, or `null`. */
 function worktreeRootFor(cand) {
   if (!cand.worktreePath) return null;
   return dirname(cand.worktreePath);
 }
 
 /**
- * Pure-ish: execute the branch reap plan.
- *
- * ## Weak-signal guard (Story #5283)
- *
- * `skipWeakSignal` withholds the **remote** delete of any candidate
- * detected only by content-equivalence, recording it on `remote[]` as
- * `{ skipped: true, reason: 'weak-signal-needs-confirmation' }` instead
- * of issuing `git push --delete`. The branch-phase driver arms it on the
- * `--yes` path unless the operator passed `--include-content-merged`,
- * mirroring the stash phase's `--drop-stashes` allowlist: an unattended
- * run may not destroy a remote ref on the weakest merge signal without
- * being told to. The interactive path leaves it disarmed — the prompt
- * already names the weak-signal count and the operator answered it.
- *
- * Local deletion is deliberately untouched: a local ref is recoverable
- * from the remote, which is exactly what the guard preserves.
- *
- * Ref-reap is decoupled from worktree-reap (Story #3598): every
- * already-merged candidate has its local ref (and remote ref, in
- * `--remote` mode) deleted regardless of whether its worktree directory
- * could be physically removed. A lock-class worktree-removal failure is
- * recorded as a non-fatal `deferred` entry + a `pending-cleanup` handoff
- * (drained by the next plan-time worktree-sweep) rather than a hard
- * `failure`, so an OS file lock on an already-merged branch's directory
- * never makes the run exit non-zero. A non-lock worktree failure still
- * surfaces as a hard failure.
+ * Execute the reap plan. `skipWeakSignal` (armed on unattended `--yes` runs)
+ * withholds only the remote delete of `content-merged` candidates; the local
+ * ref stays deletable because the remote preserves it. Ref reap never waits
+ * on worktree removal: a lock-class removal failure is deferred to the
+ * pending-cleanup sweep, not a hard failure.
  */
 export function executeCleanup(ctx) {
   const {
@@ -383,13 +290,7 @@ export function executeCleanup(ctx) {
     skipWeakSignal = false,
     logger = Logger,
   } = ctx;
-  // The remote name belongs to `executeCleanup`, not to the per-candidate
-  // reap helper, so bind it here (Story #5283). The default deleter used
-  // to drop it and let `deleteBranchRemote` fall back to `origin`, which
-  // sent every `--remote` delete of an `upstream`-configured checkout at
-  // the wrong remote. Binding — rather than closing over it — also hands
-  // an injected deleter the same `(branch, cwd, remote)` triple the git
-  // invocation is built from, so a test can see which remote was targeted.
+  // Bind the remote explicitly, or the deleter falls back to `origin`.
   const boundDeleteRemote = (b, c) => deleteRemoteFn(b, c, remoteName);
   const worktrees = [];
   const local = [];
@@ -397,10 +298,6 @@ export function executeCleanup(ctx) {
   const failures = [];
   const deferred = [];
   for (const cand of candidates) {
-    // Worktree removal is attempted but its outcome does NOT gate the ref
-    // reap: the candidate is already merged, so a leftover directory must
-    // never strand the ref. Lock-class removal failures are deferred to
-    // the pending-cleanup sweep inside reapWorktree.
     reapWorktree({
       cand,
       removeWorktreeFn,
@@ -434,9 +331,7 @@ export function executeCleanup(ctx) {
     });
   }
   let prune = null;
-  // Prune drops the tracking refs a remote *delete* left behind. A run
-  // whose every remote candidate was withheld deleted nothing, so there
-  // is nothing stale to prune and no reason to spend the fetch.
+  // Prune only when some remote delete actually ran.
   if (remote && remoteResults.some((r) => !r.skipped)) {
     prune = buildPruneSummary({ pruneRemoteFn, cwd, remoteName, failures });
   }

package/.agents/scripts/lib/orchestration/git-cleanup/phases/cli.js

@@ -1,10 +1,6 @@
 /**
- * cli.js — `main()` entry point for git-cleanup (Story #2466).
- *
- * Owns argv parsing, base-branch resolution, fan-out across the four
- * cleanup phases, and the optional JSON envelope emission. Per-phase
- * orchestrators (`runFastForwardPhase` etc.) live in
- * `phase-drivers.js`; interactive prompts in `prompts.js`.
+ * git-cleanup `main()`: argv, base-branch resolution, the four phases, and
+ * the optional JSON envelope.
  *
  * @module lib/orchestration/git-cleanup/phases/cli
  */

package/.agents/scripts/lib/orchestration/git-cleanup/phases/fast-forward.js

@@ -1,8 +1,5 @@
 /**
- * fast-forward.js — fast-forward-main phase of git-cleanup (Story #2466).
- *
- * Owns `planFastForward(ctx)` and `executeFastForward(ctx)`. Extracted
- * verbatim from `git-cleanup.js`.
+ * Fast-forward-main phase of git-cleanup.
  *
  * @module lib/orchestration/git-cleanup/phases/fast-forward
  */

package/.agents/scripts/lib/orchestration/git-cleanup/phases/filters.js

@@ -1,9 +1,5 @@
 /**
- * filters.js — pure branch-filter helpers for git-cleanup (Story #2466).
- *
- * Exports `buildGlobFilter`, `computeProtectedSet`, and
- * `computeProtectedReason` — extracted verbatim from `git-cleanup.js`
- * so the named-export contract stays byte-identical.
+ * Pure branch-filter and protected-branch helpers for git-cleanup.
  *
  * @module lib/orchestration/git-cleanup/phases/filters
  */

package/.agents/scripts/lib/orchestration/git-cleanup/phases/git-probes-ff.js

@@ -1,10 +1,5 @@
 /**
- * git-probes-ff.js — fast-forward / worktree / prune subprocess wrappers
- * for git-cleanup (Story #2466).
- *
- * Split out of `git-probes.js` so each phase file stays under Story
- * #2466's 200-LOC ceiling. Owns the wrappers the fast-forward-main,
- * prune-remotes, and worktree-reap paths call.
+ * Fast-forward / worktree / prune git wrappers for git-cleanup.
  *
  * @module lib/orchestration/git-cleanup/phases/git-probes-ff
  */
@@ -12,21 +7,16 @@
 import { gitSpawn } from '../../../git-utils.js';
 
 /**
- * Windows file-lock-class failure signatures. Mirrors the regex in
- * `worktree/lifecycle/reap.js` — a `git worktree remove` that fails with
- * one of these is an OS-level lock on the worktree directory (open
- * `node_modules` handles, AV/indexer, test/coverage artifacts), not a
- * git-state problem. Lock-class removal failures degrade to a deferred
- * `pending-cleanup` handoff instead of aborting the candidate's ref reap.
+ * OS file-lock signatures (mirrors `worktree/lifecycle/reap.js`). A lock-class
+ * worktree removal failure defers to pending-cleanup instead of aborting the
+ * ref reap.
  */
 const WORKTREE_LOCK_RE =
   /(permission denied|access is denied|directory not empty|resource busy|device or resource busy|sharing violation|used by another process|EACCES|EBUSY|ENOTEMPTY)/i;
 
 /**
- * Classify a worktree-removal stderr as Windows-lock-class or not.
- *
  * @param {string} stderr
- * @returns {boolean} `true` when the failure looks like an OS file lock.
+ * @returns {boolean}
  */
 export function isWorktreeLockFailure(stderr) {
   return WORKTREE_LOCK_RE.test(stderr ?? '');
@@ -58,15 +48,8 @@ export function mergeFastForward(cwd, ref) {
 }
 
 /**
- * Build the fast-forward probe bundle bound to a `gitSpawn`.
- *
- * This is the **single implementation** of the FF/base-sync git wrappers.
- * The standalone exports above delegate to a default instance bound to the
- * shared `gitSpawn`; callers that need to inject their own spawn for testing
- * (e.g. the epic-cleanup runner) call this factory directly instead of
- * hand-rolling a parallel copy (framework-gap #4379). The bundle also carries
- * `currentBranch` so an injecting caller gets the whole FF surface from one
- * place.
+ * The single implementation of the FF git wrappers; callers needing an
+ * injected spawn use this factory rather than a parallel copy.
  *
  * @param {(cwd: string, ...args: string[]) => { status: number, stdout: string, stderr: string }} [spawn]
  * @returns {{
@@ -131,8 +114,6 @@ export function makeFfProbes(spawn = gitSpawn) {
   };
 }
 
-// Default instance bound to the shared gitSpawn; the standalone wrappers
-// above delegate to it so there is exactly one FF-probe implementation.
 const defaultFfProbes = makeFfProbes(gitSpawn);
 
 /* node:coverage ignore next */
@@ -153,14 +134,8 @@ export function removeWorktree(worktreePath, cwd) {
 }
 
 /**
- * Prune the clone's stale remote-tracking refs and report which ones went.
- *
- * The fetch MUST NOT be `--quiet` (Story #4772). `--quiet` still prunes, but
- * suppresses the `- [deleted] (none) -> <remote>/<ref>` progress lines that
- * are the *only* record of what was dropped — `parsePruneFn` then reports an
- * empty list for work that really happened, and `computeExitCode` reads the
- * run as "nothing to do" (exit 2). The output is captured, not shown, so
- * `--quiet` bought nothing to begin with.
+ * Never `--quiet`: it suppresses the `[deleted]` lines that are the only
+ * record of what was pruned, making real work read as "nothing to do".
  *
  * @param {string} cwd
  * @param {string} remoteName