mandrel 1.62.0 → 1.63.0

package/.agents/scripts/check-action-pinning.js

@@ -0,0 +1,260 @@
+/**
+ * CLI: third-party GitHub Action pinning gate.
+ *
+ * Story #4079 (audit::devops). Closes a supply-chain regression window the
+ * `ci.yml` / `release-please.yml` comments *claimed* was guarded by a
+ * nonexistent `npm run audit-security` gate. There is no such npm script;
+ * `audit-security` is only a manual `/audit-security` slash-command lens.
+ * Nothing actually enforced that third-party `uses:` refs stay SHA-pinned,
+ * so a future edit reverting `trufflehog@<sha>` to `@main` would pass CI
+ * silently.
+ *
+ * This script scans `.github/workflows/*.yml` (and `*.yaml`), extracts every
+ * `uses:` ref, and fails the build when a **third-party** action (anything
+ * not under the first-party `actions/*` org) is pinned to a floating ref
+ * instead of a full 40-char commit SHA. First-party `actions/*` refs are
+ * allowed on major-version tags (`@v4`) — Dependabot's `github-actions`
+ * ecosystem bumps those in-place, matching the rationale in the workflow
+ * file headers.
+ *
+ * A "floating ref" is any of:
+ *   - a branch head: `@main`, `@master`
+ *   - a tag / partial-SHA that is not a full 40-hex-char commit SHA
+ *     (`@v5`, `@v3.95.3`, `@release`, a 7-char short SHA, …)
+ *
+ * Contract:
+ *   - Scans the workflows directory (default `.github/workflows`, override
+ *     with `--dir <path>`).
+ *   - Prints `<file>:<lineNo> <ref> — <reason>` for each violation, then a
+ *     one-line summary even on a clean scan so operators see the "ok" signal.
+ *   - With `--json`: writes a structured envelope to stdout and skips the
+ *     human summary.
+ *   - Exit codes: 0 = no violations; 1 = at least one floating third-party
+ *     ref. A missing / empty workflows directory exits 0 (nothing to gate).
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import process from 'node:process';
+import { runAsCli } from './lib/cli-utils.js';
+
+/**
+ * Parse argv for `--dir <path>` and `--json`. Exported so unit tests can pin
+ * the parser.
+ *
+ * @param {string[]} argv
+ * @returns {{ dir: string | null, json: boolean }}
+ */
+export function parseArgv(argv = []) {
+  let dir = null;
+  let json = false;
+  for (let i = 0; i < argv.length; i += 1) {
+    const a = argv[i];
+    if (a === '--dir') {
+      const next = argv[i + 1];
+      if (next && !next.startsWith('--')) {
+        dir = next;
+        i += 1;
+      }
+    } else if (a === '--json') {
+      json = true;
+    }
+  }
+  return { dir, json };
+}
+
+/**
+ * Is the given ref suffix a full 40-char hex commit SHA?
+ *
+ * @param {string} ref The portion after the `@` in a `uses:` value.
+ * @returns {boolean}
+ */
+export function isFullSha(ref) {
+  return /^[0-9a-f]{40}$/i.test(ref);
+}
+
+/**
+ * Is the action a first-party `actions/*` action (e.g. `actions/checkout`)?
+ * First-party refs are allowed to float on major-version tags because
+ * Dependabot's `github-actions` ecosystem bumps them in-place.
+ *
+ * Local (`./…`) and reusable-workflow (`owner/repo/.github/workflows/x.yml`)
+ * refs and Docker refs (`docker://…`) are out of scope for the SHA-pin gate;
+ * `isFirstParty` only matters for `owner/repo[@ref]` registry actions.
+ *
+ * @param {string} action The portion before the `@` in a `uses:` value.
+ * @returns {boolean}
+ */
+export function isFirstParty(action) {
+  return /^actions\//.test(action);
+}
+
+/**
+ * Pure helper: scan a single workflow file's text for `uses:` refs and return
+ * the violations. A violation is a third-party `owner/repo@ref` where `ref`
+ * is not a full 40-char SHA.
+ *
+ * Skips:
+ *   - local actions (`uses: ./path`)
+ *   - Docker refs (`uses: docker://…`)
+ *   - first-party `actions/*` refs (allowed on major-version tags)
+ *   - refs with no `@` (pinned by default branch implicitly — flagged as a
+ *     violation: an unpinned third-party ref floats on the default branch)
+ *
+ * @param {string} file Relative file label used in violation rows.
+ * @param {string} text The file contents.
+ * @returns {Array<{ file: string, line: number, action: string, ref: string | null, reason: string }>}
+ */
+export function scanWorkflowText(file, text) {
+  const violations = [];
+  const lines = text.split(/\r?\n/);
+  // Match `uses:` values, optionally quoted. The value runs until whitespace
+  // or a `#` comment. Capture the raw value for downstream parsing.
+  const usesRe = /^\s*(?:-\s*)?uses:\s*['"]?([^'"#\s]+)['"]?/;
+  for (let i = 0; i < lines.length; i += 1) {
+    const m = usesRe.exec(lines[i]);
+    if (!m) continue;
+    const value = m[1];
+    const lineNo = i + 1;
+    // Local actions and Docker refs are out of scope for the SHA-pin gate.
+    if (value.startsWith('./') || value.startsWith('docker://')) continue;
+    const atIndex = value.indexOf('@');
+    const action = atIndex === -1 ? value : value.slice(0, atIndex);
+    const ref = atIndex === -1 ? null : value.slice(atIndex + 1);
+    // First-party actions/* may float on major-version tags.
+    if (isFirstParty(action)) continue;
+    if (ref === null) {
+      violations.push({
+        file,
+        line: lineNo,
+        action,
+        ref: null,
+        reason: 'third-party action with no ref floats on the default branch',
+      });
+      continue;
+    }
+    if (!isFullSha(ref)) {
+      const floating = ref === 'main' || ref === 'master';
+      violations.push({
+        file,
+        line: lineNo,
+        action,
+        ref,
+        reason: floating
+          ? `third-party action pinned to branch head @${ref} (CWE-1357)`
+          : `third-party action @${ref} is not a full 40-char commit SHA`,
+      });
+    }
+  }
+  return violations;
+}
+
+/**
+ * Enumerate workflow files (`*.yml` / `*.yaml`) directly under `dir`.
+ * Returns absolute paths sorted for deterministic output. A missing directory
+ * yields an empty list.
+ *
+ * @param {string} dir Absolute workflows directory.
+ * @returns {string[]}
+ */
+export function listWorkflowFiles(dir) {
+  let entries;
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  return entries
+    .filter((e) => e.isFile() && /\.ya?ml$/i.test(e.name))
+    .map((e) => path.join(dir, e.name))
+    .sort();
+}
+
+/**
+ * Pure helper: render the human-readable report. One line per violation
+ * followed by a one-line summary. The summary carries a `(gate fail)` /
+ * `(ok)` marker so the result is visible in CI output.
+ *
+ * @param {Array<{ file: string, line: number, action: string, ref: string | null, reason: string }>} violations
+ * @returns {string}
+ */
+export function renderReport(violations) {
+  const lines = [];
+  for (const v of violations) {
+    const refLabel = v.ref === null ? '(no ref)' : `@${v.ref}`;
+    lines.push(`${v.file}:${v.line} ${v.action}${refLabel} — ${v.reason}`);
+  }
+  const tag = violations.length > 0 ? '(gate fail)' : '(ok)';
+  lines.push(`[action-pinning] violations=${violations.length} ${tag}`);
+  return lines.join('\n');
+}
+
+/**
+ * Top-level CLI entry. Exported so tests can drive the full pipeline against a
+ * fixture workflows directory without touching the repo's real workflows.
+ *
+ * @param {{
+ *   argv?: string[],
+ *   cwd?: string,
+ *   stdout?: { write: (s: string) => void },
+ *   stderr?: { write: (s: string) => void },
+ * }} [opts]
+ * @returns {Promise<number>} exit code: 0 = clean; 1 = floating third-party ref
+ */
+export async function runCli({
+  argv = process.argv.slice(2),
+  cwd = process.cwd(),
+  stdout = process.stdout,
+  stderr = process.stderr,
+} = {}) {
+  const { dir, json } = parseArgv(argv);
+  const resolvedDir = path.resolve(
+    cwd,
+    dir ?? path.join('.github', 'workflows'),
+  );
+
+  const files = listWorkflowFiles(resolvedDir);
+  const violations = [];
+  for (const file of files) {
+    let text;
+    try {
+      text = fs.readFileSync(file, 'utf-8');
+    } catch {
+      continue;
+    }
+    violations.push(...scanWorkflowText(path.relative(cwd, file), text));
+  }
+
+  const exitCode = violations.length > 0 ? 1 : 0;
+
+  if (json) {
+    const envelope = {
+      kind: 'action-pinning-report',
+      dir: resolvedDir,
+      filesScanned: files.length,
+      violations,
+      exitCode,
+    };
+    stdout.write(`${JSON.stringify(envelope, null, 2)}\n`);
+  } else {
+    if (files.length === 0) {
+      stderr.write(
+        `[action-pinning] ⚠ no workflow files found under ${resolvedDir}\n`,
+      );
+    }
+    stdout.write(`\n--- action-pinning scan ---\n`);
+    stdout.write(`${renderReport(violations)}\n`);
+  }
+
+  return exitCode;
+}
+
+async function main() {
+  return runCli();
+}
+
+runAsCli(import.meta.url, main, {
+  source: 'action-pinning',
+  propagateExitCode: true,
+  errorPrefix: '[action-pinning] ❌ Fatal error',
+});

