mandrel 1.85.0 → 1.87.0

package/.agents/scripts/lib/framework-version.js

@@ -0,0 +1,210 @@
+// .agents/scripts/lib/framework-version.js
+/**
+ * framework-version.js — single source of truth for the running Mandrel
+ * framework version and the ticket-body authoring stamp.
+ *
+ * Two concerns live here:
+ *
+ * 1. **Version resolution.** Under npm distribution the root `package.json`
+ *    is the canonical version marker. {@link resolveFrameworkVersion} reads it
+ *    and degrades to `'unknown'` (never throws) so a missing/unreadable
+ *    manifest can never crash an authoring or hydration path. The private
+ *    `getVersion()` in `lib/orchestration/context-hydration-engine.js`
+ *    delegates here (DRY — one manifest reader).
+ *
+ * 2. **Ticket-body stamp.** Epics and Stories are stamped **once at authoring
+ *    time** with the running version and the authoring date, via a hybrid
+ *    surface:
+ *      - a hidden machine-readable field in the trailing
+ *        `<!-- meta: {"mandrel_version":"…","authored_at":"…"} -->` block
+ *        (the source of truth, queryable by tooling), and
+ *      - a single visible footer line
+ *        `> 🏷️ Authored with Mandrel v<version> · <YYYY-MM-DD>` so a human
+ *        reading the raw GitHub issue sees the provenance without any tooling.
+ *
+ *    The stamp is **immutable**: {@link stampFrameworkVersion} is a no-op when
+ *    the body already carries a `mandrel_version`, so a later re-render or
+ *    Epic-body edit preserves the originally-authored version verbatim rather
+ *    than bumping it to whatever version happens to be running.
+ *
+ * This module imports only Node builtins so it can be pulled in from the
+ * story-body serializer, the ticket provider, and the Epic ideation renderer
+ * without risking an import cycle.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+/** Returned when the package manifest is absent or unreadable. */
+export const FALLBACK_VERSION = 'unknown';
+
+/**
+ * Trailing machine-metadata comment block: `<!-- meta: {...} -->`. Mirrors the
+ * regex the Story-body parser uses so both surfaces recognise the same block.
+ */
+const META_BLOCK_RE = /<!--\s*meta:\s*(\{[\s\S]*?\})\s*-->/;
+
+/**
+ * The visible authoring marker line. A blockquote so GitHub renders it as a
+ * callout. Used both to detect an already-emitted marker (for the strip step)
+ * and, in the Story-body parser, to skip the line during section parsing so it
+ * never pollutes the last structured section.
+ */
+export const AUTHORED_MARKER_LINE_RE = /^\s*>\s*🏷️\s+Authored with Mandrel\b/;
+
+/**
+ * Compute the default path to the root `package.json`. This module ships inside
+ * the `mandrel` package at `<pkgRoot>/.agents/scripts/lib/framework-version.js`,
+ * so the manifest sits three directories up — the same layout in the dev repo
+ * and the published tarball.
+ *
+ * @returns {string}
+ */
+function defaultPkgPath() {
+  const moduleDir = path.dirname(fileURLToPath(import.meta.url));
+  return path.resolve(moduleDir, '../../..', 'package.json');
+}
+
+/**
+ * Resolve the running framework version from the root `package.json`. Degrades
+ * to {@link FALLBACK_VERSION} (never throws) on any read or parse failure so a
+ * missing/unreadable manifest can never crash an authoring or hydration path.
+ *
+ * @param {{ pkgPath?: string }} [opts] - `pkgPath` override (test seam).
+ * @returns {string}
+ */
+export function resolveFrameworkVersion({ pkgPath } = {}) {
+  try {
+    const resolved = typeof pkgPath === 'string' ? pkgPath : defaultPkgPath();
+    const parsed = JSON.parse(fs.readFileSync(resolved, 'utf8'));
+    return typeof parsed.version === 'string' && parsed.version.trim()
+      ? parsed.version.trim()
+      : FALLBACK_VERSION;
+  } catch {
+    return FALLBACK_VERSION;
+  }
+}
+
+/**
+ * Format an authoring date as `YYYY-MM-DD` (UTC). Matches the date shape the
+ * rest of the authoring path uses (e.g. `qa-session`).
+ *
+ * @param {Date} [date=new Date()]
+ * @returns {string}
+ */
+export function formatAuthoredDate(date = new Date()) {
+  const d =
+    date instanceof Date && !Number.isNaN(date.getTime()) ? date : new Date();
+  return d.toISOString().slice(0, 10);
+}
+
+/**
+ * Build the visible authoring marker line for a given stamp. Centralised so
+ * the string is byte-identical across the two producers (the Story-body
+ * serializer and {@link stampFrameworkVersion}).
+ *
+ * @param {{ version: string, authoredAt: string }} stamp
+ * @returns {string}
+ */
+export function authoredMarkerLine({ version, authoredAt }) {
+  return `> 🏷️ Authored with Mandrel v${version} · ${authoredAt}`;
+}
+
+/**
+ * Read the framework stamp from a body's trailing meta block. Returns
+ * `{ version, authoredAt }` when a non-empty `mandrel_version` is present, or
+ * `null` when the body carries no stamp (or the meta block is malformed).
+ * `authoredAt` is `null` when the version is present but the date is absent.
+ *
+ * @param {string} markdown
+ * @returns {{ version: string, authoredAt: string|null }|null}
+ */
+export function extractFrameworkStamp(markdown) {
+  if (typeof markdown !== 'string') return null;
+  const match = markdown.match(META_BLOCK_RE);
+  if (!match) return null;
+  let parsed;
+  try {
+    parsed = JSON.parse(match[1]);
+  } catch {
+    return null;
+  }
+  if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    return null;
+  }
+  const version =
+    typeof parsed.mandrel_version === 'string' && parsed.mandrel_version.trim()
+      ? parsed.mandrel_version.trim()
+      : null;
+  if (version === null) return null;
+  const authoredAt =
+    typeof parsed.authored_at === 'string' && parsed.authored_at.trim()
+      ? parsed.authored_at.trim()
+      : null;
+  return { version, authoredAt };
+}
+
+/**
+ * Stamp a ticket body (Epic or Story markdown) with the framework version and
+ * authoring date — **once**. When the body already carries a `mandrel_version`
+ * the body is returned verbatim (immutability: never re-derive or bump an
+ * already-authored stamp). Otherwise the version keys are merged into (or
+ * create) the trailing `<!-- meta -->` block — appended **last** so the key
+ * order stays stable with the Story-body serializer — and the visible marker
+ * line is (re)emitted just above it.
+ *
+ * The `version` / `authoredAt` overrides let a caller (e.g. the Epic edit path)
+ * preserve a previously-authored stamp; both default to the running version and
+ * today's date when omitted.
+ *
+ * @param {string} markdown
+ * @param {{ version?: string, authoredAt?: string }} [stamp]
+ * @returns {string}
+ */
+export function stampFrameworkVersion(markdown, stamp = {}) {
+  const body = typeof markdown === 'string' ? markdown : '';
+
+  // Immutability: a body that already carries a version is preserved verbatim.
+  if (extractFrameworkStamp(body) !== null) return body;
+
+  const version =
+    typeof stamp?.version === 'string' && stamp.version.trim()
+      ? stamp.version.trim()
+      : resolveFrameworkVersion();
+  const authoredAt =
+    typeof stamp?.authoredAt === 'string' && stamp.authoredAt.trim()
+      ? stamp.authoredAt.trim()
+      : formatAuthoredDate();
+
+  // Merge into any existing (version-less) meta block, appending the version
+  // keys last for stable key order.
+  const metaMatch = body.match(META_BLOCK_RE);
+  const meta = {};
+  if (metaMatch) {
+    try {
+      const parsed = JSON.parse(metaMatch[1]);
+      if (
+        parsed !== null &&
+        typeof parsed === 'object' &&
+        !Array.isArray(parsed)
+      ) {
+        Object.assign(meta, parsed);
+      }
+    } catch {
+      // Malformed meta comment — drop it and re-emit a clean block.
+    }
+  }
+  meta.mandrel_version = version;
+  meta.authored_at = authoredAt;
+
+  // Strip any existing meta block / marker so both re-append canonically.
+  const head = body
+    .replace(META_BLOCK_RE, '')
+    .replace(new RegExp(AUTHORED_MARKER_LINE_RE.source, 'm'), '')
+    .replace(/\n{3,}/g, '\n\n')
+    .trimEnd();
+
+  const marker = authoredMarkerLine({ version, authoredAt });
+  return `${head}\n\n${marker}\n\n<!-- meta: ${JSON.stringify(meta)} -->`;
+}

