mandrel 2.66.0 → 2.67.0

package/.agents/scripts/lib/observability/source-classifier.js

@@ -37,6 +37,8 @@ const FRAMEWORK_SCRIPT_BASENAMES = Object.freeze([
   'check-test-temp-hygiene.js',
   'check-windows-git-perf.js',
   'ceremony-derive.js',
+  'clean-temp.js',
+  'clean-worktrees.js',
   'cleanup-repo-test-temp.js',
   'coverage-capture.js',
   'deliver-light.js',
@@ -51,7 +53,7 @@ const FRAMEWORK_SCRIPT_BASENAMES = Object.freeze([
   'generate-lens-checklists.js',
   'generate-skills-index.js',
   'generate-workflows-doc.js',
-  'git-cleanup.js',
+  'clean-git.js',
   'lint-issue-body.js',
   'mandrel-update-preflight.js',
   'merge-baseline.js',

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

@@ -1,5 +1,5 @@
 /**
- * git-cleanup `main()`: argv, base-branch resolution, the four phases, and
+ * `clean-git.js` `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/plan-runner/worktree-sweep.js

@@ -1,11 +1,17 @@
 /**
- * plan-runner/worktree-sweep.js — plan-boot sweep that force-removes
+ * plan-runner/worktree-sweep.js — boot sweep that removes
  * `.worktrees/story-<id>/` entries whose Story is closed or `agent::done`,
- * after draining the pending-cleanup manifest.
+ * after draining the pending-cleanup manifest. Called by `runBootSweep`
+ * (`boot-sweep.js`) under the shared merged-branch sweep lock.
  *
- * `--force` is deliberate: a done Story's branch is already merged, so any
- * residue (dirty artifacts, an interrupted rebase, a Windows lock) is noise;
- * the `WorktreeManager.reap` safety rails are for the active close path.
+ * Removal goes through `removeWorktreeWithRecovery` — the same seam close
+ * uses: Windows lock retries, an `fs.rm` fallback that discards residue a
+ * done Story's merged branch no longer needs, and the pending-cleanup
+ * hand-off when that exhausts. Branches are never deleted here; the
+ * merged-branch sweep owns them.
+ *
+ * Two trees are never touched: an open Story's, and the one the running
+ * process was loaded from or is working in (`findRunningCodeInside`).
  */
 
 import path from 'node:path';
@@ -13,8 +19,13 @@ import * as defaultGit from '../../git-utils.js';
 import { NOOP_LOGGER } from '../../Logger.js';
 import { AGENT_LABELS } from '../../label-constants.js';
 import { concurrentMap } from '../../util/concurrent-map.js';
-import { parseWorktreePorcelain } from '../../worktree/inspector.js';
+import { canonicalPath } from '../../worktree/canonical-path.js';
+import { parseWorktreePorcelain, samePath } from '../../worktree/inspector.js';
 import { forceDrainPendingCleanup } from '../../worktree/lifecycle/force-drain.js';
+import {
+  findRunningCodeInside,
+  removeWorktreeWithRecovery,
+} from '../../worktree/lifecycle/reap.js';
 
 const TICKET_READ_CONCURRENCY = 8;
 
@@ -27,33 +38,32 @@ function isStoryDone(ticket) {
   return labels.includes(DONE_LABEL);
 }
 
-function storyIdFromPath(wtPath) {
-  const parts = wtPath.replace(/\\/g, '/').split('/');
-  const last = parts[parts.length - 1] ?? '';
-  return defaultGit.parseStoryBranch(last);
+/**
+ * The Story id of a `<worktreeRoot>/story-<id>` entry, else `null` — a
+ * `story-<id>` directory anywhere else (e.g. `.claude/worktrees/`) is not
+ * this sweep's to judge.
+ *
+ * @param {string} wtPath
+ * @param {string} worktreeRoot
+ * @param {string} platform
+ * @returns {number|null}
+ */
+function storyIdFromPath(wtPath, worktreeRoot, platform) {
+  const parent = path.dirname(canonicalPath(wtPath));
+  if (!samePath(parent, canonicalPath(worktreeRoot), platform)) return null;
+  return defaultGit.parseStoryBranch(path.basename(path.resolve(wtPath)));
 }
 
 /**
- * Never touches a worktree whose Story is still open.
+ * Validate and normalise the options bag.
  *
  * @param {object} opts
- * @param {object} opts.provider    Only `getTicket(id)` is required.
- * @param {string} opts.repoRoot    Absolute path to the main checkout.
- * @param {object} [opts.git]
- * @param {object} [opts.logger]
- * @returns {Promise<{
- *   reaped: Array<{ storyId: number, path: string }>,
- *   skipped: Array<{ storyId: number|null, path: string, reason: string }>,
- * }>}
+ * @returns {object}
  */
-export async function sweepStaleStoryWorktrees(opts = {}) {
+function resolveSweepOptions(opts) {
   const ctx = opts.ctx;
   const provider = opts.provider ?? ctx?.provider;
   const repoRoot = opts.repoRoot ?? ctx?.cwd;
-  const git = opts.git ?? defaultGit;
-  const logger = opts.logger ?? ctx?.logger ?? NOOP_LOGGER;
-  const fsRm = opts.fsRm;
-  const worktreeRoot = opts.worktreeRoot;
   if (!provider || typeof provider.getTicket !== 'function') {
     throw new Error(
       'sweepStaleStoryWorktrees: provider with getTicket(id) is required',
@@ -62,107 +72,149 @@ export async function sweepStaleStoryWorktrees(opts = {}) {
   if (!repoRoot || typeof repoRoot !== 'string') {
     throw new Error('sweepStaleStoryWorktrees: repoRoot is required');
   }
+  const platform = opts.platform ?? process.platform;
+  return {
+    provider,
+    repoRoot,
+    platform,
+    git: opts.git ?? defaultGit,
+    logger: opts.logger ?? ctx?.logger ?? NOOP_LOGGER,
+    fsRm: opts.fsRm,
+    sleepFn: opts.sleepFn,
+    worktreeRoot: path.resolve(
+      opts.worktreeRoot ?? path.join(repoRoot, '.worktrees'),
+    ),
+    guardPaths: [process.cwd(), ...(opts.runningPaths ?? [])],
+  };
+}
 
-  const resolvedWorktreeRoot =
-    worktreeRoot ?? path.join(repoRoot, '.worktrees');
+/**
+ * Read every Story worktree's ticket; each mapper captures its own error so
+ * one provider hiccup cannot abort the sweep via concurrentMap's
+ * first-rejection-wins policy.
+ */
+function readStoryTickets(entries, o) {
+  return concurrentMap(
+    entries,
+    async (entry) => {
+      const wtPath = entry.path;
+      const storyId = wtPath
+        ? storyIdFromPath(wtPath, o.worktreeRoot, o.platform)
+        : null;
+      if (storyId === null) return { kind: 'non-story' };
+      try {
+        const ticket = await o.provider.getTicket(storyId);
+        return { kind: 'ok', wtPath, storyId, ticket };
+      } catch (err) {
+        return { kind: 'provider-error', wtPath, storyId, error: err };
+      }
+    },
+    { concurrency: TICKET_READ_CONCURRENCY },
+  );
+}
+
+/**
+ * Why a read entry must be kept, or `null` when it may be removed.
+ *
+ * @returns {string|null}
+ */
+function keepReason(r, o) {
+  if (r.kind === 'provider-error') {
+    o.logger.warn(
+      `worktree-sweep: provider.getTicket(#${r.storyId}) failed: ${r.error.message}`,
+    );
+    return `provider-error: ${r.error.message}`;
+  }
+  if (!isStoryDone(r.ticket)) return 'story-open';
+  const selfPath = findRunningCodeInside(o, r.wtPath, o.guardPaths);
+  if (selfPath) {
+    o.logger.warn(
+      `worktree-sweep: skipped storyId=${r.storyId} path=${r.wtPath} — the running process uses it (${selfPath})`,
+    );
+    return 'running-from-target-tree';
+  }
+  return null;
+}
+
+async function removeOne(r, o) {
+  const ctx = {
+    repoRoot: o.repoRoot,
+    git: o.git,
+    logger: o.logger,
+    platform: o.platform,
+    worktreeRoot: o.worktreeRoot,
+    listCache: { list: null, ts: 0 },
+    fsRm: o.fsRm,
+  };
+  const res = await removeWorktreeWithRecovery(ctx, r.wtPath, {
+    storyId: r.storyId,
+    ...(o.sleepFn ? { sleepFn: o.sleepFn, retryDelay: 0 } : {}),
+  });
+  return res.removed
+    ? null
+    : `remove-failed: ${res.reason ?? 'worktree-remove-failed'}`;
+}
+
+/**
+ * Never touches a worktree whose Story is still open, nor the one the
+ * running process uses.
+ *
+ * @param {object} opts
+ * @param {object} opts.provider    Only `getTicket(id)` is required.
+ * @param {string} opts.repoRoot    Absolute path to the main checkout.
+ * @param {object} [opts.git]
+ * @param {object} [opts.logger]
+ * @param {string[]} [opts.runningPaths] Extra paths the running process owns.
+ * @returns {Promise<{
+ *   reaped: Array<{ storyId: number, path: string }>,
+ *   skipped: Array<{ storyId: number|null, path: string, reason: string }>,
+ * }>}
+ */
+export async function sweepStaleStoryWorktrees(opts = {}) {
+  const o = resolveSweepOptions(opts);
 
   // Drain the pending-cleanup manifest first so entries whose Windows locks
   // have released self-heal instead of accumulating.
   const drainResult = await forceDrainPendingCleanup({
-    repoRoot,
-    worktreeRoot: resolvedWorktreeRoot,
-    git,
-    fsRm,
-    logger,
+    repoRoot: o.repoRoot,
+    worktreeRoot: o.worktreeRoot,
+    git: o.git,
+    fsRm: o.fsRm,
+    logger: o.logger,
   });
 
   const reaped = [];
   const skipped = [];
 
-  const listRes = git.gitSpawn(repoRoot, 'worktree', 'list', '--porcelain');
+  const listRes = o.git.gitSpawn(o.repoRoot, 'worktree', 'list', '--porcelain');
   if (listRes.status !== 0) {
-    logger.warn(
+    o.logger.warn(
       `worktree-sweep: git worktree list failed: ${listRes.stderr || listRes.stdout || 'unknown'}`,
     );
     return { reaped, skipped };
   }
 
-  const entries = parseWorktreePorcelain(listRes.stdout || '');
-
-  // Each mapper captures its own error so one provider hiccup cannot abort
-  // the sweep via concurrentMap's first-rejection-wins policy.
-  const reads = await concurrentMap(
-    entries,
-    async (entry) => {
-      const wtPath = entry.path;
-      if (!wtPath) return { kind: 'no-path' };
-      const storyId = storyIdFromPath(wtPath);
-      if (storyId === null) return { kind: 'non-story' };
-      try {
-        const ticket = await provider.getTicket(storyId);
-        return { kind: 'ok', wtPath, storyId, ticket };
-      } catch (err) {
-        return { kind: 'provider-error', wtPath, storyId, error: err };
-      }
-    },
-    { concurrency: TICKET_READ_CONCURRENCY },
+  const reads = await readStoryTickets(
+    parseWorktreePorcelain(listRes.stdout || ''),
+    o,
   );
 
   // Removes stay sequential: they mutate .git/worktrees/, and racing git's
   // locking on Windows can leave a partial admin dir the next remove trips on.
   for (const r of reads) {
-    if (r.kind === 'no-path' || r.kind === 'non-story') continue;
-    if (r.kind === 'provider-error') {
-      skipped.push({
-        storyId: r.storyId,
-        path: r.wtPath,
-        reason: `provider-error: ${r.error.message}`,
-      });
-      logger.warn(
-        `worktree-sweep: provider.getTicket(#${r.storyId}) failed: ${r.error.message}`,
-      );
-      continue;
-    }
-
-    if (!isStoryDone(r.ticket)) {
-      skipped.push({
-        storyId: r.storyId,
-        path: r.wtPath,
-        reason: 'story-open',
-      });
-      continue;
-    }
-
-    const res = git.gitSpawn(
-      repoRoot,
-      'worktree',
-      'remove',
-      '--force',
-      r.wtPath,
-    );
-    if (res.status !== 0) {
-      const reason = (
-        res.stderr ||
-        res.stdout ||
-        'worktree-remove-failed'
-      ).trim();
-      skipped.push({
-        storyId: r.storyId,
-        path: r.wtPath,
-        reason: `remove-failed: ${reason}`,
-      });
-      logger.warn(
-        `worktree-sweep: failed to reap storyId=${r.storyId} path=${r.wtPath}: ${reason}`,
-      );
+    if (r.kind === 'non-story') continue;
+    const reason = keepReason(r, o) ?? (await removeOne(r, o));
+    if (reason) {
+      skipped.push({ storyId: r.storyId, path: r.wtPath, reason });
       continue;
     }
     reaped.push({ storyId: r.storyId, path: r.wtPath });
-    logger.info(
+    o.logger.info(
       `worktree-sweep: reaped stale worktree storyId=${r.storyId} path=${r.wtPath}`,
     );
   }
 
-  git.gitSpawn(repoRoot, 'worktree', 'prune');
+  o.git.gitSpawn(o.repoRoot, 'worktree', 'prune');
 
   return {
     reaped,

package/.agents/scripts/lib/single-story-sweep.js

@@ -11,7 +11,7 @@ import {
   executeFastForward as defaultExecuteFastForward,
   planCleanup as defaultPlanCleanup,
   planFastForward as defaultPlanFastForward,
-} from '../git-cleanup.js';
+} from '../clean-git.js';
 import { evaluateProtection as defaultEvaluateProtection } from './single-story-sweep/protection.js';
 import { acquireSweepLock as defaultAcquireSweepLock } from './single-story-sweep/sweep-lock.js';
 
@@ -175,7 +175,7 @@ export function sweepMergedStoryBranches(args = {}) {
 
 /**
  * Content-merged candidates are report-only: content equivalence is weaker
- * than a merged PR or ancestry, so only an operator-confirmed `/git-cleanup`
+ * than a merged PR or ancestry, so only an operator-confirmed `/clean-git`
  * may reap them.
  */
 function partitionContentMerged(candidates) {

package/.agents/scripts/lib/temp-removal.js

@@ -0,0 +1,110 @@
+/**
+ * Filesystem primitives for the temp-retention engine: sizing a tree and
+ * deleting one while sparing the never-purged basenames at any depth.
+ */
+
+import path from 'node:path';
+
+/**
+ * Never deleted, re-checked at the deletion site: `signals.ndjson` is read
+ * long after merge and its loss is silent and unrecoverable.
+ */
+export const KEEP_BASENAMES = Object.freeze(['signals.ndjson']);
+
+/**
+ * `readdir` yielding `[]` for an absent or unreadable directory.
+ *
+ * @param {typeof import('node:fs/promises')} fsp
+ * @param {string} dir
+ * @returns {Promise<import('node:fs').Dirent[]>}
+ */
+export async function safeReaddir(fsp, dir) {
+  try {
+    return await fsp.readdir(dir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Recursive byte total; a vanished child is skipped.
+ *
+ * @param {typeof import('node:fs/promises')} fsp
+ * @param {string} target
+ * @returns {Promise<number>}
+ */
+export async function sizeOf(fsp, target) {
+  let total = 0;
+  const stack = [target];
+  while (stack.length > 0) {
+    const current = stack.pop();
+    let stats;
+    try {
+      stats = await fsp.stat(current);
+    } catch {
+      continue;
+    }
+    if (!stats.isDirectory()) {
+      total += stats.size;
+      continue;
+    }
+    for (const child of await safeReaddir(fsp, current)) {
+      stack.push(path.join(current, child.name));
+    }
+  }
+  return total;
+}
+
+/**
+ * Paths of every never-purged basename at any depth under `target`.
+ *
+ * @param {typeof import('node:fs/promises')} fsp
+ * @param {string} target
+ * @returns {Promise<string[]>}
+ */
+async function findKeptDescendants(fsp, target) {
+  const kept = [];
+  const stack = [target];
+  while (stack.length > 0) {
+    const current = stack.pop();
+    for (const child of await safeReaddir(fsp, current)) {
+      const childPath = path.join(current, child.name);
+      if (child.isDirectory()) stack.push(childPath);
+      else if (KEEP_BASENAMES.includes(child.name)) kept.push(childPath);
+    }
+  }
+  return kept;
+}
+
+/**
+ * Delete `target` while sparing every never-purged basename beneath it: a
+ * tree holding none goes in one `rm`; otherwise its children are removed
+ * one by one and the kept files (with their parent dirs) stay.
+ *
+ * @param {typeof import('node:fs/promises')} fsp
+ * @param {string} target
+ * @param {number} [knownBytes] Pre-computed size, spared a second walk.
+ * @returns {Promise<{ bytes: number, kept: string[] }>}
+ */
+export async function removeSparingKept(fsp, target, knownBytes) {
+  const stats = await fsp.stat(target);
+  if (!stats.isDirectory()) {
+    if (KEEP_BASENAMES.includes(path.basename(target))) {
+      return { bytes: 0, kept: [target] };
+    }
+    await fsp.rm(target, { force: true });
+    return { bytes: stats.size, kept: [] };
+  }
+  const kept = await findKeptDescendants(fsp, target);
+  if (kept.length === 0) {
+    const bytes = knownBytes ?? (await sizeOf(fsp, target));
+    await fsp.rm(target, { recursive: true, force: true });
+    return { bytes, kept };
+  }
+  let bytes = 0;
+  for (const child of await safeReaddir(fsp, target)) {
+    bytes += (await removeSparingKept(fsp, path.join(target, child.name)))
+      .bytes;
+  }
+  return { bytes, kept };
+}