mandrel 2.61.0 → 2.62.0

package/.agents/scripts/lib/orchestration/merge-queue.js

@@ -0,0 +1,158 @@
+/**
+ * merge-queue.js — the one GraphQL seam for a merge-queue-protected base:
+ * whether the PR's base requires a queue, whether the PR sits in it, and the
+ * dequeue. Keyed on the PR node, so no owner/repo is needed.
+ */
+
+import { gh as defaultGh, describeGhFailure } from '../gh-exec.js';
+
+/** Bound on each merge-queue GraphQL call, so a wedged `gh` cannot stall close. */
+const MERGE_QUEUE_GH_TIMEOUT_MS = 30_000;
+
+const MERGE_QUEUE_STATE_QUERY =
+  'query($id: ID!) { node(id: $id) { ... on PullRequest { isMergeQueueEnabled isInMergeQueue } } }';
+
+const DEQUEUE_MUTATION =
+  'mutation($id: ID!) { dequeuePullRequest(input: { id: $id }) { mergeQueueEntry { id } } }';
+
+/** `gh` stderr when the base requires a merge queue and the arm spelling is wrong. */
+export const MERGE_QUEUE_REFUSAL = /when merge queue enabled/i;
+
+/**
+ * @param {{ stdout?: string }|string|undefined} result
+ * @returns {object|null}
+ */
+function parseGraphqlData(result) {
+  const text = typeof result === 'string' ? result : result?.stdout;
+  const parsed = JSON.parse(String(text ?? ''));
+  if (Array.isArray(parsed?.errors) && parsed.errors.length > 0) {
+    throw new Error(
+      `graphql: ${parsed.errors.map((e) => e?.message).join('; ')}`,
+    );
+  }
+  return parsed?.data ?? null;
+}
+
+/**
+ * Whether the PR's base requires a merge queue, and whether the PR sits in
+ * it now. Keyed on the PR node, so it needs no owner/repo. Never throws: any
+ * failure returns `queueRequired: null` and the caller keeps the non-queue
+ * behaviour.
+ *
+ * @param {{ prNumber?: number|string, prRef?: string, prNodeId?: string,
+ *   gh?: object, timeoutMs?: number }} args `prNodeId` skips the id lookup.
+ * @returns {Promise<{ queueRequired: boolean|null, inQueue: boolean|null,
+ *   prNodeId: string|null, error?: string }>}
+ */
+export async function readMergeQueueState({
+  prNumber,
+  prRef,
+  prNodeId,
+  gh,
+  timeoutMs = MERGE_QUEUE_GH_TIMEOUT_MS,
+}) {
+  const facade = gh ?? defaultGh;
+  let id = prNodeId ?? null;
+  try {
+    if (!id) {
+      const view = await facade.pr.view(String(prRef ?? prNumber), ['id']);
+      id = typeof view?.id === 'string' && view.id ? view.id : null;
+    }
+    if (!id) throw new Error('PR node id unavailable');
+    const data = parseGraphqlData(
+      await facade.api({
+        method: 'POST',
+        endpoint: 'graphql',
+        body: { query: MERGE_QUEUE_STATE_QUERY, variables: { id } },
+        execOpts: { timeoutMs },
+      }),
+    );
+    const node = data?.node;
+    if (typeof node?.isMergeQueueEnabled !== 'boolean') {
+      throw new Error('merge-queue fields absent from the GraphQL response');
+    }
+    return {
+      queueRequired: node.isMergeQueueEnabled,
+      inQueue: node.isInMergeQueue === true,
+      prNodeId: id,
+    };
+  } catch (err) {
+    return {
+      queueRequired: null,
+      inQueue: null,
+      prNodeId: id,
+      error: describeGhFailure(err),
+    };
+  }
+}
+
+/**
+ * Take an enqueued PR out of the merge queue. `--disable-auto` cannot: GitHub
+ * clears the auto-merge request on enqueue, so it reads as never armed.
+ *
+ * @returns {Promise<{ ok: boolean, detail: string }>}
+ */
+async function dequeuePullRequest({ prNodeId, gh }) {
+  try {
+    parseGraphqlData(
+      await (gh ?? defaultGh).api({
+        method: 'POST',
+        endpoint: 'graphql',
+        body: { query: DEQUEUE_MUTATION, variables: { id: prNodeId } },
+        execOpts: { timeoutMs: MERGE_QUEUE_GH_TIMEOUT_MS },
+      }),
+    );
+    return { ok: true, detail: 'dequeued' };
+  } catch (err) {
+    return { ok: false, detail: describeGhFailure(err) };
+  }
+}
+
+/**
+ * Arm on a merge-queue base: a bare `--auto`, and never the direct-merge
+ * fallback — a merge that bypassed the queue would defeat the protection it
+ * exists for.
+ *
+ * @returns {Promise<{ enabled: boolean, mergeQueue: true, reason?: string }>}
+ */
+export async function armForMergeQueue({ exec, prNumber, armCwd }) {
+  try {
+    const result = await exec(['pr', 'merge', String(prNumber), '--auto'], {
+      cwd: armCwd,
+    });
+    if (result.status === 0) return { enabled: true, mergeQueue: true };
+    return {
+      enabled: false,
+      mergeQueue: true,
+      reason: `merge-queue arm failed; gh-exit-${result.status}: ${(result.stderr ?? '').trim().slice(0, 200)}`,
+    };
+  } catch (err) {
+    return {
+      enabled: false,
+      mergeQueue: true,
+      reason: `gh-spawn-error: ${err?.message ?? err}`,
+    };
+  }
+}
+
+/**
+ * Disarm an enqueued PR by dequeueing it. The caller owns the still-armed
+ * warning, so both disarm paths share it.
+ *
+ * @returns {Promise<{ disarmed: boolean, alreadyUnarmed: false, detail: string }>}
+ */
+export async function disarmByDequeue({ prNodeId, ref, gh, progress }) {
+  const dequeued = await dequeuePullRequest({ prNodeId, gh });
+  if (!dequeued.ok) {
+    return {
+      disarmed: false,
+      alreadyUnarmed: false,
+      detail: `merge-queue dequeue failed: ${dequeued.detail}`.slice(0, 200),
+    };
+  }
+  progress?.(
+    'CONFIRM',
+    `🔓 PR #${ref} removed from the merge queue — the PR stays open and hand-mergeable.`,
+  );
+  return { disarmed: true, alreadyUnarmed: false, detail: 'dequeued' };
+}

