@dzhechkov/harness-core 0.8.36 → 0.8.38

package/src/apply-leg.ts

@@ -190,8 +190,26 @@ export function probeRecallEngine(socketPath: string, timeoutMs = 1000): Promise
  * the cosine-fallback `scored` array are filtered to exclude `domain === 'apply-leg-probe'` unless
  * the request carried `probe: true` — a probe's own beacon still needs to reach ITS query, only a
  * REAL prompt must never see it.
+ *
+ * Bumped 10→11 (feature `embed-daemon-memory`, ADR-001 D1): the daemon now tries core's OWN cached
+ * embedder (`resolveAgentdbEmbedder`) first — one pipeline per process — building a private one only
+ * when core cannot hand one over; `ready` gained the ` embedder=<core-shared|own-fallback>` suffix
+ * (see `features/embed-daemon-memory/07_code_changes/change_manifest.md` for the full T3 note; this
+ * paragraph was missing from the bump history and is added here for the record, fix round 1).
+ *
+ * Bumped 11→12 (`embed-daemon-memory`, fix round 1 — F1/F2, Codex #1b/#3): (a) F1 — the own-fallback
+ * pipeline now reads the STORE's own dtype manifest before building (absent = fp32 legacy, a
+ * present-but-unrecognized value fails the request loudly instead of silently building fp32 against
+ * a q8 store); `ready`'s own-fallback branch gains ` dtype=<fp32|q8|error>`. (b) F2 — a core-shared
+ * STARTUP init failure no longer falls back to building an own pipeline (which risked a second live
+ * embedder once a later hybrid call succeeded): `embedderSource` stays `'core-shared'` and `embed`
+ * re-resolves `core.resolveAgentdbEmbedder` per request instead; `ready` names a startup failure
+ * inline as `core-shared (init failed: <msg>, will retry per request)`; `warmUpHybridEngine()` is
+ * skipped entirely in own-fallback mode. (c) `answerRecall`'s `embed(prompt)` call is now wrapped so
+ * either failure mode degrades to the SAME honest `cosine-fallback` reply shape as every other
+ * failure, never a bare protocol `{error}`.
  */
