@prplkane/roundtable 0.0.0-stage → 0.6.3

package/src/settings.js

@@ -0,0 +1,27 @@
+// Preserve unreadable settings until the user repairs them and restarts the server.
+import { readFileSync, writeFileSync, renameSync, existsSync, unlinkSync, statSync } from 'node:fs';
+import { randomUUID } from 'node:crypto';
+import path from 'node:path';
+
+export function createSettingsStore(file, { onError = () => {} } = {}) {
+  let value = {}, unreadable = false;
+  try {
+    value = JSON.parse(readFileSync(file, 'utf8'));
+    if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error('Expected a settings object.');
+  } catch (error) {
+    value = {};
+    if (error.code !== 'ENOENT') { unreadable = true; onError(error); }
+  }
+  return {
+    value,
+    save(next) {
+      if (unreadable) throw Object.assign(new Error(`${path.basename(file)} was unreadable at startup. Restore it and restart before saving; the original has not been changed.`), { code: 'SETTINGS_UNREADABLE', status: 409 });
+      if (existsSync(file) && statSync(file).isDirectory()) throw Object.assign(new Error('The settings target is a directory.'), { code: 'EISDIR' });
+      const temporary = `${file}.${randomUUID()}.tmp`;
+      try {
+        writeFileSync(temporary, JSON.stringify(next, null, 2), { flag: 'wx', mode: 0o600, flush: true });
+        renameSync(temporary, file);
+      } finally { if (existsSync(temporary)) unlinkSync(temporary); }
+    },
+  };
+}

package/src/setup-toml.js

@@ -0,0 +1,124 @@
+// A lossless TOML declaration scanner, not a value deserializer. Values remain untouched;
+// quoted/multiline strings, comments and containers cannot impersonate table/key declarations.
+// We only add a fresh table after proving that no existing declaration owns that namespace.
+export const MCP_BEGIN = '# BEGIN Roundtable managed MCP';
+export const MCP_END = '# END Roundtable managed MCP';
+const fail = () => { throw new Error('Unsupported or malformed TOML configuration; it was not changed.'); };
+
+function declarations(text) {
+  let i = 0, context = [];
+  const entries = [], markers = [];
+  const spaces = () => { while (text[i] === ' ' || text[i] === '\t' || text[i] === '\r') i++; };
+  function comment(top = false) {
+    const start = i;
+    while (i < text.length && text[i] !== '\n') i++;
+    const content = text.slice(start, i).trimEnd();
+    if (top && [MCP_BEGIN, MCP_END].includes(content)) markers.push({ text: content, start, end: start + content.length });
+  }
+  function quoted(key = false) {
+    const start = i, quote = text[i++], triple = text.slice(i, i + 2) === quote.repeat(2);
+    if (triple && key) fail();
+    if (triple) i += 2;
+    let value = '';
+    while (i < text.length) {
+      const c = text[i++];
+      if (!triple && (c === '\n' || c === '\r')) fail();
+      if (c === quote) {
+        if (!triple) return value;
+        if (text.slice(i, i + 2) === quote.repeat(2)) {
+          i += 2;
+          for (let n = 0; n < 2 && text[i] === quote; n++) i++;
+          return text.slice(start, i);
+        }
+      }
+      if (quote === '"' && c === '\\') {
+        const escaped = text[i++];
+        if (key) {
+          if (escaped === 'u' || escaped === 'U') {
+            const n = escaped === 'u' ? 4 : 8, hex = text.slice(i, i + n);
+            if (hex.length !== n || !/^[0-9a-f]+$/i.test(hex)) fail();
+            const point = parseInt(hex, 16);
+            if (point > 0x10ffff || point >= 0xd800 && point <= 0xdfff) fail();
+            value += String.fromCodePoint(point); i += n;
+          } else {
+            const escapes = { b: '\b', t: '\t', n: '\n', f: '\f', r: '\r', '"': '"', '\\': '\\' };
+            if (!Object.hasOwn(escapes, escaped)) fail();
+            value += escapes[escaped];
+          }
+        }
+      } else value += c;
+    }
+    fail();
+  }
+  function keyPath() {
+    const keys = [];
+    while (true) {
+      spaces();
+      if (text[i] === '"' || text[i] === "'") keys.push(quoted(true));
+      else {
+        const start = i;
+        while (i < text.length && /[A-Za-z0-9_-]/.test(text[i])) i++;
+        if (i === start) fail();
+        keys.push(text.slice(start, i));
+      }
+      spaces();
+      if (text[i] !== '.') return keys;
+      i++;
+    }
+  }
+  function value() {
+    spaces();
+    if (i >= text.length || text[i] === '#' || text[i] === '\n') fail();
+    const stack = [];
+    while (i < text.length) {
+      const c = text[i];
+      if (c === '\n' && !stack.length) return;
+      if (c === '#' && !stack.length) { comment(); return; }
+      if (c === '#') { comment(); continue; }
+      if (c === '"' || c === "'") { quoted(); continue; }
+      if (c === '[' || c === '{') stack.push(c);
+      if (c === ']' || c === '}') { if (stack.pop() !== (c === ']' ? '[' : '{')) fail(); }
+      i++;
+    }
+    if (stack.length) fail();
+  }
+  while (i < text.length) {
+    spaces();
+    if (text[i] === '\n') { i++; continue; }
+    if (i >= text.length) break;
+    if (text[i] === '#') { comment(true); continue; }
+    const start = i;
+    if (text[i] === '[') {
+      i++; const array = text[i] === '['; if (array) i++;
+      context = keyPath();
+      if (text[i++] !== ']' || array && text[i++] !== ']') fail();
+      entries.push({ start, path: context, table: true, array });
+      spaces(); if (text[i] === '#') comment();
+      if (i < text.length && text[i] !== '\n') fail();
+    } else {
+      const keys = keyPath();
+      if (text[i++] !== '=') fail();
+      entries.push({ start, path: [...context, ...keys], table: false });
+      value();
+    }
+  }
+  return { entries, markers };
+}
+
+export function tomlConnection(text) {
+  const { entries, markers } = declarations(text.replace(/^\uFEFF/, ' '));
+  if (markers.length && (markers.length !== 2 || markers[0].text !== MCP_BEGIN || markers[1].text !== MCP_END)) throw new Error('Roundtable configuration markers are damaged; repair them before setup.');
+  const start = markers[0]?.start, end = markers[1]?.end;
+  for (const d of entries) {
+    if (start != null && d.start > start && d.start < end) continue;
+    if (d.path[0] !== 'mcp_servers') continue;
+    if (d.path[1] === 'roundtable') throw new Error('An existing unmanaged Roundtable MCP entry was found. Keep it or remove it explicitly before using setup.');
+    if (d.path.length === 1 && (!d.table || d.array)) throw new Error('Inline or non-table MCP configuration must use TOML tables before setup; it was preserved.');
+  }
+  return { text, entry: start == null ? null : text.slice(start, end), start, end };
+}
+
+export function replaceTomlConnection(current, entry) {
+  if (current.entry) return current.text.slice(0, current.start) + (entry || '') + current.text.slice(current.end);
+  return `${current.text}${current.text.endsWith('\n') || !current.text ? '' : '\n'}${current.text ? '\n' : ''}${entry}\n`;
+}

