@prplkane/roundtable 0.0.0-stage → 0.6.3

package/src/adapters/spawn.js

@@ -0,0 +1,178 @@
+import { spawn, execFileSync } from 'node:child_process';
+import { existsSync, mkdirSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { PROFILE_RE } from '../seats.js';
+import { safeProgress } from '../progress.js';
+
+const WIN = process.platform === 'win32';
+
+// Find a real executable for `name` so spawn never needs a shell (Node refuses .cmd shims
+// without one, and a shell would mangle quoted prompt text).
+export function resolveBinary(name, npmBin, { platform = process.platform, env = process.env, exists = existsSync } = {}) {
+  const P = platform === 'win32' ? path.win32 : path.posix;
+  const dirs = (env.PATH || '').split(P.delimiter).filter(Boolean);
+  const exts = platform === 'win32' ? ['.exe'] : [''];
+  for (const dir of dirs) {
+    for (const ext of exts) {
+      const p = P.join(dir, name + ext);
+      if (exists(p)) return { file: p, prefix: [] };
+    }
+    // Respect PATH order across npm shims and native binaries too. A later desktop CLI
+    // must not silently replace the npm CLI selected by the user's terminal.
+    if (npmBin && (platform !== 'win32' || ['.cmd', '.ps1'].some((ext) => exists(P.join(dir, name + ext))))) {
+      const [pkg, rel] = npmBin;
+      const script = P.join(dir, 'node_modules', pkg, rel);
+      if (exists(script)) return { file: process.execPath, prefix: [script] };
+    }
+  }
+  throw new Error(`${name}: not found on PATH`);
+}
+
+// Kill a CLI and everything it started: the process tree on Windows (taskkill /T), the process
+// group elsewhere (the child is spawned as a group leader, so -pid reaches its helpers).
+export function killTree(child) {
+  if (WIN) {
+    try { execFileSync('taskkill', ['/PID', String(child.pid), '/T', '/F'], { stdio: 'ignore' }); } catch {}
+  } else {
+    try { process.kill(-child.pid, 'SIGKILL'); } catch { try { child.kill('SIGKILL'); } catch {} }
+  }
+}
+
+// Every CLI child still running, with the tag its caller gave (the debate slug), so a stopped
+// debate or a dying server can kill exactly those. Entries leave when the child closes.
+const live = new Map(); // child (or a call token) -> { tag, onKill, virtual }
+export function liveChildren(tag = null) {
+  return [...live.entries()].filter(([, v]) => tag == null || v.tag === tag).map(([child, v]) => ({ pid: v.virtual ? null : child.pid, tag: v.tag }));
+}
+// Kill the registered children (all, or those with `tag`). `kill` is injectable for tests.
+export function killAll(tag = null, { kill = killTree } = {}) {
+  let n = 0;
+  for (const [child, v] of [...live.entries()]) {
+    if (tag != null && v.tag !== tag) continue;
+    v.onKill(); if (!v.virtual) kill(child); live.delete(child); n++;
+  }
+  return n;
+}
+// An in-process call (an HTTP request to an API endpoint) registered under a tag, so a stopped
+// debate or a dying server aborts it like a child. Returns its abort signal and a release().
+export function registerCall(tag = null) {
+  const token = {};
+  const ac = new AbortController();
+  live.set(token, { tag, virtual: true, onKill: () => ac.abort(Object.assign(new Error('killed: the debate was stopped or the server shut down'), { code: 'KILLED' })) });
+  return { signal: ac.signal, release: () => live.delete(token) };
+}
+
+// Run a CLI once. Resolves with {stdout, stderr, code, ms}; rejects on timeout (code TIMEOUT),
+// on a kill through killAll (code KILLED) or on a spawn error.
+// stallMs: stop the process once it has made no progress for this long (code STALL), for a call
+// whose provider keeps the connection busy while producing nothing (the CLI's own idle limit
+// then never fires). progressAt: when the caller last saw progress (the adapter leaves out a
+// CLI's reconnect notices); without it, any output counts. 0: no such limit.
+export function runProcess({ file, prefix }, args, { stdin = null, cwd, timeoutMs = 300_000, env, tag = null, onStdout, completionGraceMs = null, maxOutputBytes = 8 * 1024 * 1024, stallMs = 0, progressAt = null } = {}) {
+  return new Promise((resolve, reject) => {
+    const t0 = Date.now();
+    const child = spawn(file, [...prefix, ...args], { cwd, env, windowsHide: true, detached: !WIN, stdio: ['pipe', 'pipe', 'pipe'] });
+    let out = '', err = '', done = false, outputBytes = 0, stdoutBytes = 0, stderrBytes = 0, firstOutputMs, lastOutputAt = t0;
+    let completed = false, completionTimer, stallTimer;
+    const progress = (outcome, exitCode) => safeProgress({ elapsedMs: Date.now() - t0, timeoutMs, stdoutBytes, stderrBytes,
+      firstOutputMs, idleMs: Date.now() - lastOutputAt, outcome, exitCode });
+    const finish = (fn) => { if (done) return; done = true; clearTimeout(timer); clearTimeout(completionTimer); clearInterval(stallTimer); live.delete(child); fn(); };
+    live.set(child, { tag, onKill: () => finish(() => reject(Object.assign(new Error('killed: the debate was stopped or the server shut down'), { code: 'KILLED', stdout: out, stderr: err, ms: Date.now() - t0, progress: progress('cancelled') }))) });
+    const stop = (e) => finish(() => {
+      const metadata = progress(e.code === 'TOOL_POLICY' ? 'policy' : e.code === 'OUTPUT_LIMIT' ? 'output-limit' : e.code === 'CLI_FAILURE' ? 'provider-error' : e.code === 'STALL' ? 'timeout' : 'protocol');
+      killTree(child);
+      reject(Object.assign(e, { stdout: out, stderr: err, ms: metadata.elapsedMs, progress: metadata }));
+    });
+    const receive = (d, stdout) => {
+      if (done) return;
+      outputBytes += Buffer.byteLength(d);
+      if (stdout) stdoutBytes += Buffer.byteLength(d); else stderrBytes += Buffer.byteLength(d);
+      lastOutputAt = Date.now();
+      firstOutputMs ??= lastOutputAt - t0;
+      if (outputBytes > maxOutputBytes) { stop(Object.assign(new Error('Provider output exceeded the local size limit.'), { code: 'OUTPUT_LIMIT' })); return; }
+      if (stdout) out += d; else err += d;
+      try {
+        // Only a caller that validates a terminal event, answer and usage can signal this.
+        // Keep inspecting output during the grace period, then reap a stuck CLI without
+        // losing its completed answer or launching another paid request.
+        if (stdout && onStdout?.(d) === true && completionGraceMs > 0 && !completed) {
+          completed = true;
+          completionTimer = setTimeout(finishCompleted, completionGraceMs);
+        }
+      } catch (e) { stop(e); }
+    };
+    const finishCompleted = () => finish(() => {
+      const metadata = progress('completed');
+      killTree(child);
+      resolve({ stdout: out, stderr: err, code: null, completed: true, ms: metadata.elapsedMs, progress: metadata });
+    });
+    child.stdout.setEncoding('utf8').on('data', (d) => receive(d, true));
+    child.stderr.setEncoding('utf8').on('data', (d) => receive(d, false));
+    const timer = setTimeout(() => completed ? finishCompleted() : finish(() => {
+      const metadata = progress('timeout');
+      killTree(child);
+      reject(Object.assign(new Error(`timed out after ${timeoutMs} ms`), { code: 'TIMEOUT', stdout: out, stderr: err, ms: metadata.elapsedMs, progress: metadata }));
+    }), timeoutMs);
+    if (stallMs > 0) stallTimer = setInterval(() => {
+      if (!completed && Date.now() - (progressAt?.() ?? lastOutputAt) >= stallMs) stop(Object.assign(new Error(`no progress for ${Math.round(stallMs / 1000)} s`), { code: 'STALL' }));
+    }, Math.min(1000, stallMs));
+    child.on('error', (e) => finish(() => reject(Object.assign(e, { stdout: out, stderr: err, ms: Date.now() - t0, progress: progress('spawn-error') }))));
+    child.on('close', (code) => finish(() => resolve({ stdout: out, stderr: err, code, ms: Date.now() - t0, progress: progress('exited', code) })));
+    child.stdin.on('error', () => {}); // CLI may exit before reading stdin
+    child.stdin.end(stdin ?? '');
+  });
+}
+
+// Strip parent-agent session/bridge variables so a seat starts its own CLI session, including
+// when the Roundtable server outlives the tool call that launched it. `home` points local
+// state at the instance's own directory.
+// Variables that would make a CLI bill an API account instead of the subscription it is logged
+// in to. A seat runs on the subscription unless ROUNDTABLE_API_BILLING=1 says otherwise, so a
+// key left in the shell cannot quietly move a debate onto pay-per-token.
+export const API_KEY_VARS = /^(ANTHROPIC_API_KEY|ANTHROPIC_AUTH_TOKEN|CLAUDE_API_KEY|OPENAI_API_KEY|OPENAI_ACCESS_TOKEN|CODEX_API_KEY|GOOGLE_API_KEY|GEMINI_API_KEY|GOOGLE_GENAI_API_KEY)$/;
+const CODEX_PARENT_VARS = /^(CODEX_APP_TOOLS_PIPE_PATH|CODEX_APP_RUNTIME_CLI_PATH|CODEX_INTERNAL_ORIGINATOR_OVERRIDE|CODEX_SESSION_ID|CODEX_THREAD_ID|CODEX_TOOL_CALL_ID|CODEX_PERMISSION_PROFILE)$/i;
+
+export function cleanEnv(home = null, { allowApiKeys = process.env.ROUNDTABLE_API_BILLING === '1', source = process.env } = {}) {
+  const env = {};
+  for (const [k, v] of Object.entries(source)) {
+    if (/^(CLAUDECODE|CLAUDE_CODE_|CLAUDE_AGENT_SDK|CLAUDE_PID|CLAUDE_EFFORT|ANTHROPIC_BASE_URL)/.test(k)) continue;
+    if (CODEX_PARENT_VARS.test(k)) continue;
+    if (!allowApiKeys && API_KEY_VARS.test(k)) continue;
+    env[k] = v;
+  }
+  if (home) env[home.env] = home.dir;
+  return env;
+}
+
+// Where a named profile's CLI state lives: the OS user-data directory, never the project
+// folder. One tree per profile name, one subdirectory per vendor inside it, so a profile is a
+// login the user made themselves (`doctor` prints the command). Nothing is ever copied into it:
+// the CLI's own login flow writes its credentials there, and roundtable never reads them.
+//   Windows  %USERPROFILE%\\.roundtable\\homes\\<profile>\\<vendor>
+//   macOS    ~/Library/Application Support/roundtable/homes/<profile>/<vendor>
+//   Linux    $XDG_DATA_HOME/roundtable/homes/<profile>/<vendor>, default ~/.local/share
+// Windows uses the user profile, not AppData, for the reason history.js dataDirectory gives: a
+// packaged app's programs have their AppData writes redirected into that app's own copy, so a
+// login made from one app would be missing in another.
+export function dataDir({ platform = process.platform, env = process.env, homedir = os.homedir() } = {}) {
+  const P = platform === 'win32' ? path.win32 : path.posix; // the target platform's separators, so tests can ask for any
+  if (platform === 'win32') return P.join(homedir, '.roundtable');
+  if (platform === 'darwin') return P.join(homedir, 'Library', 'Application Support', 'roundtable');
+  return P.join(env.XDG_DATA_HOME || P.join(homedir, '.local', 'share'), 'roundtable');
+}
+
+export function profileHome(vendor, profile, where = {}) {
+  const name = String(profile || '').trim();
+  if (!PROFILE_RE.test(name)) throw new Error(`Profile name "${profile}" must be 1-40 letters, digits, dots, dashes or underscores.`);
+  const win = where.platform === 'win32' || (!where.platform && process.platform === 'win32');
+  const P = win ? path.win32 : path.posix;
+  const dir = P.join(dataDir(where), 'homes', name, vendor);
+  // a profile logged in under the earlier AppData default keeps its login until it is moved
+  if (win) {
+    const exists = where.exists || existsSync, env = where.env || process.env;
+    const earlier = env.LOCALAPPDATA && P.join(env.LOCALAPPDATA, 'roundtable', 'homes', name, vendor);
+    if (earlier && !exists(dir) && exists(earlier)) return earlier;
+  }
+  return dir;
+}

package/src/agent-client.js

@@ -0,0 +1,108 @@
+import { LIMITS } from './validate.js';
+import { localClient } from './local-http.js';
+
+export const HELP = {
+  usage: 'roundtable agent <status|check|start|wait|answer|hold|finish|stop|resume|verdict> [--port 4747] [--id review-id] [--input file|-] [--seconds 25] [--after-round round] [--refresh]',
+  commands: {
+    status: 'Without --id: cached provider setup. With --id: current step, questions, latest positions and verdict. --refresh refreshes free CLI status checks.',
+    check: 'Validate --input and estimate calls/tokens without creating a review.',
+    start: 'Start the review in --input. Uses the selected providers. Returns its id immediately.',
+    wait: 'Wait up to --seconds (1–30) for a question or completion. After presenting questions, use --after-round N to wait for the next step without asking the same questions again. Returns one state object, not an event log.',
+    answer: 'Send --input {round, answers:[{id:"q1",text:"..."}], message:"optional note"}, labelled as an agent note. Read the current state first; never invent a missing answer.',
+    hold: 'Send --input {round} to give the user another answer window. This is a bounded extension, not an indefinite pause. It makes no model call.',
+    stop: 'Cancel all in-flight calls, including the chairman; keep completed replies. A verdict runs later only if explicitly requested.',
+    finish: 'End discussion and write the verdict from collected replies. Available after one complete round has a usable reply; may make a chairman call.',
+    resume: 'Resume an interrupted review. May make provider calls.',
+    verdict: 'Request a missing or failed verdict from saved replies. May make a provider call.',
+  },
+  setup: 'Use roundtable server status to inspect the local board; roundtable server start launches it hidden if needed (add --fake for a free test). After an update, server restart refuses active reviews. This client reads its launch token locally; it never prints or stores the token.',
+  input: 'check/start accept the same {fieldNotes,seats,chairman,options} JSON as the board. Check available providers first. Every result with an id carries board, a link where a person can watch the review in a browser; offer it, do not open it.',
+  recipe: {
+    questions: 'When nextAction.type is ask_user, present gate.questions with an available user-input tool; if unavailable, ask in normal chat. Tell the user the autoContinueAt deadline and that unknowns stay unknown. Do not just print JSON or answer for the user. In an async host, use nextAction.waitCommand while the question is pending; await_user means it has already been shown, so do not ask again. Read status before sending the user reply; if the round has advanced, preserve the reply and report that it was not submitted. Use hold only when the person needs more time, never as an automatic keepalive.',
+    size: 'Normally use two seats, critiqueRounds 1 (the engine default), memory stateless and an explicit budget per vendor: up to five calls before repairs. Use 0 only for a requested quick comparison and disclose that the seats did not respond to each other. Consider 2 for a requested deep review or a decision with several consequential trade-offs, within the user\'s time and budget. Consensus can end discussion early. Do not automatically start another review or exceed agreed limits because disagreement remains.',
+    completion: 'A start acknowledgement or seat positions are not a completed review. Keep waiting through status running and verdict until status done and verdict.status ready. If interrupted, failed, skipped or missing, report that limitation instead of supplying your own chairman result. Include the review id, board link and depth.completedCritiqueRounds in the final report.',
+    lenses: 'Give every seat a different lens, taken from what the decision could get wrong: risk, cost, evidence, reversibility, long-term effects, user impact. Two seats with one lens mostly agree, which wastes a call.',
+    moods: 'Pair one sceptical seat (grill) with one practical seat (builder). Use steelman when the user already leans one way, contrarian when the seats would otherwise agree too early.',
+    effort: 'effort low and the lightest model in status for the seats of a small review. Give the chairman one effort step more than the seats (medium when they run low): it judges the arguments, and at low effort it dismisses the hardest objection in a word. Raise one seat, not all, when the decision is hard to reverse.',
+    context: 'constraints, known, assumed, reversibility and deadline go into every prompt. Fill them only with facts the user stated; put guesses under assumed, never under known. Leave a field empty rather than invent it.',
+    unattended: 'Use options.unattended true for a background job with nobody to answer: it skips all pauses and keeps missing facts as assumptions. Live chat or browser reviews leave it false: ordinary checkpoints last autoContinueMs (15 seconds by default), questions last questionWaitMs (2 minutes). No answer continues automatically, without accepting a recommendation. Both modes respect the review wall clock.',
+    isolation: 'Live Antigravity requires options.allowLimitedIsolation=true. Set it only when the user has agreed to its limits: session rules deny documented tools, but the CLI cannot disable all shared customizations or MCP discovery. Choose another provider otherwise. Reported prohibited tool activity still stops the seat.',
+    terms: 'Live Antigravity also requires options.acknowledgeTermsRisk=true, for every seat, chairman or searcher on agy. Google\'s Antigravity FAQ says wrapping agy in third-party applications is not supported under consumer plans and that third-party access can get the account suspended or terminated. Show the person providers[].terms.notice and its url from status, and set the option only when they have agreed for this review; an acknowledgment on the board does not answer for an agent request. Choose another provider otherwise.',
+    research: 'Only when the user requests web research: options.research={query:"public search question",maxSearches:4,timeoutMs:120000}. Adds one fresh CLI call, the searcher, before discussion; only this query goes into research. Optional vendor ("codex", "claude" or "agy"; default "codex"; agy also needs allowLimitedIsolation and acknowledgeTermsRisk), model, effort and account set the searcher; without model and effort it runs that vendor\'s lightest model at low effort on the default login. All seats receive the same saved provider-supplied sources. Reported search operations are bounded, but an operation may start before its report arrives. Failed or interrupted research never reruns automatically.',
+    agreement: 'When gate.reopenCalls is present, every seat already agrees. Empty answers and no message go straight to the verdict. Any answer text or message runs one more round at reopenCalls calls. Send text only if it could change a seat\'s position; a fact that confirms what the seats already said is better left for the verdict.',
+  },
+};
+
+export async function runAgent(command, flags = {}, input, signal) {
+  if (command === 'guide') return HELP;
+  if (!Object.hasOwn(HELP.commands, command)) throw new Error('Unknown agent command. Use agent --help.');
+  const port = Number(flags.port || process.env.PORT || 4747);
+  if (!Number.isInteger(port) || port < LIMITS.port[0] || port > LIMITS.port[1]) throw new Error('Port must be a number from 1 to 65535.');
+  if (flags.id && !/^[a-z0-9-]+$/.test(flags.id)) throw new Error('Invalid review id.');
+  const { base, request } = localClient(port, signal);
+  const route = flags.id ? `/api/debates/${flags.id}` : null;
+  const board = (id) => `${base}/#${id}`; // where a person can watch this review in a browser
+  let result;
+  if (command === 'status' && !route) {
+    const setup = await request('/api/seats?cached=1');
+    const pools = setup.vendors.filter((v) => v.kind !== 'api').map((v) => v.vendor);
+    const readiness = flags.refresh ? await request('/api/preflight', { pools, fresh: true }) : await request('/api/preflight');
+    result = { mode: setup.runtime.mode, cataloguePending: setup.runtime.cataloguePending === true, providers: setup.vendors.map((v) => ({ vendor: v.vendor, kind: v.kind,
+      models: (v.catalogue?.models || []).map((m) => typeof m === 'string' ? m : m.id), efforts: v.catalogue?.efforts || [],
+      ...(v.terms ? { terms: { notice: v.terms.notice, url: v.terms.url, acknowledgedOnBoard: v.terms.acknowledgedAt != null } } : {}) })),
+      readiness: readiness.pools, defaults: setup.defaults, next: 'Check a JSON review with agent check --input file. No model call has been made.' };
+  } else if (command === 'check') result = await request('/api/preview', input);
+  else if (command === 'start') { const started = await request('/api/debates', input); result = { id: started.slug, board: board(started.slug), next: `agent wait --port ${port} --id ${started.slug}` }; }
+  else {
+    if (!route) throw new Error('This command needs --id from agent start or the board URL.');
+    if (command === 'status') result = { ...(await request(`${route}/state`)), board: board(flags.id) };
+    else if (command === 'wait') {
+      const seconds = Number(flags.seconds || 25);
+      if (!Number.isInteger(seconds) || seconds < LIMITS.waitSeconds[0] || seconds > LIMITS.waitSeconds[1]) throw new Error('Wait seconds must be a whole number from 1 to 30.');
+      const afterRound = flags['after-round'] == null ? -1 : Number(flags['after-round']);
+      if (!Number.isInteger(afterRound) || afterRound < -1 || afterRound > LIMITS.critiqueRounds[1] || flags['after-round'] != null && afterRound < 0) throw new Error('After round must be a whole number from 0 to 8.');
+      result = await request(`${route}/state`);
+      if (['researching', 'running', 'verdict'].includes(result.status) || result.status === 'waiting' && (result.gate?.round === afterRound || result.gate?.mode === 'countdown' && !result.gate.questions.length)) {
+        const controller = new AbortController(), timer = setTimeout(() => controller.abort(), seconds * 1000);
+        let reader;
+        try {
+          const response = await fetch(`${base}${route}/events`, { redirect: 'error', signal: signal ? AbortSignal.any([signal, controller.signal]) : controller.signal, headers: { 'last-event-id': result.revision } });
+          if (!response.ok) throw new Error('Could not wait for review events.');
+          reader = response.body.getReader();
+          const decoder = new TextDecoder(); let buffer = '', finished = false;
+          while (!finished) {
+            const next = await reader.read(); if (next.done) break;
+            buffer += decoder.decode(next.value, { stream: true });
+            let end;
+            while ((end = buffer.indexOf('\n\n')) >= 0) {
+              const event = buffer.slice(0, end).split('\n').find((line) => line.startsWith('data: ')); buffer = buffer.slice(end + 2);
+              if (event) {
+                const update = JSON.parse(event.slice(6));
+                if (['done', 'error', 'interrupted'].includes(update.type) || update.type === 'gate' && update.round !== afterRound && (update.questions?.length || update.mode === 'blocking')) finished = true;
+              }
+            }
+          }
+        } catch (error) { signal?.throwIfAborted(); if (!controller.signal.aborted) throw error; }
+        finally { clearTimeout(timer); if (reader) await reader.cancel().catch(() => {}); }
+        result = await request(`${route}/state`);
+      }
+      result = { ...result, board: board(flags.id) };
+      if (result.nextAction?.type === 'ask_user' && result.gate.round === afterRound) {
+        result.nextAction = { ...result.nextAction, type: 'await_user', instruction: 'These questions have already been presented. Keep the existing prompt pending; do not ask again or invent answers. Read status before submitting a reply. Use waitCommand to wait for another step without extending the response window.' };
+      }
+    } else {
+      const body = structuredClone(input ?? {});
+      if (!body || typeof body !== 'object' || Array.isArray(body)) throw new Error('Input must be a JSON object.');
+      if (['answer', 'finish', 'stop', 'resume'].includes(command)) body.source = 'agent';
+      if (['answer', 'hold'].includes(command) && !Number.isInteger(body.round)) throw new Error('An answer or time extension needs the round number from the current state.');
+      result = await request(`${route}/${command === 'answer' ? 'continue' : command === 'verdict' ? 'synthesize' : command}`, body);
+      result = { ...result, id: flags.id, board: board(flags.id), next: `agent wait --port ${port} --id ${flags.id}` };
+    }
+  }
+  if (['ask_user', 'await_user'].includes(result.nextAction?.type)) {
+    result.nextAction.command = `agent answer --port ${port} --id ${flags.id} --input -`;
+    result.nextAction.waitCommand = `agent wait --port ${port} --id ${flags.id} --after-round ${result.gate.round}`;
+    result.nextAction.extend = { command: `agent hold --port ${port} --id ${flags.id} --input -`, input: { round: result.gate.round } };
+  }
+  return { ok: true, ...result };
+}

package/src/cli.js

@@ -0,0 +1,44 @@
+#!/usr/bin/env node
+// The `roundtable` command (package.json "bin"). One entry point, the same scripts as
+// `npm run`: it starts the right one with the arguments passed through.
+//
+//   roundtable                 the board on http://localhost:4747, opened in your browser
+//   roundtable fake            the board with scripted seats, nothing spent (port 4748)
+//   roundtable doctor [--live] what this machine can seat
+//   roundtable export <slug> <dir>
+//   roundtable debate [...]    one debate headless against a running server (see the script)
+//   --port <n> --no-open       for the two board commands
+import { spawn } from 'node:child_process';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { terminalBanner } from './terminal.js';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const SCRIPTS = {
+  start: ['src/server.js'], fake: ['src/server.js', '--fake'], doctor: ['src/doctor.js'],
+  export: ['scripts/export.mjs'], debate: ['scripts/run-debate.mjs'], agent: ['scripts/agent.mjs'],
+  mcp: ['scripts/mcp.mjs'], setup: ['scripts/setup.mjs'], server: ['scripts/server.mjs'],
+};
+
+const args = process.argv.slice(2);
+const USAGE = ['roundtable [--port <n>] [--no-open]   the board, opened in your browser', 'roundtable fake [--port <n>]          the board with scripted seats, nothing spent',
+  'roundtable doctor [--live]            what this machine can seat', 'roundtable export <slug> <dir>        write a decision record into a codebase',
+  'roundtable debate [--token <hex>] ... one debate headless, body on stdin',
+  'roundtable agent --help              JSON commands for agents; no GUI needed',
+  'roundtable setup --client codex      connect an assistant across projects (also claude, agy, all)',
+  'roundtable setup --help              inspect, update or remove that connection',
+  'roundtable server --help             check, start, stop or restart the hidden board',
+  'roundtable mcp                       MCP tools over stdio; starts the local server as needed'].join('\n');
+// help first, wherever it is on the line: a bare `--help` must never start the real server
+if (!['agent', 'setup', 'mcp', 'server'].includes(args[0]) && args.some((a) => a === 'help' || a === '--help' || a === '-h')) { process.stdout.write(terminalBanner()); console.log(USAGE); process.exit(0); }
+const cmd = args[0] && !args[0].startsWith('-') ? args.shift() : 'start';
+if (!SCRIPTS[cmd]) { console.error(`unknown command: ${cmd}\n\n${USAGE}`); process.exit(2); }
+const env = { ...process.env };
+const port = args.indexOf('--port');
+if (port >= 0 && ['start', 'fake'].includes(cmd)) { env.PORT = args[port + 1]; args.splice(port, 2); }
+const [script, ...fixed] = SCRIPTS[cmd]; // only the script is a path; the rest are the server's own flags
+const child = spawn(process.execPath, [path.join(ROOT, script), ...fixed, ...args], { stdio: 'inherit', env, windowsHide: true });
+child.on('exit', (code, signal) => process.exit(code ?? (signal ? 1 : 0)));
+// A signal to this process goes to the child too; this process ends when the child does. (A
+// handler that only waited swallowed SIGTERM on Linux, and `kill` could not stop it.)
+for (const sig of ['SIGINT', 'SIGTERM', 'SIGHUP']) process.on(sig, () => { try { child.kill(sig); } catch {} });

package/src/contract.js

@@ -0,0 +1,256 @@
+// The reply contract every seat must follow, and its parser.
+//
+//   STANCE: <an option id (opt-1, opt-2, ...) or its exact label | other: <label>>
+//   AGREE_WITH: [labels]        (empty in round 0)
+//   DISAGREE: <=3 bullets
+//   NEW: <=2 bullets or "none"
+//   ASSUMPTIONS: bullets
+//   QUESTION_FOR_HUMAN: one line, optional
+//   PASS                        (alone, when nothing new)
+
+import { normLabel } from './validate.js';
+
+export const HEADERS = ['STANCE', 'AGREE_WITH', 'DISAGREE', 'NEW', 'ASSUMPTIONS', 'QUESTION_FOR_HUMAN'];
+// Parse decoration in separate passes: adjacent optional whitespace regexes can backtrack
+// quadratically, especially when a provider puts a Unicode line separator inside a line.
+function header(line, names, verdict = false) {
+  let rest = line.trimStart(), i = 0;
+  const opening = verdict ? '*#_-' : '*_`#>-';
+  while (i < rest.length && opening.includes(rest[i])) i++;
+  const decoration = rest.slice(0, i);
+  rest = rest.slice(i).trimStart();
+  const name = names.find((h) => rest.slice(0, h.length).toUpperCase() === h);
+  if (!name) return null;
+  rest = rest.slice(name.length).trimStart(); i = 0;
+  const closing = verdict ? '*_' : '*_`';
+  while (i < rest.length && closing.includes(rest[i])) i++;
+  const suffix = rest.slice(i).trimStart();
+  const closedBeforeColon = i > 0 && (suffix.startsWith(':') || decoration.endsWith(rest.slice(0, i)));
+  if (closedBeforeColon) rest = suffix;
+  if (rest.startsWith(':')) rest = rest.slice(1).trimStart();
+  else if (!verdict) return null;
+  let headerClosed = closedBeforeColon;
+  if (!closedBeforeColon && decoration) {
+    i = 0;
+    while (i < rest.length && closing.includes(rest[i])) i++;
+    if (i && decoration.endsWith(rest.slice(0, i)) && (i === rest.length || /\s/.test(rest[i]))) {
+      rest = rest.slice(i).trimStart(); headerClosed = true;
+    }
+  }
+  rest = rest.trimEnd();
+  // A still-open emphasis marker can wrap the entire header/value line. Remove only its
+  // matching closing marker, preserving literal punctuation in the value (e.g. Ship*).
+  if (!headerClosed && decoration) {
+    let start = decoration.length;
+    const mark = decoration[start - 1];
+    if (closing.includes(mark)) {
+      while (start > 0 && decoration[start - 1] === mark) start--;
+      const wrapper = decoration.slice(start);
+      if (rest.endsWith(wrapper)) rest = rest.slice(0, -wrapper.length).trimEnd();
+    }
+  }
+  // Keep the existing line grammar; these are not additional section delimiters.
+  if (/[\r\u2028\u2029]/.test(rest.trimEnd())) return null;
+  return [name, rest.trimEnd()];
+}
+
+function bullets(lines) {
+  return lines.map((l) => l.replace(/^\s*(?:[-*•]|\d+[.)])\s*/, '').trim()).filter(Boolean);
+}
+
+function stripFence(text) {
+  let body = text.trim();
+  if (body.startsWith('```')) {
+    let i = 3;
+    while (i < body.length && /[a-z]/i.test(body[i])) i++;
+    body = body.slice(i).trimStart();
+  }
+  return body.endsWith('```') ? body.slice(0, -3).trimEnd() : body;
+}
+
+// Ignore explicit no-question placeholders, including a short declarative explanation.
+// Be conservative: punctuation is not required for real questions, and an uncertain suffix
+// remains a question. In particular, "None of these options ..." is not a placeholder.
+export function humanQuestion(value) {
+  const text = String(value || '').trim();
+  if (!text) return null;
+  const plain = text.replace(/[*_`]/g, '').replace(/^[-•]\s+/, '').trim();
+  if (/^[-–—]+[.!]?$/.test(plain)) return null;
+  if (/[?？]/.test(plain)) return text;
+  const match = /^(?:none|n\/?a|not applicable|no (?:further |additional |unanswered )?questions?(?: for (?:the )?human)?)(?:\s*[.,;:!–—-]\s*|$)([\s\S]*)$/i.exec(plain);
+  if (!match) return text;
+  const explanation = match[1].trim();
+  if (!explanation) return null;
+  if (/[\r\u2028\u2029]/.test(explanation)) return text;
+  // These are bookkeeping statements, not a request for an answer. Other suffixes stay live.
+  if (/^(?:treat [^.;:!?]{1,160} as (?:an? )?(?:explicit )?(?:unknown|assumption)s?|(?:all |the )?questions? (?:are |were |have been )?answered|(?:the |this )?(?:information|answer|detail|value) (?:is |remains )?(?:unknown|not provided))[.!]?$/i.test(explanation)
+      && !/\b(?:who|what|when|where|why|how|which|whether|please|confirm|clarify)\b/i.test(explanation)) return null;
+  return text;
+}
+
+// Split the reply into sections keyed by header. Text before the first header is ignored.
+export function parseReply(text) {
+  const body = stripFence(text || '').trim();
+  if (/^\**PASS\**\.?$/i.test(body)) return { pass: true, stance: null, agreeWith: [], disagree: [], new: [], assumptions: [], question: null, raw: text };
+
+  const sections = {};
+  const duplicates = [];
+  let current = null;
+  for (const line of body.split(/\r?\n/)) {
+    const m = header(line, HEADERS);
+    if (m) {
+      current = m[0];
+      if (Object.hasOwn(sections, current)) duplicates.push(current);
+      sections[current] = m[1].trim() ? [m[1].trim()] : [];
+    } else if (current) {
+      sections[current].push(line);
+    }
+  }
+  const one = (k) => (sections[k] || []).join(' ').trim();
+  const list = (k) => bullets((sections[k] || []));
+  const agree = one('AGREE_WITH').replace(/^\[|\]$/g, '').split(/[,;]/).map((s) => s.trim()).filter((s) => s && !/^(none|empty|-)$/i.test(s));
+  const question = one('QUESTION_FOR_HUMAN');
+  return {
+    pass: false,
+    stance: one('STANCE') || null,
+    agreeWith: agree,
+    disagree: list('DISAGREE'),
+    new: list('NEW'),
+    assumptions: list('ASSUMPTIONS'),
+    question: humanQuestion(question),
+    sections: Object.keys(sections),
+    duplicates,
+    raw: text,
+  };
+}
+
+// Options have ids, opt-1 ... opt-N in field-notes order. Every comparison (stance keys, the
+// tally, the chosen option) uses the id; the label is for display. So "Ship" and "Ship later"
+// stay apart, non-Latin labels stay apart, and no label can collide with PASS or "other:".
+export const optionIds = (options) => (options || []).map((label, i) => ({ id: `opt-${i + 1}`, label }));
+export function optionLabel(key, options) {
+  return optionIds(options).find((o) => o.id === key)?.label ?? key;
+}
+
+// The option a piece of text names: its id, its exact label (after NFKC, case and whitespace
+// folding; nothing stripped), or the id followed by its own label ("opt-2: Wait a sprint").
+// Quotes and a trailing full stop are tolerated. Anything else names no option.
+export function optionId(text, options) {
+  if (text == null) return null;
+  const ids = optionIds(options).map((o) => ({ ...o, normalized: normLabel(o.label) }));
+  const match = (s) => {
+    for (const o of ids) if (s === o.id || s === o.normalized) return o.id;
+    const m = /^(opt-\d+)/.exec(s);
+    const o = m && ids.find((x) => x.id === m[1]);
+    if (!o) return null;
+    let label = s.slice(m[1].length).trimStart();
+    if (label && ':=(\u2014\u2013-'.includes(label[0])) label = label.slice(1).trimStart();
+    if (!label || label === o.normalized) return o.id;
+    if (label.endsWith(')') && label.slice(0, -1) === o.normalized) return o.id;
+    return null;
+  };
+  const raw = normLabel(String(text));
+  const exact = match(raw);
+  if (exact) return exact;
+  let end = raw.length, start = 0;
+  while (end && '.;'.includes(raw[end - 1])) end--;
+  // Peel only matching wrappers, testing the literal label at each layer. Removing all
+  // stars/quotes at once can turn a formatted Ship* response into the different option Ship.
+  // Only short cores can name a bounded option; huge wrapper runs still take linear work.
+  const maximum = Math.max(0, ...ids.map((o) => o.normalized.length + o.id.length + 4));
+  for (;;) {
+    while (start < end && raw[start] === ' ') start++;
+    while (end > start && raw[end - 1] === ' ') end--;
+    if (end - start <= maximum) {
+      const pick = match(raw.slice(start, end));
+      if (pick) return pick;
+    }
+    if (end - start < 2 || raw[start] !== raw[end - 1] || !'"\'`*'.includes(raw[start])) return null;
+    start++; end--;
+  }
+}
+
+// A seat's STANCE as a key: an option id, `other: <label>`, or null when it names nothing.
+export function matchStance(stance, options) {
+  if (!stance) return null;
+  const id = optionId(stance, options);
+  if (id) return id;
+  const body = stance.trim(), other = /^other\s*:/i.exec(body);
+  const label = other && body.slice(other[0].length).trim();
+  if (label) return `other: ${label}`;
+  return null;
+}
+
+// Bullet limits are repaired here, not re-prompted: a re-prompt is a whole extra call, and the
+// extra bullets stay in the reply text the board and the other seats read.
+export const BULLET_LIMITS = { disagree: 3, new: 2 };
+
+// Returns {ok, errors[], parsed}. A violation list feeds the single re-prompt; parsed.trimmed
+// names the sections cut back to their limit.
+// trim: false keeps every bullet (a hidden mood's rant is the point, not a list to keep short).
+// requireAgree: false reads a missing AGREE_WITH line in a later round as agreeing with nobody.
+export function validateReply(text, { options, round, trim = true, requireAgree = true }) {
+  const parsed = parseReply(text);
+  const errors = [];
+  for (const h of parsed.duplicates || []) errors.push(`duplicate ${h} section`);
+  if (parsed.pass) return { ok: true, errors, parsed: { ...parsed, stanceKey: 'PASS' } };
+  const stanceKey = matchStance(parsed.stance, options);
+  if (!parsed.stance) errors.push('missing STANCE line');
+  else if (!stanceKey) errors.push(`STANCE "${parsed.stance}" is not an option id (${optionIds(options).map((o) => o.id).join(', ')}) or an exact option label, and is not written as "other: <label>"`);
+  for (const h of ['DISAGREE', 'NEW', 'ASSUMPTIONS']) {
+    if (!(parsed.sections || []).includes(h)) errors.push(`missing ${h} section`);
+  }
+  if (requireAgree && round > 0 && !(parsed.sections || []).includes('AGREE_WITH')) errors.push('missing AGREE_WITH line (use [] if none)');
+  const trimmed = [];
+  for (const [key, limit] of trim ? Object.entries(BULLET_LIMITS) : []) {
+    if (parsed[key].length > limit) { parsed[key] = parsed[key].slice(0, limit); trimmed.push(key.toUpperCase()); }
+  }
+  return { ok: errors.length === 0, errors, parsed: { ...parsed, stanceKey, ...(trimmed.length ? { trimmed } : {}) } };
+}
+
+// ---- The chairman's verdict -----------------------------------------------------------------
+
+// TALLY is still read (verdicts before 0.3.1 have one) but no longer asked for: the tally is
+// counted in code from the seats' final stances, exactly, and writing it cost output tokens.
+export const VERDICT_HEADERS = ['RECOMMENDATION', 'TALLY', 'DISSENT', 'KILL_CRITERIA', 'OPEN_QUESTIONS'];
+export const REQUIRED_VERDICT = ['RECOMMENDATION', 'DISSENT', 'KILL_CRITERIA', 'OPEN_QUESTIONS'];
+
+// The verdict's sections, tolerant of markdown emphasis around a header.
+export function verdictSections(text, duplicates = []) {
+  const sections = {};
+  let cur = null;
+  for (const line of String(text || '').split(/\r?\n/)) {
+    const m = header(line, VERDICT_HEADERS, true);
+    if (m) {
+      cur = m[0];
+      if (Object.hasOwn(sections, cur)) duplicates.push(cur);
+      sections[cur] = m[1] ? [m[1]] : [];
+    } else if (cur) sections[cur].push(line);
+  }
+  return sections;
+}
+
+// The pick on the recommendation's first line: an option id, 'none' (an explicit abstention),
+// or null when the line names neither.
+export function recommendationPick(firstLine, options) {
+  const line = String(firstLine || '').trim();
+  if (/^\**\s*(none|no pick)\s*\.?\**$/i.test(line)) return 'none';
+  return optionId(line, options);
+}
+
+// Since 0.3.0 the verdict has a grammar: every section present and non-empty, and the
+// recommendation's first line is exactly an option id (or its label) or none, with the rationale
+// below it. Returns { ok, errors, pick }.
+export function validateVerdict(text, options) {
+  const duplicates = [];
+  const sections = verdictSections(text, duplicates);
+  const errors = duplicates.map((h) => `duplicate ${h} section`);
+  for (const h of REQUIRED_VERDICT) {
+    if (!sections[h]) errors.push(`missing ${h} section`);
+    else if (!sections[h].some((l) => l.trim())) errors.push(`${h} is empty`);
+  }
+  const first = (sections.RECOMMENDATION || []).find((l) => l.trim()) || '';
+  const pick = recommendationPick(first, options);
+  if (sections.RECOMMENDATION && !pick) errors.push(`the first line of RECOMMENDATION must be one option id (${optionIds(options).map((o) => o.id).join(', ')}) or none, with the rationale on the lines below`);
+  return { ok: errors.length === 0, errors, pick };
+}