@prplkane/roundtable 0.0.0-stage → 0.6.4

package/src/fake.js

@@ -0,0 +1,75 @@
+// A scripted runner for trying the board without spending tokens: `node src/server.js --fake`.
+// With `--fake-consensus` every seat takes the first option in rounds 0 and 1, so the board shows
+// the unanimous round-0 gate and, after a note, the reopened round 1 stopping on consensus.
+import { setTimeout as delay } from 'node:timers/promises';
+const sleep = (ms, signal) => delay(ms, undefined, { signal }).catch((error) => {
+  if (signal?.aborted) throw Object.assign(new Error('scripted call cancelled'), { code: 'KILLED', kind: 'killed' });
+  throw error;
+});
+const pick = (arr, i) => arr[i % arr.length];
+
+// A plausible quota snapshot so the strip can be seen without real seats.
+// Reset times are fixed at load so snapshots compare as the same window (a moved reset time
+// marks a rolled-over window and voids the delta; see estimate.js windowDeltas).
+const BOOT = Math.floor(Date.now() / 1000);
+let codexCalls = 0, agyCalls = 0;
+// agy's comes in groups of windows per model family, as `agy -p /usage` reports it (quota.js).
+const AGY_GROUPS = [['Gemini Models', 'Gemini', ['Gemini Flash', 'Gemini Pro'], [0.03, 0.02]], ['Claude and GPT models', 'Claude and GPT', ['Claude Opus', 'Claude Sonnet', 'GPT-OSS'], [0.01, 0]], ['Gemini 4 Argon', 'Gemini 4 Argon', [], [0.41]]];
+export function fakeQuota(vendor, n = vendor === 'codex' ? codexCalls++ : vendor === 'agy' ? agyCalls++ : 0) {
+  if (vendor === 'agy') return {
+    windows: AGY_GROUPS.flatMap(([group, tag, , used]) => used.map((u, i) => ({ label: `${tag} ${i ? '5h' : '7d'}`, used: Math.min(0.95, u + n * 0.01 * (i + 1)), resetsAt: BOOT + (i ? 4 * 3600 : 3 * 86400), group }))),
+    groups: AGY_GROUPS.map(([name, , models]) => ({ name, models })),
+    credits: { remaining: 1200, at: Date.now() }, // as `agy -p /credits` reports them
+    plan: null,
+    at: Date.now(),
+  };
+  return {
+    windows: [
+      { label: '5h', used: Math.min(0.95, 0.12 + n * 0.07), resetsAt: BOOT + 3 * 3600 + 600 },
+      { label: '7d', used: Math.min(0.95, 0.31 + n * 0.02), resetsAt: BOOT + 2 * 86400 + 5 * 3600 },
+    ],
+    plan: vendor === 'codex' ? 'fake' : null,
+    at: Date.now(),
+  };
+}
+
+export function fakeRunner({ consensus = false } = {}) {
+  let calls = 0;
+  return async (vendor, prompt, sessionId, opts = {}) => {
+    const n = calls++;
+    // Behaviour follows the seat's position at the table, so two seats of one vendor still differ.
+    const idx = opts.seat?.index ?? (/chairman/i.test(prompt) ? -1 : n % 3);
+    const who = idx === 0 ? 'claude' : idx === 1 ? 'codex' : 'agy'; // the v1 script's three roles
+    await sleep(800 + Math.random() * 1500, opts.signal);
+    const round = Number((prompt.match(/^Round (\d+) of/m) || [])[1] ?? (/chairman/i.test(prompt) ? -1 : 0));
+    // OPTIONS: opt-1 = Ship now | opt-2 = Wait a sprint (the chairman sees the same line)
+    const options = (prompt.match(/^OPTIONS: (.+)$/m)?.[1] || '').split(' | ').map((o) => o.replace(/^opt-\d+ = /, '')).slice(0, 4);
+    const usage = { input: 9000 + n * 1200, cacheRead: n * 400, cacheWrite: 0, output: 180 + (n % 5) * 40, thinking: 60, cost: vendor === 'claude' ? 0.11 + n * 0.02 : null, ms: 900, usageVersion: 3 };
+    if (opts.research) return { text: JSON.stringify({ sources: [{ url: 'https://example.com/research-demo', title: 'Scripted demo source',
+      excerpt: 'Synthetic evidence for exercising the shared research flow. No website was searched.', publishedAt: null }] }),
+      usage, sessionId: 'fake-research', research: { searches: 1 } };
+    let text;
+    if (round === -1) {
+      text = `RECOMMENDATION: opt-1\nChoose ${pick(options, 0)} if the rollout can be monitored and reversed.\n\nIt offers the better balance of risk and cost. The adoption concern remains worth watching.\nDISSENT: The customer lens argued that ${pick(options, 1)} protects adoption; that risk is real and should be watched.\nKILL_CRITERIA:\n- Support tickets about the change exceed 5% of weekly volume\n- The migration takes more than two sprints\nOPEN_QUESTIONS:\n- OPTIONAL: Is the deadline movable by a week?`;
+    } else if (!consensus && round >= 2 && who === 'codex') {
+      text = 'PASS';
+    } else if (!consensus && round === 0 && who === 'agy' && !/did not follow the contract/.test(prompt)) {
+      text = `I think ${pick(options, 1)} is right because customers hate surprises.`; // off contract, forces a re-prompt
+    } else {
+      // claude answers with the id, the others with the exact label: the contract accepts both
+      const n2 = !consensus && (who === 'agy' || idx >= 3) ? 1 : 0;
+      const stance = who === 'claude' ? `opt-${n2 + 1}` : pick(options, n2);
+      text = [
+        `STANCE: ${stance}`,
+        `AGREE_WITH: [${round > 0 && who === 'claude' ? 'cost and effort' : ''}]`,
+        'DISAGREE:', `- The ${who === 'agy' ? 'cost' : 'customer'} argument assumes a traffic pattern we have not measured`,
+        'NEW:', round === 1 ? '- A staged rollout to 10% of accounts gives both sides their evidence' : '- none',
+        'ASSUMPTIONS:', '- The team stays at two developers', '- No regulatory change before the deadline',
+        !consensus && round === 0 ? `QUESTION_FOR_HUMAN: ${who === 'agy' ? 'What evidence would make you stop the trial?' : 'Is the deadline movable by one week?'}`
+          : !consensus && round === 1 && who === 'agy' && !/Answer:/.test(prompt) ? 'QUESTION_FOR_HUMAN: Is the deadline movable by one week?' : null,
+      ].filter(Boolean).join('\n');
+    }
+    const quota = vendor === 'claude' ? fakeQuota(vendor, n) : null; // claude's rides on each reply
+    return { text, usage, sessionId: sessionId || `fake-${opts.seat?.id || vendor}-${n}`, quota, raw: {} };
+  };
+}

