@prplkane/roundtable 0.0.0-stage → 0.6.4

package/src/estimate.js

@@ -0,0 +1,331 @@
+// The quota picture: how much a table is likely to draw from each vendor's pool, and how the
+// measured windows move per round. Pure, so it runs in the browser and in tests.
+//
+// Baselines come from this machine's own transcripts (tokens per call, fresh round-0 calls and
+// resumed later calls separately). Effort multipliers are guesses until measured deltas replace
+// them; they live here and nowhere else.
+import { quotaGroup } from './adapters/models.js';
+
+export const EFFORT_MULTIPLIER = { low: 0.7, medium: 1, high: 1.4, xhigh: 1.8, ultra: 2.2, max: 2.6 };
+
+export function unknownUsageMessage(cause) {
+  const first = cause === 'timeout' ? 'An earlier call timed out before reporting token usage.'
+    : cause === 'network' ? 'An earlier call lost its connection before reporting token usage.'
+    : ['killed', 'interrupted'].includes(cause) ? 'An earlier call was interrupted before reporting token usage.'
+    : 'An earlier call did not report complete token usage.';
+  return `${first} Further calls are blocked because spending is unknown. Check the earlier failure and provider usage before starting more work.`;
+}
+
+// How much of a vendor's pool one token of a model draws, relative to the vendor's heaviest
+// model (1). Guesses from list-price ratios: Opus : Sonnet : Haiku about 1 : 0.2 : 0.05;
+// Gemini Pro-class : Flash about 1 : 0.2. An id that matches nothing weighs 1 (the safe side).
+// A per-model calibration, once measured, replaces the weight (projectedWindows).
+export const MODEL_WEIGHT = [
+  [/haiku/i, 0.05], [/sonnet/i, 0.2], [/opus/i, 1],
+  [/flash/i, 0.2], [/argon|pro\b/i, 1], [/gpt-oss/i, 0.1],
+  [/mini|nano/i, 0.2],
+];
+export function modelWeight(model) {
+  if (!model) return 1;
+  for (const [re, w] of MODEL_WEIGHT) if (re.test(model)) return w;
+  return 1;
+}
+// Used before any transcript exists. Taken from real debates; replaced by this machine's own medians as soon as it has some.
+export const FALLBACK = {
+  claude: { fresh: { input: 13000, output: 1500 }, resumed: { input: 9500, output: 1200 } },
+  codex: { fresh: { input: 18000, output: 1200 }, resumed: { input: 34000, output: 1000 } },
+  agy: { fresh: { input: 13000, output: 1300 }, resumed: { input: 30000, output: 1200 } },
+};
+const GENERIC = { fresh: { input: 15000, output: 1300 }, resumed: { input: 25000, output: 1100 } };
+const CHAIRMAN_INPUT_FACTOR = 1.6; // the chairman reads the whole transcript in one fresh call
+
+// Setup has no source bundle yet. Reserve an allowance per discussion/verdict call; after
+// research, use the saved bundle's UTF-8 size at three bytes per estimated input token.
+// This adds conservatism to historical baselines, not a tokenizer or a billing ceiling.
+export const RESEARCH_INPUT_RESERVE = 12000;
+export function researchInputTokens(sources = null) {
+  if (!Array.isArray(sources)) return RESEARCH_INPUT_RESERVE;
+  if (!sources.length) return 0;
+  const records = sources.map(({ id, url, title, excerpt, publishedAt, gatheredAt }) =>
+    JSON.stringify({ kind: 'web_source', id, url, title, publishedAt, gatheredAt, text: excerpt })
+      .replace(/[\u0085\u2028\u2029]/g, (c) => `\\u${c.charCodeAt(0).toString(16).padStart(4, '0')}`));
+  return Math.ceil(new TextEncoder().encode(records.join('\n')).length / 3);
+}
+const evidenceCost = (cost, baseline, tokens) => cost == null ? 0 : cost * 0.8 * tokens / baseline.input;
+
+// median for dollar figures, kept to the cent
+function median100(xs) { return Math.round(median(xs.map((x) => x * 100))) / 100; }
+
+function median(xs) {
+  if (!xs.length) return 0;
+  const s = [...xs].sort((a, b) => a - b);
+  const m = Math.floor(s.length / 2);
+  return s.length % 2 ? s[m] : Math.round((s[m - 1] + s[m]) / 2);
+}
+
+// Transcript rows (any number of debates) -> per-vendor medians per call.
+export function baselinesFrom(rows) {
+  const acc = {};
+  for (const r of rows || []) {
+    if (r.kind === 'research') continue; // web evidence gathering has a different context size
+    if (!r.usage || !r.seat?.vendor) continue;
+    if (r.type !== 'reply' && r.type !== 'verdict' && r.type !== 'attempt') continue;
+    // a call the server refused before the model ran (an endpoint's 429) reports zero tokens: known
+    // spending for the caps, but no sample of what a call costs
+    if (!((r.usage.input || 0) + (r.usage.cacheRead || 0) + (r.usage.cacheWrite || 0) + (r.usage.output || 0))) continue;
+    if (typeof r.sessionId === 'string' && r.sessionId.startsWith('fake-')) continue; // a scripted seat
+    // Rows since 0.2.0 say whether the call resumed a session; older rows are fresh at round 0 only.
+    const kind = r.type === 'verdict' || r.kind === 'verdict' || r.round === 0 || r.fresh === true ? 'fresh' : 'resumed';
+    const v = (acc[r.seat.vendor] ??= { fresh: { input: [], output: [], cost: [] }, resumed: { input: [], output: [], cost: [] } });
+    v[kind].input.push((r.usage.input || 0) + (r.usage.cacheRead || 0) + (r.usage.cacheWrite || 0));
+    v[kind].output.push((r.usage.output || 0));
+    // Cost in the vendor's own currency where the CLI reports it (claude: total_cost_usd per
+    // call, exact and without lag). Kept per model too, since cost is where models differ most.
+    if (typeof r.usage.cost === 'number') {
+      v[kind].cost.push(r.usage.cost);
+      const m = (acc[`${r.seat.vendor}:${r.seat.model || 'default'}`] ??= { fresh: { input: [], output: [], cost: [] }, resumed: { input: [], output: [], cost: [] } });
+      m[kind].cost.push(r.usage.cost);
+    }
+  }
+  const out = {};
+  for (const [vendor, v] of Object.entries(acc)) {
+    out[vendor] = {};
+    for (const kind of ['fresh', 'resumed']) {
+      out[vendor][kind] = { input: median(v[kind].input), output: median(v[kind].output), n: v[kind].input.length, cost: v[kind].cost.length ? median100(v[kind].cost) : null, nCost: v[kind].cost.length };
+    }
+  }
+  return out;
+}
+
+function baseFor(vendor, kind, baselines) {
+  const b = baselines?.[vendor]?.[kind];
+  if (b && b.n > 0 && b.input > 0) return b;
+  return (FALLBACK[vendor] || GENERIC)[kind];
+}
+
+// Projection for one debate: every seat answers round 0 fresh and every critique
+// round fresh again (memory 'stateless', the default) or resumed ('resume'); the chairman makes
+// one long fresh call. Effort scales output tokens only.
+export function project({ seats, chairman, critiqueRounds = 3, baselines = {}, memory = 'stateless', research = null, sources = null }) {
+  const bySeat = {}, byVendor = {};
+  const extra = research ? researchInputTokens(sources) : 0;
+  const add = (vendor, id, calls, model) => {
+    const sum = calls.reduce((a, c) => ({ input: a.input + c.input, output: a.output + c.output }), { input: 0, output: 0 });
+    const weight = modelWeight(model);
+    const total = Math.round(sum.input + sum.output);
+    // `weighted`: pool units, tokens times the model's weight; the pool bar and window share use it.
+    const cost = calls.every((c) => typeof c.cost === 'number') ? Math.round(calls.reduce((a, c) => a + c.cost, 0) * 100) / 100 : null;
+    const row = { vendor, id, model: model || null, weight, calls: calls.length, input: Math.round(sum.input), output: Math.round(sum.output), total, weighted: Math.round(total * weight), cost };
+    bySeat[id] = row;
+    const v = (byVendor[vendor] ??= { vendor, input: 0, output: 0, total: 0, weighted: 0, cost: null, seats: [] });
+    v.input += row.input; v.output += row.output; v.total += row.total; v.weighted += row.weighted; v.seats.push(id);
+    if (row.cost != null) v.cost = Math.round(((v.cost || 0) + row.cost) * 100) / 100;
+  };
+  // Dollar cost per call: the model's own median when measured, else the vendor's, scaled by the
+  // effort multiplier on the output share only (prompt tokens are the bulk of a call's cost).
+  const costFor = (vendor, model, kind) => {
+    const own = baselines?.[`${vendor}:${model || 'default'}`]?.[kind];
+    const b = (own?.nCost > 0 ? own : baselines?.[vendor]?.[kind]);
+    return b && b.nCost > 0 ? b.cost : null;
+  };
+  for (const s of seats || []) {
+    const m = EFFORT_MULTIPLIER[s.effort] ?? 1;
+    const fresh = baseFor(s.vendor, 'fresh', baselines), resumed = baseFor(s.vendor, 'resumed', baselines);
+    const cf = costFor(s.vendor, s.model, 'fresh'), cr = costFor(s.vendor, s.model, 'resumed');
+    const calls = [{ input: fresh.input + extra, output: fresh.output * m, cost: cf == null ? undefined : cf * (0.8 + 0.2 * m) + evidenceCost(cf, fresh, extra) }];
+    const later = memory === 'resume' ? { b: resumed, c: cr } : { b: fresh, c: cf };
+    for (let r = 0; r < critiqueRounds; r++) calls.push({ input: later.b.input + extra, output: later.b.output * m, cost: later.c == null ? undefined : later.c * (0.8 + 0.2 * m) + evidenceCost(later.c, later.b, extra) });
+    add(s.vendor, s.id, calls, s.model);
+  }
+  if (chairman?.vendor) {
+    const m = EFFORT_MULTIPLIER[chairman.effort] ?? 1;
+    const fresh = baseFor(chairman.vendor, 'fresh', baselines);
+    const cc = costFor(chairman.vendor, chairman.model, 'fresh');
+    add(chairman.vendor, 'chairman', [{ input: fresh.input * CHAIRMAN_INPUT_FACTOR + extra, output: fresh.output * 1.5 * m, cost: cc == null ? undefined : cc * CHAIRMAN_INPUT_FACTOR + evidenceCost(cc, fresh, extra) }], chairman.model);
+  }
+  if (research) {
+    const selected = typeof research === 'object' ? research : {}; // the searcher's own vendor, model and effort
+    const vendor = selected.vendor || 'codex';
+    const fresh = baseFor(vendor, 'fresh', baselines), m = EFFORT_MULTIPLIER[selected.effort] ?? 1;
+    add(vendor, 'research', [{ input: fresh.input * CHAIRMAN_INPUT_FACTOR, output: fresh.output * 1.5 * m }], selected.model);
+  }
+  const total = Object.values(byVendor).reduce((a, v) => a + v.total, 0);
+  return { bySeat, byVendor, total, critiqueRounds };
+}
+
+// Two quota snapshots of one vendor -> per-window change. A window whose reset time moved has
+// rolled over in between, so its delta is meaningless and marked invalid.
+// Two readings of one window can give its reset a minute apart: Claude's /usage prints the time to
+// the minute and rounds it differently from one read to the next ("4:59am", then "5am"), and its
+// reply gives the exact second. A rollover moves the reset by hours, so a few minutes is the same
+// window.
+const SAME_RESET_S = 300;
+export function windowDeltas(prev, next) {
+  if (!prev?.windows || !next?.windows) return [];
+  return next.windows.map((w) => {
+    const p = prev.windows.find((x) => x.label === w.label);
+    if (!p) return { label: w.label, delta: 0, valid: false };
+    const a = p.resetsAt ?? null, b = w.resetsAt ?? null;
+    const sameWindow = a == null || b == null ? a === b : Math.abs(a - b) <= SAME_RESET_S;
+    const delta = w.used - p.used;
+    return { label: w.label, delta, valid: sameWindow && delta >= 0 };
+  });
+}
+
+// What one round of one pool can measure: its window deltas and the calibration keys they feed,
+// the pool's and, when the round ran one model, `pool:model`. models: the Set of models it ran.
+// A quota in groups (agy) moves only the windows of the group a model draws on, and the other
+// groups standing still says nothing about these tokens. So only a one-model round is measured
+// there, only on that model's group, and only under the model's key: a pool-wide rate would be
+// projected onto every group.
+export function roundDeltas(prev, next, pool, models) {
+  const deltas = windowDeltas(prev, next);
+  const model = models?.size === 1 ? [...models][0] : null;
+  if (!next?.groups?.length) return { deltas, keys: model ? [pool, `${pool}:${model}`] : [pool] };
+  const group = model && quotaGroup(next.groups, model);
+  if (!group) return { deltas: [], keys: [] };
+  const own = new Set(next.windows.filter((w) => w.group === group).map((w) => w.label));
+  return { deltas: deltas.filter((d) => own.has(d.label)), keys: [`${pool}:${model}`] };
+}
+
+// Vendors report window usage in whole percentage points and, at least for Claude, with a lag:
+// a round rarely moves a window, and a move often lands a debate later. So the calibration is
+// long-run: every valid round adds its tokens and its movement to one running total per key and
+// window, and the rate is total movement over total tokens. Until the total has moved at all, the
+// figure is a ceiling (less than one point per every token seen) that tightens with each token.
+// A rolled-over window (reset time moved) contributes nothing for that round; the totals stand.
+export const WINDOW_RESOLUTION = 0.01;
+
+// calib: { [key]: { [label]: entry } }, key = vendor or vendor:model, entry =
+//   { moved, tokens, rounds, samples, pctPerToken, pending, ceilPerToken, pctPerRound }
+//   moved        total window movement seen (fraction of the window)
+//   tokens       total tokens behind that movement
+//   samples      rounds in which a whole-point move landed
+//   pctPerToken  moved / tokens once moved > 0, else 0
+//   pending      alias of tokens while unmoved (what the UI reports the ceiling over)
+//   ceilPerToken resolution / tokens while unmoved
+//   pctPerRound  mean movement per round (the pool row's coarse figure)
+export function updateCalibration(calib, key, deltas, tokens, { resolution = WINDOW_RESOLUTION } = {}) {
+  const out = { ...calib, [key]: { ...(calib?.[key] || {}) } };
+  for (const d of deltas) {
+    if (!(tokens > 0) || !d.valid) continue;
+    const prev = out[key][d.label] || { moved: 0, tokens: 0, rounds: 0, samples: 0, pctPerRound: 0 };
+    const moved = prev.moved + d.delta, total = prev.tokens + tokens, rounds = prev.rounds + 1;
+    const samples = prev.samples + (d.delta >= resolution ? 1 : 0);
+    out[key][d.label] = {
+      moved, tokens: total, rounds, samples,
+      pctPerToken: moved > 0 ? moved / total : 0,
+      pending: moved > 0 ? 0 : total,
+      ceilPerToken: moved > 0 ? null : resolution / total,
+      pctPerRound: prev.pctPerRound + (d.delta - prev.pctPerRound) / rounds,
+    };
+  }
+  return out;
+}
+
+// What one entry says a token costs: a measurement, or a ceiling, or nothing yet.
+function rate(entry) {
+  if (!entry) return null;
+  if (entry.moved > 0 || entry.samples > 0) return { perToken: entry.pctPerToken, upperBound: false, samples: entry.samples, tokens: entry.tokens };
+  if (entry.ceilPerToken) return { perToken: entry.ceilPerToken, upperBound: true, samples: 0, pending: entry.pending };
+  return null;
+}
+
+// Projected share of each window for one vendor's seats. calib is the whole calibration map,
+// keyed `vendor` and `vendor:model`. A seat uses its model's own measurement when one exists,
+// otherwise the vendor's measurement scaled by the model weight. null when nothing is measured.
+export function projectedWindows(calib, vendor, seatRows) {
+  const base = calib?.[vendor];
+  const labels = new Set();
+  for (const key of Object.keys(calib || {})) if (key === vendor || key.startsWith(`${vendor}:`)) for (const l of Object.keys(calib[key])) labels.add(l);
+  if (!labels.size) return null;
+  const out = [];
+  for (const label of labels) {
+    let pct = 0, samples = 0, any = false, upperBound = false, pending = 0;
+    for (const row of seatRows || []) {
+      // The model's own measurement wins. Otherwise the vendor's rate times the model weight,
+      // capped by the model's own ceiling when that ceiling is the lower figure.
+      const own = rate(calib?.[`${vendor}:${row.model || 'default'}`]?.[label]);
+      const b = rate(base?.[label]);
+      let pick = null;
+      if (own && !own.upperBound) pick = { ...own, weight: 1 };
+      else if (b && !b.upperBound) {
+        const weighted = b.perToken * (row.weight ?? modelWeight(row.model));
+        pick = own && own.perToken < weighted ? { ...own, weight: 1 } : { ...b, weight: row.weight ?? modelWeight(row.model) };
+      } else if (own || b) {
+        const o = own ? own.perToken : Infinity, v = b ? b.perToken * (row.weight ?? modelWeight(row.model)) : Infinity;
+        pick = o <= v ? { ...own, weight: 1 } : { ...b, weight: row.weight ?? modelWeight(row.model) };
+      }
+      if (!pick) continue;
+      pct += pick.perToken * row.total * pick.weight; samples += pick.samples; any = true;
+      upperBound ||= pick.upperBound; pending = Math.max(pending, pick.pending || 0);
+    }
+    // upperBound: the window has not moved a whole point over `pending` tokens, so the figure is
+    // "less than this", tightening as tokens accumulate; otherwise it is a measurement.
+    if (any) out.push({ label, pct, samples, upperBound, pending });
+  }
+  return out.length ? out : null;
+}
+
+// What one round is likely to draw per vendor, before it runs: each seat's fresh or resumed
+// baseline (fresh at round 0 and in stateless memory), effort on the output share. Used by the
+// engine's budget gate. Returns { [vendor]: { tokens, cost|null, seats } }.
+export function projectRound({ seats, round, baselines = {}, memory = 'stateless', researchTokens = 0 }) {
+  const out = {};
+  for (const s of seats || []) {
+    const kind = round === 0 || memory !== 'resume' ? 'fresh' : 'resumed';
+    const b = baseFor(s.vendor, kind, baselines);
+    const m = EFFORT_MULTIPLIER[s.effort] ?? 1;
+    const own = baselines?.[`${s.vendor}:${s.model || 'default'}`]?.[kind];
+    const cb = own?.nCost > 0 ? own : baselines?.[s.vendor]?.[kind];
+    const cost = cb && cb.nCost > 0 ? cb.cost * (0.8 + 0.2 * m) + evidenceCost(cb.cost, b, researchTokens) : null;
+    const v = (out[s.vendor] ??= { tokens: 0, cost: null, seats: 0 });
+    v.tokens += Math.round(b.input + researchTokens + b.output * m);
+    v.seats++;
+    if (cost != null) v.cost = Math.round(((v.cost || 0) + cost) * 100) / 100;
+  }
+  return out;
+}
+
+// The chairman's one long fresh call, same units.
+export function projectChairman({ chairman, baselines = {}, researchTokens = 0 }) {
+  if (!chairman?.vendor) return {};
+  const b = baseFor(chairman.vendor, 'fresh', baselines);
+  const m = EFFORT_MULTIPLIER[chairman.effort] ?? 1;
+  const own = baselines?.[`${chairman.vendor}:${chairman.model || 'default'}`]?.fresh;
+  const cb = own?.nCost > 0 ? own : baselines?.[chairman.vendor]?.fresh;
+  const cost = cb && cb.nCost > 0 ? Math.round((cb.cost * CHAIRMAN_INPUT_FACTOR + evidenceCost(cb.cost, b, researchTokens)) * 100) / 100 : null;
+  return { [chairman.vendor]: { tokens: Math.round(b.input * CHAIRMAN_INPUT_FACTOR + researchTokens + b.output * 1.5 * m), cost, seats: 1 } };
+}
+
+// Would running `next` ({vendor: {tokens, cost}}) on top of `spent` cross `budget`
+// ({vendor: {tokens?, usd?}})? Returns the first crossing, or null.
+export function budgetCheck(budget, spent, next) {
+  for (const [vendor, cap] of Object.entries(budget || {})) {
+    if (!cap) continue;
+    // No new call to this vendor adds zero cost. An actual call whose projection is unknown
+    // still carries cost: null and must be refused under a dollar cap.
+    const s = spent?.[vendor] || { tokens: 0, cost: 0 }, n = next?.[vendor] || { tokens: 0, cost: 0 };
+    if (cap.tokens > 0 && s.tokensUnknown && next?.[vendor]) return { vendor, kind: 'tokens-unknown', spent: s.tokens, projected: n.tokens, cap: cap.tokens };
+    if (cap.tokens > 0 && s.tokens + n.tokens > cap.tokens) return { vendor, kind: 'tokens', spent: s.tokens, projected: n.tokens, cap: cap.tokens };
+    // A dollar cap cannot be checked against a cost nobody reported: that is a crossing of its
+    // own kind, not a zero.
+    if (cap.usd > 0 && (s.costUnknown || n.cost == null)) return { vendor, kind: 'usd-unknown', spent: Math.round((s.cost || 0) * 100) / 100, projected: n.cost ?? null, cap: cap.usd };
+    if (cap.usd > 0 && (s.cost || 0) + (n.cost || 0) > cap.usd) return { vendor, kind: 'usd', spent: Math.round((s.cost || 0) * 100) / 100, projected: n.cost, cap: cap.usd };
+  }
+  return null;
+}
+
+// Calibration on disk divides a window's move by the tokens a round spent. Before usage version 3
+// a 'subset' vendor's tokens counted its cached input twice (Codex), so its rates are too low:
+// drop those entries (the vendor and its vendor:model keys) once, and mark the file version 3.
+// Entries for other vendors measured the same tokens then as now and are kept.
+export const CALIBRATION_VERSION = 3;
+export function migrateCalibration(file, { subsetVendors = [] } = {}) {
+  if (!file || typeof file !== 'object') return { calibration: {}, dropped: [] };
+  const { _version, ...entries } = file;
+  if (_version >= CALIBRATION_VERSION) return { calibration: entries, dropped: [] };
+  const dropped = Object.keys(entries).filter((k) => subsetVendors.includes(k.split('@')[0].split(':')[0]));
+  for (const k of dropped) delete entries[k];
+  return { calibration: entries, dropped };
+}