package/.agents/scripts/lib/orchestration/context-hydration-engine.js

@@ -19,7 +19,6 @@
 import crypto from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
-import { fileURLToPath } from 'node:url';
 import { getCommands } from '../config/commands.js';
 import {
   getLimits,
@@ -28,6 +27,7 @@ import {
   resolveConfig,
 } from '../config-resolver.js';
 import { sliceEpicBodyForDelivery } from '../epic-body-sections.js';
+import { resolveFrameworkVersion } from '../framework-version.js';
 import { Logger } from '../Logger.js';
 import {
   buildEnvelope,
@@ -133,31 +133,16 @@ export function formatSkillCapsulesSection(entries) {
 // ---------------------------------------------------------------------------
 
 /**
- * Resolve the framework version from the installed package's `package.json`.
- *
- * Under npm distribution `package.json` is the single source of truth for the
- * framework version (the legacy plaintext version marker is retired). This
- * module ships inside the `mandrel` package at
- * `<pkgRoot>/.agents/scripts/lib/orchestration/context-hydration-engine.js`,
- * so the package manifest sits four directories up — the same layout in the
- * dev repo and in the published tarball. Read that manifest's `version`.
- *
- * Falls back to `'unknown'` when the manifest is absent or unreadable so a
- * missing package.json never crashes hydration.
+ * Resolve the framework version. Delegates to the shared
+ * {@link resolveFrameworkVersion} helper (single owner of the root
+ * `package.json` read) so the hydrator and the ticket-body stamp read the same
+ * source. Retained as a thin named wrapper so the mismatch-warning call sites
+ * below read against a stable local name.
  *
  * @returns {string}
  */
 function getVersion() {
-  try {
-    const moduleDir = path.dirname(fileURLToPath(import.meta.url));
-    const pkgPath = path.resolve(moduleDir, '../../../..', 'package.json');
-    const parsed = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
-    return typeof parsed.version === 'string' && parsed.version.trim()
-      ? parsed.version.trim()
-      : 'unknown';
-  } catch {
-    return 'unknown';
-  }
+  return resolveFrameworkVersion();
 }
 
 /**

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';
 
@@ -148,6 +152,40 @@ export function findWorktreePathForBranch(branch, worktrees) {
   return null;
 }
 
+/**
+ * Classify a `git branch -D <branch>` result. Pure — no IO. Exported as the
+ * clean unit-test seam for the not-found rule (this module carries a
+ * `node:coverage ignore file` header, so the git-side glue is not directly
+ * covered).
+ *
+ * Story #4393 — on the `/deliver` post-merge reap path a branch is routinely
+ * *already gone* (a prior sweep, a re-run, or GitHub's `--delete-branch`
+ * already dropped it). `git branch -D` then exits non-zero with a "not found"
+ * stderr. That is an **already-reaped success**, not a reap failure: counting
+ * it as a failure forces `reapEpicBranches().ok` false, which makes
+ * BranchCleaner classify `failed`, which flips the merged Epic to
+ * `agent::blocked` and reopens it. Only a not-found stderr is absorbed as
+ * success; every other non-zero exit stays a genuine failure.
+ *
+ * @param {{ status: number, stderr?: string }} branchDel
+ * @returns {{ branchDeleted: boolean, alreadyAbsent: boolean, stderr?: string }}
+ */
+export function classifyBranchDeletion(branchDel) {
+  if (branchDel?.status === 0) {
+    return { branchDeleted: true, alreadyAbsent: false };
+  }
+  const stderr = (branchDel?.stderr ?? '').trim();
+  // git's own message for a missing ref: "error: branch 'foo' not found."
+  if (/\bnot found\b/i.test(stderr)) {
+    return { branchDeleted: true, alreadyAbsent: true };
+  }
+  return {
+    branchDeleted: false,
+    alreadyAbsent: false,
+    ...(stderr ? { stderr } : {}),
+  };
+}
+
 /**
  * Reap a single branch. Best-effort worktree remove → fallback to `--force`
  * → fallback to filesystem rm → `git worktree prune` → `git branch -D`.
@@ -160,7 +198,7 @@ export function findWorktreePathForBranch(branch, worktrees) {
  *   rmSyncFn?: (path: string, opts: object) => void,
  *   logger?: { info?: Function, warn?: Function },
  * }} opts
- * @returns {{ branch: string, worktreeReaped: boolean, branchDeleted: boolean, method: string, stderr?: string }}
+ * @returns {{ branch: string, worktreeReaped: boolean, branchDeleted: boolean, alreadyAbsent: boolean, method: string, stderr?: string }}
  */
 export function reapBranch(opts) {
   const { branch, cwd, worktreePath, gitSpawn, rmSyncFn, logger } = opts;
@@ -197,16 +235,18 @@ export function reapBranch(opts) {
     gitSpawn(cwd, 'worktree', 'prune');
   }
 
-  // Drop the local branch.
+  // Drop the local branch. An already-absent branch (git → "not found") is
+  // already reaped — classifyBranchDeletion absorbs it as success so a benign
+  // missing ref never counts as a reap failure (Story #4393).
   const branchDel = gitSpawn(cwd, 'branch', '-D', branch);
-  const branchDeleted = branchDel.status === 0;
-  const stderr =
-    !branchDeleted && branchDel.stderr ? branchDel.stderr.trim() : undefined;
+  const { branchDeleted, alreadyAbsent, stderr } =
+    classifyBranchDeletion(branchDel);
 
   return {
     branch,
     worktreeReaped,
     branchDeleted,
+    alreadyAbsent,
     method: method ?? 'unknown',
     ...(stderr ? { stderr } : {}),
   };
@@ -328,6 +368,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 +435,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 +461,7 @@ export function reapEpicBranches(opts) {
       switched: null,
       pruned: null,
       wtBranch: null,
+      fastForward: null,
       epicBranchKept: false,
       ok: true,
     };
@@ -463,6 +550,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 +578,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,
+  };
+}