@prplkane/roundtable 0.0.0-stage → 0.6.3

package/package.json

@@ -1,6 +1,52 @@
-{
-  "name": "@prplkane/roundtable",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+{
+  "name": "@prplkane/roundtable",
+  "version": "0.6.3",
+  "description": "Local decision reviews with coding-agent CLIs, human input, budget checks and Markdown records.",
+  "keywords": [
+    "claude",
+    "codex",
+    "antigravity",
+    "cli",
+    "debate",
+    "decision",
+    "multi-agent",
+    "subscription"
+  ],
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "roundtable": "src/cli.js"
+  },
+  "files": [
+    "src",
+    "scripts",
+    "skills/roundtable/SKILL.md",
+    "docs/workflow.md",
+    "README.md",
+    "SECURITY.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "start": "node src/server.js",
+    "fake": "node src/server.js --fake",
+    "test": "node --test test/*.test.js",
+    "doctor": "node src/doctor.js",
+    "export": "node scripts/export.mjs",
+    "debate": "node scripts/run-debate.mjs"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/prplkane/roundtable.git"
+  },
+  "homepage": "https://github.com/prplkane/roundtable#readme",
+  "bugs": {
+    "url": "https://github.com/prplkane/roundtable/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/scripts/agent.mjs

@@ -0,0 +1,40 @@
+// JSON CLI; the MCP adapter uses the same client directly.
+import { readFile } from 'node:fs/promises';
+import { BODY_LIMIT } from '../src/validate.js';
+import { HELP, runAgent } from '../src/agent-client.js';
+import { clientError } from '../src/local-http.js';
+
+try {
+  const args = process.argv.slice(2), command = args.shift();
+  if (!command || ['help', '--help', '-h'].includes(command) || args.includes('--help')) { console.log(JSON.stringify(HELP)); }
+  else {
+    if (!Object.hasOwn(HELP.commands, command)) throw new Error('Unknown agent command. Use agent --help.');
+    const flags = {};
+    while (args.length) {
+      const key = args.shift();
+      if (key === '--refresh') { flags.refresh = true; continue; }
+      if (!['--port', '--id', '--input', '--seconds', '--after-round'].includes(key) || !args.length || Object.hasOwn(flags, key.slice(2))) throw new Error('Invalid or repeated option. Use agent --help.');
+      flags[key.slice(2)] = args.shift();
+    }
+    async function input(required = true) {
+      if (!flags.input) { if (!required) return {}; throw new Error('Supply --input file or --input - for JSON on stdin.'); }
+      let text;
+      if (flags.input === '-') {
+        const chunks = []; let size = 0;
+        for await (const chunk of process.stdin) { size += chunk.length; if (size > BODY_LIMIT) throw new Error('Input exceeds 256 KiB.'); chunks.push(chunk); }
+        text = Buffer.concat(chunks).toString('utf8');
+      } else {
+        const bytes = await readFile(flags.input);
+        if (bytes.length > BODY_LIMIT) throw new Error('Input exceeds 256 KiB.');
+        text = bytes.toString('utf8');
+      }
+      try { return JSON.parse(text.replace(/^\uFEFF/, '')); } catch { throw new Error('Input must contain valid JSON.'); }
+    }
+    const body = ['check', 'start', 'answer', 'hold', 'finish', 'stop', 'resume', 'verdict'].includes(command)
+      ? await input(['check', 'start', 'answer', 'hold'].includes(command)) : undefined;
+    console.log(JSON.stringify(await runAgent(command, flags, body)));
+  }
+} catch (error) {
+  console.log(JSON.stringify(clientError(error)));
+  process.exitCode = 1;
+}

package/scripts/export.mjs

@@ -0,0 +1,20 @@
+// node scripts/export.mjs <slug> <target dir>   (npm run export -- <slug> <target dir>)
+// Writes <target>/<slug>.md, the decision record for a saved session, and
+// refreshes the index (README.md, or DECISIONS.md when a README exists that roundtable did not
+// write). Idempotent: re-exporting replaces both. A file in the way that roundtable did not
+// write is refused, never replaced.
+import { openDebateDir } from '../src/store.js';
+import { exportDebate } from '../src/export.js';
+import { dataDirectory } from '../src/history.js';
+
+const [slug, target] = process.argv.slice(2);
+if (!slug || !target) { console.error('usage: node scripts/export.mjs <slug> <target dir>'); process.exit(2); }
+const debatesDir = dataDirectory();
+const store = openDebateDir(debatesDir, slug, { create: false });
+if (!store) { console.error(`no transcript for ${slug} under ${debatesDir}`); process.exit(1); }
+try {
+  const warnings = [];
+  const rows = store.readTranscript({ onWarning: (w) => { warnings.push(w); console.warn(w.message); } });
+  const out = exportDebate(rows, slug, target, { forbid: [debatesDir], warnings });
+  console.log(`${out.path}\n${out.indexPath}  (${out.meta.status}: ${out.meta.chosen})`);
+} catch (e) { console.error(e.message); process.exit(1); }

package/scripts/mcp.mjs

@@ -0,0 +1,175 @@
+// Dependency-free MCP stdio adapter. Shares the review client with the JSON CLI.
+// No provider is called by initialize/tools/list/guide or by starting the local board.
+import { VERSION } from '../src/version.js';
+import { BODY_LIMIT, LIMITS } from '../src/validate.js';
+import { runAgent } from '../src/agent-client.js';
+import { clientError } from '../src/local-http.js';
+import { ensureServer } from '../src/local-server.js';
+
+const integer = ([minimum, maximum]) => ({ type: 'integer', minimum, maximum });
+const object = (properties = {}, required = []) => ({ type: 'object', properties, required, additionalProperties: false });
+const id = { type: 'string', pattern: '^[a-z0-9-]+$', maxLength: 250, description: 'The exact review id returned by start.' };
+const round = integer(LIMITS.critiqueRounds);
+const text = (maxLength, description) => ({ type: 'string', maxLength, ...(description ? { description } : {}) });
+const review = { type: 'object', required: ['fieldNotes', 'seats'], additionalProperties: false, properties: {
+  fieldNotes: { type: 'object', required: ['decision', 'options'], properties: {
+    decision: text(LIMITS.decision), options: { type: 'array', minItems: LIMITS.options[0], maxItems: LIMITS.options[1], items: text(LIMITS.option) },
+    constraints: text(LIMITS.field), known: text(LIMITS.field), assumed: text(LIMITS.field), reversibility: text(LIMITS.field), deadline: text(LIMITS.field),
+  }, additionalProperties: false },
+  seats: { type: 'array', minItems: LIMITS.seats[0], maxItems: LIMITS.seats[1], items: { type: 'object', required: ['vendor', 'lens'],
+    properties: { vendor: text(LIMITS.seatField), lens: text(LIMITS.seatField), model: text(LIMITS.seatField), effort: text(LIMITS.seatField) }, additionalProperties: true } },
+  chairman: { type: 'object', properties: { vendor: text(LIMITS.seatField), model: text(LIMITS.seatField), effort: text(LIMITS.seatField) }, additionalProperties: true },
+  options: { type: 'object', properties: {
+    critiqueRounds: { ...round, description: 'Default 1. Use 0 for a quick comparison; 2 for deeper examination within agreed limits. Consensus can stop early.' },
+    unattended: { type: 'boolean', description: 'True only when nobody will answer. Attended reviews auto-continue after the answer window.' },
+    questionWaitMs: integer(LIMITS.questionWaitMs),
+    autoContinueMs: integer(LIMITS.autoContinueMs),
+    budget: { type: 'object', additionalProperties: true, description: 'Per-provider caps, for example {"claude":{"tokens":160000}}. Check projected calls first.' },
+  }, additionalProperties: true },
+} };
+const descriptors = [
+  ['guide', 'Read the Roundtable workflow, request recipe and question/completion rules. No model calls.', object(), true],
+  ['status', 'Check provider setup, or read a review by id. Starts the local board if needed. refresh checks free provider status; no model call.', object({ id, refresh: { type: 'boolean' } }), true],
+  ['check', 'Validate a proposed review and estimate its calls/tokens before starting. Makes no model call.', object({ review }, ['review']), true],
+  ['start', 'Start the requested Roundtable review after check. Makes model calls within its limits. Returns an id, NOT a recommendation; keep calling wait through the chairman.', object({ review }, ['review']), false],
+  ['wait', 'Wait up to 25 seconds for questions or completion. A wait timeout is progress, not completion. After showing questions, pass afterRound to await the next step without repeating them.', object({ id, seconds: integer(LIMITS.waitSeconds), afterRound: round }, ['id']), true],
+  ['answer', 'Submit only the user\'s real answers to the current round; read status first. May resume model calls. Silence is handled by the timer, not blank answers.', object({ id, round,
+    answers: { type: 'array', maxItems: LIMITS.answers, items: object({ id: text(LIMITS.questionId), text: text(LIMITS.answer) }, ['id', 'text']) }, message: text(LIMITS.message) }, ['id', 'round']), false],
+  ['hold', 'Give the user another bounded answer window when they need more time. No model call. Never use as an automatic keepalive.', object({ id, round }, ['id', 'round']), false],
+  ['finish', 'On the user\'s request, end discussion and call the chairman with collected replies. Keep waiting for the verdict.', object({ id, message: text(LIMITS.message) }, ['id']), false],
+  ['stop', 'Cancel this review, including an in-flight chairman, when the user asks to stop. Does not synthesize a recommendation.', object({ id, message: text(LIMITS.message) }, ['id']), false],
+  ['resume', 'Resume an interrupted review when requested. Can make model calls; never automatically retry an uncertain write.', object({ id, message: text(LIMITS.message) }, ['id']), false],
+  ['verdict', 'Request a missing or failed chairman verdict when authorized and available in actions. Can make a model call; wait for completion.', object({ id }, ['id']), false],
+];
+const TOOLS = descriptors.map(([command, description, inputSchema, readOnlyHint]) => ({
+  name: `roundtable_${command}`, description, inputSchema,
+  annotations: { readOnlyHint, destructiveHint: false, idempotentHint: readOnlyHint, openWorldHint: !['guide', 'wait', 'hold', 'stop'].includes(command) },
+}));
+
+function validate(value, schema, field = 'arguments') {
+  const kind = schema.type;
+  if (kind === 'object') {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error(`${field} must be an object.`);
+    for (const key of schema.required || []) if (!Object.hasOwn(value, key)) throw new Error(`${field}.${key} is required.`);
+    for (const [key, v] of Object.entries(value)) {
+      if (Object.hasOwn(schema.properties || {}, key)) validate(v, schema.properties[key], `${field}.${key}`);
+      else if (schema.additionalProperties === false) throw new Error(`Unknown field ${field}.${key}.`);
+    }
+  } else if (kind === 'array') {
+    if (!Array.isArray(value) || value.length < (schema.minItems || 0) || value.length > (schema.maxItems ?? Infinity)) throw new Error(`${field} has an invalid list length.`);
+    value.forEach((v, i) => validate(v, schema.items, `${field}[${i}]`));
+  } else if (kind === 'string') {
+    if (typeof value !== 'string' || value.length > (schema.maxLength ?? Infinity) || schema.pattern && !new RegExp(schema.pattern).test(value)) throw new Error(`${field} is invalid text.`);
+  } else if (kind === 'integer') {
+    if (!Number.isInteger(value) || value < schema.minimum || value > schema.maximum) throw new Error(`${field} must be an integer from ${schema.minimum} to ${schema.maximum}.`);
+  } else if (typeof value !== kind) throw new Error(`${field} must be ${kind}.`);
+}
+
+function options(args) {
+  const out = { fake: false, start: true };
+  while (args.length) {
+    const arg = args.shift();
+    if (arg === '--fake') out.fake = true;
+    else if (arg === '--no-start') out.start = false;
+    else if (arg === '--port' && args.length && out.port == null) out.port = Number(args.shift());
+    else throw new Error('Use roundtable mcp [--port N] [--fake] [--no-start].');
+  }
+  out.port ??= out.fake ? 4748 : 4747;
+  if (!Number.isInteger(out.port) || out.port < LIMITS.port[0] || out.port > LIMITS.port[1]) throw new Error('Invalid loopback port.');
+  return out;
+}
+
+async function serve(config) {
+  let starting;
+  async function ready(signal) {
+    signal.throwIfAborted();
+    // Share startup across simultaneous tools; each cancelled caller stops before dispatch.
+    starting ??= ensureServer(config).finally(() => { starting = null; });
+    let cancel;
+    const cancelled = new Promise((_, reject) => { cancel = () => reject(signal.reason); signal.addEventListener('abort', cancel, { once: true }); });
+    try { return await Promise.race([starting, cancelled]); }
+    finally { signal.removeEventListener('abort', cancel); }
+  }
+  async function call(name, input, signal) {
+    const tool = TOOLS.find((t) => t.name === name);
+    if (!tool) throw new Error('Unknown Roundtable tool.');
+    validate(input, tool.inputSchema);
+    if (Buffer.byteLength(JSON.stringify(input)) > BODY_LIMIT) throw new Error('Tool arguments exceed 256 KiB.');
+    const command = name.slice('roundtable_'.length);
+    if (command !== 'guide') await ready(signal);
+    if (signal.aborted) throw new Error('Tool request cancelled before dispatch.');
+    const flags = { port: config.port, id: input.id, refresh: input.refresh, seconds: input.seconds, 'after-round': input.afterRound };
+    let body;
+    if (['start', 'check'].includes(command)) body = input.review;
+    else if (['answer', 'hold', 'finish', 'stop', 'resume', 'verdict'].includes(command)) { body = { ...input }; delete body.id; }
+    const result = { service: 'roundtable', transport: 'mcp', ok: true, ...await runAgent(command, flags, body, signal) };
+    if (result.id) {
+      if (['ask_user', 'await_user'].includes(result.nextAction?.type)) {
+        result.nextAction.tool = 'roundtable_answer';
+        result.nextAction.arguments = { id: result.id, ...result.nextAction.answerTemplate };
+        result.nextAction.wait = { tool: 'roundtable_wait', arguments: { id: result.id, afterRound: result.gate.round } };
+        result.nextAction.extend = { tool: 'roundtable_hold', arguments: { id: result.id, round: result.gate.round } };
+      } else if (!result.nextAction || result.nextAction.type === 'wait') result.nextAction = { type: 'wait', tool: 'roundtable_wait', arguments: { id: result.id }, instruction: 'Keep waiting through discussion and chairman synthesis. Only done with verdict.status ready is a completed recommendation.' };
+      result.completed = result.status === 'done' && result.verdict?.status === 'ready';
+    }
+    return result;
+  }
+
+  let initialized = false, input = Buffer.alloc(0), closing = false;
+  const requests = new Map();
+  const send = (value) => { if (!closing) process.stdout.write(`${JSON.stringify(value)}\n`); };
+  const error = (id, code, message) => send({ jsonrpc: '2.0', id, error: { code, message } });
+  async function handle(message) {
+    if (!message || Array.isArray(message) || message.jsonrpc !== '2.0' || typeof message.method !== 'string' || message.id != null && !['number', 'string'].includes(typeof message.id)) { error(null, -32600, 'Invalid JSON-RPC request.'); return; }
+    if (!Object.hasOwn(message, 'id')) {
+      if (message.method === 'notifications/cancelled') requests.get(message.params?.requestId)?.abort();
+      return;
+    }
+    const { id, method, params = {} } = message;
+    if (requests.has(id)) { error(id, -32600, 'Request id is already in flight.'); return; }
+    if (method === 'initialize') {
+      if (initialized) { error(id, -32600, 'Already initialized.'); return; }
+      initialized = true;
+      send({ jsonrpc: '2.0', id, result: { protocolVersion: ['2024-11-05', '2025-03-26', '2025-06-18', '2025-11-25'].includes(params?.protocolVersion) ? params.protocolVersion : '2025-11-25',
+        capabilities: { tools: { listChanged: false } }, serverInfo: { name: 'roundtable', version: VERSION },
+        instructions: 'Use roundtable_guide and status before check/start. Keep waiting until the chairman finishes. Present ask_user questions with the host input tool or chat; silence auto-continues without answers. Never replace Roundtable with your own agents or accept a recommendation for the user.' } }); return;
+    }
+    if (method === 'ping') { send({ jsonrpc: '2.0', id, result: {} }); return; }
+    if (!initialized) { error(id, -32000, 'Initialize first.'); return; }
+    if (method === 'tools/list') { send({ jsonrpc: '2.0', id, result: { tools: TOOLS } }); return; }
+    if (method !== 'tools/call') { error(id, -32601, 'Method not found.'); return; }
+    if (requests.size >= 16) { error(id, -32000, 'Too many concurrent tool calls.'); return; }
+    const controller = new AbortController(); requests.set(id, controller);
+    try {
+      let result;
+      try { result = await call(params?.name, params?.arguments ?? {}, controller.signal); }
+      catch (e) { result = { service: 'roundtable', transport: 'mcp', ...clientError(e) }; }
+      if (!controller.signal.aborted) send({ jsonrpc: '2.0', id, result: { content: [{ type: 'text', text: JSON.stringify(result) }], structuredContent: result, isError: result.ok === false } });
+    } finally { requests.delete(id); }
+  }
+  const close = () => { closing = true; for (const c of requests.values()) c.abort(); };
+  process.stdin.on('data', (chunk) => {
+    input = Buffer.concat([input, chunk]);
+    let end;
+    while ((end = input.indexOf(10)) >= 0) {
+      const line = input.subarray(0, end); input = input.subarray(end + 1);
+      if (line.length > BODY_LIMIT + 4096) { error(null, -32600, 'Message exceeds size limit.'); close(); process.exitCode = 1; process.stdin.destroy(); return; }
+      if (!line.toString('utf8').trim()) continue;
+      let parsed;
+      try { parsed = JSON.parse(line.toString('utf8')); } catch { error(null, -32700, 'Invalid JSON.'); continue; }
+      void handle(parsed).catch(() => error(parsed?.id ?? null, -32603, 'Internal protocol error.'));
+    }
+    if (input.length > BODY_LIMIT + 4096) { error(null, -32600, 'Message exceeds size limit.'); close(); process.exitCode = 1; process.stdin.destroy(); }
+  });
+  process.stdin.on('end', close);
+  process.stdout.on('error', close);
+  process.on('SIGINT', () => { close(); process.exit(0); });
+  process.on('SIGTERM', () => { close(); process.exit(0); });
+}
+
+if (process.argv.slice(2).some((a) => ['--help', '-h', 'help'].includes(a))) {
+  console.log('roundtable mcp [--port N] [--fake] [--no-start]\nMCP over newline-delimited JSON-RPC on stdio. Normally starts a hidden local board when needed. --fake uses scripted providers and port 4748. --no-start requires an existing board. No model call is made until a review action requests it.');
+} else {
+  try { await serve(options(process.argv.slice(2))); }
+  catch (e) { console.error(e.message); process.exitCode = 1; }
+}

package/scripts/run-debate.mjs

@@ -0,0 +1,70 @@
+// Drive one debate headless against a running server and print what the strip would show.
+// Gates are answered after a short pause (a note for round 0 if --note is given), so a real
+// multi-seat run can be recorded without the browser. Usage:
+//   node scripts/run-debate.mjs --port 4747 --token <hex> --rounds 1 --note "..." < debate.json
+// The token is on the server's startup line; ROUNDTABLE_TOKEN works too.
+// stdin: the same JSON body the setup screen posts ({fieldNotes, seats, chairman, options}).
+import { readFileSync, existsSync } from 'node:fs';
+import path from 'node:path';
+import { dataDirectory } from '../src/history.js';
+
+const arg = (name, dflt) => { const i = process.argv.indexOf(`--${name}`); return i > 0 ? process.argv[i + 1] : dflt; };
+const PORT = Number(arg('port', 4747));
+const NOTE = arg('note', '');
+const PAUSE = Number(arg('pause', 3000));
+const base = `http://127.0.0.1:${PORT}`;
+const SEND = { 'content-type': 'application/json', 'x-roundtable-token': arg('token', process.env.ROUNDTABLE_TOKEN || '') };
+
+const body = JSON.parse(readFileSync(0, 'utf8'));
+if (arg('rounds')) body.options = { ...(body.options || {}), critiqueRounds: Number(arg('rounds')) };
+
+const res = await fetch(`${base}/api/debates`, { method: 'POST', headers: SEND, body: JSON.stringify(body) });
+const out = await res.json();
+if (!res.ok) { console.error('refused:', out.error); process.exit(1); }
+const slug = out.slug;
+console.log(`debate ${slug}`);
+
+const t0 = Date.now();
+const stamp = () => `${String(Math.round((Date.now() - t0) / 1000)).padStart(4)}s`;
+const usage = [];
+const calib = [];
+const stream = await fetch(`${base}/api/debates/${slug}/events`);
+const reader = stream.body.getReader();
+const dec = new TextDecoder();
+let buf = '';
+let done = false;
+while (!done) {
+  const { value, done: end } = await reader.read();
+  if (end) break;
+  buf += dec.decode(value, { stream: true });
+  let i;
+  while ((i = buf.indexOf('\n\n')) >= 0) {
+    const chunk = buf.slice(0, i); buf = buf.slice(i + 2);
+    const line = chunk.split('\n').find((l) => l.startsWith('data: '));
+    if (!line) continue;
+    const e = JSON.parse(line.slice(6));
+    switch (e.type) {
+      case 'started': console.log(stamp(), 'seats:', e.seats.map((s) => `${s.label}/${s.lens}${s.model ? '/' + s.model : ''}${s.effort ? '/' + s.effort : ''}`).join(', ')); break;
+      case 'attempt': if (e.usage) usage.push(e); console.log(stamp(), `  call ${e.kind} r${e.round} ${e.seat.label || e.seat.vendor}: ${e.usage ? `in ${e.usage.input} cache ${e.usage.cacheRead + e.usage.cacheWrite} out ${e.usage.output}${e.usage.cost != null ? ' $' + e.usage.cost.toFixed(2) : ''}` : 'usage unknown'}`); break;
+      case 'reply': console.log(stamp(), `r${e.round} ${e.seat.label} (${e.seat.lens}) -> ${e.stanceKey}${e.question ? ' | Q: ' + e.question : ''}${e.failed ? ' | FAILED ' + e.errors.join('; ') : ''}`); break;
+      case 'quota': console.log(stamp(), `quota ${e.vendor}:`, e.quota.windows.map((w) => `${w.label} ${(w.used * 100).toFixed(1)}%`).join(' ')); break;
+      case 'calibration': if (e.round != null) { calib.push(e); console.log(stamp(), `calibration ${e.key} round ${e.round}: ${e.tokens} tokens ->`, e.deltas.filter((d) => d.valid).map((d) => `${d.label} +${(d.delta * 100).toFixed(2)}%`).join(' ') || 'no valid delta'); } break;
+      case 'gate': {
+        console.log(stamp(), `gate ${e.reason} (${e.mode})${e.stop ? ' stop=' + e.stop : ''}${e.questions.length ? ' questions: ' + e.questions.map((q) => q.lens + ': ' + q.question).join(' | ') : ''}`);
+        setTimeout(() => fetch(`${base}/api/debates/${slug}/continue`, { method: 'POST', headers: SEND, body: JSON.stringify({ message: e.round === 0 ? NOTE : '' }) }), PAUSE);
+        break;
+      }
+      case 'reopen': console.log(stamp(), 'reopened after a note at a unanimous round 0'); break;
+      case 'stopped': console.log(stamp(), `stopped: ${e.reason} after ${e.rounds} rounds`); break;
+      case 'verdict': console.log(stamp(), `verdict by ${e.seat?.vendor || 'nobody'}${e.seat?.model ? '/' + e.seat.model : ''}`); break;
+      case 'error': console.log(stamp(), 'ERROR', e.message); done = true; break;
+      case 'done': done = true; break;
+    }
+  }
+}
+const per = {};
+for (const e of usage) { const k = e.seat.label ? `${e.seat.label} (${e.seat.lens})` : 'chairman'; const u = (per[k] ??= { in: 0, cache: 0, out: 0, cost: 0 }); u.in += e.usage.input; u.cache += e.usage.cacheRead + e.usage.cacheWrite; u.out += e.usage.output; u.cost += e.usage.cost || 0; }
+console.log('\nper seat:'); for (const [k, u] of Object.entries(per)) console.log(`  ${k}: in ${u.in} cache ${u.cache} out ${u.out}${u.cost ? ' $' + u.cost.toFixed(2) : ''}`);
+const f = path.join(dataDirectory(), '_calibration.json');
+if (existsSync(f)) console.log('\ncalibration file:', readFileSync(f, 'utf8'));
+process.exit(0);

package/scripts/server.mjs

@@ -0,0 +1,28 @@
+import { inspectServer, ensureServer, stopServer } from '../src/local-server.js';
+import { clientError } from '../src/local-http.js';
+import { LIMITS } from '../src/validate.js';
+
+const args = process.argv.slice(2), command = args.shift();
+if (!command || ['help', '--help', '-h'].includes(command) || args.includes('--help')) {
+  console.log('roundtable server status|start|stop|restart [--port N] [--fake]\nManage the hidden local board. Stop/restart refuses active reviews and never cancels them. Use the same data directory and mode as the running board.');
+} else {
+  try {
+    if (!['status', 'start', 'stop', 'restart'].includes(command)) throw new Error('Unknown server command. Use roundtable server --help.');
+    const config = { fake: false };
+    while (args.length) {
+      const arg = args.shift();
+      if (arg === '--fake' && !config.fake) config.fake = true;
+      else if (arg === '--port' && args.length && config.port == null) config.port = Number(args.shift());
+      else throw new Error('Invalid or repeated server option. Use roundtable server --help.');
+    }
+    config.port ??= config.fake ? 4748 : 4747;
+    if (!Number.isInteger(config.port) || config.port < LIMITS.port[0] || config.port > LIMITS.port[1]) throw new Error('Invalid loopback port.');
+    let result;
+    if (command === 'status') result = { ok: true, server: await inspectServer(config, { allowOlder: true }) };
+    else {
+      if (['stop', 'restart'].includes(command)) result = await stopServer(config);
+      if (['start', 'restart'].includes(command)) result = { ok: true, server: await ensureServer(config) };
+    }
+    console.log(JSON.stringify(result));
+  } catch (e) { console.log(JSON.stringify(clientError(e))); process.exitCode = 1; }
+}

package/scripts/setup.mjs

@@ -0,0 +1,182 @@
+// Explicit, user-scoped host setup. No install hook, vendor CLI or model invocation.
+import { readFile, writeFile, mkdir, rename, unlink, lstat, open, access, constants } from 'node:fs/promises';
+import { createHash, randomUUID } from 'node:crypto';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { MCP_BEGIN as BEGIN, MCP_END as END, tomlConnection, replaceTomlConnection } from '../src/setup-toml.js';
+
+const ROOT = fileURLToPath(new URL('../', import.meta.url));
+const HELP = `roundtable setup --client codex|claude|agy|all [--check|--remove] [--port N] [--fake|--live] [--home directory]
+
+Connect the installed Roundtable MCP tools and skill for all projects of the selected assistant.
+Run once after a global npm install. Restart the assistant or reload its MCP connections afterward.
+Run again after an update to refresh the skill and connection. --check inspects without changing files.
+--remove removes only this setup's unchanged entries. User edits and unrelated settings are preserved.
+--fake selects demo mode; --live selects live mode. Updates preserve the saved mode and port
+unless explicitly changed. A new connection defaults to live port 4747 (demo: 4748).
+--home selects an isolated user home for testing; normally the current user's home is used.
+CODEX_HOME and CLAUDE_CONFIG_DIR are honored unless --home is supplied. No model call is made.
+`;
+const hash = (s) => createHash('sha256').update(s).digest('hex');
+const plain = (v) => v && typeof v === 'object' && !Array.isArray(v);
+
+function parse(args) {
+  const out = { clients: [], home: os.homedir(), explicitHome: false, check: false, remove: false };
+  while (args.length) {
+    const key = args.shift();
+    if (key === '--client' && args.length) out.clients.push(args.shift());
+    else if (key === '--home' && args.length && !out.explicitHome) { out.home = path.resolve(args.shift()); out.explicitHome = true; }
+    else if (key === '--port' && args.length && out.port == null) out.port = Number(args.shift());
+    else if (['--fake', '--live'].includes(key) && out.fake == null) out.fake = key === '--fake';
+    else if (['--check', '--remove'].includes(key) && !out[key.slice(2)]) out[key.slice(2)] = true;
+    else throw new Error('Invalid or repeated setup option. Use roundtable setup --help.');
+  }
+  if (!out.clients.length || out.clients.some((c) => !['codex', 'claude', 'agy', 'all'].includes(c))) throw new Error('Choose --client codex, claude, agy or all.');
+  out.clients = [...new Set(out.clients.includes('all') ? ['codex', 'claude', 'agy'] : out.clients)];
+  if (out.check && out.remove) throw new Error('Choose either --check or --remove.');
+  if (out.port != null && (!Number.isInteger(out.port) || out.port < 1 || out.port > 65535)) throw new Error('Port must be from 1 to 65535.');
+  return out;
+}
+
+async function readTarget(file) {
+  try {
+    const stat = await lstat(file);
+    if (!stat.isFile() || stat.isSymbolicLink()) throw new Error(`Refusing to replace a linked or non-file configuration: ${file}`);
+    return { text: await readFile(file, 'utf8'), mode: stat.mode & 0o777 };
+  } catch (e) { if (e.code === 'ENOENT') return null; throw e; }
+}
+function json(raw, label) {
+  let value;
+  try { value = raw ? JSON.parse(raw.text.replace(/^\uFEFF/, '')) : {}; } catch { throw new Error(`${label} contains invalid JSON; it was not changed.`); }
+  if (!plain(value)) throw new Error(`${label} must contain a JSON object; it was not changed.`);
+  return value;
+}
+const same = (a, b) => a?.text === b?.text;
+async function writeTarget(file, before, after) {
+  if (!same(before, await readTarget(file))) throw new Error(`Configuration changed during setup; retry after the other editor finishes: ${file}`);
+  if (after == null) { if (before) await unlink(file); return; }
+  if (before?.text === after.text) return;
+  await mkdir(path.dirname(file), { recursive: true, mode: 0o700 });
+  const tmp = `${file}.roundtable-${randomUUID()}.tmp`;
+  try {
+    await writeFile(tmp, after.text, { flag: 'wx', mode: after.mode ?? before?.mode ?? 0o600 });
+    if (!same(before, await readTarget(file))) throw new Error(`Configuration changed during setup; it was not replaced: ${file}`);
+    await rename(tmp, file);
+  }
+  finally { await unlink(tmp).catch((e) => { if (e.code !== 'ENOENT') throw e; }); }
+}
+
+function hostFiles(client, opts) {
+  const h = opts.home;
+  if (client === 'codex') {
+    const codex = !opts.explicitHome && process.env.CODEX_HOME ? path.resolve(process.env.CODEX_HOME) : path.join(h, '.codex');
+    return { config: path.join(codex, 'config.toml'), skill: path.join(codex, 'skills', 'roundtable', 'SKILL.md'), kind: 'toml' };
+  }
+  if (client === 'claude') {
+    const custom = !opts.explicitHome && process.env.CLAUDE_CONFIG_DIR ? path.resolve(process.env.CLAUDE_CONFIG_DIR) : null;
+    return { config: custom ? path.join(custom, '.claude.json') : path.join(h, '.claude.json'),
+      skill: path.join(custom || path.join(h, '.claude'), 'skills', 'roundtable', 'SKILL.md'), kind: 'json' };
+  }
+  return { config: path.join(h, '.gemini', 'config', 'mcp_config.json'), skill: path.join(h, '.gemini', 'config', 'skills', 'roundtable', 'SKILL.md'), kind: 'json' };
+}
+
+function configEntry(raw, kind) {
+  if (kind === 'json') {
+    const parsed = json(raw, 'Assistant configuration');
+    if (parsed.mcpServers != null && !plain(parsed.mcpServers)) throw new Error('mcpServers must be an object; configuration was not changed.');
+    return { parsed, entry: parsed.mcpServers?.roundtable === undefined ? null : JSON.stringify(parsed.mcpServers.roundtable) };
+  }
+  return tomlConnection(raw?.text || '');
+}
+function updateConfig(current, kind, entry) {
+  if (kind === 'json') {
+    const parsed = structuredClone(current.parsed);
+    if (entry == null) { if (parsed.mcpServers) { delete parsed.mcpServers.roundtable; if (!Object.keys(parsed.mcpServers).length) delete parsed.mcpServers; } }
+    else { parsed.mcpServers ??= {}; parsed.mcpServers.roundtable = JSON.parse(entry); }
+    return `${JSON.stringify(parsed, null, 2)}\n`;
+  }
+  return replaceTomlConnection(current, entry);
+}
+
+async function executableExists(command) {
+  if (!command || !path.isAbsolute(command)) return false;
+  try {
+    await access(command, constants.X_OK);
+    const stat = await lstat(command);
+    return stat.isFile() || stat.isSymbolicLink();
+  } catch { return false; }
+}
+
+async function setup(opts) {
+  const receiptFile = path.join(opts.home, '.roundtable', 'integrations.json');
+  let lock;
+  if (!opts.check) {
+    await mkdir(path.dirname(receiptFile), { recursive: true, mode: 0o700 });
+    try { lock = await open(`${receiptFile}.lock`, 'wx', 0o600); }
+    catch (e) { if (e.code === 'EEXIST') throw new Error('Another setup holds the integration lock. If it crashed, remove integrations.json.lock before retrying.'); throw e; }
+  }
+  try {
+    const oldReceipt = await readTarget(receiptFile), receipt = json(oldReceipt, 'Roundtable integration receipt');
+    receipt.clients ??= {};
+    if (!plain(receipt.clients)) throw new Error('Invalid integration receipt; no configuration changed.');
+    const skillText = await readFile(path.join(ROOT, 'skills', 'roundtable', 'SKILL.md'), 'utf8');
+    const command = process.execPath;
+    const changes = [], results = [];
+    for (const client of opts.clients) {
+      const files = hostFiles(client, opts);
+      const [configRaw, skillRaw] = await Promise.all([readTarget(files.config), readTarget(files.skill)]);
+      const current = configEntry(configRaw, files.kind), saved = receipt.clients[client];
+      const sameLocation = saved && saved.config === files.config && saved.skill === files.skill;
+      // A profile override selects a different host, not permission to overwrite the old one.
+      if (saved && !sameLocation) throw new Error(`${client}: the host profile moved. Remove the old connection using its original profile before connecting this one.`);
+      const configMatches = sameLocation && current.entry != null && hash(current.entry) === saved.configHash;
+      const skillMatches = sameLocation && skillRaw != null && hash(skillRaw.text) === saved.skillHash;
+      const intact = configMatches && skillMatches;
+      if (opts.check) {
+        let scriptExists = false, nodeExists = false;
+        if (saved?.script) scriptExists = !!await readTarget(saved.script);
+        // Old receipts predate the command field; read it only from an unchanged owned entry.
+        const node = saved?.command || (configMatches ? files.kind === 'json' ? current.parsed.mcpServers.roundtable.command
+          : JSON.parse(/^command = (.+)$/m.exec(current.entry)?.[1] || 'null') : null);
+        nodeExists = await executableExists(node);
+        results.push({ client, connected: !!intact && scriptExists && nodeExists, config: files.config, skill: files.skill,
+          ...(intact && scriptExists && nodeExists ? {} : { issue: !nodeExists && saved ? 'The configured Node executable is missing or not executable. Rerun setup with a working Node installation.'
+            : 'Connection missing, edited, or installed script moved. Rerun setup to repair missing files; reconcile edited files first.' }) });
+        continue;
+      }
+      if (saved && (current.entry != null && !configMatches || skillRaw != null && !skillMatches) || !saved && (current.entry != null || skillRaw)) throw new Error(`${client}: existing Roundtable settings or skill were edited or are unmanaged. They were preserved; reconcile them before setup.`);
+      if (opts.remove && !saved) { results.push({ client, removed: false, reason: 'No managed connection.' }); continue; }
+      const fake = opts.fake ?? (saved?.mode === 'demo');
+      const port = opts.port ?? (opts.fake == null ? saved?.port : null) ?? (fake ? 4748 : 4747);
+      const args = [path.join(ROOT, 'scripts', 'mcp.mjs'), '--port', String(port), ...(fake ? ['--fake'] : [])];
+      const entry = opts.remove ? null : files.kind === 'json' ? JSON.stringify({ command, args })
+        : `${BEGIN}\n[mcp_servers.roundtable]\ncommand = ${JSON.stringify(command)}\nargs = ${JSON.stringify(args)}\n${END}`;
+      if (!opts.remove || current.entry != null) changes.push({ file: files.config, before: configRaw, after: { text: updateConfig(current, files.kind, entry) } });
+      changes.push({ file: files.skill, before: skillRaw, after: opts.remove ? null : { text: skillText } });
+      if (opts.remove) delete receipt.clients[client];
+      else receipt.clients[client] = { ...files, configHash: hash(entry), skillHash: hash(skillText), command, script: args[0], port, mode: fake ? 'demo' : 'live' };
+      results.push({ client, ...(opts.remove ? { removed: true } : { connected: true }), config: files.config, skill: files.skill });
+    }
+    if (!opts.check) {
+      changes.push({ file: receiptFile, before: oldReceipt, after: { text: `${JSON.stringify(receipt, null, 2)}\n` } });
+      const applied = [];
+      try { for (const change of changes) { await writeTarget(change.file, change.before, change.after); applied.push(change); } }
+      catch (e) {
+        let rollbackFailed = false;
+        for (const c of applied.reverse()) { try { await writeTarget(c.file, c.after, c.before); } catch { rollbackFailed = true; } }
+        throw new Error(`${e.message}${rollbackFailed ? ' Some files changed concurrently; inspect the connection before retrying.' : ' Previous file contents restored.'}`);
+      }
+    }
+    return { ok: !opts.check || results.every((r) => r.connected), clients: results,
+      next: opts.check ? 'A connection check makes no model call. Use roundtable_status in the assistant to verify tool availability.'
+        : opts.remove ? 'Restart the assistant or reload its MCP connections to remove the tools.'
+          : 'Restart the assistant or reload its MCP connections. From any project, ask it to use Roundtable; it should call roundtable_guide, status, check, start and wait for the chairman. Connecting a host does not authorize using it as a review provider.' };
+  } finally { if (lock) { await lock.close(); await unlink(`${receiptFile}.lock`); } }
+}
+
+if (!process.argv[2] || process.argv.slice(2).some((a) => ['--help', '-h', 'help'].includes(a))) console.log(HELP);
+else {
+  try { const result = await setup(parse(process.argv.slice(2))); console.log(JSON.stringify(result)); if (!result.ok) process.exitCode = 1; }
+  catch (e) { console.log(JSON.stringify({ ok: false, error: e.message })); process.exitCode = 1; }
+}