mandrel 1.57.0

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

@@ -0,0 +1,276 @@
+/**
+ * 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.
+ */
+
+import { spawnSync } from 'node:child_process';
+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;
+
+/**
+ * @param {Awaited<ReturnType<typeof drainPendingCleanup>>} prev
+ * @param {Awaited<ReturnType<typeof drainPendingCleanup>>} next
+ */
+function mergeDrainPasses(prev, next) {
+  const drainedSet = new Set([...prev.drained, ...next.drained]);
+  const drainedDetails = [
+    ...prev.drainedDetails,
+    ...next.drainedDetails.filter(
+      (d) => !prev.drainedDetails.some((f) => f.storyId === d.storyId),
+    ),
+  ];
+  return {
+    drained: [...drainedSet],
+    drainedDetails,
+    persistent: next.persistent,
+    persistentDetails: next.persistentDetails,
+    stillPending: next.stillPending,
+    stillPendingDetails: next.stillPendingDetails,
+  };
+}
+
+/**
+ * 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.
+ *
+ * @param {string} wtPath Absolute path to the worktree directory.
+ * @param {object} [opts]
+ * @param {Function} [opts.spawn] Injection point for tests (default `spawnSync`).
+ * @param {string} [opts.platform] Override `process.platform` for tests.
+ * @returns {Array<{pid:number, name:string, path?:string, commandLine?:string}>}
+ */
+export function findHoldersInPath(wtPath, opts = {}) {
+  const spawn = opts.spawn ?? spawnSync;
+  const platform = opts.platform ?? process.platform;
+  if (platform !== 'win32') return [];
+  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 = [
+    `$needle = '${psNeedle}'`,
+    `$wild = $needle + '*'`,
+    `$wildAny = '*' + $needle + '*'`,
+    `Get-CimInstance Win32_Process |`,
+    `  Where-Object {`,
+    `    ($_.ExecutablePath -and $_.ExecutablePath -like $wild) -or`,
+    `    ($_.CommandLine -and $_.CommandLine -like $wildAny)`,
+    `  } |`,
+    `  Select-Object ProcessId, Name, ExecutablePath, CommandLine |`,
+    `  ConvertTo-Json -Compress -Depth 2`,
+  ].join('\n');
+
+  let res;
+  try {
+    res = spawn(
+      'powershell.exe',
+      ['-NoProfile', '-NonInteractive', '-Command', script],
+      { encoding: 'utf8', timeout: 15_000 },
+    );
+  } catch {
+    return [];
+  }
+  if (!res || res.status !== 0 || !res.stdout) return [];
+
+  const raw = String(res.stdout).trim();
+  if (!raw) return [];
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return [];
+  }
+  const list = Array.isArray(parsed) ? parsed : [parsed];
+  return list
+    .filter((p) => p && typeof p.ProcessId === 'number' && p.ProcessId > 0)
+    .map((p) => ({
+      pid: p.ProcessId,
+      name: typeof p.Name === 'string' ? p.Name : '?',
+      path: typeof p.ExecutablePath === 'string' ? p.ExecutablePath : undefined,
+      commandLine:
+        typeof p.CommandLine === 'string' ? p.CommandLine : undefined,
+    }));
+}
+
+/**
+ * `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.
+ */
+export function terminateHolders(holders, opts = {}) {
+  const spawn = opts.spawn ?? spawnSync;
+  const platform = opts.platform ?? process.platform;
+  const logger = opts.logger ?? NOOP_LOGGER;
+  if (platform !== 'win32') return [];
+  if (!Array.isArray(holders) || holders.length === 0) return [];
+
+  const killed = [];
+  for (const h of holders) {
+    if (!h || typeof h.pid !== 'number') continue;
+    let res;
+    try {
+      res = spawn('taskkill.exe', ['/T', '/F', '/PID', String(h.pid)], {
+        encoding: 'utf8',
+        timeout: 10_000,
+      });
+    } catch (err) {
+      logger.warn(
+        `force-drain: taskkill spawn failed pid=${h.pid}: ${err.message}`,
+      );
+      continue;
+    }
+    if (res && res.status === 0) {
+      killed.push(h.pid);
+      logger.warn(
+        `force-drain: terminated pid=${h.pid} name=${h.name} path=${h.path ?? '?'}`,
+      );
+    } else {
+      const stderr = (res?.stderr || res?.stdout || '').toString().trim();
+      logger.warn(
+        `force-drain: taskkill pid=${h.pid} failed: ${stderr || 'unknown'}`,
+      );
+    }
+  }
+  return killed;
+}
+
+/**
+ * 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.
+ */
+export async function forceDrainPendingCleanup({
+  repoRoot,
+  worktreeRoot,
+  git,
+  fsRm,
+  logger = NOOP_LOGGER,
+  findHolders = findHoldersInPath,
+  killHolders = terminateHolders,
+  sleep = (ms) => new Promise((r) => setTimeout(r, ms)),
+  escalate = true,
+} = {}) {
+  const first = await drainPendingCleanup({
+    repoRoot,
+    worktreeRoot,
+    git,
+    fsRm,
+    logger,
+  });
+
+  const empty = { escalated: [], killedPids: {}, noHolders: [] };
+  if (!escalate) return { ...first, ...empty };
+
+  const stuck = [...first.stillPending, ...first.persistent];
+  if (stuck.length === 0) return { ...first, ...empty };
+
+  const escalated = [];
+  const killedPids = {};
+  const noHolders = [];
+  const stuckSet = new Set(stuck);
+  const entries = readManifest(worktreeRoot).filter((e) =>
+    stuckSet.has(e.storyId),
+  );
+
+  for (const entry of entries) {
+    const holders = findHolders(entry.path);
+    if (holders.length === 0) {
+      logger.warn(
+        `force-drain: no user-mode holders for storyId=${entry.storyId} path=${entry.path} ` +
+          `(likely Search indexer / AV / kernel handle — will retry next sweep)`,
+      );
+      noHolders.push(entry.storyId);
+      continue;
+    }
+    logger.warn(
+      `force-drain: escalating storyId=${entry.storyId} — ${holders.length} holder(s) detected`,
+    );
+    const killed = killHolders(holders, { logger });
+    if (killed.length === 0) continue;
+    killedPids[entry.storyId] = killed;
+    escalated.push(entry.storyId);
+  }
+
+  if (escalated.length === 0) {
+    return { ...first, escalated, killedPids, noHolders };
+  }
+
+  await sleep(SETTLE_MS);
+
+  let followUp = await drainPendingCleanup({
+    repoRoot,
+    worktreeRoot,
+    git,
+    fsRm,
+    logger,
+  });
+
+  const stuckAfter =
+    followUp.stillPending.length + followUp.persistent.length > 0;
+  if (stuckAfter) {
+    await sleep(POST_KILL_RETRY_SETTLE_MS);
+    const third = await drainPendingCleanup({
+      repoRoot,
+      worktreeRoot,
+      git,
+      fsRm,
+      logger,
+    });
+    followUp = mergeDrainPasses(followUp, third);
+  }
+
+  const drainedSet = new Set([...first.drained, ...followUp.drained]);
+  const drainedDetails = [
+    ...first.drainedDetails,
+    ...followUp.drainedDetails.filter(
+      (d) => !first.drainedDetails.some((f) => f.storyId === d.storyId),
+    ),
+  ];
+  return {
+    drained: [...drainedSet],
+    drainedDetails,
+    persistent: followUp.persistent,
+    persistentDetails: followUp.persistentDetails,
+    stillPending: followUp.stillPending,
+    stillPendingDetails: followUp.stillPendingDetails,
+    escalated,
+    killedPids,
+    noHolders,
+  };
+}