package/.agents/scripts/check-arch-cycles.js

@@ -1,10 +1,19 @@
 /**
  * CLI: ratchet-down architecture gate for import cycles (Story #3991).
  *
- * Walks every `.js` file under `.agents/scripts/` (excluding
- * `node_modules`), parses relative static-import edges
- * (`from './…/x.js'`), detects directed cycles via DFS, and compares
- * them against the committed allowlist at `baselines/arch-cycles.json`.
+ * Walks every `.js` file across the project's **distributed surface**
+ * (the `files[]` set published to npm — `.agents/scripts/`, `bin/`, and
+ * the root `lib/`, excluding `node_modules`), parses relative
+ * static-import edges (`from './…/x.js'`), detects directed cycles via
+ * DFS, and compares them against the committed allowlist at
+ * `baselines/arch-cycles.json`.
+ *
+ * The multi-root scan resolves every root into a **single** import graph
+ * keyed by repository-relative module ids (Story #4071). This lets
+ * `findCycles` catch cycles that cross the documented lifecycle↔runtime
+ * partition — e.g. a `bin/` lifecycle script and an `.agents/scripts/lib`
+ * runtime module importing each other — which a single-root scan cannot
+ * see because it only walks one side of the partition.
  *
  * Ratchet semantics mirror `check-dead-exports.js`:
  *   - Any detected cycle NOT in the allowlist → exit 1, cycle path printed.
@@ -19,8 +28,8 @@
  * Flags:
  *   --baseline <path>  override the allowlist path (default
  *                      `baselines/arch-cycles.json`, resolved from cwd)
- *   --root <path>      override the scanned root (default
- *                      `.agents/scripts`, resolved from cwd)
+ *   --root <path>      scan a single explicit root instead of the default
+ *                      distributed surface, relativized against that root
  *   --json             write the structured envelope to stdout
  */
 
