mandrel 1.57.0

package/.agents/scripts/lib/orchestration/post-merge/phases/worktree-reap.js

@@ -0,0 +1,396 @@
+/**
+ * phases/worktree-reap.js — post-merge worktree reap phase.
+ *
+ * After a Story branch is merged into the Epic branch, this phase removes
+ * the per-Story worktree at `.worktrees/story-<id>/`. The reap is split
+ * into three concerns:
+ *
+ *   1. `worktreeReapPhase` — the phase entry point. Honors the
+ *      `worktreeIsolation.{enabled,reapOnSuccess}` config, delegates the
+ *      actual remove to `WorktreeManager.reap`, then runs a re-prune
+ *      retry loop to clear stale `.git/worktrees/<name>/` registry
+ *      entries that Windows file-locks occasionally leave behind.
+ *   2. `applyStillRegisteredState` — classifies a still-registered entry
+ *      after retries as either `stale-registry-entry` (operationally
+ *      complete; schedule pending-cleanup drain) or `still-registered`
+ *      (genuine failure; OPERATOR ACTION REQUIRED).
+ *   3. Friction-signal emission via `signals-writer` so retrospectives
+ *      surface lock failures and stale-registry escalations.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { setTimeout as sleepPromise } from 'node:timers/promises';
+import { getStoryBranch } from '../../../git-utils.js';
+import { appendSignal } from '../../../observability/signals-writer.js';
+import { recordPendingCleanup } from '../../../worktree/lifecycle/pending-cleanup.js';
+import { WorktreeManager } from '../../../worktree-manager.js';
+
+const WINDOWS_LOCK_RE =
+  /(permission denied|access is denied|directory not empty|resource busy|device or resource busy|sharing violation|EACCES|EBUSY|ENOTEMPTY)/i;
+
+/**
+ * Backoff delays (ms) between `git worktree prune` + re-list passes when a
+ * worktree entry is still registered after a successful reap. On Windows the
+ * registry-cleanup half of `git worktree remove` often loses a race with a
+ * background file handle (Defender / Search indexer / the editor) — the
+ * directory and branch are gone, but `.git/worktrees/<name>/` is locked
+ * for a beat. Three retries (250ms, 1s, 4s) cover the common case without
+ * adding noticeable latency to clean POSIX runs.
+ */
+const STALE_REGISTRY_REPRUNE_DELAYS_MS = [250, 1000, 4000];
+
+function isWindowsReapLockFailure(reason) {
+  return typeof reason === 'string' && WINDOWS_LOCK_RE.test(reason);
+}
+
+function findStillRegisteredEntry(entries, storyId) {
+  if (!Array.isArray(entries)) return undefined;
+  const want = Number(storyId);
+  return entries.find((r) => {
+    if (!r || typeof r.path !== 'string') return false;
+    const match = r.path.match(/[/\\]story-(\d+)$/);
+    return match ? Number(match[1]) === want : false;
+  });
+}
+
+function resolveWorktreeRoot(repoRoot, orchestration) {
+  if (!repoRoot) return null;
+  const configuredRoot = orchestration?.worktreeIsolation?.root ?? '.worktrees';
+  return path.join(repoRoot, configuredRoot);
+}
+
+async function retryPruneUntilCleared(
+  wm,
+  storyId,
+  { sleep, delays = STALE_REGISTRY_REPRUNE_DELAYS_MS } = {},
+) {
+  const sleepFn = typeof sleep === 'function' ? sleep : sleepPromise;
+  let attempts = 0;
+  let lastEntry;
+  for (const delay of delays) {
+    await sleepFn(delay);
+    attempts += 1;
+    if (typeof wm.prune === 'function') {
+      try {
+        await wm.prune();
+      } catch {
+        // best-effort — prune failure is non-fatal; fall through to list check
+      }
+    }
+    const refreshed = (await wm.list()) ?? [];
+    lastEntry = findStillRegisteredEntry(refreshed, storyId);
+    if (!lastEntry) return { cleared: true, attempts };
+  }
+  return { cleared: false, attempts, stillRegistered: lastEntry };
+}
+
+function reapPhaseLogger(progress) {
+  return progress ?? (() => {});
+}
+
+export function createWorktreeReapState(overrides = {}) {
+  return {
+    status: 'not-run',
+    path: null,
+    reason: null,
+    method: null,
+    pendingCleanup: null,
+    branchDeleted: null,
+    remoteBranchDeleted: null,
+    ...overrides,
+  };
+}
+
+async function emitReapFailureFriction({
+  storyId,
+  epicId,
+  reapResult,
+  epicBranch,
+  logger,
+  config,
+}) {
+  if (!epicId || !storyId) return;
+  const reason = String(reapResult?.reason ?? 'unknown');
+  const wtPath = reapResult?.path ?? '(unknown path)';
+  try {
+    await appendSignal({
+      epicId: Number(epicId),
+      storyId: Number(storyId),
+      signal: {
+        kind: 'friction',
+        timestamp: new Date().toISOString(),
+        epicId: Number(epicId),
+        storyId: Number(storyId),
+        category: 'reap-failure',
+        source: { tool: 'story-close.js' },
+        details: `Worktree reap failed: ${reason}`,
+        epicBranch,
+        worktreePath: wtPath,
+        reason,
+      },
+      config,
+    });
+  } catch (err) {
+    logger?.warn?.(
+      `[post-merge-pipeline] friction signal append failed: ${err?.message ?? err}`,
+    );
+  }
+}
+
+function resolveSkipState(wtConfig, log) {
+  if (!wtConfig?.enabled) {
+    log('WORKTREE', '⏭️ Skipping worktree reap (worktree isolation disabled)');
+    return createWorktreeReapState({ status: 'skipped-disabled' });
+  }
+  if (!(wtConfig.reapOnSuccess ?? true)) {
+    log('WORKTREE', '⏭️ Skipping worktree reap (reapOnSuccess=false)');
+    return createWorktreeReapState({ status: 'skipped-config' });
+  }
+  return null;
+}
+
+function resolveInitialReapStatus(reapResult) {
+  if (reapResult.removed) return 'removed';
+  if (reapResult.method === 'deferred-to-sweep') return 'deferred-to-sweep';
+  return 'failed';
+}
+
+function initialReapState(reapResult) {
+  return createWorktreeReapState({
+    status: resolveInitialReapStatus(reapResult),
+    path: reapResult.path ?? null,
+    reason: reapResult.reason ?? null,
+    method: reapResult.method ?? null,
+    pendingCleanup: reapResult.pendingCleanup ?? null,
+    branchDeleted:
+      reapResult.branchDeleted !== undefined ? reapResult.branchDeleted : null,
+    remoteBranchDeleted:
+      reapResult.remoteBranchDeleted !== undefined
+        ? reapResult.remoteBranchDeleted
+        : null,
+  });
+}
+
+async function logReapOutcome({
+  reapResult,
+  log,
+  logger,
+  storyId,
+  epicId,
+  epicBranch,
+  config,
+}) {
+  if (reapResult.removed) {
+    log('WORKTREE', `🗑️  Reaped worktree: ${reapResult.path}`);
+    return;
+  }
+  if (!reapResult.reason) return;
+  await emitReapFailureFriction({
+    storyId,
+    epicId,
+    reapResult,
+    epicBranch,
+    logger,
+    config,
+  });
+  log(
+    'WORKTREE',
+    `⚠️  Worktree not reaped (${reapResult.reason}): ${reapResult.path}`,
+  );
+  if (isWindowsReapLockFailure(reapResult.reason)) {
+    logger.error(
+      `[story-close] OPERATOR ACTION REQUIRED: Worktree at ${reapResult.path} ` +
+        `could not be removed (Windows lock/permission error: ${reapResult.reason}). ` +
+        'Close any editor/terminal holding the path, then run ' +
+        '`git worktree remove <path> --force && git worktree prune` to clean up.',
+    );
+  }
+}
+
+async function detectStillRegistered({ wm, storyId, log, sleep }) {
+  const leftover = (await wm.list()) ?? [];
+  const initial = findStillRegisteredEntry(leftover, storyId);
+  if (!initial) return null;
+  const retry = await retryPruneUntilCleared(wm, storyId, { sleep });
+  if (retry.cleared) {
+    log(
+      'WORKTREE',
+      `🧹 Stale worktree registry entry cleared after ${retry.attempts} re-prune attempt(s)`,
+    );
+    return null;
+  }
+  return retry.stillRegistered ?? initial;
+}
+
+async function escalateStillRegistered({
+  state,
+  stillRegistered,
+  storyId,
+  epicId,
+  epicBranch,
+  logger,
+  config,
+}) {
+  logger.error(
+    `[story-close] OPERATOR ACTION REQUIRED: Worktree still registered after reap: ` +
+      `${stillRegistered.path}. Run ` +
+      '`git worktree remove <path> --force && git worktree prune` to clean up.',
+  );
+  await emitReapFailureFriction({
+    storyId,
+    epicId,
+    reapResult: {
+      path: stillRegistered.path,
+      reason: 'still-registered-after-reap',
+    },
+    epicBranch,
+    logger,
+    config,
+  });
+  return state;
+}
+
+function logStaleRegistryEntry({ state, stillRegistered, logger }) {
+  logger.warn(
+    `[story-close] Worktree directory removed and branch deleted, but ` +
+      `\`git worktree list\` still shows ${stillRegistered.path}. ` +
+      'Scheduled for background prune via pending-cleanup; ' +
+      `branchDeleted=${state.branchDeleted}.`,
+  );
+  return state;
+}
+
+export async function worktreeReapPhase(ctx) {
+  const {
+    orchestration,
+    storyId,
+    epicId,
+    epicBranch,
+    repoRoot,
+    progress,
+    logger,
+    worktreeManagerFactory,
+    config,
+    sleep,
+    recordPendingCleanupFn = recordPendingCleanup,
+    pathExistsFn = fs.existsSync,
+  } = ctx;
+  const wtConfig = orchestration?.worktreeIsolation;
+  const log = reapPhaseLogger(progress);
+  const skipState = resolveSkipState(wtConfig, log);
+  if (skipState) return skipState;
+
+  const wm = worktreeManagerFactory
+    ? worktreeManagerFactory({ repoRoot, config: wtConfig })
+    : new WorktreeManager({ repoRoot, config: wtConfig });
+  const reapResult = await wm.reap(storyId, { epicBranch });
+  let state = initialReapState(reapResult);
+  await logReapOutcome({
+    reapResult,
+    log,
+    logger,
+    storyId,
+    epicId,
+    epicBranch,
+    config,
+  });
+
+  const stillRegistered = await detectStillRegistered({
+    wm,
+    storyId,
+    log,
+    sleep,
+  });
+  if (!stillRegistered) return state;
+
+  state = applyStillRegisteredState({
+    state,
+    stillRegistered,
+    reapResult,
+    storyId,
+    orchestration,
+    repoRoot,
+    logger,
+    recordPendingCleanupFn,
+    pathExistsFn,
+  });
+  if (state.status === 'still-registered') {
+    return escalateStillRegistered({
+      state,
+      stillRegistered,
+      storyId,
+      epicId,
+      epicBranch,
+      logger,
+      config,
+    });
+  }
+  if (state.status === 'stale-registry-entry') {
+    return logStaleRegistryEntry({ state, stillRegistered, logger });
+  }
+  return state;
+}
+
+/**
+ * Decide how to treat a worktree entry that is still registered after reap +
+ * re-prune retries. Two outcomes:
+ *
+ *   - `stale-registry-entry` (operationally complete): the reap succeeded,
+ *     the worktree directory is gone, and the local branch was deleted by
+ *     reap. The only artifact left is the `.git/worktrees/<name>/` registry
+ *     entry — a Windows file-lock artifact, not a genuine cleanup failure.
+ *     Record a pending-cleanup entry so the post-close drain (or the next
+ *     plan-time sweep) re-runs `git worktree prune`, and let the close
+ *     pipeline report `branchDeleted: true` honestly.
+ *   - `still-registered` (genuine failure): the directory is still on disk
+ *     OR the branch was not deleted. The pre-existing OPERATOR ACTION
+ *     escalation still fires.
+ */
+function applyStillRegisteredState({
+  state,
+  stillRegistered,
+  reapResult,
+  storyId,
+  orchestration,
+  repoRoot,
+  logger,
+  recordPendingCleanupFn,
+  pathExistsFn,
+}) {
+  const pathGone = !pathExistsFn(stillRegistered.path);
+  const branchDeleted = reapResult.branchDeleted === true;
+  const operationallyComplete =
+    reapResult.removed === true && pathGone && branchDeleted;
+  if (!operationallyComplete) {
+    return {
+      ...state,
+      status: 'still-registered',
+      path: stillRegistered.path,
+      reason: 'still-registered-after-reap',
+    };
+  }
+  const worktreeRoot = resolveWorktreeRoot(repoRoot, orchestration);
+  let manifestEntry = null;
+  if (worktreeRoot) {
+    try {
+      manifestEntry = recordPendingCleanupFn(worktreeRoot, {
+        storyId: Number(storyId),
+        branch: getStoryBranch(null, storyId),
+        path: stillRegistered.path,
+        push: false,
+      });
+    } catch (err) {
+      logger?.warn?.(
+        `[post-merge-pipeline] pending-cleanup record failed (continuing): ${err?.message ?? err}`,
+      );
+    }
+  }
+  return {
+    ...state,
+    status: 'stale-registry-entry',
+    path: stillRegistered.path,
+    reason: 'stale-registry-entry',
+    pendingCleanup: manifestEntry ?? state.pendingCleanup,
+  };
+}