package/.agents/scripts/lib/worktree/lifecycle/gc.js

@@ -0,0 +1,49 @@
+/**
+ * worktree/lifecycle/gc.js
+ *
+ * Sweep abandoned worktrees: enumerate every story-<id> worktree git knows
+ * about, drop the ones not in `openStoryIds`, and forward each candidate to
+ * `reap`. Reuses pure helpers from sibling submodules; never touches state
+ * outside `ctx`.
+ */
+
+import { storyIdFromPath } from '../inspector.js';
+import { reap } from './reap.js';
+import { list } from './registry-sync.js';
+import { validateStoryId } from './shared.js';
+
+export async function gc(ctx, openStoryIds, opts = {}) {
+  const open = new Set((openStoryIds ?? []).map((x) => validateStoryId(x)));
+  const worktrees = await list(ctx);
+  const reaped = [];
+  const skipped = [];
+
+  for (const wt of worktrees) {
+    const id = storyIdFromPath(wt.path, ctx.worktreeRoot);
+    if (id === null) continue;
+    if (open.has(id)) continue;
+
+    const result = await reap(ctx, id, {
+      epicBranch: opts.epicBranch ?? null,
+      worktrees,
+      discardAfterMerge: opts.discardAfterMerge,
+    });
+    if (result.removed) {
+      reaped.push({
+        storyId: id,
+        path: wt.path,
+        ...(result.discardedPaths
+          ? { discardedPaths: result.discardedPaths }
+          : {}),
+      });
+    } else {
+      skipped.push({
+        storyId: id,
+        path: wt.path,
+        reason: result.reason ?? 'unknown',
+      });
+    }
+  }
+
+  return { reaped, skipped };
+}

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