@@ -29,6 +38,16 @@ import path from 'node:path';
 import process from 'node:process';
 import { runAsCli } from './lib/cli-utils.js';
 
+/**
+ * Default scan roots making up the project's distributed surface — the
+ * directories published to npm via `package.json` `files[]`. Resolving
+ * them into one graph (relativized against the repo root) means a cycle
+ * crossing two roots is visible to `findCycles`.
+ *
+ * @type {string[]}
+ */
+export const DEFAULT_ROOTS = [path.join('.agents', 'scripts'), 'bin', 'lib'];
+
 /**
  * Parse argv for `--baseline <path>`, `--root <path>`, and `--json`.
  * Exported so unit tests can pin the parser.
@@ -304,22 +323,27 @@ export async function runCli({
   stderr = process.stderr,
 } = {}) {
   const { baselinePath, rootPath, json } = parseArgv(argv);
-  const resolvedRoot = path.resolve(
-    cwd,
-    rootPath ?? path.join('.agents', 'scripts'),
+  // With an explicit `--root`, scan that single root and relativize ids
+  // against it (unchanged contract). Without it, scan the full distributed
+  // surface and relativize every id against the repo root (`cwd`) so edges
+  // that cross two roots resolve into a single graph.
+  const graphRoot = rootPath ? path.resolve(cwd, rootPath) : path.resolve(cwd);
+  const scanDirs = (rootPath ? [rootPath] : DEFAULT_ROOTS).map((dir) =>
+    path.resolve(cwd, dir),
   );
   const resolvedBaselinePath = path.resolve(
     cwd,
     baselinePath ?? path.join('baselines', 'arch-cycles.json'),
   );
-  if (!fs.existsSync(resolvedRoot)) {
-    throw new Error(`[arch-cycles] scan root not found: ${resolvedRoot}`);
+  const presentScanDirs = scanDirs.filter((dir) => fs.existsSync(dir));
+  if (presentScanDirs.length === 0) {
+    throw new Error(`[arch-cycles] no scan root found: ${scanDirs.join(', ')}`);
   }
   const baseline = loadBaseline(resolvedBaselinePath);
   const allowlisted = Array.isArray(baseline?.cycles) ? baseline.cycles : [];
 
-  const files = collectJsFiles(resolvedRoot);
-  const graph = buildGraph(files, resolvedRoot);
+  const files = presentScanDirs.flatMap((dir) => collectJsFiles(dir));
+  const graph = buildGraph(files, graphRoot);
   const detected = findCycles(graph);
   const diff = diffCycles(allowlisted, detected);
   const exitCode = diff.added.length > 0 ? 1 : 0;
@@ -327,7 +351,7 @@ export async function runCli({
   if (json) {
     const envelope = {
       kind: 'arch-cycles-report',
-      root: resolvedRoot,
+      root: graphRoot,
       baselinePath: resolvedBaselinePath,
       allowlisted: allowlisted.map(normalizeCycle),
       detected,

package/.agents/scripts/epic-deliver-prepare.js

@@ -139,101 +139,82 @@ function resolveGitUserEmail(cwd) {
  *   checkpointInitializedAt: string,
  * }>}
  */
