cc-viewer 1.6.348 → 1.7.1

package/server/lib/v2/meta-rows.js

@@ -0,0 +1,360 @@
+/**
+ * Wire v3 (V3.S2) — request-list metadata rows.
+ *
+ * A row is a journal fold (req + done by seq) plus two body-derived fields
+ * (typeTag, cacheLoss) computed in a bounded streaming Pass B over exactly the
+ * windowed members: bodies are materialized one at a time, classified, and
+ * dropped — the wire carries rows only (~1.3KB each vs full entries).
+ *
+ * Two DELIBERATE classification divergences from the legacy full-entry list
+ * (both more correct; pinned in test/v2-meta-rows.test.js, declared in
+ * history.md):
+ *  - membership is the journal fold — a SUPERSET of the synthesizer's output
+ *    (conv-gapped crash-orphans get a row; their detail fetch answers 404 and
+ *    typeTag stays journal-derived);
+ *  - mainAgent is `kind==='main' && !meta.leader` — the isMain semantics the
+ *    mainAgentRing already pinned, dropping "main-looking" sub/misc bodies.
+ */
+import { readFileSync, readdirSync } from 'node:fs';
+import { join, basename } from 'node:path';
+import { readJsonlTolerant } from './replay.js';
+import { iterateV2Items, findTeammateSessionDirs } from './adapter.js';
+import { SingleFlight } from './singleflight.js';
+import { reportSwallowed } from '../error-report.js';
+import { classifyRequest } from '../../../src/utils/requestType.js';
+
+// KEEP IN SYNC: server/lib/v2/adapter.js itemKey — (sessionId, seq) identity.
+const itemKey = (sessionId, seq) => `${sessionId}\x00${seq}`;
+
+const CACHE_TTL_MS = 5 * 60 * 1000;
+
+/** KEEP IN SYNC: src/utils/helpers.js stripPrivateKeys. */
+function stripPrivateKeys(obj) {
+  if (Array.isArray(obj)) return obj.map(stripPrivateKeys);
+  if (obj && typeof obj === 'object') {
+    const result = {};
+    for (const key of Object.keys(obj)) {
+      if (key.startsWith('_')) continue;
+      result[key] = stripPrivateKeys(obj[key]);
+    }
+    return result;
+  }
+  return obj;
+}
+
+/**
+ * KEEP IN SYNC: src/utils/helpers.js _computeCacheLoss (that module cannot be
+ * imported server-side — SVG/i18n dependency chain). One deliberate fix: the
+ * client computes the ttl gap as `stringTs - stringTs` (NaN, so its ttl branch
+ * never fires); here the timestamps are parsed — pinned in the unit test.
+ */
+export function computeCacheLoss(prevEntry, currEntry) {
+  const gap = Date.parse(currEntry.timestamp) - Date.parse(prevEntry.timestamp);
+  if (gap > CACHE_TTL_MS) return { reason: 'ttl', reasons: ['ttl'] };
+  const prev = stripPrivateKeys(prevEntry.body);
+  const curr = stripPrivateKeys(currEntry.body);
+  if (!prev || !curr) return { reason: 'key_change', reasons: ['key_change'] };
+  const reasons = [];
+  if (prev.model !== curr.model) reasons.push('model_change');
+  if (JSON.stringify(prev.system) !== JSON.stringify(curr.system)) reasons.push('system_change');
+  if (JSON.stringify(prev.tools) !== JSON.stringify(curr.tools)) reasons.push('tools_change');
+  const prevMsgs = prev.messages || [];
+  const currMsgs = curr.messages || [];
+  if (currMsgs.length < prevMsgs.length) {
+    reasons.push('msg_truncated');
+  } else {
+    const prefixLen = Math.min(prevMsgs.length, currMsgs.length);
+    let prefixMatch = true;
+    for (let j = 0; j < prefixLen; j++) {
+      if (JSON.stringify(prevMsgs[j]) !== JSON.stringify(currMsgs[j])) { prefixMatch = false; break; }
+    }
+    if (!prefixMatch) reasons.push('msg_modified');
+  }
+  if (reasons.length === 0) reasons.push('key_change');
+  return { reason: reasons[0], reasons };
+}
+
+function readMeta(dir) {
+  try { return JSON.parse(readFileSync(join(dir, 'meta.json'), 'utf-8')); } catch { return null; }
+}
+
+/** Fold one session dir's journal into row skeletons (no bodies touched). */
+function foldDir(dir) {
+  const meta = readMeta(dir);
+  const isTeammateDir = !!(meta && meta.leader);
+  const sessionId = (meta && meta.sessionId) || basename(dir);
+  const reqs = new Map();
+  const dones = new Map();
+  for (const line of readJsonlTolerant(join(dir, 'journal.jsonl'))) {
+    if (line.ph === 'req' && !reqs.has(line.seq)) reqs.set(line.seq, line);
+    else if (line.ph === 'done' && !dones.has(line.seq)) dones.set(line.seq, line);
+  }
+  const rows = [];
+  for (const [seq, r] of reqs) {
+    const d = dones.get(seq);
+    const usage = d && d.usage ? {
+      input_tokens: d.usage.in || 0,
+      output_tokens: d.usage.out || 0,
+      cache_read_input_tokens: d.usage.cr || 0,
+      cache_creation_input_tokens: d.usage.cw || 0,
+    } : null;
+    rows.push({
+      seq,
+      sessionId,
+      timestamp: r.ts || '',
+      url: r.url || '',
+      method: r.method || 'POST',
+      // V3.S5 assembler inputs: which conv channel this request's messages
+      // live in, and whether its event was a snapshot (checkpoint marker).
+      conv: r.conv,
+      evt: r.evt,
+      kind: r.kind || 'misc',
+      mainAgent: r.kind === 'main' && !isTeammateDir,
+      // v1 entry contract (adapter.js:427): teammate = agentName string | true
+      teammate: isTeammateDir ? ((meta.leader && meta.leader.agentName) || true) : undefined,
+      model: r.model,
+      proxyUrl: r.proxy && r.proxy.url ? r.proxy.url : undefined,
+      status: d && typeof d.http === 'number' ? d.http : undefined,
+      duration: d && typeof d.dur === 'number' ? d.dur : undefined,
+      usage,
+      inProgress: !d,
+      typeTag: null,   // Pass B
+      cacheLoss: null, // Pass B
+    });
+  }
+  return rows;
+}
+
+/**
+ * Read the request-list metadata rows for a session (leader + folded
+ * teammates), windowed like the entry list: dedup timestamp|url last-wins →
+ * `before` filter → tail-`limit`. Pass B streams the window members' bodies
+ * once to attach typeTag/cacheLoss.
+ *
+ * @param {string} sessionDir
+ * @param {{limit?: number, before?: string|null, since?: string|null, passB?: boolean}} [opts] -
+ *   passB:false skips body classification (live increments send rows first
+ *   and re-send corrections once Pass B / the next request lands);
+ *   `since` (review P1-2) scopes an incremental reconnect to the delta window
+ *   — without it every mobile reconnect re-transmits the full session
+ * @returns {Promise<{rows: object[], totalCount: number, hasMore: boolean, oldestTimestamp: string}>}
+ */
+export async function readV2RequestsMeta(sessionDir, opts = {}) {
+  const limit = opts.limit || 0;
+  const before = opts.before || null;
+  const since = opts.since || null;
+  const meta = readMeta(sessionDir);
+  const leaderUuid = (meta && meta.sessionId) || basename(sessionDir);
+  const dirs = [sessionDir];
+  try { dirs.push(...findTeammateSessionDirs(sessionDir, leaderUuid).map((t) => t.dir)); } catch { /* leaderless */ } // items are {dir, leader}
+
+  // k-way ordering parity: same (ts, sessionId, seq) comparator as iterateV2Items
+  const all = dirs.flatMap(foldDir);
+  all.sort((a, b) => (a.timestamp < b.timestamp ? -1 : a.timestamp > b.timestamp ? 1 : a.sessionId < b.sessionId ? -1 : a.sessionId > b.sessionId ? 1 : a.seq - b.seq));
+
+  // dedup timestamp|url last-wins (nokey rows key on seq — stable, unlike array index)
+  const dedup = new Map();
+  for (const row of all) {
+    const key = row.timestamp && row.url ? `${row.timestamp}|${row.url}` : `__nokey_${row.sessionId}_${row.seq}`;
+    dedup.set(key, row);
+  }
+  let rows = [...dedup.values()];
+  if (before) rows = rows.filter((r) => r.timestamp && r.timestamp < before);
+  const totalCount = rows.length;
+  let hasMore = false;
+  if (limit > 0 && rows.length > limit) {
+    hasMore = true;
+    rows = rows.slice(rows.length - limit);
+  }
+  const oldestTimestamp = rows.length > 0 ? rows[0].timestamp : '';
+  // Emission-time since filter (mirrors selectV2Window: applied after the
+  // window selection; nokey rows always resend — the legacy contract).
+  if (since) rows = rows.filter((r) => !r.timestamp || r.timestamp >= since);
+
+  if (opts.passB !== false && rows.length > 0) {
+    await attachBodyFields(sessionDir, rows);
+  }
+  return { rows, totalCount, hasMore, oldestTimestamp };
+}
+
+// In-flight coalescing for the v3 cold reads (review P2-b): a reconnect storm
+// is N tabs hitting the same sessionDir at once — without this each ran its
+// own full journal fold + Pass B + conv-file reads. cached:false — /events is
+// a live-attach caller (S10b F5b: a stale TTL window would widen the
+// cold-load→attach broadcast-loss gap), so callers only JOIN in-flight runs.
+const _coldBundleFlight = new SingleFlight({ ttlMs: 500 });
+
+/**
+ * The complete v3 cold read for one /events connection: windowed rows +
+ * native conv/responses payloads, single-flighted per (dir, window).
+ */
+export function readV2ColdBundle(sessionDir, { limit = 0, since = null } = {}) {
+  const key = `bundle:${sessionDir}|${limit}|${since || ''}`;
+  return _coldBundleFlight.run(key, async () => {
+    const meta = await readV2RequestsMeta(sessionDir, { limit, since });
+    const native = await readV2NativeCold(sessionDir, meta.rows);
+    return { meta, native };
+  }, { cached: false });
+}
+
+/**
+ * Wire v3 (V3.S4) cold native lines for the flagged client's assembler:
+ * per conv channel, raw lines from the LAST snapshot at-or-before the
+ * window's oldest seq (per session) through the end; responses lines for
+ * exactly the window member seqs. Lines are forwarded verbatim (string
+ * concat, no parse/stringify round trip beyond seq/t sniffing).
+ *
+ * ASYNC with event-loop yields (review P1-4): a large session's conv files
+ * total tens of MB — reading and snapshot-scanning them in one synchronous
+ * stretch blocks every connected client for the duration of the cold load.
+ *
+ * @param {string} sessionDir - leader dir (teammate dirs folded like the rows)
+ * @param {object[]} rows - the window rows (readV2RequestsMeta output)
+ * @returns {Promise<{convPayloads: string[], respPayloads: string[]}>}
+ *   pre-serialized JSON payloads for `v3_conv` / `v3_resp` SSE frames
+ */
+export async function readV2NativeCold(sessionDir, rows) {
+  const yieldLoop = () => new Promise((resolve) => setImmediate(resolve));
+  const minSeqBySession = new Map();
+  const memberSeqsBySession = new Map();
+  for (const r of rows) {
+    const cur = minSeqBySession.get(r.sessionId);
+    if (cur === undefined || r.seq < cur) minSeqBySession.set(r.sessionId, r.seq);
+    let set = memberSeqsBySession.get(r.sessionId);
+    if (!set) { set = new Set(); memberSeqsBySession.set(r.sessionId, set); }
+    set.add(r.seq);
+  }
+  const meta = readMeta(sessionDir);
+  const leaderUuid = (meta && meta.sessionId) || basename(sessionDir);
+  const dirs = [sessionDir];
+  try { dirs.push(...findTeammateSessionDirs(sessionDir, leaderUuid).map((t) => t.dir)); } catch { /* leaderless */ } // items are {dir, leader}
+
+  const convPayloads = [];
+  const respPayloads = [];
+  for (const dir of dirs) {
+    const dirMeta = readMeta(dir);
+    const sessionId = (dirMeta && dirMeta.sessionId) || basename(dir);
+    const minSeq = minSeqBySession.get(sessionId);
+    const memberSeqs = memberSeqsBySession.get(sessionId);
+    if (minSeq === undefined) continue; // no window rows from this session
+    // conv channels: raw lines from the channel's last snapshot ≤ minSeq
+    const convRoot = join(dir, 'conversations');
+    let keys = [];
+    try { keys = readdirSync(convRoot, { withFileTypes: true }).filter((e) => e.isDirectory()).map((e) => e.name); } catch { /* no conv dir */ }
+    for (const key of keys) {
+      let files = [];
+      try { files = readdirSync(join(convRoot, key)).filter((f) => /^e\d+\.jsonl$/.test(f)).sort((a, b) => Number(a.match(/\d+/)[0]) - Number(b.match(/\d+/)[0])); } catch { continue; }
+      const raws = [];
+      for (const f of files) {
+        let text = '';
+        try { text = readFileSync(join(convRoot, key, f), 'utf-8'); } catch { continue; }
+        for (const line of text.split('\n')) {
+          const trimmed = line.trim();
+          if (trimmed) raws.push(trimmed);
+        }
+        await yieldLoop(); // one yield per conv file read
+      }
+      // last snapshot at-or-before the window start for this session
+      let start = 0;
+      for (let i = 0; i < raws.length; i++) {
+        try {
+          const ev = JSON.parse(raws[i]);
+          if (ev.t === 'snapshot' && ev.seq <= minSeq) start = i;
+          if (ev.seq > minSeq) break;
+        } catch { /* tolerate torn line */ }
+        if (i % 2000 === 1999) await yieldLoop();
+      }
+      const windowRaws = raws.slice(start);
+      // Cap each frame at ~512KB of lines: a multi-MB single SSE event forces
+      // one giant synchronous JSON.parse on the client's main thread (no
+      // paint, no rAF — the loading UI freezes). Small frames are macrotask
+      // boundaries: the browser paints and the byte meter ticks between them.
+      pushChunked(convPayloads, windowRaws, (linesJson) => `{"sessionId":${JSON.stringify(sessionId)},"channel":${JSON.stringify(key)},"lines":[${linesJson}]}`);
+    }
+    // responses: exactly the window member seqs
+    let respText = '';
+    try { respText = readFileSync(join(dir, 'responses.jsonl'), 'utf-8'); } catch { /* none yet */ }
+    await yieldLoop();
+    const respRaws = [];
+    for (const line of respText.split('\n')) {
+      const trimmed = line.trim();
+      if (!trimmed) continue;
+      const m = /"seq":\s*(\d+)/.exec(trimmed);
+      if (m && memberSeqs && memberSeqs.has(Number(m[1]))) respRaws.push(trimmed);
+    }
+    pushChunked(respPayloads, respRaws, (linesJson) => `{"sessionId":${JSON.stringify(sessionId)},"lines":[${linesJson}]}`);
+  }
+  return { convPayloads, respPayloads };
+}
+
+const NATIVE_FRAME_BUDGET = 512 * 1024;
+
+/** Split raw lines into ≤~512KB payloads (see comment at the conv call site). */
+function pushChunked(out, raws, wrap) {
+  let buf = [];
+  let bytes = 0;
+  const flush = () => {
+    if (buf.length > 0) out.push(wrap(buf.join(',')));
+    buf = [];
+    bytes = 0;
+  };
+  for (const raw of raws) {
+    buf.push(raw);
+    bytes += raw.length + 1;
+    if (bytes >= NATIVE_FRAME_BUDGET) flush();
+  }
+  flush();
+}
+
+/**
+ * Bounded streaming Pass B: materialize exactly the rows' bodies (one at a
+ * time), classify typeTag with one-entry lookahead (classifyRequest's
+ * Preflight/Plan detection reads nextReq), compute cacheLoss against the
+ * retained previous mainAgent body, then drop the body.
+ */
+async function attachBodyFields(sessionDir, rows) {
+  const rowByKey = new Map(rows.map((r) => [itemKey(r.sessionId, r.seq), r]));
+  const materialize = (sessionId, seq) => rowByKey.has(itemKey(sessionId, seq));
+  let pending = null;      // { row, entry } awaiting its nextReq for classify
+  let prevMainFull = null; // previous mainAgent full-body entry (cacheLoss)
+  let n = 0;
+  const finish = (slot, nextEntry) => {
+    const { row, entry } = slot;
+    try {
+      const tag = classifyRequest(entry, nextEntry);
+      row.typeTag = tag ? { type: tag.type, subType: tag.subType ?? null } : null;
+    } catch (err) {
+      // Diagnostic-worthy (a throw silently mis-tags the row; the live path
+      // reports the same failure) — CLAUDE.md swallow rule.
+      reportSwallowed('v2-meta.row-classify', err);
+      row.typeTag = null; // journal-derived kind still renders
+    }
+    // authoritative synthesis-level markers (parity with the legacy list)
+    row.mainAgent = entry.mainAgent === true;
+    if (entry.teammate) row.teammate = entry.teammate;
+    if (entry.body && entry.body.model) row.model = entry.body.model;
+    if (row.mainAgent) {
+      const usage = entry.response?.body?.usage;
+      const cacheCreate = usage?.cache_creation_input_tokens || 0;
+      const cacheRead = usage?.cache_read_input_tokens || 0;
+      if (prevMainFull && cacheCreate > 0 && cacheCreate > cacheRead) {
+        try { row.cacheLoss = computeCacheLoss(prevMainFull, entry); } catch (err) { reportSwallowed('v2-meta.row-cacheloss', err); }
+      }
+      prevMainFull = entry;
+    }
+  };
+  for (const item of iterateV2Items(sessionDir, { materialize })) {
+    const row = rowByKey.get(itemKey(item.sessionId, item.seq));
+    if (!row) continue;
+    // main deltas carry only their appended slice — classification and
+    // cacheLoss need the full replayed state (stateRef aliases it transiently)
+    let entry = item.entry;
+    if (row.mainAgent && item.stateRef && entry.body) {
+      entry = { ...entry, body: { ...entry.body, messages: item.stateRef } };
+    }
+    if (pending) finish(pending, entry);
+    pending = { row, entry };
+    if (++n % 20 === 0) await new Promise((resolve) => setImmediate(resolve));
+  }
+  if (pending) finish(pending, null);
+}

