@geraldmaron/construct 1.1.1 → 1.2.1

package/lib/chat/openrouter-fallback.mjs

@@ -0,0 +1,151 @@
+/**
+ * lib/chat/openrouter-fallback.mjs — OpenRouter failure parsing and turn-time fallback.
+ *
+ * When a free slug returns 404/429 at call time, walks the live poll for the next
+ * candidate. When an Ollama tag is pinned but not pulled, falls through to the
+ * next configured provider for the same turn (mirroring session launch resolution).
+ */
+
+import { classifyProviderFailure, resolveValidatedChatModel } from '../model-router.mjs';
+
+const MAX_FALLBACK_ATTEMPTS = 3;
+
+export function parseOpenRouterError(error) {
+  const text = typeof error === 'string' ? error : String(error?.message || error || '');
+  let raw = text;
+  try {
+    const jsonMatch = text.match(/\{[\s\S]*\}/);
+    if (jsonMatch) {
+      const body = JSON.parse(jsonMatch[0]);
+      raw = body?.error?.metadata?.raw || body?.error?.message || text;
+    }
+  } catch { /* not JSON */ }
+
+  let summary = raw;
+  const ollamaMissing = raw.match(/model ['"]([^'"]+)['"] not found/i);
+  if (ollamaMissing) {
+    const native = ollamaMissing[1];
+    summary = `Ollama model '${native}' is not installed locally. Pull it with: ollama pull ${native} (or: construct ollama pull ${native})`;
+  } else if (/rate[- ]?limit|429|temporarily rate-limited/i.test(raw)) {
+    summary = raw.replace(/^Provider returned error\.?\s*/i, '').trim() || 'rate-limited upstream';
+  } else if (/unavailable for free|paid version is available/i.test(raw)) {
+    summary = 'free tier retired — use a different free model or paid slug';
+  } else if (/Failed after \d+ attempts/i.test(text)) {
+    summary = raw || 'provider error after retries';
+  } else if (/OLLAMA_MODEL_NOT_PULLED|not installed locally/i.test(raw)) {
+    summary = raw;
+  }
+
+  return { raw, summary, text };
+}
+
+export function ensureFailedModels(session) {
+  if (!session.failedModels) session.failedModels = new Set();
+  return session.failedModels;
+}
+
+export function recordFailedModel(session, modelId) {
+  if (!modelId) return;
+  ensureFailedModels(session).add(modelId);
+}
+
+export function getExcludeList(session) {
+  return [...ensureFailedModels(session)];
+}
+
+export function shouldAttemptFreeFallback(session, modelId) {
+  if (session?.modelMode === 'free-router') return true;
+  return typeof modelId === 'string' && /:free$/i.test(modelId);
+}
+
+export function isOllamaNotPulledError(error) {
+  const text = typeof error === 'string' ? error : String(error?.message || error || '');
+  return error?.code === 'OLLAMA_MODEL_NOT_PULLED' || /not installed locally/i.test(text);
+}
+
+export async function handleOllamaNotPulledFailure({ session, error, env = process.env, currentModel }) {
+  if (!isOllamaNotPulledError(error)) return null;
+  if (typeof currentModel !== 'string' || !currentModel.startsWith('ollama/')) return null;
+
+  recordFailedModel(session, currentModel);
+  const excludeFamilies = typeof currentModel === 'string' && currentModel.startsWith('ollama/')
+    ? ['ollama']
+    : [];
+  const next = resolveValidatedChatModel({ env, requested: null, excludeFamilies });
+  if (!next?.id || next.id === currentModel) return null;
+
+  const parsed = parseOpenRouterError(error);
+  return {
+    modelId: next.id,
+    notice: `${parsed.summary} Switched to ${next.id} for this turn.`,
+  };
+}
+
+export async function handleModelFailure(opts) {
+  const openRouter = await handleOpenRouterFailure(opts);
+  if (openRouter) return openRouter;
+  return handleOllamaNotPulledFailure(opts);
+}
+
+export async function handleOpenRouterFailure({ session, error, env = process.env, currentModel }) {
+  const parsed = parseOpenRouterError(error);
+  const classified = classifyProviderFailure({ error: { message: parsed.text || parsed.raw } });
+  if (!classified?.retryable) return null;
+  if (!shouldAttemptFreeFallback(session, currentModel)) return null;
+
+  recordFailedModel(session, currentModel);
+  const exclude = getExcludeList(session);
+  const { resolveFreeOpenRouterModel } = await import('../../apps/chat/engine/models.mjs');
+  const next = await resolveFreeOpenRouterModel({ env, tier: 'standard', exclude });
+  if (!next || next === currentModel) return null;
+
+  const short = (id) => id.replace(/^openrouter\//, '');
+  return {
+    modelId: next,
+    notice: `${short(currentModel)} failed (${parsed.summary}). Switched to ${short(next)}. Retry or /model to pick manually.`,
+  };
+}
+
+export async function runTurnWithFallback({
+  driver,
+  text,
+  session,
+  layers,
+  env,
+  promptOptions = {},
+  runTurnInto,
+  onUpdate = () => {},
+}) {
+  let model = session.model;
+  let lastState = null;
+  let lastNotice = null;
+
+  for (let attempt = 0; attempt < MAX_FALLBACK_ATTEMPTS; attempt++) {
+    lastState = await runTurnInto(
+      driver,
+      text,
+      { ...promptOptions, model, turnOverlay: promptOptions.turnOverlay },
+      { session, layers, onUpdate },
+    );
+
+    if (!lastState.error) {
+      return { state: lastState, model, notice: lastNotice };
+    }
+
+    const fallback = await handleModelFailure({
+      session,
+      error: lastState.error,
+      env,
+      currentModel: model,
+    });
+    if (!fallback) break;
+
+    model = fallback.modelId;
+    session.model = model;
+    lastNotice = fallback.notice;
+  }
+
+  return { state: lastState, model, notice: lastNotice };
+}
+
+export { MAX_FALLBACK_ATTEMPTS };

package/lib/chat/permission-prompt.mjs

@@ -0,0 +1,33 @@
+/**
+ * lib/chat/permission-prompt.mjs — interactive permission decisions for ask mode.
+ *
+ * Maps user keystrokes and readline answers to the host-agnostic decision
+ * vocabulary (allow | allow_always | reject) shared by the permission gate
+ * (apps/chat/engine/tools/permission.mjs). Both the Ink overlay and the linear
+ * readline prompt use the same parser so behaviour stays identical.
+ */
+
+export function formatPermissionQuestion({ tool = 'tool', input = null } = {}) {
+  const detail = input && typeof input === 'object'
+    ? Object.keys(input).slice(0, 3).join(', ')
+    : '';
+  const suffix = detail ? ` (${detail})` : '';
+  return `Allow "${tool}"${suffix}?  [y] once  [a] always  [n] reject`;
+}
+
+export function parsePermissionDecision(raw) {
+  const s = String(raw ?? '').trim().toLowerCase();
+  if (['a', 'always', 'allow_always', 'all'].includes(s)) return 'allow_always';
+  if (['n', 'no', 'reject', 'r', 'deny', '0'].includes(s)) return 'reject';
+  if (['y', 'yes', 'allow', 'once', '1', ''].includes(s)) return 'allow';
+  return null;
+}
+
+export function parsePermissionKey(char) {
+  if (!char) return null;
+  const c = char.toLowerCase();
+  if (c === 'a') return 'allow_always';
+  if (c === 'n' || c === 'r') return 'reject';
+  if (c === 'y') return 'allow';
+  return null;
+}

package/lib/chat/picker-catalog.mjs

@@ -0,0 +1,45 @@
+/**
+ * lib/chat/picker-catalog.mjs — predefined list-picker item sets for construct chat.
+ */
+
+import { LAYER_KEYS, PERMISSION_MODES, SANDBOX_LEVELS, INSPECTOR_MODES } from './config.mjs';
+
+export const PERMISSION_PICKER_ITEMS = Object.freeze([
+  { id: 'allow', label: 'Allow once', detail: 'y' },
+  { id: 'allow_always', label: 'Allow always', detail: 'a' },
+  { id: 'reject', label: 'Reject', detail: 'n' },
+]);
+
+export const BOOL_PICKER_ITEMS = Object.freeze([
+  { id: 'on', label: 'on', detail: 'true' },
+  { id: 'off', label: 'off', detail: 'false' },
+]);
+
+export function settingKeyPickerItems() {
+  return [
+    { id: 'thinking', label: 'thinking', tag: 'bool' },
+    ...LAYER_KEYS.map((k) => ({ id: k, label: k, tag: 'layer' })),
+    { id: 'permission', label: 'permission mode', tag: 'enum' },
+    { id: 'sandbox', label: 'sandbox', tag: 'enum' },
+    { id: 'inspector', label: 'inspector panel', tag: 'enum' },
+    { id: 'ascii', label: 'ascii glyphs', tag: 'bool' },
+    { id: 'theme', label: 'color theme', tag: 'enum' },
+    { id: 'model', label: 'model', tag: 'model' },
+  ];
+}
+
+export function enumPickerItems(key) {
+  if (key === 'permission') return PERMISSION_MODES.map((v) => ({ id: v, label: v }));
+  if (key === 'sandbox') return SANDBOX_LEVELS.map((v) => ({ id: v, label: v }));
+  if (key === 'inspector') return INSPECTOR_MODES.map((v) => ({ id: v, label: v }));
+  if (key === 'theme') return ['auto', 'light', 'dark'].map((v) => ({ id: v, label: v }));
+  return [];
+}
+
+export function isBoolSetting(key) {
+  return key === 'thinking' || key === 'ascii' || LAYER_KEYS.includes(key);
+}
+
+export function isEnumSetting(key) {
+  return key === 'permission' || key === 'sandbox' || key === 'inspector' || key === 'theme';
+}

package/lib/chat/policy-telemetry.mjs

@@ -0,0 +1,34 @@
+/**
+ * lib/chat/policy-telemetry.mjs — bounded sink for execution-policy degraded-mode
+ * events (construct-6zga.1.2 / construct-rv2x).
+ *
+ * When the owned loop compiles a turn's execution policy from a missing, unknown,
+ * or degraded capability profile, the policy collapses to the conservative
+ * envelope. The engine records that fact here instead of printing to the chat
+ * stream so the degradation is observable (dashboard, diagnostics) without
+ * touching the renderer event union or the live transcript. The buffer is
+ * in-process and bounded; it is a diagnostic signal, not durable state.
+ */
+
+const RECENT = [];
+const MAX_EVENTS = 50;
+
+export function recordPolicyTelemetry(event = {}) {
+  const entry = {
+    kind: typeof event.kind === 'string' ? event.kind : 'execution-policy-degraded',
+    model: event.model ?? null,
+    capabilityClass: event.capabilityClass ?? 'unknown',
+    reasons: Array.isArray(event.reasons) ? [...event.reasons] : [],
+  };
+  RECENT.push(entry);
+  if (RECENT.length > MAX_EVENTS) RECENT.shift();
+  return entry;
+}
+
+export function recentPolicyTelemetry() {
+  return RECENT.map((e) => ({ ...e, reasons: [...e.reasons] }));
+}
+
+export function clearPolicyTelemetry() {
+  RECENT.length = 0;
+}

package/lib/chat/present.mjs

@@ -0,0 +1,246 @@
+/**
+ * lib/chat/present.mjs — headless formatters for construct chat surfaces.
+ *
+ * Shared by Ink TUI, linear renderer, and dashboard web cockpit. Keeps route
+ * rows, tool grouping, usage ledgers, and SSE overlay serialization identical
+ * across surfaces.
+ */
+
+import { formatTokens, formatUsageFooter } from './tui/usage.mjs';
+
+export function summarizeToolCalls(tools = []) {
+  const groups = new Map();
+  for (const t of tools) {
+    const title = t.title || t.kind || 'tool';
+    if (!groups.has(title)) {
+      groups.set(title, { title, count: 0, status: 'completed', refs: [] });
+    }
+    const g = groups.get(title);
+    g.count += 1;
+    if (t.status === 'failed') g.status = 'failed';
+    else if (t.status === 'pending' && g.status !== 'failed') g.status = 'pending';
+    else if (t.status === 'in_progress' && g.status === 'completed') g.status = 'in_progress';
+    const ref = t.input?.path || t.input?.pattern || t.input?.glob || t.input?.name;
+    if (ref) {
+      const s = String(ref);
+      if (!g.refs.includes(s)) g.refs.push(s);
+    }
+  }
+  return [...groups.values()];
+}
+
+export function summarizeSources(sources = []) {
+  if (!sources?.length) {
+    return { total: 0, byTool: {}, refs: [] };
+  }
+  const byTool = {};
+  const refs = [];
+  for (const s of sources) {
+    if (typeof s === 'string') {
+      if (!refs.includes(s)) refs.push(s);
+      continue;
+    }
+    byTool[s.tool] = (byTool[s.tool] || 0) + 1;
+    if (s.ref && !refs.includes(s.ref)) refs.push(s.ref);
+  }
+  return { total: sources.length, byTool, refs };
+}
+
+export function formatRefsInline(refs, { max = 3 } = {}) {
+  if (!refs?.length) return '';
+  if (refs.length <= max) return refs.join(', ');
+  const shown = refs.slice(0, max);
+  return `${shown.join(', ')} +${refs.length - max} more`;
+}
+
+export function formatSourceToolCounts(byTool) {
+  const entries = Object.entries(byTool || {});
+  if (!entries.length) return '';
+  return entries.map(([tool, n]) => `${tool} ${n}`).join('  ');
+}
+
+export function contextRows(overlay, { layers = null } = {}) {
+  if (!overlay) return [];
+  const rows = [];
+  if (overlay.intent) rows.push({ label: 'intent', value: overlay.intent });
+  if (overlay.workCategory) rows.push({ label: 'category', value: overlay.workCategory });
+  if (overlay.track) rows.push({ label: 'track', value: overlay.track });
+  if (overlay.specialists?.length && layers?.specialists !== false) {
+    rows.push({ label: 'route', value: overlay.specialists.join(' → ') });
+  }
+  if (overlay.externalResearch?.required) {
+    const shape = overlay.externalResearch.shape ? ` (${overlay.externalResearch.shape})` : '';
+    rows.push({ label: 'research', value: `required${shape}` });
+  }
+  return rows;
+}
+
+export function splitSourceLines(refs, { limit = 4 } = {}) {
+  if (!refs?.length) return { lines: ['none yet'], hidden: 0, total: 0 };
+  const shown = refs.slice(0, limit);
+  return {
+    lines: shown,
+    hidden: Math.max(0, refs.length - limit),
+    total: refs.length,
+  };
+}
+
+export function toolGroupLabel(group) {
+  const count = group.count > 1 ? ` ×${group.count}` : '';
+  const refs = formatRefsInline(group.refs, { max: 2 });
+  return refs ? `${group.title}${count}  ${refs}` : `${group.title}${count}`;
+}
+
+export function toolStatusGlyph(status) {
+  if (status === 'completed') return '✓';
+  if (status === 'failed') return '✗';
+  if (status === 'in_progress') return '›';
+  return '·';
+}
+
+/**
+ * @param {Record<string, unknown> | null | undefined} overlay
+ * @param {{ layers?: Record<string, boolean> | null }} [options]
+ * @returns {{
+ *   chain: string[],
+ *   intent: string | null,
+ *   track: string | null,
+ *   gates: Array<{ label: string, value: string }>,
+ *   summary: string | null,
+ *   chainLine: string | null,
+ * } | null}
+ */
+export function formatRouteStrip(overlay, { layers = null } = {}) {
+  if (!overlay) return null;
+  const showSpecialists = layers?.specialists !== false;
+  const chain = showSpecialists && Array.isArray(overlay.specialists)
+    ? [...overlay.specialists]
+    : [];
+  const intent = overlay.intent || null;
+  const track = overlay.track || null;
+  const gates = formatGateRows(overlay);
+  const summary = overlay.dispatchSummary || null;
+  const chainLine = showSpecialists
+    ? (chain.length ? chain.join(' → ') : 'direct')
+    : null;
+  return { chain, intent, track, gates, summary, chainLine };
+}
+
+/**
+ * @param {Record<string, unknown> | null | undefined} overlay
+ * @param {{ layers?: Record<string, boolean> | null }} [options]
+ */
+export function formatRouteLogLine(overlay, { layers = null } = {}) {
+  const strip = formatRouteStrip(overlay, { layers });
+  if (!strip) return '';
+  const parts = [];
+  if (strip.intent) parts.push(`intent=${strip.intent}`);
+  if (strip.track) parts.push(`track=${strip.track}`);
+  if (strip.chainLine) parts.push(strip.chainLine);
+  return parts.join(' · ');
+}
+
+export function formatRiskFlags(riskFlags = {}) {
+  return Object.entries(riskFlags)
+    .filter(([, v]) => v)
+    .map(([k]) => k);
+}
+
+export function formatContractChain(chain = []) {
+  return chain.map((edge) => `${edge.producer} → ${edge.consumer}${edge.stage ? ` (${edge.stage})` : ''}`);
+}
+
+export function formatGateRows(overlay) {
+  if (!overlay) return [];
+  const rows = [];
+  if (overlay.externalResearch?.required) {
+    const detail = overlay.externalResearch.shape || overlay.externalResearch.reason || 'yes';
+    rows.push({ label: 'research', value: `required (${detail})` });
+  }
+  if (overlay.framingChallenge?.required) {
+    rows.push({ label: 'framing', value: 'challenge required' });
+  }
+  if (overlay.docAuthoring?.docType) {
+    rows.push({ label: 'doc', value: `${overlay.docAuthoring.docType} → ${overlay.docAuthoring.owner || 'unknown'}` });
+  }
+  if (overlay.artifactReview?.requiredReviewers?.length) {
+    rows.push({
+      label: 'reviewers',
+      value: overlay.artifactReview.requiredReviewers.join(', '),
+    });
+  }
+  return rows;
+}
+
+export function contextMeterBar(used, size, width = 18) {
+  const ratio = size > 0 ? Math.max(0, Math.min(1, used / size)) : 0;
+  const filled = Math.round(ratio * width);
+  return {
+    bar: '█'.repeat(filled) + '░'.repeat(Math.max(0, width - filled)),
+    ratio,
+    percent: `${Math.round(ratio * 100)}%`,
+    label: `${formatTokens(used) || '0'}/${formatTokens(size) || '?'}`,
+  };
+}
+
+export function sessionUsageSummary(session) {
+  const t = session?.usage?.tokens || session?.tokens || {};
+  const parts = [];
+  if (t.total) parts.push(`${formatTokens(t.total)} tok`);
+  const cost = session?.usage?.cost?.amount ?? session?.cost?.amount;
+  if (cost > 0) parts.push(`~$${cost.toFixed(cost < 1 ? 3 : 2)}`);
+  const turns = session?.usage?.turns ?? session?.turns;
+  if (turns) parts.push(`${turns} turn${turns === 1 ? '' : 's'}`);
+  return parts.join(' · ') || 'no tokens yet';
+}
+
+export function formatTurnUsageLine(usage) {
+  return formatUsageFooter(usage, {}).replace(/^\[usage\] /, '');
+}
+
+export function overlayToSsePayload(overlay) {
+  if (!overlay) return null;
+  return {
+    type: 'overlay',
+    intent: overlay.intent || null,
+    workCategory: overlay.workCategory || null,
+    track: overlay.track || null,
+    specialists: overlay.specialists || [],
+    externalResearch: overlay.externalResearch || null,
+    riskFlags: overlay.riskFlags || null,
+    contractChain: overlay.contractChain || [],
+    framingChallenge: overlay.framingChallenge || null,
+    dispatchSummary: overlay.dispatchSummary || null,
+    dispatchReasons: overlay.dispatchReasons || null,
+    triggers: overlay.triggers || [],
+    docAuthoring: overlay.docAuthoring || null,
+    artifactReview: overlay.artifactReview || null,
+    sessionTurnIndex: overlay.sessionTurnIndex ?? 0,
+    priorIntent: overlay.priorIntent ?? null,
+    workingBranch: overlay.workingBranch ?? null,
+  };
+}
+
+export function sessionMetaToSsePayload({ session, layers, workingBranch, oracle, ctx = null }) {
+  return {
+    type: 'session_meta',
+    model: session?.model || null,
+    demoLabel: session?.demoGuide ? (session.demoTitle || 'scripted') : null,
+    modelMode: session?.modelMode || 'pinned',
+    sandbox: session?.sandbox || null,
+    permissionMode: session?.permissionMode || null,
+    layers: layers || {},
+    workingBranch: workingBranch || null,
+    ctx,
+    oracle: oracle ? {
+      visible: oracle.visible,
+      summary: oracle.summary,
+      topGaps: (oracle.topGaps || []).map((g) => ({ id: g.id, detail: g.detail || g.message || '' })),
+    } : null,
+    usage: session?.usage ? {
+      turns: session.usage.turns,
+      tokens: { ...session.usage.tokens },
+      cost: session.usage.cost ? { ...session.usage.cost } : null,
+    } : null,
+  };
+}

package/lib/chat/session-context.mjs

@@ -0,0 +1,39 @@
+/**
+ * lib/chat/session-context.mjs — session-scoped context for planTurn routing.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { execSync } from 'node:child_process';
+
+export function buildPlanContext({ session, cwd = process.cwd(), turnBlocks = [], text = '' } = {}) {
+  const turns = turnBlocks.filter((item) => item.kind === 'turn');
+  const lastTurn = turns.length ? turns[turns.length - 1].block : null;
+
+  let workingBranch = null;
+  try {
+    workingBranch = execSync('git branch --show-current', { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim() || null;
+  } catch { /* not a git repo */ }
+
+  let projectSummary = null;
+  const contextPath = path.join(cwd, '.cx', 'context.md');
+  try {
+    if (fs.existsSync(contextPath)) {
+      projectSummary = fs.readFileSync(contextPath, 'utf8').slice(0, 500);
+    }
+  } catch { /* unreadable */ }
+
+  const trimmed = String(text).trim();
+  const vagueFollowUp = /^(tell me more|what about|continue|go on|explain|elaborate|and\?)/i.test(trimmed);
+  const projectQuestion = /\b(what is this project|what('s| is) this (repo|project|codebase)|describe this project)\b/i.test(trimmed);
+
+  return {
+    turnIndex: session?.usage?.turns ?? 0,
+    priorIntent: lastTurn?.overlay?.intent ?? null,
+    priorWorkCategory: lastTurn?.overlay?.workCategory ?? null,
+    workingBranch,
+    projectSummary,
+    vagueFollowUp: vagueFollowUp && (session?.usage?.turns ?? 0) > 0,
+    projectQuestion,
+  };
+}

package/lib/chat/session-persist.mjs

@@ -0,0 +1,73 @@
+/**
+ * lib/chat/session-persist.mjs — JSONL transcript persistence for construct chat surfaces.
+ *
+ * Shared by CLI linear mode and dashboard owned-loop SSE so web/desktop resume
+ * matches .cx/chat-sessions/ on disk.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { resolveProjectScopedPath } from '../project-root.mjs';
+import { deserializeBlock, serializeBlock, snapshotTurn } from './tui/turn-block.mjs';
+import { migrateEvidenceVerdict } from './evidence.mjs';
+
+export function chatSessionFilePath({ cwd, convId, host = 'construct-web' }) {
+  const dir = resolveProjectScopedPath('chat-sessions', { cwd });
+  return path.join(dir, `${convId}-${host}.jsonl`);
+}
+
+export function createChatPersister({ cwd, sessionId, resumePath = null, host = 'construct' }) {
+  try {
+    const dir = resolveProjectScopedPath('chat-sessions', { cwd });
+    fs.mkdirSync(dir, { recursive: true });
+    const file = resumePath || path.join(dir, `${new Date().toISOString().replace(/[:.]/g, '-')}-${host}-${sessionId}.jsonl`);
+    if (!resumePath) {
+      fs.appendFileSync(file, `${JSON.stringify({ type: 'session_start', host, sessionId, ts: new Date().toISOString() })}\n`);
+    }
+    const append = (row) => {
+      try {
+        fs.appendFileSync(file, `${JSON.stringify({ ...row, ts: new Date().toISOString() })}\n`);
+      } catch { /* log is best-effort */ }
+    };
+    return {
+      filePath: file,
+      event: (event) => append(event),
+      transcript: (role, text) => append({ type: 'transcript', role, text }),
+      transcriptBlock: (turn) => append(serializeBlock(turn)),
+    };
+  } catch {
+    return null;
+  }
+}
+
+export function loadPersistedTurns(filePath) {
+  if (!filePath || !fs.existsSync(filePath)) return { turns: [], turnBlocks: [] };
+  const turns = [];
+  const turnBlocks = [];
+  const lines = fs.readFileSync(filePath, 'utf8').split('\n').filter(Boolean);
+  for (const line of lines) {
+    try {
+      const row = JSON.parse(line);
+      const block = deserializeBlock(row);
+      if (!block) continue;
+      turnBlocks.push({ kind: 'turn', block });
+      const snap = snapshotTurn(block);
+      const evidence = migrateEvidenceVerdict(snap);
+      turns.push({
+        id: snap.id || `turn-${turns.length + 1}`,
+        userText: snap.userText || '',
+        assistant: snap.assistant || '',
+        thinking: snap.thinking || '',
+        tools: snap.tools || [],
+        overlay: snap.overlay || null,
+        sources: snap.sources || [],
+        usage: snap.usage || null,
+        evidence,
+        unverified: ['insufficient_evidence', 'uncited_evidence', 'partially_verified'].includes(evidence.status),
+        working: false,
+        system: false,
+      });
+    } catch { /* skip malformed rows */ }
+  }
+  return { turns, turnBlocks };
+}