mandrel 2.65.0 → 2.67.0

package/.agents/scripts/boot-sweep.js

@@ -3,13 +3,18 @@
 
 /**
  * boot-sweep.js — non-interactive *protected* merged-branch sweep over
- * `sweepMergedBranches` (flags: see HELP). Unlike `git-cleanup --branches` it
+ * `sweepMergedBranches` (flags: see HELP). Unlike `clean-git --branches` it
  * always skips a branch with unpushed work, a dirty worktree or an open
  * parent Story. Best-effort: failures land in the envelope, exit is always 0.
  *
+ * After the branch sweep it runs the closed-Story worktree sweep
+ * (`sweepStaleStoryWorktrees`) under the same lock: `.worktrees/story-<id>`
+ * trees whose Story is closed or `agent::done` are removed; an open Story's
+ * tree and the tree this process runs from are never touched.
+ *
  * `content-merged` branches (merge-tree equivalence — no merge check ever
  * validated their exact diff) are never reaped here, only reported for
- * `/git-cleanup`.
+ * `/clean-git`.
  */
 
 import path from 'node:path';
@@ -18,9 +23,13 @@ import { parseArgs } from 'node:util';
 import { runAsCli } from './lib/cli-utils.js';
 import { PROJECT_ROOT, resolveConfig } from './lib/config-resolver.js';
 import { Logger } from './lib/Logger.js';
+import { sweepStaleStoryWorktrees } from './lib/orchestration/plan-runner/worktree-sweep.js';
 import { createProvider } from './lib/provider-factory.js';
 import { buildProtectionCtx } from './lib/single-story-sweep/protection-ctx.js';
-import { resolveSweepLockPath } from './lib/single-story-sweep/sweep-lock.js';
+import {
+  acquireSweepLock,
+  resolveSweepLockPath,
+} from './lib/single-story-sweep/sweep-lock.js';
 import { sweepMergedBranches } from './lib/single-story-sweep.js';
 import { sweepTempRetention } from './lib/temp-retention.js';
 
@@ -46,10 +55,13 @@ Runs the protected merged-branch boot sweep non-interactively: reaps every
 local branch whose PR is MERGED and whose HEAD matches the merged headRefOid,
 skipping any candidate the protection partition flags (unpushed work, dirty
 worktree, still-open parent Story), then fast-forwards the base branch.