package/.agents/scripts/lib/orchestration/single-story-close/phases/auto-merge.js

@@ -3,6 +3,10 @@
  * Non-fatal: a failure returns `{ enabled: false, reason }`. The arm runs from
  * the primary worktree so `--delete-branch`'s local `git checkout <base>`
  * cannot collide with a worktree holding the base.
+ *
+ * A merge-queue base is armed with a bare `--auto` instead: `gh` refuses
+ * `--delete-branch` under a queue, the queue rule picks the strategy, and the
+ * repo's `delete_branch_on_merge` owns the remote branch reap.
  */
 
 import { gh as defaultGh, describeGhFailure } from '../../../gh-exec.js';
@@ -11,6 +15,12 @@ import {
   decideAdvisoryGateBlock,
   deriveRedHeadRuns,
 } from '../../merge-poll.js';
+import {
+  armForMergeQueue,
+  disarmByDequeue,
+  MERGE_QUEUE_REFUSAL,
+  readMergeQueueState,
+} from '../../merge-queue.js';
 
 /**
  * The operator deliberately owns the merge, so close does not wait for it;
@@ -104,8 +114,9 @@ async function directMergeFallback({ exec, prNumber, armCwd, autoReason }) {
  *   gh?: ReturnType<typeof import('../../../gh-exec.js').createGh>,
  *   runner?: (args: string[], opts: object) => ({ status: number, stdout?: string, stderr?: string } | Promise<{ status: number, stdout?: string, stderr?: string }>),
  *   resolveArmCwd?: (cwd: string) => string,
- * }} opts
- * @returns {Promise<{ enabled: boolean, reason?: string, localCleanupDeferred?: boolean, directMerged?: boolean }>}
+ *   queueRequired?: boolean,
+ * }} opts `queueRequired`: the base requires a merge queue.
+ * @returns {Promise<{ enabled: boolean, reason?: string, localCleanupDeferred?: boolean, directMerged?: boolean, mergeQueue?: boolean }>}
  */
 export async function enableAutoMergeWith({
   cwd,
@@ -113,9 +124,19 @@ export async function enableAutoMergeWith({
   gh,
   runner,
   resolveArmCwd = resolveAutoMergeArmCwd,
+  queueRequired = false,
 }) {
   const exec = runner ?? makeDefaultGhAutoMergeRunner(gh ?? defaultGh);
   const armCwd = resolveArmCwd(cwd);
+  const arm = queueRequired ? armForMergeQueue : armNativeAutoMerge;
+  return arm({ exec, prNumber, armCwd });
+}
+
+/**
+ * `--auto --squash --delete-branch`, falling back to a direct squash-merge
+ * only when native auto-merge is unavailable.
+ */
+async function armNativeAutoMerge({ exec, prNumber, armCwd }) {
   try {
     const result = await exec(
       [
@@ -134,6 +155,10 @@ export async function enableAutoMergeWith({
       // The remote side stands; the land tail finishes the local ref reap.
       return { enabled: true, localCleanupDeferred: true, reason: detail };
     }
+    if (MERGE_QUEUE_REFUSAL.test(String(result.stderr ?? ''))) {
+      // The detection probe missed the queue; the refusal names it.
+      return armForMergeQueue({ exec, prNumber, armCwd });
+    }
     if (isAutoMergeUnavailable(result.stderr)) {
       return directMergeFallback({
         exec,
@@ -218,15 +243,32 @@ const NOT_ARMED = /not enabled|isn't enabled|is not set|no auto-?merge/i;
 
 /**
  * Lives here because `lifecycle-lint` confines `gh pr merge` to this module.
- * Never throws.
+ * An enqueued PR is dequeued instead. Never throws.
  *
  * @param {{ prNumber?: number|string, prRef?: string, gh?: object,
- *   progress?: (tag: string, msg: string) => void }} args `prRef` wins over
- *   `prNumber` when both are given.
+ *   progress?: (tag: string, msg: string) => void,
+ *   readMergeQueueStateFn?: typeof readMergeQueueState }} args `prRef` wins
+ *   over `prNumber` when both are given.
  * @returns {Promise<{ disarmed: boolean, alreadyUnarmed: boolean, detail: string }>}
  */
-export async function disarmAutoMerge({ prNumber, prRef, gh, progress }) {
+export async function disarmAutoMerge({
+  prNumber,
+  prRef,
+  gh,
+  progress,
+  readMergeQueueStateFn = readMergeQueueState,
+}) {
   const ref = String(prRef ?? prNumber);
+  const queue = await readMergeQueueStateFn({ prNumber, prRef, gh });
+  const outcome =
+    queue?.inQueue === true && queue.prNodeId
+      ? await disarmByDequeue({ prNodeId: queue.prNodeId, ref, gh, progress })
+      : await disableNativeAutoMerge({ ref, gh, progress });
+  warnIfStillArmed({ outcome, ref, progress });
+  return outcome;
+}
+
+async function disableNativeAutoMerge({ ref, gh, progress }) {
   try {
     await (gh ?? defaultGh).pr.merge(ref, ['--disable-auto']);
     progress?.(
@@ -235,9 +277,7 @@ export async function disarmAutoMerge({ prNumber, prRef, gh, progress }) {
     );
     return { disarmed: true, alreadyUnarmed: false, detail: 'disarmed' };
   } catch (err) {
-    const outcome = classifyDisarmFailure(describeGhFailure(err));
-    warnIfStillArmed({ outcome, ref, progress });
-    return outcome;
+    return classifyDisarmFailure(describeGhFailure(err));
   }
 }
 
@@ -307,6 +347,62 @@ async function evaluateAdvisoryGate({
   };
 }
 
+/**
+ * Report an arm that stood, naming how it will land.
+ *
+ * @returns {{ autoMergeEnabled: true, autoMergeReason: null, localCleanupDeferred: boolean, directMerged?: boolean, mergeQueue?: boolean }}
+ */
+function reportArmed({ result, prNumber, progress }) {
+  if (result.mergeQueue) {
+    progress(
+      'PR',
+      `✅ Auto-merge enabled on PR #${prNumber} (merge queue — the queue rule picks the strategy).`,
+    );
+    return {
+      autoMergeEnabled: true,
+      autoMergeReason: null,
+      localCleanupDeferred: false,
+      mergeQueue: true,
+    };
+  }
+  if (result.directMerged) {
+    progress(
+      'PR',
+      `✅ Native auto-merge unavailable on PR #${prNumber} — direct squash-merge landed it` +
+        (result.localCleanupDeferred
+          ? " (gh's LOCAL branch cleanup deferred to the land tail; the merge stands)."
+          : '.'),
+    );
+    return {
+      autoMergeEnabled: true,
+      autoMergeReason: null,
+      directMerged: true,
+      localCleanupDeferred: Boolean(result.localCleanupDeferred),
+    };
+  }
+  if (result.localCleanupDeferred) {
+    progress(
+      'PR',
+      `⚠️ Auto-merge armed on PR #${prNumber}, but gh's LOCAL branch cleanup failed ` +
+        `(${result.reason}) — deferring the local ref reap to the land tail; the merge stands.`,
+    );
+    return {
+      autoMergeEnabled: true,
+      autoMergeReason: null,
+      localCleanupDeferred: true,
+    };
+  }
+  progress(
+    'PR',
+    `✅ Auto-merge enabled on PR #${prNumber} (squash, delete-branch).`,
+  );
+  return {
+    autoMergeEnabled: true,
+    autoMergeReason: null,
+    localCleanupDeferred: false,
+  };
+}
+
 /**
  * Dispatch auto-merge enablement.
  *
@@ -319,7 +415,7 @@ async function evaluateAdvisoryGate({
  *   gh?: ReturnType<typeof import('../../../gh-exec.js').createGh>,
  *   progress: (tag: string, msg: string) => void,
  * }} args
- * @returns {Promise<{ autoMergeEnabled: boolean, autoMergeReason: string|null, localCleanupDeferred?: boolean, directMerged?: boolean }>}
+ * @returns {Promise<{ autoMergeEnabled: boolean, autoMergeReason: string|null, localCleanupDeferred?: boolean, directMerged?: boolean, mergeQueue?: boolean }>}
  *   `localCleanupDeferred`: the arm stands but the land tail owns the local
  *   ref reap. `directMerged`: landed by direct squash-merge instead.
  */
@@ -334,6 +430,7 @@ export async function runAutoMergePhase({
   gh,
   progress,
   readPrWaitProbeFn = readAdvisoryProbe,
+  readMergeQueueStateFn = readMergeQueueState,
 }) {
   if (noAutoMerge) {
     progress('PR', '⏭  Auto-merge disabled (--no-auto-merge).');
@@ -384,45 +481,14 @@ export async function runAutoMergePhase({
       },
     };
   }
-  const result = await enableAutoMergeWith({ cwd, prNumber, gh });
-  if (result.enabled) {
-    if (result.directMerged) {
-      progress(
-        'PR',
-        `✅ Native auto-merge unavailable on PR #${prNumber} — direct squash-merge landed it` +
-          (result.localCleanupDeferred
-            ? " (gh's LOCAL branch cleanup deferred to the land tail; the merge stands)."
-            : '.'),
-      );
-      return {
-        autoMergeEnabled: true,
-        autoMergeReason: null,
-        directMerged: true,
-        localCleanupDeferred: Boolean(result.localCleanupDeferred),
-      };
-    }
-    if (result.localCleanupDeferred) {
-      progress(
-        'PR',
-        `⚠️ Auto-merge armed on PR #${prNumber}, but gh's LOCAL branch cleanup failed ` +
-          `(${result.reason}) — deferring the local ref reap to the land tail; the merge stands.`,
-      );
-      return {
-        autoMergeEnabled: true,
-        autoMergeReason: null,
-        localCleanupDeferred: true,
-      };
-    }
-    progress(
-      'PR',
-      `✅ Auto-merge enabled on PR #${prNumber} (squash, delete-branch).`,
-    );
-    return {
-      autoMergeEnabled: true,
-      autoMergeReason: null,
-      localCleanupDeferred: false,
-    };
-  }
+  const queue = await readMergeQueueStateFn({ prNumber, gh });
+  const result = await enableAutoMergeWith({
+    cwd,
+    prNumber,
+    gh,
+    queueRequired: queue?.queueRequired === true,
+  });
+  if (result.enabled) return reportArmed({ result, prNumber, progress });
   progress(
     'PR',
     `⚠️ Auto-merge enablement failed (${result.reason}) — operator can merge manually.`,

package/.agents/scripts/lib/orchestration/single-story-close/phases/confirm-merge.js

@@ -49,6 +49,7 @@ import {
   readRunSummary,
   resolveAdvisoryGateVerdict,
 } from '../../merge-poll.js';
+import { readMergeQueueState } from '../../merge-queue.js';
 import { NEXT_COMMANDS } from '../../story-deliver-terminal.js';
 import {
   postStructuredComment,
@@ -117,6 +118,30 @@ function readString(value, absent = undefined) {
   return typeof value === 'string' && value ? value : absent;
 }
 
+/**
+ * `inMergeQueue` for a green open PR, the only state GitHub enqueues from;
+ * `undefined` otherwise, so the common poll pays no extra call. An enqueued
+ * PR has no auto-merge request and can read BLOCKED — neither is a disarm.
+ */
+async function readInMergeQueue({
+  view,
+  checksStatus,
+  gh,
+  ghTimeoutMs,
+  readMergeQueueStateFn,
+}) {
+  const prNodeId = readString(view?.id);
+  if (view?.state !== 'OPEN' || checksStatus !== 'success' || !prNodeId) {
+    return undefined;
+  }
+  const queue = await readMergeQueueStateFn({
+    prNodeId,
+    gh,
+    timeoutMs: ghTimeoutMs,
+  });
+  return typeof queue?.inQueue === 'boolean' ? queue.inQueue : undefined;
+}
+
 /**
  * One probe per poll iteration. A failed or timed-out read degrades to
  * `{ checksStatus: 'pending', error }` so a flaky read is never a verdict.
@@ -127,10 +152,12 @@ export async function readPrWaitProbe({
   prNumber,
   gh = defaultGh,
   ghTimeoutMs = MERGE_WAIT_GH_TIMEOUT_MS,
+  readMergeQueueStateFn = readMergeQueueState,
 }) {
   try {
     const view = await withGhTimeout(
       gh.pr.view(prNumber, [
+        'id',
         'state',
         'mergedAt',
         'createdAt',
@@ -142,13 +169,21 @@ export async function readPrWaitProbe({
       ghTimeoutMs,
       `gh pr view ${prNumber}`,
     );
+    const checksStatus = deriveChecksStatus(view?.statusCheckRollup);
     return {
       state: readString(view?.state, null),
       mergedAt: readString(view?.mergedAt, null),
       createdAt: readString(view?.createdAt, null),
       mergeStateStatus: readString(view?.mergeStateStatus),
       reviewDecision: readString(view?.reviewDecision),
-      checksStatus: deriveChecksStatus(view?.statusCheckRollup),
+      checksStatus,
+      inMergeQueue: await readInMergeQueue({
+        view,
+        checksStatus,
+        gh,
+        ghTimeoutMs,
+        readMergeQueueStateFn,
+      }),
       // Head-anchored, so superseded/pending runs don't read as red; `null`
       // when the rollup is empty (the consecutive-probe fallback owns that).
       requiredRunEvidence: deriveRequiredRunEvidence(view?.statusCheckRollup),
@@ -644,6 +679,18 @@ async function resolveAdvisoryUnlanded({
   };
 }
 
+/**
+ * An enqueued PR reads BLOCKED with every check green, which the classifier
+ * would call human-required — but the queue lands it unattended.
+ */
+function queuedExhaustionVerdict(probe, cumulativeMs) {
+  if (probe?.inMergeQueue !== true) return {};
+  return {
+    blockClassOverride: 'checks-pending-timeout',
+    reasonOverride: `PR is still in the merge queue after ${Math.round(cumulativeMs / 1000)} seconds — GitHub merges it when the queue's checks pass; a queued base may need a larger delivery.mergeWatch.maxBudgetSeconds`,
+  };
+}
+
 /** Classify, emit `merge.unlanded`, post friction, block — all best-effort. */
 async function blockOnUnlanded({
   storyId,
@@ -1126,6 +1173,7 @@ export async function runConfirmMergePhase({
             exhausted: true,
             elapsedSeconds: Math.round(cumulativeMs / 1000),
           },
+          ...queuedExhaustionVerdict(probe, cumulativeMs),
         };
       }
     }

package/docs/CHANGELOG.md

@@ -15,6 +15,13 @@ All notable changes to this project will be documented in this file.
 -->
 <!-- markdownlint-disable-file MD004 MD012 MD037 -->
 
+## [2.62.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.61.0...mandrel-v2.62.0) (2026-09-18)
+
+
+### Fixed
+
+* **close:** arm auto-merge on a merge-queue-protected base ([#5395](https://github.com/dsj1984/mandrel/issues/5395)) ([#5396](https://github.com/dsj1984/mandrel/issues/5396)) ([6d739ea](https://github.com/dsj1984/mandrel/commit/6d739eadb8ae00bedeb7279b1a765c3e0cc5791e))
+
 ## [2.61.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.60.0...mandrel-v2.61.0) (2026-09-18)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mandrel",
-  "version": "2.61.0",
+  "version": "2.62.0",
   "description": "Claude Code-first opinionated workflow framework: instructions, skills, rules, and SDLC workflows that govern AI coding assistants.",
   "files": [
     ".agents/",