mandrel 1.85.0 → 1.86.0

package/.agents/scripts/lib/single-story-sweep.js

@@ -1,27 +1,41 @@
 /**
- * single-story-sweep.js — Sweep merged `story-*` branches at init.
+ * single-story-sweep.js — the scope-agnostic merged-branch sweep engine
+ * plus the `story-*` boot-sweep preset.
  *
- * Wraps `git-cleanup-branches.js` with a fixed policy tuned for the
- * `/single-story-deliver` boot path:
+ * `sweepMergedBranches` is the single reap engine every boot cleanup
+ * path routes through. It sits directly over the `git-cleanup` phase
+ * library (`planCleanup` / `executeCleanup` / `executeFastForward` /
+ * `buildGlobFilter`) and the shared `evaluateProtection` guard set, so
+ * no reap path re-implements the `git branch -D` / `git merge --ff-only`
+ * primitives:
  *
- *   - Scope: `story-*` only (never touches `epic/*`, `story/<id>/*`, etc.).
- *   - Mode:  --execute --remote (delete local + origin + prune trackers).
- *   - Skip:  the current run's `storyBranch` is always excluded, even if a
- *            stale PR for the same id were already merged.
+ *   - Scope: caller-supplied `include` / `exclude` globs (via
+ *            `buildGlobFilter`). The story preset pins `story-*`.
+ *   - Reap:  merged local branches whose PR HEAD SHA equals the merged
+ *            `headRefOid`, deleted local + origin with tracking-ref
+ *            prune (`executeCleanup` in `--remote` mode).
  *   - Protection (Story #2011): each candidate is filtered through
  *            `evaluateProtection` before reaching `executeCleanup`. A
  *            candidate is protected (not reaped) when its branch HEAD
  *            differs from the PR's `headRefOid` (unpushed work), when
  *            its worktree has uncommitted edits, or when the parent
  *            Story ticket is not in a terminal state. Protected
- *            candidates surface in the result envelope under
- *            `protected` so the operator can see what was skipped.
+ *            candidates surface under `protected`.
+ *   - Fast-forward (opt-in via `fastForward: true`): fast-forward the
+ *            base branch through `executeFastForward` after the reap.
+ *            Best-effort — a failed fast-forward never fails the sweep.
  *   - Concurrency (Story #2011): the sweep acquires a process-scoped
  *            lockfile around plan + execute. On lock contention the
- *            sweep is skipped (init continues — same contract as a
+ *            sweep is skipped (the host continues — same contract as a
  *            plan failure).
- *   - Errors are caught and surfaced in the envelope. The caller MUST NOT
- *            propagate sweep failures — story init proceeds either way.
+ *   - Never touches the stash stack.
+ *   - Errors are caught and surfaced in the envelope. Callers MUST NOT
+ *            propagate sweep failures — the host proceeds either way.
+ *
+ * `sweepMergedStoryBranches` is a thin preset over the engine tuned for
+ * the boot path (`include: story-*`, `exclude: <current story branch>`,
+ * `fastForward: false`). Its exported name, signature, and result
+ * envelope are unchanged from the pre-engine implementation.
  *
  * Re-exports the same `planCleanup` / `executeCleanup` injection seams so
  * tests can stub git/`gh` without touching the CLI.
@@ -30,7 +44,9 @@
 import {
   buildGlobFilter,
   executeCleanup as defaultExecuteCleanup,
+  executeFastForward as defaultExecuteFastForward,
   planCleanup as defaultPlanCleanup,
+  planFastForward as defaultPlanFastForward,
 } from '../git-cleanup.js';
 import { evaluateProtection as defaultEvaluateProtection } from './single-story-sweep/protection.js';
 import { acquireSweepLock as defaultAcquireSweepLock } from './single-story-sweep/sweep-lock.js';
@@ -38,15 +54,20 @@ import { acquireSweepLock as defaultAcquireSweepLock } from './single-story-swee
 const STORY_BRANCH_INCLUDE = 'story-*';
 
 /**
- * Sweep merged `story-*` branches in `cwd`.
+ * Scope-agnostic merged-branch sweep engine.
  *
  * @param {{
  *   cwd: string,
  *   baseBranch: string,
- *   currentStoryBranch: string,
+ *   include?: string[],
+ *   exclude?: string[],
+ *   fastForward?: boolean,
  *   logger?: { info?: (m: string) => void, warn?: (m: string) => void },
+ *   logTag?: string,
  *   planCleanupFn?: typeof defaultPlanCleanup,
  *   executeCleanupFn?: typeof defaultExecuteCleanup,
+ *   planFastForwardFn?: typeof defaultPlanFastForward,
+ *   executeFastForwardFn?: typeof defaultExecuteFastForward,
  *   protectionFn?: typeof defaultEvaluateProtection,
  *   protectionCtx?: object,
  *   acquireLockFn?: typeof defaultAcquireSweepLock,
@@ -61,17 +82,23 @@ const STORY_BRANCH_INCLUDE = 'story-*';
  *   remoteDeleted: number,
  *   protected: Array<{ branch: string, reason: string, worktreePath?: string|null }>,
  *   failures: Array<{ branch: string|null, scope: string, stderr?: string }>,
+ *   fastForward?: object,
  *   error?: string,
  *   reason?: string,
  * }>}
  */
