mandrel 2.61.0 → 2.63.0

package/.agents/scripts/lib/baselines/merge-envelopes.js

@@ -1,11 +1,10 @@
 /**
  * Pure 3-way merge of baseline envelopes by row identity. A line-based git
- * merge either conflicts on disjoint work (the `generatedAt` line) or splices
- * both sides into a row set no scorer produced.
+ * merge conflicts on disjoint rows that sit adjacent in sort order, and can
+ * splice both sides into a row set no scorer produced.
  *
  * Per identity the side that differs from base wins; both differing is a
- * conflict; absence is a value. The rollup is always recomputed from the
- * merged rows, never merged. Identity comes from the kind's `rowIdentity`,
+ * conflict; absence is a value. Identity comes from the kind's `rowIdentity`,
  * never `keyField`. No I/O: the driver validates the result.
  *
  * @module lib/baselines/merge-envelopes
@@ -15,8 +14,8 @@ import { deepEqual } from '../json-utils.js';
 import { KNOWN_KINDS } from './envelope.js';
 import { getKindModule } from './kernel.js';
 
-/** Keys not merged 3-way: rows by identity, rollup derived, stamp = later. */
-const DERIVED_KEYS = Object.freeze(['rows', 'rollup', 'generatedAt']);
+/** Merged by identity, not as a stamp. */
+const ROW_KEY = 'rows';
 
 /**
  * Kind from `$schema`, or `null` for anything not a known per-kind envelope.
@@ -76,20 +75,6 @@ function indexRows(rows, rowIdentity, side) {
   return out;
 }
 
-/**
- * @param {string|undefined} ours
- * @param {string|undefined} theirs
- * @returns {string|undefined}
- */
-function laterStamp(ours, theirs) {
-  if (typeof ours !== 'string') return theirs;
-  if (typeof theirs !== 'string') return ours;
-  const a = Date.parse(ours);
-  const b = Date.parse(theirs);
-  if (Number.isNaN(a) || Number.isNaN(b)) return ours > theirs ? ours : theirs;
-  return a >= b ? ours : theirs;
-}
-
 /**
  * 3-way merge of envelope stamps; a double bump to different values is a
  * real conflict (two scorers).
@@ -102,7 +87,7 @@ function laterStamp(ours, theirs) {
 function mergeStamps(base, ours, theirs) {
   const keys = new Set(
     [...Object.keys(ours), ...Object.keys(theirs), ...Object.keys(base)].filter(
-      (k) => !DERIVED_KEYS.includes(k),
+      (k) => k !== ROW_KEY,
     ),
   );
   const merged = {};
@@ -170,15 +155,13 @@ function mergeRowSets({ baseEnv, ours, theirs, rowIdentity }) {
 }
 
 /**
- * `base` is `null` when the file was added on both sides. `components`
- * defaults to `[]`, matching what a refresh writes.
+ * `base` is `null` when the file was added on both sides.
  *
  * @param {{
  *   base: object|null,
  *   ours: object,
  *   theirs: object,
  *   kind?: string,
- *   components?: Array<object>,
  * }} params
  * @returns {{
  *   kind: string,
@@ -186,13 +169,7 @@ function mergeRowSets({ baseEnv, ours, theirs, rowIdentity }) {
  *   conflicts: Array<{scope: string, identity: string, base?: unknown, ours?: unknown, theirs?: unknown}>,
  * }}
  */