package/.agents/scripts/lib/orchestration/post-merge-pipeline.js

@@ -0,0 +1,205 @@
+/**
+ * post-merge-pipeline.js — sequencer for the post-merge phases of
+ * `story-close`.
+ *
+ * After the Story branch is merged into the Epic branch, several best-effort
+ * cleanup + reporting phases must run:
+ *
+ *   1. worktree-reap       — remove the per-Story worktree.
+ *   2. branch-cleanup      — delete the Story branch (local + remote).
+ *   3. ticket-closure      — transition the Story to agent::done
+ *                            and run cascade completion.
+ *   4. notification        — fire the story-complete webhook.
+ *   5. dashboard-refresh   — regenerate the dispatch manifest.
+ *   6. temp-cleanup        — delete the per-Story manifest pair under
+ *                            `temp/epic-<eid>/stories/story-<sid>/manifest.{md,json}`
+ *                            (Epic #1030 Story #1040). Falls back to the
+ *                            legacy flat `temp/story-manifest-<id>.{md,json}`
+ *                            layout when `epicId` is unknown — both paths
+ *                            are tried so partial migrations don't leak
+ *                            files in either layout.
+ *   7. detectors           — fire rework + retry signal detectors against
+ *                            this Story's `traces.ndjson` and persist each
+ *                            emission to `signals.ndjson` BEFORE the
+ *                            analyzer renders the perf-summary comment.
+ *   8. perf-summary        — shell out to `analyze-execution.js` so the
+ *                            analyzer is the single writer of the
+ *                            `<!-- structured:story-perf-summary -->`
+ *                            comment on the Story ticket.
+ *
+ * Each phase is wrapped by `runPhase` so a single failure does not abort
+ * the rest of the close-out — the same best-effort contract that the
+ * pre-extraction inline code provided. Phase return values are merged into
+ * a `state` object whose shape `runStoryClose` consumes to build the final
+ * structured result.
+ *
+ * The phase implementations live under `./post-merge/phases/` (one file
+ * per phase) — this module is a pure sequencer that imports each phase,
+ * re-exports them for backwards compatibility, and runs them in order
+ * via `runPhase`.
+ */
+
+import { execFileSync } from 'node:child_process';
+import path from 'node:path';
+import { Logger } from '../Logger.js';
+import { detectorsPhase } from './detectors-phase.js';
+import { runPhase } from './phase-runner.js';
+import { branchCleanupPhase } from './post-merge/phases/branch-cleanup.js';
+import { dashboardRefreshPhase } from './post-merge/phases/dashboard-refresh.js';
+import { notificationPhase } from './post-merge/phases/notification.js';
+import { tempCleanupPhase } from './post-merge/phases/temp-cleanup.js';
+import { ticketClosurePhase } from './post-merge/phases/ticket-closure.js';
+import {
+  createWorktreeReapState,
+  worktreeReapPhase,
+} from './post-merge/phases/worktree-reap.js';
+
+export {
+  branchCleanupPhase,
+  dashboardRefreshPhase,
+  detectorsPhase,
+  notificationPhase,
+  tempCleanupPhase,
+  ticketClosurePhase,
+  worktreeReapPhase,
+};
+
+function reapPhaseLogger(progress) {
+  return progress ?? (() => {});
+}
+
+/**
+ * perfSummaryPhase — shells out to `analyze-execution.js --story <sid>
+ * --epic <eid> --phase-timings <path>` so the analyzer is the single
+ * writer of the `<!-- structured:story-perf-summary -->` comment on the
+ * Story ticket (Epic #1030 Story #1046). Replaces the legacy
+ * `<!-- structured:phase-timings -->` post that lived inline in
+ * `post-merge-close.js`.
+ *
+ * Best-effort: any failure (missing analyzer, non-zero exit, no path
+ * supplied) logs a warning and resolves — the merge has already
+ * succeeded and we would rather lose the perf summary than roll back
+ * closure.
+ *
+ * @param {{
+ *   storyId: number|string,
+ *   epicId: number|string,
+ *   phaseTimingsPath: string|null|undefined,
+ *   projectRoot?: string,
+ *   progress?: Function,
+ *   logger?: object,
+ *   spawnFn?: typeof execFileSync,
+ * }} ctx
+ * @returns {Promise<{ status: 'ok'|'skipped'|'failed', reason?: string }>}
+ */
+export async function perfSummaryPhase(ctx) {
+  const {
+    storyId,
+    epicId,
+    phaseTimingsPath,
+    projectRoot,
+    progress,
+    logger,
+    spawnFn = execFileSync,
+  } = ctx;
+  const log = reapPhaseLogger(progress);
+  if (!phaseTimingsPath) {
+    log('PERF', '⏭️ Skipping perf-summary (no phase-timings path provided)');
+    return { status: 'skipped', reason: 'no-phase-timings-path' };
+  }
+  const root = projectRoot ?? process.cwd();
+  const analyzerPath = path.join(
+    root,
+    '.agents',
+    'scripts',
+    'analyze-execution.js',
+  );
+  const args = [
+    analyzerPath,
+    '--story',
+    String(storyId),
+    '--epic',
+    String(epicId),
+    '--phase-timings',
+    phaseTimingsPath,
+  ];
+  log(
+    'PERF',
+    `Running analyzer: analyze-execution.js --story ${storyId} --epic ${epicId}`,
+  );
+  try {
+    spawnFn(process.execPath, args, {
+      cwd: root,
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    log('PERF', '✅ story-perf-summary posted');
+    return { status: 'ok' };
+  } catch (err) {
+    const reason = err?.message ?? String(err);
+    logger?.warn?.(
+      `[post-merge-pipeline] ⚠️ analyze-execution failed (non-fatal): ${reason}`,
+    );
+    return { status: 'failed', reason };
+  }
+}
+
+export const DEFAULT_POST_MERGE_PHASES = Object.freeze([
+  {
+    name: 'worktree-reap',
+    fn: worktreeReapPhase,
+    stateKey: 'worktreeReap',
+    fallback: createWorktreeReapState({
+      status: 'failed',
+      reason: 'phase-error',
+    }),
+  },
+  { name: 'branch-cleanup', fn: branchCleanupPhase, stateKey: 'branchCleanup' },
+  { name: 'ticket-closure', fn: ticketClosurePhase, stateKey: 'ticketClosure' },
+  { name: 'notification', fn: notificationPhase },
+  {
+    name: 'dashboard-refresh',
+    fn: dashboardRefreshPhase,
+    stateKey: 'manifestUpdated',
+  },
+  { name: 'temp-cleanup', fn: tempCleanupPhase },
+  // Detectors MUST run before `perf-summary`. The perf phase shells out
+  // to `analyze-execution.js`, which reads the per-Story signals stream
+  // to author the `<!-- structured:story-perf-summary -->` comment;
+  // emitting rework/retry events first ensures the rendered surface
+  // reflects this Story's signals.
+  { name: 'detectors', fn: detectorsPhase, stateKey: 'detectors' },
+  { name: 'perf-summary', fn: perfSummaryPhase, stateKey: 'perfSummary' },
+]);
+
+/**
+ * Sequence the post-merge phases of `story-close`. Every phase runs
+ * under `runPhase` so a single failure logs `[phase=<name>] <err>` and the
+ * pipeline keeps going. Each phase's return value is recorded under its
+ * `stateKey` (when defined) on the returned state object.
+ *
+ * @param {object} ctx          Phase collaborators (provider, notify,
+ *                              logger, progress, etc.).
+ * @param {Array<{name: string, fn: Function, stateKey?: string, fallback?: any}>} [phases]
+ *                              Phase descriptors. Defaults to `DEFAULT_POST_MERGE_PHASES`.
+ * @returns {Promise<object>}   Aggregated state from each phase.
+ */
+export async function runPostMergePipeline(
+  ctx,
+  phases = DEFAULT_POST_MERGE_PHASES,
+) {
+  const logger = ctx.logger ?? Logger;
+  const state = {
+    worktreeReap: createWorktreeReapState(),
+    branchCleanup: { localDeleted: false, remoteDeleted: false },
+    ticketClosure: { closedTickets: [], cascadedTo: [], cascadeFailed: [] },
+    manifestUpdated: false,
+  };
+  for (const phase of phases) {
+    const value = await runPhase(phase.name, () => phase.fn(ctx, state), {
+      logger,
+      fallback: phase.fallback,
+    });
+    if (phase.stateKey && value !== undefined) state[phase.stateKey] = value;
+  }
+  return state;
+}

package/.agents/scripts/lib/orchestration/pr-base-guard.js

@@ -0,0 +1,47 @@
+// .agents/scripts/lib/orchestration/pr-base-guard.js
+/**
+ * pr-base-guard.js — refuse to open a pull request that would route an
+ * Epic-attached Story's work directly into `main` instead of into the
+ * parent Epic integration branch.
+ *
+ * Background: Story #2960 — during Epic #2880 wave 5 a sub-agent fell
+ * back to `gh pr create --base main` after `story-close.js`
+ * short-circuited as a no-op. The orphaned PR forced a manual recovery
+ * (`git merge origin/main` back into `epic/2880`). This module is the
+ * defence-in-depth call any framework helper that triggers `gh pr create`
+ * MUST invoke before shelling out.
+ *
+ * Scope: the guard fires only when the Story body declares an
+ * `Epic: #N` (or `Parent: #N`) reference. Stand-alone Stories — the
+ * `/single-story-deliver` surface — are unaffected because they have no
+ * parent reference to detect.
+ */
+
+import { resolveStoryHierarchy } from '../story-lifecycle.js';
+
+/**
+ * Inspect a Story's body for an Epic parent reference and refuse a PR
+ * whose `baseBranch` is not the matching `epic/<N>` integration branch.
+ *
+ * @param {object} args
+ * @param {number} args.storyId — Story ticket id (used in the error
+ *   message so the operator can grep the failing surface).
+ * @param {string|null|undefined} args.storyBody — raw Story body markdown.
+ *   When falsy, the guard short-circuits (no parent → nothing to enforce).
+ * @param {string} args.baseBranch — the `--base` value about to be passed
+ *   to `gh pr create`.
+ * @throws {Error} when the Story is Epic-attached and `baseBranch` is not
+ *   the parent Epic's branch. The message matches the AC verbatim so
+ *   reviewers can grep it.
+ */
+export function assertStoryPrBaseAllowed({ storyId, storyBody, baseBranch }) {
+  if (!storyBody) return;
+  const { epicId } = resolveStoryHierarchy(storyBody);
+  if (epicId == null) return;
+  const expected = `epic/${epicId}`;
+  if (baseBranch === expected) return;
+  throw new Error(
+    `Story #${storyId} is parented by Epic #${epicId} — merge into ${expected}, not ${baseBranch}. ` +
+      'To bypass, use /single-story-deliver explicitly.',
+  );
+}