mandrel 2.65.0 → 2.67.0

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

@@ -9,6 +9,11 @@ import { getCiDelivery } from '../../config/ci.js';
 import { resolveConfig } from '../../config-resolver.js';
 import { getStoryBranch, gitSpawn, gitSync } from '../../git-utils.js';
 import { Logger } from '../../Logger.js';
+import {
+  emitReviewBlockedFriction,
+  recordCloseTelemetry,
+  resolveWorkerTokens,
+} from '../../observability/close-telemetry.js';
 import { emitTerminalFriction } from '../../observability/runtime-friction.js';
 import { emitTerseResult } from '../../observability/terse-result.js';
 import { createProvider } from '../../provider-factory.js';
@@ -80,17 +85,20 @@ function createPhaseTimer(nowMs = Date.now) {
 const UNTIMED = Object.freeze({ stamp() {} });
 
 /**
- * The single terminal writer: the result summary, the envelope callers parse,
- * and terminal friction — so no ending can forget one. Must be awaited: the
- * CLI `process.exit`s as soon as `main` resolves.
+ * The single terminal writer: the retry signal, the result summary (with its
+ * `telemetry`), the envelope callers parse, and terminal friction — so no
+ * ending can forget one. Must be awaited: the CLI `process.exit`s as soon as
+ * `main` resolves.
  */
 async function emitTerminal({
   terminal,
   result,
   config,
   phaseTimer = UNTIMED,
+  workerTokens = null,
 }) {
   phaseTimer.stamp(terminal);
+  await recordCloseTelemetry({ terminal, result, config, workerTokens });
   if (result) {
     emitTerseResult({
       label: 'STORY CLOSE RESULT',
@@ -109,23 +117,32 @@ async function emitTerminal({
   await emitTerminalFriction({ envelope: terminal, config });
 }
 
+/**
+ * @param {number} storyId
+ * @param {string} reason
+ * @returns {{ storyId: number, standalone: true, action: 'noop', reason: string }}
+ */
+function noopResult(storyId, reason) {
+  return { storyId, standalone: true, action: 'noop', reason };
+}
+
 /**
  * Terminal for an already-closed Story. `not_planned` means nothing merged,
  * so it fails rather than reporting `landed` (which would also unblock
  * dependents); `completed` or null (GitHub's default) reads as landed.
  */
-async function alreadyClosedResult(storyId, stateReason = null, config) {
+async function alreadyClosedResult(
+  storyId,
+  stateReason = null,
+  config,
+  workerTokens = null,
+) {
   if (stateReason === 'not_planned') {
     progress(
       'NOOP',
       `Story #${storyId} is closed as not planned — nothing to land.`,
     );
-    const result = {
-      storyId,
-      standalone: true,
-      action: 'noop',
-      reason: 'closed-not-planned',
-    };
+    const result = noopResult(storyId, 'closed-not-planned');
     const terminal = buildTerminalEnvelope({
       storyId,
       status: 'failed',
@@ -138,17 +155,12 @@ async function alreadyClosedResult(storyId, stateReason = null, config) {
       nextCommand: null,
       elapsedSeconds: 0,
     });
-    await emitTerminal({ terminal, result, config });
+    await emitTerminal({ terminal, result, config, workerTokens });
     return { success: false, result, terminal };
   }
 
   progress('NOOP', `Story #${storyId} is already closed. Nothing to do.`);
-  const result = {
-    storyId,
-    standalone: true,
-    action: 'noop',
-    reason: 'already-closed',
-  };
+  const result = noopResult(storyId, 'already-closed');
   const terminal = buildTerminalEnvelope({
     storyId,
     status: 'landed',
@@ -156,7 +168,7 @@ async function alreadyClosedResult(storyId, stateReason = null, config) {
     nextCommand: null,
     elapsedSeconds: 0,
   });
-  await emitTerminal({ terminal, result, config });
+  await emitTerminal({ terminal, result, config, workerTokens });
   return { success: true, result, terminal };
 }
 
@@ -179,13 +191,9 @@ async function preflightBlockedResult({
   preflight,
   config,
   startedAtMs,
+  workerTokens = null,
 }) {
-  const result = {
-    storyId,
-    standalone: true,
-    action: 'noop',
-    reason: `graphql-preflight-${preflight.verdict}`,
-  };
+  const result = noopResult(storyId, `graphql-preflight-${preflight.verdict}`);
   const terminal = buildTerminalEnvelope({
     storyId,
     status: 'blocked',
@@ -198,7 +206,7 @@ async function preflightBlockedResult({
     nextCommand: NEXT_COMMANDS.close(storyId),
     elapsedSeconds: elapsedSecondsSince(startedAtMs),
   });
-  await emitTerminal({ terminal, result, config });
+  await emitTerminal({ terminal, result, config, workerTokens });
   return { success: false, result, terminal };
 }
 
@@ -244,6 +252,8 @@ function resolveWorktreePath({ cwd, config, storyId }) {
  * the validated tree is the pushed tree (base-sync's merge commit included),
  * and a cheap conflict is found before the expensive gates.
  *
+ * @param {object} ctx
+ * @param {object} deps
  * @returns {Promise<{
  *   validationGates: Record<string, string>|null,
  *   lockWait: { waitedSeconds: number, expired: boolean }|null,
@@ -251,49 +261,37 @@ function resolveWorktreePath({ cwd, config, storyId }) {
  * }>} `validationGates` is null when skipped; `pending` means a full-suite
  *   lock wait expired and the gates deferred.
  */
-async function runPrePushPhases({
-  cwd,
-  worktreePath,
-  config,
-  baseBranch,
-  baseConfirmed,
-  storyBranch,
-  storyId,
-  provider,
-  skipValidation,
-  skipSync,
-  injectedSync,
-  injectedGitSpawn,
-  setPhase = () => {},
-  setObservedGates = () => {},
-}) {
+async function runPrePushPhases(ctx, deps) {
+  const { options, worktreePath, baseBranch, storyBranch, storyId, setPhase } =
+    ctx;
+  const { cwd } = options;
   setPhase('wrong-tree-guard');
   await runWrongTreeGuardPhase({
     cwd,
     worktreePath,
     baseBranch,
     storyId,
-    provider,
+    provider: deps.provider,
     progress,
-    gitSpawn: injectedGitSpawn,
+    gitSpawn: deps.gitSpawn,
   });
-  if (!skipSync) {
+  if (!options.skipSync) {
     setPhase('base-sync');
     await runBaseSyncPhase({
       cwd,
       worktreePath,
       baseBranch,
-      baseConfirmed,
+      baseConfirmed: ctx.baseConfirmed,
       storyBranch,
       storyId,
-      provider,
-      injectedSync,
+      provider: deps.provider,
+      injectedSync: deps.sync,
       progress,
     });
   } else {
     progress('SYNC', '⏭ Skipped (--skip-sync).');
   }
-  if (skipValidation) {
+  if (options.skipValidation) {
     progress('VALIDATE', '⏭ Skipped (--skip-validation).');
     return { validationGates: null, lockWait: null, pending: false };
   }
@@ -303,7 +301,7 @@ async function runPrePushPhases({
     validation = await runCloseValidationPhase({
       cwd,
       worktreePath,
-      config,
+      config: deps.config,
       baseBranch,
       storyBranch,
       storyId,
@@ -314,12 +312,12 @@ async function runPrePushPhases({
   } catch (err) {
     // The gate that died is all this run observed; the envelope claims no more.
     if (typeof err?.closeGate === 'string') {
-      setObservedGates({ [err.closeGate]: 'failed' });
+      ctx.setObservedGates({ [err.closeGate]: 'failed' });
     }
     throw err;
   }
   const gates = validation?.gates ?? null;
-  setObservedGates(gates);
+  ctx.setObservedGates(gates);
   return {
     validationGates: gates,
     lockWait: validation?.lockWait ?? null,
@@ -327,25 +325,64 @@ async function runPrePushPhases({
   };
 }
 
-async function openAndReviewPr({
-  cwd,
-  worktreePath,
-  story,
-  storyId,
-  storyBranch,
-  baseBranch,
-  provider,
-  config,
-  overrideReviewBlock,
-  injectedGh,
-  injectedRunCodeReview,
-  setPhase = () => {},
-}) {
-  setPhase('push');
+/**
+ * An overridden Story proceeds; anything else emits friction, blocks, throws.
+ *
+ * @param {object} ctx
+ * @param {object} deps
+ * @param {{ prUrl: string, prNumber: number|null, reviewOutcome: object }} pr
+ * @returns {Promise<object>}
+ */
+async function resolveReviewHalt(
+  ctx,
+  deps,
+  { prUrl, prNumber, reviewOutcome },
+) {
+  const { storyId } = ctx;
+  const criticalCount = reviewOutcome.severity?.critical ?? 0;
+  // Checked before the blocked transition: an overridden Story proceeds.
+  if (ctx.options.overrideReviewBlock) {
+    return await handleOverriddenReviewBlock({
+      provider: deps.provider,
+      storyId,
+      prUrl,
+      prNumber,
+      criticalCount,
+      criticalByProvider: reviewOutcome.criticalByProvider,
+      reason: ctx.options.overrideReviewBlock,
+      config: deps.config,
+    });
+  }
+  await emitReviewBlockedFriction({
+    storyId,
+    prNumber,
+    criticalCount,
+    criticalByProvider: reviewOutcome.criticalByProvider,
+    config: deps.config,
+  });
+  await handleCriticalReviewBlock({
+    provider: deps.provider,
+    storyId,
+    prUrl,
+    criticalCount,
+  });
+  throw new Error(
+    `[single-story-close] Story-scope review reported ${criticalCount} critical blocker(s) on PR ${prUrl}. ` +
+      'Auto-merge was not enabled. Remediate the findings posted to the PR and re-run `/mandrel-deliver`. ' +
+      'If you have reviewed a finding and judged it wrong, re-run with ' +
+      '`--override-review-block "<reason>"` rather than merging by hand.',
+  );
+}
+
+async function openAndReviewPr(ctx, deps) {
+  const { options, worktreePath, story, storyId, storyBranch, baseBranch } =
+    ctx;
+  const { cwd } = options;
+  ctx.setPhase('push');
   // Push from the worktree so `pre-push` measures the tree being sent; the
   // ref-based reads below resolve identically from the shared `.git`.
   pushStoryBranch({ cwd, worktreePath, storyBranch, gitSync, progress });
-  setPhase('pull-request');
+  ctx.setPhase('pull-request');
   const { url: prUrl, alreadyMerged } = await ensurePullRequestWith({
     cwd,
     storyId,
@@ -353,7 +390,7 @@ async function openAndReviewPr({
     storyBody: story.body,
     storyBranch,
     baseBranch,
-    gh: injectedGh,
+    gh: deps.gh,
     progress,
   });
   const prNumber = parsePrNumber(prUrl);
@@ -361,7 +398,7 @@ async function openAndReviewPr({
   if (alreadyMerged) {
     return { prUrl, prNumber, alreadyMerged: true };
   }
-  setPhase('code-review');
+  ctx.setPhase('code-review');
   const reviewOutcome = await runStoryScopeReview({
     cwd,
     storyId,
@@ -369,56 +406,24 @@ async function openAndReviewPr({
     baseBranch,
     prUrl,
     prNumber,
-    provider,
-    runCodeReviewFn: injectedRunCodeReview ?? runCodeReviewDefault,
+    provider: deps.provider,
+    runCodeReviewFn: deps.runCodeReview,
     gitSpawnFn: gitSpawn,
     progress,
   });
-  if (reviewOutcome.halted) {
-    const criticalCount = reviewOutcome.severity?.critical ?? 0;
-    // Checked before the blocked transition: an overridden Story proceeds.
-    if (overrideReviewBlock) {
-      const override = await handleOverriddenReviewBlock({
-        provider,
-        storyId,
-        prUrl,
-        prNumber,
-        criticalCount,
-        reason: overrideReviewBlock,
-        config,
-      });
-      return {
-        prUrl,
-        prNumber,
-        alreadyMerged: false,
-        reviewOverride: override,
-      };
-    }
-    await handleCriticalReviewBlock({
-      provider,
-      storyId,
-      prUrl,
-      criticalCount,
-    });
-    throw new Error(
-      `[single-story-close] Story-scope review reported ${criticalCount} critical blocker(s) on PR ${prUrl}. ` +
-        'Auto-merge was not enabled. Remediate the findings posted to the PR and re-run `/mandrel-deliver`. ' +
-        'If you have reviewed a finding and judged it wrong, re-run with ' +
-        '`--override-review-block "<reason>"` rather than merging by hand.',
-    );
-  }
-  return { prUrl, prNumber, alreadyMerged: false, reviewOverride: null };
+  const reviewOverride = reviewOutcome.halted
+    ? await resolveReviewHalt(ctx, deps, { prUrl, prNumber, reviewOutcome })
+    : null;
+  return { prUrl, prNumber, alreadyMerged: false, reviewOverride };
 }
 
-async function releaseLease({
-  provider,
-  storyId,
-  config,
-  injectedReleaseLease,
-}) {
+async function releaseLease({ storyId }, deps) {
   try {
-    const release = injectedReleaseLease ?? releaseStoryLease;
-    const outcome = await release({ provider, storyId, config });
+    const outcome = await deps.releaseLease({
+      provider: deps.provider,
+      storyId,
+      config: deps.config,
+    });
     progress(
       'LEASE',
       outcome.released
@@ -442,14 +447,13 @@ async function releaseLease({
  *
  * @template T
  * @param {() => Promise<T>} run
- * @param {{ provider: object, storyId: number, config: object, injectedReleaseLease?: Function }} leaseArgs
  * @returns {Promise<T>}
  */
-async function releaseLeaseOnBlock(run, leaseArgs) {
+async function releaseLeaseOnBlock(run, ctx, deps) {
   try {
     return await run();
   } catch (err) {
-    await releaseLease(leaseArgs);
+    await releaseLease(ctx, deps);
     throw err;
   }
 }
@@ -513,6 +517,29 @@ function closeResult({
   };
 }
 
+/**
+ * An injected double wins, else the real one; an absent optional seam stays
+ * `undefined` so its phase applies its own default.
+ *
+ * @param {{ cwd: string }} options
+ * @param {object} injected
+ * @returns {object}
+ */
+function resolveCloseDeps(options, injected) {
+  const config = injected.injectedConfig || resolveConfig({ cwd: options.cwd });
+  return {
+    config,
+    provider: injected.injectedProvider || createProvider(config),
+    notify: injected.injectedNotify,
+    sync: injected.injectedSync,
+    runCodeReview: injected.injectedRunCodeReview ?? runCodeReviewDefault,
+    gh: injected.injectedGh,
+    gitSpawn: injected.injectedGitSpawn,
+    releaseLease: injected.injectedReleaseLease ?? releaseStoryLease,
+    graphqlProbe: injected.injectedGraphqlProbe,
+  };
+}
+
 export async function runSingleStoryClose({
   storyId: storyIdParam,
   cwd: cwdParam,
@@ -525,15 +552,8 @@ export async function runSingleStoryClose({
   mergeWatchMode: mergeWatchModeParam,
   rerunAdvisory: rerunAdvisoryParam,
   overrideReviewBlock: overrideReviewBlockParam,
-  injectedProvider,
-  injectedConfig,
-  injectedNotify,
-  injectedSync,
-  injectedRunCodeReview,
-  injectedGh,
-  injectedGitSpawn,
-  injectedReleaseLease,
-  injectedGraphqlProbe,
+  workerTokens: workerTokensParam,
+  ...injected
 } = {}) {
   const options = parseCloseOptions({
     storyIdParam,
@@ -547,10 +567,11 @@ export async function runSingleStoryClose({
     mergeWatchModeParam,
     rerunAdvisoryParam,
     overrideReviewBlockParam,
+    workerTokensParam,
   });
   if (!options.storyId) {
     throw new Error(
-      'Usage: node single-story-close.js --story <STORY_ID> [--cwd <main-repo>] [--skip-validation] [--skip-sync] [--no-auto-merge] [--wait-merge|--no-wait-merge] [--max-wait-seconds <n>] [--merge-watch-mode <sync|async>] [--rerun-advisory <n>] [--override-review-block <reason>]',
+      'Usage: node single-story-close.js --story <STORY_ID> [--cwd <main-repo>] [--skip-validation] [--skip-sync] [--no-auto-merge] [--wait-merge|--no-wait-merge] [--max-wait-seconds <n>] [--merge-watch-mode <sync|async>] [--rerun-advisory <n>] [--override-review-block <reason>] [--worker-tokens <n>]',
     );
   }
 
@@ -568,21 +589,11 @@ export async function runSingleStoryClose({
     observedGates = gates;
   };
   try {
-    return await runClosePipeline({
-      options,
-      setPhase,
-      setObservedGates,
-      phaseTimer,
-      injectedProvider,
-      injectedConfig,
-      injectedNotify,
-      injectedSync,
-      injectedRunCodeReview,
-      injectedGh,
-      injectedGitSpawn,
-      injectedReleaseLease,
-      injectedGraphqlProbe,
-    });
+    const startedAtMs = Date.now();
+    return await runClosePipeline(
+      { options, setPhase, setObservedGates, phaseTimer, startedAtMs },
+      resolveCloseDeps(options, injected),
+    );
   } catch (err) {
     if (err && typeof err === 'object') {
       err.closePhaseDurations = phaseTimer.finish();
@@ -706,6 +717,7 @@ async function finishWithMergeWait(prCtx, deps) {
     result,
     config: prCtx.config,
     phaseTimer: prCtx.phaseTimer,
+    workerTokens: prCtx.workerTokens,
   });
   reportWaitTerminal(terminal, { storyId: prCtx.storyId, prUrl: prCtx.prUrl });
   return { success: terminal.status === 'landed', result, terminal };
@@ -759,6 +771,7 @@ async function finishWithoutMergeWait(prCtx, waitForMergeReason) {
     result,
     config: prCtx.config,
     phaseTimer: prCtx.phaseTimer,
+    workerTokens: prCtx.workerTokens,
   });
   progress(
     'DONE',
@@ -777,14 +790,14 @@ async function finishWithoutMergeWait(prCtx, waitForMergeReason) {
  */
 async function finishDeferred(
   lockWait,
-  { config, startedAtMs, phaseTimer, ...ids },
+  { config, startedAtMs, phaseTimer, workerTokens, ...ids },
 ) {
   const { result, terminal, note } = lockWaitPending({
     ...ids,
     lockWait,
     elapsedSeconds: elapsedSecondsSince(startedAtMs),
   });
-  await emitTerminal({ terminal, result, config, phaseTimer });
+  await emitTerminal({ terminal, result, config, phaseTimer, workerTokens });
   progress('PENDING', note);
   return { success: false, result, terminal };
 }
@@ -819,212 +832,212 @@ function reportOperatorMergeSkip({
   );
 }
 
-async function runClosePipeline({
-  options,
-  setPhase,
-  setObservedGates,
-  phaseTimer,
-  injectedProvider,
-  injectedConfig,
-  injectedNotify,
-  injectedSync,
-  injectedRunCodeReview,
-  injectedGh,
-  injectedGitSpawn,
-  injectedReleaseLease,
-  injectedGraphqlProbe,
-}) {
-  const startedAtMs = Date.now();
-  const config = injectedConfig || resolveConfig({ cwd: options.cwd });
-  const provider = injectedProvider || createProvider(config);
-  const storyBranch = getStoryBranch(options.storyId);
-
-  progress('INIT', `Closing standalone Story #${options.storyId}...`);
-  const story = await provider.getTicket(options.storyId);
-  if (story.state === 'closed') {
-    return await alreadyClosedResult(
-      options.storyId,
-      story.stateReason,
-      config,
-    );
-  }
-
-  const leaseArgs = {
-    provider,
-    storyId: options.storyId,
-    config,
-    injectedReleaseLease,
-  };
+async function loadStoryPhase(ctx, deps) {
+  progress('INIT', `Closing standalone Story #${ctx.storyId}...`);
+  ctx.story = await deps.provider.getTicket(ctx.storyId);
+  if (ctx.story.state !== 'closed') return null;
+  return await alreadyClosedResult(
+    ctx.storyId,
+    ctx.story.stateReason,
+    deps.config,
+    ctx.workerTokens,
+  );
+}
 
-  // `gh pr` needs GraphQL; one cheap read here beats the gate chain plus a push.
+/** One cheap GraphQL read here beats the gate chain plus a push. */
+async function graphqlPreflightPhase(ctx, deps) {
   const preflight = await runGraphqlPreflight({
-    storyId: options.storyId,
-    provider,
+    storyId: ctx.storyId,
+    provider: deps.provider,
     progress,
-    ghFacade: injectedGh,
-    probe: injectedGraphqlProbe,
+    ghFacade: deps.gh,
+    probe: deps.graphqlProbe,
   });
-  if (preflight) {
-    await releaseLease(leaseArgs);
-    return await preflightBlockedResult({
-      storyId: options.storyId,
-      preflight,
-      config,
-      startedAtMs,
-    });
-  }
+  if (!preflight) return null;
+  await releaseLease(ctx, deps);
+  return await preflightBlockedResult({
+    storyId: ctx.storyId,
+    preflight,
+    config: deps.config,
+    startedAtMs: ctx.startedAtMs,
+    workerTokens: ctx.workerTokens,
+  });
+}
 
-  // The base the run was SEEDED from (init receipt); throws before any merge
-  // when it disagrees with current config.
-  const { values: runScoped, confirmed: baseConfirmed } =
-    await resolveRunScopedConfig({
-      storyId: options.storyId,
-      config,
-      progress,
-    });
-  const baseBranch = runScoped.baseBranch;
+/**
+ * The base the run was SEEDED from (init receipt); throws before any merge
+ * when it disagrees with current config.
+ */
+async function resolveBasePhase(ctx, deps) {
+  const { values, confirmed } = await resolveRunScopedConfig({
+    storyId: ctx.storyId,
+    config: deps.config,
+    progress,
+  });
+  ctx.baseBranch = values.baseBranch;
+  ctx.baseConfirmed = confirmed;
+  ctx.worktreePath = resolveWorktreePath({
+    cwd: ctx.options.cwd,
+    config: deps.config,
+    storyId: ctx.storyId,
+  });
+  return null;
+}
 
-  const worktreePath = resolveWorktreePath({
-    cwd: options.cwd,
-    config,
-    storyId: options.storyId,
+async function prePushPhase(ctx, deps) {
+  ctx.prePush = await releaseLeaseOnBlock(
+    () => runPrePushPhases(ctx, deps),
+    ctx,
+    deps,
+  );
+  if (!ctx.prePush.pending) return null;
+  return await finishDeferred(ctx.prePush.lockWait, {
+    storyId: ctx.storyId,
+    storyBranch: ctx.storyBranch,
+    baseBranch: ctx.baseBranch,
+    config: deps.config,
+    startedAtMs: ctx.startedAtMs,
+    phaseTimer: ctx.phaseTimer,
+    workerTokens: ctx.workerTokens,
   });
-  const prePush = await releaseLeaseOnBlock(
-    () =>
-      runPrePushPhases({
-        ...options,
-        config,
-        baseBranch,
-        baseConfirmed,
-        storyBranch,
-        provider,
-        worktreePath,
-        injectedSync,
-        injectedGitSpawn,
-        setPhase,
-        setObservedGates,
-      }),
-    leaseArgs,
+}
+
+async function openPrPhase(ctx, deps) {
+  ctx.pr = await releaseLeaseOnBlock(
+    () => openAndReviewPr(ctx, deps),
+    ctx,
+    deps,
   );
-  if (prePush.pending) {
-    return await finishDeferred(prePush.lockWait, {
-      storyId: options.storyId,
-      storyBranch,
-      baseBranch,
-      config,
-      startedAtMs,
-      phaseTimer,
-    });
-  }
+  return null;
+}
 
-  const { prUrl, prNumber, alreadyMerged, reviewOverride } =
-    await releaseLeaseOnBlock(
-      () =>
-        openAndReviewPr({
-          cwd: options.cwd,
-          worktreePath,
-          story,
-          storyId: options.storyId,
-          storyBranch,
-          baseBranch,
-          provider,
-          config,
-          overrideReviewBlock: options.overrideReviewBlock,
-          injectedGh,
-          injectedRunCodeReview,
-          setPhase,
-        }),
-      leaseArgs,
-    );
-  // Reap BEFORE the arm: `gh pr merge --delete-branch` may merge at once and
-  // then fail deleting a branch a live worktree holds, reading as a failed
-  // arm. Safe — the work is pushed, and a dirty tree is still refused.
-  const worktreeReaped = await reapWorktreePhase({
-    cwd: options.cwd,
-    storyId: options.storyId,
-    worktreePath,
-    wtIsolation: config.delivery?.worktreeIsolation,
+/**
+ * Reap BEFORE the arm: `gh pr merge --delete-branch` may merge at once and
+ * then fail deleting a branch a live worktree holds, reading as a failed arm.
+ * Safe — the work is pushed, and a dirty tree is still refused.
+ */
+async function reapWorktreePhaseStep(ctx, deps) {
+  ctx.worktreeReaped = await reapWorktreePhase({
+    cwd: ctx.options.cwd,
+    storyId: ctx.storyId,
+    worktreePath: ctx.worktreePath,
+    wtIsolation: deps.config.delivery?.worktreeIsolation,
     progress,
     WorktreeManager,
   });
-  setPhase('auto-merge');
-  const ciDelivery = getCiDelivery(config);
-  const {
-    autoMergeEnabled,
-    autoMergeReason,
-    localCleanupDeferred,
-    directMerged,
-    advisoryGate,
-  } = await resolveAutoMergeOutcome({
+  return null;
+}
+
+/** No lease release here: only the post-land tail releases it. */
+async function armPhase(ctx, deps) {
+  ctx.setPhase('auto-merge');
+  const ciDelivery = getCiDelivery(deps.config);
+  const { prUrl, prNumber, alreadyMerged } = ctx.pr;
+  ctx.arm = await resolveAutoMergeOutcome({
     alreadyMerged,
-    cwd: options.cwd,
+    cwd: ctx.options.cwd,
     prNumber,
     prUrl,
-    noAutoMerge: options.noAutoMerge,
+    noAutoMerge: ctx.options.noAutoMerge,
     autoMergePolicy: ciDelivery.autoMerge,
     blockOnAdvisoryFailure: ciDelivery.blockOnAdvisoryFailure,
     advisoryAllowlist: ciDelivery.advisoryAllowlist,
-    gh: injectedGh,
+    gh: deps.gh,
     progress,
   });
   await flipLabelAndNotify({
-    provider,
-    notifyFn: injectedNotify,
-    storyId: options.storyId,
-    story,
+    provider: deps.provider,
+    notifyFn: deps.notify,
+    storyId: ctx.storyId,
+    story: ctx.story,
     prUrl,
-    autoMergeEnabled,
-    autoMergeReason,
-    config,
+    autoMergeEnabled: ctx.arm.autoMergeEnabled,
+    autoMergeReason: ctx.arm.autoMergeReason,
+    config: deps.config,
     progress,
   });
-  // No lease release here: only the post-land tail (confirmed merge) releases
-  // it; every non-merged ending keeps the claim while the PR is open.
+  return null;
+}
 
-  // Resolved now, not at parse time: it needs the config and the arm outcome
-  // (an un-armed PR rests at `agent::closing` rather than waiting).
+/** Wait-for-merge needs the arm outcome, so it is resolved here. */
+async function finishPhase(ctx, deps) {
+  const { options, arm } = ctx;
   const { waitForMerge, reason: waitForMergeReason } = resolveWaitForMerge({
     waitForMergeExplicit: options.waitForMergeExplicit,
     noWaitForMerge: options.noWaitForMerge,
-    config,
-    autoMergeReason,
+    config: deps.config,
+    autoMergeReason: arm.autoMergeReason,
   });
   reportOperatorMergeSkip({
     waitForMergeReason,
-    autoMergeReason,
-    storyId: options.storyId,
+    autoMergeReason: arm.autoMergeReason,
+    storyId: ctx.storyId,
     waitForMergeExplicit: options.waitForMergeExplicit,
   });
   const prCtx = {
-    storyId: options.storyId,
-    storyBranch,
-    baseBranch,
-    prNumber,
-    prUrl,
-    autoMergeEnabled,
-    autoMergeReason,
-    advisoryGate,
-    worktreeReaped,
-    localCleanupDeferred,
-    directMerged,
-    config,
-    startedAtMs,
-    phaseTimer,
-    lockWait: prePush.lockWait,
-    gates: closeEnvelopeGates(options, prePush.validationGates, reviewOverride),
+    storyId: ctx.storyId,
+    storyBranch: ctx.storyBranch,
+    baseBranch: ctx.baseBranch,
+    prNumber: ctx.pr.prNumber,
+    prUrl: ctx.pr.prUrl,
+    autoMergeEnabled: arm.autoMergeEnabled,
+    autoMergeReason: arm.autoMergeReason,
+    advisoryGate: arm.advisoryGate,
+    worktreeReaped: ctx.worktreeReaped,
+    localCleanupDeferred: arm.localCleanupDeferred,
+    directMerged: arm.directMerged,
+    config: deps.config,
+    startedAtMs: ctx.startedAtMs,
+    phaseTimer: ctx.phaseTimer,
+    workerTokens: ctx.workerTokens,
+    lockWait: ctx.prePush.lockWait,
+    gates: closeEnvelopeGates(
+      options,
+      ctx.prePush.validationGates,
+      ctx.pr.reviewOverride,
+    ),
   };
+  if (!waitForMerge) {
+    return await finishWithoutMergeWait(prCtx, waitForMergeReason);
+  }
+  return await finishWithMergeWait(prCtx, {
+    cwd: options.cwd,
+    provider: deps.provider,
+    maxWaitSeconds: options.maxWaitSeconds,
+    mergeWatchMode: options.mergeWatchMode,
+    rerunAdvisory: options.rerunAdvisory,
+    setPhase: ctx.setPhase,
+    injectedGh: deps.gh,
+    injectedNotify: deps.notify,
+  });
+}
 
-  if (waitForMerge) {
-    return await finishWithMergeWait(prCtx, {
-      cwd: options.cwd,
-      provider,
-      maxWaitSeconds: options.maxWaitSeconds,
-      mergeWatchMode: options.mergeWatchMode,
-      rerunAdvisory: options.rerunAdvisory,
-      setPhase,
-      injectedGh,
-      injectedNotify,
-    });
+/** Each phase extends the shared context; a non-null return ends the run. */
+const CLOSE_PIPELINE = Object.freeze([
+  loadStoryPhase,
+  graphqlPreflightPhase,
+  resolveBasePhase,
+  prePushPhase,
+  openPrPhase,
+  reapWorktreePhaseStep,
+  armPhase,
+  finishPhase,
+]);
+
+/**
+ * @param {object} run
+ * @param {object} deps
+ * @returns {Promise<{ success: boolean, result: object, terminal: object }>}
+ */
+async function runClosePipeline(run, deps) {
+  const ctx = {
+    ...run,
+    storyId: run.options.storyId,
+    storyBranch: getStoryBranch(run.options.storyId),
+    workerTokens: resolveWorkerTokens(run.options.workerTokens),
+  };
+  for (const phase of CLOSE_PIPELINE) {
+    const ending = await phase(ctx, deps);
+    if (ending) return ending;
   }
-  return await finishWithoutMergeWait(prCtx, waitForMergeReason);
 }