mandrel 1.84.0 → 1.86.0

package/.agents/scripts/lib/config/explain.js

@@ -126,10 +126,8 @@ const KEY_MEANINGS = Object.freeze({
     'How many recent commits the snapshot summarizes.',
   'planning.riskHeuristics':
     'Phrases that flag a Story as high-risk for HITL escalation.',
-  'planning.taskSizing.maxAcceptance':
-    'Hard ceiling on acceptance criteria per Story.',
   'planning.taskSizing.softAcceptanceCount':
-    'Acceptance-criteria count above which a Story is flagged as large.',
+    'Acceptance-criteria count above which a Story is flagged as large (advisory-only — there is no hard acceptance ceiling).',
   'planning.taskSizing.softFiles':
     'Touched-file count above which a Story is flagged as large.',
   'planning.taskSizing.hardFiles':
@@ -148,6 +146,16 @@ const KEY_MEANINGS = Object.freeze({
     'Time-to-live for the Epic lease before a stale claim is reclaimable.',
   'delivery.ci.skipForStoryPushes':
     'Whether Story-branch pushes carry a [skip ci] trailer.',
+  'delivery.ci.earlyPr':
+    'Whether /deliver opens the Epic PR early so CI warms during later waves.',
+  'delivery.ci.watch.pollIntervalMs':
+    'Poll cadence (ms) for the merge/CI watch loop.',
+  'delivery.ci.watch.maxPolls':
+    'Maximum number of poll probes before the CI watch gives up.',
+  'delivery.ci.watch.maxResumes':
+    'Maximum times the CI watch may resume after a transient stall.',
+  'delivery.ci.autoMerge':
+    'Merge posture: trust-ci merges on green checks; strict also requires a clean review gate.',
   'delivery.preflight.maxStories':
     'Pre-dispatch ceiling on estimated Story count (no cap when unset).',
   'delivery.preflight.maxWaves':

package/.agents/scripts/lib/config/github.js

@@ -13,23 +13,27 @@
  */
 
 /**
- * Default required-check suite. The framework runs lint + format:check +
- * test by default; consumers override via
- * `github.branchProtection.requiredChecks` in `.agentrc.json`.
+ * Default required-check suite. Mirrors the live CI required-check set
+ * (`lint` + `test` + `baselines`); consumers override via
+ * `github.branchProtection.requiredChecks` in `.agentrc.json`. Kept in sync
+ * with `DEFAULT_CHECKS` in `git-pr-quality-gate.js` and the CI job names in
+ * `.github/workflows/ci.yml` — the retired `format:check` folded into `lint`
+ * (Story #1829) and `lifecycle-doc-drift` collapsed into `lint`/`docs:check`
+ * (Epic #1943), so neither belongs in the default set.
  */
 export const DEFAULT_REQUIRED_CHECKS = Object.freeze([
   Object.freeze({
     name: 'lint',
     cmd: Object.freeze(['npm', 'run', 'lint']),
   }),
-  Object.freeze({
-    name: 'format:check',
-    cmd: Object.freeze(['npm', 'run', 'format:check']),
-  }),
   Object.freeze({
     name: 'test',
     cmd: Object.freeze(['npm', 'test']),
   }),
+  Object.freeze({
+    name: 'baselines',
+    cmd: Object.freeze(['node', '.agents/scripts/check-baselines.js']),
+  }),
 ]);
 
 export const BRANCH_PROTECTION_DEFAULTS = Object.freeze({

package/.agents/scripts/lib/config-settings-schema-delivery.js

@@ -226,10 +226,31 @@ const EPIC_AUDIT_SCHEMA = {
 // commit subjects so intermediate pushes do not stampede the CI fleet.
 // The Epic-branch merge commit produced by story-close.js's merge
 // runner never carries the marker, regardless of this flag.
+//
+// Story #4356 (Epic #4355) — CI-aware delivery namespace. `earlyPr` gates
+// whether /deliver opens the Epic PR early (before every Story merges) so CI
+// starts warming while later waves run; defaults to `true` via getCiDelivery.
+// `watch.*` tunes the merge/CI watch poll loop (poll cadence, poll cap, and
+// how many times the watcher may resume after a transient stall).
+// `autoMerge` selects the merge posture: `"trust-ci"` (default) merges once
+// required checks pass, `"strict"` additionally requires a clean review gate.
+const CI_WATCH_SCHEMA = {
+  type: 'object',
+  properties: {
+    pollIntervalMs: { type: 'integer', minimum: 1 },
+    maxPolls: { type: 'integer', minimum: 1 },
+    maxResumes: { type: 'integer', minimum: 0 },
+  },
+  additionalProperties: false,
+};
+
 const CI_DELIVERY_SCHEMA = {
   type: 'object',
   properties: {
     skipForStoryPushes: { type: 'boolean' },
+    earlyPr: { type: 'boolean' },
+    watch: CI_WATCH_SCHEMA,
+    autoMerge: { type: 'string', enum: ['trust-ci', 'strict'] },
   },
   additionalProperties: false,
 };

package/.agents/scripts/lib/config-settings-schema.js

@@ -250,18 +250,18 @@ const CODEBASE_SNAPSHOT_SCHEMA = {
  * `planning.taskSizing` — Story-sizing thresholds consumed by
  * `ticket-validator-sizing.js`. Operator overrides shallow-merge with
  * `DEFAULT_TASK_SIZING` defaults (softFiles 15, hardFiles 30,
- * maxAcceptance 14, softAcceptanceCount 10 — the uniform relaxed profile
- * from Story #3874). Story #3760 collapsed the per-profile matrix and the
- * parallel `testSurface` axis into a flat set of knobs; the `sizingProfile`
- * enum was replaced by an optional body-level `wide` declaration that lifts
- * the `hardFiles` rejection.
+ * softAcceptanceCount 10 — the uniform relaxed profile from Story #3874).
+ * Story #3760 collapsed the per-profile matrix and the parallel
+ * `testSurface` axis into a flat set of knobs; the `sizingProfile` enum was
+ * replaced by an optional body-level `wide` declaration that lifts the
+ * `hardFiles` rejection. The hard `maxAcceptance` ceiling was removed after
+ * the Epic #4355 decomposition experiment — acceptance mass is advisory-only.
  */
 const TASK_SIZING_SCHEMA = {
   type: 'object',
   properties: {
     softFiles: { type: 'integer', minimum: 1 },
     hardFiles: { type: 'integer', minimum: 1 },
-    maxAcceptance: { type: 'integer', minimum: 1 },
     softAcceptanceCount: { type: 'integer', minimum: 1 },
     // Under-size (merge-candidate) thresholds (Story #4312). A Story whose
     // footprint is at or below BOTH ceilings and that carries a `depends_on`

package/.agents/scripts/lib/orchestration/epic-cleanup.js

@@ -29,8 +29,12 @@
  */
 
 import { spawnSync } from 'node:child_process';
-
 import { parseWorktreePorcelain } from '../worktree/inspector.js';
+import {
+  executeFastForward,
+  planFastForward,
+} from './git-cleanup/phases/fast-forward.js';
+import { makeFfProbes } from './git-cleanup/phases/git-probes-ff.js';
 
 const WT_SCRATCH_BRANCH = 'wt-branch';
 
@@ -328,6 +332,51 @@ export function deleteWtBranchIfPresent(opts) {
   return { deleted: false, present: true, stderr };
 }
 
+/**
+ * Fast-forward the base branch to its remote after a confirmed merge, so a
+ * post-`/deliver` local checkout converges to `origin/<baseBranch>` without a
+ * manual `git pull`. Reuses `planFastForward` + `executeFastForward` from the
+ * git-cleanup phase library (the single source of the FF state machine),
+ * feeding them probes bound to the injected `gitSpawn`.
+ *
+ * @param {{
+ *   cwd: string,
+ *   baseBranch?: string,
+ *   remoteName?: string,
+ *   gitSpawn: (cwd: string, ...args: string[]) => { status: number, stdout: string, stderr: string },
+ *   logger?: { info?: Function, warn?: Function },
+ * }} opts
+ * @returns {{ ok: boolean, applied: boolean, skipped: boolean, reason?: string, behind?: number, stderr?: string }}
+ */
+export function fastForwardBaseBranch(opts) {
+  const {
+    cwd,
+    baseBranch = 'main',
+    remoteName = 'origin',
+    gitSpawn,
+    logger,
+  } = opts;
+  const probe = makeFfProbes(gitSpawn);
+  const plan = planFastForward({
+    cwd,
+    baseBranch,
+    remoteName,
+    isCleanFn: probe.isClean,
+    currentBranchFn: probe.currentBranch,
+    fetchFn: probe.fetch,
+    canFastForwardFn: probe.canFastForward,
+  });
+  return executeFastForward({
+    cwd,
+    baseBranch,
+    remoteName,
+    plan,
+    checkoutFn: probe.checkout,
+    mergeFn: probe.merge,
+    ...(logger ? { logger } : {}),
+  });
+}
+
 /**
  * Reap every branch owned by the Epic. Best-effort — failures aggregate into
  * the result rather than throwing.
@@ -350,6 +399,7 @@ export function deleteWtBranchIfPresent(opts) {
  *   switched: { switched: boolean, from: string|null, to: string|null, stderr?: string } | null,
  *   pruned: { pruned: string[], stderr?: string } | null,
  *   wtBranch: { deleted: boolean, present: boolean, reason?: string, stderr?: string } | null,
+ *   fastForward: { ok: boolean, applied: boolean, skipped: boolean, reason?: string, behind?: number, stderr?: string } | null,
  *   epicBranchKept: boolean,
  *   ok: boolean,
  * }}
@@ -375,6 +425,7 @@ export function reapEpicBranches(opts) {
       switched: null,
       pruned: null,
       wtBranch: null,
+      fastForward: null,
       epicBranchKept: false,
       ok: true,
     };
@@ -463,6 +514,26 @@ export function reapEpicBranches(opts) {
     logger?.info?.(`[epic-cleanup] deleted stale ${WT_SCRATCH_BRANCH} ref`);
   }
 
+  // After a confirmed merge (epic branch NOT kept), fast-forward the base
+  // branch so the local checkout converges to `origin/<baseBranch>` with no
+  // manual `git pull`. When the epic branch is kept (open PR), the merge is
+  // not confirmed, so the FF is skipped with an explicit reason rather than
+  // moving `main` under an in-flight PR.
+  const fastForward = epicHasOpenPr
+    ? { ok: true, applied: false, skipped: true, reason: 'epic-branch-kept' }
+    : fastForwardBaseBranch({
+        cwd,
+        baseBranch,
+        remoteName: remote,
+        gitSpawn,
+        logger,
+      });
+  if (fastForward.applied) {
+    logger?.info?.(
+      `[epic-cleanup] fast-forwarded ${baseBranch} by ${fastForward.behind} commit(s) to ${remote}/${baseBranch}`,
+    );
+  }
+
   const failures = reaped.filter((r) => !r.branchDeleted);
   return {
     epicId: state?.epicId ?? null,
@@ -471,7 +542,224 @@ export function reapEpicBranches(opts) {
     switched,
     pruned,
     wtBranch,
+    fastForward,
     epicBranchKept: epicHasOpenPr,
     ok: failures.length === 0,
   };
 }
+
+/**
+ * Does a local branch head ref exist? Thin `git rev-parse --verify` wrapper
+ * exported for the resume-detect path (and its tests).
+ *
+ * @param {{ cwd: string, gitSpawn: Function, branch: string }} opts
+ * @returns {boolean}
+ */
+export function localRefExists({ cwd, gitSpawn, branch }) {
+  const res = gitSpawn(
+    cwd,
+    'rev-parse',
+    '--verify',
+    '--quiet',
+    `refs/heads/${branch}`,
+  );
+  return res.status === 0;
+}
+
+/**
+ * Probe whether the Epic branch's PR is MERGED and, if so, its URL (needed
+ * for the `epic.merge.armed` payload). Fails CLOSED to
+ * `{ merged: false, prUrl: null }` on any probe error — an indeterminate
+ * probe must never auto-arm a destructive reap.
+ *
+ * @param {{
+ *   epicBranch: string,
+ *   cwd: string,
+ *   spawnFn?: typeof spawnSync,
+ *   logger?: { warn?: Function },
+ * }} opts
+ * @returns {{ merged: boolean, prUrl: string|null }}
+ */
+export function epicPrMergeState(opts) {
+  const { epicBranch, cwd, spawnFn = spawnSync, logger } = opts;
+  if (typeof epicBranch !== 'string' || epicBranch.length === 0) {
+    return { merged: false, prUrl: null };
+  }
+  let result;
+  try {
+    result = spawnFn(
+      'gh',
+      [
+        'pr',
+        'list',
+        '--head',
+        epicBranch,
+        '--state',
+        'merged',
+        '--json',
+        'number,url,mergedAt',
+        '--limit',
+        '1',
+      ],
+      { cwd, encoding: 'utf-8', shell: false },
+    );
+  } catch (err) {
+    logger?.warn?.(
+      `[epic-cleanup] merged-PR probe threw for ${epicBranch} (treating as unmerged): ${err?.message ?? err}`,
+    );
+    return { merged: false, prUrl: null };
+  }
+  if (!result || result.status !== 0) {
+    logger?.warn?.(
+      `[epic-cleanup] merged-PR probe failed for ${epicBranch} (status=${result?.status}): ${(result?.stderr ?? '').trim()}`,
+    );
+    return { merged: false, prUrl: null };
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(String(result.stdout ?? '').trim() || '[]');
+  } catch {
+    return { merged: false, prUrl: null };
+  }
+  if (!Array.isArray(parsed) || parsed.length === 0) {
+    return { merged: false, prUrl: null };
+  }
+  const row = parsed[0];
+  const prUrl =
+    typeof row?.url === 'string' && row.url.length > 0 ? row.url : null;
+  // A merged-state row with no usable URL cannot arm (the schema requires a
+  // `prUrl`), so treat it as not-armable.
+  return { merged: prUrl !== null, prUrl };
+}
+
+/**
+ * Detect a merged-but-uncleaned Epic: the PR merged but one or more local
+ * `epic/<id>` / `story-<id>` refs still linger. This is the signal `/deliver`
+ * idempotent resume uses to auto-fire `epic.merge.armed` so Phase 9 reaps
+ * without a manual command. Pure given its injected ports.
+ *
+ * @param {{
+ *   state: object|null,
+ *   cwd: string,
+ *   gitSpawn: Function,
+ *   spawnFn?: Function,
+ *   prMergeStateFn?: typeof epicPrMergeState,
+ *   logger?: { warn?: Function, info?: Function },
+ * }} opts
+ * @returns {{
+ *   epicId: number|null,
+ *   epicBranch: string|null,
+ *   presentRefs: string[],
+ *   localRefsPresent: boolean,
+ *   merged: boolean,
+ *   prUrl: string|null,
+ *   shouldArm: boolean,
+ *   reason: string,
+ * }}
+ */
+export function detectMergedUncleanedEpic(opts) {
+  const {
+    state,
+    cwd,
+    gitSpawn,
+    spawnFn,
+    prMergeStateFn = epicPrMergeState,
+    logger,
+  } = opts;
+  const { epicBranch, storyBranches } = listEpicBranchesFromState(state);
+  if (!epicBranch) {
+    return {
+      epicId: null,
+      epicBranch: null,
+      presentRefs: [],
+      localRefsPresent: false,
+      merged: false,
+      prUrl: null,
+      shouldArm: false,
+      reason: 'no-state',
+    };
+  }
+  const presentRefs = [epicBranch, ...storyBranches].filter((branch) =>
+    localRefExists({ cwd, gitSpawn, branch }),
+  );
+  if (presentRefs.length === 0) {
+    // Already clean — nothing to arm. This is the idempotent no-op that
+    // makes re-running `/deliver` on an already-reaped Epic safe.
+    return {
+      epicId: state.epicId,
+      epicBranch,
+      presentRefs,
+      localRefsPresent: false,
+      merged: false,
+      prUrl: null,
+      shouldArm: false,
+      reason: 'no-local-refs',
+    };
+  }
+  const { merged, prUrl } = prMergeStateFn({
+    epicBranch,
+    cwd,
+    spawnFn,
+    logger,
+  });
+  const shouldArm = merged && prUrl !== null;
+  return {
+    epicId: state.epicId,
+    epicBranch,
+    presentRefs,
+    localRefsPresent: true,
+    merged,
+    prUrl,
+    shouldArm,
+    reason: shouldArm ? 'merged-uncleaned' : 'not-merged',
+  };
+}
+
+/**
+ * `/deliver` idempotent-resume auto-arm: detect a merged-but-uncleaned Epic
+ * and, when found, fire `epic.merge.armed` on the injected lifecycle `bus` so
+ * the Cleaner → BranchCleaner chain reaps Phase 9 without an operator command.
+ * A no-op (and never throws on a clean/unmerged Epic) so re-running resume is
+ * safe.
+ *
+ * @param {{
+ *   state: object|null,
+ *   cwd: string,
+ *   gitSpawn: Function,
+ *   spawnFn?: Function,
+ *   bus: { emit: (event: string, payload: object) => Promise<unknown> },
+ *   detectFn?: typeof detectMergedUncleanedEpic,
+ *   logger?: { warn?: Function, info?: Function },
+ * }} opts
+ * @returns {Promise<{ armed: boolean, reason: string, prUrl: string|null, detection: object }>}
+ */
+export async function armCleanupIfMerged(opts) {
+  const { state, cwd, gitSpawn, spawnFn, bus, detectFn, logger } = opts;
+  if (!bus || typeof bus.emit !== 'function') {
+    throw new TypeError('armCleanupIfMerged requires a bus exposing emit()');
+  }
+  const detect = detectFn ?? detectMergedUncleanedEpic;
+  const detection = detect({ state, cwd, gitSpawn, spawnFn, logger });
+  if (!detection.shouldArm) {
+    return {
+      armed: false,
+      reason: detection.reason,
+      prUrl: detection.prUrl,
+      detection,
+    };
+  }
+  const payload = { prUrl: detection.prUrl };
+  if (Number.isInteger(detection.epicId) && detection.epicId > 0) {
+    payload.epicId = detection.epicId;
+  }
+  await bus.emit('epic.merge.armed', payload);
+  logger?.info?.(
+    `[epic-cleanup] resume auto-arm: fired epic.merge.armed for ${detection.epicBranch} (${detection.prUrl})`,
+  );
+  return {
+    armed: true,
+    reason: 'merged-uncleaned',
+    prUrl: detection.prUrl,
+    detection,
+  };
+}

package/.agents/scripts/lib/orchestration/finalize/open-or-locate-pr.js

@@ -27,6 +27,20 @@
  * does not attempt to create a duplicate PR. This is the AC-10
  * idempotency contract the Finalizer relies on for cross-process
  * re-runs of `/deliver`.
+ *
+ * Early-PR draft mode — Story #4359 (Epic #4355).
+ *
+ *   When `delivery.ci.earlyPr` is on (the default), `/deliver` opens the
+ *   Epic PR as a **draft** at wave 1 (`openOrLocatePr({ draft: true })`)
+ *   so every subsequent per-wave push runs CI attributed to its own wave.
+ *   The `draft` flag only appends `--draft` to the `gh pr create` shell —
+ *   the probe/locate path is unchanged, so a re-run on the same head
+ *   branch still short-circuits without opening a duplicate. Phase 7 then
+ *   flips that existing draft to ready-for-review via `markPrReady` rather
+ *   than creating the PR. When `earlyPr` is off, no draft is opened at
+ *   wave 1 and Phase 7 opens the PR at close time exactly as before
+ *   (`openOrLocatePr` with no `draft`). The title/body contract
+ *   (`feat: Epic #<id>` / `Closes #<id>`) is identical in both modes.
  */
 
 import { spawnSync } from 'node:child_process';
@@ -119,6 +133,12 @@ export function parsePrViewResult(stdout) {
  *   or changelog entry).
  * @param {string} [args.body] — explicit PR body override; defaults to
  *   `Closes #<epicId>`.
+ * @param {boolean} [args.draft] — when `true`, open the new PR as a draft
+ *   (`gh pr create --draft`). Story #4359: the early-PR path opens the
+ *   Epic PR as a draft at wave 1 so per-wave pushes warm CI; Phase 7 later
+ *   flips it ready via `markPrReady`. Only affects the create path — the
+ *   locate short-circuit never inspects draft state, so a re-run stays
+ *   idempotent. Default `false`.
  * @param {string} [args.cwd] — working directory for the gh shells.
  *   Default `process.cwd()`.
  * @param {Function} [args.ghSpawn] — override the gh invocation for
@@ -131,6 +151,7 @@ export async function openOrLocatePr({
   baseBranch = 'main',
   title,
   body,
+  draft = false,
   cwd = process.cwd(),
   ghSpawn = defaultGhSpawn,
 } = {}) {
@@ -206,6 +227,11 @@ export async function openOrLocatePr({
       finalTitle,
       '--body',
       finalBody,
+      // Story #4359: open as a draft when the early-PR path requests it.
+      // The flag is elided entirely when `draft` is false so the
+      // close-time (earlyPr=false) create path is byte-identical to the
+      // pre-Story behaviour.
+      ...(draft ? ['--draft'] : []),
     ],
     cwd,
   });
@@ -239,3 +265,42 @@ export async function openOrLocatePr({
   }
   return { prNumber: parsed.number, url: parsed.url, created: true };
 }
+
+/**
+ * Mark an existing draft PR as ready-for-review — Story #4359 (Epic
+ * #4355). This is the Phase-7 counterpart to the wave-1 draft open: when
+ * `delivery.ci.earlyPr` is on, the Epic PR already exists as a draft, so
+ * finalize flips it ready rather than creating a PR.
+ *
+ * Idempotent: `gh pr ready` on an already-ready PR is a no-op that exits
+ * 0, so re-running finalize (or replaying after a crash) is safe. When the
+ * PR reference does not resolve, `gh` exits non-zero and this helper
+ * throws with the stderr detail.
+ *
+ * @param {object} args
+ * @param {string} args.pr — a PR reference `gh pr ready` accepts: the
+ *   numeric id, the branch name, or the html URL. `openOrLocatePr`
+ *   returns both `prNumber` and `url`; either is a valid input.
+ * @param {string} [args.cwd] — working directory for the gh shell.
+ *   Default `process.cwd()`.
+ * @param {Function} [args.ghSpawn] — override the gh invocation for
+ *   tests. Same shape as `defaultGhSpawn`.
+ * @returns {Promise<{ pr: string, ready: true }>}
+ */
+export async function markPrReady({
+  pr,
+  cwd = process.cwd(),
+  ghSpawn = defaultGhSpawn,
+} = {}) {
+  const ref = pr == null ? '' : String(pr).trim();
+  if (ref.length === 0) {
+    throw new TypeError('markPrReady: pr must be a non-empty reference');
+  }
+  const ready = ghSpawn({ args: ['pr', 'ready', ref], cwd });
+  if (ready.status !== 0) {
+    throw new Error(
+      `markPrReady: gh pr ready failed (status=${ready.status}): ${ready.stderr.trim()}`,
+    );
+  }
+  return { pr: ref, ready: true };
+}

package/.agents/scripts/lib/orchestration/git-cleanup/phases/git-probes-ff.js

@@ -34,54 +34,107 @@ export function isWorktreeLockFailure(stderr) {
 
 /* node:coverage ignore next */
 export function isWorkingTreeClean(cwd) {
-  const res = gitSpawn(cwd, 'status', '--porcelain');
-  if (res.status !== 0) return false;
-  return res.stdout.trim() === '';
+  return defaultFfProbes.isClean(cwd);
 }
 
 /* node:coverage ignore next */
 export function fetchRef(cwd, remoteName, ref) {
-  const res = gitSpawn(cwd, 'fetch', '--quiet', remoteName, ref);
-  if (res.status !== 0) return { ok: false, stderr: res.stderr };
-  return { ok: true };
+  return defaultFfProbes.fetch(cwd, remoteName, ref);
 }
 
 /* node:coverage ignore next */
 export function canFastForward(cwd, baseBranch, remoteName) {
-  const ref = `${remoteName}/${baseBranch}`;
-  const ahead = gitSpawn(
-    cwd,
-    'rev-list',
-    '--left-right',
-    '--count',
-    `${baseBranch}...${ref}`,
-  );
-  if (ahead.status !== 0) {
-    return { ok: false, behind: 0, reason: 'rev-list-failed' };
-  }
-  const parts = ahead.stdout.trim().split(/\s+/);
-  const localAhead = Number(parts[0]) || 0;
-  const remoteAhead = Number(parts[1]) || 0;
-  if (localAhead > 0) {
-    return { ok: false, behind: remoteAhead, reason: 'not-fast-forward' };
-  }
-  return { ok: true, behind: remoteAhead };
+  return defaultFfProbes.canFastForward(cwd, baseBranch, remoteName);
 }
 
 /* node:coverage ignore next */
 export function checkoutBranch(cwd, branch) {
-  const res = gitSpawn(cwd, 'checkout', branch);
-  if (res.status !== 0) return { ok: false, stderr: res.stderr };
-  return { ok: true };
+  return defaultFfProbes.checkout(cwd, branch);
 }
 
 /* node:coverage ignore next */
 export function mergeFastForward(cwd, ref) {
-  const res = gitSpawn(cwd, 'merge', '--ff-only', ref);
-  if (res.status !== 0) return { ok: false, stderr: res.stderr };
-  return { ok: true };
+  return defaultFfProbes.merge(cwd, ref);
 }
 
+/**
+ * Build the fast-forward probe bundle bound to a `gitSpawn`.
+ *
+ * This is the **single implementation** of the FF/base-sync git wrappers.
+ * The standalone exports above delegate to a default instance bound to the
+ * shared `gitSpawn`; callers that need to inject their own spawn for testing
+ * (e.g. the epic-cleanup runner) call this factory directly instead of
+ * hand-rolling a parallel copy (framework-gap #4379). The bundle also carries
+ * `currentBranch` so an injecting caller gets the whole FF surface from one
+ * place.
+ *
+ * @param {(cwd: string, ...args: string[]) => { status: number, stdout: string, stderr: string }} [spawn]
+ * @returns {{
+ *   isClean: (cwd: string) => boolean,
+ *   currentBranch: (cwd: string) => string|null,
+ *   fetch: (cwd: string, remoteName: string, ref: string) => { ok: boolean, stderr?: string },
+ *   canFastForward: (cwd: string, baseBranch: string, remoteName: string) => { ok: boolean, behind: number, reason?: string },
+ *   checkout: (cwd: string, branch: string) => { ok: boolean, stderr?: string },
+ *   merge: (cwd: string, ref: string) => { ok: boolean, stderr?: string },
+ * }}
+ */
+export function makeFfProbes(spawn = gitSpawn) {
+  return {
+    isClean: (cwd) => {
+      const res = spawn(cwd, 'status', '--porcelain');
+      return res.status === 0 && String(res.stdout ?? '').trim() === '';
+    },
+    currentBranch: (cwd) => {
+      const res = spawn(cwd, 'symbolic-ref', '--quiet', '--short', 'HEAD');
+      return res.status !== 0 ? null : String(res.stdout ?? '').trim() || null;
+    },
+    fetch: (cwd, remoteName, ref) => {
+      const res = spawn(cwd, 'fetch', '--quiet', remoteName, ref);
+      return res.status === 0
+        ? { ok: true }
+        : { ok: false, stderr: res.stderr };
+    },
+    canFastForward: (cwd, baseBranch, remoteName) => {
+      const ref = `${remoteName}/${baseBranch}`;
+      const ahead = spawn(
+        cwd,
+        'rev-list',
+        '--left-right',
+        '--count',
+        `${baseBranch}...${ref}`,
+      );
+      if (ahead.status !== 0) {
+        return { ok: false, behind: 0, reason: 'rev-list-failed' };
+      }
+      const parts = String(ahead.stdout ?? '')
+        .trim()
+        .split(/\s+/);
+      const localAhead = Number(parts[0]) || 0;
+      const remoteAhead = Number(parts[1]) || 0;
+      if (localAhead > 0) {
+        return { ok: false, behind: remoteAhead, reason: 'not-fast-forward' };
+      }
+      return { ok: true, behind: remoteAhead };
+    },
+    checkout: (cwd, branch) => {
+      const res = spawn(cwd, 'checkout', branch);
+      return res.status === 0
+        ? { ok: true }
+        : { ok: false, stderr: res.stderr };
+    },
+    merge: (cwd, ref) => {
+      const res = spawn(cwd, 'merge', '--ff-only', ref);
+      return res.status === 0
+        ? { ok: true }
+        : { ok: false, stderr: res.stderr };
+    },
+  };
+}
+
+// Default instance bound to the shared gitSpawn; the standalone wrappers
+// above delegate to it so there is exactly one FF-probe implementation.
+const defaultFfProbes = makeFfProbes(gitSpawn);
+
 /* node:coverage ignore next */
 export function removeWorktree(worktreePath, cwd) {
   const plain = gitSpawn(cwd, 'worktree', 'remove', worktreePath);