-export async function runEpicDeliverPrepare({
+/**
+ * Run the fail-closed preflight guards (Story #3482): refuse on a
+ * dirty/foreign-branch checkout and on a live foreign Epic lease, BEFORE any
+ * snapshot or git mutation. No-op when guards are suppressed. The guards are
+ * skipped when `skipPreflightGuards` is set, OR — implicitly — when a caller
+ * injects a provider but no git seam (the signature of the prepare-runner
+ * unit tests that drive an in-memory provider and never stand up a tree). The
+ * real CLI path injects neither, so the guards always run for an
+ * operator-driven invocation. Story #4075 — extracted from
+ * `runEpicDeliverPrepare`.
+ */
+async function runPreflightGuardsForPrepare({
   epicId,
   cwd,
+  config,
+  provider,
   injectedProvider,
-  injectedConfig,
-  injectedFindings,
-  ignoreConcurrencyHazards = false,
-  steal = false,
-  asOperator,
   injectedGit,
+  asOperator,
+  steal,
   leaseHeartbeatAt,
   leaseNow,
-  skipPreflightGuards = false,
-} = {}) {
-  if (!Number.isInteger(epicId) || epicId <= 0) {
-    throw new TypeError(
-      'runEpicDeliverPrepare: --epic must be a positive integer',
-    );
-  }
-
-  const config = injectedConfig ?? resolveConfig({ cwd });
-  if (!config.github) {
-    throw new Error('runEpicDeliverPrepare: no github block in .agentrc.json');
-  }
-  const provider = injectedProvider ?? createProvider(config);
-  const { deliverRunner } = getRunners(config);
-  const concurrencyCap = deliverRunner.concurrencyCap;
-
-  // Preflight guards (Story #3482): fail closed on a dirty/foreign-branch
-  // checkout and on a live foreign Epic lease, BEFORE any snapshot or git
-  // mutation runs. The guards are injectable so the unit suite exercises them
-  // without a real repo. They are skipped when an explicit `skipPreflightGuards`
-  // is set, OR — implicitly — when a caller injects a provider but no git seam:
-  // that combination is the signature of the pre-existing prepare-runner unit
-  // tests that assert the DAG/checkpoint behaviour against an in-memory
-  // provider and never stand up a working tree. The real CLI path passes
-  // neither `injectedProvider` nor `injectedGit`, so the guards always run for
-  // an operator-driven invocation.
+  skipPreflightGuards,
+}) {
   const guardsSuppressed =
     skipPreflightGuards || (Boolean(injectedProvider) && !injectedGit);
-  if (!guardsSuppressed) {
-    const guardCwd = cwd ?? process.cwd();
-    const git = injectedGit ?? createGitShim(guardCwd);
-    const baseBranch = config.project?.baseBranch ?? 'main';
-    const expectedBranch = [getEpicBranch(epicId), baseBranch];
-    const operator =
-      resolveOperator({
-        asFlag: asOperator,
-        config,
-        gitUserEmail: injectedGit ? undefined : resolveGitUserEmail(guardCwd),
-      }) ?? null;
-
-    // Liveness seam: a foreign claim is only "live" (and so refuses) when the
-    // claim *owner* has a recent `story.heartbeat`. Without this the lease
-    // guard is inert — `heartbeatAt` defaults to null, `isClaimLive(null)` is
-    // false, and every foreign claim looks stale and gets silently reclaimed
-    // (audit #3513). Read the Epic's current assignee (the claim owner) and
-    // resolve that owner's latest heartbeat from the Epic lifecycle ledger
-    // (`temp/epic-<id>/lifecycle.ndjson`) via the shared resolver, so a LIVE
-    // foreign claim actually refuses and only a genuinely stale/absent one is
-    // reclaimed. Tests may inject `leaseHeartbeatAt` directly (any value,
-    // including null) to bypass the ledger read; the CLI passes nothing.
-    let heartbeatAt = leaseHeartbeatAt;
-    if (heartbeatAt === undefined) {
-      const epicTicket = await provider.getTicket(epicId);
-      const claimOwner = leaseCurrentOwner(epicTicket?.assignees);
-      heartbeatAt = claimOwner
-        ? latestHeartbeatForOwner({ epicId, owner: claimOwner, config })
-        : null;
-    }
+  if (guardsSuppressed) return;
 
-    await runPrepareGuards({
-      epicId,
-      expectedBranch,
-      git,
-      provider,
-      operator,
-      heartbeatAt,
-      steal,
+  const guardCwd = cwd ?? process.cwd();
+  const git = injectedGit ?? createGitShim(guardCwd);
+  const baseBranch = config.project?.baseBranch ?? 'main';
+  const expectedBranch = [getEpicBranch(epicId), baseBranch];
+  const operator =
+    resolveOperator({
+      asFlag: asOperator,
       config,
-      now: leaseNow,
-      logger: Logger,
-    });
+      gitUserEmail: injectedGit ? undefined : resolveGitUserEmail(guardCwd),
+    }) ?? null;
+
+  // Liveness seam: a foreign claim is only "live" (and so refuses) when the
+  // claim *owner* has a recent `story.heartbeat`. Without this the lease
+  // guard is inert — every foreign claim looks stale and gets silently
+  // reclaimed (audit #3513). Read the Epic's current assignee (the claim
+  // owner) and resolve that owner's latest heartbeat from the Epic lifecycle
+  // ledger via the shared resolver. Tests may inject `leaseHeartbeatAt`
+  // directly (any value, including null) to bypass the ledger read.
+  let heartbeatAt = leaseHeartbeatAt;
+  if (heartbeatAt === undefined) {
+    const epicTicket = await provider.getTicket(epicId);
+    const claimOwner = leaseCurrentOwner(epicTicket?.assignees);
+    heartbeatAt = claimOwner
+      ? latestHeartbeatForOwner({ epicId, owner: claimOwner, config })
+      : null;
   }
 
-  // Story #3027: try the preflight cache first so we don't re-walk Epic
-  // → Feature → Story when `epic-deliver-preflight.js` already did. The
-  // cache key is a deterministic fingerprint of the Epic ticket plus the
-  // cached Story snapshots (Story #4019): the Epic re-fetch plus one
-  // getTicket per cached Story is still far cheaper than the full
-  // hierarchy BFS, and a Story-dependency edit now invalidates the cache.
-  // Cache miss or baseSha mismatch → fall back to a fresh pass.
-  const ctx = { epicId, provider };
-  let state = {};
-  let cacheStatus = 'miss';
+  await runPrepareGuards({
+    epicId,
+    expectedBranch,
+    git,
+    provider,
+    operator,
+    heartbeatAt,
+    steal,
+    config,
+    now: leaseNow,
+    logger: Logger,
+  });
+}
+
+/**
+ * Resolve the Epic state, preferring the preflight cache (Story #3027) and
+ * falling back to a fresh snapshot + wave-DAG pass on miss or baseSha
+ * mismatch. Returns `{ state, cacheStatus }`. Story #4075 — extracted from
+ * `runEpicDeliverPrepare`.
+ */
+async function resolvePrepareState({ epicId, cwd, provider }) {
   const cached = await readPreflightCache({ epicId, cwd });
   if (cached) {
     const freshEpic = await provider.getTicket(epicId);
@@ -245,35 +226,42 @@ export async function runEpicDeliverPrepare({
     );
     const freshBaseSha = computeBaseSha(freshEpic, freshStories);
     if (freshBaseSha === cached.baseSha) {
-      state = {
-        epic: cached.epic,
-        stories: cached.stories,
-        waves: cached.waves,
+      return {
+        state: {
+          epic: cached.epic,
+          stories: cached.stories,
+          waves: cached.waves,
+        },
+        cacheStatus: 'hit',
       };
-      cacheStatus = 'hit';
-    } else {
-      cacheStatus = 'stale';
     }
   }
-  if (cacheStatus !== 'hit') {
-    state = await runSnapshotPhase(ctx, {}, state);
-    state = await runBuildWaveDagPhase(ctx, {}, state);
-  }
+  const ctx = { epicId, provider };
+  let state = await runSnapshotPhase(ctx, {}, {});
+  state = await runBuildWaveDagPhase(ctx, {}, state);
+  return { state, cacheStatus: cached ? 'stale' : 'miss' };
+}
 
-  // Cross-Story concurrency-hazard gate (Story #2297). Findings come in
-  // via DI; no default loader is wired yet — production callers will
-  // either pass findings derived from the persisted manifest or rely on
-  // the empty default (gate trivially passes).
+/**
+ * Evaluate the cross-Story concurrency-hazard gate (Story #2297). Throws on a
+ * tripped, non-bypassed gate; warns (and returns `gate`) on a bypassed trip.
+ * Story #4075 — extracted from `runEpicDeliverPrepare`.
+ */
+function evaluatePrepareConcurrencyGate({
+  config,
+  waves,
+  injectedFindings,
+  ignoreConcurrencyHazards,
+}) {
   const findings = Array.isArray(injectedFindings) ? injectedFindings : [];
-  const pendingKeys = collectPendingStoryKeys(state.waves);
+  const pendingKeys = collectPendingStoryKeys(waves);
   const pendingFindings = filterFindingsToPending(findings, pendingKeys);
-  const concurrencyPolicy = {
-    failOnConcurrencyHazards:
-      config?.delivery?.failOnConcurrencyHazards === true,
-  };
   const gate = evaluateConcurrencyGate({
     findings: pendingFindings,
-    policy: concurrencyPolicy,
+    policy: {
+      failOnConcurrencyHazards:
+        config?.delivery?.failOnConcurrencyHazards === true,
+    },
     ignore: ignoreConcurrencyHazards === true,
   });
   if (gate.tripped && !gate.bypassed) {
@@ -288,6 +276,63 @@ export async function runEpicDeliverPrepare({
       `[epic-deliver-prepare] ⚠️  Concurrency-hazard gate bypassed via --ignore-concurrency-hazards (reason=${gate.reason}, count=${gate.findings.length}).`,
     );
   }
+  return gate;
+}
+
+export async function runEpicDeliverPrepare({
+  epicId,
+  cwd,
+  injectedProvider,
+  injectedConfig,
+  injectedFindings,
+  ignoreConcurrencyHazards = false,
+  steal = false,
+  asOperator,
+  injectedGit,
+  leaseHeartbeatAt,
+  leaseNow,
+  skipPreflightGuards = false,
+} = {}) {
+  if (!Number.isInteger(epicId) || epicId <= 0) {
+    throw new TypeError(
+      'runEpicDeliverPrepare: --epic must be a positive integer',
+    );
+  }
+
+  const config = injectedConfig ?? resolveConfig({ cwd });
+  if (!config.github) {
+    throw new Error('runEpicDeliverPrepare: no github block in .agentrc.json');
+  }
+  const provider = injectedProvider ?? createProvider(config);
+  const { deliverRunner } = getRunners(config);
+  const concurrencyCap = deliverRunner.concurrencyCap;
+
+  await runPreflightGuardsForPrepare({
+    epicId,
+    cwd,
+    config,
+    provider,
+    injectedProvider,
+    injectedGit,
+    asOperator,
+    steal,
+    leaseHeartbeatAt,
+    leaseNow,
+    skipPreflightGuards,
+  });
+
+  const { state, cacheStatus } = await resolvePrepareState({
+    epicId,
+    cwd,
+    provider,
+  });
+
+  const gate = evaluatePrepareConcurrencyGate({
+    config,
+    waves: state.waves,
+    injectedFindings,
+    ignoreConcurrencyHazards,
+  });
 
   const totalWaves = state.waves.length;
   const checkpointState = await initializeEpicRunState({