-export async function sweepMergedStoryBranches({
+export async function sweepMergedBranches({
   cwd,
   baseBranch,
-  currentStoryBranch,
+  include = ['*'],
+  exclude = [],
+  fastForward = false,
   logger = {},
+  logTag = '[sweep]',
   planCleanupFn = defaultPlanCleanup,
   executeCleanupFn = defaultExecuteCleanup,
+  planFastForwardFn = defaultPlanFastForward,
+  executeFastForwardFn = defaultExecuteFastForward,
   protectionFn = defaultEvaluateProtection,
   protectionCtx = null,
   acquireLockFn = defaultAcquireSweepLock,
@@ -92,16 +119,13 @@ export async function sweepMergedStoryBranches({
 
   // Optional lock acquisition. Skip silently when no lockPath is
   // supplied (e.g. unit tests, callers that opt out). Contention is
-  // non-fatal — return a skipped result and let init continue.
+  // non-fatal — return a skipped result and let the host continue.
   let releaseLock = () => {};
   if (lockPath) {
-    const lockResult = acquireLockFn({
-      lockPath,
-      timeoutMs: lockTimeoutMs,
-    });
+    const lockResult = acquireLockFn({ lockPath, timeoutMs: lockTimeoutMs });
     if (!lockResult.acquired) {
       log.warn(
-        `[single-story-sweep] lock not acquired (${lockResult.reason}${
+        `${logTag} lock not acquired (${lockResult.reason}${
           lockResult.detail ? `: ${lockResult.detail}` : ''
         }); skipping sweep.`,
       );
@@ -120,16 +144,28 @@ export async function sweepMergedStoryBranches({
   }
 
   try {
-    return await runSweepUnderLock({
+    const reap = await runSweepUnderLock({
       cwd,
       baseBranch,
-      currentStoryBranch,
+      include,
+      exclude,
       log,
+      logTag,
       planCleanupFn,
       executeCleanupFn,
       protectionFn,
       protectionCtx,
     });
+    if (!fastForward) return reap;
+    const ff = runFastForwardStep({
+      cwd,
+      baseBranch,
+      log,
+      logTag,
+      planFastForwardFn,
+      executeFastForwardFn,
+    });
+    return { ...reap, fastForward: ff };
   } finally {
     try {
       releaseLock();
@@ -139,41 +175,73 @@ export async function sweepMergedStoryBranches({
   }
 }
 
+/**
+ * Sweep merged `story-*` branches in `cwd`. Preset over
+ * {@link sweepMergedBranches} for the boot path: it pins the `story-*`
+ * include glob, excludes the current run's `currentStoryBranch`, and
+ * keeps `fastForward` off (the boot caller fast-forwards the base branch
+ * separately). Exported name, signature, and result-envelope shape are
+ * unchanged from the pre-engine implementation.
+ *
+ * @param {{
+ *   cwd: string,
+ *   baseBranch: string,
+ *   currentStoryBranch: string,
+ *   logger?: { info?: (m: string) => void, warn?: (m: string) => void },
+ *   planCleanupFn?: typeof defaultPlanCleanup,
+ *   executeCleanupFn?: typeof defaultExecuteCleanup,
+ *   protectionFn?: typeof defaultEvaluateProtection,
+ *   protectionCtx?: object,
+ *   acquireLockFn?: typeof defaultAcquireSweepLock,
+ *   lockPath?: string|null,
+ *   lockTimeoutMs?: number,
+ * }} args
+ * @returns {Promise<object>} the {@link sweepMergedBranches} envelope.
+ */
+export function sweepMergedStoryBranches(args = {}) {
+  const { currentStoryBranch } = args;
+  const exclude =
+    typeof currentStoryBranch === 'string' && currentStoryBranch.length > 0
+      ? [currentStoryBranch]
+      : [];
+  return sweepMergedBranches({
+    ...args,
+    include: [STORY_BRANCH_INCLUDE],
+    exclude,
+    fastForward: false,
+    logTag: '[single-story-sweep]',
+  });
+}
+
 /**
  * Inner: the plan + protect + execute pipeline. Kept separate so the
- * outer `sweepMergedStoryBranches` can stay focused on the lock
- * acquire/release wrapper.
+ * outer engine can stay focused on the lock and fast-forward wrappers.
  */
 async function runSweepUnderLock({
   cwd,
   baseBranch,
-  currentStoryBranch,
+  include,
+  exclude,
   log,
+  logTag,
   planCleanupFn,
   executeCleanupFn,
   protectionFn,
   protectionCtx,
 }) {
-  const exclude =
-    typeof currentStoryBranch === 'string' && currentStoryBranch.length > 0
-      ? [currentStoryBranch]
-      : [];
-  const filter = buildGlobFilter({
-    include: [STORY_BRANCH_INCLUDE],
-    exclude,
-  });
+  const filter = buildGlobFilter({ include, exclude });
 
   let plan;
   try {
     plan = planCleanupFn({ cwd, baseBranch, filter });
   } catch (err) {
     const msg = err?.message ?? String(err);
-    log.warn(`[single-story-sweep] plan failed: ${msg}`);
+    log.warn(`${logTag} plan failed: ${msg}`);
     return zeroResult({ error: `plan: ${msg}` });
   }
 
   if (plan.candidates.length === 0) {
-    log.info('[single-story-sweep] no merged story branches to reap.');
+    log.info(`${logTag} no merged branches to reap.`);
     return {
       ok: true,
       skipped: false,
@@ -190,11 +258,12 @@ async function runSweepUnderLock({
     protectionFn,
     protectionCtx,
     log,
+    logTag,
   });
 
   if (reapable.length === 0) {
     log.info(
-      `[single-story-sweep] all ${plan.candidates.length} candidate(s) protected; no reap.`,
+      `${logTag} all ${plan.candidates.length} candidate(s) protected; no reap.`,
     );
     return {
       ok: true,
@@ -207,20 +276,41 @@ async function runSweepUnderLock({
     };
   }
 
+  return executeReap({
+    reapable,
+    protectedList,
+    candidateCount: plan.candidates.length,
+    cwd,
+    executeCleanupFn,
+    log,
+    logTag,
+  });
+}
+
+/**
+ * Execute the reap plan for the reapable candidates and shape the result
+ * envelope. Split out of {@link runSweepUnderLock} so each function keeps
+ * a single responsibility.
+ */
+function executeReap({
+  reapable,
+  protectedList,
+  candidateCount,
+  cwd,
+  executeCleanupFn,
+  log,
+  logTag,
+}) {
   let result;
   try {
-    result = executeCleanupFn({
-      candidates: reapable,
-      cwd,
-      remote: true,
-    });
+    result = executeCleanupFn({ candidates: reapable, cwd, remote: true });
   } catch (err) {
     const msg = err?.message ?? String(err);
-    log.warn(`[single-story-sweep] execute failed: ${msg}`);
+    log.warn(`${logTag} execute failed: ${msg}`);
     return {
       ok: false,
       skipped: false,
-      candidates: plan.candidates.length,
+      candidates: candidateCount,
       localDeleted: 0,
       remoteDeleted: 0,
       protected: protectedList,
@@ -241,18 +331,18 @@ async function runSweepUnderLock({
   const summary = `${localDeleted} local + ${remoteDeleted} remote${protectedSummary}`;
   if (result.ok) {
     log.info(
-      `[single-story-sweep] reaped ${summary}${reapedBranches ? ` [${reapedBranches}]` : ''}.`,
+      `${logTag} reaped ${summary}${reapedBranches ? ` [${reapedBranches}]` : ''}.`,
     );
   } else {
     log.warn(
-      `[single-story-sweep] reaped ${summary} with ${result.failures.length} failure(s) — init continues.`,
+      `${logTag} reaped ${summary} with ${result.failures.length} failure(s) — host continues.`,
     );
   }
 
   return {
     ok: result.ok,
     skipped: false,
-    candidates: plan.candidates.length,
+    candidates: candidateCount,
     localDeleted,
     remoteDeleted,
     protected: protectedList,
@@ -260,6 +350,44 @@ async function runSweepUnderLock({
   };
 }
 
+/**
+ * Best-effort fast-forward of the base branch through the git-cleanup
+ * fast-forward phase. Never throws — a failed fast-forward is logged and
+ * returned as `{ ok: false, error }` but must never fail the sweep.
+ */
+function runFastForwardStep({
+  cwd,
+  baseBranch,
+  log,
+  logTag,
+  planFastForwardFn,
+  executeFastForwardFn,
+}) {
+  try {
+    const plan = planFastForwardFn({ cwd, baseBranch });
+    const ff = executeFastForwardFn({
+      cwd,
+      baseBranch,
+      plan,
+      logger: {
+        info: (m) => log.info(m.replace(/^\[git-cleanup\]\s*/, `${logTag} `)),
+        warn: (m) => log.warn(m.replace(/^\[git-cleanup\]\s*/, `${logTag} `)),
+      },
+    });
+    return {
+      ok: ff.ok !== false,
+      applied: !!ff.applied,
+      skipped: !!ff.skipped,
+      behind: ff.behind ?? null,
+      reason: ff.reason ?? null,
+    };
+  } catch (err) {
+    const msg = err?.message ?? String(err);
+    log.warn(`${logTag} fast-forward failed: ${msg}`);
+    return { ok: false, applied: false, skipped: false, error: msg };
+  }
+}
+
 /**
  * Iterate plan candidates and split them into `reapable` (safe to pass
  * to executeCleanup) and `protectedList` (skipped, with a reason).
@@ -270,14 +398,15 @@ async function runSweepUnderLock({
  *
  * When no `protectionCtx` is supplied (legacy callers, unit tests),
  * the protection check is bypassed entirely and every candidate is
- * reapable. The CLI surface in `single-story-init.js` always supplies
- * a ctx, so this fallback never fires in production.
+ * reapable. The boot-path CLI surfaces always supply a ctx, so this
+ * fallback never fires in production.
  */
 async function partitionCandidates({
   candidates,
   protectionFn,
   protectionCtx,
   log,
+  logTag,
 }) {
   const reapable = [];
   const protectedList = [];
@@ -291,7 +420,7 @@ async function partitionCandidates({
       verdict = await protectionFn({ candidate, ctx: protectionCtx });
     } catch (err) {
       const reason = `protection-eval-error: ${err?.message ?? err}`;
-      log.warn(`[single-story-sweep] protected ${candidate.branch}: ${reason}`);
+      log.warn(`${logTag} protected ${candidate.branch}: ${reason}`);
       protectedList.push({
         branch: candidate.branch,
         reason,
@@ -300,9 +429,7 @@ async function partitionCandidates({
       continue;
     }
     if (verdict?.protected) {
-      log.info(
-        `[single-story-sweep] protected ${candidate.branch}: ${verdict.reason}`,
-      );
+      log.info(`${logTag} protected ${candidate.branch}: ${verdict.reason}`);
       protectedList.push({
         branch: candidate.branch,
         reason: verdict.reason ?? 'unknown',

package/.agents/scripts/single-story-init.js

@@ -35,7 +35,6 @@
  * @see .agents/workflows/helpers/single-story-deliver.md
  */
 
-import { spawnSync as defaultSpawnSync } from 'node:child_process';
 import { existsSync } from 'node:fs';
 import path from 'node:path';
 import { parseSprintArgs } from './lib/cli-args.js';
@@ -67,12 +66,18 @@ import {
   upsertStructuredComment,
 } from './lib/orchestration/ticketing.js';
 import { createProvider } from './lib/provider-factory.js';
+import { buildProtectionCtx } from './lib/single-story-sweep/protection-ctx.js';
 // `sweepMergedStoryBranches` is imported dynamically below — its transitive
 // graph reaches `picomatch` (via `git-cleanup.js`). Loading it statically
 // would crash module resolution before `assertDepsInstalled()` can emit a
 // friendly "run npm install" message.
 import { WorktreeManager } from './lib/worktree-manager.js';
 
+// `makeGhRunner` moved to the shared `single-story-sweep/protection-ctx.js`
+// module (Story #4373) so the three boot callers build an identical
+// protection ctx. Re-exported here to preserve its existing import path.
+export { makeGhRunner } from './lib/single-story-sweep/protection-ctx.js';
+
 /**
  * Fail fast with a clear, actionable message when project deps are missing.
  * Uses only Node builtins so it stays loadable when `node_modules/` is empty.
@@ -97,50 +102,6 @@ function assertDepsInstalled(projectRoot) {
 
 const progress = Logger.createProgress('single-story-init', { stderr: true });
 
-/**
- * Build the synchronous `gh` runner the single-story sweep uses for its
- * candidate-protection checks. Exported for testing.
- *
- * Story #2990: the sweep protection-ctx ghRunner stays on raw
- * `spawnSync('gh', …)` (not the `lib/gh-exec.js` async facade) because
- * `executeCleanup` invokes the protection checks inside a synchronous
- * candidate-filter loop. The runner contract is the legacy
- * `(args, opts) => stdout string` shape; converting it to async would
- * ripple into the single-story-sweep planner, which is intentionally out
- * of scope for the callers-only provider migration.
- *
- * Story #4073: the `spawnImpl` seam injects the `spawnSync` boundary so the
- * runner's success/error handling can be unit-tested without a live `gh`
- * binary. It defaults to `child_process.spawnSync` (mirroring the
- * `spawnImpl` seam in `lib/gh-exec.js` and the `runner` seam in
- * `lib/bootstrap/gh-preflight.js`), so the production CLI path is unchanged.
- * The synchronous `spawnSync` shape is preserved deliberately — the
- * candidate-filter loop in `executeCleanup` is synchronous, so converting
- * this to the async `lib/gh-exec.js` facade would ripple into the
- * single-story-sweep planner.
- *
- * @param {string} cwd Repo root used as the default spawn cwd.
- * @param {typeof defaultSpawnSync} [spawnImpl] Injectable spawn boundary —
- *   defaults to `child_process.spawnSync`. Tests pass a fake to assert the
- *   error/exit-code handling without spawning a real child process.
- * @returns {(args: string[], opts?: { cwd?: string }) => string}
- */
-export function makeGhRunner(cwd, spawnImpl = defaultSpawnSync) {
-  return (args, opts) => {
-    const result = spawnImpl('gh', args, {
-      cwd: opts?.cwd ?? cwd,
-      encoding: 'utf-8',
-      shell: false,
-    });
-    if (result.status !== 0) {
-      throw new Error(
-        `gh ${args.join(' ')} exit ${result.status}: ${result.stderr ?? ''}`,
-      );
-    }
-    return result.stdout ?? '';
-  };
-}
-
 /**
  * Validate that the fetched ticket is a standalone Story this script can
  * deliver. Throws with the canonical operator-facing message otherwise.
@@ -222,12 +183,7 @@ export async function reapMergedStoryBranches({
         info: (m) => progress('CLEANUP', m),
         warn: (m) => progress('CLEANUP', `⚠️ ${m}`),
       },
-      protectionCtx: {
-        repoRoot: cwd,
-        gitSpawn,
-        ghRunner: makeGhRunner(cwd),
-        getTicket: (id) => provider.getTicket(id),
-      },
+      protectionCtx: buildProtectionCtx({ cwd, provider }),
       lockPath,
       lockTimeoutMs,
     });

package/.agents/workflows/git-deliver.md

@@ -70,6 +70,33 @@ it is about to run** before it acts.
 
 ---
 
+## Boot sweep
+
+Before detecting the git setup, run the **protected boot sweep** so
+`/git-deliver` starts from a tidy local checkout — a feature branch this
+command opened and pushed on a prior run, once its PR has merged, is reaped
+here rather than left to accumulate:
+
+```bash
+node .agents/scripts/boot-sweep.js \
+  --include 'feat/*' --include 'fix/*' --include 'chore/*' \
+  --include 'docs/*' --include 'refactor/*' \
+  --current "$(git rev-parse --abbrev-ref HEAD)"
+```
+
+This is the **safe subset** of the `/git-cleanup` phases: it fast-forwards the
+base branch (`main`), prunes stale remote-tracking refs, and reaps every local
+branch whose PR is **merged** and whose HEAD matches the merged `headRefOid`.
+It **never** touches the stash stack, and its `evaluateProtection` partition
+skips (never reaps) any candidate with unpushed work, a dirty worktree, or a
+still-open parent ticket; `--current` always excludes the branch you are on.
+The sweep is **silent on a no-op** — nothing merged, `main` already current →
+one summary line (`[boot-sweep] reaped 0 local + 0 remote; protected 0.`). Its
+exit code is always `0`; a failed sweep is reported in that summary, never
+allowed to fail the delivery run.
+
+---
+
 ## Step 0 — Detect Git Setup & Resolve Level
 
 1. Resolve `[BASE_BRANCH]` from `--base` or `.agentrc.json` →
@@ -248,6 +275,15 @@ Do **not** poll CI. That is the `/deliver` Phase 7 job and is overkill for
 ad-hoc changes. The operator (or GitHub's email notification) is the next
 watcher.
 
+> **Local ref left behind — reaped at the next boot.** At the **pr** level
+> this command leaves a local feature branch behind after the PR merges; it
+> does **not** reap it inline (the merge happens later, out of band). You do
+> not need to run `/git-cleanup` by hand: the next time `/git-deliver` (or
+> `/plan`) runs, its **Boot sweep** step reaps that merged ad-hoc branch and
+> fast-forwards `main` automatically. The delivering flow owns tidying its own
+> refs on the next boot — see
+> [`.agents/rules/git-conventions.md` § Local checkout hygiene](../rules/git-conventions.md).
+
 ---
 
 ## Troubleshooting

package/.agents/workflows/helpers/deliver-epic-reference.md

@@ -509,20 +509,26 @@ node .agents/scripts/lifecycle-emit.js --epic <epicId> \
 
 If Phase 8.5 fell back to the operator-merges-button path (`gh pr
 merge --auto` was declined), the `epic.merge.armed` event never fires
-inside this run and Phase 9 will not run automatically. After the
-operator merges the PR, `epic/<epicId>` and each `story-<id>` ref can
-be reaped manually:
+inside this run and Phase 9 will not run automatically. **Do not** hand-reap
+the refs with a raw `git branch -D` sequence — drive the same
+`BranchCleaner`-backed reap the auto-merge path uses by firing
+`epic.merge.armed` after the operator merges the PR:
 
 ```bash
-git checkout main
-git pull --ff-only origin main
-git branch -D epic/<epicId>
-git branch -D story-<id1> story-<id2> ...
-git remote prune origin
+node .agents/scripts/lifecycle-emit.js --epic <epicId> \
+  --event epic.merge.armed --pr-url <prUrl>
 ```
 
-Note that `git-cleanup.js` alone will not catch `story-<id>` refs in
-this case because the epic PR squash-merges break the `git branch
---merged main` signal and the stories never had their own PRs. Wiring
-a CLI surface that drives the BranchCleaner listener for this
-fallback is tracked as follow-up to Story #2398.
+That single emit reaps `epic/<epicId>` and every `story-<id>` ref from the
+checkpoint, prunes stale tracking refs, and fast-forwards local `main` to
+`origin/main` — the whole Phase 9 reap, not a partial hand-roll. A plain
+`git-cleanup.js` sweep alone will **not** catch the `story-<id>` refs here,
+because the epic PR squash-merge breaks the `git branch --merged main` signal
+and the stories never had their own PRs; the lifecycle-emit surface above is
+the correct driver.
+
+Re-running `/deliver <epicId>` reaches the same outcome without the manual
+emit: the idempotent-resume auto-arm
+(`detectMergedUncleanedEpic` → `armCleanupIfMerged` in
+[`epic-cleanup.js`](../../scripts/lib/orchestration/epic-cleanup.js)) detects
+the merged-but-uncleaned Epic and fires `epic.merge.armed` for you.

package/.agents/workflows/helpers/deliver-epic.md

@@ -734,6 +734,18 @@ On an arming decision the predicate emits `epic.merge.ready`; the downstream
 `epic.merge.blocked` with the disqualifying reasons and exits without merging
 — the operator merges manually.
 
+**Blocked-path output (operator merges the button).** When arming is
+declined, `epic.merge.armed` never fires inside this run, so Phase 9 does not
+reap automatically. Surface the exact one-liner the operator runs **after**
+they merge the PR by hand so local refs are reaped and `main` is
+fast-forwarded (the idempotent-resume path below runs this automatically on
+the next `/deliver <epicId>`):
+
+```bash
+node .agents/scripts/lifecycle-emit.js --epic <epicId> \
+  --event epic.merge.armed --pr-url <prUrl>
+```
+
 Close the phase wrapper by emitting `epic.automerge.end` (records the arm
 outcome on the ledger; `merged: true` once GitHub completes the squash,
 `merged: false` with a reason otherwise):
@@ -784,6 +796,19 @@ via `helpers/epic-deliver-story`'s own checkpointing). The PR from Phase 7 is
 updated in place on subsequent runs. The authoritative live view is
 the `epic-run-progress` structured comment.
 
+**Resume auto-arm for a merged-but-uncleaned Epic.** When `/deliver` resumes
+against an Epic whose PR already merged (operator merged the button in a prior
+session) but whose local `epic/<id>` / `story-<id>` refs still linger, the
+resume path detects the merged-but-uncleaned state
+(`detectMergedUncleanedEpic` in
+[`epic-cleanup.js`](../../scripts/lib/orchestration/epic-cleanup.js)) and fires
+`epic.merge.armed` automatically so Phase 9 reaps — no manual command. The
+detection is idempotent: an already-reaped Epic (no local refs) is a clean
+no-op, and an unmerged Epic never arms. It resolves the merged PR's URL for the
+required `epic.merge.armed` payload and fails closed (does **not** arm) on any
+indeterminate `gh` probe. The one-liner under Phase 8.5 / Phase 9 is the manual
+equivalent for the case where the operator does not re-run `/deliver`.
+
 ---
 
 ## Constraints

package/.agents/workflows/helpers/deliver-stories.md

@@ -318,11 +318,24 @@ Print a final run summary listing every delivered Story in completion order:
 All Stories delivered. PRs opened, auto-merge armed. CI will merge each
 PR when checks pass; each child then confirms the merge and flips its
 Story to `agent::done` (Story #3385 — until the merge confirms, a Story
-rests at `agent::closing` with its issue OPEN). Run
-`git-cleanup --fast-forward-main` after the last merge to bring local
-main up to date.
+rests at `agent::closing` with its issue OPEN).
 ```
 
+Then **fast-forward `main` yourself** — do not instruct the operator to run it
+after the last merge. The delivering flow owns bringing the local base branch
+up to whatever has merged so far:
+
+```bash
+node .agents/scripts/git-cleanup.js --fast-forward-main --execute --yes
+```
+
+This runs only the fast-forward-main phase (`git fetch origin main` →
+`git merge --ff-only`); it is idempotent and a no-op when `main` is already
+current, so it is safe to run even while some PRs are still queued in
+auto-merge. Report its one-line result in the summary. Merged Story branches
+themselves are reaped by the boot sweep at the next `/plan` / `/deliver` boot —
+see [`.agents/rules/git-conventions.md` § Local checkout hygiene](../../rules/git-conventions.md).
+
 When some Stories are blocked or failed, list them explicitly with the
 `blockerCommentId` or failure detail so the operator knows where to look.