mandrel 2.0.0 → 2.2.0

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/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

package/.agents/scripts/lib/orchestration/lifecycle/emit-ledger-event.js

@@ -0,0 +1,142 @@
+/**
+ * emit-ledger-event.js — shared validate-and-append core for the
+ * merge-terminal lifecycle emitters (Story #4539).
+ *
+ * `emit-merge-unlanded.js` and `emit-merge-flip-failed.js` report the two
+ * terminal outcomes a landing attempt can reach without ending at
+ * `agent::done`. They share everything except their schema and their
+ * payload's meaning, so the Ajv compile/cache, the scope→ledger routing,
+ * and the NDJSON append live here once rather than being copy-pasted.
+ *
+ * Like its callers, this is a bare `appendFileSync` rather than a bus
+ * publish: these events fire from the `single-story-close` flow, which has
+ * no bus at all, so a direct append keeps the call site dependency-free.
+ */
+
+import { appendFileSync, mkdirSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import Ajv2020 from 'ajv/dist/2020.js';
+import addFormats from 'ajv-formats';
+
+import { storyLedgerPath } from '../../config/temp-paths.js';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const SCHEMA_DIR = path.resolve(
+  __dirname,
+  '..',
+  '..',
+  '..',
+  '..',
+  'schemas',
+  'lifecycle',
+);
+
+/**
+ * The scopes a merge-terminal event may be WRITTEN with. v2.0.0 removed the
+ * Epic tier, so `'story'` is the only emittable scope.
+ *
+ * Note the deliberate asymmetry with the `merge.unlanded` /
+ * `merge.flip-failed` schema enums, which still accept `'epic'`: archived
+ * ledger records carry `scope: 'epic'` and the schemas must keep validating
+ * them on read. The value stays READABLE; only the writer path is gone —
+ * the same split `merge-block-class.js` keeps for `predicate-refused`.
+ */
+const VALID_SCOPES = new Set(['story']);
+
+/** @type {Map<string, Function>} */
+const _validators = new Map();
+
+/**
+ * Compile (once) and return the validator for a lifecycle schema file.
+ *
+ * @param {string} schemaFile Basename under `.agents/schemas/lifecycle/`.
+ * @returns {Function}
+ */
+function getValidator(schemaFile) {
+  const cached = _validators.get(schemaFile);
+  if (cached) return cached;
+  const schema = JSON.parse(
+    readFileSync(path.resolve(SCHEMA_DIR, schemaFile), 'utf8'),
+  );
+  const ajv = new Ajv2020({ allErrors: true, strict: false });
+  addFormats(ajv);
+  const validator = ajv.compile(schema);
+  _validators.set(schemaFile, validator);
+  return validator;
+}
+
+/**
+ * Assert the fields every merge-terminal event shares. Throws with the
+ * caller's own emitter name so the message stays attributable.
+ *
+ * @param {string} emitter
+ * @param {{ scope: string, ticketId: number, prNumber: number, reason: string, elapsedSeconds: number }} fields
+ */
+export function assertMergeTerminalFields(
+  emitter,
+  { scope, ticketId, prNumber, reason, elapsedSeconds },
+) {
+  if (!VALID_SCOPES.has(scope)) {
+    throw new Error(
+      `${emitter}: scope "${scope}" must be one of: ${[...VALID_SCOPES].join(', ')}`,
+    );
+  }
+  if (!Number.isInteger(ticketId) || ticketId < 1) {
+    throw new Error(`${emitter}: ticketId must be a positive integer`);
+  }
+  if (!Number.isInteger(prNumber) || prNumber < 1) {
+    throw new Error(`${emitter}: prNumber must be a positive integer`);
+  }
+  if (typeof reason !== 'string' || reason.length === 0) {
+    throw new Error(`${emitter}: reason must be a non-empty string`);
+  }
+  if (typeof elapsedSeconds !== 'number' || elapsedSeconds < 0) {
+    throw new Error(`${emitter}: elapsedSeconds must be a non-negative number`);
+  }
+}
+
+/**
+ * Validate a payload against its lifecycle schema and append exactly one
+ * NDJSON record to the scope-resolved ledger.
+ *
+ * @param {object} args
+ * @param {string} args.emitter       Caller name, for error attribution.
+ * @param {string} args.schemaFile    Basename under `schemas/lifecycle/`.
+ * @param {object} args.payload       The event payload (already assembled).
+ * @param {number} args.ticketId
+ * @param {string} args.timestamp
+ * @param {object} [args.config]
+ * @param {string} [args.ledgerPath]  Override for tests / non-default layouts.
+ * @returns {{ ledgerPath: string, record: object }}
+ */
+export function appendLedgerEvent({
+  emitter,
+  schemaFile,
+  payload,
+  ticketId,
+  timestamp,
+  config,
+  ledgerPath: ledgerPathOverride,
+}) {
+  const validator = getValidator(schemaFile);
+  if (!validator(payload)) {
+    const detail = (validator.errors ?? [])
+      .map((e) => `${e.instancePath || '/'} ${e.message}`)
+      .join('; ');
+    throw new Error(`${emitter}: payload failed schema validation: ${detail}`);
+  }
+
+  const ledgerPath =
+    ledgerPathOverride ?? storyLedgerPath(null, ticketId, config);
+  mkdirSync(path.dirname(ledgerPath), { recursive: true });
+  const record = {
+    kind: 'emitted',
+    ts: timestamp,
+    event: payload.event,
+    payload,
+  };
+  appendFileSync(ledgerPath, `${JSON.stringify(record)}\n`, 'utf8');
+  return { ledgerPath, record };
+}

package/.agents/scripts/lib/orchestration/lifecycle/emit-loop-tick.js

@@ -9,14 +9,12 @@
  * appends an inspectable `emitted` line a reconciler can read for
  * forward-progress evidence.
  *
- * Distinct from `story.heartbeat` (emit-story-heartbeat.js): the
- * heartbeat carries Story-phase info for a single in-flight Story and is
- * always Epic-scoped (its ledger path is `epicLedgerPath(epicId)`). A
- * host loop is not bound to a Story tier, so `loop.tick` carries a
+ * A host loop is not bound to a Story tier, so `loop.tick` carries a
  * free-form `loopName`, a monotonic `round` counter, the loop's
- * configured `cadence` label, and a per-round `status` instead. Keeping
- * the two events separate means a loop tick never masquerades as Story
- * progress (and vice versa).
+ * configured `cadence` label, and a per-round `status`. It is now the only
+ * forward-progress beat: the Story-scoped `story.heartbeat` it was once
+ * contrasted against was Epic-scoped by construction, could never fire under
+ * v2 (which has no Epics), and was deleted (A22).
  *
  * Bus path (Story acceptance: "Emitting a loop.tick event THROUGH the
  * lifecycle bus appends a record to the per-run ledger"): this helper
@@ -39,7 +37,7 @@
  * Ledger path resolution: a caller supplies EITHER an explicit
  * `ledgerPath` (the host-loop case — the loop owns where its ledger
  * lives) OR an `epicId`, in which case the canonical
- * `epicLedgerPath(epicId)` is used so an Epic-scoped loop's ticks land
+ * `runLedgerPath(epicId)` is used so an Epic-scoped loop's ticks land
  * in the same `temp/run-<id>/lifecycle.ndjson` the rest of the run
  * reads. Exactly one of the two MUST be supplied.
  */
@@ -47,7 +45,7 @@
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 
-import { epicLedgerPath } from '../../config/temp-paths.js';
+import { runLedgerPath } from '../../config/temp-paths.js';
 import { createBus } from './bus.js';
 import { createLedgerWriter } from './ledger-writer.js';
 
@@ -104,7 +102,7 @@ function decomposeLedgerPath(ledgerPath) {
  *                                   One of running|done|blocked.
  * @param {string} [opts.timestamp]  ISO-8601 wall clock. Defaults to now().
  * @param {number} [opts.epicId]     When supplied (and no `ledgerPath`),
- *                                   the canonical `epicLedgerPath(epicId)`
+ *                                   the canonical `runLedgerPath(epicId)`
  *                                   is used for the ledger.
  * @param {object} [opts.config]     Optional resolved config for tempRoot
  *                                   (only consulted on the `epicId` path).
@@ -158,7 +156,7 @@ export async function emitLoopTick(opts) {
     if (!Number.isInteger(epicId) || epicId < 1) {
       throw new Error('emitLoopTick: epicId must be a positive integer');
     }
-    ledgerPath = epicLedgerPath(epicId, config);
+    ledgerPath = runLedgerPath(epicId, config);
   }
 
   const payload = {