mandrel 1.94.0 → 2.1.0

package/.agents/scripts/lib/orchestration/consolidation-precondition.js

@@ -12,7 +12,7 @@
  * reconcile — dispatching it is pure token spend for a no-op. This module
  * computes that decision **deterministically**, off the same two inputs the
  * critic itself reads (the draft array and the Epic body's Delivery Slicing
- * table), so `helpers/plan-epic.md` Phase 8.3 can skip the sub-agent
+ * table), so the planning workflow can skip the sub-agent
  * dispatch when it is provably safe to.
  *
  * **Fail-open by design.** Every ambiguous case — a missing or unparseable
@@ -30,7 +30,7 @@
  * Epic body off disk / the GitHub API.
  */
 
-import { DELIVERY_SLICING_RE as DELIVERY_SLICING_HEADING_RE } from '../epic-body-sections.js';
+import { DELIVERY_SLICING_RE as DELIVERY_SLICING_HEADING_RE } from '../ticket-body-sections.js';
 
 /** A row is a markdown table line: starts with `|` once trimmed. */
 const TABLE_ROW_RE = /^\|/;
@@ -123,7 +123,7 @@ export function parseDeliverySlicingTable(epicBody) {
 
 /**
  * True when `story` is the recognized wave-0 BDD scaffold Story — identified
- * by the literal `bdd-scaffold` goal token the `epic-plan-decompose-author`
+ * by the literal `bdd-scaffold` goal token the decomposer prompt
  * skill's WAVE-0 BDD SCAFFOLD STORY section requires. Scaffold Stories are
  * not a Delivery Slicing slice, so they are excluded from the count
  * comparison — BDD-adopting consumer repos still benefit from the
@@ -145,7 +145,7 @@ function isBddScaffoldStory(story) {
  *
  * @param {object} input
  * @param {object[]} input.draftStories - The draft `tickets.json` array
- *   (`epic-plan-decompose-author`'s output) — raw Story ticket objects with
+ *   (the decomposer's output) — raw Story ticket objects with
  *   top-level `slug` / `depends_on` / `body` (serialized string).
  * @param {string} input.epicBody - The Epic body carrying the folded Tech
  *   Spec sections (`## Delivery Slicing` onward).

package/.agents/scripts/lib/orchestration/context-envelope.js

@@ -8,7 +8,7 @@
  * @module lib/orchestration/context-envelope
  */
 
-/** @typedef {'protocolPolicy' | 'persona' | 'skillCapsules' | 'hierarchy' | 'acceptanceCriteria' | 'verificationCommands' | 'taskInstructions'} SectionName */
+/** @typedef {'protocolPolicy' | 'skillCapsules' | 'hierarchy' | 'acceptanceCriteria' | 'verificationCommands' | 'taskInstructions'} SectionName */
 
 /**
  * @typedef {object} SectionSource
@@ -37,7 +37,7 @@
 /**
  * @typedef {object} ContextEnvelope
  * @property {'1'} schemaVersion
- * @property {{ id: number, title: string, persona?: string, skills?: string[], protocolVersion?: string }} task
+ * @property {{ id: number, title: string, skills?: string[], protocolVersion?: string }} task
  * @property {Section[]} sections
  * @property {TicketSnapshot[]} provenance
  * @property {{ maxTokens: number, used: number, elided: string[] }} budget
@@ -51,7 +51,6 @@ export const PROMPT_SECTION_SEPARATOR =
 /** Rendering order for {@link envelopeToPrompt} (not elision priority). */
 export const SECTION_RENDER_ORDER = Object.freeze([
   'protocolPolicy',
-  'persona',
   'skillCapsules',
   'hierarchy',
   'acceptanceCriteria',
@@ -65,7 +64,6 @@ export const DEFAULT_SECTION_PRIORITIES = Object.freeze({
   hierarchy: 20,
   acceptanceCriteria: 30,
   verificationCommands: 40,
-  persona: 50,
   protocolPolicy: 80,
   taskInstructions: 100,
 });
@@ -76,7 +74,6 @@ export const DEFAULT_ELIDE_POLICIES = Object.freeze({
   hierarchy: 'summarize',
   acceptanceCriteria: 'summarize',
   verificationCommands: 'drop',
-  persona: 'summarize',
   protocolPolicy: 'drop',
   taskInstructions: 'drop',
 });

package/.agents/scripts/lib/orchestration/deliver-recover.js

@@ -0,0 +1,328 @@
+/**
+ * deliver-recover.js — probe a stranded Story and name its ONE next command
+ * (Story #4543).
+ *
+ * Recovery here is a **read, not a repair**. Every input is already
+ * probeable — labels and lease from the ticket, the branch locally and via
+ * its tracking ref, the worktree path, the PR by head branch (with state,
+ * merge, and checks probes) — so this module is probes, a decision table
+ * over `label × PR × branch × worktree`, and one command with the evidence it
+ * was derived from. It never mutates anything, and it never prints a menu of
+ * options: a menu is what an operator already has, and it is the thing they
+ * cannot act on.
+ *
+ * The strand shapes the table resolves, and why each is real:
+ *
+ *   - `executing` with no PR → resume implementation. The work never reached
+ *     close.
+ *   - `closing` with a pending PR → resume the land. The overwhelmingly
+ *     common shape now that the merge wait is bounded: the wait returned
+ *     `pending` and something has to pick it back up.
+ *   - `closing` with a red PR → enter the fix loop. Waiting is pointless; no
+ *     budget turns a failed check green.
+ *   - `closing` with a MERGED PR → run confirm. **This is the strand a
+ *     `/deliver` re-run refuses outright**, because `single-story-init.js`
+ *     hard-errors on an already-closed Story — so before this surface, the
+ *     merged-but-label-stale Story had no automated way back.
+ *   - `done` with a drifted board → run resync. The GitHub Projects bot won
+ *     the race.
+ *   - `blocked` → print the class-specific remediation the friction comment
+ *     already names, rather than inventing a second opinion about a
+ *     condition that was already classified.
+ *
+ * The command vocabulary is shared with the terminal envelope
+ * (`story-deliver-terminal.js#NEXT_COMMANDS`), so recovery and normal
+ * resumption speak one language instead of two dialects for one state.
+ */
+
+import { gh as defaultGh } from '../gh-exec.js';
+import { gitSpawn as defaultGitSpawn, getStoryBranch } from '../git-utils.js';
+import { deriveChecksStatus } from './merge-poll.js';
+import { NEXT_COMMANDS } from './story-deliver-terminal.js';
+import { STATE_LABELS } from './ticketing.js';
+
+/**
+ * Probe the ticket: state labels, issue open/closed, and the lease holder.
+ *
+ * @returns {Promise<object>}
+ */
+export async function probeTicket({ provider, storyId }) {
+  try {
+    const ticket = await provider.getTicket(storyId);
+    const labels = Array.isArray(ticket?.labels) ? ticket.labels : [];
+    const stateLabel =
+      labels.find((l) => typeof l === 'string' && l.startsWith('agent::')) ??
+      null;
+    return {
+      ok: true,
+      stateLabel,
+      labels,
+      issueState: ticket?.state ?? null,
+      title: ticket?.title ?? null,
+      lease: ticket?.assignees?.[0] ?? ticket?.assignee ?? null,
+    };
+  } catch (err) {
+    return { ok: false, error: String(err?.message ?? err) };
+  }
+}
+
+/**
+ * Probe the Story branch locally and its remote tracking ref, plus the
+ * worktree path. Pure git — no network.
+ *
+ * @returns {object}
+ */
+export function probeBranch({ cwd, storyBranch, config, gitSpawnFn }) {
+  const spawn = gitSpawnFn ?? defaultGitSpawn;
+  const localRef = spawn(
+    cwd,
+    'show-ref',
+    '--verify',
+    '--quiet',
+    `refs/heads/${storyBranch}`,
+  );
+  const remoteRef = spawn(
+    cwd,
+    'show-ref',
+    '--verify',
+    '--quiet',
+    `refs/remotes/origin/${storyBranch}`,
+  );
+  const worktreeRoot =
+    config?.delivery?.worktreeIsolation?.root ?? '.worktrees';
+  const worktrees = spawn(cwd, 'worktree', 'list', '--porcelain');
+  const worktreePath =
+    worktrees.status === 0 &&
+    typeof worktrees.stdout === 'string' &&
+    worktrees.stdout.includes(`${worktreeRoot}/${storyBranch}`)
+      ? `${worktreeRoot}/${storyBranch}`
+      : null;
+  return {
+    local: localRef.status === 0,
+    remote: remoteRef.status === 0,
+    worktreePath,
+  };
+}
+
+/**
+ * Probe the PR for the Story branch. `--state all` is required: a merged PR
+ * is no longer `open`, and the merged-but-label-stale strand is precisely
+ * the one that matters most here.
+ *
+ * @returns {Promise<object|null>}
+ */
+export async function probePr({ storyBranch, gh = defaultGh }) {
+  try {
+    const rows = await gh.pr.list(
+      ['--head', storyBranch, '--state', 'all'],
+      ['number', 'url', 'state', 'mergedAt', 'statusCheckRollup'],
+    );
+    if (!Array.isArray(rows) || rows.length === 0) return null;
+    const row = rows[0];
+    return {
+      number: Number(row?.number) || null,
+      url: row?.url ?? null,
+      state: row?.state ?? null,
+      mergedAt: row?.mergedAt ?? null,
+      checksStatus: deriveChecksStatus(row?.statusCheckRollup),
+    };
+  } catch (err) {
+    return { error: String(err?.message ?? err) };
+  }
+}
+
+/**
+ * The decision table. Pure: every input is an already-observed probe, so the
+ * mapping is testable without git, GitHub, or a clock.
+ *
+ * Returns exactly one `{ shape, nextCommand, evidence[], detail }` — never a
+ * list of candidates.
+ *
+ * @param {{ storyId: number, ticket: object, branch: object, pr: object|null }} probes
+ * @returns {{ shape: string, nextCommand: string|null, detail: string, evidence: string[] }}
+ */
+export function decideRecovery({ storyId, ticket, branch, pr }) {
+  const evidence = [
+    `label=${ticket?.stateLabel ?? 'none'}`,
+    `issue=${ticket?.issueState ?? 'unknown'}`,
+    `pr=${pr?.number ? `#${pr.number} ${pr.state ?? '?'}` : 'none'}`,
+    `checks=${pr?.checksStatus ?? 'n/a'}`,
+    `branch.local=${branch?.local ?? false}`,
+    `branch.remote=${branch?.remote ?? false}`,
+    `worktree=${branch?.worktreePath ?? 'none'}`,
+    `lease=${ticket?.lease ?? 'unclaimed'}`,
+  ];
+
+  const label = ticket?.stateLabel;
+  const merged = pr?.state === 'MERGED' || Boolean(pr?.mergedAt);
+
+  // A merged PR outranks every label reading. The code is on the base
+  // branch; whatever the label says, the only thing left is the flip + tail.
+  if (merged && label !== STATE_LABELS.DONE) {
+    return {
+      shape: 'merged-label-stale',
+      nextCommand: NEXT_COMMANDS.confirmMerge(storyId),
+      detail:
+        `PR #${pr.number} is MERGED but the Story is at \`${label ?? 'no state label'}\`. ` +
+        `A /deliver re-run cannot fix this — single-story-init.js hard-errors on an ` +
+        `already-closed Story. The confirm CLI is idempotent and flips the label from ` +
+        `the already-merged PR, then runs the land tail.`,
+      evidence,
+    };
+  }
+
+  if (label === STATE_LABELS.BLOCKED) {
+    return {
+      shape: 'blocked',
+      nextCommand: NEXT_COMMANDS.recover(storyId),
+      detail:
+        `Story is at \`agent::blocked\`. The block was already classified when it was ` +
+        `filed — read the \`friction\` comment on #${storyId} for the class-specific ` +
+        `remediation, resolve it, then transition back to \`agent::executing\`. ` +
+        `Re-run this probe afterwards to confirm the strand cleared.`,
+      evidence,
+    };
+  }
+
+  if (label === STATE_LABELS.DONE) {
+    return {
+      shape: 'done-board-drift',
+      nextCommand: NEXT_COMMANDS.resync(storyId),
+      detail:
+        `Story is \`agent::done\`. Nothing to deliver. If the Projects board still shows ` +
+        `it as In Progress, the GitHub built-in workflow won the post-merge race; the ` +
+        `resync re-asserts the column and is a no-op otherwise.`,
+      evidence,
+    };
+  }
+
+  if (label === STATE_LABELS.CLOSING) {
+    if (pr?.checksStatus === 'failure') {
+      return {
+        shape: 'closing-pr-red',
+        nextCommand: NEXT_COMMANDS.watchCi(storyId, pr.number),
+        detail:
+          `PR #${pr.number} has a red required check. Waiting cannot help — fix the ` +
+          `failure and push a new commit on \`story-${storyId}\`; auto-merge stays armed ` +
+          `across retries.`,
+        evidence,
+      };
+    }
+    if (pr?.number) {
+      return {
+        shape: 'closing-pr-pending',
+        nextCommand: NEXT_COMMANDS.resumeLand(storyId),
+        detail:
+          `PR #${pr.number} is open and healthy. This is the normal resumable shape after ` +
+          `a bounded merge wait returned \`pending\`. The confirm CLI polls it to a ` +
+          `confirmed merge and runs the land tail.`,
+        evidence,
+      };
+    }
+    return {
+      shape: 'closing-no-pr',
+      nextCommand: NEXT_COMMANDS.close(storyId),
+      detail:
+        `Story is at \`agent::closing\` but no PR exists for \`story-${storyId}\`. The ` +
+        `close did not reach the pull-request phase; re-run it (close is idempotent and ` +
+        `reuses an existing PR when one is found).`,
+      evidence,
+    };
+  }
+
+  if (label === STATE_LABELS.EXECUTING) {
+    if (pr?.number) {
+      return {
+        shape: 'executing-with-pr',
+        nextCommand: NEXT_COMMANDS.close(storyId),
+        detail:
+          `PR #${pr.number} exists but the Story is still \`agent::executing\` — the close ` +
+          `opened the PR and then died before the label flip. Re-run close; it reuses the ` +
+          `open PR rather than opening a duplicate.`,
+        evidence,
+      };
+    }
+    return {
+      shape: 'executing-no-pr',
+      nextCommand: NEXT_COMMANDS.implement(storyId),
+      detail:
+        `Story is \`agent::executing\` with no PR. Implementation never finished. Re-init ` +
+        `(idempotent — it reuses the existing branch and worktree) and resume in the ` +
+        `worktree it prints.`,
+      evidence,
+    };
+  }
+
+  return {
+    shape: 'ready',
+    nextCommand: NEXT_COMMANDS.close(storyId),
+    detail:
+      `Story is at \`${label ?? 'no agent:: state label'}\` — not mid-delivery, so there ` +
+      `is no strand to recover. Deliver it normally via /deliver ${storyId}.`,
+    evidence,
+  };
+}
+
+/**
+ * Probe live state and resolve the single next command. Read-only.
+ *
+ * @param {object} args
+ * @param {number} args.storyId
+ * @param {string} args.cwd
+ * @param {object} args.provider
+ * @param {object} [args.config]
+ * @param {object} [args.gh]
+ * @param {Function} [args.gitSpawnFn]
+ * @returns {Promise<object>}
+ */
+export async function recoverStory({
+  storyId,
+  cwd,
+  provider,
+  config,
+  gh = defaultGh,
+  gitSpawnFn,
+}) {
+  const storyBranch = getStoryBranch(storyId);
+  const ticket = await probeTicket({ provider, storyId });
+  if (!ticket.ok) {
+    throw new Error(
+      `deliver-recover: could not read Story #${storyId}: ${ticket.error}`,
+    );
+  }
+  const branch = probeBranch({ cwd, storyBranch, config, gitSpawnFn });
+  const pr = await probePr({ storyBranch, gh });
+  const decision = decideRecovery({ storyId, ticket, branch, pr });
+  return {
+    storyId,
+    storyBranch,
+    probes: { ticket, branch, pr },
+    ...decision,
+  };
+}
+
+/**
+ * Render the operator-facing report: the shape, the one command, and the
+ * evidence it was derived from — so the operator can check the reasoning
+ * rather than trust it.
+ *
+ * @param {object} recovery
+ * @returns {string}
+ */
+export function renderRecovery(recovery) {
+  const lines = [
+    `Story #${recovery.storyId} — ${recovery.shape}`,
+    '',
+    recovery.detail,
+    '',
+    'Evidence:',
+    ...recovery.evidence.map((e) => `  - ${e}`),
+    '',
+  ];
+  if (recovery.nextCommand) {
+    lines.push('Next command:', `  ${recovery.nextCommand}`, '');
+  } else {
+    lines.push('Next command: none — nothing to do.', '');
+  }
+  return lines.join('\n');
+}

package/.agents/scripts/lib/orchestration/detectors-phase.js

@@ -1,7 +1,12 @@
 /**
- * detectors-phase.js — pure post-merge phase that runs the per-Story
- * signal detectors (rework + retry) before `analyze-execution.js` shells
- * out to render the `<!-- structured:story-perf-summary -->` comment.
+ * detectors-phase.js — pure phase that runs the per-Story signal detectors
+ * (rework + retry) over the local NDJSON stream.
+ *
+ * Story #4545 — this phase has no production caller. Its sequencer
+ * (`post-merge-pipeline.js`) went in the v2.0.0 cutover, and the
+ * `analyze-execution.js` consumer it fed was deleted with the
+ * execution-analysis surface. Kept alive only by its own test — the
+ * test-importer blind spot the dead-exports ratchet cannot see.
  *
  * Extracted from `post-merge-pipeline.js` (Story #1770 / Task #1779) to
  * keep the parent sequencer's maintainability score above its baseline
@@ -39,8 +44,9 @@
  * @module lib/orchestration/detectors-phase
  */
 
+import path from 'node:path';
 import { getSignals } from '../config/limits.js';
-import { storyArtifactPath } from '../config/temp-paths.js';
+import { storyTempDir } from '../config/temp-paths.js';
 import { Logger } from '../Logger.js';
 import { appendSignal } from '../observability/signals-writer.js';
 import { detectRetry, detectRework } from '../signals/detectors/index.js';
@@ -114,7 +120,7 @@ function isValidIdPair(eid, sid) {
 
 /**
  * Run the rework + retry detectors for one Story and persist every
- * emission to `temp/epic-<eid>/stories/story-<sid>/signals.ndjson`.
+ * emission to `temp/run-<id>/stories/story-<sid>/signals.ndjson`.
  *
  * @param {{
  *   epicId: number|string,
@@ -159,7 +165,7 @@ export async function detectorsPhase(ctx) {
     return { rework: 0, retry: 0 };
   }
 
-  const tracesPath = storyArtifactPath(eid, sid, 'traces.ndjson', config);
+  const tracesPath = path.join(storyTempDir(eid, sid, config), 'traces.ndjson');
   const taskId = resolveLastTaskId(tasks);
   const baseArgs = { tracesPath, epicId: eid, storyId: sid, taskId };
   const common = {

package/.agents/scripts/lib/orchestration/docs-digest.js

@@ -1,5 +1,5 @@
 /**
- * docs-digest.js — per-Epic docs digest builder (Story #4338).
+ * docs-digest.js — per-run docs digest builder (Story #4338).
  *
  * `/deliver` story sub-agents previously re-read every file in
  * `project.docsContextFiles` on every Story, re-paying the full docs payload
@@ -16,8 +16,8 @@
  * Story #4433 extends this module with {@link ensureDocsDigest}, a shared
  * generate-and-write export so the planner-context surface
  * (`plan-context.js` / `authoring-context.js`) can produce a session docs
- * digest without duplicating the mkdir+writeFile plumbing
- * `epic-deliver-prepare.js` already owns for the delivery-children digest.
+ * digest without duplicating the mkdir+writeFile plumbing shared by
+ * `plan-context.js` / `authoring-context.js` and the `/deliver` workflow.
  */
 
 import fs from 'node:fs';
@@ -110,7 +110,7 @@ function renderDocSection(doc) {
 }
 
 /**
- * Build the per-Epic docs digest markdown from the configured docs context
+ * Build the per-run docs digest markdown from the configured docs context
  * files. Missing files are skipped silently (the read seam returns only the
  * files it could stat + read). Returns `null` when there is nothing to digest
  * — i.e. `docsContextFiles` is empty/unset — so callers surface a null
@@ -130,7 +130,7 @@ export async function buildDocsDigest({ docsContextFiles, docsRoot } = {}) {
   const header = [
     '# Docs digest',
     '',
-    'Per-Epic outline of the project docs context set. Each entry lists the',
+    'Per-run outline of the project docs context set. Each entry lists the',
     'file path, byte size, and its heading outline (with line numbers) plus',
     'the first paragraph under each `##` section. Read the full file on demand',
     'when a section looks relevant — do **not** ingest the whole set per Story.',
@@ -144,10 +144,10 @@ export async function buildDocsDigest({ docsContextFiles, docsRoot } = {}) {
 /**
  * Build the docs digest and write it to `outputPath`, returning `null` (no
  * write) when there is nothing to digest. This is the single shared
- * generate-and-persist export both digest producers call: the per-Epic
- * delivery-children digest (`epic-deliver-prepare.js`) and the planner-
+ * generate-and-persist export both digest producers call: the per-run
+ * `/deliver` docs digest (`helpers/deliver-story.md`) and the planner-
  * context digest (`plan-context.js` → `authoring-context.js`, Story
- * #4433). Callers own path construction (temp-root layout, epic id, etc.)
+ * #4433). Callers own path construction (temp-root layout, run id, etc.)
  * so both surfaces can keep — or deliberately share — their own convention;
  * this function only owns "build digest, ensure parent dir, write file".
  *

package/.agents/scripts/lib/orchestration/file-assumptions.js

@@ -45,11 +45,10 @@
  * the shared-editor conflict gate's domain — that finding's rendering is
  * cross-referenced (see `renderMismatch`), not duplicated here.
  *
- * Legacy compatibility: stories whose `body.changes` items are still bare
- * strings carry no assumption and are skipped silently here. The
- * deprecation signal is emitted *once* per validator invocation through
- * `collectDeprecationWarnings`, so consumers running an older planner
- * see a clear migration nudge without a hard failure mid-flight.
+ * String bullets: stories whose `body.changes` items are still bare
+ * strings are hard errors — they are pushed to `errors[]` by the
+ * validator's body-shape gate before this module runs. There is no
+ * silent skip or deprecation nudge.
  */
 
 import { gitSpawn } from '../git-utils.js';
@@ -319,21 +318,16 @@ export function validateStoryFileAssumptions(opts) {
     const entries = collectStoryAssumptionEntries(story);
 
     if (entries.length === 0) {
-      // Legacy path: this Story carries no object-form entries. Emit a
-      // single deprecation warning so the operator sees the migration
-      // nudge once per Story rather than per-bullet.
       if (hasLegacyChangeBullets(story)) {
-        warnings.push(
-          `"${slug}" → body.changes uses legacy string bullets without { path, assumption }. Migrate to object form so Phase 8 can verify file-state assumptions. See Story #2636.`,
+        errors.push(
+          `"${slug}" → body.changes uses legacy string bullets without { path, assumption }. Migrate every bullet to object form so Phase 8 can verify file-state assumptions. See Story #2636.`,
         );
       }
       continue;
     }
 
-    // Partial-migration warning: some entries are object-form, some are
-    // still strings. Surface once so the operator notices the gap.
     if (hasLegacyChangeBullets(story)) {
-      warnings.push(
+      errors.push(
         `"${slug}" → body.changes mixes object-form entries with legacy string bullets. Migrate every bullet for full freshness coverage.`,
       );
     }

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

@@ -26,7 +26,7 @@ function resolveBaseBranch(cwd, override) {
   if (override) return override;
   try {
     const cfg = resolveConfig({ cwd });
-    return cfg?.project?.baseBranch || cfg?.agentSettings?.baseBranch || 'main';
+    return cfg?.project?.baseBranch || 'main';
   } catch {
     return 'main';
   }

package/.agents/scripts/lib/orchestration/git-cleanup/phases/fast-forward.js

@@ -59,6 +59,36 @@ export function planFastForward(ctx) {
   return { runnable: true, behind: ff.behind, currentBranch: cur };
 }
 
+/**
+ * Return HEAD to the branch it started on.
+ *
+ * {@link maybeCheckout} moves the checkout to `baseBranch` so `merge
+ * --ff-only` has somewhere to land. Leaving it there silently relocates the
+ * operator: this phase runs from the MAIN checkout — which may be parked on
+ * unrelated work — and the close tail can reach it long after the operator
+ * walked away (a belated `single-story-confirm-merge --wait`, for instance).
+ * Fast-forwarding the base branch is the contract every delivering flow owes
+ * the checkout; moving someone off the branch they were using is not, and it
+ * is the kind of surprise that gets subsequent work committed to the wrong
+ * branch.
+ *
+ * Best-effort: a failed restore warns and never fails the phase — the
+ * fast-forward already succeeded, and `planFastForward` refuses on a dirty
+ * tree, so nothing uncommitted is ever at risk here.
+ */
+function restoreBranchIfMoved({ plan, baseBranch, cwd, checkoutFn, logger }) {
+  const original = plan.currentBranch;
+  if (!original || original === baseBranch) return;
+  const co = checkoutFn(cwd, original);
+  if (!co.ok) {
+    logger.warn?.(
+      `${TAG} ⚠️ checkout left on ${baseBranch}: restoring ${original} failed: ${co.stderr}`,
+    );
+    return;
+  }
+  logger.info?.(`${TAG} ↩️  restored checkout to ${original}`);
+}
+
 function maybeCheckout({ plan, baseBranch, cwd, checkoutFn, logger }) {
   if (!plan.currentBranch || plan.currentBranch === baseBranch) {
     return { ok: true };
@@ -108,6 +138,9 @@ export function executeFastForward(ctx) {
     logger.warn?.(
       `${TAG} ❌ merge --ff-only ${ref} failed: ${mergeRes.stderr}`,
     );
+    // We already moved HEAD to run the merge; put it back even on the
+    // failure path rather than stranding the operator on the base branch.
+    restoreBranchIfMoved({ plan, baseBranch, cwd, checkoutFn, logger });
     return {
       ok: false,
       applied: false,
@@ -119,5 +152,6 @@ export function executeFastForward(ctx) {
   logger.info?.(
     `${TAG} ✅ fast-forwarded ${baseBranch} by ${plan.behind} commit(s)`,
   );
+  restoreBranchIfMoved({ plan, baseBranch, cwd, checkoutFn, logger });
   return { ok: true, applied: true, skipped: false, behind: plan.behind };
 }

package/.agents/scripts/lib/orchestration/lease-guard-shared.js

@@ -2,8 +2,9 @@
  * lease-guard-shared.js — Story #3992: single-source the lease-acquisition
  * kernel shared by the three per-surface lease guards.
  *
- * `epic-deliver-lease-guard.js`, `epic-plan-lease-guard.js`, and
- * `single-story-lease-guard.js` historically each carried their own copy of
+ * The per-surface lease guards — today `single-story-lease-guard.js`;
+ * historically also the retired Epic-tier deliver/plan guards —
+ * each carried their own copy of
  * the operator-handle resolution and the fail-closed acquire wrapper around
  * `ticket-lease.acquireLease` (anchor `heartbeatAt` to `now` so a foreign
  * assignee always reads as a live claim, then throw an operator-facing