mandrel 1.57.0

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

@@ -0,0 +1,219 @@
+/**
+ * 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.
+ *
+ * @module lib/orchestration/git-cleanup/phases/branches-reap
+ */
+
+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.
+ */
+export function reapWorktree({
+  cand,
+  removeWorktreeFn,
+  cwd,
+  logger,
+  worktrees,
+  failures,
+  deferred = [],
+  recordPendingCleanupFn = null,
+  worktreeRoot = null,
+}) {
+  if (!cand.hasWorktree || !cand.worktreePath) return true;
+  const wtRes = removeWorktreeFn(cand.worktreePath, cwd);
+  worktrees.push({
+    path: cand.worktreePath,
+    ok: wtRes.ok,
+    dirty: wtRes.dirty,
+    lockClass: wtRes.lockClass ?? false,
+    stderr: wtRes.stderr,
+  });
+  if (wtRes.dirty && wtRes.ok) {
+    logger.warn?.(
+      `${TAG} ⚠️ dirty worktree force-removed: ${cand.worktreePath}`,
+    );
+  }
+  if (wtRes.ok) return true;
+  if (wtRes.lockClass) {
+    recordDeferredWorktree({
+      cand,
+      wtRes,
+      logger,
+      deferred,
+      recordPendingCleanupFn,
+      worktreeRoot,
+    });
+    return false;
+  }
+  failures.push({
+    branch: cand.branch,
+    scope: 'worktree',
+    stderr: wtRes.stderr,
+  });
+  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,
+  logger,
+  deferred,
+  recordPendingCleanupFn,
+  worktreeRoot,
+}) {
+  let pendingCleanup = null;
+  const storyId = storyIdFromBranch(cand.branch);
+  if (recordPendingCleanupFn && worktreeRoot && storyId != null) {
+    try {
+      pendingCleanup = recordPendingCleanupFn(worktreeRoot, {
+        storyId,
+        branch: cand.branch,
+        path: cand.worktreePath,
+        push: false,
+      });
+    } catch (err) {
+      logger.warn?.(
+        `${TAG} ⚠️ pending-cleanup handoff failed for ${cand.branch}: ${err?.message ?? err}`,
+      );
+    }
+  }
+  deferred.push({
+    branch: cand.branch,
+    path: cand.worktreePath,
+    reason: 'worktree-lock',
+    stderr: wtRes.stderr,
+    pendingCleanup,
+  });
+  logger.warn?.(
+    `${TAG} ⚠️ worktree ${cand.worktreePath} could not be removed (file lock); ` +
+      `ref reaped, directory deferred to pending-cleanup sweep`,
+  );
+}
+
+/**
+ * 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).
+ */
+function storyIdFromBranch(branch) {
+  const m = /^story-(\d+)$/.exec(branch ?? '');
+  return m ? Number(m[1]) : null;
+}
+
+export function reapLocalRef({ cand, deleteLocalFn, cwd, local, failures }) {
+  if (cand.localExists === false) return true;
+  const localRes = deleteLocalFn(cand.branch, cwd);
+  local.push({
+    branch: cand.branch,
+    ok: localRes.deleted,
+    reason: localRes.reason,
+    alreadyGone: localRes.reason === 'not-found',
+    stderr: localRes.stderr,
+  });
+  if (!localRes.deleted) {
+    failures.push({
+      branch: cand.branch,
+      scope: 'local',
+      reason: localRes.reason,
+      stderr: localRes.stderr,
+    });
+    return false;
+  }
+  return true;
+}
+
+export function reapRemoteRef({
+  cand,
+  deleteRemoteFn,
+  cwd,
+  remoteResults,
+  failures,
+}) {
+  const remoteRes = deleteRemoteFn(cand.branch, cwd);
+  remoteResults.push({
+    branch: cand.branch,
+    ok: remoteRes.deleted,
+    reason: remoteRes.reason,
+    alreadyGone: remoteRes.reason === 'not-found',
+    stderr: remoteRes.stderr,
+  });
+  if (!remoteRes.deleted) {
+    failures.push({
+      branch: cand.branch,
+      scope: 'remote',
+      reason: remoteRes.reason,
+      stderr: remoteRes.stderr,
+    });
+  }
+}
+
+export function buildPruneSummary({
+  pruneRemoteFn,
+  cwd,
+  remoteName,
+  failures,
+}) {
+  const pruneRes = pruneRemoteFn(cwd, remoteName);
+  const prune = {
+    attempted: true,
+    ok: pruneRes.ok,
+    remote: remoteName,
+    pruned: pruneRes.pruned ?? [],
+    stderr: pruneRes.stderr,
+  };
+  if (!pruneRes.ok) {
+    failures.push({ branch: null, scope: 'prune', stderr: pruneRes.stderr });
+  }
+  return prune;
+}

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