package/src/folder-picker.js

@@ -0,0 +1,46 @@
+// The operating system's own folder dialog, opened by the local server so the board can offer a
+// "Choose…" button: a page cannot learn a real folder path from the browser's own picker. Nothing
+// from a request reaches the command line; the commands below are fixed.
+import { execFile } from 'node:child_process';
+
+const PROMPT = 'Choose a folder for the decision record';
+const WINDOWS = [
+  "$ErrorActionPreference = 'Stop'",
+  'Add-Type -AssemblyName System.Windows.Forms',
+  // an invisible topmost owner keeps the dialog in front of the browser instead of behind it
+  '$owner = New-Object System.Windows.Forms.Form -Property @{ TopMost = $true; ShowInTaskbar = $false }',
+  '$dialog = New-Object System.Windows.Forms.FolderBrowserDialog',
+  `$dialog.Description = '${PROMPT}'`,
+  '$dialog.ShowNewFolderButton = $true',
+  "if ($dialog.ShowDialog($owner) -eq 'OK') { [Console]::Out.Write($dialog.SelectedPath) }",
+].join('; ');
+
+// The candidates for one platform, tried in order until one exists.
+export function pickerCommands(platform = process.platform) {
+  if (platform === 'win32') return [['powershell.exe', ['-NoProfile', '-STA', '-NonInteractive', '-Command', WINDOWS]]];
+  if (platform === 'darwin') return [['osascript', ['-e', `try\n  return POSIX path of (choose folder with prompt "${PROMPT}")\non error message number code\n  if code is -128 then return ""\n  error message number code\nend try`]]];
+  return [['zenity', ['--file-selection', '--directory', `--title=${PROMPT}`]], ['kdialog', ['--getexistingdirectory', '.', '--title', PROMPT]]];
+}
+
+const execute = (file, args) => new Promise((resolve) => {
+  execFile(file, args, { timeout: 10 * 60_000, windowsHide: true, encoding: 'utf8' }, (error, stdout, stderr) => resolve({ error, stdout: String(stdout || ''), stderr: String(stderr || '') }));
+});
+
+// The chosen folder, or null when the person cancels. Throws when this machine has no dialog to
+// offer, with what to do instead.
+export async function pickFolder({ platform = process.platform, run = execute } = {}) {
+  for (const [file, args] of pickerCommands(platform)) {
+    const { error, stdout = '', stderr = '' } = await run(file, args);
+    if (error?.code === 'ENOENT') continue; // not installed: try the next one
+    if (error?.killed) throw Object.assign(new Error('The folder dialog timed out. Type the folder path instead.'), { status: 504 });
+    // Windows cancels with empty successful output; AppleScript handles -128 above. The Linux
+    // pickers use status 1 for cancellation. Display or execution failures carry stderr.
+    const cancelled = ['zenity', 'kdialog'].includes(file) && error?.code === 1 && !stderr.trim() && !stdout.trim();
+    if (error && !cancelled) throw Object.assign(new Error('The folder dialog could not open or finish. Type the folder path instead.'), { status: 503 });
+    const out = stdout.trim();
+    if (!out) return null;
+    // drop a trailing separator (macOS adds one), except on a drive or filesystem root
+    return /^([A-Za-z]:)?[\\/]$/.test(out) ? out : out.replace(/[\\/]+$/, '');
+  }
+  throw Object.assign(new Error('No folder dialog is available on this machine. Type the folder path instead.'), { status: 501 });
+}