-export const APPLY_LEG_VERSION = 10;
+export const APPLY_LEG_VERSION = 12;
 
 /**
  * Parse the `dz-apply-leg-version` stamp from a deployed helper file. Unlike
@@ -1027,6 +1045,18 @@ function socketAlive(path) {
   });
 }
 
+// ADR-001 (embed-daemon-memory, D1/T3): better-sqlite3 is resolved INDEPENDENTLY of the embedder now
+// — the cosine-fallback leg always needs it to read the mirror, regardless of whether the embedder
+// itself comes from core (embedder=core-shared) or this daemon's own pipeline (embedder=own-fallback).
+// Splitting it out of the old resolveDeps() lets the daemon start on core-shared alone when only
+// better-sqlite3 (not transformers) is locally resolvable.
+function resolveDatabase() {
+  const req = createRequire(join(PROJECT, 'package.json'));
+  return req('better-sqlite3');
+}
+
+// own-fallback ONLY (ADR-001 D1): resolves the transformers module for the daemon's OWN pipeline,
+// built only when core has no resolveAgentdbEmbedder to share (no core module, or it errored).
 function resolveDeps() {
   const req = createRequire(join(PROJECT, 'package.json'));
   // agentdb >= 3.0.0-alpha depends on '@huggingface/transformers' (the '@xenova/transformers'
@@ -1054,7 +1084,7 @@ function resolveDeps() {
   if (transformers === undefined) {
     throw new Error('neither @huggingface/transformers nor @xenova/transformers could be resolved (' + String((lastErr && lastErr.message) || lastErr) + ')');
   }
-  return { Database: req('better-sqlite3'), transformers };
+  return { transformers };
 }
 
 const cos = (a, b) => {
@@ -1119,17 +1149,151 @@ async function main() {
 
   const started = Date.now();
   const model = configuredModel();
-  let deps;
+
+  // better-sqlite3 is required regardless of which embedder answers a request (ADR-001, T3) — the
+  // cosine-fallback leg always reads the mirror through it.
+  let Database;
   try {
-    deps = resolveDeps();
+    Database = resolveDatabase();
   } catch (err) {
     log('deps unavailable — not starting:', err?.message ?? err);
     process.exit(0); // never a hard failure: the hook degrades to silence
   }
 
-  const { pipeline } = await import(deps.transformers);
-  const extractor = await pipeline('feature-extraction', model);
-  const embed = async (text) => Array.from((await extractor(text, { pooling: 'mean', normalize: true })).data);
+  // ADR-001 D1 (embed-daemon-memory): the daemon SHARES core's single per-process embedder and
+  // builds a private pipeline only when core cannot hand one over AT ALL — no core module, or a core
+  // build too old to export \`resolveAgentdbEmbedder\` (F2, fix round 1, Codex #3). A STARTUP init
+  // FAILURE (core exists, has the export, but the call itself errored — offline model cache, a
+  // corrupted manifest) is NEVER treated as "core unavailable": own-fallback must not be built in
+  // that case, because a LATER hybrid call could succeed and stand up a SECOND, independent pipeline
+  // in the same process — the exact "two live embedders" defect the review named. Instead
+  // \`embedderSource\` STAYS \`'core-shared'\` and \`embed\` re-resolves \`core.resolveAgentdbEmbedder\`
+  // on EVERY call: core's own per-process cache (agentdb-index.ts) makes a repeat call after SUCCESS
+  // effectively free, and evicts its own entry on failure — so a transient startup failure can heal
+  // on a later request without this daemon ever building an embedder of its own.
+  //
+  // The shared embedder is still PROBED EAGERLY, before \`ready\`, for the same reason the own
+  // pipeline always was: the cosine-fallback leg must answer inside the hook budget on the FIRST
+  // request too (parity AC-2: hybrid delayed by 3000 ms, reply < 2000 ms). MEASURED 2026-09-16
+  // (change_manifest.md, deviation B): a LAZY resolve put the cold pipeline init (2000-3600 ms) on
+  // the first fallback reply — 4/5 runs at 2063-2146 ms. The probe's OUTCOME only decides the
+  // \`ready\`-log wording now (F2) — it never gates \`embedderSource\` or builds an own-fallback
+  // pipeline. The starved-budget parity test that used to lean on a cold engine now injects
+  // DZ_EMBED_HYBRID_DELAY_MS itself, so its premise holds by construction, not by cold timing.
+  let embed;
+  let embedderSource;
+  let embedderReadyDetail = '';
+  let ownFallbackDtypeLabel;
+  const startupCore = await loadCoreModule();
+  const coreHasSharedEmbedder = startupCore !== undefined && typeof startupCore.resolveAgentdbEmbedder === 'function';
+  if (coreHasSharedEmbedder) {
+    embedderSource = 'core-shared';
+    embed = async (text) => {
+      const shared = await startupCore.resolveAgentdbEmbedder(PROJECT);
+      if (!shared || typeof shared.embed !== 'function' || 'error' in shared) {
+        throw new Error((shared && shared.error) || 'resolveAgentdbEmbedder returned no embed()');
+      }
+      return shared.embed(text);
+    };
+    let startupProbe;
+    try {
+      startupProbe = await startupCore.resolveAgentdbEmbedder(PROJECT);
+    } catch (err) {
+      startupProbe = { error: err?.message ?? String(err) };
+    }
+    if (!startupProbe || typeof startupProbe.embed !== 'function' || 'error' in startupProbe) {
+      const msg = (startupProbe && startupProbe.error) || 'resolveAgentdbEmbedder returned no embed()';
+      log('core-shared embedder init failed at startup, will retry per request:', msg);
+      embedderReadyDetail = \` (init failed: \${msg}, will retry per request)\`;
+    }
+  }
+  if (embed === undefined) {
+    // own-fallback: ONLY when core has no resolveAgentdbEmbedder to share at all (no core module, or
+    // a fake/old core, as in test fixtures) — never as a reaction to a startup init error (above).
+    let deps;
+    try {
+      deps = resolveDeps();
+    } catch (err) {
+      log('deps unavailable — not starting:', err?.message ?? err);
+      process.exit(0); // never a hard failure: the hook degrades to silence
+    }
+    // F1 (fix round 1, Codex #1b): the daemon has no core to ask, so it reads the STORE's own dtype
+    // manifest directly — an own pipeline built blindly at fp32 would silently compare vectors from
+    // two different spaces against a q8 store. Absent manifest = fp32 (legacy — matches every store
+    // predating this feature, same discipline as embedding-config.ts's readEmbedManifest). A manifest
+    // that IS present but names neither known dtype is NEVER folded into that same fp32 case — this
+    // daemon fails loudly for that request (embed() throws below, caught honestly by answerRecall)
+    // rather than silently mixing dtype spaces.
+    const manifestPath = join(PROJECT, '.dz', 'agentdb.db.embed-manifest.json');
+    let ownDtype = 'fp32';
+    let ownDtypeError;
+    let manifestIsFile = false;
+    try {
+      manifestIsFile = statSync(manifestPath).isFile(); // a non-file at the sidecar path is "absent", as in core
+    } catch {
+      manifestIsFile = false;
+    }
+    if (manifestIsFile) {
+      try {
+        const raw = JSON.parse(readFileSync(manifestPath, 'utf-8'))?.dtype;
+        if (raw === 'fp32' || raw === 'q8') {
+          ownDtype = raw;
+        } else if (raw !== undefined) {
+          ownDtypeError = String(raw);
+        }
+      } catch (err) {
+        // Lead delta after Codex r2 (HIGH): a manifest that EXISTS but cannot be parsed is NOT
+        // "absent" — refusing beats guessing fp32 over a q8 store (same rule as core's readError).
+        ownDtypeError = 'unreadable manifest: ' + (err?.message ?? String(err));
+      }
+    }
+    embedderSource = 'own-fallback';
+    if (ownDtypeError !== undefined) {
+      log('manifest dtype unknown:', ownDtypeError);
+      ownFallbackDtypeLabel = 'error';
+      const dtypeErrMsg = \`manifest dtype unknown: \${ownDtypeError}\`;
+      embed = async () => { throw new Error(dtypeErrMsg); };
+    } else {
+      ownFallbackDtypeLabel = ownDtype;
+      const { pipeline } = await import(deps.transformers);
+      const extractor = await pipeline('feature-extraction', model, ownDtype === 'q8' ? { dtype: 'q8' } : {});
+      embed = async (text) => Array.from((await extractor(text, { pooling: 'mean', normalize: true })).data);
+    }
+  }
+
+  // AM-1 (fix round 1): warm resolveAgentdbEmbedder — cached PER PROCESS since db1521ba (cold
+  // ~2-3.6 s, warm ~1 ms, MEASURED, see the manifest's T8/AM-1 discussion) — OFF the request path,
+  // so the first REAL \`op: recall\` is not the one that pays the cold init. Fired fire-and-forget as
+  // early as main() can (moved up from right-before-listen, T3/embed-daemon-memory: every ms of
+  // extra head start matters against a multi-second cold cost — see change_manifest.md), never
+  // awaited by startup: this is a best-effort head start, not a guarantee — a request landing in
+  // the window before it completes still pays the (possibly-partial, since it JOINS the same
+  // in-flight resolveAgentdbEmbedder promise, D1) cold cost, and a warm-up failure (no core module,
+  // engine error) is silently swallowed — never-block applies to startup exactly as it does to a
+  // request. Measured: the slowest cold resolveAgentdbEmbedder init observed in this environment
+  // was 3653 ms (T8 log, 2026-09-14) — 10 s leaves a wide margin without risking an unbounded
+  // warm-up hang.
+  const WARMUP_TIMEOUT_MS = 10_000;
+  async function warmUpHybridEngine() {
+    const core = await loadCoreModule();
+    if (core === undefined) return;
+    const guard = new Promise((resolve) => {
+      const t = setTimeout(resolve, WARMUP_TIMEOUT_MS);
+      t.unref?.();
+    });
+    // An empty-string query still exercises the FULL semantic leg (embed + engine.search), which is
+    // exactly what needs warming; recallHybrid degrades any error inside it honestly, so nothing
+    // here needs its own try/catch beyond the outer .catch(() => {}) at the call site below.
+    await Promise.race([core.recallHybrid(PROJECT, '', { limit: 1, mode: 'hook', deferExposures: true }), guard]);
+  }
+  // Fire-and-forget, never awaited — main() proceeds immediately regardless of warm-up outcome.
+  // F2 (fix round 1, Codex #3): warm-up specifically primes the HYBRID leg's own use of
+  // resolveAgentdbEmbedder — pointless when this daemon has no core embedder to share (own-fallback
+  // has no core module, or a fake/old core in tests) AND risks standing up a SECOND, unrelated
+  // pipeline via whatever recallHybrid does internally in that case. Skipped entirely in own-fallback.
+  if (embedderSource === 'core-shared') {
+    warmUpHybridEngine().catch(() => {});
+  }
 
   // READ-ONLY. This process must never be the writer that tears the file for a concurrent reader.
   const dbPath = join(PROJECT, '.dz', 'agentdb.db');
@@ -1137,7 +1301,7 @@ async function main() {
 
   function loadPatterns() {
     if (!existsSync(dbPath)) return [];
-    const db = new deps.Database(dbPath, { readonly: true, fileMustExist: true });
+    const db = new Database(dbPath, { readonly: true, fileMustExist: true });
     try {
       const ph = DZ_TASK_TYPES.map(() => '?').join(',');
       // NOTE: the vector mirror carries no \`domain\` — that column lives in the lexical store. An
@@ -1249,36 +1413,22 @@ async function main() {
       patternsAt = Date.now();
     }
     if (patterns.length === 0) return { hits: [], engine: 'cosine-fallback', reason: hybrid.reason };
-    const qv = await embed(prompt);
+    // F1/F2 (fix round 1): \`embed()\` can now THROW honestly (own-fallback with an unrecognized
+    // manifest dtype, F1; core-shared re-resolution failing on this exact request, F2) — caught here
+    // so it degrades to the SAME honest cosine-fallback shape every other failure gets, never a bare
+    // protocol {error} reply reaching the socket handler's outer catch (the AM-3 defect class).
+    let qv;
+    try {
+      qv = await embed(prompt);
+    } catch (err) {
+      return { hits: [], engine: 'cosine-fallback', reason: \`embedder unavailable: \${err?.message ?? err}\` };
+    }
     const scored = patterns.map((p) => ({ dzId: p.dzId, pattern: p.pattern, score: cos(qv, p.vec), domain: p.domain, ...(p.quarantined ? { quarantined: true } : {}) }));
     scored.sort((a, b) => b.score - a.score);
     // AM-3: same domain exclusion as the hybrid leg, applied before slicing for the same reason.
     return { hits: filterProbeHits(scored, probe).slice(0, limit), engine: 'cosine-fallback', reason: hybrid.reason };
   }
 
-  // AM-1 (fix round 1): warm resolveAgentdbEmbedder — cached PER PROCESS since db1521ba (cold
-  // ~2-3.6 s, warm ~1 ms, MEASURED, see the manifest's T8/AM-1 discussion) — OFF the request path,
-  // so the first REAL \`op: recall\` is not the one that pays the cold init. Fired fire-and-forget
-  // right before \`listen()\` below, never awaited by startup: this is a best-effort head start, not
-  // a guarantee — a request landing in the few-hundred-ms window before it completes still pays the
-  // cold cost exactly as before this amendment, and a warm-up failure (no core module, engine
-  // error) is silently swallowed — never-block applies to startup exactly as it does to a request.
-  // Measured: the slowest cold resolveAgentdbEmbedder init observed in this environment was 3653 ms
-  // (T8 log, 2026-09-14) — 10 s leaves a wide margin without risking an unbounded warm-up hang.
-  const WARMUP_TIMEOUT_MS = 10_000;
-  async function warmUpHybridEngine() {
-    const core = await loadCoreModule();
-    if (core === undefined) return;
-    const guard = new Promise((resolve) => {
-      const t = setTimeout(resolve, WARMUP_TIMEOUT_MS);
-      t.unref?.();
-    });
-    // An empty-string query still exercises the FULL semantic leg (embed + engine.search), which is
-    // exactly what needs warming; recallHybrid degrades any error inside it honestly, so nothing
-    // here needs its own try/catch beyond the outer .catch(() => {}) at the call site below.
-    await Promise.race([core.recallHybrid(PROJECT, '', { limit: 1, mode: 'hook', deferExposures: true }), guard]);
-  }
-
   let idleTimer;
   let lastActivityAt = Date.now();
   const touch = () => {
@@ -1353,9 +1503,6 @@ async function main() {
 
   for (const sig of ['SIGINT', 'SIGTERM', 'SIGHUP']) process.on(sig, () => shutdown(0));
 
-  // AM-1: fire-and-forget, never awaited — bind proceeds immediately regardless of warm-up outcome.
-  warmUpHybridEngine().catch(() => {});
-
   // FR-3 ("absence of a receipt is not success"): \`ready\` is printed ONLY after \`listen\`'s callback
   // AND a fresh \`existsSync(SOCKET)\` both confirm the socket file is actually on disk — a caller
   // that greps stderr for "ready" must never see it for a socket that silently failed to bind.
@@ -1397,7 +1544,11 @@ async function main() {
         return bindFailed(\`could not publish socket pointer: \${err?.message ?? err}\`);
       }
     }
-    log(\`ready: \${patterns.length} pattern vectors, model \${model}, socket \${SOCKET}\`);
+    // F1/F2 (fix round 1): own-fallback names ITS resolved dtype (\`dtype=<fp32|q8|error>\`, F1); a
+    // core-shared daemon that failed its startup probe names that too, inline (\`(init failed: …,
+    // will retry per request)\`, F2) — both make the honest state observable from \`ready\` alone.
+    const embedderReadyLabel = embedderSource === 'own-fallback' ? \`\${embedderSource} dtype=\${ownFallbackDtypeLabel}\` : \`\${embedderSource}\${embedderReadyDetail}\`;
+    log(\`ready: \${patterns.length} pattern vectors, model \${model}, socket \${SOCKET} embedder=\${embedderReadyLabel}\`);
     touch();
   });
   server.on('error', (err) => bindFailed(err?.message ?? String(err)));

package/src/codex-rollouts.ts

@@ -0,0 +1,374 @@
+/**
+ * A pure reader for Codex CLI rollout logs (feature `measurement-integrity`, ADR-001 D3).
+ *
+ * A `dz feature-adr-record --kind ledger` row for a Codex coder/reviewer stage carries
+ * `tokens: null` in 130 of 156 recorded rows (Step 0, 2026-09-16) even though the spend is sitting
+ * right there on disk: Codex writes one JSONL file per session at
+ * `~/.codex/sessions/YYYY/MM/DD/rollout-<ts>-<uuid>.jsonl`, and nothing in the pipeline reads it. The
+ * pipeline dispatches Codex without an explicit session id (`codex exec -C <repo> -m <id> …`), so the
+ * only way to join a ledger row to the rollout that produced it is a WINDOW match: the stage's own
+ * start/end time, its `cwd`, and its model.
+ *
+ * PURE — this module never opens `~/.codex/sessions` itself; the CLI reads the files and hands their
+ * TEXT to {@link parseCodexRollout}. It must never gain a `node:fs` import (the `core-boundary`
+ * ratchet, `test/core-boundary.test.ts`, pins the current file/import count).
+ *
+ * ## A measured schema correction (read before touching the parser)
+ *
+ * Step 0's assessment described the usage record as `type: "token_count"`, keyed
+ * `payload.info.total_token_usage`. A live probe of this machine's `~/.codex/sessions` (2026-09-16,
+ * `cli_version: "0.154.0"`, every rollout from the last two days) found NO such record — the CURRENT
+ * shape is `type: "token_usage_record"`, keyed `payload.usage`, with the same five sub-fields
+ * (`input_tokens`, `cached_input_tokens`, `output_tokens`, `reasoning_output_tokens`,
+ * `total_tokens`). The model id lives on `type: "turn_context"`'s `payload.model` (not on
+ * `session_meta`, as Step 0 assumed), and `cwd` is carried by BOTH `session_meta.payload.cwd` and
+ * `turn_context.payload.cwd`. Rather than build against a shape that no longer exists on this
+ * machine, {@link parseCodexRollout} accepts BOTH the documented legacy shape and the measured
+ * current one — Codex CLI versions drift the schema (C-2: this module depends on no version beyond
+ * the fields it reads), and a reader that understands only a shape nothing on disk still emits would
+ * fail FR-5 at the exact thing it exists to fix.
+ *
+ * @packageDocumentation
+ */
+
+interface RawRecord {
+  readonly type?: unknown;
+  readonly timestamp?: unknown;
+  readonly ts?: unknown;
+  readonly payload?: unknown;
+}
+
+function isRecord(v: unknown): v is Record<string, unknown> {
+  return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+
+function nonEmptyString(v: unknown): string | null {
+  return typeof v === 'string' && v.length > 0 ? v : null;
+}
+
+function finiteNonNegative(v: unknown): number {
+  return typeof v === 'number' && Number.isFinite(v) && v >= 0 ? v : 0;
+}
+
+/** Epoch ms from a record's own `timestamp` (current schema) or `ts` (legacy/defensive), or `null`. */
+function recordTimeMs(rec: Record<string, unknown>): number | null {
+  const raw = rec['timestamp'] ?? rec['ts'];
+  if (typeof raw === 'number' && Number.isFinite(raw)) return raw;
+  if (typeof raw === 'string') {
+    const ms = Date.parse(raw);
+    return Number.isFinite(ms) ? ms : null;
+  }
+  return null;
+}
+
+function isoOrNull(ms: number | null): string | null {
+  if (ms === null || !Number.isFinite(ms) || Math.abs(ms) > 8.64e15) return null;
+  try {
+    return new Date(ms).toISOString();
+  } catch {
+    return null;
+  }
+}
+
+export interface CodexRolloutTotals {
+  readonly input: number;
+  readonly cachedInput: number;
+  readonly output: number;
+  readonly reasoning: number;
+  readonly total: number;
+}
+
+/**
+ * measurement-integrity fix-round-1/F5 (Codex r1 HIGH #5): one TURN of a session — the span between
+ * one `turn_context` record and the next (or the file's last record, for the final turn). A turn
+ * carries its OWN model/cwd (from ITS `turn_context`) and, when a usage-bearing record (`token_count`
+ * / `token_usage_record`) was seen while this turn was current, that record's totals — `null` when no
+ * such record fell inside this turn's interval (nothing to attribute to it).
+ */
+export interface CodexRolloutTurn {
+  readonly model: string | null;
+  readonly cwd: string | null;
+  readonly startedAt: string | null;
+  readonly endedAt: string | null;
+  readonly totals: CodexRolloutTotals | null;
+}
+
+export interface CodexRollout {
+  readonly id: string;
+  readonly cwd: string | null;
+  readonly model: string | null;
+  /** ISO, or `null` when no record in the file carried a parseable timestamp. */
+  readonly startedAt: string | null;
+  readonly endedAt: string | null;
+  readonly totals: CodexRolloutTotals;
+  /** measurement-integrity fix-round-1/F5: `'turn'` when the file carried at least one `turn_context`
+   *  record (the measured current schema always does) — {@link matchCodexRollouts} then matches at
+   *  TURN granularity, never against this whole session's wide interval. `'session'` when the schema
+   *  gave no turn boundaries at all (the legacy shape Step 0 documented) — matching honestly falls
+   *  back to the whole-session interval, and that fact travels with the result rather than being
+   *  silently assumed away. */
+  readonly granularity: 'turn' | 'session';
+  /** turns whose open or close boundary carried no timestamp — reported, never matched. */
+  readonly unmatchableTurns: number;
+  /** Empty when `granularity === 'session'`. */
+  readonly turns: readonly CodexRolloutTurn[];
+}
+
+export interface CodexRolloutParseError {
+  readonly error: string;
+}
+
+/** Pull `{input_tokens, cached_input_tokens, output_tokens, reasoning_output_tokens, total_tokens}`
+ *  (both schemas use these five field names) out of a usage-bearing sub-object. */
+function totalsFrom(usage: Record<string, unknown>): CodexRolloutTotals {
+  return {
+    input: finiteNonNegative(usage['input_tokens']),
+    cachedInput: finiteNonNegative(usage['cached_input_tokens']),
+    output: finiteNonNegative(usage['output_tokens']),
+    reasoning: finiteNonNegative(usage['reasoning_output_tokens']),
+    total: finiteNonNegative(usage['total_tokens']),
+  };
+}
+
+/**
+ * Parse ONE rollout file's full text into a {@link CodexRollout}. Pure, never-throws; a corrupt line
+ * is skipped exactly the way `extractCostSamples` (`cost-ledger.ts`) skips one.
+ *
+ * `fileName`, when given, is used ONLY as a last-resort `id` source (the `rollout-<ts>-<uuid>.jsonl`
+ * name's own uuid) when no `session_meta` record carried one — never trusted over the file's own
+ * content.
+ */
+export function parseCodexRollout(text: string, fileName?: string): CodexRollout | CodexRolloutParseError {
+  if (typeof text !== 'string' || text.trim().length === 0) {
+    return { error: 'empty rollout text' };
+  }
+
+  let id: string | null = null;
+  let cwd: string | null = null;
+  let sessionMetaModel: string | null = null;
+  let turnContextModel: string | null = null;
+  let firstMs: number | null = null;
+  let lastMs: number | null = null;
+  let lastTotals: CodexRolloutTotals | null = null;
+  let sawAnyRecord = false;
+
+  // measurement-integrity fix-round-1/F5 (Codex r1 HIGH #5): each `turn_context` record OPENS a new
+  // turn, in file order. `open` is the turn currently being built; `turns` collects CLOSED ones. A
+  // turn closes when the NEXT `turn_context` is seen (its `endedAt` is that boundary's own
+  // timestamp) or, for the LAST open turn, at end-of-file (`endedAt` = the last record's timestamp).
+  // A usage-bearing record is attached to whichever turn is open at its own timestamp — `null` stays
+  // on a turn that never saw one, so a caller can tell "nothing to attribute here" from "attributed
+  // zero".
+  // Lead delta after Codex r2 (#5 PARTIAL, new HIGH #1): a turn's totals are the DELTA of the
+  // session-cumulative usage between its open and close (the record's own usage counter is
+  // cumulative for the session — assigning the last cumulative total to a turn made the second turn
+  // carry the first one's tokens). `startedMs: null` marks a turn opened by a `turn_context` WITHOUT
+  // a timestamp: it still closes the previous turn (so no usage can leak into it) but can never be
+  // matched to a window — the rollout reports it under `unmatchableTurns`.
+  interface OpenTurn { model: string | null; cwd: string | null; startedMs: number | null; baseline: CodexRolloutTotals | null; totals: CodexRolloutTotals | null }
+  const closedTurns: CodexRolloutTurn[] = [];
+  let open: OpenTurn | null = null;
+
+  let unmatchableTurns = 0;
+  const closeOpenTurn = (endMs: number | null): void => {
+    if (open === null) return;
+    if (open.startedMs === null || endMs === null) unmatchableTurns += 1;
+    closedTurns.push({
+      model: open.model,
+      cwd: open.cwd,
+      startedAt: open.startedMs === null ? null : isoOrNull(open.startedMs),
+      endedAt: endMs === null ? null : isoOrNull(endMs),
+      totals: open.totals,
+    });
+  };
+  const deltaTotals = (now: CodexRolloutTotals, base: CodexRolloutTotals | null): CodexRolloutTotals => {
+    if (base === null) return now;
+    const d = (a: number, b: number): number => (a - b >= 0 ? a - b : a); // a counter that went DOWN is per-record, not cumulative
+    return { input: d(now.input, base.input), cachedInput: d(now.cachedInput, base.cachedInput), output: d(now.output, base.output), reasoning: d(now.reasoning, base.reasoning), total: d(now.total, base.total) };
+  };
+
+  for (const line of text.split('\n')) {
+    if (line.length === 0) continue;
+    let rec: unknown;
+    try {
+      rec = JSON.parse(line);
+    } catch {
+      continue; // corrupt line — skip, never throw
+    }
+    if (!isRecord(rec)) continue;
+    sawAnyRecord = true;
+
+    const ms = recordTimeMs(rec);
+    if (ms !== null) {
+      firstMs = firstMs === null ? ms : Math.min(firstMs, ms);
+      lastMs = lastMs === null ? ms : Math.max(lastMs, ms);
+    }
+
+    const type = rec['type'];
+    const payload = isRecord(rec['payload']) ? rec['payload'] : null;
+    if (payload === null) continue;
+
+    if (type === 'session_meta') {
+      if (id === null) id = nonEmptyString(payload['session_id']) ?? nonEmptyString(payload['id']);
+      if (cwd === null) cwd = nonEmptyString(payload['cwd']);
+      // Step 0's documented (legacy, not observed live on this machine) shape put `model` directly on
+      // `session_meta` — accepted here too, but `turnContextModel` always wins at the end (below)
+      // since that is what the measured current schema actually carries.
+      if (sessionMetaModel === null) sessionMetaModel = nonEmptyString(payload['model']);
+    } else if (type === 'turn_context') {
+      if (turnContextModel === null) turnContextModel = nonEmptyString(payload['model']);
+      if (cwd === null) cwd = nonEmptyString(payload['cwd']);
+      // Close the previous open turn AT this boundary (even when the boundary has no timestamp —
+      // the previous turn must stop absorbing usage), then open the new one.
+      closeOpenTurn(ms);
+      open = { model: nonEmptyString(payload['model']), cwd: nonEmptyString(payload['cwd']) ?? cwd, startedMs: ms, baseline: lastTotals, totals: null };
+    }
+
+    // Legacy shape (Step 0's documented one, not observed live on this machine 2026-09-16):
+    // `type: "token_count"`, `payload.info.total_token_usage`.
+    if (type === 'token_count') {
+      const info = isRecord(payload['info']) ? payload['info'] : null;
+      const usage = info !== null && isRecord(info['total_token_usage']) ? info['total_token_usage'] : null;
+      if (usage !== null) {
+        const t = totalsFrom(usage);
+        if (open !== null) open.totals = deltaTotals(t, open.baseline);
+        lastTotals = t;
+      }
+    }
+    // Current shape (measured live, cli_version 0.154.0): `type: "token_usage_record"`,
+    // `payload.usage`.
+    if (type === 'token_usage_record') {
+      const usage = isRecord(payload['usage']) ? payload['usage'] : null;
+      if (usage !== null) {
+        const t = totalsFrom(usage);
+        if (open !== null) open.totals = deltaTotals(t, open.baseline);
+        lastTotals = t;
+      }
+    }
+  }
+  if (open !== null && lastMs !== null) closeOpenTurn(lastMs);
+
+  if (!sawAnyRecord) return { error: 'no parseable JSON lines in rollout text' };
+  if (id === null) {
+    // Last resort: the uuid embedded in `rollout-<ts>-<uuid>.jsonl` — never invented, only read back.
+    // A plain "greedy dash" regex would stop at the uuid's OWN internal dashes (its 8-4-4-4-12 hex
+    // groups), so this matches the canonical uuid shape explicitly rather than "everything after the
+    // last dash".
+    const m = typeof fileName === 'string'
+      ? /([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})\.jsonl$/.exec(fileName)
+      : null;
+    id = m !== null ? (m[1] ?? null) : null;
+  }
+  if (id === null) return { error: 'no session_meta record and no id in fileName — cannot identify this rollout' };
+  if (lastTotals === null) {
+    return { error: 'no token_count or token_usage_record entry — nothing to attribute' };
+  }
+
+  return {
+    id,
+    cwd,
+    model: turnContextModel ?? sessionMetaModel,
+    startedAt: isoOrNull(firstMs),
+    endedAt: isoOrNull(lastMs),
+    totals: lastTotals,
+    granularity: closedTurns.length > 0 ? 'turn' : 'session',
+    unmatchableTurns,
+    turns: closedTurns,
+  };
+}
+
+export type CodexRolloutMatch =
+  | { readonly status: 'none' }
+  | { readonly status: 'one'; readonly rollout: CodexRollout }
+  | { readonly status: 'ambiguous'; readonly candidates: readonly CodexRollout[] };
+
+export interface CodexRolloutMatchWindow {
+  /** ISO instant — the window's lower bound. */
+  readonly from: string;
+  /** ISO instant — the window's upper bound. */
+  readonly to: string;
+  /** Exact match against {@link CodexRollout.cwd}, when given. */
+  readonly cwd?: string;
+  /** Exact match against {@link CodexRollout.model}, when given. */
+  readonly model?: string;
+}
+
+/**
+ * measurement-integrity fix-round-1/F5 (Codex r1 HIGH #5): every candidate window `matchCodexRollouts`
+ * may attribute spend to, at the SHARPEST granularity `parseCodexRollout` could recover from the
+ * file. For a `granularity: 'turn'` rollout this is one candidate PER TURN THAT ACTUALLY CARRIES
+ * USAGE (a turn nothing was ever attributed to yields no candidate — there is nothing honest to
+ * report for it); for `granularity: 'session'` it is exactly one candidate, the whole file, exactly
+ * as this reader behaved before this fix.
+ *
+ * This is the fix for the CRITICAL scenario the Codex review named: the OLD matcher tested the
+ * whole session's `[startedAt, endedAt]` against the query window, so ANY brief overlap with that wide
+ * interval could attribute an entire multi-turn session's cumulative spend (and, potentially, another
+ * turn's DIFFERENT model) to one stage. Scoping candidates to turns means two turns of the SAME
+ * session that only one of them overlaps the window can no longer collide — and two turns that BOTH
+ * overlap it correctly produce two candidates, which the caller below turns into `ambiguous` rather
+ * than an arbitrary pick (this is also where "the model of every usage-bearing turn matching a window
+ * must agree" ends up enforced: two turns with different models can only both match by being two
+ * SEPARATE candidates, which is ambiguous by construction — there is no path where a mismatch is
+ * silently resolved to one of them).
+ */
+function candidateViewsOf(r: CodexRollout): readonly CodexRollout[] {
+  if (r.granularity === 'session') return [r];
+  const out: CodexRollout[] = [];
+  for (const turn of r.turns) {
+    if (turn.totals === null) continue; // nothing was ever attributed to this turn — not a candidate
+    out.push({
+      id: r.id,
+      unmatchableTurns: r.unmatchableTurns,
+      cwd: turn.cwd,
+      model: turn.model,
+      startedAt: turn.startedAt,
+      endedAt: turn.endedAt,
+      totals: turn.totals,
+      granularity: 'turn',
+      turns: [turn],
+    });
+  }
+  return out;
+}
+
+/**
+ * Which candidate VIEWS (session-level, or — per {@link candidateViewsOf} — turn-level whenever the
+ * schema recovered turn boundaries) have an interval that OVERLAPS the given `[from, to]` window
+ * (never nearest-in-time — ADR-001 D3 rejects "closest by clock" because two reviews back to back
+ * would attribute one's spend to the other). A candidate with no parseable timestamps never matches —
+ * an unattributable interval is not a wildcard.
+ *
+ * `0` matches → `{status:'none'}`. `1` → `{status:'one', rollout}`. `>1` → `{status:'ambiguous',
+ * candidates}` — NEVER an arbitrary pick of "the first" (NFR-3). `>1` also covers the case where two
+ * DIFFERENT turns (of the same or different rollouts) overlap the window with different models — that
+ * disagreement can never resolve to a lone `'one'`, it always surfaces as `'ambiguous'`.
+ */
+export function matchCodexRollouts(
+  rollouts: readonly CodexRollout[],
+  window: CodexRolloutMatchWindow,
+): CodexRolloutMatch {
+  const fromMs = Date.parse(window.from);
+  const toMs = Date.parse(window.to);
+  if (!Number.isFinite(fromMs) || !Number.isFinite(toMs) || fromMs > toMs) return { status: 'none' };
+
+  const candidates: CodexRollout[] = [];
+  for (const r of rollouts) {
+    for (const view of candidateViewsOf(r)) {
+      if (view.startedAt === null || view.endedAt === null) continue;
+      const startMs = Date.parse(view.startedAt);
+      const endMs = Date.parse(view.endedAt);
+      if (!Number.isFinite(startMs) || !Number.isFinite(endMs)) continue;
+      // Lead delta after Codex r2 (#5): the turn must START inside the window — a turn that merely
+      // brushes the window's edge (any-overlap) is exactly how a neighbouring dispatch's turn leaks in.
+      if (startMs < fromMs || startMs > toMs) continue;
+      if (window.cwd !== undefined && view.cwd !== window.cwd) continue;
+      if (window.model !== undefined && view.model !== window.model) continue;
+      candidates.push(view);
+    }
+  }
+
+  if (candidates.length === 0) return { status: 'none' };
+  if (candidates.length === 1) return { status: 'one', rollout: candidates[0]! };
+  return { status: 'ambiguous', candidates };
+}