@@ -0,0 +1,309 @@
+/**
+ * branches.js — branch-reap phase of git-cleanup (Story #2466).
+ * Owns `planCleanup` + `executeCleanup`. Reap helpers live in
+ * `branches-reap.js`.
+ * @module lib/orchestration/git-cleanup/phases/branches
+ */
+
+import { dirname } from 'node:path';
+
+import {
+  deleteBranchLocal,
+  deleteBranchRemote,
+} from '../../../git-branch-cleanup.js';
+import { Logger } from '../../../Logger.js';
+import { recordPendingCleanup } from '../../../worktree/lifecycle/pending-cleanup.js';
+import {
+  buildPruneSummary,
+  reapLocalRef,
+  reapRemoteRef,
+  reapWorktree,
+} from './branches-reap.js';
+import { computeProtectedReason } from './filters.js';
+import {
+  branchTipSha,
+  classifyLatestPr,
+  currentBranch as defaultCurrentBranch,
+  listLocalBranches,
+  listMergedBranches,
+  listRemoteBranches,
+  probeAllPrs,
+  probeLatestPr,
+  pruneRemoteTracking,
+  readProtectedConfig,
+  removeWorktree,
+  worktreesByBranch,
+} from './git-probes.js';
+import { parsePrunedRefs } from './prune.js';
+
+function skipEntryFromVerdict(branch, verdict) {
+  const entry = { branch, reason: verdict.reason };
+  if (verdict.prNumber != null) entry.prNumber = verdict.prNumber;
+  if (verdict.tipSha) entry.tipSha = verdict.tipSha;
+  if (verdict.mergedSha) entry.mergedSha = verdict.mergedSha;
+  return entry;
+}
+
+function evaluateLocalBranch({
+  branch,
+  classify,
+  filter,
+  mergedByGit,
+  prProbe,
+  cwd,
+  wtMap,
+  remoteName,
+  branchTipShaFn,
+}) {
+  const protectedReason = classify(branch);
+  if (protectedReason) return { skip: { branch, reason: protectedReason } };
+  if (!filter(branch)) return { skip: { branch, reason: 'filtered' } };
+  const prInfo = prProbe(branch, cwd);
+  const verdict = classifyLatestPr({
+    prInfo,
+    branch,
+    cwd,
+    remoteName,
+    localExists: true,
+    branchTipShaFn,
+  });
+  if (verdict.kind === 'skip') {
+    return { skip: skipEntryFromVerdict(branch, verdict) };
+  }
+  let detectedBy = null;
+  let resolvedPrInfo = null;
+  if (verdict.kind === 'candidate') {
+    detectedBy = 'gh';
+    resolvedPrInfo = verdict.prInfo;
+  } else if (mergedByGit.has(branch)) {
+    detectedBy = 'git-merged';
+  } else {
+    return { skip: { branch, reason: 'not-merged' } };
+  }
+  const wt = wtMap.get(branch);
+  return {
+    candidate: {
+      branch,
+      prNumber: resolvedPrInfo?.number ?? null,
+      mergedAt: resolvedPrInfo?.mergedAt ?? null,
+      hasWorktree: !!wt,
+      worktreePath: wt?.path ?? null,
+      detectedBy,
+      localExists: true,
+    },
+  };
+}
+
+function collectRemoteOnlyCandidates({
+  remoteLister,
+  remoteName,
+  cwd,
+  localSet,
+  classify,
+  filter,
+  prProbe,
+  branchTipShaFn,
+  skipped,
+}) {
+  const out = [];
+  for (const branch of remoteLister(cwd, remoteName)) {
+    if (localSet.has(branch)) continue;
+    if (classify(branch)) continue;
+    if (!filter(branch)) continue;
+    const prInfo = prProbe(branch, cwd);
+    const verdict = classifyLatestPr({
+      prInfo,
+      branch,
+      cwd,
+      remoteName,
+      localExists: false,
+      branchTipShaFn,
+    });
+    if (verdict.kind === 'no-pr') continue;
+    if (verdict.kind === 'skip') {
+      skipped.push(skipEntryFromVerdict(branch, verdict));
+      continue;
+    }
+    out.push({
+      branch,
+      prNumber: verdict.prInfo.number ?? null,
+      mergedAt: verdict.prInfo.mergedAt ?? null,
+      hasWorktree: false,
+      worktreePath: null,
+      detectedBy: 'remote-only',
+      localExists: false,
+    });
+  }
+  return out;
+}
+
+/**
+ * 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'`. When the latest PR is MERGED
+ * but the branch tip has diverged from the PR's `headRefOid` (post-merge
+ * force-push), the branch is skipped with
+ * `reason: 'tip-diverged-from-merge'`.
+ *
+ * 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.
+ */
+export function planCleanup(ctx) {
+  const {
+    cwd,
+    baseBranch,
+    localLister = listLocalBranches,
+    mergedLister = listMergedBranches,
+    currentBranchFn = defaultCurrentBranch,
+    protectedConfigFn = readProtectedConfig,
+    worktreesFn = worktreesByBranch,
+    prProbe: injectedPrProbe,
+    prIndexFn = probeAllPrs,
+    prFallback = probeLatestPr,
+    branchTipShaFn = branchTipSha,
+    filter = () => true,
+    includeRemoteOnly = false,
+    remoteLister = listRemoteBranches,
+    remoteName = 'origin',
+  } = ctx;
+  const prProbe =
+    injectedPrProbe ??
+    (() => {
+      const prIndex = prIndexFn(cwd);
+      return (branch, c) =>
+        prIndex.has(branch) ? prIndex.get(branch) : prFallback(branch, c);
+    })();
+  const resolvedCurrent = currentBranchFn(cwd);
+  const resolvedConfigured = protectedConfigFn(cwd);
+  const classify = (branch) =>
+    computeProtectedReason({
+      baseBranch,
+      currentBranch: resolvedCurrent,
+      configured: resolvedConfigured,
+      branch,
+    });
+  const wtMap = worktreesFn(cwd);
+  const mergedByGit = new Set(mergedLister(cwd, baseBranch));
+  const localBranches = localLister(cwd);
+  const localSet = new Set(localBranches);
+  const candidates = [];
+  const skipped = [];
+  for (const branch of localBranches) {
+    const out = evaluateLocalBranch({
+      branch,
+      classify,
+      filter,
+      mergedByGit,
+      prProbe,
+      cwd,
+      wtMap,
+      remoteName,
+      branchTipShaFn,
+    });
+    if (out.skip) skipped.push(out.skip);
+    else candidates.push(out.candidate);
+  }
+  if (includeRemoteOnly) {
+    candidates.push(
+      ...collectRemoteOnlyCandidates({
+        remoteLister,
+        remoteName,
+        cwd,
+        localSet,
+        classify,
+        filter,
+        prProbe,
+        branchTipShaFn,
+        skipped,
+      }),
+    );
+  }
+  return { candidates, skipped };
+}
+
+/**
+ * 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).
+ */
+function worktreeRootFor(cand) {
+  if (!cand.worktreePath) return null;
+  return dirname(cand.worktreePath);
+}
+
+/**
+ * Pure-ish: execute the branch reap plan.
+ *
+ * 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.
+ */
+export function executeCleanup(ctx) {
+  const {
+    candidates,
+    cwd,
+    remote,
+    removeWorktreeFn = removeWorktree,
+    deleteLocalFn = (b, c) => deleteBranchLocal(b, { cwd: c, force: true }),
+    deleteRemoteFn = (b, c) => deleteBranchRemote(b, { cwd: c }),
+    pruneRemoteFn = (c, r) => pruneRemoteTracking(c, r, parsePrunedRefs),
+    recordPendingCleanupFn = recordPendingCleanup,
+    remoteName = 'origin',
+    logger = Logger,
+  } = ctx;
+  const worktrees = [];
+  const local = [];
+  const remoteResults = [];
+  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,
+      cwd,
+      logger,
+      worktrees,
+      failures,
+      deferred,
+      recordPendingCleanupFn,
+      worktreeRoot: worktreeRootFor(cand),
+    });
+    if (!reapLocalRef({ cand, deleteLocalFn, cwd, local, failures })) continue;
+    if (remote)
+      reapRemoteRef({ cand, deleteRemoteFn, cwd, remoteResults, failures });
+  }
+  let prune = null;
+  if (remote && remoteResults.length > 0) {
+    prune = buildPruneSummary({ pruneRemoteFn, cwd, remoteName, failures });
+  }
+  return {
+    worktrees,
+    local,
+    remote: remoteResults,
+    prune,
+    failures,
+    deferred,
+    ok: failures.length === 0,
+  };
+}

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