+Then removes every .worktrees/story-<id> tree whose Story is closed or
+agent::done (never an open Story's, never the tree this process runs from);
+the outcome lands under "worktreeSweep".
 Branches detected only via the weaker content-equivalence signal
 (detectedBy: 'content-merged') are never reaped here — they are reported
 under "contentMerged" (and a routing hint in the summary line) for the
-operator to send to /git-cleanup.
+operator to send to /clean-git.
 
 Options:
   --include <glob>     Branch glob to sweep (repeatable). Default: story-*
@@ -60,6 +72,63 @@ Options:
   --json               Emit the result envelope as JSON.
 `;
 
+/**
+ * The closed-Story worktree sweep under the shared sweep lock; never throws.
+ * A contended lock skips it — the holder's next boot picks the trees up.
+ * Shared with `single-story-init.js`, whose boot never reaches
+ * {@link runBootSweep}: one sweep, one lock, two callers. `keepPaths` joins
+ * the sweep's running-tree guard — init passes the tree it is about to
+ * work in, so the Story being initialized is never removed.
+ *
+ * @param {{
+ *   root: string,
+ *   provider: object,
+ *   lockPath: string,
+ *   lockTimeoutMs: number,
+ *   sweepFn?: Function,
+ *   acquireLockFn?: Function,
+ *   logger: object,
+ *   logTag?: string,
+ *   keepPaths?: string[],
+ * }} args
+ * @returns {Promise<object>} `{ ok, reaped, skipped, reason?, error? }`.
+ */
+export async function runWorktreeSweep({
+  root,
+  provider,
+  lockPath,
+  lockTimeoutMs,
+  sweepFn = sweepStaleStoryWorktrees,
+  acquireLockFn = acquireSweepLock,
+  logger,
+  logTag = '[boot-sweep]',
+  keepPaths = [],
+}) {
+  const lock = acquireLockFn({ lockPath, timeoutMs: lockTimeoutMs });
+  if (!lock.acquired) {
+    return { ok: true, reason: `lock-${lock.reason}`, reaped: [], skipped: [] };
+  }
+  try {
+    const result = await sweepFn({
+      provider,
+      repoRoot: root,
+      runningPaths: keepPaths,
+      logger: {
+        info: (m) => logger.info?.(`${logTag} ${m}`),
+        warn: (m) => logger.warn?.(`${logTag} ${m}`),
+        error: (m) => logger.warn?.(`${logTag} ${m}`),
+      },
+    });
+    return { ok: true, ...result };
+  } catch (err) {
+    const msg = err?.message ?? String(err);
+    logger.warn?.(`${logTag} worktree sweep threw (host continues): ${msg}`);
+    return { ok: false, error: msg, reaped: [], skipped: [] };
+  } finally {
+    lock.release();
+  }
+}
+
 /**
  * Run the protected boot sweep; never throws.
  *
@@ -73,11 +142,13 @@ Options:
  *   injectedConfig?: object,
  *   injectedProvider?: object,
  *   injectedSweep?: Function,
+ *   worktreeSweepFn?: Function,
+ *   acquireLockFn?: Function,
  *   purgeFn?: Function,
  *   logger?: { info?: Function, warn?: Function },
  * }} [args]
  * @returns {Promise<object>} the {@link sweepMergedBranches} envelope plus
- *   `tempPurge`.
+ *   `worktreeSweep` and `tempPurge`.
  */
 export async function runBootSweep({
   cwd,
@@ -89,6 +160,8 @@ export async function runBootSweep({
   injectedConfig,
   injectedProvider,
   injectedSweep,
+  worktreeSweepFn = sweepStaleStoryWorktrees,
+  acquireLockFn = acquireSweepLock,
   purgeFn = sweepTempRetention,
   logger = Logger,
 } = {}) {
@@ -130,6 +203,16 @@ export async function runBootSweep({
       lockTimeoutMs,
     });
 
+    const worktreeSweep = await runWorktreeSweep({
+      root,
+      provider,
+      lockPath,
+      lockTimeoutMs,
+      sweepFn: worktreeSweepFn,
+      acquireLockFn,
+      logger,
+    });
+
     // Temp-retention catch-up: reaped branches are confirmed merges, so their
     // artifacts are spent; the age floor collects the rest.
     const purge = await purgeFn({
@@ -138,7 +221,7 @@ export async function runBootSweep({
       label: 'boot-sweep',
       logger,
     });
-    return { ...result, tempPurge: purge };
+    return { ...result, worktreeSweep, tempPurge: purge };
   } catch (err) {
     const msg = err?.message ?? String(err);
     logger.warn?.(`[boot-sweep] sweep threw (host continues): ${msg}`);
@@ -157,7 +240,7 @@ export async function runBootSweep({
 }
 
 /**
- * One-line summary; a nonzero `contentMerged` count adds a `/git-cleanup` hint.
+ * One-line summary; a nonzero `contentMerged` count adds a `/clean-git` hint.
  *
  * @param {{ localDeleted: number, remoteDeleted: number, protected?: Array, contentMerged?: Array }} result
  * @returns {string}
@@ -165,11 +248,16 @@ export async function runBootSweep({
 export function buildSummaryLine(result) {
   const protectedCount = result.protected?.length ?? 0;
   const contentMergedCount = result.contentMerged?.length ?? 0;
+  const worktreesReaped = result.worktreeSweep?.reaped?.length ?? 0;
+  const worktreeSuffix =
+    worktreesReaped > 0
+      ? `; removed ${worktreesReaped} closed-Story worktree(s)`
+      : '';
   const contentMergedSuffix =
     contentMergedCount > 0
-      ? `; ${contentMergedCount} content-merged branch(es) left for /git-cleanup`
+      ? `; ${contentMergedCount} content-merged branch(es) left for /clean-git`
       : '';
-  return `[boot-sweep] reaped ${result.localDeleted} local + ${result.remoteDeleted} remote; protected ${protectedCount}${contentMergedSuffix}.`;
+  return `[boot-sweep] reaped ${result.localDeleted} local + ${result.remoteDeleted} remote; protected ${protectedCount}${worktreeSuffix}${contentMergedSuffix}.`;
 }
 
 /**

package/.agents/scripts/bootstrap.js

@@ -716,6 +716,13 @@ async function detectCreation(answers, skipGithub) {
   return creation;
 }
 
+function projectNameFor(pn, projects) {
+  const match = projects.find((p) => p.value === pn);
+  if (!match) return '(unknown)';
+  const m = /^(.*)\s+\(#\d+\)$/.exec(match.label);
+  return m ? m[1] : match.label;
+}
+
 /**
  * `{ name, number }` for the summary; the picker stores only the number, so
  * an existing project's name is looked up.
@@ -723,20 +730,78 @@ async function detectCreation(answers, skipGithub) {
 function resolveProjectDisplay(answers, skipGithub, projectsList) {
   const pn = answers.projectNumber;
   if (!pn) return { name: '(skip)', number: '(skip)' };
-  if (/^\d+$/.test(pn)) {
-    let name = '(unknown)';
-    if (!skipGithub) {
-      const projects =
-        projectsList ?? safeList(() => listProjects({ owner: answers.owner }));
-      const match = projects.find((p) => p.value === pn);
-      if (match) {
-        const m = /^(.*)\s+\(#\d+\)$/.exec(match.label);
-        name = m ? m[1] : match.label;
-      }
+  if (!/^\d+$/.test(pn)) return { name: pn, number: '(new)' };
+  if (skipGithub) return { name: '(unknown)', number: pn };
+  const projects =
+    projectsList ?? safeList(() => listProjects({ owner: answers.owner }));
+  return { name: projectNameFor(pn, projects), number: pn };
+}
+
+/** Opt-ins default off; dry-run resolves them without prompting. */
+const OPT_INS = Object.freeze([
+  {
+    key: 'withProjectBoard',
+    flag: 'with-project-board',
+    prompt: 'Set up project board fields (Status, custom)?',
+  },
+  {
+    key: 'withIssueForms',
+    flag: 'with-issue-forms',
+    prompt: 'Generate GitHub Issue Form templates?',
+  },
+  {
+    key: 'withQuality',
+    flag: 'with-quality',
+    prompt:
+      'Install local quality gates (pre-commit hook + quality:preview/watch scripts)?',
+  },
+]);
+
+async function resolveOptIns(state) {
+  const optIns = {};
+  for (const { key, flag, prompt } of OPT_INS) {
+    let on = Boolean(state.flags[flag]);
+    if (!state.flags['dry-run'] && !on) {
+      on = await confirmYesNo(prompt, state.interactive, false);
     }
-    return { name, number: pn };
+    optIns[key] = on;
   }
-  return { name: pn, number: '(new)' };
+  return optIns;
+}
+
+async function approveCreation(state, creation) {
+  if (state.flags['dry-run'] || !(creation.newRepo || creation.newProject)) {
+    return true;
+  }
+  return confirmYesNo(
+    'Create the new GitHub repo/project listed above?',
+    state.interactive,
+  );
+}
+
+async function confirmSummary(state, answers, creation, projectsList) {
+  const skipGithub = Boolean(state.flags['skip-github']);
+  const project = resolveProjectDisplay(answers, skipGithub, projectsList);
+  Logger.info(
+    renderAnswerSummary(
+      answers,
+      creation,
+      project,
+      state.gitInitialized,
+      resolveRepoVisibility(state.flags),
+    ),
+  );
+  return confirmYesNo('Is this correct?', state.interactive);
+}
+
+/** Owner repo/project lists, fetched once for pickers and summary. */
+function fetchPickerLists(state, skipGithub) {
+  const owner = resolveOwnerForPicker(state.defaults, state.flags);
+  if (skipGithub || !owner) return { reposList: [], projectsList: [] };
+  return {
+    reposList: safeList(() => listRepos({ owner }).map(bareRepoName)),
+    projectsList: safeList(() => listProjects({ owner })),
+  };
 }
 
 /**
@@ -745,22 +810,16 @@ function resolveProjectDisplay(answers, skipGithub, projectsList) {
  */
 export async function collectAndConfirm(state) {
   const skipGithub = Boolean(state.flags['skip-github']);
-  const owner = resolveOwnerForPicker(state.defaults, state.flags);
-  // Fetched once for pickers and summary, so the name never needs a second call.
-  const reposList =
-    !skipGithub && owner
-      ? safeList(() => listRepos({ owner }).map(bareRepoName))
-      : [];
-  const projectsList =
-    !skipGithub && owner ? safeList(() => listProjects({ owner })) : [];
-
+  const lists = fetchPickerLists(state, skipGithub);
   let silentAccept = state.silentAccept;
   for (;;) {
     const { answers, missing } = await collectAnswers({
-      questions: buildQuestions(state.defaults, state.flags, process.env, {
-        reposList,
-        projectsList,
-      }),
+      questions: buildQuestions(
+        state.defaults,
+        state.flags,
+        process.env,
+        lists,
+      ),
       flags: state.flags,
       interactive: state.interactive,
       assumeYes: state.assumeYes,
@@ -775,78 +834,24 @@ export async function collectAndConfirm(state) {
       );
       return { ok: false, exit: 1 };
     }
-    if (!answers.operatorHandle) answers.operatorHandle = answers.owner;
-    answers.operatorHandle = normalizeHandleAnswer(answers.operatorHandle);
+    answers.operatorHandle = normalizeHandleAnswer(
+      answers.operatorHandle || answers.owner,
+    );
 
     const creation = await detectCreation(answers, skipGithub);
-    const project = resolveProjectDisplay(answers, skipGithub, projectsList);
-    Logger.info(
-      renderAnswerSummary(
-        answers,
-        creation,
-        project,
-        state.gitInitialized,
-        resolveRepoVisibility(state.flags),
-      ),
-    );
-    const correct = await confirmYesNo('Is this correct?', state.interactive);
-    if (!correct) {
+    if (!(await confirmSummary(state, answers, creation, lists.projectsList))) {
       Logger.info('[Bootstrap] Okay — let’s try again.');
       silentAccept = [];
       continue;
     }
-
-    if (!state.flags['dry-run'] && (creation.newRepo || creation.newProject)) {
-      const approved = await confirmYesNo(
-        'Create the new GitHub repo/project listed above?',
-        state.interactive,
-      );
-      if (!approved) {
-        Logger.error(
-          '[Bootstrap] Creation declined — cannot continue without the repo/project. Exiting.',
-        );
-        return { ok: false, exit: 1 };
-      }
-    }
-
-    // Opt-ins default off; dry-run resolves them without prompting.
-    let withProjectBoard = Boolean(state.flags['with-project-board']);
-    if (!state.flags['dry-run'] && !withProjectBoard) {
-      withProjectBoard = await confirmYesNo(
-        'Set up project board fields (Status, custom)?',
-        state.interactive,
-        false,
-      );
-    }
-
-    let withIssueForms = Boolean(state.flags['with-issue-forms']);
-    if (!state.flags['dry-run'] && !withIssueForms) {
-      withIssueForms = await confirmYesNo(
-        'Generate GitHub Issue Form templates?',
-        state.interactive,
-        false,
-      );
-    }
-
-    let withQuality = Boolean(state.flags['with-quality']);
-    if (!state.flags['dry-run'] && !withQuality) {
-      withQuality = await confirmYesNo(
-        'Install local quality gates (pre-commit hook + quality:preview/watch scripts)?',
-        state.interactive,
-        false,
+    if (!(await approveCreation(state, creation))) {
+      Logger.error(
+        '[Bootstrap] Creation declined — cannot continue without the repo/project. Exiting.',
       );
+      return { ok: false, exit: 1 };
     }
-
-    return {
-      ok: true,
-      payload: {
-        answers,
-        creation,
-        withProjectBoard,
-        withIssueForms,
-        withQuality,
-      },
-    };
+    const optIns = await resolveOptIns(state);
+    return { ok: true, payload: { answers, creation, ...optIns } };
   }
 }
 

package/.agents/scripts/{git-cleanup.js → clean-git.js}

@@ -100,10 +100,10 @@ async function main() {
 }
 
 runAsCli(import.meta.url, main, {
-  source: 'git-cleanup',
+  source: 'clean-git',
   usage: {
     invocation:
-      'node .agents/scripts/git-cleanup.js [--execute] [--yes] [--json] [phase flags] [filters]',
+      'node .agents/scripts/clean-git.js [--execute] [--yes] [--json] [phase flags] [filters]',
     summary:
       'Tidy the local checkout in four phases — fast-forward the base branch, prune stale remote refs, reap merged branches, triage stashes. Dry-run unless --execute.',
     flags: [

package/.agents/scripts/clean-temp.js

@@ -0,0 +1,54 @@
+#!/usr/bin/env node
+/* node:coverage ignore file -- thin CLI shell; the engine is lib/clean-temp.js */
+
+/**
+ * `/clean-temp` — preview (default) or delete spent entries under the
+ * project's tempRoot. Thin shell over `lib/clean-temp.js`.
+ *
+ * Exit codes: 0 clean or dry-run, 1 refused (tempRoot outside the project
+ * root) or a deletion failed.
+ */
+
+import { runCleanTemp } from './lib/clean-temp.js';
+import { runAsCli } from './lib/cli-utils.js';
+import { resolveConfig } from './lib/config-resolver.js';
+import { promptYesNo } from './lib/orchestration/git-cleanup/phases/prompts.js';
+import { createProvider } from './lib/provider-factory.js';
+
+/* node:coverage ignore next */
+async function main() {
+  const { exitCode } = await runCleanTemp({
+    argv: process.argv.slice(2),
+    cwd: process.cwd(),
+    loadConfig: (projectRoot) => resolveConfig({ cwd: projectRoot }),
+    getProvider: createProvider,
+    confirm: promptYesNo,
+    write: (text) => process.stdout.write(text),
+    writeErr: (text) => process.stderr.write(text),
+  });
+  return exitCode;
+}
+
+runAsCli(import.meta.url, main, {
+  source: 'clean-temp',
+  propagateExitCode: true,
+  usage: {
+    invocation:
+      'node .agents/scripts/clean-temp.js [--execute] [--yes] [--json] [--cwd <path>]',
+    summary:
+      "Sort every top-level entry under the project's tempRoot into framework / closed-issue / aged / kept buckets. Dry-run unless --execute.",
+    flags: [
+      ['--execute', 'Delete the confirmed buckets (default is a dry run).'],
+      [
+        '--yes',
+        'Skip the per-bucket prompts; deletes framework and closed-issue only — aged is never deleted unattended.',
+      ],
+      ['--json', 'Emit the result envelope as JSON.'],
+      ['--cwd <path>', 'Project directory (default: process cwd).'],
+    ],
+    notes: [
+      'Refuses (exit 1) when the resolved tempRoot is not inside the project root.',
+      'qa/, cache/, *.lock and signals.ndjson (at any depth) are never deleted.',
+    ],
+  },
+});