package/src/snapshot.js

@@ -0,0 +1,93 @@
+import { rollup, hasUsableRound, DEFAULTS } from './engine.js';
+import { groupQuestions, stopExplanation, cancellationReason } from './review-view.js';
+import { optionLabel, verdictSections } from './contract.js';
+import { safeProgress } from './progress.js';
+import { researchSources } from './research.js';
+
+const RESEARCH_FAILURES = {
+  timeout: 'Research did not finish before its time limit.',
+  network: 'Research could not reach the provider.',
+  quota: 'The research provider reported a usage limit.',
+  auth: 'The research provider requires login.',
+  missing: 'The research provider CLI was not found.',
+  compatibility: 'The research provider does not support a required option.',
+  budget: 'Research was blocked by a budget or operation limit.',
+  policy: 'Research stopped after a provider-policy failure.',
+  format: 'Research did not produce a valid source bundle.',
+  killed: 'Research was cancelled.',
+  interrupted: 'Research was interrupted and was not rerun.',
+  other: 'Research failed. Open the board for details.',
+};
+const integerWithin = (value, min, max) => Number.isSafeInteger(value) && value >= min && value <= max;
+
+// Project both live and saved research: failed transcript rows can contain arbitrary CLI text.
+function researchSnapshot(research) {
+  if (research.status === 'running') return { status: 'running',
+    ...(integerWithin(research.maxSearches, 1, 8) ? { maxSearches: research.maxSearches } : {}),
+    ...(integerWithin(research.timeoutMs, 30000, 600000) ? { timeoutMs: research.timeoutMs } : {}) };
+  if (research.status === 'done') {
+    try {
+      const gatheredAt = new Date(research.gatheredAt).toISOString();
+      if (gatheredAt !== research.gatheredAt || !integerWithin(research.searches, 1, 8)) throw new Error('invalid metadata');
+      return { status: 'done', gatheredAt, searches: research.searches,
+        sources: researchSources(JSON.stringify({ sources: research.sources }), gatheredAt) };
+    } catch { return { status: 'failed', errorKind: 'format', error: RESEARCH_FAILURES.format }; }
+  }
+  const errorKind = research.status === 'interrupted' ? 'interrupted'
+    : Object.hasOwn(RESEARCH_FAILURES, research.errorKind) ? research.errorKind : 'other';
+  return { status: research.status === 'interrupted' ? 'interrupted' : 'failed', errorKind,
+    error: RESEARCH_FAILURES[errorKind], progress: safeProgress(research.progress),
+    ...(integerWithin(research.searches, 0, 9) ? { searches: research.searches } : {}) };
+}
+
+// One compact, read-only view for local clients. Raw provider output and launch tokens stay out.
+export function reviewSnapshot(d) {
+  const state = d.debate?.state || d.rebuilt;
+  const rounds = state.rounds || [];
+  const lastRound = rounds.length - 1;
+  const verdict = state.verdict;
+  const status = d.interrupted ? 'interrupted' : d.finished ? 'done' : state.status === 'error' ? 'error' : d.pending ? 'waiting'
+    : d.synthesizing || d.events.some((e) => e.type === 'stopped') && !d.finished ? 'verdict' : state.status || 'running';
+  const gate = d.pending?.info;
+  const sections = verdict && !verdict.failed && !verdict.skipped ? verdictSections(verdict.text) : null;
+  const usage = rollup(d.events).total;
+  return {
+    schemaVersion: 1, id: d.slug, revision: `${d.gen}:${d.events.length - 1}`, status,
+    decision: state.fieldNotes?.decision, options: state.fieldNotes?.options, round: state.round ?? lastRound,
+    depth: { plannedCritiqueRounds: state.options?.critiqueRounds ?? DEFAULTS.critiqueRounds,
+      attemptedRounds: rounds.filter((r) => r?.length === state.seats.length).length,
+      attemptedCritiqueRounds: rounds.slice(1).filter((r) => r?.length === state.seats.length).length,
+      completedRounds: rounds.filter((r) => hasUsableRound([r], state.seats.length)).length,
+      completedCritiqueRounds: rounds.slice(1).filter((r) => hasUsableRound([r], state.seats.length)).length },
+    deadlineAt: state.deadlineAt, stopReason: state.stopReason || null,
+    ...(state.research ? { research: researchSnapshot(state.research) } : {}),
+    ...(state.stopReason ? { explanation: stopExplanation(state.stopReason, state.stopContext) } : {}),
+    actions: d.finished ? (!verdict || verdict.failed || verdict.skipped) && hasUsableRound(rounds, state.seats.length) ? ['verdict'] : []
+      : d.interrupted ? ['resume'] : status === 'error' ? [] : [...(gate ? ['answer', 'hold'] : ['wait']), ...(d.debate?.canFinish() ? ['finish'] : []), 'stop'],
+    // reopenCalls: the seats already agree, so empty answers end the discussion; any answer text
+    // or message runs one more round at this many calls. Absent when answering cannot reopen.
+    gate: gate ? { round: gate.round, mode: gate.mode, reason: gate.reason, stop: gate.stop, questions: groupQuestions(gate.questions),
+      autoContinueAt: d.pending.autoContinueAt ?? null, timeoutBehavior: 'continue_without_answers',
+      ...(gate.reopenable ? { reopenCalls: (state.seats || []).length } : {}) } : null,
+    nextAction: gate?.questions.length ? {
+      type: 'ask_user',
+      instruction: 'Ask gate.questions using your available user-input tool. If there is no form, ask in chat. Group overlapping questions without losing their IDs. Do not invent answers. Tell the user when the response window closes; unanswered questions remain unknown. Read status before submitting a reply because the review may have continued.',
+      answerTemplate: { round: gate.round, answers: groupQuestions(gate.questions).map((q) => ({ id: q.id, text: '' })) },
+    } : { type: gate || ['researching', 'running', 'verdict'].includes(status) ? 'wait'
+      : status === 'done' && sections ? 'report_result' : 'report_incomplete',
+      ...(!gate && !['researching', 'running', 'verdict'].includes(status) && !(status === 'done' && sections)
+        ? { instruction: 'The review has no completed chairman recommendation. Report its actual status and available actions; do not invent a verdict or automatically start another model call.' } : {}) },
+    replies: (rounds[lastRound] || []).map((r) => ({ lens: r.seat.lens, vendor: r.seat.vendor,
+      status: cancellationReason(r, state.stopReason, lastRound) ? 'cancelled' : r.failed ? 'failed' : r.valid ? 'replied' : 'invalid',
+      // a recovered stall on a complete reply: the provider connection was started again this many times
+      ...(safeProgress(r.progress).reconnects ? { reconnects: safeProgress(r.progress).reconnects } : {}),
+      ...(r.failed ? { reason: cancellationReason(r, state.stopReason, lastRound) || r.errorKind, progress: safeProgress(r.progress) } : r.valid ? {
+        position: optionLabel(r.stanceKey, state.fieldNotes?.options), agreesWith: r.parsed.agreeWith,
+        disagrees: r.parsed.disagree, newPoints: r.parsed.new, assumptions: r.parsed.assumptions,
+      } : {}) })),
+    verdict: verdict ? { status: verdict.skipped ? 'skipped' : verdict.failed ? 'failed' : 'ready',
+      ...(sections ? { sections: Object.fromEntries(Object.entries(sections).map(([key, lines]) => [key, lines.filter((x) => x.trim()).join('\n')])) } : { reason: verdict.reason || verdict.errorKind || 'format' }) } : null,
+    usage: { input: usage.input, cacheRead: usage.cacheRead, cacheWrite: usage.cacheWrite, output: usage.output,
+      cost: usage.cost, tokenCoverage: usage.tokenCoverage, costCoverage: usage.costCoverage },
+  };
+}

