mandrel 2.24.0 → 2.26.0

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

@@ -9,23 +9,27 @@
  */
 
 import path from 'node:path';
-import { parseSprintArgs } from '../../../cli-args.js';
+import { parseMergeWatchMode, parseSprintArgs } from '../../../cli-args.js';
 import { getDeliveryRouting } from '../../../config/delivery-routing.js';
 import { PROJECT_ROOT } from '../../../project-root.js';
 import { isOperatorMergeReason } from './auto-merge.js';
 
 /**
- * Resolve a flag value from an explicit override, a parsed CLI arg, or a
- * hard default.
+ * Resolve a flag value from an explicit override or a parsed CLI arg.
+ *
+ * Returns `undefined` when neither is supplied — that absence is itself the
+ * answer here, letting each caller below apply its own default (a `!!` coerce,
+ * a config lookup, or a deliberate `undefined` passed further down). The
+ * former third `defaultValue` parameter was dropped in Story #4961: no call
+ * site passed it, so it documented a mode nobody used.
  *
  * @template T
  * @param {T|undefined} paramValue
  * @param {T|undefined} parsedValue
- * @param {T} defaultValue
- * @returns {T}
+ * @returns {T|undefined}
  */
-function resolveFlag(paramValue, parsedValue, defaultValue) {
-  return paramValue ?? parsedValue ?? defaultValue;
+function resolveFlag(paramValue, parsedValue) {
+  return paramValue ?? parsedValue;
 }
 
 /**
@@ -87,8 +91,8 @@ export function resolveWaitForMerge({
  * (`waitForMergeExplicit` / `noWaitForMerge`) for the runner to resolve once
  * the config and the arm outcome exist.
  *
- * @param {{ storyIdParam, cwdParam, skipValidationParam, skipSyncParam, noAutoMergeParam, waitForMergeParam, noWaitForMergeParam, maxWaitSecondsParam }} raw
- * @returns {{ storyId, cwd, skipValidation, skipSync, noAutoMerge, waitForMergeExplicit, noWaitForMerge, maxWaitSeconds }}
+ * @param {{ storyIdParam, cwdParam, skipValidationParam, skipSyncParam, noAutoMergeParam, waitForMergeParam, noWaitForMergeParam, maxWaitSecondsParam, mergeWatchModeParam }} raw
+ * @returns {{ storyId, cwd, skipValidation, skipSync, noAutoMerge, waitForMergeExplicit, noWaitForMerge, maxWaitSeconds, mergeWatchMode }}
  */
 export function parseCloseOptions({
   storyIdParam,
@@ -99,26 +103,27 @@ export function parseCloseOptions({
   waitForMergeParam,
   noWaitForMergeParam,
   maxWaitSecondsParam,
+  mergeWatchModeParam,
 }) {
-  const parsed =
-    storyIdParam !== undefined
-      ? {
-          storyId: storyIdParam,
-          cwd: cwdParam ?? null,
-          skipValidation: !!skipValidationParam,
-          skipSync: !!skipSyncParam,
-          noAutoMerge: !!noAutoMergeParam,
-          // Preserve undefined so resolveWaitForMerge can apply the
-          // closeAndLand config default when neither flag was injected.
-          waitForMerge: waitForMergeParam,
-          noWaitForMerge: !!noWaitForMergeParam,
-          maxWaitSeconds: maxWaitSecondsParam,
-        }
-      : parseSprintArgs();
-  const waitForMergeExplicit = waitForMergeParam ?? parsed.waitForMerge;
-  const maxWaitSeconds = maxWaitSecondsParam ?? parsed.maxWaitSeconds;
+  // An injecting caller (`storyIdParam` supplied) is not reading argv at all,
+  // so there is nothing to parse and `parsed` stays empty. This used to build a
+  // stand-in object that copied every `*Param` into the slot of the same name —
+  // which is precisely what `resolveFlag` already does below, preferring the
+  // param over the parsed slot. One expression per flag now serves both
+  // callers, so a new flag is added in one place instead of two that can drift.
+  const parsed = storyIdParam === undefined ? parseSprintArgs() : {};
+  // Preserve undefined so resolveWaitForMerge can apply the closeAndLand
+  // config default when neither flag was supplied.
+  const waitForMergeExplicit = resolveFlag(
+    waitForMergeParam,
+    parsed.waitForMerge,
+  );
+  const maxWaitSeconds = resolveFlag(
+    maxWaitSecondsParam,
+    parsed.maxWaitSeconds,
+  );
   return {
-    storyId: parsed.storyId,
+    storyId: resolveFlag(storyIdParam, parsed.storyId),
     cwd: path.resolve(cwdParam ?? parsed.cwd ?? PROJECT_ROOT),
     // `undefined` when unsupplied — the merge wait then reads
     // `delivery.mergeWatch.maxWaitSeconds`. A per-run override exists so a
@@ -128,21 +133,20 @@ export function parseCloseOptions({
       Number.isInteger(maxWaitSeconds) && maxWaitSeconds > 0
         ? maxWaitSeconds
         : undefined,
-    skipValidation: resolveFlag(
-      skipValidationParam,
-      parsed.skipValidation,
-      false,
+    // `undefined` when unsupplied — the merge wait then reads
+    // `delivery.mergeWatch.mode`. The two merge-watch flags stay composable and
+    // mode-agnostic: `--merge-watch-mode async` picks the posture, and an
+    // explicit `--max-wait-seconds` still wins over that posture's probe cap.
+    mergeWatchMode: parseMergeWatchMode(
+      resolveFlag(mergeWatchModeParam, parsed.mergeWatchMode),
     ),
-    skipSync: resolveFlag(skipSyncParam, parsed.skipSync, false),
-    noAutoMerge: resolveFlag(noAutoMergeParam, parsed.noAutoMerge, false),
+    skipValidation: !!resolveFlag(skipValidationParam, parsed.skipValidation),
+    skipSync: !!resolveFlag(skipSyncParam, parsed.skipSync),
+    noAutoMerge: !!resolveFlag(noAutoMergeParam, parsed.noAutoMerge),
     waitForMergeExplicit:
       typeof waitForMergeExplicit === 'boolean'
         ? waitForMergeExplicit
         : undefined,
-    noWaitForMerge: resolveFlag(
-      noWaitForMergeParam,
-      parsed.noWaitForMerge,
-      false,
-    ),
+    noWaitForMerge: !!resolveFlag(noWaitForMergeParam, parsed.noWaitForMerge),
   };
 }

package/.agents/scripts/lib/orchestration/single-story-close/phases/pull-request.js

@@ -1,8 +1,9 @@
 /**
- * phases/pull-request.js — open or reuse the PR for a standalone Story.
+ * phases/pull-request.js — open, reuse, or decline to open the PR for a
+ * standalone Story.
  *
- * Probes for an existing open PR with `head = storyBranch`; creates one if
- * none exists. Returns the PR URL.
+ * Probes for an existing PR with `head = storyBranch`; creates one if none
+ * exists. Returns `{ url, alreadyMerged, created }`.
  *
  * `gh pr view --head` is not available on all `gh` versions, so we probe
  * with `gh pr list --head <branch>` and fall back to `gh pr create`.
@@ -13,17 +14,99 @@
  * error classification, timeout handling, and JSON parsing surface
  * instead of carrying its own `execFileSync('gh', …)` plumbing.
  *
+ * ## An already-merged PR is not an absent PR (Story #4873)
+ *
+ * The probe used to ask for `--state open` only. On the recovery path that is
+ * a false negative with teeth: a resumed close pushes the branch, the push
+ * turns the checks green, armed auto-merge lands the ORIGINAL PR server-side,
+ * and the resumed close then sees no OPEN PR on the head — so it opened a
+ * SECOND PR against a branch that is now byte-identical to base and
+ * squash-merged a zero-file commit onto `main`. Both halves of that are now
+ * closed:
+ *
+ *   1. The probe reads `--state all` and reports a MERGED PR on this head as
+ *      the outcome (`alreadyMerged: true`), so the caller lands on the merge
+ *      that already happened instead of manufacturing a new one. An OPEN PR
+ *      still wins over a merged one — a re-opened head is a live PR.
+ *   2. Creation is REFUSED outright when the head-versus-base diff contains no
+ *      files. An empty diff means there is nothing to merge, so a PR opened on
+ *      it can only ever produce an empty commit.
+ *
+ * The empty-diff guard fails **open**, not closed: `computeChangeSet` returns
+ * `files: null` when it cannot enumerate the diff at all, and absence of
+ * evidence must never block a legitimate PR — only a positively-observed empty
+ * file list refuses.
+ *
  * The function still accepts an injected `gh` facade so tests can wire
  * a fake without spawning real children.
  */
 
 import { gh as defaultGh } from '../../../gh-exec.js';
 import { Logger } from '../../../Logger.js';
+import { computeChangeSet as defaultComputeChangeSet } from '../../change-set.js';
 import { normalizePrTitle } from './normalize-pr-title.js';
 
 /**
- * Probe for an existing open PR with `head = storyBranch`; create one if
- * none exists. Returns the PR URL. Exported for testing.
+ * Pick the PR this head branch should resolve to from a `gh pr list
+ * --state all` projection. A live PR always wins; otherwise the first MERGED
+ * PR is the outcome to report. A head whose only PRs were CLOSED without
+ * merging resolves to nothing — there is a new PR to open.
+ *
+ * A row carrying a url but no recognizable `state` reads as live, not as
+ * nothing: the projection this phase asks for always includes `state`, so an
+ * absent one means an older/other `gh`, and the old `--state open` probe
+ * treated every returned row as a reusable open PR. Guessing "no PR" there is
+ * the failure mode with teeth — it opens a duplicate.
+ *
+ * Pure, and module-private on purpose: `ensurePullRequestWith` is the only
+ * caller and the only surface worth pinning, so the precedence is asserted
+ * through it rather than through a test-only export the production
+ * dead-export ratchet would then flag.
+ *
+ * @param {Array<{url?: string, state?: string, mergedAt?: string}>} rows
+ * @returns {{ url: string, state: 'OPEN'|'MERGED' }|null}
+ */
+function pickHeadPullRequest(rows) {
+  if (!Array.isArray(rows)) return null;
+  let merged = null;
+  for (const row of rows) {
+    const url = String(row?.url ?? '').trim();
+    if (!url) continue;
+    const state = String(row?.state ?? '').toUpperCase();
+    if (state === 'MERGED' || (state !== 'OPEN' && row?.mergedAt)) {
+      merged ??= { url, state: 'MERGED' };
+      continue;
+    }
+    if (state === 'CLOSED') continue;
+    return { url, state: 'OPEN' };
+  }
+  return merged;
+}
+
+/**
+ * Enumerate the head-versus-base diff and report whether it is positively
+ * empty. `null` (diff unenumerable) is NOT empty — see the module header.
+ *
+ * The diff is taken against `origin/<baseBranch>` when that ref resolves,
+ * because the local base ref can trail the remote by exactly the merge that
+ * makes this diff empty — the very state the guard exists to catch. It falls
+ * back to the local ref, and finally to "unknown", when the remote ref cannot
+ * be enumerated.
+ *
+ * @returns {{ empty: boolean, baseRef: string|null }}
+ */
+function probeEmptyDiff({ cwd, baseBranch, storyBranch, computeChangeSet }) {
+  for (const baseRef of [`origin/${baseBranch}`, baseBranch]) {
+    const set = computeChangeSet({ baseRef, headRef: storyBranch, cwd });
+    if (!set.enumerated) continue;
+    return { empty: (set.files ?? []).length === 0, baseRef };
+  }
+  return { empty: false, baseRef: null };
+}
+
+/**
+ * Probe for an existing PR with `head = storyBranch`; create one if none
+ * exists. Exported for testing.
  *
  * @param {{
  *   cwd: string,
@@ -32,9 +115,10 @@ import { normalizePrTitle } from './normalize-pr-title.js';
  *   storyBranch: string,
  *   baseBranch: string,
  *   gh?: ReturnType<typeof import('../../../gh-exec.js').createGh>,
+ *   computeChangeSetFn?: typeof defaultComputeChangeSet,
  *   progress?: (tag: string, msg: string) => void,
  * }} args
- * @returns {Promise<string>}
+ * @returns {Promise<{ url: string, alreadyMerged: boolean, created: boolean }>}
  */
 export async function ensurePullRequestWith({
   cwd: _cwd,
@@ -43,6 +127,7 @@ export async function ensurePullRequestWith({
   storyBranch,
   baseBranch,
   gh = defaultGh,
+  computeChangeSetFn = defaultComputeChangeSet,
   progress = () => {},
 }) {
   // `cwd` is preserved on the call signature for backwards compatibility
@@ -51,22 +136,26 @@ export async function ensurePullRequestWith({
   // before invoking the phase, so the effective cwd matches the legacy
   // `execFileSync('gh', …, { cwd })` shape.
   try {
-    // `gh pr list --head <branch> --state open --json url` returns a
-    // JSON array of `{ url }` rows; an empty array means no open PR on
-    // this head. We pick the first entry's URL (matching the legacy
-    // `-q '.[0].url // empty'` projection on our side) so the typed
-    // `gh.pr.list` facade can stay generic.
+    // `gh pr list --head <branch> --state all --json url,state,mergedAt`
+    // returns a JSON array of rows; an empty array means this head has never
+    // had a PR. `--state all` (not `open`) is load-bearing — see the module
+    // header's duplicate-empty-PR note.
     const rows = await gh.pr.list(
-      ['--head', storyBranch, '--state', 'open'],
-      ['url'],
+      ['--head', storyBranch, '--state', 'all'],
+      ['url', 'state', 'mergedAt'],
     );
-    const existing =
-      Array.isArray(rows) && rows.length > 0
-        ? String(rows[0]?.url ?? '').trim()
-        : '';
-    if (existing) {
-      progress('PR', `Reusing existing PR: ${existing}`);
-      return existing;
+    const existing = pickHeadPullRequest(rows);
+    if (existing?.state === 'OPEN') {
+      progress('PR', `Reusing existing PR: ${existing.url}`);
+      return { url: existing.url, alreadyMerged: false, created: false };
+    }
+    if (existing?.state === 'MERGED') {
+      progress(
+        'PR',
+        `✅ PR for ${storyBranch} is already MERGED: ${existing.url} — ` +
+          'reporting that outcome instead of opening a second PR.',
+      );
+      return { url: existing.url, alreadyMerged: true, created: false };
     }
   } catch (err) {
     // `gh pr list` failure is recoverable — fall through to create. Log
@@ -76,6 +165,25 @@ export async function ensurePullRequestWith({
     );
   }
 
+  // Nothing to merge → nothing to open. Refused before `gh pr create` so the
+  // failure names the empty diff rather than surfacing later as a zero-file
+  // squash commit on the base branch.
+  const emptyDiff = probeEmptyDiff({
+    cwd: _cwd ?? process.cwd(),
+    baseBranch,
+    storyBranch,
+    computeChangeSet: computeChangeSetFn,
+  });
+  if (emptyDiff.empty) {
+    throw new Error(
+      `[single-story-close] refusing to open a pull request for ${storyBranch}: ` +
+        `the head-versus-base diff (${emptyDiff.baseRef}...${storyBranch}) contains no files. ` +
+        'An empty diff has nothing to merge, and a PR opened on it can only squash an empty ' +
+        'commit onto the base branch. If the work already landed, confirm the merge instead: ' +
+        `node .agents/scripts/single-story-confirm-merge.js --story ${storyId}`,
+    );
+  }
+
   progress('PR', `Opening PR for ${storyBranch} → ${baseBranch}...`);
   // The repo squash-merges and GitHub uses the PR title as the squash
   // subject on `main`. A raw human issue title is not a Conventional
@@ -110,7 +218,7 @@ export async function ensurePullRequestWith({
     ]);
     const url = (createResult?.stdout ?? '').trim();
     progress('PR', `✅ Opened: ${url}`);
-    return url;
+    return { url, alreadyMerged: false, created: true };
   } catch (err) {
     throw new Error(
       `[single-story-close] \`gh pr create\` failed: ${err?.message ?? err}`,

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

@@ -42,7 +42,12 @@ export function pushStoryBranch({
 }) {
   progress('GIT', `Pushing ${storyBranch} to origin...`);
   try {
-    gitSync(cwd, 'push', '--no-verify', '-u', 'origin', storyBranch);
+    // No hook-bypass flag here, deliberately. Close runs its own gate chain
+    // before this point, but `--skip-validation` skips that chain, and the
+    // bypass then left nothing running at all. `pre-push` is the backstop,
+    // and it only became reachable once hooks were materialized into
+    // worktrees — which is where every Story branch is built.
+    gitSync(cwd, 'push', '-u', 'origin', storyBranch);
     progress('GIT', `✅ Pushed ${storyBranch}.`);
   } catch (err) {
     throw new Error(