mandrel 2.66.0 → 2.68.0

package/.agents/scripts/lib/orchestration/single-story-close/runner.js

@@ -33,7 +33,7 @@ import { deriveCloseNote } from './close-note.js';
 import { runAutoMergePhase } from './phases/auto-merge.js';
 import { runBaseSyncPhase } from './phases/base-sync.js';
 import { runCloseValidationPhase } from './phases/close-validation.js';
-import { parsePrNumber, runStoryScopeReview } from './phases/code-review.js';
+import { parsePrNumber } from './phases/code-review.js';
 import { runConfirmMergePhase } from './phases/confirm-merge.js';
 import { runGraphqlPreflight } from './phases/graphql-preflight.js';
 import { lockWaitPending } from './phases/lock-wait-pending.js';
@@ -45,11 +45,17 @@ import { handleCriticalReviewBlock } from './phases/review-block.js';
 import { handleOverriddenReviewBlock } from './phases/review-override.js';
 import { reapWorktreePhase } from './phases/worktree-reap.js';
 import { runWrongTreeGuardPhase } from './phases/wrong-tree-guard.js';
+import {
+  discardHeldReview,
+  reviewAfterPrOpen,
+  startHeldReview,
+} from './review-overlap.js';
 
 const progress = Logger.createProgress('single-story-close', { stderr: true });
 
 /**
  * Wall-clock seconds per named phase; each transition logs the phase it ends.
+ * Overlapping work `pause`s the clock and `record`s its own time.
  *
  * @param {() => number} [nowMs]
  */