package/src/store.js

@@ -0,0 +1,303 @@
+import { mkdirSync, existsSync, appendFileSync, writeFileSync, readFileSync, readdirSync, renameSync, unlinkSync } from 'node:fs';
+import path from 'node:path';
+import { readFile } from 'node:fs/promises';
+import { fieldNotesText } from './prompts.js';
+import { positions, ledgerEntries, synthesisOf } from './engine.js';
+import { ADAPTERS } from './adapters/config.js';
+import { optionId, humanQuestion } from './contract.js';
+import { noteRecord, storedNote } from './notes.js';
+import { researchSources } from './research.js';
+
+// Usage rows written before usageVersion 3 carry the vendor's own input figure. Bring them to
+// the one meaning (input = uncached) by the vendor's cache semantics. Idempotent: a row already
+// at version 3 is left alone, so a legacy transcript with new rows appended reads correctly.
+export function normaliseRows(rows) {
+  return rows.map((r) => {
+    if (!r?.usage || r.usage.usageVersion >= 3 || !r.seat?.vendor) return r;
+    const semantics = ADAPTERS[r.seat.vendor]?.cacheSemantics || 'unknown';
+    const input = semantics === 'subset' ? Math.max(0, (r.usage.input || 0) - (r.usage.cacheRead || 0)) : r.usage.input;
+    return { ...r, usage: { ...r.usage, input, usageVersion: 3, cacheSemantics: semantics, normalised: true } };
+  });
+}
+
+// A transcript from scripted seats: marked fake on its head row (since 0.3.0), or, for older
+// ones, any reply carrying a session id the fake runner made.
+export function isSynthetic(rows) {
+  return rows.some((r) => (r.type === 'field-notes' && r.fake === true) || (typeof r.sessionId === 'string' && r.sessionId.startsWith('fake-')));
+}
+
+const reportTranscriptWarning = (warning) => console.warn(`[transcript] ${warning.message}`);
+
+// Parse bytes so a torn UTF-8 character and a torn JSON value have the same recovery boundary.
+// Only an unreadable, unterminated final line with a valid prefix is recoverable. A completed
+// bad line or a non-record JSON value is corruption; never skip it and trust the rest.
+function inspectTranscript(file, data = existsSync(file) ? readFileSync(file) : Buffer.alloc(0)) {
+  const rows = [];
+  const name = `${path.basename(path.dirname(file))}/transcript.jsonl`;
+  const decoder = new TextDecoder('utf-8', { fatal: true });
+  const corrupt = (line) => Object.assign(new Error(`${name}: corrupt record at line ${line}. Restore the transcript from a backup before resuming or exporting; the original file has not been changed.`), { code: 'TRANSCRIPT_CORRUPT', line });
+  let start = 0, line = 0;
+  while (start < data.length) {
+    line++;
+    const newline = data.indexOf(10, start);
+    const end = newline < 0 ? data.length : newline;
+    let row;
+    try {
+      const text = decoder.decode(data.subarray(start, end));
+      if (text.trim()) row = JSON.parse(text);
+    } catch {
+      if (newline < 0 && rows.some((r) => r.type === 'field-notes')) {
+        const warning = { code: 'TRANSCRIPT_TAIL', line, message: `${name}: incomplete final line ${line} was ignored. Complete records are available; the original bytes will be backed up before the next write.` };
+        return { rows, data, tail: start, warning };
+      }
+      throw corrupt(line);
+    }
+    if (row !== undefined) {
+      if (!row || typeof row !== 'object' || Array.isArray(row) || typeof row.type !== 'string' || !row.type) throw corrupt(line);
+      rows.push(row);
+    }
+    start = end + 1;
+  }
+  return { rows, data, tail: null, warning: null };
+}
+
+// Every readable transcript's valid prefix, oldest folder first. Corrupt records are excluded
+// as a whole with a warning, so one damaged archive does not prevent server startup.
+// excludeSynthetic: leave out whole transcripts from scripted seats (estimates must never learn
+// from them).
+export function readAllTranscripts(root, { excludeSynthetic = false, onWarning = reportTranscriptWarning } = {}) {
+  const rows = [];
+  let dirs = [];
+  try { dirs = readdirSync(root, { withFileTypes: true }).filter((d) => d.isDirectory() && !d.name.startsWith('_')).map((d) => d.name).sort(); } catch { return rows; }
+  for (const name of dirs) {
+    const f = path.join(root, name, 'transcript.jsonl');
+    if (!existsSync(f)) continue;
+    let own;
+    try {
+      const parsed = inspectTranscript(f);
+      own = parsed.rows;
+      if (parsed.warning) onWarning(parsed.warning);
+    } catch (error) { onWarning(error); continue; }
+    if (excludeSynthetic && isSynthetic(own)) continue;
+    rows.push(...normaliseRows(own));
+  }
+  return rows;
+}
+
+export function slugFor(decision, root) {
+  const base = (decision || 'debate').toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '').slice(0, 40) || 'debate';
+  const day = new Date().toISOString().slice(0, 10);
+  let slug;
+  do { slug = `${day}-${base}-${globalThis.crypto.randomUUID().replaceAll('-', '')}`; } while (existsSync(path.join(root, slug)));
+  return slug;
+}
+
+// One folder per debate: transcript.jsonl (every message, with usage), field-notes.md, verdict.md.
+export function openDebateDir(root, slug, { create = true } = {}) {
+  const dir = path.join(root, slug);
+  const transcript = path.join(dir, 'transcript.jsonl');
+  if (!create && !existsSync(transcript)) return null;
+  mkdirSync(dir, { recursive: true });
+  let prepared = false;
+  function prepareAppend() {
+    if (prepared) return null;
+    const parsed = inspectTranscript(transcript);
+    let recovery = null;
+    if (parsed.tail != null) {
+      const id = globalThis.crypto.randomUUID();
+      const backup = `transcript.recovery-${id}.jsonl`;
+      const temporary = path.join(dir, `transcript.repair-${id}.tmp`);
+      // Save the exact original first, without replacing an existing file. Stage the repaired
+      // prefix separately; a failed backup or replacement leaves the original unchanged.
+      writeFileSync(path.join(dir, backup), parsed.data, { flag: 'wx', mode: 0o600 });
+      recovery = { t: new Date().toISOString(), type: 'transcript-recovered', line: parsed.warning.line, backup,
+        message: `Recovered complete records before incomplete line ${parsed.warning.line}. The exact original is saved beside the transcript as ${backup}.` };
+      writeFileSync(temporary, Buffer.concat([parsed.data.subarray(0, parsed.tail), Buffer.from(JSON.stringify(recovery) + '\n')]), { flag: 'wx', mode: 0o600 });
+      try { renameSync(temporary, transcript); } finally { if (existsSync(temporary)) unlinkSync(temporary); }
+    } else if (parsed.data.length && parsed.data.at(-1) !== 10) {
+      // A fully written final JSON value is valid even without its newline. Separate the next
+      // append so it cannot turn two valid records into one corrupt line.
+      appendFileSync(transcript, '\n');
+    }
+    prepared = true;
+    return recovery;
+  }
+  return {
+    dir,
+    prepareAppend,
+    // One empty directory per instance: the CLIs read project files, project memory and
+    // project settings from the working directory, so none of that is shared between seats.
+    seatDir(id) {
+      const d = path.join(dir, 'seats', String(id).replace(/[^a-z0-9_-]/gi, '_'));
+      mkdirSync(d, { recursive: true });
+      return d;
+    },
+    append(row) {
+      try {
+        prepareAppend();
+        appendFileSync(transcript, JSON.stringify({ t: new Date().toISOString(), ...row }) + '\n', { flush: row.type === 'attempt-start' });
+      } catch (error) {
+        // A failed append can have written a torn tail. Even this same writer must inspect
+        // and preserve it before a later turn or a repaired review writes anything else.
+        prepared = false;
+        throw error;
+      }
+    },
+    writeFieldNotes(fn, seats) {
+      const md = [
+        `# Field notes: ${fn.decision}`, '',
+        '```', fieldNotesText(fn), '```', '',
+        '## Seats', ...seats.map((s) => `- ${s.vendor}${s.endpoint ? ` at ${s.endpoint}` : ''} as "${s.lens}"`), '',
+      ].join('\n');
+      writeFileSync(path.join(dir, 'field-notes.md'), md);
+    },
+    writeVerdict(text, meta) {
+      const md = [
+        `# Verdict: ${meta.decision}`, '',
+        `Chairman: ${meta.chairman}. Rounds: ${meta.rounds}. Stopped because: ${meta.stopReason}.`, '',
+        text.trim(), '',
+      ].join('\n');
+      writeFileSync(path.join(dir, 'verdict.md'), md);
+    },
+    readTranscript({ onWarning = reportTranscriptWarning } = {}) {
+      const parsed = inspectTranscript(transcript);
+      if (parsed.warning) onWarning(parsed.warning);
+      return parsed.rows;
+    },
+    async readTranscriptAsync({ onWarning = reportTranscriptWarning } = {}) {
+      const parsed = inspectTranscript(transcript, await readFile(transcript));
+      if (parsed.warning) onWarning(parsed.warning);
+      return parsed.rows;
+    },
+  };
+}
+
+// Rebuild a debate from its transcript rows: what the board needs to replay it, and what the
+// engine needs to continue it. Pure. A round is complete when every seat in the field-notes row
+// has a reply at that index; a partial round is dropped and re-run from scratch on resume. When
+// a seat has several reply rows for one round (a re-run after an interruption), the last wins.
+// Returns null when there is no field-notes row.
+export function rebuildDebate(rows) {
+  rows = normaliseRows(rows);
+  const head = rows.find((r) => r.type === 'field-notes');
+  if (!head) return null;
+  let research = rows.findLast((r) => r.type === 'research') || (rows.some((r) => r.type === 'research-start') ? { status: 'interrupted' } : null);
+  const fieldNotes = { ...head.fieldNotes };
+  delete fieldNotes.research;
+  if (research?.status === 'done') {
+    try {
+      const gatheredAt = new Date(research.gatheredAt).toISOString();
+      if (!Number.isInteger(research.searches) || research.searches < 1 || research.searches > 8) throw new Error('invalid count');
+      research = { status: 'done', gatheredAt, searches: research.searches, attemptId: research.attemptId,
+        sources: researchSources(JSON.stringify({ sources: research.sources }), gatheredAt) };
+      fieldNotes.research = research.sources;
+    } catch { research = { status: 'failed', errorKind: 'format', error: 'The saved research bundle is invalid. It was not refetched.' }; }
+  }
+  const seats = head.seats || [];
+  const sid = (s) => s?.id ?? `${s?.vendor}:${s?.lens}`; // schema 1 rows had no seat id
+  const byRound = new Map(); // round -> Map(seatId -> reply)
+  const humanNotes = [], initialNotes = [], reopens = [];
+  let stop = null, verdict = null, error = null, resumedRows = 0, accepted = null;
+  const downs = [];
+  let fallback = null;
+  const originalOf = new Map(); // a normalized reply -> the row as written (for usage identity)
+  for (const r of rows) {
+    if (r.type === 'reply') {
+      if (!byRound.has(r.round)) byRound.set(r.round, new Map());
+      // before 0.3.0 a stance key was the option's label; since, its id. A resumed old debate
+      // compares both, so old keys are read as ids (PASS and "other: …" are left as they are);
+      // otherwise a stance that never moved could not count as stable.
+      const old = !(head.schemaVersion >= 3) && r.stanceKey && r.stanceKey !== 'PASS' && !r.stanceKey.startsWith('other: ');
+      let row = old ? { ...r, stanceKey: optionId(r.stanceKey, head.fieldNotes?.options) ?? r.stanceKey } : r;
+      const question = humanQuestion(r.question);
+      if (question !== (r.question ?? null) || (r.parsed?.question && humanQuestion(r.parsed.question) !== r.parsed.question))
+        row = { ...row, question, ...(row.parsed ? { parsed: { ...row.parsed, question: humanQuestion(row.parsed.question) } } : {}) };
+      if (row !== r) originalOf.set(row, r);
+      byRound.get(r.round).set(sid(r.seat), row);
+    } else if (r.type === 'human') (r.round === -1 ? initialNotes : (humanNotes[r.round] ??= [])).push(storedNote(r));
+    else if (r.type === 'reopen') reopens.push(r);
+    else if (r.type === 'stop') stop = r;
+    else if (r.type === 'verdict') verdict = r;
+    else if (r.type === 'synthesis-cancelled') verdict = { text: 'Verdict not written: you stopped the synthesis.', failed: true, skipped: true, reason: r.reason, seat: null };
+    else if (r.type === 'error') error = r;
+    else if (r.type === 'resumed') resumedRows++;
+    else if (r.type === 'accepted') accepted = r;
+    else if (r.type === 'pool-down') downs.push(r);
+    else if (r.type === 'chairman-fallback') fallback = r;
+  }
+  const rounds = [];
+  for (let i = 0; byRound.has(i); i++) {
+    const m = byRound.get(i);
+    if (seats.length && !seats.every((s) => m.has(sid(s)))) break; // partial: stop here
+    rounds.push(seats.length ? seats.map((s) => m.get(sid(s))) : [...m.values()]);
+  }
+  const partialRound = byRound.has(rounds.length) ? rounds.length : null;
+  // finished: the rounds are closed. synthesis: whether a verdict got written. They are separate,
+  // so a debate whose verdict was skipped or failed is complete and can still be given one.
+  // before 0.3.0 a failed chairman was a verdict whose text began "Chairman failed:"
+  if (verdict && !verdict.failed && !verdict.skipped && /^Chairman failed:/.test(verdict.text || '')) verdict = { ...verdict, failed: true };
+  const finished = !!(stop || verdict);
+  const synthesis = synthesisOf(verdict);
+  const deadlineAt = [...rows].reverse().find((r) => (r.type === 'resumed' || r.type === 'field-notes') && r.deadlineAt != null)?.deadlineAt ?? null;
+  // session ids: the last reply row of each seat (resume mode continues the thread)
+  const sessions = {};
+  for (const r of rows) if (r.type === 'reply' && r.sessionId) sessions[sid(r.seat)] = r.sessionId;
+  // The spend ledger, partial rounds included (they were paid for), and each seat's last
+  // cumulative cost reading, so a resumed session is charged only its own part.
+  const ledger = ledgerEntries(rows);
+  // Older versions recorded tool activity on a repair/reply row after the successful
+  // attempt. Keep the policy state even if the process stopped before a complete round.
+  const policyFailures = rows.filter((r) => r.seat && (r.usedTools || r.toolFail || r.errorKind === 'policy')).map((r) => r.seat);
+  const lastRawCost = {};
+  for (const e of ledger) {
+    const cost = e.usage?.raw?.cost ?? e.rawCost;
+    if (typeof cost === 'number') lastRawCost[sid(e.seat)] = cost;
+  }
+  const seatsWithSessions = seats.map((s) => ({ ...s, sessionId: sessions[sid(s)] || null, ...(lastRawCost[sid(s)] != null ? { lastRawCost: lastRawCost[sid(s)] } : {}) }));
+  // Ledger entries the board must see as attempts: real attempt rows, plus legacy usage that no
+  // replayed reply carries (a re-prompt whose turn never got a reply, and, since only the last
+  // replay, a reply superseded by a re-run, a reply in a partial round).
+  const shownReplies = new Set(rounds.flat().map((x) => originalOf.get(x) || x));
+  const attemptEvents = [
+    ...ledger.filter((e) => e.type === 'attempt' || e.type === 'reprompt'),
+    ...rows.filter((r) => r.type === 'reply' && !r.attemptId && r.usage && !shownReplies.has(r)).map((r) => ({ ...r, kind: 'reply' })),
+  ].map((e) => ({ ...e, type: 'attempt' }));
+  const shown = new Set();
+  const attemptsFor = (pred) => attemptEvents.filter((e, i) => !shown.has(i) && pred(e) && shown.add(i));
+
+  // The event list the board replays. Same shapes as the live engine emits.
+  const t = (row) => ({ type: row.type });
+  const events = [{ type: 'started', seats, fieldNotes, options: head.options, chairman: head.chairman, deadlineAt, replayed: true }];
+  if (research) events.push({ type: 'research', ...research, replayed: true });
+  const recoveryWarnings = rows.filter((r) => r.type === 'transcript-recovered').map((r) => ({ ...r, type: 'transcript-warning' }));
+  events.push(...recoveryWarnings);
+  events.push(...initialNotes.map((note) => ({ type: 'human', round: -1, ...noteRecord(note) })));
+  rounds.forEach((replies, i) => {
+    events.push({ type: 'round-start', round: i });
+    events.push(...attemptsFor((e) => e.round === i && e.kind !== 'verdict'));
+    for (const r of replies) {
+      events.push({ ...r, type: 'reply' });
+      events.push({ type: 'seat-state', round: i, seat: r.seat, state: r.state || (r.failed ? (r.timedOut ? 'timed-out' : 'failed') : (r.reprompted ? 'reprompted' : 'replied')) });
+    }
+    events.push({ type: 'round-done', round: i, replies, positions: positions(replies) });
+    for (const timeout of rows.filter((r) => r.type === 'gate-timeout' && r.round === i)) events.push({ type: 'gate-timeout', round: i, unanswered: timeout.unanswered });
+    for (const note of humanNotes[i] || []) events.push({ type: 'human', round: i, ...noteRecord(note) });
+    for (const ro of reopens.filter((x) => x.round === i)) events.push({ type: 'reopen', round: ro.round, stop: ro.stop });
+  });
+  events.push(...attemptsFor(() => true)); // a partial round's calls and the chairman's
+  events.push(...rows.filter((r) => r.type === 'budget'));
+  for (const x of downs) events.push({ ...x, type: 'pool-down' });
+  if (fallback) events.push({ ...fallback, type: 'chairman-fallback' });
+  for (const expired of rows.filter((r) => r.type === 'gate-expired')) events.push({ type: 'gate-expired', round: expired.round });
+  if (stop) events.push({ type: 'stopped', reason: stop.reason, rounds: stop.rounds, context: stop.context });
+  if (verdict && verdict.skipped) events.push({ type: 'verdict', seat: null, text: verdict.text, usage: null, failed: true, skipped: true, reason: verdict.reason });
+  else if (verdict) events.push({ type: 'chairman-start', seat: verdict.seat }, { type: 'verdict', seat: verdict.seat, text: verdict.text, usage: verdict.usage, attemptId: verdict.attemptId, progress: verdict.progress, ...(verdict.failed ? { failed: true, errors: verdict.errors, errorKind: verdict.errorKind, cancelReason: verdict.cancelReason } : {}) });
+  if (error && !finished) events.push({ type: 'error', message: error.message });
+  if (finished) events.push({ type: 'done', reason: stop?.reason ?? null, replayed: true, synthesis });
+  else events.push({ type: 'interrupted', round: rounds.length, partialRound, resumedBefore: resumedRows });
+  if (accepted) events.push({ ...accepted, type: 'accepted' });
+  return {
+    fieldNotes, research, seats: seatsWithSessions, chairman: head.chairman, options: head.options,
+    rounds, humanNotes, initialNotes, partialRound, finished, synthesis, deadlineAt, accepted, stopReason: stop?.reason ?? null, stopContext: stop?.context ?? null, verdict, nextRound: rounds.length, events, ledger, policyFailures, recoveryWarnings,
+  };
+}