package/src/export.js

@@ -0,0 +1,307 @@
+// Decision records: one plain-markdown file per debate, written into a codebase so an agent
+// that can read the repo (sandboxed or not) can read what was decided and why, plus an index
+// README.md listing every record. Pure functions over transcript rows, plus two file writers.
+//
+//   decisionRecord(rows, slug)       -> { markdown, meta }            (pure)
+//   updateIndex(existing, meta)      -> new index text, or null when the file is not ours (pure)
+//   validateTarget(target)           -> absolute path of an existing directory, or throws
+//   exportDebate(rows, slug, target) -> { path, indexPath, meta }     (writes both files)
+//
+// The exporter writes only into files it can prove it wrote: a record whose front matter names
+// this slug under `roundtable:`, and an index region between two marker comments. Everything
+// outside the region is kept byte for byte; any other file in the way is refused, never
+// replaced.
+import { existsSync, statSync, lstatSync, realpathSync, readFileSync, writeFileSync, openSync, closeSync, fchmodSync, renameSync, unlinkSync } from 'node:fs';
+import { randomUUID } from 'node:crypto';
+import os from 'node:os';
+import path from 'node:path';
+import { rebuildDebate, normaliseRows } from './store.js';
+import { rollup } from './engine.js';
+import { optionIds, optionId, optionLabel, recommendationPick, verdictSections, VERDICT_HEADERS } from './contract.js';
+import { normLabel } from './validate.js';
+import { noteRecord, noteAuthor } from './notes.js';
+
+// The chairman's sections, same tolerance as the board (markdown emphasis around the header).
+export function parseVerdict(text) {
+  const sections = verdictSections(text);
+  const out = {};
+  for (const h of VERDICT_HEADERS) out[h] = (sections[h] || []).map((l) => l.trim()).filter(Boolean).join('\n');
+  out.parsed = Object.keys(sections).length > 0;
+  return out;
+}
+
+// A 0.2.0 verdict has no grammar line. Its first line counts only when it begins with one exact
+// option label followed by punctuation or nothing ("Ship now, on balance."), longest label first,
+// so "Ship later, ..." never reads as "Ship" and "Do not use Postgres" never reads as Postgres.
+function leadingOption(line, options) {
+  const s = normLabel(line || '');
+  for (const o of [...optionIds(options)].sort((a, b) => b.label.length - a.label.length)) {
+    const l = normLabel(o.label);
+    if (s === l || (s.startsWith(l) && /^[\s]*[,.;:!?(\u2014\u2013-]/.test(s.slice(l.length)))) return o.id;
+  }
+  return null;
+}
+
+// Which option the debate chose, as its label:
+// - the option on the recommendation's first line;
+// - 'no pick' when the chairman wrote none: an abstention is never filled in from the seats;
+// - for a legacy verdict (no grammar) or a missing one, the option every seat ended on, and only
+//   when every seat has an eligible final stance;
+// - otherwise 'no consensus'. Substring presence never counts.
+// finalStances: one per seat, an option id or label, or null for a seat with no eligible stance.
+export function chosenOption(options, recommendation, finalStances, { legacy = true } = {}) {
+  const first = String(recommendation || '').split(/\r?\n/).find((l) => l.trim()) || '';
+  const pick = recommendationPick(first, options) ?? (legacy ? leadingOption(first, options) : null);
+  if (pick === 'none') return 'no pick';
+  if (pick) return optionLabel(pick, options);
+  if (!legacy) return 'no consensus';
+  const ids = finalStances.map((s) => (s == null ? null : optionId(s, options)));
+  if (ids.length && ids.every(Boolean) && new Set(ids).size === 1) return optionLabel(ids[0], options);
+  return 'no consensus';
+}
+
+const STOPPED = new Set(['human', 'wall-clock', 'budget', 'all-failed', 'seats-down']);
+const yaml = (v) => (typeof v === 'string' && /[:#"'\n]|^\s|\s$/.test(v) ? JSON.stringify(v) : String(v));
+const k = (n) => (n || 0).toLocaleString('en-US');
+
+export function decisionRecord(rows, slug, { warnings = [], metadataOnly = false } = {}) {
+  rows = normaliseRows(rows);
+  const rb = rebuildDebate(rows);
+  if (!rb) throw new Error('No field-notes row: nothing to export.');
+  const fn = rb.fieldNotes;
+  const options = fn.options || [];
+  const verdictRow = rb.verdict;
+  const v = parseVerdict(verdictRow?.skipped ? '' : verdictRow?.text);
+  const date = (rows.find((r) => r.t)?.t || new Date().toISOString()).slice(0, 10);
+  const seats = rb.seats;
+  const finalRound = rb.rounds.length - 1;
+  // A seat's final stance: its last reply's, where only a PASS carries an earlier stance forward.
+  // A failed or off-contract last reply leaves the seat with no eligible stance (null).
+  const finalStance = (seat) => {
+    for (let i = finalRound; i >= 0; i--) {
+      const r = rb.rounds[i]?.find((x) => (x.seat.id ?? `${x.seat.vendor}:${x.seat.lens}`) === (seat.id ?? `${seat.vendor}:${seat.lens}`));
+      if (!r) continue;
+      if (r.failed || !r.valid) return null;
+      if (r.stanceKey !== 'PASS') return r.stanceKey;
+    }
+    return null;
+  };
+  const head = rows.find((r) => r.type === 'field-notes');
+  const finals = seats.map(finalStance);
+  // the tally, counted in code from the final stances (the chairman's own is kept for comparison)
+  const counts = {};
+  for (const f of finals) { const k = f ? optionLabel(f, options) : 'no eligible stance'; counts[k] = (counts[k] || 0) + 1; }
+  const tallyCount = Object.keys(counts).length ? `Final: ${Object.entries(counts).sort((x, y) => y[1] - x[1]).map(([k, n]) => `${k} ${n}`).join(', ')}.` : '';
+  const legacy = !(head?.schemaVersion >= 3);
+  // a failed verdict (the chairman never met the grammar) is diagnostic text: it never chooses
+  const failedVerdict = !!(verdictRow?.failed && !verdictRow.skipped);
+  const chosen = failedVerdict ? 'no verdict' : chosenOption(options, v.RECOMMENDATION, finals, { legacy });
+  // The AI recommends; only a human decides. `accepted` comes from an `accepted` row (POST
+  // .../accept) and may differ from the recommendation; both are written.
+  const acceptedRow = [...rows].reverse().find((r) => r.type === 'accepted');
+  const accepted = acceptedRow ? (acceptedRow.option === 'none' ? 'no option' : optionLabel(acceptedRow.option, options)) : null;
+  const recommended = chosen;
+  const status = accepted ? 'accepted' : failedVerdict ? 'no verdict' : !rb.finished || !verdictRow || verdictRow.skipped || STOPPED.has(rb.stopReason) ? 'stopped' : chosen === 'no consensus' || chosen === 'no pick' ? 'split' : 'recommended';
+  const usage = rollup(rows);
+  const recoveryMessages = [...new Set([...rb.recoveryWarnings, ...warnings].map((w) => w.message).filter(Boolean))];
+  const meta = { title: fn.decision, date, slug, status, chosen: accepted ?? chosen, recommended, accepted, stopReason: rb.stopReason, file: `${slug}.md` };
+  if (metadataOnly) return { meta, summary: { decision: fn.decision, finished: rb.finished, seats: seats.length, rounds: rb.rounds.length, usage: usage.total, warning: recoveryMessages.at(-1) || null } };
+
+  // where the seat ran is part of the record: a CLI on a subscription, or an API endpoint by URL
+  const where = (s) => (s.endpoint ? `API ${s.endpoint}` : 'CLI');
+  const seatLine = (s) => [s.label || s.vendor, where(s), s.lens, s.mood?.preset === 'custom' ? `custom: ${s.mood.text}` : (s.mood?.preset || 'grill'), s.model || 'default model', s.effort || 'default effort'].join(', ');
+  const front = [
+    '---',
+    `title: ${yaml(fn.decision)}`,
+    `date: ${date}`,
+    `slug: ${slug}`,
+    `status: ${status}`,
+    `stop_reason: ${rb.stopReason || 'none'}`,
+    'options:',
+    ...options.map((o) => `  - ${yaml(o)}`),
+    `chosen: ${yaml(accepted ?? chosen)}`,
+    `recommended: ${yaml(recommended)}`,
+    ...(acceptedRow ? [`accepted: ${yaml(accepted)}`, `accepted_on: ${String(acceptedRow.t || '').slice(0, 10) || 'unknown'}`] : []),
+    'seats:',
+    ...seats.map((s) => `  - ${yaml(seatLine(s))}`),
+    `chairman: ${rb.chairman?.vendor || 'none'}${rb.chairman?.endpoint ? ` at ${rb.chairman.endpoint}` : ''}${rb.chairman?.model ? ` (${rb.chairman.model})` : ''}`,
+    `rounds: ${rb.rounds.length}`,
+    `roundtable: ${slug}`,
+    '---',
+  ];
+  const section = (title, body) => [`## ${title}`, '', body && body.trim() ? body.trim() : '_not given_', ''];
+  const list = (text) => text; // the chairman already writes bullets
+  const notesBody = [
+    fn.constraints ? `- **Constraints:** ${fn.constraints}` : null,
+    fn.known ? `- **Evidence, known:** ${fn.known}` : null,
+    fn.assumed ? `- **Evidence, assumed:** ${fn.assumed}` : null,
+    fn.reversibility ? `- **Reversibility:** ${fn.reversibility}` : null,
+    fn.deadline ? `- **Deadline:** ${fn.deadline}` : null,
+  ].filter(Boolean).join('\n');
+  const tallyRows = seats.map((s, i) => {
+    const per = rb.rounds.map((round) => {
+      const r = round.find((x) => (x.seat.id ?? `${x.seat.vendor}:${x.seat.lens}`) === (s.id ?? `${s.vendor}:${s.lens}`));
+      return r ? (r.failed ? 'no reply' : optionLabel(r.stanceKey, options)) : '';
+    });
+    return `| ${s.label || s.vendor} · ${s.lens} | ${per.join(' | ')} | ${finals[i] ? optionLabel(finals[i], options) : 'none'} |`;
+  });
+  const tally = rb.rounds.length
+    ? [`| seat | ${rb.rounds.map((_, i) => `round ${i}`).join(' | ')} | final |`, `|---|${rb.rounds.map(() => '---').join('|')}|---|`, ...tallyRows].join('\n')
+    : '';
+  const formatNotes = (notes) => notes.map((note) => `**${noteAuthor(note)}:** ${noteRecord(note).text}`).join('\n\n');
+  const humanNotes = [rb.initialNotes?.length ? `### Before round 0\n\n${formatNotes(rb.initialNotes)}` : null,
+    ...rb.humanNotes.map((ns, i) => (ns?.length ? `### After round ${i}\n\n${formatNotes(ns)}` : null))].filter(Boolean).join('\n\n');
+  const costCell = (u) => (u.cost == null ? 'not reported' : `$${u.cost.toFixed(2)}${u.costCoverage && u.costCoverage.reported < u.costCoverage.of ? ` (partial: ${u.costCoverage.reported} of ${u.costCoverage.of} calls report a cost)` : ''}`);
+  const tokens = (n, u) => u.tokenCoverage?.reported === 0 ? 'unknown'
+    : `${k(n)}${u.tokenCoverage && u.tokenCoverage.reported < u.tokenCoverage.of ? ' (partial)' : ''}`;
+  const usageRows = seats.map((s) => {
+    const u = usage.bySeat[s.id ?? `${s.vendor}:${s.lens}`]?.usage;
+    return u ? `| ${s.label || s.vendor} · ${s.lens} | ${tokens(u.input, u)} | ${tokens(u.cacheRead + u.cacheWrite, u)} | ${tokens(u.output, u)} | ${costCell(u)} |` : null;
+  }).filter(Boolean);
+  const ch = usage.bySeat.chairman?.usage;
+  const researchUsage = usage.bySeat.research?.usage;
+  if (researchUsage) usageRows.push(`| searcher (${usage.bySeat.research.seat?.vendor || rb.options?.research?.vendor || 'codex'}) | ${tokens(researchUsage.input, researchUsage)} | ${tokens(researchUsage.cacheRead + researchUsage.cacheWrite, researchUsage)} | ${tokens(researchUsage.output, researchUsage)} | ${costCell(researchUsage)} |`);
+  if (ch) usageRows.push(`| chairman (${rb.chairman?.vendor || '?'}) | ${tokens(ch.input, ch)} | ${tokens(ch.cacheRead + ch.cacheWrite, ch)} | ${tokens(ch.output, ch)} | ${costCell(ch)} |`);
+  const t = usage.total;
+  const usageTable = usageRows.length
+    ? ['| seat | input | cache | output | cost |', '|---|---|---|---|---|', ...usageRows, `| **debate** | ${tokens(t.input, t)} | ${tokens(t.cacheRead + t.cacheWrite, t)} | ${tokens(t.output, t)} | ${costCell(t)} |`].join('\n')
+    : '';
+  // a grammar line names an id: show its label in its place
+  const recText = v.parsed ? v.RECOMMENDATION.replace(/^\s*(opt-\d+)\b\.?/, (m, id) => `**${optionLabel(id, options)}** (${id})`) : '';
+  const recommendation = verdictRow?.skipped ? verdictRow.text : (v.parsed ? recText : (verdictRow?.text || ''));
+
+  const md = [
+    ...front,
+    '',
+    `# ${fn.decision}`,
+    '',
+    acceptedRow
+      ? `Accepted by the human on ${String(acceptedRow.t || date).slice(0, 10)}: **${accepted}**. Recommended by a roundtable of ${seats.length} seats on ${date}: **${recommended}** (stopped because: ${rb.stopReason || 'not stopped'}).`
+      : `Recommended by a roundtable of ${seats.length} seats on ${date}: **${recommended}** (${status}, stopped because: ${rb.stopReason || 'not stopped'}). Not yet accepted by a human.`,
+    ...(acceptedRow?.note ? ['', `> ${String(acceptedRow.note).replace(/\r?\n/g, ' ')}`] : []),
+    '',
+    ...(recoveryMessages.length ? section('Record recovery', recoveryMessages.join('\n\n')) : []),
+    ...section('Question', `${fn.decision}\n\nOptions:\n${options.map((o) => `- ${o}`).join('\n')}`),
+    ...section('Field notes', notesBody),
+    ...(rb.research ? section('Shared web evidence', rb.research.status === 'done'
+      ? ['Provider-supplied citations, excerpts and publication dates; not independently verified. Every seat received this saved bundle.',
+        `Gathered: ${rb.research.gatheredAt}. Reported search operations: ${rb.research.searches}.`,
+        ...rb.research.sources.map((s) => `### ${s.id}: ${s.title.replace(/[\r\n]/g, ' ')}\n\n<${s.url}>\n\nPublished: ${s.publishedAt || 'not reported'}\n\n> ${s.excerpt.replace(/\r?\n/g, '\n> ')}`)].join('\n\n')
+      : rb.research.error || 'Research was interrupted; no source bundle was saved.') : []),
+    ...section('Tally', [tally, tallyCount].filter(Boolean).join('\n\n')),
+    ...section('Recommendation', recommendation),
+    ...(v.TALLY ? section("Chairman's tally", v.TALLY) : []),
+    ...section('Dissent', list(v.DISSENT)),
+    ...section('Kill criteria', list(v.KILL_CRITERIA)),
+    ...section('Open questions', list(v.OPEN_QUESTIONS)),
+    ...section('Discussion notes', humanNotes),
+    ...section('Usage', [usageTable, usage.unknownAttempts ? `${usage.unknownAttempts} call(s) did not report usable token counts. Totals include reported figures only; unknown usage is not zero.` : ''].filter(Boolean).join('\n\n')),
+    `_Exported by roundtable from debates/${slug}/transcript.jsonl._`,
+    '',
+  ].join('\n');
+  return { markdown: md, meta };
+}
+
+const INDEX_INTRO = ['# Decision records', '', 'One file per roundtable debate, newest first. Written by `npm run export`; re-exporting a debate replaces its row.', ''];
+const TABLE_HEAD = ['| date | title | chosen | status | record |', '|---|---|---|---|---|'];
+const REGION_START = '<!-- roundtable:index -->';
+const REGION_END = '<!-- roundtable:index:end -->';
+const cell = (s) => String(s ?? '').replace(/\|/g, '\\|').replace(/\r?\n/g, ' ');
+const isRow = (l) => /^\|\s*\d{4}-\d{2}-\d{2}\s*\|/.test(l);
+
+// The index: create it, or replace this slug's row inside our marked region. A legacy index
+// (written before the markers, recognised by its whole header, not by a date column) is
+// converted, keeping what was written around its table. Returns null for any other file.
+export function updateIndex(existing, meta) {
+  const row = `| ${meta.date} | ${cell(meta.title)} | ${cell(meta.chosen)} | ${meta.status} | [${meta.file}](./${meta.file}) |`;
+  const region = (oldRows) => {
+    const rows = oldRows.filter(isRow).filter((l) => !l.includes(`](./${meta.file})`));
+    rows.push(row);
+    rows.sort((a, b) => (b.slice(2, 12).localeCompare(a.slice(2, 12))) || a.localeCompare(b));
+    return [REGION_START, ...TABLE_HEAD, ...rows, REGION_END];
+  };
+  if (existing == null) return [...INDEX_INTRO, ...region([]), ''].join('\n');
+  const eol = existing.includes('\r\n') ? '\r\n' : '\n';
+  const lines = existing.split(/\r?\n/);
+  const start = lines.indexOf(REGION_START), end = lines.indexOf(REGION_END);
+  if (start >= 0 && end > start) return [...lines.slice(0, start), ...region(lines.slice(start + 1, end)), ...lines.slice(end + 1)].join(eol);
+  // legacy: our title, our sentence, our exact table header
+  const header = lines.indexOf(TABLE_HEAD[0]);
+  const legacy = lines[0] === INDEX_INTRO[0] && lines.some((l) => l.startsWith('One file per roundtable debate') && l.includes('Written by `npm run export`')) && header > 0 && lines[header + 1] === TABLE_HEAD[1];
+  if (!legacy) return null;
+  let after = header + 2;
+  while (after < lines.length && isRow(lines[after])) after++;
+  return [...lines.slice(0, header), ...region(lines.slice(header + 2, after)), ...lines.slice(after)].join(eol);
+}
+
+// A record file is ours when its front matter names this slug under `roundtable:`; a legacy
+// record (before that key) when it has our `slug:` line and our opening sentence.
+export function ownsRecord(text, slug) {
+  const front = /^---\r?\n([\s\S]*?)\r?\n---/.exec(text)?.[1] || '';
+  if (new RegExp(`^roundtable: ${slug}$`, 'm').test(front)) return true;
+  return new RegExp(`^slug: ${slug}$`, 'm').test(front) && /\nDecided by a roundtable of \d+ seats on /.test(text); // the 0.2.0 sentence
+}
+
+// An existing directory, as an absolute path. Records are named from the slug, which is
+// restricted to [a-z0-9-], so the written path can only be directly inside it.
+// forbid: further directories the caller will not write into (the server's own debates dir).
+export function validateTarget(target, { forbid = [] } = {}) {
+  if (!target || typeof target !== 'string') throw new Error('Export needs a target directory.');
+  let abs = path.resolve(target);
+  if (!existsSync(abs) || !statSync(abs).isDirectory()) throw new Error(`Export target is not an existing directory: ${abs}`);
+  abs = realpathSync(abs);
+  const same = (dir) => path.relative(existsSync(dir) ? realpathSync(dir) : path.resolve(dir), abs) === '';
+  if (path.parse(abs).root === abs) throw new Error(`Refusing to export into a filesystem root: ${abs}`);
+  if (same(os.homedir())) throw new Error(`Refusing to export into the home directory: ${abs}. Pick a decisions folder inside a project.`);
+  for (const f of forbid) if (same(f)) throw new Error(`Refusing to export into ${abs}: roundtable keeps its own transcripts there.`);
+  return abs;
+}
+
+export function recordPath(target, slug, opts) {
+  if (!/^[a-z0-9-]+$/.test(slug)) throw new Error(`Bad slug: ${slug}`);
+  const abs = validateTarget(target, opts);
+  const file = path.resolve(abs, `${slug}.md`);
+  if (path.dirname(file) !== abs) throw new Error('Refusing to write outside the target directory.');
+  return file;
+}
+
+// Temp file in the same directory, then rename: a reader never sees half a file.
+function writeAtomic(file, text, mode) {
+  const tmp = `${file}.${randomUUID()}.tmp`;
+  const fd = openSync(tmp, 'wx', mode ?? 0o666);
+  try {
+    try {
+      writeFileSync(fd, text);
+      // Creation respects umask; an existing record/index keeps its exact access bits.
+      if (mode != null && process.platform !== 'win32') fchmodSync(fd, mode);
+    } finally { closeSync(fd); }
+    renameSync(tmp, file);
+  } finally { if (existsSync(tmp)) unlinkSync(tmp); }
+}
+
+function regularOrAbsent(file) {
+  try {
+    const s = lstatSync(file);
+    if (!s.isFile() || s.isSymbolicLink()) throw new Error(`Refusing linked or non-file export destination: ${file}`);
+    return s.mode & 0o777;
+  } catch (e) { if (e.code !== 'ENOENT') throw e; }
+}
+
+// Every check runs before the first write, so a refusal leaves the directory untouched.
+export function exportDebate(rows, slug, target, opts) {
+  const file = recordPath(target, slug, opts);
+  const mode = regularOrAbsent(file);
+  if (existsSync(file) && !ownsRecord(readFileSync(file, 'utf8'), slug)) throw new Error(`Refusing to replace ${file}: it was not written by roundtable for this debate.`);
+  const { markdown, meta } = decisionRecord(rows, slug, opts);
+  let indexPath = null, indexText = null, indexMode;
+  for (const name of ['README.md', 'DECISIONS.md']) {
+    const p = path.join(path.dirname(file), name);
+    const candidateMode = regularOrAbsent(p);
+    const next = updateIndex(existsSync(p) ? readFileSync(p, 'utf8') : null, meta);
+    if (next != null) { indexPath = p; indexText = next; indexMode = candidateMode; break; }
+  }
+  if (!indexPath) throw new Error(`Refusing to export into ${path.dirname(file)}: README.md and DECISIONS.md both exist and neither is a roundtable index.`);
+  writeAtomic(file, markdown, mode);
+  writeAtomic(indexPath, indexText, indexMode);
+  return { path: file, indexPath, meta };
+}