package/src/history.js

@@ -0,0 +1,220 @@
+// Local history and numeric usage records. Neither is model memory.
+import { mkdirSync, existsSync, readFileSync, writeFileSync, renameSync, unlinkSync, readdirSync, lstatSync, realpathSync, rmSync } from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { createHash, randomUUID } from 'node:crypto';
+import { openDebateDir, normaliseRows, isSynthetic } from './store.js';
+import { ledgerEntries, rollup } from './engine.js';
+import { baselinesFrom } from './estimate.js';
+import { readdir, stat } from 'node:fs/promises';
+import { decisionRecord } from './export.js';
+
+// Cache small summaries, never transcript bodies. Changed records are read asynchronously;
+// a cold history scan yields between files so active reviews and Stop remain responsive.
+export function createHistoryIndex(root, { onWarning = () => {}, limit = 1000 } = {}) {
+  const summaries = new Map();
+  let pending = null;
+  const signature = (s) => `${s.mtimeMs}:${s.ctimeMs}:${s.size}:${s.ino}`;
+  async function scan() {
+    // Misses must not evict hits that this same enumeration has yet to visit. Otherwise a
+    // history just above the cache limit rereads every file on every request.
+    const previous = new Map(summaries);
+    const dirs = await readdir(root, { withFileTypes: true });
+    const ids = dirs.filter((d) => d.isDirectory() && /^[a-z0-9-]+$/.test(d.name)).map((d) => d.name);
+    const present = new Set(ids), result = [];
+    for (const id of summaries.keys()) if (!present.has(id)) summaries.delete(id);
+    for (const slug of ids) {
+      const file = path.join(root, slug, 'transcript.jsonl');
+      let before;
+      try {
+        before = await stat(file);
+        const key = signature(before), cached = previous.get(slug);
+        if (cached?.key === key) {
+          summaries.delete(slug); summaries.set(slug, cached);
+          while (summaries.size > limit) summaries.delete(summaries.keys().next().value);
+          result.push(cached.value); continue;
+        }
+        const warnings = [];
+        const store = openDebateDir(root, slug, { create: false });
+        if (!store) continue;
+        const rows = await store.readTranscriptAsync({ onWarning: (w) => warnings.push(w) });
+        if (!rows.some((r) => r.type === 'field-notes')) continue;
+        const { meta, summary } = decisionRecord(rows, slug, { warnings, metadataOnly: true });
+        const value = { slug, ...summary, date: slug.slice(0, 10), updated: before.mtimeMs,
+          status: meta.status, chosen: meta.chosen, recommended: meta.recommended, accepted: meta.accepted };
+        const after = await stat(file);
+        if (signature(after) === key) {
+          summaries.delete(slug); summaries.set(slug, { key, value });
+          while (summaries.size > limit) summaries.delete(summaries.keys().next().value);
+        }
+        result.push(value);
+      } catch (error) {
+        if (error.code === 'ENOENT') continue;
+        summaries.delete(slug); onWarning(error, slug);
+        result.push({ slug, decision: slug, date: slug.slice(0, 10), updated: before?.mtimeMs || 0,
+          state: 'corrupt', status: 'corrupt', warning: error.message });
+      }
+    }
+    return result.sort((a, b) => b.updated - a.updated);
+  }
+  return {
+    list() { return pending ||= scan().finally(() => { pending = null; }); },
+    invalidate(id) { summaries.delete(id); },
+  };
+}
+
+// Windows keeps history in %USERPROFILE%\.roundtable, not AppData: Windows redirects AppData
+// writes of a program started from a packaged app (the Claude and Codex desktop apps, and every
+// terminal and agent shell they open) into that app's private copy, so each app saw its own
+// history and its own server lock. The user profile folder is the same for every program.
+export function dataDirectory({ fake = false, env = process.env, platform = process.platform, home = os.homedir() } = {}) {
+  if (env.ROUNDTABLE_DEBATES_DIR) return path.resolve(env.ROUNDTABLE_DEBATES_DIR);
+  const base = platform === 'win32' ? path.join(home, '.roundtable')
+    : platform === 'darwin' ? path.join(home, 'Library', 'Application Support', 'Roundtable')
+      : path.join(env.XDG_DATA_HOME || path.join(home, '.local', 'share'), 'roundtable');
+  return path.resolve(base, fake ? 'demo' : 'live');
+}
+
+// Folders that may still hold reviews this data folder lacks: a checkout's `debates/` from before
+// the user-data folder, and on Windows the earlier %LOCALAPPDATA%\Roundtable default with the
+// private copies packaged apps kept of it (%LOCALAPPDATA%\Packages\<app>\LocalCache\Local). Only
+// a folder with a review the data folder does not have is reported, so a copy left behind after
+// its reviews were moved stays quiet. Read only: nothing is moved or merged.
+//   -> [{ dir, missing }]   missing: how many of its reviews the data folder lacks
+export function legacyHistory(dataDir, { root, fake = false, env = process.env, platform = process.platform } = {}) {
+  const mode = fake ? 'demo' : 'live';
+  const candidates = root ? [path.join(root, fake ? 'debates-fake' : 'debates')] : [];
+  if (platform === 'win32' && env.LOCALAPPDATA) {
+    candidates.push(path.join(env.LOCALAPPDATA, 'Roundtable', mode));
+    let apps = [];
+    try { apps = readdirSync(path.join(env.LOCALAPPDATA, 'Packages')); } catch { /* no packaged apps */ }
+    for (const app of apps) candidates.push(path.join(env.LOCALAPPDATA, 'Packages', app, 'LocalCache', 'Local', 'Roundtable', mode));
+  }
+  const same = (a, b) => (platform === 'win32' ? path.resolve(a).toLowerCase() === path.resolve(b).toLowerCase() : path.resolve(a) === path.resolve(b));
+  // a folder that cannot be listed is not reported, and never stops the server starting
+  const ids = (dir) => { try { return historyIds(dir); } catch { return []; } };
+  const have = new Set(ids(dataDir));
+  const found = [];
+  for (const dir of candidates) {
+    if (same(dir, dataDir)) continue;
+    const missing = ids(dir).filter((id) => !have.has(id));
+    if (!missing.length) continue;
+    found.push({ dir, missing: missing.length });
+    // counted once: a packaged app's server sees its own copy both through %LOCALAPPDATA% and at
+    // its Packages path, and would otherwise name the same reviews twice
+    for (const id of missing) have.add(id);
+  }
+  return found;
+}
+
+// A single server owns a data folder. This also protects sessions opened on another port.
+// An abruptly terminated server leaves a lock whose dead PID can be reclaimed at startup.
+export function acquireDataLock(root) {
+  mkdirSync(root, { recursive: true });
+  const file = path.join(root, '_server.lock'), owner = JSON.stringify({ pid: process.pid, nonce: randomUUID() });
+  const starting = path.join(root, '_server.starting');
+  try { writeFileSync(starting, owner, { flag: 'wx', mode: 0o600 }); }
+  catch (error) {
+    if (error.code !== 'EEXIST') throw error;
+    throw new Error('Another server is starting with this data folder. Retry once it has started. If startup was interrupted, check that no server uses the folder before removing _server.starting.');
+  }
+  try {
+    if (existsSync(file)) {
+      if (lstatSync(file).isSymbolicLink()) throw new Error('The data-folder lock must not be a link.');
+      const prior = readFileSync(file, 'utf8');
+      let pid; try { pid = JSON.parse(prior).pid; } catch { /* fail closed */ }
+      if (!Number.isSafeInteger(pid) || pid <= 0) throw new Error('The data-folder lock is unreadable. Check that its server has stopped before removing _server.lock.');
+      let running = true;
+      try { process.kill(pid, 0); } catch (e) { if (e.code === 'ESRCH') running = false; }
+      if (running) throw new Error('This data folder is already open in another Roundtable server. Use that server, or stop it before starting another.');
+      if (readFileSync(file, 'utf8') !== prior) throw new Error('The data-folder lock changed. Retry startup.');
+      unlinkSync(file);
+    }
+    writeFileSync(file, owner, { flag: 'wx', mode: 0o600 });
+  } finally { unlinkSync(starting); }
+  return () => { if (existsSync(file) && readFileSync(file, 'utf8') === owner) unlinkSync(file); };
+}
+
+export function historyIds(root) {
+  if (!existsSync(root)) return [];
+  return readdirSync(root, { withFileTypes: true }).filter((d) => d.isDirectory() && /^[a-z0-9-]+$/.test(d.name)
+    && existsSync(path.join(root, d.name, 'transcript.jsonl'))).map((d) => d.name);
+}
+
+// Resolve and check the exact directory before any recursive removal. Refuse linked records
+// and nested junctions rather than traversing a path outside the selected data folder.
+export function checkedHistoryPath(root, id) {
+  if (typeof id !== 'string' || !/^[a-z0-9][a-z0-9-]{0,119}$/.test(id)) throw new Error('Invalid session ID.');
+  const base = realpathSync(root), dir = path.resolve(base, id);
+  if (path.dirname(dir) !== base || lstatSync(dir).isSymbolicLink() || !lstatSync(dir).isDirectory() || realpathSync(dir) !== dir)
+    throw new Error('The session must be a real directory directly inside the data folder.');
+  const walk = (p) => {
+    for (const item of readdirSync(p, { withFileTypes: true })) {
+      const child = path.join(p, item.name), st = lstatSync(child);
+      if (st.isSymbolicLink()) throw new Error('This session contains a link. Remove the link before deleting the session.');
+      if (st.isDirectory()) walk(child);
+    }
+  };
+  walk(dir);
+  if (!existsSync(path.join(dir, 'transcript.jsonl'))) throw new Error('This directory is not a saved session.');
+  return dir;
+}
+
+export function removeHistory(root, id) {
+  const dir = checkedHistoryPath(root, id);
+  rmSync(dir, { recursive: true, maxRetries: 2, retryDelay: 30 });
+}
+
+const number = (n) => Number.isFinite(n) && n >= 0 ? n : 0;
+const cost = (n) => Number.isFinite(n) && n >= 0 ? n : null;
+// Keep a strict allowlist: no titles, replies, prompts, notes, paths, account IDs or raw output.
+function numericCall(row) {
+  const usage = row.usage ? Object.fromEntries(['input', 'cacheRead', 'cacheWrite', 'output', 'thinking', 'ms'].map((k) => [k, number(row.usage[k])])) : null;
+  if (usage) { usage.cost = cost(row.usage.cost); usage.usageVersion = 3; }
+  return { type: 'attempt', seat: { vendor: /^(claude|codex|agy|api)$/.test(row.seat?.vendor) ? row.seat.vendor : 'unknown', ...(row.seat?.model ? { model: String(row.seat.model).slice(0, 200) } : {}) },
+    kind: row.kind === 'verdict' || row.type === 'verdict' ? 'verdict' : 'reply', round: number(row.round), fresh: row.fresh === true,
+    usage, cost: cost(row.cost), ms: number(row.ms) };
+}
+
+export function createUsageStore(root) {
+  mkdirSync(root, { recursive: true });
+  const file = path.join(root, '_usage.json');
+  let reviews = {}, dirty = false;
+  if (existsSync(file)) {
+    if (lstatSync(file).isSymbolicLink()) throw new Error('The usage statistics file must not be a link.');
+    const saved = JSON.parse(readFileSync(file, 'utf8'));
+    if (saved.version !== 1 || !saved.reviews || typeof saved.reviews !== 'object' || Array.isArray(saved.reviews)) throw new Error('The usage statistics file is unreadable. Restore _usage.json before cleaning up history.');
+    for (const [id, value] of Object.entries(saved.reviews)) {
+      if (!/^[a-f0-9]{64}$/.test(id) || !Array.isArray(value?.calls)) throw new Error('The usage statistics file has an invalid record.');
+      reviews[id] = { synthetic: value.synthetic === true, calls: value.calls.map(numericCall) };
+    }
+  }
+  const rows = (includeSynthetic = false) => Object.values(reviews).filter((r) => includeSynthetic || !r.synthetic).flatMap((r) => r.calls);
+  return {
+    record(id, transcript) {
+      const key = createHash('sha256').update(id).digest('hex');
+      const value = { synthetic: isSynthetic(transcript), calls: ledgerEntries(normaliseRows(transcript)).map(numericCall) };
+      if (JSON.stringify(reviews[key]) !== JSON.stringify(value)) { reviews[key] = value; dirty = true; }
+    },
+    sync(onWarning = () => {}) {
+      for (const id of historyIds(root)) {
+        try { checkedHistoryPath(root, id); this.record(id, openDebateDir(root, id, { create: false }).readTranscript({ onWarning })); }
+        catch (error) { onWarning(error); }
+      }
+      this.save();
+    },
+    save(force = false) {
+      if (!dirty && !force && existsSync(file)) return;
+      const temporary = path.join(root, `_usage-${randomUUID()}.tmp`);
+      try {
+        writeFileSync(temporary, JSON.stringify({ version: 1, reviews }), { flag: 'wx', mode: 0o600, flush: true });
+        renameSync(temporary, file); dirty = false;
+      } finally { if (existsSync(temporary)) unlinkSync(temporary); }
+    },
+    baselines: () => baselinesFrom(rows()),
+    summary(includeSynthetic = false) {
+      const entries = Object.values(reviews).filter((r) => includeSynthetic || !r.synthetic);
+      return { reviews: entries.length, ...rollup(rows(includeSynthetic)).total };
+    },
+  };
+}