@@ -57,11 +63,14 @@ function createPhaseTimer(nowMs = Date.now) {
   const durations = {};
   let current = null;
   let since = 0;
+  const record = (phase, ms) => {
+    const seconds = Math.round(Math.max(0, ms) / 100) / 10;
+    durations[phase] = (durations[phase] ?? 0) + seconds;
+    progress('TIMING', `⏱  ${phase}: ${seconds}s`);
+  };
   const end = () => {
     if (current === null) return;
-    const seconds = Math.round((nowMs() - since) / 100) / 10;
-    durations[current] = (durations[current] ?? 0) + seconds;
-    progress('TIMING', `⏱  ${current}: ${seconds}s`);
+    record(current, nowMs() - since);
     current = null;
   };
   return {
@@ -71,6 +80,8 @@ function createPhaseTimer(nowMs = Date.now) {
       current = phase;
       since = nowMs();
     },
+    record,
+    pause: end,
     finish() {
       end();
       return Object.keys(durations).length > 0 ? { ...durations } : null;
@@ -257,6 +268,7 @@ function resolveWorktreePath({ cwd, config, storyId }) {
  * @returns {Promise<{
  *   validationGates: Record<string, string>|null,
  *   lockWait: { waitedSeconds: number, expired: boolean }|null,
+ *   suiteTimings: object|null,
  *   pending: boolean,
  * }>} `validationGates` is null when skipped; `pending` means a full-suite
  *   lock wait expired and the gates deferred.
@@ -293,7 +305,12 @@ async function runPrePushPhases(ctx, deps) {
   }
   if (options.skipValidation) {
     progress('VALIDATE', '⏭ Skipped (--skip-validation).');
-    return { validationGates: null, lockWait: null, pending: false };
+    return {
+      validationGates: null,
+      lockWait: null,
+      suiteTimings: null,
+      pending: false,
+    };
   }
   setPhase('close-validation');
   let validation;
@@ -308,8 +325,22 @@ async function runPrePushPhases(ctx, deps) {
       progress,
       runCloseValidation,
       buildDefaultGates,
+      onPreGateStepsDone: () => {
+        ctx.heldReview = startHeldReview({
+          cwd,
+          storyId,
+          storyBranch,
+          baseBranch,
+          provider: deps.provider,
+          runCodeReviewFn: deps.runCodeReview,
+          gitSpawnFn: gitSpawn,
+          progress,
+          config: deps.config,
+        });
+      },
     });
   } catch (err) {
+    discardHeldReview(ctx.heldReview, 'validation failed', progress);
     // The gate that died is all this run observed; the envelope claims no more.
     if (typeof err?.closeGate === 'string') {
       ctx.setObservedGates({ [err.closeGate]: 'failed' });
@@ -321,6 +352,7 @@ async function runPrePushPhases(ctx, deps) {
   return {
     validationGates: gates,
     lockWait: validation?.lockWait ?? null,
+    suiteTimings: validation?.suiteTimings ?? null,
     pending: validation?.pending === true,
   };
 }
@@ -396,10 +428,11 @@ async function openAndReviewPr(ctx, deps) {
   const prNumber = parsePrNumber(prUrl);
   // Already merged (landed between invocations): skip review and arm; confirm observes it.
   if (alreadyMerged) {
+    discardHeldReview(ctx.heldReview, 'PR already merged', progress);
     return { prUrl, prNumber, alreadyMerged: true };
   }
-  ctx.setPhase('code-review');
-  const reviewOutcome = await runStoryScopeReview({
+  const reviewOutcome = await reviewAfterPrOpen({
+    held: ctx.heldReview,
     cwd,
     storyId,
     storyBranch,
@@ -410,6 +443,9 @@ async function openAndReviewPr(ctx, deps) {
     runCodeReviewFn: deps.runCodeReview,
     gitSpawnFn: gitSpawn,
     progress,
+    setPhase: ctx.setPhase,
+    pauseTimer: ctx.phaseTimer.pause,
+    recordDuration: ctx.phaseTimer.record,
   });
   const reviewOverride = reviewOutcome.halted
     ? await resolveReviewHalt(ctx, deps, { prUrl, prNumber, reviewOutcome })
@@ -690,6 +726,7 @@ async function finishWithMergeWait(prCtx, deps) {
     autoMergeEnabled: prCtx.autoMergeEnabled,
     gates: prCtx.gates,
     lockWait: prCtx.lockWait,
+    suiteTimings: prCtx.suiteTimings,
     elapsedSeconds: elapsedSecondsSince(prCtx.startedAtMs),
   });
   const result = closeResult({
@@ -763,6 +800,7 @@ async function finishWithoutMergeWait(prCtx, waitForMergeReason) {
     },
     gates: prCtx.gates,
     lockWait: prCtx.lockWait,
+    suiteTimings: prCtx.suiteTimings,
     nextCommand: NEXT_COMMANDS.confirmMerge(prCtx.storyId),
     elapsedSeconds: elapsedSecondsSince(prCtx.startedAtMs),
   });
@@ -891,6 +929,7 @@ async function prePushPhase(ctx, deps) {
     deps,
   );
   if (!ctx.prePush.pending) return null;
+  discardHeldReview(ctx.heldReview, 'validation pending', progress);
   return await finishDeferred(ctx.prePush.lockWait, {
     storyId: ctx.storyId,
     storyBranch: ctx.storyBranch,
@@ -991,6 +1030,7 @@ async function finishPhase(ctx, deps) {
     phaseTimer: ctx.phaseTimer,
     workerTokens: ctx.workerTokens,
     lockWait: ctx.prePush.lockWait,
+    suiteTimings: ctx.prePush.suiteTimings,
     gates: closeEnvelopeGates(
       options,
       ctx.prePush.validationGates,

package/.agents/scripts/lib/orchestration/story-deliver-terminal.js

@@ -114,8 +114,9 @@ function compact(obj) {
  * @param {string|null} [args.nextCommand]
  * @param {number} args.elapsedSeconds
  * @param {object|null} [args.waitBudget]
- * @param {{ waitedSeconds: number, expired: boolean }|null} [args.lockWait]
+ * @param {{ waitedSeconds: number, expired: boolean, holder?: object }|null} [args.lockWait]
  *   Full-suite lock wait; `waitBudget` is merge-wait only.
+ * @param {{ lockWaitMs: number, hostWaitMs: number|null, testRunMs: number }|null} [args.suiteTimings]
  * @param {Record<string, number>|null} [args.phaseDurations] Seconds per phase.
  * @param {string} [args.timestamp]
  * @param {{ schema: object|null, error: string|null }} [args.schemaSource]
@@ -138,6 +139,7 @@ export function buildTerminalEnvelope({
   elapsedSeconds = 0,
   waitBudget,
   lockWait,
+  suiteTimings,
   phaseDurations,
   timestamp = new Date().toISOString(),
   schemaSource,
@@ -160,6 +162,7 @@ export function buildTerminalEnvelope({
     elapsedSeconds: Math.max(0, Number(elapsedSeconds) || 0),
     waitBudget: waitBudget ?? null,
     lockWait: lockWait ?? null,
+    suiteTimings: suiteTimings ?? null,
     phaseDurations,
     timestamp,
   });
@@ -324,35 +327,24 @@ export function emitTerminalEnvelope(
 }
 
 /**
- * Map a `runConfirmMergePhase` outcome onto the terminal envelope.
+ * Map a `runConfirmMergePhase` outcome onto the terminal envelope; the other
+ * fields pass through.
  *
  * @returns {object} A validated `story-deliver-terminal` envelope.
  */
 export function terminalFromWaitOutcome({
   waitOutcome,
-  storyId,
-  storyBranch,
-  baseBranch,
   prNumber,
   prUrl,
   autoMergeEnabled,
-  gates,
-  lockWait,
-  elapsedSeconds,
+  ...common
 }) {
+  const { storyId } = common;
   const prBase = {
     number: prNumber,
     url: prUrl ?? null,
     autoMergeEnabled: Boolean(autoMergeEnabled),
   };
-  const common = {
-    storyId,
-    storyBranch,
-    baseBranch,
-    gates,
-    lockWait,
-    elapsedSeconds,
-  };
 
   if (waitOutcome.terminal === 'landed') {
     return buildTerminalEnvelope({

package/.agents/scripts/lib/process-group.js

@@ -27,7 +27,7 @@ export function groupSpawnOptions(platform = process.platform) {
  * @param {{ platform?: string, killFn?: (pid: number, signal: string) => void }} [opts]
  * @returns {boolean}
  */
-function killProcessGroup(
+export function killProcessGroup(
   child,
   signal = 'SIGKILL',
   { platform = process.platform, killFn = process.kill.bind(process) } = {},

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/supervised-suite.js

@@ -0,0 +1,247 @@
+/**
+ * A full suite supervised as a process group. The suite may write
+ * `$MANDREL_SUITE_READY_FILE` when its tests start; the kill timer then
+ * re-arms a fresh `timeoutMs`, so a pre-test wait (bounded by `timeoutMs`
+ * too) never spends the test budget. Close parses the timing line back.
+ */
+import { spawn } from 'node:child_process';
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+import {
+  groupSpawnOptions,
+  killProcessGroup,
+  superviseGroup,
+  TIMEOUT_EXIT_CODE,
+} from './process-group.js';
+
+/** @typedef {{ lockWaitMs: number, hostWaitMs: number|null, testRunMs: number }} SuiteTimings */
+
+export const SUITE_READY_FILE_ENV = 'MANDREL_SUITE_READY_FILE';
+
+const DEFAULT_READY_POLL_MS = 250;
+
+const NO_HOST_WAIT = 'n/a';
+
+/** @param {{ dir?: string }} [opts] */
+export function suiteReadyHandshake({ dir = os.tmpdir() } = {}) {
+  const name = `mandrel-suite-ready-${process.pid}-${crypto.randomBytes(6).toString('hex')}`;
+  const file = path.join(dir, name);
+  return { file, env: { [SUITE_READY_FILE_ENV]: file } };
+}
+
+/** @param {SuiteTimings} timings */
+export function formatSuiteTimings({ lockWaitMs, hostWaitMs, testRunMs }) {
+  const host = hostWaitMs === null ? NO_HOST_WAIT : Math.round(hostWaitMs);
+  return `⏲ suite timings: lockWaitMs=${Math.round(lockWaitMs)} hostWaitMs=${host} testRunMs=${Math.round(testRunMs)}`;
+}
+
+/**
+ * @param {string} line
+ * @returns {SuiteTimings|null}
+ */
+export function parseSuiteTimings(line) {
+  const match =
+    /suite timings: lockWaitMs=(\d+) hostWaitMs=(\d+|n\/a) testRunMs=(\d+)/u.exec(
+      String(line ?? ''),
+    );
+  if (!match) return null;
+  return {
+    lockWaitMs: Number(match[1]),
+    hostWaitMs: match[2] === NO_HOST_WAIT ? null : Number(match[2]),
+    testRunMs: Number(match[3]),
+  };
+}
+
+function fileExists(fsImpl, file) {
+  try {
+    return fsImpl.existsSync(file);
+  } catch {
+    return false;
+  }
+}
+
+function removeQuietly(fsImpl, file) {
+  try {
+    fsImpl.rmSync(file, { force: true });
+  } catch {
+    // A leftover marker is harmless.
+  }
+}
+
+class SuiteClock {
+  constructor({ kill, timeoutMs, readyTimeoutMs, readyFile, fsImpl, nowFn }) {
+    Object.assign(this, { kill, timeoutMs, readyFile, fsImpl, nowFn });
+    this.timedOut = false;
+    this.startedAt = nowFn();
+    this.readyAt = null;
+    this.endedAt = null;
+    this.timer = null;
+    this.poller = null;
+    this.arm(readyTimeoutMs ?? timeoutMs);
+  }
+
+  arm(boundMs) {
+    clearTimeout(this.timer);
+    if (!(Number.isFinite(boundMs) && boundMs > 0)) return;
+    this.timer = setTimeout(() => {
+      this.timedOut = true;
+      this.kill();
+    }, boundMs);
+  }
+
+  watch(pollMs) {
+    this.poller = setInterval(() => this.checkReady(), pollMs);
+    this.poller.unref?.();
+  }
+
+  checkReady() {
+    if (this.readyAt !== null || this.timedOut) return;
+    if (!fileExists(this.fsImpl, this.readyFile)) return;
+    this.readyAt = this.nowFn();
+    clearInterval(this.poller);
+    this.arm(this.timeoutMs);
+  }
+
+  stop() {
+    this.endedAt ??= this.nowFn();
+    this.checkReady();
+    clearInterval(this.poller);
+    clearTimeout(this.timer);
+    removeQuietly(this.fsImpl, this.readyFile);
+  }
+
+  timings() {
+    const end = this.endedAt ?? this.nowFn();
+    const testStart = this.readyAt ?? this.startedAt;
+    return {
+      hostWaitMs: this.readyAt === null ? null : this.readyAt - this.startedAt,
+      testRunMs: Math.max(0, end - testStart),
+    };
+  }
+}
+
+/**
+ * `hostWaitMs` is spawn → ready (null without a signal); `testRunMs` ends at
+ * exit. `readyTimeoutMs` (pre-ready bound) is a test seam over `timeoutMs`.
+ *
+ * @param {{ pid?: number, kill?: Function }} child
+ * @param {{ readyFile: string, timeoutMs?: number, readyTimeoutMs?: number, readyPollMs?: number, abortSignal?: AbortSignal, signalOnParentSignal?: string, fsImpl?: object, nowFn?: () => number }} opts
+ */
+export function superviseSuite(child, opts) {
+  const { readyPollMs = DEFAULT_READY_POLL_MS, fsImpl = fs } = opts;
+  const group = superviseGroup(child, {
+    abortSignal: opts.abortSignal,
+    signalOnParentSignal: opts.signalOnParentSignal,
+  });
+  const clock = new SuiteClock({
+    ...opts,
+    fsImpl,
+    nowFn: opts.nowFn ?? Date.now,
+    kill: () => killProcessGroup(child, 'SIGKILL'),
+  });
+  clock.watch(readyPollMs);
+  return {
+    get timedOut() {
+      return clock.timedOut;
+    },
+    get timings() {
+      return clock.timings();
+    },
+    release() {
+      clock.stop();
+      group.release();
+    },
+  };
+}
+
+/**
+ * A bare suite gets SIGKILL on a parent signal; a gate with its own cleanup
+ * (a capture holding the lock) SIGTERM. A full-suite gate also gets the
+ * handshake and emits its timing line on release.
+ *
+ * @param {{ fullSuiteLock?: boolean, timeoutMs?: number, signal?: AbortSignal, env?: Record<string, string> }} opts
+ * @param {{ lockWaitMs?: number }} [lock]
+ */
+export function gateSupervision(opts, lock = {}) {
+  const base = {
+    timeoutMs: opts.timeoutMs,
+    abortSignal: opts.signal,
+    signalOnParentSignal: opts.fullSuiteLock ? 'SIGKILL' : 'SIGTERM',
+  };
+  if (!opts.fullSuiteLock) {
+    return { env: opts.env, supervise: (child) => superviseGroup(child, base) };
+  }
+  const handshake = suiteReadyHandshake();
+  return {
+    env: { ...opts.env, ...handshake.env },
+    supervise: (child, output) =>
+      reportOnRelease(
+        superviseSuite(child, { ...base, readyFile: handshake.file }),
+        (timings) =>
+          output.emit(
+            output.prefix +
+              formatSuiteTimings({
+                lockWaitMs: lock.lockWaitMs ?? 0,
+                ...timings,
+              }),
+          ),
+      ),
+  };
+}
+
+/**
+ * @param {ReturnType<typeof superviseSuite>} supervisor
+ * @param {(timings: object) => void} report
+ */
+function reportOnRelease(supervisor, report) {
+  return {
+    get timedOut() {
+      return supervisor.timedOut;
+    },
+    release() {
+      supervisor.release();
+      report(supervisor.timings);
+    },
+  };
+}
+
+/**
+ * Resolves the exit code, or `124` when the supervisor killed the suite.
+ *
+ * @param {{ cmd: string, args: string[], cwd: string, env?: Record<string, string>, timeoutMs?: number, readyTimeoutMs?: number, readyPollMs?: number, lockWaitMs?: number, spawnImpl?: typeof spawn, onTimings?: (timings: SuiteTimings) => void, onTimeout?: () => void }} opts
+ * @returns {Promise<number>}
+ */
+export function runSupervisedSuite(opts) {
+  const { cmd, args, cwd, env = {}, spawnImpl = spawn } = opts;
+  const handshake = suiteReadyHandshake();
+  return new Promise((resolve) => {
+    const child = spawnImpl(cmd, args, {
+      cwd,
+      env: { ...process.env, ...env, ...handshake.env },
+      stdio: 'inherit',
+      shell: process.platform === 'win32',
+      ...groupSpawnOptions(),
+    });
+    const supervisor = superviseSuite(child, {
+      ...opts,
+      readyFile: handshake.file,
+    });
+    let settled = false;
+    const settle = (code) => {
+      if (settled) return;
+      settled = true;
+      supervisor.release();
+      opts.onTimings?.({
+        lockWaitMs: opts.lockWaitMs ?? 0,
+        ...supervisor.timings,
+      });
+      if (supervisor.timedOut) opts.onTimeout?.();
+      resolve(supervisor.timedOut ? TIMEOUT_EXIT_CODE : code);
+    };
+    child.on('error', () => settle(1));
+    child.on('exit', (code) => settle(code ?? 1));
+  });
+}

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 };
+}