mandrel 1.94.0 → 2.1.0

package/.agents/scripts/lib/format-generated-json.js

@@ -0,0 +1,97 @@
+/**
+ * format-generated-json.js — run generated JSON through the project
+ * formatter (Biome) so a generator's output matches what the repo's
+ * commit-time formatting would have produced anyway.
+ *
+ * Why this exists. Generators serialize with `JSON.stringify`, which
+ * expands every array across multiple lines. Biome collapses short ones
+ * that fit inside `lineWidth` (`"allowedTools": ["Read", "Bash"]`), and
+ * lint-staged runs `biome format --write` over staged JSON at commit
+ * time — so the committed artifact is Biome-shaped while a fresh
+ * generator run is not. The gap means regenerating on a clean tree
+ * always leaves format drift, and a `<generate>` → `lint` sequence fails
+ * on `biome ci` even when the generator's own `--check` reports the
+ * artifact semantically fresh (Story #4546).
+ *
+ * Running the real formatter, rather than hand-matching its array
+ * collapsing, keeps this correct by construction across future formatter
+ * and `lineWidth` changes.
+ *
+ * Stdin mode is deliberate: Biome's configured `formatWrite` command is
+ * whole-tree (`biome format --write .`), which is a far broader side
+ * effect than a generator should have. `--stdin-file-path` makes this a
+ * pure content transform with no filesystem writes.
+ */
+
+import { spawnSync } from 'node:child_process';
+import process from 'node:process';
+import { Logger } from './Logger.js';
+
+/** Wall-clock ceiling for the formatter spawn, so a hung child cannot wedge a generator run. */
+const FORMATTER_TIMEOUT_MS = 30_000;
+
+/**
+ * Warn once about a fallback and return null for the caller to act on.
+ * Owning the message here keeps every caller's write path a single
+ * `formatGeneratedJson(...) ?? serialized` expression.
+ */
+function fallback(filename) {
+  Logger.warn(
+    `project formatter (biome) unavailable — writing unformatted ${filename}; ` +
+      'run your formatter over it if a format gate rejects it',
+  );
+  return null;
+}
+
+/**
+ * Format `source` as JSON using the project formatter.
+ *
+ * Best-effort by design: `.agents/` is materialized into consumer
+ * projects that need not have Biome installed, so an unavailable or
+ * failing formatter warns and returns `null` for the caller to fall back
+ * on its own serialization rather than failing the generator. That is
+ * safe wherever the artifact's freshness check compares parsed objects
+ * rather than bytes — formatting carries no semantic content.
+ *
+ * `--no` keeps npx from reaching the network to install a missing Biome.
+ * `filename` is passed as a bare basename: Biome only needs it to infer
+ * the language and match config overrides, and a basename cannot carry
+ * the spaces that would break arg quoting under the Windows `shell:
+ * true` spawn.
+ *
+ * @param {string} source Text to format.
+ * @param {object} opts
+ * @param {string} opts.cwd Directory to resolve the formatter and its config from.
+ * @param {string} [opts.filename] Basename Biome attributes the stdin text to.
+ * @param {typeof spawnSync} [opts.spawn] Injection seam for tests.
+ * @returns {string|null} Formatted text with a trailing newline, or null to fall back.
+ */
+export function formatGeneratedJson(
+  source,
+  { cwd, filename = 'generated.json', spawn = spawnSync },
+) {
+  let result;
+  try {
+    result = spawn(
+      'npx',
+      ['--no', 'biome', 'format', `--stdin-file-path=${filename}`],
+      {
+        cwd,
+        input: source,
+        encoding: 'utf8',
+        // npm/npx ship as `.cmd` shims on Windows, which Node refuses to
+        // spawn without a shell since CVE-2024-27980.
+        shell: process.platform === 'win32',
+        timeout: FORMATTER_TIMEOUT_MS,
+      },
+    );
+  } catch {
+    return fallback(filename);
+  }
+  if (!result || result.error || result.status !== 0) return fallback(filename);
+  const stdout = result.stdout;
+  if (typeof stdout !== 'string' || stdout.trim() === '') {
+    return fallback(filename);
+  }
+  return stdout.endsWith('\n') ? stdout : `${stdout}\n`;
+}

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

@@ -1,108 +1,35 @@
 // .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.
+ * framework-version.js — the visible authoring-marker surface for the legacy
+ * ticket-body provenance stamp.
  *