@@ -0,0 +1,178 @@
+/**
+ * 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 epicRef`, and a
+ * fallback `git log --grep=resolves #<storyId>` against the Epic ref 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 — the `(resolves #N)` token on
+ * the Epic's `--no-ff` merge commit (emitted by
+ * `story-close/merge-runner.js`) is the durable proof the Story was
+ * integrated.
+ *
+ * Pure with respect to the supplied `ctx` bag; the only side effects are
+ * the `gitSpawn` calls.
+ */
+
+import { parseStoryBranch } from '../../git-utils.js';
+import { resolvesGrepArgs } from '../../orchestration/resolves-token.js';
+
+/**
+ * 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}}
+ */
+export function resolveHeadSha(ctx, wtPath) {
+  const res = ctx.git.gitSpawn(wtPath, 'rev-parse', 'HEAD');
+  if (res.status !== 0) {
+    return { ok: false, reason: `rev-parse-failed: ${res.stderr || 'HEAD'}` };
+  }
+  const sha = res.stdout.trim();
+  return { ok: true, sha, short: sha.slice(0, 7) || 'HEAD' };
+}
+
+/**
+ * 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.
+ *
+ * @param {object} ctx
+ * @param {string} headSha
+ * @param {string} epicRef
+ * @returns {{outcome: 'ancestor'} | {outcome: 'not-ancestor'} | {outcome: 'error', reason: string}}
+ */
+export function checkHeadAncestor(ctx, headSha, epicRef) {
+  const res = ctx.git.gitSpawn(
+    ctx.repoRoot,
+    'merge-base',
+    '--is-ancestor',
+    headSha,
+    epicRef,
+  );
+  if (res.status === 0) return { outcome: 'ancestor' };
+  if (res.status === 1) return { outcome: 'not-ancestor' };
+  return {
+    outcome: 'error',
+    reason: res.stderr || res.stdout || 'unknown',
+  };
+}
+
+/**
+ * Predicate: did the Epic ref accumulate a `--no-ff` merge commit whose
+ * subject names this Story (e.g. `... (resolves #1851)`)? Returns `true`
+ * when the grep finds at least one matching merge commit, `false` when it
+ * returns empty or fails.
+ *
+ * Returns `false` for branches that do not match the canonical
+ * `story-<id>` shape — the merge-commit subject contract is only
+ * guaranteed for story branches.
+ *
+ * @param {object} ctx
+ * @param {string} branch Worktree branch (e.g. `story-1851`).
+ * @param {string} epicRef Epic branch ref (e.g. `epic/1831`).
+ * @returns {boolean}
+ */
+export function hasMergeCommitForStory(ctx, branch, epicRef) {
+  const storyId = parseStoryBranch(branch);
+  if (storyId === null) return false;
+  const grep = ctx.git.gitSpawn(
+    ctx.repoRoot,
+    'log',
+    epicRef,
+    '--merges',
+    '-n',
+    '1',
+    '--pretty=%H',
+    ...resolvesGrepArgs(storyId),
+  );
+  return grep.status === 0 && grep.stdout.trim().length > 0;
+}
+
+/**
+ * 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.
+ *
+ * @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`).
+ * @returns {boolean}
+ */
+export function hasRebasedEquivalents(ctx, branch, epicRef) {
+  const res = ctx.git.gitSpawn(ctx.repoRoot, 'cherry', epicRef, branch);
+  if (res.status !== 0) return false;
+  const lines = (res.stdout || '')
+    .split('\n')
+    .map((l) => l.trim())
+    .filter(Boolean);
+  if (lines.length === 0) return false;
+  return lines.every((line) => line.startsWith('- '));
+}
+
+/**
+ * Run the full three-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`).
+ * @returns {Promise<{safe: boolean, reason: string}>}
+ */
+export async function checkMergeReachability(ctx, wtPath, branch, epicRef) {
+  const head = resolveHeadSha(ctx, wtPath);
+  if (!head.ok) return { safe: false, reason: head.reason };
+
+  const ancestor = checkHeadAncestor(ctx, head.sha, epicRef);
+  if (ancestor.outcome === 'ancestor') {
+    return { safe: true, reason: 'head-reachable-from-epic' };
+  }
+  if (ancestor.outcome === 'error') {
+    return {
+      safe: false,
+      reason: `merge-check-failed: head=${head.short} epic=${epicRef}: ${ancestor.reason}`,
+    };
+  }
+
+  if (hasMergeCommitForStory(ctx, branch, epicRef)) {
+    return { safe: true, reason: 'merge-commit-reachable' };
+  }
+  if (hasRebasedEquivalents(ctx, branch, epicRef)) {
+    return { safe: true, reason: 'rebased-equivalents' };
+  }
+  return {
+    safe: false,
+    reason: `unmerged-commits: head=${head.short} epic=${epicRef}`,
+  };
+}