package/server/lib/v2/migrate-prompt.js

@@ -0,0 +1,54 @@
+// 1.7.0 migration prompt (plan P2): detect legacy v1 logs that have not been
+// converted to the v2 session store yet, so the UI can offer one-click
+// migration at startup / workspace switch. Detection is pure filesystem
+// arithmetic on top of the converter's own bookkeeping — a v1 file counts as
+// pending unless the convert state marks it done AT ITS CURRENT SIZE (the
+// converter's trust rule, convert.js), because the converter never deletes
+// v1 sources ("files exist" alone is not "migration needed").
+import { statSync } from 'node:fs';
+import { join } from 'node:path';
+import { listV1Files, listConvertibleProjects, readConvertState } from './convert.js';
+
+/** Pending v1 files + bytes of ONE project dir. */
+function pendingOf(projectDir) {
+  const state = readConvertState(projectDir);
+  const doneAtSize = new Map(
+    (state && Array.isArray(state.files) ? state.files : [])
+      .filter((f) => f && f.done)
+      .map((f) => [f.name, f.size])
+  );
+  let files = 0;
+  let totalBytes = 0;
+  for (const name of listV1Files(projectDir)) {
+    let size = 0;
+    try { size = statSync(join(projectDir, name)).size; } catch { continue; }
+    if (size === 0) continue; // empty shells are not worth prompting over
+    if (doneAtSize.get(name) === size) continue; // converted & unchanged
+    files++;
+    totalBytes += size;
+  }
+  return { files, totalBytes };
+}
+
+/**
+ * Migration status of one project (plus how many OTHER projects also have
+ * pending v1 logs — the prompt mentions `ccv convert --all` for those).
+ * @param {string} logDir - LOG_DIR root
+ * @param {string} project - project directory name ('' → not pending)
+ * @returns {{pending: boolean, files: number, totalBytes: number, otherProjects: number}}
+ */
+export function migrationStatus(logDir, project) {
+  const empty = { pending: false, files: 0, totalBytes: 0, otherProjects: 0 };
+  if (!logDir || !project) return empty;
+  try {
+    const { files, totalBytes } = pendingOf(join(logDir, project));
+    let otherProjects = 0;
+    for (const p of listConvertibleProjects(logDir)) {
+      if (p === project) continue;
+      if (pendingOf(join(logDir, p)).files > 0) otherProjects++;
+    }
+    return { pending: files > 0, files, totalBytes, otherProjects };
+  } catch {
+    return empty;
+  }
+}

