mandrel 1.57.0

package/.agents/scripts/lib/orchestration/preflight-cache.js

@@ -0,0 +1,164 @@
+/**
+ * preflight-cache.js — Epic #3019 / Story #3027.
+ *
+ * Cache adapter for the snapshot/DAG envelope produced by
+ * `epic-deliver-preflight.js` so `epic-deliver-prepare.js` can skip the
+ * second walk of Epic → Feature → Story when the underlying Epic ticket
+ * has not drifted between the two operator invocations.
+ *
+ * Contract:
+ *   - Cache file lives at `<cwd>/temp/epic-<epicId>/preflight-snapshot.json`.
+ *   - Envelope shape:
+ *       {
+ *         epicId: number,
+ *         baseSha: string,        // deterministic fingerprint of the Epic
+ *                                 // snapshot returned by provider.getTicket
+ *         capturedAt: string,     // ISO-8601 timestamp
+ *         epic: object,           // the snapshot from runSnapshotPhase
+ *         stories: object[],      // the open Story tickets from runBuildWaveDagPhase
+ *         waves: Array<Array<object>>, // wave DAG (ids + labels preserved)
+ *       }
+ *   - `computeBaseSha(epic)` derives the cache key from the same provider
+ *     call (`getTicket(epicId)`) used to walk the hierarchy. The hash
+ *     covers the Epic's id, body, labels (sorted), and (when present)
+ *     `updatedAt` — the same fields that drive Story discovery and the
+ *     acceptance-spec gate.
+ *   - Cache miss is signalled by `readCache` returning `null`. Callers
+ *     MUST fall back to a fresh snapshot/DAG pass.
+ *   - `writeCache` creates the parent directory recursively and writes
+ *     atomically (write to `<path>.tmp` then rename).
+ *
+ * The module is pure JS / node:fs — no provider dependency — so tests
+ * can exercise it without spinning up a GitHub mock.
+ */
+
+import { createHash } from 'node:crypto';
+import { mkdir, readFile, rename, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+
+/**
+ * Resolve the on-disk path for an Epic's preflight cache.
+ *
+ * @param {{ epicId: number, cwd?: string }} args
+ * @returns {string}
+ */
+export function preflightCachePath({ epicId, cwd }) {
+  if (!Number.isInteger(epicId) || epicId <= 0) {
+    throw new TypeError(
+      'preflightCachePath: epicId must be a positive integer',
+    );
+  }
+  const root = cwd ?? process.cwd();
+  return path.join(root, 'temp', `epic-${epicId}`, 'preflight-snapshot.json');
+}
+
+/**
+ * Stable string fingerprint of an Epic snapshot. The hash is keyed on the
+ * exact fields `runSnapshotPhase` reads (`getTicket(epicId)` return value)
+ * so that any drift the snapshot phase would observe forces a cache miss.
+ *
+ * Labels are sorted to absorb GitHub's non-deterministic label order
+ * across responses. The hash is sha256; we return the full hex digest so
+ * the cache key is collision-resistant for the lifetime of a delivery.
+ *
+ * @param {{ id?: number|string, number?: number|string, body?: string, labels?: string[], updatedAt?: string }} epic
+ * @returns {string}
+ */
+export function computeBaseSha(epic) {
+  if (!epic || typeof epic !== 'object') {
+    throw new TypeError('computeBaseSha: epic snapshot must be an object');
+  }
+  const id = epic.id ?? epic.number ?? null;
+  const body = typeof epic.body === 'string' ? epic.body : '';
+  const labels = Array.isArray(epic.labels)
+    ? [...epic.labels].map(String).sort()
+    : [];
+  const updatedAt = typeof epic.updatedAt === 'string' ? epic.updatedAt : null;
+  const payload = JSON.stringify({ id, body, labels, updatedAt });
+  return createHash('sha256').update(payload).digest('hex');
+}
+
+/**
+ * Read the cached preflight envelope from disk. Returns `null` when the
+ * file is missing or unreadable — callers MUST treat that as a cache
+ * miss and fall back to a fresh snapshot/DAG pass.
+ *
+ * The function intentionally swallows `ENOENT` and JSON-parse errors so
+ * a stale or partially-written file does not poison `epic-deliver-prepare`.
+ *
+ * @param {{ epicId: number, cwd?: string }} args
+ * @returns {Promise<object | null>}
+ */
+export async function readPreflightCache({ epicId, cwd }) {
+  const cachePath = preflightCachePath({ epicId, cwd });
+  let raw;
+  try {
+    raw = await readFile(cachePath, 'utf8');
+  } catch (err) {
+    if (err && err.code === 'ENOENT') return null;
+    throw err;
+  }
+  try {
+    const parsed = JSON.parse(raw);
+    if (!parsed || typeof parsed !== 'object') return null;
+    if (parsed.epicId !== epicId) return null;
+    if (typeof parsed.baseSha !== 'string' || !parsed.baseSha) return null;
+    if (!parsed.epic || typeof parsed.epic !== 'object') return null;
+    if (!Array.isArray(parsed.stories)) return null;
+    if (!Array.isArray(parsed.waves)) return null;
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Persist the preflight envelope to disk. Writes atomically via tmp +
+ * rename so concurrent readers never observe a partial file.
+ *
+ * @param {{ epicId: number, baseSha: string, epic: object, stories: object[], waves: Array<Array<object>>, cwd?: string, capturedAt?: string }} args
+ * @returns {Promise<{ cachePath: string, baseSha: string }>}
+ */
+export async function writePreflightCache({
+  epicId,
+  baseSha,
+  epic,
+  stories,
+  waves,
+  cwd,
+  capturedAt,
+}) {
+  if (!Number.isInteger(epicId) || epicId <= 0) {
+    throw new TypeError(
+      'writePreflightCache: epicId must be a positive integer',
+    );
+  }
+  if (typeof baseSha !== 'string' || !baseSha) {
+    throw new TypeError(
+      'writePreflightCache: baseSha must be a non-empty string',
+    );
+  }
+  if (!epic || typeof epic !== 'object') {
+    throw new TypeError('writePreflightCache: epic must be an object');
+  }
+  if (!Array.isArray(stories)) {
+    throw new TypeError('writePreflightCache: stories must be an array');
+  }
+  if (!Array.isArray(waves)) {
+    throw new TypeError('writePreflightCache: waves must be an array');
+  }
+  const cachePath = preflightCachePath({ epicId, cwd });
+  await mkdir(path.dirname(cachePath), { recursive: true });
+  const envelope = {
+    epicId,
+    baseSha,
+    capturedAt: capturedAt ?? new Date().toISOString(),
+    epic,
+    stories,
+    waves,
+  };
+  const tmp = `${cachePath}.tmp`;
+  await writeFile(tmp, `${JSON.stringify(envelope, null, 2)}\n`, 'utf8');
+  await rename(tmp, cachePath);
+  return { cachePath, baseSha };
+}

package/.agents/scripts/lib/orchestration/reassert-status-column.js

@@ -0,0 +1,202 @@
+/**
+ * reassert-status-column — re-fire `ColumnSync` against a ticket's
+ * current label set so the GitHub Projects v2 Status column matches the
+ * orchestrator's view (Story #2845, hardened in Story #2876).
+ *
+ * Why a dedicated helper:
+ *   `transitionTicketState` already calls `syncProjectStatusColumn` at
+ *   label-flip time, but the GitHub built-in `Pull request merged` /
+ *   `Pull request linked to issue` workflows fire ~minutes after the
+ *   PR auto-merges and overwrite Status. The orchestrator's close path
+ *   has long-since exited by then, so "the last write" is the bot's.
+ *   This helper is invoked AFTER the merge confirmation step (via the
+ *   `resync-status-column.js` CLI the `/single-story-deliver` workflow
+ *   doc calls) to reassert authority and win the race deterministically.
+ *
+ *   Operators who disable the conflicting bot workflows (via the
+ *   `--reap-conflicting-workflows` bootstrap flag) get the same outcome
+ *   without needing the re-sync. The helper is defense-in-depth and is
+ *   cheap to fire — Story #2876 added a bounded poll-and-retry loop so
+ *   the defense actually works against an asynchronous bot overwrite
+ *   that lands after the initial mutation. Without the loop, a one-shot
+ *   mutation routinely lost the race (reproduced on Story #2871 /
+ *   PR #2872).
+ *
+ * Surface:
+ *   - {@link reassertStatusColumn} — read the ticket's current labels,
+ *     pick the canonical column via {@link columnForLabels}, push it
+ *     via `ColumnSync.sync`, then poll the live Status for a bounded
+ *     window and re-fire on drift. Returns the sync envelope augmented
+ *     with `attempts`.
+ */
+
+import { ColumnSync, columnForLabels } from './column-sync.js';
+
+/**
+ * Default total mutation attempts (including the initial sync). At
+ * `pollDelayMs = 5000`, four attempts cover a ~15 s defense window —
+ * long enough to outlast the typical GitHub built-in workflow fire
+ * timing without ballooning the close-path wall clock.
+ */
+export const DEFAULT_POLL_ATTEMPTS = 4;
+
+/**
+ * Default delay between drift checks (ms). Five seconds is a sweet
+ * spot: short enough that the operator doesn't perceive the close
+ * path as hung, long enough that one re-fire usually wins the race.
+ */
+export const DEFAULT_POLL_DELAY_MS = 5000;
+
+/**
+ * Production sleep function. Tests inject `sleepFn: () => Promise.resolve()`
+ * so the poll loop runs instantly.
+ *
+ * @param {number} ms
+ * @returns {Promise<void>}
+ */
+function defaultSleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/**
+ * Re-assert the Status column for a single ticket. Reads the ticket's
+ * current labels so the caller doesn't have to pass them (the typical
+ * use site is a post-merge CLI that knows the ticket id only).
+ *
+ * Returns the same envelope shape as `ColumnSync.sync`, augmented with
+ * `attempts` (the number of mutations actually fired):
+ *   - `{ status: 'synced', column, attempts }` — the mutation landed
+ *     and the drift-check confirmed Status matches the target. If
+ *     drift was detected and re-fired, `attempts` reflects the total
+ *     mutation count.
+ *   - `{ status: 'drifted', column, attempts }` — the helper exhausted
+ *     `pollAttempts` and the live Status still didn't match the
+ *     target. Returned, not thrown — the caller decides whether to
+ *     escalate. `column` carries the target column the helper was
+ *     trying to set.
+ *   - `{ status: 'skipped', reason }` — no-op for an enumerated reason
+ *     (`no-matching-label`, `no-project`, `no-meta`, `no-option-<col>`,
+ *     `not-on-project`). Skip paths short-circuit before the poll loop.
+ *
+ * Throws when the provider is unusable. Other failures (GraphQL,
+ * network) propagate from `ColumnSync.sync` and `provider.getTicket` —
+ * callers wrap in try/catch if they want best-effort semantics.
+ *
+ * @param {{
+ *   provider: { getTicket: Function, graphql: Function, owner: string, repo: string, projectNumber?: number|null },
+ *   ticketId: number,
+ *   logger?: { info: Function, warn: Function },
+ *   pollAttempts?: number,
+ *   pollDelayMs?: number,
+ *   sleepFn?: (ms: number) => Promise<void>,
+ * }} args
+ * @returns {Promise<{ status: string, column?: string, reason?: string, attempts?: number }>}
+ */
+export async function reassertStatusColumn(args) {
+  const {
+    provider,
+    ticketId,
+    logger,
+    pollAttempts = DEFAULT_POLL_ATTEMPTS,
+    pollDelayMs = DEFAULT_POLL_DELAY_MS,
+    sleepFn = defaultSleep,
+  } = args ?? {};
+  if (!provider || typeof provider.getTicket !== 'function') {
+    throw new TypeError(
+      'reassertStatusColumn requires a provider with getTicket',
+    );
+  }
+  if (typeof provider.graphql !== 'function') {
+    throw new TypeError(
+      'reassertStatusColumn requires a provider with graphql (for ColumnSync)',
+    );
+  }
+  if (!Number.isInteger(ticketId) || ticketId <= 0) {
+    throw new TypeError(
+      'reassertStatusColumn requires a positive integer ticketId',
+    );
+  }
+  if (!Number.isInteger(pollAttempts) || pollAttempts <= 0) {
+    throw new TypeError(
+      'reassertStatusColumn requires a positive integer pollAttempts',
+    );
+  }
+
+  const ticket = await provider.getTicket(ticketId);
+  const labels = Array.isArray(ticket?.labels) ? ticket.labels : [];
+  const targetColumn = columnForLabels(labels);
+  if (!targetColumn) {
+    return { status: 'skipped', reason: 'no-matching-label' };
+  }
+  const sync = new ColumnSync({ provider, logger: logger ?? console });
+
+  // First attempt — always fires through ColumnSync.sync so the skip
+  // paths (no-project / no-meta / no-option-<col> / not-on-project)
+  // short-circuit before we enter the poll loop.
+  const initial = await sync.sync(ticketId, labels);
+  if (initial.status !== 'synced') {
+    return initial;
+  }
+  let attempts = 1;
+  let lastEnvelope = { ...initial, attempts };
+
+  // Drift loop — read live Status, re-fire if it doesn't match the
+  // target column. Bounded by pollAttempts so a hostile bot can't
+  // stall the close path indefinitely.
+  for (let i = 1; i < pollAttempts; i += 1) {
+    await sleepFn(pollDelayMs);
+    let current;
+    try {
+      current = await sync.readCurrentColumn(ticketId);
+    } catch (err) {
+      logger?.warn?.(
+        `[reassertStatusColumn] drift-check #${i} failed (transient): ${
+          err?.message ?? err
+        }. Continuing.`,
+      );
+      continue;
+    }
+    if (current === targetColumn) {
+      // Sticky confirmation — return the existing envelope.
+      return lastEnvelope;
+    }
+    logger?.info?.(
+      `[reassertStatusColumn] drift detected on attempt ${i} (current=${
+        current ?? '<null>'
+      } target=${targetColumn}); re-firing.`,
+    );
+    try {
+      const next = await sync.sync(ticketId, labels);
+      attempts += 1;
+      // Skip envelopes during the retry loop are unexpected once we've
+      // already synced once; preserve their shape but stop retrying.
+      if (next.status !== 'synced') {
+        return { ...next, attempts };
+      }
+      lastEnvelope = { ...next, attempts };
+    } catch (err) {
+      logger?.warn?.(
+        `[reassertStatusColumn] re-fire attempt ${i} failed (transient): ${
+          err?.message ?? err
+        }. Continuing.`,
+      );
+    }
+  }
+
+  // Exhausted the poll budget — final drift read to report the
+  // honest outcome to the caller.
+  let final;
+  try {
+    final = await sync.readCurrentColumn(ticketId);
+  } catch {
+    final = null;
+  }
+  if (final === targetColumn) {
+    return lastEnvelope;
+  }
+  return {
+    status: 'drifted',
+    column: targetColumn,
+    attempts,
+  };
+}

package/.agents/scripts/lib/orchestration/reconciler.js

@@ -0,0 +1,137 @@
+/**
+ * lib/orchestration/reconciler.js — Ticket Hierarchy Reconciliation
+ */
+
+import { Logger } from '../Logger.js';
+import { AGENT_LABELS, TYPE_LABELS } from '../label-constants.js';
+import { concurrentMap } from '../util/concurrent-map.js';
+import { STATE_LABELS } from './ticketing.js';
+
+const AGENT_DONE_LABEL = STATE_LABELS.DONE;
+
+// Inlined parent-id parser. The reconciler only needs the direct parent
+// reference scraped from a ticket body's `parent: #N` trailer; pulling the
+// helper inline keeps reconciler.js self-contained for the 3-tier
+// hierarchy walk (Stories → Features).
+const PARENT_ID_PATTERN = /^parent:\s*#(\d+)/m;
+
+function parseParentIdFromBody(body) {
+  const match = (body ?? '').match(PARENT_ID_PATTERN);
+  return match ? Number.parseInt(match[1], 10) : null;
+}
+
+// Cap=4 — bounded parallelism for ticket-update fan-outs. Reconciliation
+// iterates an Epic-sized set of independent GitHub mutations; cap matches
+// the established pattern across the orchestration layer (wave-gate,
+// progress-reporter, sub-issue link reconcile) and stays well under the
+// secondary rate-limit ceiling observed for issue PATCHes.
+const RECONCILE_CONCURRENCY = 4;
+
+/**
+ * Reconcile the ticket hierarchy bottom-up (Stories → Features).
+ *
+ * Walks every Story and Feature under the Epic; if all children of a
+ * container are done, closes the container and applies `agent::done`.
+ *
+ * Epic auto-closure is intentionally excluded — Epics close only through
+ * the formal `/epic-deliver` workflow.
+ *
+ * Per-ticket provider failures are logged and swallowed so a single bad
+ * ticket cannot halt reconciliation across the rest of the graph.
+ *
+ * @param {import('../ITicketingProvider.js').ITicketingProvider} provider  Ticketing provider.
+ * @param {number} _epicId                                               Epic id (reserved — currently unused; kept for call-site stability).
+ * @param {object} _epic                                                 Epic ticket record (reserved — currently unused).
+ * @param {object[]} allTickets                                          Every ticket under the Epic.
+ * @param {boolean} dryRun                                               When true, mutate nothing.
+ * @returns {Promise<void>}
+ */
+export async function reconcileHierarchy(
+  provider,
+  _epicId,
+  _epic,
+  allTickets,
+  dryRun,
+) {
+  const ticketMap = new Map(allTickets.map((t) => [t.id, t]));
+
+  const childrenOf = new Map();
+  for (const ticket of allTickets) {
+    const parentId = parseParentIdFromBody(ticket.body);
+    if (parentId != null) {
+      if (!childrenOf.has(parentId)) childrenOf.set(parentId, []);
+      childrenOf.get(parentId).push(ticket.id);
+    }
+  }
+
+  function isDone(ticketId) {
+    const t = ticketMap.get(ticketId);
+    if (!t) return false;
+    return (
+      t.state === 'closed' ||
+      (t.labelSet ?? new Set(t.labels)).has(AGENT_DONE_LABEL)
+    );
+  }
+
+  function shouldClose(id) {
+    const ticket = ticketMap.get(id);
+    if (!ticket || ticket.state === 'closed') return null;
+    const children = childrenOf.get(id) ?? [];
+    if (children.length === 0) return null;
+    if (!children.every((cid) => isDone(cid))) return null;
+    return ticket;
+  }
+
+  async function applyClose(id, typeName, ticket) {
+    try {
+      await provider.updateTicket(id, {
+        labels: {
+          add: [AGENT_DONE_LABEL],
+          remove: [AGENT_LABELS.READY, AGENT_LABELS.EXECUTING],
+        },
+        state: 'closed',
+        state_reason: 'completed',
+      });
+      ticket.state = 'closed';
+      Logger.info(`✅ ${typeName} #${id} closed and marked agent::done.`);
+    } catch (err) {
+      Logger.warn(`Failed to close ${typeName} #${id}: ${err.message}`);
+    }
+  }
+
+  async function maybeClose(id, typeName) {
+    const ticket = shouldClose(id);
+    if (!ticket) return;
+    Logger.info(
+      `All children of ${typeName} #${id} "${ticket.title}" are done. Closing...`,
+    );
+    if (dryRun) {
+      Logger.info(
+        `[DRY-RUN] Would close ${typeName} #${id} and set agent::done.`,
+      );
+      ticket.state = 'closed';
+      return;
+    }
+    await applyClose(id, typeName, ticket);
+  }
+
+  const storyIds = allTickets
+    .filter((t) => (t.labelSet ?? new Set(t.labels)).has(TYPE_LABELS.STORY))
+    .map((t) => t.id);
+  const featureIds = allTickets
+    .filter((t) => (t.labelSet ?? new Set(t.labels)).has(TYPE_LABELS.FEATURE))
+    .map((t) => t.id);
+
+  // cap=4 — Stories are container leaves of this reconcile (their children
+  // are Tasks already settled by reconcileClosedTasks); independent close
+  // mutations can fan out without ordering. Features stay sequential because
+  // a Feature may parent another Feature, and bottom-up close depends on
+  // child-Feature state already being mutated in the same pass.
+  await concurrentMap(storyIds, (id) => maybeClose(id, 'Story'), {
+    concurrency: RECONCILE_CONCURRENCY,
+  });
+  for (const id of featureIds) await maybeClose(id, 'Feature');
+
+  // EXCLUSION: Epic auto-closure removed.
+  // The Epic ticket now stays open until the formal /epic-deliver workflow is executed.
+}

package/.agents/scripts/lib/orchestration/recurring-failure-detector.js

@@ -0,0 +1,152 @@
+// .agents/scripts/lib/orchestration/recurring-failure-detector.js
+/**
+ * recurring-failure-detector.js — Story #3062 / Epic #3051.
+ *
+ * Pure helper that scans a per-Epic lifecycle ledger for
+ * `close-validate.end` `emitted` records and groups them by `failedGate`.
+ * Returns one finding per gate that appears in **two or more distinct
+ * Stories** within the same Epic. Findings are the substrate
+ * `/epic-deliver` consumes when upserting the cross-Story
+ * `recurring-failure-class` structured comment on the Epic ticket.
+ *
+ * The helper is intentionally pure: no GitHub I/O, no global state. It
+ * accepts either a pre-parsed `records[]` array (the hot path used by
+ * `wave-tick` once it has already read the ledger for its in-flight
+ * reconciliation) or a `ledgerPath` string (the convenience path that
+ * reads + parses NDJSON on its own). When both are supplied,
+ * `records` wins — the caller already paid the parse cost.
+ *
+ * Finding shape (sorted lexicographically by `gate` for determinism):
+ *
+ *   { gate: string, storyIds: number[], firstSeenAt: string, lastSeenAt: string }
+ *
+ * - `storyIds` is the deduplicated, ascending list of Story IDs that
+ *   recorded a `close-validate.end` with `ok: false` and this gate.
+ * - `firstSeenAt` / `lastSeenAt` are ISO-8601 strings pulled from the
+ *   ledger record's top-level `ts` (set by `LedgerWriter.buildEmitted`),
+ *   which is the canonical wall-clock for the event.
+ *
+ * @module lib/orchestration/recurring-failure-detector
+ */
+
+import { existsSync, readFileSync } from 'node:fs';
+
+/**
+ * Detect recurring failure classes across Stories within one Epic.
+ *
+ * @param {number} epicId Positive integer — the Epic the ledger belongs
+ *   to. Used only for validation (the helper does not filter records by
+ *   epicId; the ledger is already epic-scoped on disk).
+ * @param {object} [opts]
+ * @param {Array<object>} [opts.records] Pre-parsed NDJSON records. Each
+ *   entry is the object emitted by `LedgerWriter.buildEmitted`
+ *   (`{ kind, seqId, ts, event, payload }`).
+ * @param {string} [opts.ledgerPath] Filesystem path to `lifecycle.ndjson`.
+ *   Read + parsed only when `records` is absent. A missing file returns
+ *   an empty findings array (no throw).
+ * @returns {Array<{gate: string, storyIds: number[], firstSeenAt: string, lastSeenAt: string}>}
+ */
+export function detectRecurringFailures(epicId, opts = {}) {
+  if (!Number.isInteger(epicId) || epicId <= 0) {
+    throw new TypeError(
+      'detectRecurringFailures: epicId must be a positive integer',
+    );
+  }
+  const records = resolveRecords(opts);
+  if (records.length === 0) return [];
+
+  /** @type {Map<string, {storyIds: Set<number>, firstSeenAt: string, lastSeenAt: string}>} */
+  const byGate = new Map();
+  for (const record of records) {
+    const finding = extractFailedGateRecord(record);
+    if (!finding) continue;
+    const { gate, storyId, ts } = finding;
+    const bucket = byGate.get(gate);
+    if (!bucket) {
+      byGate.set(gate, {
+        storyIds: new Set([storyId]),
+        firstSeenAt: ts,
+        lastSeenAt: ts,
+      });
+      continue;
+    }
+    bucket.storyIds.add(storyId);
+    if (ts < bucket.firstSeenAt) bucket.firstSeenAt = ts;
+    if (ts > bucket.lastSeenAt) bucket.lastSeenAt = ts;
+  }
+
+  const findings = [];
+  for (const [gate, bucket] of byGate) {
+    if (bucket.storyIds.size < 2) continue;
+    findings.push({
+      gate,
+      storyIds: Array.from(bucket.storyIds).sort((a, b) => a - b),
+      firstSeenAt: bucket.firstSeenAt,
+      lastSeenAt: bucket.lastSeenAt,
+    });
+  }
+  findings.sort((a, b) => (a.gate < b.gate ? -1 : a.gate > b.gate ? 1 : 0));
+  return findings;
+}
+
+/**
+ * Resolve the records array from caller opts. Pre-parsed `records` wins
+ * over a `ledgerPath` so callers that already loaded the file (e.g.
+ * `wave-tick.js` doing its in-flight reconciliation) don't pay the parse
+ * cost twice. A missing ledger file is treated as "no records" — the
+ * tick must remain stateless and must not throw when nothing has
+ * happened yet on this Epic.
+ *
+ * @param {object} opts
+ * @returns {Array<object>}
+ */
+function resolveRecords(opts) {
+  if (Array.isArray(opts.records)) return opts.records;
+  if (typeof opts.ledgerPath !== 'string' || opts.ledgerPath.length === 0) {
+    return [];
+  }
+  if (!existsSync(opts.ledgerPath)) return [];
+  let raw;
+  try {
+    raw = readFileSync(opts.ledgerPath, 'utf8');
+  } catch {
+    return [];
+  }
+  if (!raw) return [];
+  const out = [];
+  for (const line of raw.split(/\r?\n/)) {
+    if (!line) continue;
+    try {
+      out.push(JSON.parse(line));
+    } catch {
+      // Malformed line — skip; the ledger is append-only NDJSON and a
+      // partial write at process death is the only realistic source of
+      // un-parseable lines. The next tick will see the completed line.
+    }
+  }
+  return out;
+}
+
+/**
+ * Decide whether a ledger record is a `close-validate.end` `emitted`
+ * payload carrying a failed gate, and if so extract the
+ * `(gate, storyId, ts)` triple the bucketing loop consumes. Returns
+ * `null` for any record that doesn't satisfy every guard.
+ *
+ * @param {object} record
+ * @returns {{gate: string, storyId: number, ts: string} | null}
+ */
+function extractFailedGateRecord(record) {
+  if (!record || record.kind !== 'emitted') return null;
+  if (record.event !== 'close-validate.end') return null;
+  const payload = record.payload;
+  if (!payload || typeof payload !== 'object') return null;
+  if (payload.ok !== false) return null;
+  const gate = payload.failedGate;
+  if (typeof gate !== 'string' || gate.length === 0) return null;
+  const storyId = payload.storyId;
+  if (!Number.isInteger(storyId) || storyId <= 0) return null;
+  const ts = typeof record.ts === 'string' && record.ts ? record.ts : '';
+  if (!ts) return null;
+  return { gate, storyId, ts };
+}