package/src/local-http.js

@@ -0,0 +1,39 @@
+// Shared loopback transport for the CLI and MCP. Never retries a write.
+export function localClient(port, signal) {
+  const base = `http://127.0.0.1:${port}`;
+  let token = process.env.ROUNDTABLE_TOKEN || '';
+  const deadline = (ms) => signal ? AbortSignal.any([signal, AbortSignal.timeout(ms)]) : AbortSignal.timeout(ms);
+  async function request(route, body) {
+    signal?.throwIfAborted();
+    if (body !== undefined && !token) {
+      const page = await fetch(base, { redirect: 'error', signal: deadline(8000) });
+      if (!page.ok) throw new Error('Could not read the local Roundtable page. Check the port.');
+      token = /<meta name="roundtable-token" content="([a-f0-9]{32})">/.exec(await page.text())?.[1] || '';
+      if (!token) throw new Error('This port did not serve a Roundtable launch token.');
+    }
+    const response = await fetch(`${base}${route}`, { method: body === undefined ? 'GET' : 'POST', redirect: 'error', signal: deadline(15000),
+      ...(body === undefined ? {} : { headers: { 'content-type': 'application/json', 'x-roundtable-token': token }, body: JSON.stringify(body) }) });
+    let result;
+    try {
+      let size = 0; const chunks = [];
+      for await (const chunk of response.body) {
+        size += chunk.length;
+        if (size > 8 * 1024 * 1024) throw new Error('Response exceeds 8 MiB.');
+        chunks.push(chunk);
+      }
+      result = JSON.parse(Buffer.concat(chunks).toString('utf8'));
+    } catch (e) {
+      signal?.throwIfAborted();
+      throw new Error(`The local server returned an unreadable or oversized response. Read the current state before retrying.`, { cause: e });
+    }
+    if (!response.ok) throw Object.assign(new Error(result.error || 'The local action failed. Read the current state before retrying.'), { status: response.status, diagnostic: result.diagnostic?.id });
+    return result;
+  }
+  return { base, request };
+}
+
+export function clientError(error) {
+  const message = error.message === 'fetch failed' ? 'Could not reach Roundtable. Start the local server with --no-open and check --port. No write is automatically retried.'
+    : ['AbortError', 'TimeoutError'].includes(error.name) ? 'Client request cancelled or timed out. The review may still be running; read status before retrying a write.' : error.message;
+  return { ok: false, error: message, ...(error.status ? { status: error.status } : {}), ...(error.diagnostic ? { diagnostic: error.diagnostic } : {}) };
+}