-export function mergeEnvelopes({
-  base,
-  ours,
-  theirs,
-  kind,
-  components = [],
-} = {}) {
+export function mergeEnvelopes({ base, ours, theirs, kind } = {}) {
   const resolvedKind =
     kind ?? kindFromEnvelope(ours) ?? kindFromEnvelope(theirs);
   if (!resolvedKind) {
@@ -217,12 +194,7 @@ export function mergeEnvelopes({
     theirs ?? {},
   );
 
-  const envelope = {
-    ...stamps,
-    generatedAt: laterStamp(ours?.generatedAt, theirs?.generatedAt),
-    rollup: mod.rollup(sortedRows, components),
-    rows: sortedRows,
-  };
+  const envelope = { ...stamps, rows: sortedRows };
 
   return {
     kind: resolvedKind,
@@ -251,41 +223,15 @@ function orderKeys(obj, order) {
 }
 
 /**
- * Same arithmetic as `buildCyclomaticEnvelope`. Must be derived: two branches
- * each adding a row both write `n + 1`, which a 3-way merge resolves cleanly
- * and wrongly.
- *
- * @param {Array<object>} rows
- * @returns {{ '*': { filesAboveCeiling: number, methodsAboveCeiling: number, maxCyclomatic: number } }}
- */
-function cyclomaticRollup(rows) {
-  let methods = 0;
-  let max = 0;
-  for (const row of rows) {
-    methods += Number(row?.methodsAboveCeiling ?? 0);
-    const rowMax = Number(row?.maxCyclomatic ?? 0);
-    if (rowMax > max) max = rowMax;
-  }
-  return {
-    '*': {
-      filesAboveCeiling: rows.length,
-      methodsAboveCeiling: methods,
-      maxCyclomatic: max,
-    },
-  };
-}
-
-/**
- * Row-set baselines that are not per-kind envelopes. `rollup: null` is real:
- * the dead-export generator writes none. `keyOrder` mirrors each generator.
+ * Row-set baselines that are not per-kind envelopes. `keyOrder` mirrors each
+ * generator.
  */
 const PLAIN_BASELINE_KINDS = Object.freeze({
   cyclomatic: Object.freeze({
     rowIdentity: (row) => String(row?.file ?? ''),
     sortRows: (rows) =>
       [...rows].sort((a, b) => String(a.file).localeCompare(String(b.file))),
-    rollup: cyclomaticRollup,
-    keyOrder: ['$schema', 'generatedAt', 'ceiling', 'rollup', 'rows'],
+    keyOrder: ['$schema', 'ceiling', 'rows'],
   }),
   'dead-exports': Object.freeze({
     rowIdentity: (row) => `${row?.file ?? ''}::${row?.symbol ?? ''}`,
@@ -295,8 +241,7 @@ const PLAIN_BASELINE_KINDS = Object.freeze({
           String(a.file).localeCompare(String(b.file)) ||
           String(a.symbol).localeCompare(String(b.symbol)),
       ),
-    rollup: null,
-    keyOrder: ['$schema', 'kernelVersion', 'generatedAt', 'mode', 'rows'],
+    keyOrder: ['$schema', 'kernelVersion', 'mode', 'rows'],
   }),
 });
 
@@ -357,15 +302,7 @@ export function mergePlainBaseline({ base, ours, theirs, kind } = {}) {
     ours ?? {},
     theirs ?? {},
   );
-  const envelope = orderKeys(
-    {
-      ...stamps,
-      generatedAt: laterStamp(ours?.generatedAt, theirs?.generatedAt),
-      ...(spec.rollup ? { rollup: spec.rollup(sortedRows) } : {}),
-      rows: sortedRows,
-    },
-    spec.keyOrder,
-  );
+  const envelope = orderKeys({ ...stamps, rows: sortedRows }, spec.keyOrder);
   return {
     kind: resolvedKind,
     envelope,
@@ -380,8 +317,8 @@ const REGENERATE_COMMANDS = Object.freeze({
 });
 
 /**
- * After a conflicted merge, hand-resolving rows never updates the rollup, so
- * the driver must name the regeneration command.
+ * After a conflicted merge, hand-resolved rows describe a tree nobody scored,
+ * so the driver must name the regeneration command.
  *
  * @param {string} kind
  * @returns {string}

package/.agents/scripts/lib/baselines/reader.js

@@ -130,21 +130,21 @@ function validate(kind, parsed, sourceHint) {
 /**
  * The one narrowing projection for every loaded envelope. It is an
  * allow-list: compat axes read stamps off the loaded object and fail closed
- * on `undefined`, so every envelope stamp must be carried through here.
+ * on `undefined`, so every envelope stamp must be carried through here. The
+ * committed file carries no rollup; a consumer that needs one derives it from
+ * `rows` through the kind module.
  *
  * @param {string} kind
  * @param {object} parsed A validated baseline envelope.
- * @returns {{ rollup: object, rows: Array<object>, kernelVersion: string, generatedAt: string }}
+ * @returns {{ rows: Array<object>, kernelVersion: string }}
  */
 function shapeEnvelope(kind, parsed) {
   const rows = Array.isArray(parsed.rows)
     ? parsed.rows.map((row) => canonicaliseRow(kind, row))
     : [];
   return {
-    rollup: parsed.rollup ?? { '*': {} },
     rows,
     kernelVersion: parsed.kernelVersion,
-    generatedAt: parsed.generatedAt,
     scoringSemantics: parsed.scoringSemantics,
     tsTranspilerVersion: parsed.tsTranspilerVersion,
     provenanceStamped: parsed.provenanceStamped,
@@ -154,7 +154,7 @@ function shapeEnvelope(kind, parsed) {
 /**
  * @param {string} kind
  * @param {string} absolutePath
- * @returns {{ rollup: object, rows: Array<object>, kernelVersion: string, generatedAt: string }}
+ * @returns {{ rows: Array<object>, kernelVersion: string }}
  */
 function readAndShape(kind, absolutePath) {
   let raw;
@@ -195,7 +195,7 @@ function inferKindFromSchema(schemaValue) {
 /**
  * @param {string} kind
  * @param {{ configPath?: string, cwd?: string }} [opts]
- * @returns {{ rollup: object, rows: Array<object>, kernelVersion: string, generatedAt: string }}
+ * @returns {{ rows: Array<object>, kernelVersion: string }}
  */
 export function load(kind, opts = {}) {
   if (!Object.hasOwn(KIND_TO_SCHEMA_FILE, kind)) {
@@ -214,7 +214,7 @@ export function load(kind, opts = {}) {
  *
  * @param {string} absolutePath
  * @param {{ kind?: string }} [opts]
- * @returns {{ rollup: object, rows: Array<object>, kernelVersion: string, generatedAt: string }}
+ * @returns {{ rows: Array<object>, kernelVersion: string }}
  */
 export function loadFile(absolutePath, opts = {}) {
   if (typeof absolutePath !== 'string' || absolutePath.length === 0) {

package/.agents/scripts/lib/baselines/refresh-service.js

@@ -260,7 +260,6 @@ export function resolveDefaultScorer(kind, { cwd } = {}) {
  *   fs?: typeof nodeFs,
  *   gitDiff?: (args: { baseRef: string, headRef: string, cwd: string }) => Iterable<string> | Promise<Iterable<string>>,
  *   cwd?: string,
- *   generatedAt?: string,
  *   requireRowsForScopeFiles?: boolean,
  *   requiredScopeFilePredicate?: (file: string) => boolean,
  * }} opts
@@ -285,7 +284,6 @@ export async function refreshBaseline(opts = {}) {
     fs = nodeFs,
     gitDiff = defaultGitDiff,
     cwd = process.cwd(),
-    generatedAt,
     requireRowsForScopeFiles = false,
     requiredScopeFilePredicate,
   } = opts;
@@ -349,11 +347,10 @@ export async function refreshBaseline(opts = {}) {
       scope.mode === 'full'
         ? null
         : { mode: 'diff', files: new Set(scope.files) },
-    generatedAt: generatedAt ?? process.env.MANDREL_BASELINE_GENERATED_AT,
   });
 
   // The writer returns the prior object itself when nothing changed; skip the
-  // write so on-disk bytes (including `generatedAt`) stay verbatim.
+  // write so on-disk bytes stay verbatim.
   let wrote = false;
   if (priorEnvelope === null || envelope !== priorEnvelope) {
     writeEnvelopeFile(writePath, envelope, { fsImpl: fs });
@@ -523,9 +520,7 @@ function readPriorEnvelope(writePath, fs) {
       parsed &&
       typeof parsed === 'object' &&
       !Array.isArray(parsed) &&
-      Array.isArray(parsed.rows) &&
-      parsed.rollup &&
-      typeof parsed.rollup === 'object'
+      Array.isArray(parsed.rows)
     ) {
       return parsed;
     }

package/.agents/scripts/lib/baselines/writer.js

@@ -1,7 +1,6 @@
 /**
  * Shared baseline writer, the single funnel for envelope assembly
- * (`write`: project, canonical-assert, merge, stabilise, sort, rollup, stamp,
- * validate) and serialisation (`writeFile`: atomic tmp + rename).
+ * (`write`: project, canonical-assert, merge, stabilise, sort, stamp, validate) and serialisation (`writeFile`: atomic tmp + rename).
  *
  * @module lib/baselines/writer
  */
@@ -16,16 +15,14 @@ import { assertCanonical } from './path-canon.js';
 /**
  * Assemble and validate an envelope (no I/O). With `scope`, out-of-scope
  * `prior` rows are preserved first; with `epsilon`, sub-epsilon deltas then
- * resolve to prior bytes. `prior` rows must already be canonical. When rows
- * and rollup deep-equal the prior envelope, the prior is returned unchanged
- * so a no-op refresh leaves no `generatedAt` diff.
+ * resolve to prior bytes. `prior` rows must already be canonical. When the
+ * rows deep-equal the prior envelope's, the prior is returned unchanged so a
+ * no-op refresh leaves no diff.
  *
  * @param {{
  *   kind: string,
  *   rows: Array<object>,
- *   components?: Array<object>,
  *   kernelVersion?: string,
- *   generatedAt?: string,
  *   prior?: Array<object>,
  *   priorEnvelope?: object,
  *   epsilon?: number,
@@ -36,9 +33,7 @@ import { assertCanonical } from './path-canon.js';
 export function write({
   kind,
   rows,
-  components,
   kernelVersion,
-  generatedAt,
   prior,
   priorEnvelope,
   epsilon,
@@ -79,20 +74,9 @@ export function write({
   const stabilised = stabiliseRows(mod, merged, prior, epsilon);
 
   const sortedRows = mod.sortRows(stabilised);
-  const rollup = mod.rollup(sortedRows, components ?? []);
-
-  if (!Object.hasOwn(rollup, '*')) {
-    throw new Error(
-      `writer.write: ${kind} rollup is missing the required "*" key`,
-    );
-  }
 
   const priorEnv = resolvePriorEnvelope(priorEnvelope, prior);
-  if (
-    priorEnv &&
-    deepEqual(sortedRows, priorEnv.rows) &&
-    deepEqual(rollup, priorEnv.rollup)
-  ) {
+  if (priorEnv && deepEqual(sortedRows, priorEnv.rows)) {
     // No smuggling an invalid envelope through the short-circuit.
     assertEnvelope(priorEnv);
     return priorEnv;
@@ -101,9 +85,7 @@ export function write({
   const envelope = buildEnvelope({
     kind,
     rows: sortedRows,
-    rollup,
     kernelVersion: kernelVersion ?? currentKernelVersion(kind),
-    generatedAt,
     extras:
       typeof mod.envelopeExtras === 'function' ? mod.envelopeExtras() : null,
   });
@@ -113,29 +95,20 @@ export function write({
 
 /** `priorEnvelope`, else `prior` when it is a whole envelope, else null. */
 function resolvePriorEnvelope(priorEnvelope, prior) {
-  if (
-    priorEnvelope &&
-    typeof priorEnvelope === 'object' &&
-    !Array.isArray(priorEnvelope) &&
-    Array.isArray(priorEnvelope.rows) &&
-    priorEnvelope.rollup &&
-    typeof priorEnvelope.rollup === 'object'
-  ) {
-    return priorEnvelope;
-  }
-  if (
-    prior &&
-    typeof prior === 'object' &&
-    !Array.isArray(prior) &&
-    Array.isArray(prior.rows) &&
-    prior.rollup &&
-    typeof prior.rollup === 'object'
-  ) {
-    return prior;
-  }
+  if (isEnvelopeObject(priorEnvelope)) return priorEnvelope;
+  if (isEnvelopeObject(prior)) return prior;
   return null;
 }
 
+function isEnvelopeObject(value) {
+  return (
+    Boolean(value) &&
+    typeof value === 'object' &&
+    !Array.isArray(value) &&
+    Array.isArray(value.rows)
+  );
+}
+
 /**
  * Serialise deterministically (fixed top-level key order, two-space indent,
  * trailing newline) and atomically (tmp + rename).
@@ -161,11 +134,9 @@ export function writeFile(absPath, envelope, opts = {}) {
   const canonical = {
     $schema: envelope.$schema,
     kernelVersion: envelope.kernelVersion,
-    generatedAt: envelope.generatedAt,
     scoringSemantics: envelope.scoringSemantics,
     tsTranspilerVersion: envelope.tsTranspilerVersion,
     provenanceStamped: envelope.provenanceStamped,
-    rollup: envelope.rollup,
     rows: envelope.rows,
   };
 

package/.agents/scripts/lib/coverage-baseline.js

@@ -156,8 +156,6 @@ function writeEnvelopeViaFsImpl(abs, envelope, fsImpl) {
   const canonical = {
     $schema: envelope.$schema,
     kernelVersion: envelope.kernelVersion,
-    generatedAt: envelope.generatedAt,
-    rollup: envelope.rollup,
     rows: envelope.rows,
   };
   fsImpl.writeFileSync(abs, `${JSON.stringify(canonical, null, 2)}\n`);

package/.agents/scripts/lib/cyclomatic-ceiling.js

@@ -163,29 +163,17 @@ export function diffCyclomaticRows(baselineRows, currentRows) {
 }
 
 /**
- * @param {{ rows: Array<object>, ceiling: number, generatedAt?: string }} args
+ * No stamp and no rollup: both would rewrite on every refresh and conflict
+ * textually wherever the merge driver does not run.
+ *
+ * @param {{ rows: Array<object>, ceiling: number }} args
  * @returns {object}
  */
-export function buildCyclomaticEnvelope({ rows, ceiling, generatedAt }) {
-  const safeRows = rows ?? [];
-  let methods = 0;
-  let max = 0;
-  for (const row of safeRows) {
-    methods += Number(row.methodsAboveCeiling ?? 0);
-    if (Number(row.maxCyclomatic ?? 0) > max) max = Number(row.maxCyclomatic);
-  }
+export function buildCyclomaticEnvelope({ rows, ceiling }) {
   return {
     $schema: CYCLOMATIC_BASELINE_SCHEMA,
-    generatedAt: generatedAt ?? new Date().toISOString(),
     ceiling,
-    rollup: {
-      '*': {
-        filesAboveCeiling: safeRows.length,
-        methodsAboveCeiling: methods,
-        maxCyclomatic: max,
-      },
-    },
-    rows: safeRows,
+    rows: rows ?? [],
   };
 }
 

package/.agents/scripts/lib/git/sync-from-base.js

@@ -38,7 +38,7 @@ function refuseWithoutMergeDriver(cwd, gitSpawn) {
       `.gitattributes routes baselines/*.json through the mandrel-baseline merge ` +
       `driver, but ${BASELINE_MERGE_DRIVER_CONFIG_KEY} is unset in this clone. ` +
       'Merging origin now would text-merge generated baselines, which conflicts on ' +
-      'the generatedAt stamp and can splice rows neither branch scored. Register the ' +
+      'adjacent rows and can splice rows neither branch scored. Register the ' +
       `driver, then re-run:\n  ${BASELINE_MERGE_DRIVER_REMEDY}\n` +
       '  (or: npm run baselines:merge-driver)',
     remedy: BASELINE_MERGE_DRIVER_REMEDY,

package/.agents/scripts/lib/orchestration/check-baselines/phases/evaluate.js

@@ -17,34 +17,28 @@ import { applyFloors, flattenBreaches } from './floors.js';
 import { applyRefreshAcknowledgment } from './refresh-ack.js';
 
 /**
- * Recompute the `*` floor rollup without `ignoreGlobs` rows, in case a
- * baseline was poisoned by some route other than generation (which already
- * drops them); an ignored file could otherwise breach a global floor. A no-op
- * for a correct baseline; compare is untouched.
+ * The floor rollup, derived from the rows (the committed file carries none).
+ * `ignoreGlobs` rows are dropped first in case a baseline was poisoned by some
+ * route other than generation, which already drops them; an ignored file
+ * could otherwise breach a global floor.
  *
- * @param {{ kind: string, baseline: { rollup?: object, rows?: object[] }, ignoreGlobs?: string[], cwd?: string }} args
+ * @param {{ kind: string, baseline: { rows?: object[] }, ignoreGlobs?: string[], cwd?: string }} args
  * @returns {object}
  */
-function rollupExcludingIgnored({ kind, baseline, ignoreGlobs, cwd }) {
-  const rollup = baseline?.rollup;
-  if (!Array.isArray(ignoreGlobs) || ignoreGlobs.length === 0) return rollup;
-  const rows = baseline?.rows;
-  if (!Array.isArray(rows) || rows.length === 0) return rollup;
-  let mod;
-  try {
-    mod = getKindModule(kind);
-  } catch {
-    return rollup;
-  }
-  if (mod?.keyField !== 'path' || typeof mod.rollup !== 'function')
-    return rollup;
-  const kept = rows.filter((row) => {
-    const p = row?.path;
-    return typeof p !== 'string' || !isIgnoredByGlobs(p, ignoreGlobs, cwd);
-  });
-  if (kept.length === rows.length) return rollup;
-  const recomputed = mod.rollup(kept);
-  return { ...rollup, '*': recomputed?.['*'] ?? rollup?.['*'] };
+function floorRollupOf({ kind, baseline, ignoreGlobs, cwd }) {
+  const mod = getKindModule(kind);
+  const rows = Array.isArray(baseline?.rows) ? baseline.rows : [];
+  const filterIgnored =
+    mod.keyField === 'path' &&
+    Array.isArray(ignoreGlobs) &&
+    ignoreGlobs.length > 0;
+  const kept = filterIgnored
+    ? rows.filter((row) => {
+        const p = row?.path;
+        return typeof p !== 'string' || !isIgnoredByGlobs(p, ignoreGlobs, cwd);
+      })
+    : rows;
+  return mod.rollup(kept);
 }
 
 function loadHeadBaseline(kind, cwd, configPath) {
@@ -87,7 +81,6 @@ function buildGateReport({
     baseRef: cmp.baseRef ?? null,
     // Without this a compare arm that never ran looks identical to a clean run.
     baseRead: cmp.baseRead === true,
-    generatedAt: baseline.generatedAt,
     acknowledged: ack.acknowledged,
     // Acknowledgment can be partial; name which regressions it cleared.
     acknowledgedKeys: ack.acknowledgedKeys,
@@ -114,7 +107,7 @@ export async function evaluateKind({
       schemaError: { tag: 'semantics', message: semanticsError },
     };
   }
-  const floorRollup = rollupExcludingIgnored({
+  const floorRollup = floorRollupOf({
     kind,
     baseline,
     ignoreGlobs: gateBlock.ignoreGlobs,

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