mandrel 2.59.0 → 2.61.0

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

@@ -30,6 +30,8 @@ import { runBaseSyncPhase } from './phases/base-sync.js';
 import { runCloseValidationPhase } from './phases/close-validation.js';
 import { parsePrNumber, runStoryScopeReview } 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';
 import { parseCloseOptions, resolveWaitForMerge } from './phases/options.js';
 import { ensurePullRequestWith } from './phases/pull-request.js';
 import { pushStoryBranch } from './phases/push.js';
@@ -41,29 +43,11 @@ import { runWrongTreeGuardPhase } from './phases/wrong-tree-guard.js';
 const progress = Logger.createProgress('single-story-close', { stderr: true });
 
 /**
- * Emit the terminal envelope on stdout alongside the legacy close result.
- *
- * Both are printed: the envelope is the contract callers parse (Story
- * #4543), while `STORY CLOSE RESULT` stays byte-compatible for the existing
- * surfaces that grep it. One writer, one place — so the envelope can never
- * be emitted from a path that forgot it.
- *
- * Story #4578 — the same one-place property is why the runtime-derived
- * friction emit hangs here: a close that ends `failed`, or parks `pending`
- * on an exhausted merge-wait budget, is friction the retro must see, and
- * routing it through the single emitter means no terminal path can forget
- * it. `emitTerminalFriction` decides what (if anything) is worth a record —
- * see `frictionForTerminal` for why `blocked` and a `--no-wait-merge`
- * `pending` are deliberately NOT flagged here.
- *
- * Async, and awaited by every caller: the CLI exits via `process.exit` the
- * moment `main` resolves, so a fire-and-forget append would be discarded.
- * The emit is best-effort internally and cannot throw.
+ * 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.
  */
 async function emitTerminal({ terminal, result, config }) {
-  // Story #4685 — the human-facing result dump goes to a temp log; the agent
-  // acts on the (separate, unsuppressible) terminal envelope emitted below.
-  // The single summary line keeps the fields worth an at-a-glance read.
   if (result) {
     emitTerseResult({
       label: 'STORY CLOSE RESULT',
@@ -83,21 +67,16 @@ async function emitTerminal({ terminal, result, config }) {
 }
 
 /**
- * Terminal for a Story that was already closed before this run started.
- *
- * `state: 'closed'` alone does NOT mean the work landed. GitHub closes an
- * issue as `completed` (the `Closes #<id>` footer firing on merge — the work
- * IS on the base branch) or as `not_planned` (superseded by a re-plan,
- * abandoned — nothing ever merged). Reporting the second as `landed` told
- * `/mandrel-deliver` that work had reached `main` when no PR ever merged, which would
- * also satisfy any dependent Story waiting on it. Fail loudly instead: being
- * handed an abandoned Story is an input error only the operator can resolve.
- *
- * A null `stateReason` keeps the `completed` reading — GitHub defaults to it,
- * and issues closed before the field existed carry null.
+ * 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) {
   if (stateReason === 'not_planned') {
+    progress(
+      'NOOP',
+      `Story #${storyId} is closed as not planned — nothing to land.`,
+    );
     const result = {
       storyId,
       standalone: true,
@@ -120,15 +99,13 @@ async function alreadyClosedResult(storyId, stateReason = null, config) {
     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',
   };
-  // Idempotent re-run against a Story closed as completed. `landed` is the
-  // honest status — the issue closed on merge, so the work is on the base
-  // branch — and there is nothing left to command.
   const terminal = buildTerminalEnvelope({
     storyId,
     status: 'landed',
@@ -141,16 +118,49 @@ async function alreadyClosedResult(storyId, stateReason = null, config) {
 }
 
 /**
- * Project the baselines entries out of close-validation's per-gate outcomes,
- * keyed by the gate's own name (Story #5172).
+ * Reuses the classifier's fallback class: the vocabulary is pinned by the
+ * terminal schema, so `reason` names the blocker instead.
+ */
+const PREFLIGHT_BLOCK_CLASS = 'api-race-other';
+
+/**
+ * Returned, not thrown: a classified block, not a crash (a throw surfaces as
+ * `failed`). The next command is the same close.
  *
- * The envelope's `gates` map used to roll the whole gate chain up into a
- * single `validation` verdict, which was fine while the baselines gate was
- * one entry and stopped being fine when it became two: a reader of a failed
- * close could not tell whether the cheap coverage-independent baselines had
- * breached or the expensive coverage-consuming ones had. Only registered
- * entries are reported — a consumer whose config registers just one of the
- * pair gets just that one, never a phantom key for a gate that never existed.
+ * @param {{ storyId: number, preflight: { verdict: string, reason: string },
+ *   config: object, startedAtMs: number }} args
+ * @returns {Promise<{ success: false, result: object, terminal: object }>}
+ */
+async function preflightBlockedResult({
+  storyId,
+  preflight,
+  config,
+  startedAtMs,
+}) {
+  const result = {
+    storyId,
+    standalone: true,
+    action: 'noop',
+    reason: `graphql-preflight-${preflight.verdict}`,
+  };
+  const terminal = buildTerminalEnvelope({
+    storyId,
+    status: 'blocked',
+    phase: 'init',
+    blocked: {
+      blockClass: PREFLIGHT_BLOCK_CLASS,
+      reason: preflight.reason,
+      frictionCommentId: null,
+    },
+    nextCommand: NEXT_COMMANDS.close(storyId),
+    elapsedSeconds: elapsedSecondsSince(startedAtMs),
+  });
+  await emitTerminal({ terminal, result, config });
+  return { success: false, result, terminal };
+}
+
+/**
+ * The split baselines gates, by name; only registered ones, never a phantom key.
  *
  * @param {Record<string, string>|null|undefined} validationGates
  * @returns {Record<string, string>}
@@ -164,6 +174,22 @@ function baselinesEnvelopeGates(validationGates) {
   return out;
 }
 
+/**
+ * @param {{ skipValidation?: boolean, skipSync?: boolean }} options
+ * @param {Record<string, string>|null} validationGates
+ * @param {object|null} reviewOverride
+ * @returns {Record<string, string>}
+ */
+function closeEnvelopeGates(options, validationGates, reviewOverride) {
+  return {
+    validation: options.skipValidation ? 'skipped' : 'passed',
+    ...baselinesEnvelopeGates(validationGates),
+    baseSync: options.skipSync ? 'skipped' : 'passed',
+    // The review did fail; the envelope records the human override.
+    codeReview: reviewOverride ? 'overridden' : 'passed',
+  };
+}
+
 function resolveWorktreePath({ cwd, config, storyId }) {
   const root = config.delivery?.worktreeIsolation?.root ?? '.worktrees';
   const candidate = path.resolve(cwd, root, `story-${storyId}`);
@@ -171,25 +197,16 @@ function resolveWorktreePath({ cwd, config, storyId }) {
 }
 
 /**
- * The pre-push phases, in the order the pipeline walks them: wrong-tree
- * guard → base-sync → close-validation.
- *
- * Story #5172 put base-sync AHEAD of close-validation, for two reasons that
- * are really one. The cheap one: a base-sync conflict is a hard block that
- * costs nothing to detect, so paying for the full gate chain before
- * discovering it burns the pipeline's most expensive minutes on a tree that
- * was never going to be pushed. The load-bearing one: with the gates last,
- * **the validated tree is the pushed tree**. Under the old order the merge
- * commit base-sync writes landed AFTER validation, so every close pushed a
- * tree no gate had ever seen.
- *
- * `--skip-sync` and `--skip-validation` stay independent — either, both or
- * neither may be set, and each still elides exactly its own phase.
+ * wrong-tree guard → base-sync → close-validation. Validation runs last so
+ * the validated tree is the pushed tree (base-sync's merge commit included),
+ * and a cheap conflict is found before the expensive gates.
  *
- * @returns {Promise<{ validationGates: Record<string, string>|null }>}
- *   The per-gate outcomes close-validation observed, or `null` when the phase
- *   was skipped. Feeds the terminal envelope's `gates` map so the split
- *   baselines entries are separable there.
+ * @returns {Promise<{
+ *   validationGates: Record<string, string>|null,
+ *   lockWait: { waitedSeconds: number, expired: boolean }|null,
+ *   pending: boolean,
+ * }>} `validationGates` is null when skipped; `pending` means a full-suite
+ *   lock wait expired and the gates deferred.
  */
 async function runPrePushPhases({
   cwd,
@@ -235,7 +252,7 @@ async function runPrePushPhases({
   }
   if (skipValidation) {
     progress('VALIDATE', '⏭ Skipped (--skip-validation).');
-    return { validationGates: null };
+    return { validationGates: null, lockWait: null, pending: false };
   }
   setPhase('close-validation');
   let validation;
@@ -252,12 +269,7 @@ async function runPrePushPhases({
       buildDefaultGates,
     });
   } catch (err) {
-    // Story #5279 — the failed terminal REPORTS gates rather than
-    // reconstructing them, so hand it what this run observed. The phase tags
-    // `closeGate` with the entry that died; that one name is the whole of
-    // what the run observed about gate outcomes, and therefore the whole of
-    // what the envelope may claim. Anything else it might have named is a
-    // gate the run never proved ran at all.
+    // The gate that died is all this run observed; the envelope claims no more.
     if (typeof err?.closeGate === 'string') {
       setObservedGates({ [err.closeGate]: 'failed' });
     }
@@ -265,7 +277,11 @@ async function runPrePushPhases({
   }
   const gates = validation?.gates ?? null;
   setObservedGates(gates);
-  return { validationGates: gates };
+  return {
+    validationGates: gates,
+    lockWait: validation?.lockWait ?? null,
+    pending: validation?.pending === true,
+  };
 }
 
 async function openAndReviewPr({
@@ -283,17 +299,14 @@ async function openAndReviewPr({
   setPhase = () => {},
 }) {
   setPhase('push');
-  // Issue #4990 — push from the Story worktree so `pre-push` measures the
-  // tree being sent. `gh` and the review's ref-based diffs below keep the
-  // caller's `cwd`: they read the shared `.git`, so they resolve identically
-  // from either tree.
+  // 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');
   const { url: prUrl, alreadyMerged } = await ensurePullRequestWith({
     cwd,
     storyId,
     storyTitle: story.title,
-    // Scanned for a declared `BREAKING CHANGE:` footer — see pull-request.js.
     storyBody: story.body,
     storyBranch,
     baseBranch,
@@ -301,10 +314,7 @@ async function openAndReviewPr({
     progress,
   });
   const prNumber = parsePrNumber(prUrl);
-  // Story #4873 — the head's PR already merged (an armed PR that landed while
-  // a previous close invocation was between phases). There is nothing left to
-  // review and nothing left to arm; the confirm phase probes the PR, observes
-  // MERGED, and lands the Story on the merge that actually happened.
+  // Already merged (landed between invocations): skip review and arm; confirm observes it.
   if (alreadyMerged) {
     return { prUrl, prNumber, alreadyMerged: true };
   }
@@ -318,19 +328,12 @@ async function openAndReviewPr({
     prNumber,
     provider,
     runCodeReviewFn: injectedRunCodeReview ?? runCodeReviewDefault,
-    // The runner owns the git seam it hands its phases (same as `gitSync` to
-    // `pushStoryBranch`). The review needs it to resolve `origin/<base>` —
-    // the ref base-sync merged from — before it will score anything
-    // (Story #5325).
     gitSpawnFn: gitSpawn,
     progress,
   });
   if (reviewOutcome.halted) {
     const criticalCount = reviewOutcome.severity?.critical ?? 0;
-    // The sanctioned override. Checked BEFORE the blocked
-    // transition so an overridden run never touches `agent::blocked`: the
-    // Story is proceeding, and parking it would make the label lie for the
-    // rest of the close.
+    // Checked before the blocked transition: an overridden Story proceeds.
     if (overrideReviewBlock) {
       const override = await handleOverriddenReviewBlock({
         provider,
@@ -390,30 +393,12 @@ async function releaseLease({
 }
 
 /**
- * Story #4257 — run a blocked-prone phase and, if it throws, release the
- * assignee-lease best-effort BEFORE re-throwing the original error.
- *
- * The two recoverable-blocked close exits (base-sync conflict in
- * `runBaseSyncPhase`, and a critical-blocker review halt in
- * `openAndReviewPr`) throw before the clean-close lease release at the
- * tail of `runSingleStoryClose`, stranding the operator's lease
- * indefinitely. The standalone lease has **no** TTL to expire by (Story
- * #5006 deleted it): `acquireLease` refuses any foreign assignee outright,
- * so a stranded claim is cleared only by `--steal` or de-assignment. That fail-closed-refuses a different operator who picks up
- * the blocked Story — exactly the hand-off case. Releasing here closes
- * that gap.
- *
- * The original throw is preserved verbatim (per
- * `rules/orchestration-error-handling.md` — throw, never `Logger.fatal`),
- * so the CLI boundary still maps it to a non-zero exit; the lease release
- * must not swallow it. `releaseLease` is itself best-effort and never
- * throws, so it cannot mask the real failure. Fail-closed re-acquire
- * semantics are preserved: `releaseStoryLease` no-ops when the operator no
- * longer holds the claim, and a self-held re-acquire on a re-run still
- * succeeds against the now-unclaimed ticket.
+ * Release the lease best-effort before re-throwing a blocked-prone phase's
+ * error verbatim. The lease has no TTL, so a stranded claim would refuse the
+ * next operator who picks up the blocked Story.
  *
  * @template T
- * @param {() => Promise<T>} run The blocked-prone phase to execute.
+ * @param {() => Promise<T>} run
  * @param {{ provider: object, storyId: number, config: object, injectedReleaseLease?: Function }} leaseArgs
  * @returns {Promise<T>}
  */
@@ -427,25 +412,8 @@ async function releaseLeaseOnBlock(run, leaseArgs) {
 }
 
 /**
- * Did this run OBSERVE the PR merge? (Story #5279)
- *
- * `merged` used to be whatever the caller happened to pass, and the two
- * finishers passed different halves of the truth. Three observations say a
- * merge happened, and each of them reported `merged: false` on at least one
- * path:
- *
- *   - the confirm phase watched it land (`waitOutcome.confirmed`);
- *   - it landed and only the `agent::done` label write failed
- *     (`merged-flip-failed`) — the terminal envelope for that same run
- *     already reports `pr.state: MERGED` from the probe, so a result denying
- *     the merge made the two halves of one run contradict each other;
- *   - the arm phase direct-squash-merged it synchronously because the
- *     repository has no native auto-merge (`directMerged`), which the
- *     no-wait finisher never consulted at all.
- *
- * Deliberately observation-only: it reads what the run saw, never what the
- * run intended. A `null`/absent `waitOutcome` is the no-wait finisher, whose
- * sole observation is the direct merge.
+ * Did this run OBSERVE the merge — confirmed, merged-but-flip-failed, or
+ * direct-merged? Observation only, never intent.
  *
  * @param {{ waitOutcome?: object|null, directMerged?: boolean }} args
  * @returns {boolean}
@@ -486,25 +454,13 @@ function closeResult({
     autoMergeReason,
     worktreeReaped,
     leaseReleased,
-    // Story #4681 — `gh`'s local head-branch delete failed while the remote
-    // merge/arm stood. Surfaced so the land is auditable as
-    // merged-with-deferred-cleanup rather than silently degraded.
+    // `gh`'s local branch delete failed while the remote merge/arm stood.
     localCleanupDeferred,
-    // Story #4682 — native auto-merge was unavailable (no branch protection /
-    // an already-clean PR), so the PR was landed by a direct squash-merge.
-    // Surfaced so a checks-less land is auditable rather than looking like a
-    // queued auto-merge that never fired.
+    // No native auto-merge, so the arm squash-merged directly.
     directMerged,
     waitedForMerge,
     merged,
-    // Story #5266 — derived from `merged` / `directMerged` / `autoMergeEnabled`,
-    // never from `waitedForMerge`. A wait that expired unmerged used to write
-    // "PR merge confirmed" beside `merged: false`, and this log is what the
-    // operator reads first. See close-note.js for the invariant.
-    // Story #5279 — `landCompleted` keeps that invariant intact now that
-    // `merged: true` no longer implies the flip and the tail ran: a direct
-    // merge under `--no-wait-merge`, and a `merged-flip-failed` block, are
-    // both merged WITHOUT a completed land.
+    // Never from `waitedForMerge`; `merged` can be true without a completed land.
     note: deriveCloseNote({
       merged,
       directMerged,
@@ -534,6 +490,7 @@ export async function runSingleStoryClose({
   injectedGh,
   injectedGitSpawn,
   injectedReleaseLease,
+  injectedGraphqlProbe,
 } = {}) {
   const options = parseCloseOptions({
     storyIdParam,
@@ -554,18 +511,10 @@ export async function runSingleStoryClose({
     );
   }
 
-  // Story #4543 — track the phase so a crash is attributable. The runner
-  // deliberately keeps THROWING (the library contract every caller and test
-  // relies on: a failed gate must not look like a return value); it only tags
-  // the error with the phase it died in, and the CLI boundary turns that into
-  // the `failed` terminal envelope. Tagging rather than swallowing is what
-  // lets `failed` name its phase without inventing a second success path.
+  // The runner keeps THROWING; it only tags the error with its phase and the
+  // gates it observed (null until validation reports), and the CLI boundary
+  // builds the `failed` envelope from those tags.
   let phase = 'init';
-  // Story #5279 — the per-gate outcomes this run OBSERVED, tagged onto a
-  // throwing error alongside the phase so `failedTerminalFor` reports gates
-  // instead of reconstructing which ones "must have" run. Stays null until
-  // close-validation reports, so a run that died before it claims no gates at
-  // all rather than inventing names for gates that were never registered.
   let observedGates = null;
   const setPhase = (next) => {
     phase = next;
@@ -586,6 +535,7 @@ export async function runSingleStoryClose({
       injectedGh,
       injectedGitSpawn,
       injectedReleaseLease,
+      injectedGraphqlProbe,
     });
   } catch (err) {
     if (err && typeof err === 'object') {
@@ -597,10 +547,7 @@ export async function runSingleStoryClose({
 }
 
 /**
- * Resolve the arm outcome. An already-merged head PR (Story #4873) has nothing
- * to arm — `gh pr merge` against it fails, which would report the arm as a
- * fault and block a Story whose work is already on the base branch. Skip the
- * arm and let the confirm phase observe the merge that happened.
+ * An already-merged PR skips the arm (`gh pr merge` would fail and block it).
  *
  * @param {object} args
  * @returns {Promise<{ autoMergeEnabled: boolean, autoMergeReason: string|null,
@@ -620,10 +567,6 @@ async function resolveAutoMergeOutcome({ alreadyMerged, ...phaseArgs }) {
 }
 
 /**
- * Report the merge-wait terminal on the progress channel. Three endings, each
- * with its own operator-facing shape — `landed` is done, `pending` is
- * resumable and NOT a failure, anything else is a block naming its class.
- *
  * @param {{ status: string, nextCommand: string, blocked?: {blockClass?: string} }} terminal
  * @param {{ storyId: number, prUrl: string|null }} ctx
  * @returns {void}
@@ -634,9 +577,7 @@ function reportWaitTerminal(terminal, { storyId, prUrl }) {
     return;
   }
   if (terminal.status === 'pending') {
-    // NOT a failure and NOT a block — the wait reached the edge of its
-    // host slot with the PR healthy and in flight. The CLI maps this to
-    // its own exit code so a caller can resume without classifying.
+    // Not a failure: resumable, with its own CLI exit code.
     progress(
       'PENDING',
       `⏸  Story #${storyId}: PR ${prUrl} still in flight — resume with: ${terminal.nextCommand}`,
@@ -652,11 +593,8 @@ function reportWaitTerminal(terminal, { storyId, prUrl }) {
 }
 
 /**
- * The close-and-land ending (Story #4428): poll the just-armed PR to merge
- * confirmation and emit the terminal the outcome names.
- *
- * @param {object} prCtx  The shared PR/gate context built by the pipeline.
- * @param {object} deps   Runtime seams the confirm phase needs.
+ * @param {object} prCtx
+ * @param {object} deps
  * @returns {Promise<{ success: boolean, result: object, terminal: object }>}
  */
 async function finishWithMergeWait(prCtx, deps) {
@@ -689,6 +627,7 @@ async function finishWithMergeWait(prCtx, deps) {
     prUrl: prCtx.prUrl,
     autoMergeEnabled: prCtx.autoMergeEnabled,
     gates: prCtx.gates,
+    lockWait: prCtx.lockWait,
     elapsedSeconds: elapsedSecondsSince(prCtx.startedAtMs),
   });
   const result = closeResult({
@@ -700,22 +639,15 @@ async function finishWithMergeWait(prCtx, deps) {
     autoMergeEnabled: prCtx.autoMergeEnabled,
     autoMergeReason: prCtx.autoMergeReason,
     worktreeReaped: prCtx.worktreeReaped,
-    // Story #4860 — the release is a post-land tail step now, so the tail's
-    // own per-step boolean IS the answer. A wait that ended anything other
-    // than landed never ran the tail, and correctly reports `false`: the
-    // claim is still held, by design.
+    // Released by the post-land tail only; any other ending keeps the claim.
     leaseReleased: waitOutcome.tail?.leaseRelease === true,
     localCleanupDeferred: prCtx.localCleanupDeferred,
     directMerged: prCtx.directMerged,
     waitedForMerge: true,
-    // Story #5279 — `confirmed` alone denied the merge behind a
-    // `merged-flip-failed` block, whose own envelope (above) reports
-    // `pr.state: MERGED` off the probe.
     merged: deriveObservedMerge({
       waitOutcome,
       directMerged: prCtx.directMerged,
     }),
-    // Only the confirmed ending runs the flip, the issue close and the tail.
     landCompleted: waitOutcome.confirmed === true,
   });
   await emitTerminal({ terminal, result, config: prCtx.config });
@@ -724,20 +656,14 @@ async function finishWithMergeWait(prCtx, deps) {
 }
 
 /**
- * The no-wait ending — `--no-wait-merge` / operator-merge. The PR is open and
- * a human owns the land. That is a `pending` terminal by definition: the work
- * is not done, nothing is broken, and one named command finishes it — rather
- * than a fourth status invented for this one case.
+ * The no-wait ending: a human owns the land, so it is `pending` with one
+ * command to finish it. A direct merge by the arm is still observed.
  *
  * @param {object} prCtx
  * @param {string} waitForMergeReason
  * @returns {Promise<{ success: boolean, result: object, terminal: object }>}
  */
 async function finishWithoutMergeWait(prCtx, waitForMergeReason) {
-  // Story #5279 — a repository with no native auto-merge is direct
-  // squash-merged synchronously by the arm phase, so this ending can and does
-  // hold an OBSERVED merge. It used to report `merged: false` and hard-code
-  // `pr.state: 'OPEN'` for a PR the same run had just merged.
   const merged = deriveObservedMerge({ directMerged: prCtx.directMerged });
   const result = closeResult({
     storyId: prCtx.storyId,
@@ -748,15 +674,11 @@ async function finishWithoutMergeWait(prCtx, waitForMergeReason) {
     autoMergeEnabled: prCtx.autoMergeEnabled,
     autoMergeReason: prCtx.autoMergeReason,
     worktreeReaped: prCtx.worktreeReaped,
-    // Story #4860 — this is the no-wait ending: the PR is open and a human
-    // owns the merge, so the Story stays assigned until the confirm-merge
-    // surface lands it and runs the tail.
     leaseReleased: false,
     localCleanupDeferred: prCtx.localCleanupDeferred,
     directMerged: prCtx.directMerged,
     merged,
-    // Whatever the merge state, this ending never flips `agent::done`, never
-    // closes the issue and never runs the tail — `nextCommand` does.
+    // The flip, issue close and tail belong to `nextCommand`.
     landCompleted: false,
   });
   const terminal = buildTerminalEnvelope({
@@ -772,6 +694,7 @@ async function finishWithoutMergeWait(prCtx, waitForMergeReason) {
       autoMergeEnabled: Boolean(prCtx.autoMergeEnabled),
     },
     gates: prCtx.gates,
+    lockWait: prCtx.lockWait,
     nextCommand: NEXT_COMMANDS.confirmMerge(prCtx.storyId),
     elapsedSeconds: elapsedSecondsSince(prCtx.startedAtMs),
   });
@@ -784,9 +707,25 @@ async function finishWithoutMergeWait(prCtx, waitForMergeReason) {
 }
 
 /**
- * Wall-clock seconds since the close started, rounded — the terminal
- * envelope's `elapsedSeconds`.
+ * A full-suite lock wait expired: `pending`, nothing pushed.
  *
+ * @param {{ waitedSeconds: number, expired: boolean }|null} lockWait
+ * @param {{ storyId: number, storyBranch: string, baseBranch: string,
+ *   config: object, startedAtMs: number }} ctx
+ * @returns {Promise<{ success: false, result: object, terminal: object }>}
+ */
+async function finishDeferred(lockWait, { config, startedAtMs, ...ids }) {
+  const { result, terminal, note } = lockWaitPending({
+    ...ids,
+    lockWait,
+    elapsedSeconds: elapsedSecondsSince(startedAtMs),
+  });
+  await emitTerminal({ terminal, result, config });
+  progress('PENDING', note);
+  return { success: false, result, terminal };
+}
+
+/**
  * @param {number} startedAtMs
  * @returns {number}
  */
@@ -795,10 +734,6 @@ function elapsedSecondsSince(startedAtMs) {
 }
 
 /**
- * Announce the operator-merge skip: the PR was deliberately left un-armed, so
- * nothing here can land it and the Story rests at `agent::closing`. No-op on
- * every other wait reason.
- *
  * @param {{ waitForMergeReason: string, autoMergeReason: string|null,
  *   storyId: number, waitForMergeExplicit?: boolean }} args
  * @returns {void}
@@ -820,11 +755,6 @@ function reportOperatorMergeSkip({
   );
 }
 
-/**
- * The close pipeline proper. Split out of `runSingleStoryClose` so the
- * phase-tagging wrapper above stays a thin, obviously-correct boundary rather
- * than a try block wrapped around a hundred lines of pipeline.
- */
 async function runClosePipeline({
   options,
   setPhase,
@@ -837,6 +767,7 @@ async function runClosePipeline({
   injectedGh,
   injectedGitSpawn,
   injectedReleaseLease,
+  injectedGraphqlProbe,
 }) {
   const startedAtMs = Date.now();
   const config = injectedConfig || resolveConfig({ cwd: options.cwd });
@@ -846,12 +777,6 @@ async function runClosePipeline({
   progress('INIT', `Closing standalone Story #${options.storyId}...`);
   const story = await provider.getTicket(options.storyId);
   if (story.state === 'closed') {
-    progress(
-      'NOOP',
-      story.stateReason === 'not_planned'
-        ? `Story #${options.storyId} is closed as not planned — nothing to land.`
-        : `Story #${options.storyId} is already closed. Nothing to do.`,
-    );
     return await alreadyClosedResult(
       options.storyId,
       story.stateReason,
@@ -859,16 +784,35 @@ async function runClosePipeline({
     );
   }
 
-  // Story #4891 — the base branch this run was SEEDED from, read back off the
-  // run's `story-init` receipt rather than re-resolved from a config file that
-  // may have changed during the whole implementation window. Throws (fail
-  // closed, naming both values) when the pin and current config disagree —
-  // deliberately here, before the gate chain, format-autofix and base-sync,
-  // so a wrong base is never merged into the Story branch. `baseConfirmed`
-  // gates the base-merge remediation advice further down.
+  const leaseArgs = {
+    provider,
+    storyId: options.storyId,
+    config,
+    injectedReleaseLease,
+  };
+
+  // `gh pr` needs GraphQL; one cheap read here beats the gate chain plus a push.
+  const preflight = await runGraphqlPreflight({
+    storyId: options.storyId,
+    provider,
+    progress,
+    ghFacade: injectedGh,
+    probe: injectedGraphqlProbe,
+  });
+  if (preflight) {
+    await releaseLease(leaseArgs);
+    return await preflightBlockedResult({
+      storyId: options.storyId,
+      preflight,
+      config,
+      startedAtMs,
+    });
+  }
+
+  // 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({
-      provider,
       storyId: options.storyId,
       config,
       progress,
@@ -880,17 +824,7 @@ async function runClosePipeline({
     config,
     storyId: options.storyId,
   });
-  // Story #4257 — the base-sync conflict and review-critical exits throw
-  // before the clean-close lease release at the tail of this function.
-  // Wrap both blocked-prone phases so the lease is released best-effort
-  // before the throw propagates; the original error is preserved.
-  const leaseArgs = {
-    provider,
-    storyId: options.storyId,
-    config,
-    injectedReleaseLease,
-  };
-  const { validationGates } = await releaseLeaseOnBlock(
+  const prePush = await releaseLeaseOnBlock(
     () =>
       runPrePushPhases({
         ...options,
@@ -907,6 +841,15 @@ async function runClosePipeline({
       }),
     leaseArgs,
   );
+  if (prePush.pending) {
+    return await finishDeferred(prePush.lockWait, {
+      storyId: options.storyId,
+      storyBranch,
+      baseBranch,
+      config,
+      startedAtMs,
+    });
+  }
 
   const { prUrl, prNumber, alreadyMerged, reviewOverride } =
     await releaseLeaseOnBlock(
@@ -927,16 +870,9 @@ async function runClosePipeline({
         }),
       leaseArgs,
     );
-  // Reap the per-Story worktree BEFORE the arm (Story #4681). Arming runs
-  // `gh pr merge --auto --squash --delete-branch`, which — against an
-  // already-mergeable PR — merges immediately and then shells out to local
-  // `git` to drop `story-<id>`. A live worktree still holding that ref makes
-  // the local delete fail, `gh` exit non-zero, and the arm read as failed,
-  // which used to strand a genuinely merged PR at `agent::blocked`.
-  // Pre-empting the hold is the ordering half of the fix (the tolerate half
-  // lives in `phases/auto-merge.js`); it is safe here because push and PR
-  // creation already made the work durable off-machine, and `isSafeToRemove`
-  // still refuses a dirty tree.
+  // 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,
@@ -960,7 +896,6 @@ async function runClosePipeline({
     prUrl,
     noAutoMerge: options.noAutoMerge,
     autoMergePolicy: ciDelivery.autoMerge,
-    // Story #5096 — the pre-arm advisory-gate refusal.
     blockOnAdvisoryFailure: ciDelivery.blockOnAdvisoryFailure,
     advisoryAllowlist: ciDelivery.advisoryAllowlist,
     gh: injectedGh,
@@ -977,30 +912,11 @@ async function runClosePipeline({
     config,
     progress,
   });
-  // Story #4860 — the clean-path lease release USED to sit here, immediately
-  // after the arm and the `agent::closing` flip. That dropped the operator's
-  // claim the moment the PR opened, so a ticket read unassigned for the whole
-  // time its PR was in flight — and forever on the operator-merge path, where
-  // nothing downstream ever re-claimed it. The release now belongs to the
-  // post-land tail, which runs only on a CONFIRMED merge and which both
-  // landing surfaces reach. Every non-merged ending below — the
-  // `merge.unlanded` block, an exhausted wait budget, `--no-wait-merge`,
-  // `--no-auto-merge` — deliberately RETAINS the claim: the PR is open and the
-  // work still has an owner. The only releases that survive here are
-  // `releaseLeaseOnBlock`'s two throwing exits above, which fire before the PR
-  // is ever armed (Story #4257's hand-off property).
+  // 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.
 
-  // Close-and-land (Story #4428; default since `delivery.routing.closeAndLand`
-  // — Story #4539): poll the just-armed PR to merge confirmation, or block
-  // explicitly with `merge.unlanded`, instead of resting at `agent::closing`.
-  // This is the DEFAULT path for attended and headless runs alike.
-  //
-  // Resolved here rather than at parse time because two inputs do not exist
-  // until now: the resolved config (whose cwd the parse produces) and the
-  // actual arm outcome. A PR the operator deliberately left un-armed
-  // (`--no-auto-merge` / `autoMerge: "strict"`) has nothing to land, so it
-  // rests at `agent::closing` for the human instead of burning the poll
-  // budget and then blocking a healthy Story.
+  // 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).
   const { waitForMerge, reason: waitForMergeReason } = resolveWaitForMerge({
     waitForMergeExplicit: options.waitForMergeExplicit,
     noWaitForMerge: options.noWaitForMerge,
@@ -1027,17 +943,8 @@ async function runClosePipeline({
     directMerged,
     config,
     startedAtMs,
-    gates: {
-      validation: options.skipValidation ? 'skipped' : 'passed',
-      // Story #5172 — the split baselines entries, named individually so a
-      // reader can tell the two apart. Absent when validation was skipped.
-      ...baselinesEnvelopeGates(validationGates),
-      baseSync: options.skipSync ? 'skipped' : 'passed',
-      // An overridden blocker reports `overridden`, never
-      // `passed`. The review DID fail; a human authorized shipping anyway, and
-      // the envelope is the machine-readable trail that says so.
-      codeReview: reviewOverride ? 'overridden' : 'passed',
-    },
+    lockWait: prePush.lockWait,
+    gates: closeEnvelopeGates(options, prePush.validationGates, reviewOverride),
   };
 
   if (waitForMerge) {