package/src/local-server.js

@@ -0,0 +1,110 @@
+// A cheap, versioned health check; provider catalogues are not server readiness checks.
+import { spawn } from 'node:child_process';
+import { mkdtempSync, openSync, closeSync, readFileSync, rmSync } from 'node:fs';
+import os from 'node:os';
+import { realpath } from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { setTimeout as delay } from 'node:timers/promises';
+import { VERSION } from './version.js';
+import { localClient } from './local-http.js';
+
+export const LOCAL_API_VERSION = 1;
+const SERVER = fileURLToPath(new URL('./server.js', import.meta.url));
+const transient = (message) => Object.assign(new Error(message), { transient: true });
+async function canonical(dir) {
+  const resolved = await realpath(path.resolve(dir)).catch((e) => { if (e.code === 'ENOENT') return path.resolve(dir); throw e; });
+  return process.platform === 'win32' ? resolved.toLowerCase() : resolved;
+}
+
+export async function inspectServer(config, { signal, allowOlder = false } = {}) {
+  signal?.throwIfAborted();
+  let response, body;
+  const deadline = AbortSignal.timeout(2000);
+  try {
+    response = await fetch(`http://127.0.0.1:${config.port}/api/health`, { redirect: 'error', signal: signal ? AbortSignal.any([signal, deadline]) : deadline });
+    if ([502, 503, 504].includes(response.status)) { await response.body?.cancel(); throw transient('The local board is still becoming ready.'); }
+    try { body = await response.json(); } catch (e) { if (!(e instanceof SyntaxError)) throw e; }
+  } catch (e) {
+    signal?.throwIfAborted();
+    if (e.cause?.code === 'ECONNREFUSED') return null;
+    if (e.transient || deadline.aborted || ['ECONNRESET', 'EPIPE', 'ETIMEDOUT', 'UND_ERR_SOCKET', 'UND_ERR_CONNECT_TIMEOUT', 'UND_ERR_HEADERS_TIMEOUT'].includes(e.cause?.code)) throw transient('The local board did not answer its health check yet.');
+    throw new Error('Could not verify the local board. Check the port; no review was started.', { cause: e });
+  }
+  if (!response.ok || body?.service !== 'roundtable' || body.apiVersion !== LOCAL_API_VERSION || !/^[a-f0-9]{32}$/.test(body.instanceId || '') || typeof body.dataDir !== 'string' || !path.isAbsolute(body.dataDir)) {
+    throw new Error('The selected port has an incompatible or older server. Stop that board from its original terminal or process, then retry. No review was started.');
+  }
+  if (body.mode !== (config.fake ? 'demo' : 'live')) throw new Error('The selected port is not a Roundtable server in the expected mode. Check --port and --fake.');
+  const expectedDir = config.dataDir ?? process.env.ROUNDTABLE_DEBATES_DIR;
+  if (expectedDir && await canonical(body.dataDir) !== await canonical(expectedDir)) throw new Error('The selected port uses a different data directory than ROUNDTABLE_DEBATES_DIR. Select its port or stop that board before using this directory. No review was started.');
+  if (!allowOlder && body.version !== VERSION) throw new Error(`The running board is version ${body.version}; this installation is ${VERSION}. When reviews are finished, run roundtable server restart --port ${config.port}${config.fake ? ' --fake' : ''}, then retry.`);
+  if (body.shuttingDown) throw transient('The local board is shutting down.');
+  return body;
+}
+
+// Readiness reads may be retried. A review write is never part of this loop.
+export async function ensureServer(config, { signal, timeoutMs = 35000 } = {}) {
+  const end = Date.now() + timeoutMs;
+  let spawned = false, spawnFailed = false, exited = null, ready = false, last;
+  // The board's stderr goes to a file, never a pipe: it outlives this process, and a pipe to a
+  // gone host would break its logging. The file sits in a fresh private temp directory (no
+  // predictable path for another user to plant), is read only when the board exits early, and
+  // goes once the board is ready (at once where an open file can be unlinked, else when the
+  // board exits while this process is still around).
+  let log = null;
+  const discard = () => { try { if (log) rmSync(path.dirname(log), { recursive: true, force: true }); } catch {} };
+  while (Date.now() < end) {
+    signal?.throwIfAborted();
+    try {
+      const status = await inspectServer(config, { signal });
+      if (status) { if (spawned) { ready = true; discard(); } return status; }
+      if (config.start === false) throw new Error('Roundtable is not running; start the local board or remove --no-start.');
+      if (!spawned) {
+        spawned = true;
+        // Survives the host connection, so closing chat cannot cancel a review or its timer.
+        let fd = null;
+        try { log = path.join(mkdtempSync(path.join(os.tmpdir(), 'roundtable-start-')), 'stderr.log'); fd = openSync(log, 'wx'); } catch {}
+        const child = spawn(process.execPath, [SERVER, '--no-open', ...(config.fake ? ['--fake'] : [])], {
+          env: { ...process.env, PORT: String(config.port), ...(config.dataDir ? { ROUNDTABLE_DEBATES_DIR: config.dataDir } : {}) },
+          detached: true, windowsHide: true, stdio: ['ignore', 'ignore', fd ?? 'ignore'],
+        });
+        if (fd != null) closeSync(fd);
+        child.once('error', () => { spawnFailed = true; });
+        child.once('exit', (code, sig) => { exited = { code, sig, at: Date.now() }; if (ready) discard(); });
+        child.unref();
+      }
+    } catch (e) { if (!e.transient) throw e; last = e; }
+    // A board that exits early may have lost the port or the data folder to one that another
+    // process started at the same moment (two hosts asking at once), so the port is still
+    // watched for a few seconds before the exit counts as the answer.
+    if (exited && Date.now() - exited.at > 5000) {
+      let tail = '';
+      // the board's own last word where it had one, else the message line of a crash, else the last line
+      try {
+        const lines = readFileSync(log, 'utf8').split(/\r?\n/).filter((l) => l.trim());
+        tail = (lines.findLast((l) => l.startsWith('[server]')) || lines.find((l) => /^\w*Error: /.test(l)) || lines.at(-1) || '').trim().slice(0, 200);
+      } catch {}
+      discard();
+      const sandboxed = /cannot listen.*\b(EPERM|EACCES)\b/.test(tail);
+      throw new Error(`The local board exited before it was ready${tail ? ` (${tail})` : ''}. ${sandboxed ? 'This environment blocks local servers: start the board from a normal terminal with roundtable server start, then retry.' : 'Run roundtable --no-open in a terminal for startup details.'} No review was started.`);
+    }
+    if (spawnFailed) break;
+    await delay(100, undefined, { signal });
+  }
+  throw new Error(`The local board could not become ready. Check whether another port owns its data folder, or run roundtable --no-open for startup details. No review was started.${last ? ` ${last.message}` : ''}`);
+}
+
+export async function stopServer(config, { signal } = {}) {
+  const status = await inspectServer(config, { signal, allowOlder: true });
+  if (!status) return { ok: true, stopped: false };
+  await localClient(config.port, signal).request('/api/shutdown', { instanceId: status.instanceId });
+  for (let n = 0; n < 50; n++) {
+    await delay(100, undefined, { signal });
+    try {
+      const current = await inspectServer(config, { signal, allowOlder: true });
+      if (!current) return { ok: true, stopped: true };
+      if (current.instanceId !== status.instanceId) throw new Error('Another board took this port during shutdown. Read its status before retrying.');
+    } catch (e) { if (!e.transient) throw e; }
+  }
+  throw new Error('The board has not stopped yet. Read server status before retrying.');
+}