package/src/terminal.js

@@ -0,0 +1,53 @@
+import { VERSION } from './version.js';
+
+// The app's logo tile, pixel for pixel (src/ui/logo.svg): the round table on its 16x16 tile,
+// orchid with aubergine ink like the board header. Half blocks put two pixel rows in one
+// terminal cell, so the tile keeps its square shape at 16 columns by 8 rows.
+const TILE = [
+  '................', '................',
+  '......####......', '....##....##....', '...#........#...', '...#..####..#...',
+  '..#..######..#..', '..#..######..#..', '..#..######..#..', '...#..####..#...',
+  '...#........#...', '....##....##....', '......####......',
+  '................', '................', '................',
+];
+const TAGLINE = 'Local decision reviews';
+const RESET = '\x1b[0m';
+
+// Half blocks need a UTF-8 terminal. Windows consoles take UTF-16 from Node whatever the code
+// page; elsewhere the locale has to say so. ROUNDTABLE_ASCII=1 forces the plain form.
+const unicode = (env, platform) => env.ROUNDTABLE_ASCII !== '1'
+  && (platform === 'win32' || /utf-?8/i.test(env.LC_ALL || env.LC_CTYPE || env.LANG || ''));
+// Tile and ink colours: true colour where the terminal says so, the nearest 256-colour or
+// basic pair otherwise. Returned as [tile background, ink foreground, orchid foreground].
+function palette(env, platform) {
+  if (/truecolor|24bit/i.test(env.COLORTERM || '') || env.WT_SESSION || platform === 'win32') return ['\x1b[48;2;199;154;208m', '\x1b[38;2;43;29;56m', '\x1b[38;2;199;154;208m'];
+  if (env.TERM?.includes('256color')) return ['\x1b[48;5;182m', '\x1b[38;5;234m', '\x1b[38;5;182m'];
+  return ['\x1b[45m', '\x1b[30m', '\x1b[35m'];
+}
+
+function tileRows(colour) {
+  const rows = [];
+  for (let y = 0; y < TILE.length; y += 2) {
+    let line = '';
+    for (let x = 0; x < 16; x++) {
+      const top = TILE[y][x] === '#', bottom = TILE[y + 1][x] === '#';
+      line += top && bottom ? '█' : top ? '▀' : bottom ? '▄' : ' ';
+    }
+    rows.push(colour(line));
+  }
+  return rows;
+}
+
+export function terminalBanner({ isTTY = process.stdout.isTTY, columns = process.stdout.columns ?? 80, env = process.env, platform = process.platform } = {}) {
+  if (!isTTY || env.CI || env.TERM === 'dumb') return '';
+  const paint = (s, code) => env.NO_COLOR ? s : `${code}${s}${RESET}`;
+  const [tile, ink, orchid] = palette(env, platform);
+  const version = `v${VERSION}`;
+  const name = paint('ROUNDTABLE', '\x1b[1m');
+  const compact = `${name}${columns >= 12 + version.length ? `  ${paint(version, '\x1b[2m')}` : ''}`;
+  // 2 indent + 16 tile + 3 gap + the tagline, the widest line beside the tile
+  if (!unicode(env, platform) || columns < 21 + TAGLINE.length) return `\n${compact}\n\n`;
+  const beside = { 2: `${name} ${paint('▌', orchid)}`, 3: paint(version, '\x1b[2m'), 5: paint(TAGLINE, '\x1b[2m') };
+  const lines = tileRows((row) => paint(row, tile + ink)).map((row, y) => `  ${row}${beside[y] ? `   ${beside[y]}` : ''}`);
+  return `\n${lines.join('\n')}\n\n`;
+}