@@ -0,0 +1,99 @@
+/**
+ * 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`.
+ *
+ * @module lib/orchestration/git-cleanup/phases/cli
+ */
+
+import path from 'node:path';
+
+import { PROJECT_ROOT, resolveConfig } from '../../../config-resolver.js';
+import { parseCleanupArgs } from './parse-args.js';
+import {
+  runBranchPhase,
+  runFastForwardPhase,
+  runPrunePhase,
+  runStashPhase,
+} from './phase-drivers.js';
+import { buildJsonEnvelope, computeExitCode } from './render.js';
+
+/* node:coverage ignore next */
+function resolveBaseBranch(cwd, override) {
+  if (override) return override;
+  try {
+    const cfg = resolveConfig({ cwd });
+    return cfg?.project?.baseBranch || cfg?.agentSettings?.baseBranch || 'main';
+  } catch {
+    return 'main';
+  }
+}
+
+/* node:coverage ignore next */
+async function runActivePhases(opts, cwd, baseBranch) {
+  const out = {
+    fastForward: null,
+    prune: null,
+    branchesPlan: null,
+    branchesResult: null,
+    stashes: null,
+  };
+  if (opts.phases.fastForwardMain) {
+    out.fastForward = await runFastForwardPhase(opts, cwd, baseBranch);
+  }
+  if (opts.phases.pruneRemotes) {
+    out.prune = await runPrunePhase(opts, cwd);
+  }
+  if (opts.phases.branches) {
+    const r = await runBranchPhase(opts, cwd, baseBranch);
+    out.branchesPlan = r.plan;
+    out.branchesResult = r.result;
+  }
+  if (opts.phases.stashes) {
+    out.stashes = await runStashPhase(opts, cwd);
+  }
+  return out;
+}
+
+/* node:coverage ignore next */
+function maybeEmitJson(opts, baseBranch, phaseResults) {
+  if (!opts.json) return;
+  const envelope = buildJsonEnvelope({
+    dryRun: opts.dryRun,
+    baseBranch,
+    plan: phaseResults.branchesPlan ?? { candidates: [], skipped: [] },
+    result: phaseResults.branchesResult,
+    fastForward: phaseResults.fastForward,
+    prune: phaseResults.prune,
+    stashes: phaseResults.stashes,
+  });
+  process.stdout.write(`${JSON.stringify(envelope)}\n`);
+}
+
+/**
+ * Run the full multi-phase pipeline and return the operator-facing
+ * envelope plus the resolved exit code. The CLI shell wraps this in
+ * `runAsCli(...)` and applies `process.exit(envelope.exitCode)` at the
+ * harness boundary so library code stays free of direct `process.exit`
+ * calls (see `tests/enforcement/process-exit.test.js`).
+ */
+/* node:coverage ignore next */
+export async function runCleanup() {
+  const opts = parseCleanupArgs(process.argv.slice(2));
+  const cwd = path.resolve(opts.cwd ?? PROJECT_ROOT);
+  const baseBranch = resolveBaseBranch(cwd, opts.base);
+  const phaseResults = await runActivePhases(opts, cwd, baseBranch);
+  maybeEmitJson(opts, baseBranch, phaseResults);
+  return {
+    exitCode: computeExitCode({
+      branchesPlan: phaseResults.branchesPlan,
+      branchesResult: phaseResults.branchesResult,
+      fastForward: phaseResults.fastForward,
+      prune: phaseResults.prune,
+      stashes: phaseResults.stashes,
+    }),
+  };
+}