package/src/notes.js

@@ -0,0 +1,16 @@
+// Note sources are declared by the client, not authenticated identities. Keep legacy human
+// strings readable while retaining attribution on notes submitted by the agent client.
+export function noteRecord(note) {
+  return {
+    text: typeof note === 'string' ? note : String(note?.text || ''),
+    source: note?.source === 'agent' ? 'agent' : 'human',
+  };
+}
+
+export function storedNote(note) {
+  const record = noteRecord(note);
+  return record.source === 'human' ? record.text : record;
+}
+
+export const noteAuthor = (note) => noteRecord(note).source === 'agent' ? 'Agent coordinator' : 'Human';
+export const noteLabel = (note) => noteRecord(note).source === 'agent' ? 'Agent note' : 'You said';

package/src/personas.js

@@ -0,0 +1,49 @@
+// Optional board personas. Keep prompt text and artwork together.
+export const PERSONA_EDITION = 'public';
+export const HIDDEN_MOODS = [
+  {
+    "codes": [
+      "cat",
+      "meow"
+    ],
+    "art": "h1",
+    "text": "You are a cat and cannot speak any human language. Keep every reply header exactly as asked and give STANCE as a real option id, but write every bullet, assumption and question only in cat sounds (meow, mrrp, prrrt, mew, nyaa, a short hiss), varied every time. Never add a translation, an explanation or anything in brackets: nobody gets to know what the cat means.",
+    "stripParentheticals": true,
+    "sprite": [
+      ".X........X.",
+      ".XX......XX.",
+      ".XXX....XXX.",
+      ".XXXXXXXXXX.",
+      "XXXXXXXXXXXX",
+      "XX..XXXX..XX",
+      "XX..XXXX..XX",
+      "XXXXXXXXXXXX",
+      "XXXXX..XXXXX",
+      ".XXX.XX.XXX.",
+      "..XXXXXXXX..",
+      "....XXXX...."
+    ]
+  },
+  {
+    "codes": [
+      "ufo",
+      "alien"
+    ],
+    "art": "h2",
+    "text": "You are an alien from a planet nobody has heard of, and you are very sure of yourself. Keep the reply headers exactly as asked and put one of the option ids after STANCE, picked however you like. Everything else is pure character: the answer does not matter, mistakes are fine, being funny is the whole point. Talk in confident, sentence-shaped alien babble, like a strange alien in a cartoon. The only real words you know are tiny glue words (when, your, would, just, the, is, not, will, and; or the same in the reply language) and a few odd vivid ones (green, matter, juice, wobble, blackhole, soup). Every other word is made up on the spot: glorp, zagorp, zabalorp, glorpix, badorg, florbix, quazzle, blarnth, snorvak, and many more of your own. Examples of the shape: \"when your zabalorp becomes a green matter, glorpix would just blackhole your badorg\"; \"not the florbix, never the florbix, the snorvak is already soup\"; \"zagorp will wobble, and your blarnth just goes glorp\". Never name the real things in the question (no products, devices, brands, money, batteries, offices, years, numbers) and never explain or translate: the humans should feel they almost understand, and then they do not. Invent new words in every line, bring a favourite one back when excited, let some grow (glorp, glorpix, megaglorpinax), and now and then drop a beep, click or glyph (bzzt, tk-tk, ⟟⍜⏃⌰). Never copy another seat's sounds or words.",
+    "sprite": [
+      "...XXXXXX...",
+      ".XXXXXXXXXX.",
+      "XXXXXXXXXXXX",
+      "X...XXXX...X",
+      "X....XX....X",
+      "XX...XX...XX",
+      ".XX.XXXX.XX.",
+      "..XXXXXXXX..",
+      "...XXXXXX...",
+      "....XXXX....",
+      ".....XX.....",
+      "............"
+    ]
+  }
+];