package/server/lib/v2/replay.js

@@ -0,0 +1,191 @@
+// Wire Format v2 — session-dir readers + MECHANICAL wire replay.
+//
+// Replay here is deliberately interpretation-free: conversation events are
+// applied exactly as the write side derived them from wire state
+// (snapshot → replace state; append → concat; ctl replace-tail → swap last;
+// ctl compact → no-op, the surrounding snapshot already carries the state).
+// This reproduces the EXACT wire messages of every request — byte-equal to
+// what v1's delta reconstruction yields for the same request — without any
+// reverse-anchor/session semantics (those belong to the S5 materializer,
+// which presents conversations; verify only needs wire truth).
+
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { createHash } from 'node:crypto';
+import { messageFingerprint, normalizeMsgForEquality } from '../session-boundary.js';
+import { isSupportedWireFormat } from './layout.js';
+
+/** Parse a JSONL file tolerating a truncated tail line (spec §14). */
+export function readJsonlTolerant(path) {
+  if (!existsSync(path)) return [];
+  const out = [];
+  for (const line of readFileSync(path, 'utf-8').split('\n')) {
+    const t = line.trim();
+    if (!t) continue;
+    try { out.push(JSON.parse(t)); } catch { /* truncated tail — drop */ }
+  }
+  return out;
+}
+
+/** List session ids under LOG_DIR/<project>/sessions/ (or a staging sibling
+ *  when the offline converter passes `sessionsDirName`). */
+export function listSessionIds(projectDir, sessionsDirName = 'sessions') {
+  const root = join(projectDir, sessionsDirName);
+  if (!existsSync(root)) return [];
+  return readdirSync(root, { withFileTypes: true }).filter(e => e.isDirectory()).map(e => e.name);
+}
+
+/**
+ * Read one session dir into a folded structure:
+ * { sessionId, meta, wireFormat, reqs: Map<seq, reqLine>,
+ *   dones: Map<seq, doneLine>, convEvents: Map<convKey, event[] (sorted by seq)> }
+ *
+ * Reader version gate (spec §14): the version is taken from meta.json and the
+ * journal sentinel (`ph:'meta'` first line). A session stamped with a version
+ * this build doesn't understand returns `unsupported: true` with EMPTY folds —
+ * callers must refuse it loudly instead of interpreting bytes they can't parse.
+ * A missing version (torn creation) is treated as the current one.
+ */
+export function readSession(projectDir, sessionId, sessionsDirName = 'sessions') {
+  const dir = join(projectDir, sessionsDirName, sessionId);
+  let meta = null;
+  try { meta = JSON.parse(readFileSync(join(dir, 'meta.json'), 'utf-8')); } catch { }
+  let wireFormat = meta && typeof meta.wireFormat === 'number' ? meta.wireFormat : null;
+  const unsupportedOf = (v) => ({
+    sessionId, dir, meta, wireFormat: v, unsupported: true,
+    reqs: new Map(), dones: new Map(), convEvents: new Map(),
+  });
+  if (!isSupportedWireFormat(wireFormat)) return unsupportedOf(wireFormat);
+  const reqs = new Map();
+  const dones = new Map();
+  for (const line of readJsonlTolerant(join(dir, 'journal.jsonl'))) {
+    if (line.ph === 'req') reqs.set(line.seq, line);
+    else if (line.ph === 'done' && !dones.has(line.seq)) dones.set(line.seq, line);
+    else if (line.ph === 'meta' && typeof line.wireFormat === 'number') {
+      // Journal sentinel wins over meta.json (per-file self-description).
+      wireFormat = line.wireFormat;
+      if (!isSupportedWireFormat(wireFormat)) return unsupportedOf(wireFormat);
+    }
+  }
+  const convEvents = new Map();
+  const convRoot = join(dir, 'conversations');
+  if (existsSync(convRoot)) {
+    for (const entry of readdirSync(convRoot, { withFileTypes: true })) {
+      if (!entry.isDirectory()) continue;
+      const events = [];
+      for (const f of readdirSync(join(convRoot, entry.name))) {
+        if (!/^e\d+\.jsonl$/.test(f)) continue;
+        events.push(...readJsonlTolerant(join(convRoot, entry.name, f)));
+      }
+      events.sort((a, b) => a.seq - b.seq);
+      convEvents.set(entry.name, events);
+    }
+  }
+  return { sessionId, dir, meta, wireFormat, reqs, dones, convEvents };
+}
+
+/** Digest of a messages array: sha256 over the per-message fingerprint list.
+ *  Shared formula between the v1 and v2 sides of verify. Messages are
+ *  normalized first (S4 decision 2026-07-14): the client's cache_control
+ *  breakpoint migration rewrites OLD messages (string → block array with
+ *  cache_control) — v1 delta cannot express that mutation, so without
+ *  normalization every real active day fails the soak gate on false
+ *  positives (plan S4 table, 2026-07-13 row). */
+export function messagesDigest(messages) {
+  const h = createHash('sha256');
+  for (const m of messages) h.update(messageFingerprint(normalizeMsgForEquality(m)) + '\n');
+  return h.digest('hex').slice(0, 16);
+}
+
+/** Same content-hash formula as BlobStore.put — lets verify compare v1 inline
+ *  tools/system against v2 blob refs WITHOUT reading blob files.
+ *  KEEP IN SYNC: server/lib/v2/blob-store.js `put` is the writing twin of this
+ *  formula; any change to hash/slice/serialization must land in both. */
+export function blobRefOf(value) {
+  if (value === undefined || value === null) return null;
+  return 'sha256-' + createHash('sha256').update(JSON.stringify(value)).digest('hex').slice(0, 16);
+}
+
+/**
+ * Mechanically replay one conversation's events, yielding the wire state
+ * digest after each event: Map<seq, {digest, len}>. Also returns integrity
+ * violations against the journal's msgTo counts (checked by the caller,
+ * which owns the journal).
+ */
+export function replayConversation(events) {
+  let state = [];
+  const bySeq = new Map();
+  for (const ev of events) {
+    if (ev.t === 'snapshot') {
+      state = Array.isArray(ev.msgs) ? ev.msgs : [];
+    } else if (ev.t === 'append') {
+      if (Array.isArray(ev.msgs) && ev.msgs.length > 0) state = state.concat(ev.msgs);
+    } else if (ev.t === 'ctl') {
+      if (ev.op === 'replace-tail' && ev.msg && state.length > 0) {
+        state = state.slice(0, -1).concat([ev.msg]);
+      }
+      // 'compact' is a marker for the materializer; wire state came via the
+      // snapshot event of the same request.
+    }
+    bySeq.set(ev.seq, { digest: messagesDigest(state), len: state.length });
+  }
+  return bySeq;
+}
+
+/**
+ * Build the per-request wire index of one session:
+ * Map<`${ts}|${url}`, Array<{seq, kind, conv, epoch, digest, len, toolsRef,
+ *                            sysRef, done, status, msgTo}>>
+ * — an ARRAY per key: `${ts}|${url}` is not unique in real logs (same-ms
+ * countTokens bursts), and collapsing twins loses their done lines/digests
+ * (real-data finding 2026-07-14). Also returns integrity violations
+ * (journal msgTo vs replayed length).
+ */
+export function indexSession(session) {
+  const replayed = new Map(); // convKey → Map<seq, {digest, len}>
+  for (const [convKey, events] of session.convEvents) replayed.set(convKey, replayConversation(events));
+
+  const index = new Map();
+  const integrity = [];
+  // Walk reqs in seq order; for reqs without a conv event (unchanged wire),
+  // carry the conv's latest replayed state at or before that seq.
+  const lastStateOf = new Map(); // convKey → {digest, len}
+  const seqs = [...session.reqs.keys()].sort((a, b) => a - b);
+  for (const seq of seqs) {
+    const req = session.reqs.get(seq);
+    const done = session.dones.get(seq) || null;
+    let digest = null;
+    let len = null;
+    if (req.conv) {
+      const conv = replayed.get(req.conv);
+      const hit = conv && conv.get(seq);
+      if (hit) {
+        lastStateOf.set(req.conv, hit);
+        digest = hit.digest; len = hit.len;
+      } else {
+        const carried = lastStateOf.get(req.conv);
+        if (carried) { digest = carried.digest; len = carried.len; }
+      }
+      if (typeof req.msgTo === 'number' && len != null && req.msgTo !== len) {
+        integrity.push({ sessionId: session.sessionId, seq, conv: req.conv, msgTo: req.msgTo, replayedLen: len });
+      }
+    }
+    const key = `${req.ts}|${req.url}`;
+    const rec = {
+      sessionId: session.sessionId,
+      seq,
+      kind: req.kind,
+      conv: req.conv || null,
+      epoch: req.epoch,
+      digest,
+      len,
+      toolsRef: (req.blobs && req.blobs.tools) || null,
+      sysRef: (req.blobs && req.blobs.sys) || null,
+      done: !!done,
+      status: done ? done.status : null,
+    };
+    const arr = index.get(key);
+    if (arr) arr.push(rec); else index.set(key, [rec]);
+  }
+  return { index, integrity };
+}