- * Two concerns live here:
+ * Tickets authored under v1 carry a hybrid stamp: a hidden
+ * `<!-- meta: {"mandrel_version":"…","authored_at":"…"} -->` block plus a
+ * single visible footer line
+ * `> 🏷️ Authored with Mandrel v<version> · <YYYY-MM-DD>`. The producer of
+ * new stamps was retired with the Epic write surface (#4574) — nothing stamps
+ * a new ticket — but bodies already stamped are live in the backlog, so the
+ * Story-body serializer/parser must keep round-tripping them:
  *
- * 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).
+ * - {@link AUTHORED_MARKER_LINE_RE} lets the parser skip the marker line during
+ *   section parsing so it never pollutes the last structured section.
+ * - {@link authoredMarkerLine} lets the serializer re-emit a byte-identical
+ *   marker line for a stamp it parsed, preserving provenance verbatim.
  *
- * 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.
+ * This module imports nothing so it can be pulled in from the story-body
+ * serializer 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.
+ * callout. Used 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}).
+ * Build the visible authoring marker line for a given stamp. The Story-body
+ * serializer uses this to re-emit a legacy stamp it parsed, byte-identically.
  *
  * @param {{ version: string, authoredAt: string }} stamp
  * @returns {string}
@@ -110,101 +37,3 @@ export function formatAuthoredDate(date = new Date()) {
 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/gh-exec.js

@@ -505,6 +505,14 @@ export function createGh(execImpl = exec, defaultExecOpts = {}) {
       execWithDefaults({ args: ['pr', 'edit', idStr(id), ...flags] }),
     merge: (id, flags = []) =>
       execWithDefaults({ args: ['pr', 'merge', idStr(id), ...flags] }),
+    /**
+     * Bring a `mergeStateStatus: BEHIND` PR up to date with its base
+     * (Story #4543). The close-and-land merge wait calls this a bounded
+     * number of times rather than waiting out its budget behind a base it
+     * could have caught up to.
+     */
+    updateBranch: (id, flags = []) =>
+      execWithDefaults({ args: ['pr', 'update-branch', idStr(id), ...flags] }),
     list: (flags = [], fields) =>
       execWithDefaults({
         args: ['pr', 'list', ...flags, ...jsonFlag(fields)],

package/.agents/scripts/lib/git-branch-cleanup.js

@@ -2,7 +2,7 @@
  * git-branch-cleanup.js — Shared branch deletion helpers (local + remote).
  *
  * Consolidates the "delete this branch from local and/or origin" pattern
- * used by `story-close.js` and other branch-reaping flows. Originally
+ * used by `single-story-close.js` and other branch-reaping flows. Originally
  * carved out when more than one caller re-implemented the same idempotency
  * rules with subtle drift.
  *
@@ -117,15 +117,6 @@ export function deleteBranchEverywhere(name, opts = {}) {
   return { deleted: bothOk, reason, local, remote };
 }
 
-/**
- * Backwards-compatible alias for `deleteBranchEverywhere`. Older call
- * sites and tests imported this name; keeping the alias avoids touching
- * them in the migration.
- *
- * @deprecated prefer `deleteBranchEverywhere`.
- */
-export const deleteBranchBoth = deleteBranchEverywhere;
-
 /**
  * Delete N branches in a single batched git call (push --delete X Y Z, or
  * branch -D X Y Z), falling back to per-ref delete via

package/.agents/scripts/lib/git-branch-lifecycle.js

@@ -3,7 +3,8 @@
  *
  * Consolidates the "does this branch exist locally / remotely?" and
  * "ensure this branch exists and is checked out" logic that
- * `story-init.js` and `dispatch-engine.js` had each re-implemented.
+ * `single-story-init.js` centralizes (formerly duplicated across the deleted
+ * `story-init.js` and `dispatch-engine.js` entry seams).
  *
  * All helpers take an explicit `cwd`. Callers with worktree isolation
  * enabled pass the worktree path; single-tree callers pass `PROJECT_ROOT`.
@@ -87,18 +88,16 @@ export function branchExistsViaTrackingRef(branch, cwd) {
 
 /**
  * Pure: classify how a `story-<id>` branch should be seeded from the (local,
- * remote) ref-presence matrix. This is the single source of truth shared by
- * both story-init paths (Story #3513):
- *   - `single-story-init.js#decideStoryBranchSeed` (standalone path)
- *   - `story-init/branch-initializer.js#planStoryBranchSeed` (Epic path)
+ * remote) ref-presence matrix. This is the single source of truth for
+ * `single-story-init.js#decideStoryBranchSeed` (v2 `/deliver` path).
  *
- * Both call sites previously re-implemented the same `local → no-op, remote →
- * fetch, else create` decision tree; they now delegate here so the branching
- * logic lives in exactly one place. The two callers keep their own keyword for
+ * The init path previously re-implemented the same `local → no-op, remote →
+ * fetch, else create` decision tree; it now delegates here so the branching
+ * logic lives in exactly one place. The caller keeps its own keyword for
  * the "local ref already exists" outcome (`reuse` vs `none`) — synonyms for
- * "do not re-create / do not re-seed" preserved for their existing public/test
- * contracts — so this classifier returns the neutral `'local'` keyword and
- * each caller maps it onto its own vocabulary.
+ * "do not re-create / do not re-seed" preserved for its existing public/test
+ * contract — so this classifier returns the neutral `'local'` keyword and
+ * the caller maps it onto its own vocabulary.
  *
  * @param {{ localHas: boolean, remoteHas: boolean }} presence
  * @returns {'local'|'fetch'|'create'}
@@ -116,22 +115,18 @@ export function classifyBranchSeed({ localHas, remoteHas }) {
 
 /**
  * Single-home for the story-branch seed-action *switch shell* that
- * `single-story-init.js#seedStoryBranch` (standalone path) and
- * `story-init/branch-initializer.js#ensureStoryBranchSeed` (Epic path) had
- * each re-implemented (Story #4255). Both already delegated the (local,
- * remote) decision to `classifyBranchSeed`; only the act-on-the-decision
- * shell (reuse / fetch / create) was duplicated, and that shell was the
- * drift surface for the seed-decision contract.
+ * `single-story-init.js#seedStoryBranch` owns (Story #4255). The deleted
+ * Epic `story-init/branch-initializer.js` path had duplicated the same
+ * shell before v2 cutover.
  *
  * The two callers differ in exactly two behavioural axes, both of which are
  * parameters here — no other conditional branching is introduced:
- *   - **`baseRef`** — the ref to branch from on `create` (`main` for the
- *     standalone path, the Epic branch for the Epic path).
+ *   - **`baseRef`** — the ref to branch from on `create` (`main` for v2
+ *     `/deliver`; pre-v2 Epic close used the Epic branch).
  *   - **`swallowCreateRace`** — when `true`, a `git branch` that exits
  *     non-zero with an "already exists" stderr is treated as reuse rather
- *     than a fatal error (closes the probe→create race the Epic path runs
- *     under concurrent wave dispatch). When `false`, any create failure
- *     throws (the standalone path has no concurrent creator to race).
+ *     than a fatal error (pre-v2 concurrent wave dispatch). When `false`, any create failure
+ *     throws (the v2 standalone path has no concurrent creator to race).
  *
  * The asymmetric surrounding wrappers (merged-sweep, fast-forward,
  * donor-prime, workspace-verify, phase-timer) are deliberately NOT folded
@@ -204,90 +199,6 @@ export function seedStoryBranchRef({
   }
 }
 
-/**
- * Ensure an Epic branch exists and is published to `origin`. Handles all
- * four states of the (local, remote) matrix.
- *
- * @param {string} epicBranch
- * @param {string} baseBranch
- * @param {string} cwd
- * @param {{ progress?: (phase: string, message: string) => void }} [opts]
- */
-export async function ensureEpicBranch(epicBranch, baseBranch, cwd, opts = {}) {
-  assertBranchSafe(epicBranch, baseBranch);
-  const progress = opts.progress ?? (() => {});
-
-  // Short-circuit: if we're already on the epic branch, just sync with remote.
-  // This avoids redundant checkout calls and prevents the edge case where
-  // branchExistsLocally returns false while we're on the branch (detached HEAD,
-  // worktree race), which would route into the create path and fail on -b.
-  const onBranch = currentBranch(cwd);
-  if (onBranch === epicBranch) {
-    const remote = branchExistsRemotely(epicBranch, cwd);
-    if (remote) {
-      progress('GIT', `Already on ${epicBranch}. Syncing with remote.`);
-      await gitPullWithRetry(cwd, 'origin', epicBranch);
-    } else {
-      progress('GIT', `Already on ${epicBranch}. Publishing to remote.`);
-      gitSync(cwd, 'push', '--no-verify', '-u', 'origin', epicBranch);
-    }
-    return;
-  }
-
-  const local = branchExistsLocally(epicBranch, cwd);
-  const remote = branchExistsRemotely(epicBranch, cwd);
-
-  if (!local && !remote) {
-    progress('GIT', `Creating Epic branch: ${epicBranch} (from ${baseBranch})`);
-    gitSync(cwd, 'checkout', baseBranch);
-    await gitPullWithRetry(cwd, 'origin', baseBranch);
-    gitSync(cwd, 'checkout', '-b', epicBranch);
-    gitSync(cwd, 'push', '--no-verify', '-u', 'origin', epicBranch);
-    _assertOnBranch(cwd, epicBranch);
-    return;
-  }
-
-  if (local && !remote) {
-    progress(
-      'GIT',
-      `Epic branch exists locally only: ${epicBranch}. Publishing.`,
-    );
-    gitSync(cwd, 'checkout', epicBranch);
-    gitSync(cwd, 'push', '--no-verify', '-u', 'origin', epicBranch);
-    _assertOnBranch(cwd, epicBranch);
-    return;
-  }
-
-  if (!local && remote) {
-    progress('GIT', `Tracking remote Epic branch: ${epicBranch}`);
-    gitSync(cwd, 'checkout', '-b', epicBranch, `origin/${epicBranch}`);
-    await gitPullWithRetry(cwd, 'origin', epicBranch);
-    _assertOnBranch(cwd, epicBranch);
-    return;
-  }
-
-  progress('GIT', `Epic branch exists. Syncing: ${epicBranch}`);
-  gitSync(cwd, 'checkout', epicBranch);
-  await gitPullWithRetry(cwd, 'origin', epicBranch);
-  _assertOnBranch(cwd, epicBranch);
-}
-
-/**
- * Post-operation assertion: verify HEAD is on the expected branch.
- * Guards against TOCTOU races where a parallel agent switches branches
- * between our checkout and pull.
- */
-function _assertOnBranch(cwd, expected) {
-  const actual = currentBranch(cwd);
-  if (actual !== expected) {
-    throw new Error(
-      `[git-branch-lifecycle] Branch assertion failed after checkout. ` +
-        `Expected HEAD on '${expected}', found '${actual}'. ` +
-        `A concurrent process may have switched branches.`,
-    );
-  }
-}
-
 /**
  * Check out a Story branch, creating it from `epicBranch` if neither local
  * nor remote exists. Non-destructive: if the branch already exists, this
@@ -342,80 +253,6 @@ export async function checkoutStoryBranch(
   gitSync(cwd, 'checkout', '-b', storyBranch, epicBranch);
 }
 
-/**
- * Ensure an Epic branch ref exists locally and is published to `origin`,
- * **without moving HEAD**. Designed for the worktree bootstrap path where
- * the main checkout must not switch branches (a parallel agent may be
- * working there, or the tree may be dirty).
- *
- * Uses `git branch` (not `checkout -b`) to create refs, and `git push` to
- * publish. Callers that need HEAD on the epic branch should use
- * `ensureEpicBranch()` instead.
- *
- * @param {string} epicBranch
- * @param {string} baseBranch
- * @param {string} cwd
- * @param {{ progress?: (phase: string, message: string) => void }} [opts]
- */
-/**
- * Pure: choose the action to take for `ensureEpicBranchRef` given whether
- * the branch exists locally and/or remotely. One of:
- *   - `'noop'` — both refs exist; nothing to do.
- *   - `'fetch'` — only remote exists; fetch into local.
- *   - `'publish-existing'` — only local exists; push it.
- *   - `'create-and-publish'` — neither exists; create from base then push.
- *
- * @param {boolean} local
- * @param {boolean} remote
- * @returns {'noop' | 'fetch' | 'publish-existing' | 'create-and-publish'}
- */
-export function planEnsureEpicBranchRefAction(local, remote) {
-  if (local) return remote ? 'noop' : 'publish-existing';
-  return remote ? 'fetch' : 'create-and-publish';
-}
-
-export function ensureEpicBranchRef(epicBranch, baseBranch, cwd, opts = {}) {
-  assertBranchSafe(epicBranch, baseBranch);
-  const progress = opts.progress ?? (() => {});
-
-  // `ensureEpicBranchRef` is always called after a `git fetch origin` (via
-  // `cachedGitFetch` / `fetchMainRefs` in `bootstrapWorktree`). The
-  // remote-tracking refs are therefore authoritative, so we check
-  // `refs/remotes/origin/<branch>` locally rather than issuing a second
-  // network `ls-remote` call.
-  const action = planEnsureEpicBranchRefAction(
-    branchExistsLocally(epicBranch, cwd),
-    branchExistsViaTrackingRef(epicBranch, cwd),
-  );
-
-  if (action === 'noop') {
-    progress('GIT', `Epic branch ref exists (local+remote): ${epicBranch}`);
-    return;
-  }
-
-  if (action === 'fetch') {
-    progress('GIT', `Fetching remote Epic branch ref: ${epicBranch}`);
-    const res = gitSpawn(cwd, 'fetch', 'origin', `${epicBranch}:${epicBranch}`);
-    if (res.status !== 0) {
-      throw new Error(
-        `ensureEpicBranchRef: failed to fetch ${epicBranch}: ${res.stderr}`,
-      );
-    }
-    return;
-  }
-
-  if (action === 'create-and-publish') {
-    progress(
-      'GIT',
-      `Creating Epic branch ref: ${epicBranch} (from ${baseBranch})`,
-    );
-    gitSync(cwd, 'branch', epicBranch, baseBranch);
-  }
-
-  progress('GIT', `Publishing Epic branch: ${epicBranch}`);
-  gitSync(cwd, 'push', '--no-verify', '-u', 'origin', epicBranch);
-}
-
 /**
  * Ensure an arbitrary branch exists locally, creating from `baseBranch` if
  * missing. Used by the dispatcher's task-dispatch path where the expected