@prplkane/roundtable 0.6.3 → 0.6.4

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 0.6.4
+
+### Terminal
+
+- Report only the provider CLIs found on this machine: `roundtable doctor` lists missing ones
+  in a single line instead of a block each (`--vendor <name>` still shows the full block), and
+  foreground startup prints a `providers:` line in the seat colours instead of a failed quota
+  read for every CLI that is not installed.
+- Always print how to open the board and that Ctrl+C stops it, including with `--no-open`.
+- Say plainly when the port cannot be taken: in use, or a sandbox that forbids a local server
+  (`EPERM`), with the `roundtable server start` way out. The MCP tools and `roundtable server
+  start` report that last line within seconds instead of waiting out the readiness timeout,
+  while two hosts starting the board at once both get the one that won the port.
+- Blink the block cursor beside the wordmark where the terminal allows blinking text, and show
+  vendor names in their seat colours.
+
 ## 0.6.3
 
 ### Assistant integration

package/README.md

@@ -69,9 +69,10 @@ For a source snapshot before its npm release, use
 `npm install -g https://github.com/prplkane/roundtable/archive/refs/heads/main.tar.gz`.
 
 Interactive `roundtable --help`, `roundtable` and `roundtable fake` show the app's pixel logo
-tile in orchid, with the wordmark and installed version beside it. Narrow terminals and
-terminals without UTF-8 use a short title; `NO_COLOR=1` disables color. Redirected output,
-CI, dumb terminals, MCP and JSON commands omit the decoration.
+tile in orchid, with the wordmark, a blinking cursor and the installed version beside it, then
+the provider CLIs found on this machine in their seat colors. Narrow terminals and terminals
+without UTF-8 use a short title; `NO_COLOR=1` disables color. Redirected output, CI, dumb
+terminals, MCP and JSON commands omit the decoration.
 
 ### Try the demo
 

package/docs/workflow.md

@@ -160,6 +160,23 @@ requested action needs them. There is no Roundtable cloud connection or API key
 Keep the provider CLI executables on the assistant's `PATH`; after changing a Node version or
 moving its installation, rerun setup and reload the assistant.
 
+Some assistants run commands in a sandbox that forbids opening a local port. A `roundtable`
+command run inside such a shell cannot start the board: it dies with `listen EPERM
+127.0.0.1:4747`, and the command reports that line. Codex on Linux has shown this. Check
+first that the MCP connection itself is loaded (`codex mcp list`, then `/mcp` in Codex), since
+the MCP tools are started by the assistant rather than by its sandboxed shell. If the tools
+still cannot start the board, start it once from a normal terminal:
+
+```bash
+roundtable server start
+```
+
+It keeps running in the background and `roundtable server status` shows it; the tools then
+only connect to it. Stop it with `roundtable server stop` when no review is active. If a tool
+still cannot reach a board that is running, that sandbox blocks loopback connections too, and
+the assistant cannot use Roundtable from inside it; report it as an issue with the assistant,
+version and OS.
+
 To check the workflow without a provider account, use `roundtable setup --client codex --fake`
 before restarting the assistant and request a scripted demo review. This uses port 4748 and
 makes no model calls. Switch back with `roundtable setup --client codex --live` and reload again.
@@ -168,10 +185,12 @@ the board, or run `roundtable fake` for a foreground demo. If the board is alrea
 the background, open its URL instead of starting a second server.
 
 Foreground board startup and top-level help show the app's pixel logo tile in orchid, with
-the wordmark and installed version beside it. The tile is drawn with half-block characters,
-so it needs a UTF-8 terminal; other locales, and `ROUNDTABLE_ASCII=1`, get the wordmark
-alone. Narrow terminals use a short title, `NO_COLOR=1` removes color, and redirected
-output, CI, `TERM=dumb`, MCP and JSON commands omit it.
+the wordmark, a blinking block cursor and the installed version beside it. The tile is drawn
+with half-block characters, so it needs a UTF-8 terminal; other locales, and
+`ROUNDTABLE_ASCII=1`, get the wordmark alone. Startup then lists the provider CLIs found on
+`PATH`, each in its seat color; `roundtable doctor` names the missing ones in one line.
+Narrow terminals use a short title, `NO_COLOR=1` removes color, and redirected output, CI,
+`TERM=dumb`, MCP and JSON commands omit the decoration.
 
 ## 2. Install and log in to each vendor
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@prplkane/roundtable",
-  "version": "0.6.3",
+  "version": "0.6.4",
   "description": "Local decision reviews with coding-agent CLIs, human input, budget checks and Markdown records.",
   "keywords": [
     "claude",

package/skills/roundtable/SKILL.md

@@ -16,7 +16,9 @@ one-time `roundtable setup --client codex` (or `claude` / `agy`) step.
    The MCP server starts the local board when needed; offer its link without opening it.
    For the CLI fallback, read `roundtable agent --help`, then `roundtable agent status --refresh`.
    If no server answers, use `roundtable server start` to start a hidden board and retry
-   the read. An incompatible running board needs a restart after its reviews finish;
+   the read. If that reports `EPERM` or that the environment blocks local servers, your
+   sandbox forbids the port: ask the user to run `roundtable server start` in their own
+   terminal once, then retry. An incompatible running board needs a restart after its reviews finish;
    `roundtable server restart` refuses active reviews. Never automatically retry a write
    that might already have succeeded.
 2. Choose distinct perspectives using the user's facts and constraints. Normally use two seats,

package/src/doctor.js

@@ -13,6 +13,7 @@ import { fileURLToPath } from 'node:url';
 import { ADAPTERS } from './adapters/config.js';
 import { resolveBinary, runProcess, profileHome, dataDir } from './adapters/spawn.js';
 import { dataDirectory } from './history.js';
+import { paintVendor } from './terminal.js';
 
 // Shell lines that log a profile in, per vendor, for the platform the user is on. Pure.
 export function loginInstructions(vendor, profile, where = {}) {
@@ -46,9 +47,13 @@ async function main() {
   const catalogue = await vendorCatalogue(ADAPTERS.agy.terms && !acknowledgeTermsRisk ? { agyModels: async () => [] } : {});
   console.log(`roundtable doctor  (${process.platform}, node ${process.version}, data dir ${dataDir()})`);
   console.log(live ? 'live: one trivial model call per vendor' : 'static only; add --live for one trivial model call per vendor');
+  const missing = []; // CLIs not on PATH: one line at the end, a full block only when asked for by --vendor
   for (const [vendor, a] of Object.entries(ADAPTERS)) {
     if (only && only !== vendor) continue;
-    console.log(`\n== ${a.label} (${vendor})  pool: ${a.pool}`);
+    let bin = null, lookup = null;
+    if (a.kind === 'cli') try { bin = resolveBinary(a.binary, a.npmBin); } catch (e) { lookup = e.message; }
+    if (a.kind === 'cli' && !bin && only !== vendor) { missing.push(`${a.label} (${a.binary})`); continue; }
+    console.log(`\n== ${paintVendor(a)} (${vendor})  pool: ${a.pool}`);
     if (a.kind === 'api') { // no binary: everything about an endpoint seat is on its card
       console.log('  seat it    on the board: base URL (…/v1), model id, and for a hosted API the NAME of the key variable');
       console.log(`  efforts    ${a.effortLevels.join(', ')}  (reasoning_effort, sent only when set)`);
@@ -58,8 +63,7 @@ async function main() {
     }
     const held = !!a.terms && !acknowledgeTermsRisk;
     const heldLine = `held: nothing is sent to ${a.binary} without --acknowledge-terms-risk`;
-    let bin = null;
-    try { bin = resolveBinary(a.binary, a.npmBin); console.log(`  binary     ${bin.prefix.length ? `${bin.prefix[0]} (via node)` : bin.file}`); } catch (e) { console.log(`  binary     NOT FOUND: ${e.message}`); }
+    console.log(`  binary     ${bin ? bin.prefix.length ? `${bin.prefix[0]} (via node)` : bin.file : `NOT FOUND: ${lookup}`}`);
     if (bin) console.log(`  version    ${await version(bin, vendor)}`);
     const c = catalogue[vendor];
     if (held) console.log(`  models     ${heldLine}`);
@@ -88,6 +92,7 @@ async function main() {
     }
     if (profile) for (const l of loginInstructions(vendor, profile)) console.log(`  profile    ${l}`);
   }
+  if (missing.length) console.log(`\nnot installed: ${missing.join(', ')}; install and sign in to seat them, or add --vendor <name> for that block`);
   if (!profile) console.log('\nadd --profile <name> to see how to log a named account profile in for each vendor');
 }
 

package/src/local-server.js

@@ -1,5 +1,7 @@
 // A cheap, versioned health check; provider catalogues are not server readiness checks.
 import { spawn } from 'node:child_process';
+import { mkdtempSync, openSync, closeSync, readFileSync, rmSync } from 'node:fs';
+import os from 'node:os';
 import { realpath } from 'node:fs/promises';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -43,23 +45,49 @@ export async function inspectServer(config, { signal, allowOlder = false } = {})
 // Readiness reads may be retried. A review write is never part of this loop.
 export async function ensureServer(config, { signal, timeoutMs = 35000 } = {}) {
   const end = Date.now() + timeoutMs;
-  let spawned = false, spawnFailed = false, last;
+  let spawned = false, spawnFailed = false, exited = null, ready = false, last;
+  // The board's stderr goes to a file, never a pipe: it outlives this process, and a pipe to a
+  // gone host would break its logging. The file sits in a fresh private temp directory (no
+  // predictable path for another user to plant), is read only when the board exits early, and
+  // goes once the board is ready (at once where an open file can be unlinked, else when the
+  // board exits while this process is still around).
+  let log = null;
+  const discard = () => { try { if (log) rmSync(path.dirname(log), { recursive: true, force: true }); } catch {} };
   while (Date.now() < end) {
     signal?.throwIfAborted();
     try {
       const status = await inspectServer(config, { signal });
-      if (status) return status;
+      if (status) { if (spawned) { ready = true; discard(); } return status; }
       if (config.start === false) throw new Error('Roundtable is not running; start the local board or remove --no-start.');
       if (!spawned) {
         spawned = true;
         // Survives the host connection, so closing chat cannot cancel a review or its timer.
+        let fd = null;
+        try { log = path.join(mkdtempSync(path.join(os.tmpdir(), 'roundtable-start-')), 'stderr.log'); fd = openSync(log, 'wx'); } catch {}
         const child = spawn(process.execPath, [SERVER, '--no-open', ...(config.fake ? ['--fake'] : [])], {
           env: { ...process.env, PORT: String(config.port), ...(config.dataDir ? { ROUNDTABLE_DEBATES_DIR: config.dataDir } : {}) },
-          detached: true, windowsHide: true, stdio: 'ignore',
+          detached: true, windowsHide: true, stdio: ['ignore', 'ignore', fd ?? 'ignore'],
         });
-        child.once('error', () => { spawnFailed = true; }); child.unref();
+        if (fd != null) closeSync(fd);
+        child.once('error', () => { spawnFailed = true; });
+        child.once('exit', (code, sig) => { exited = { code, sig, at: Date.now() }; if (ready) discard(); });
+        child.unref();
       }
     } catch (e) { if (!e.transient) throw e; last = e; }
+    // A board that exits early may have lost the port or the data folder to one that another
+    // process started at the same moment (two hosts asking at once), so the port is still
+    // watched for a few seconds before the exit counts as the answer.
+    if (exited && Date.now() - exited.at > 5000) {
+      let tail = '';
+      // the board's own last word where it had one, else the message line of a crash, else the last line
+      try {
+        const lines = readFileSync(log, 'utf8').split(/\r?\n/).filter((l) => l.trim());
+        tail = (lines.findLast((l) => l.startsWith('[server]')) || lines.find((l) => /^\w*Error: /.test(l)) || lines.at(-1) || '').trim().slice(0, 200);
+      } catch {}
+      discard();
+      const sandboxed = /cannot listen.*\b(EPERM|EACCES)\b/.test(tail);
+      throw new Error(`The local board exited before it was ready${tail ? ` (${tail})` : ''}. ${sandboxed ? 'This environment blocks local servers: start the board from a normal terminal with roundtable server start, then retry.' : 'Run roundtable --no-open in a terminal for startup details.'} No review was started.`);
+    }
     if (spawnFailed) break;
     await delay(100, undefined, { signal });
   }

package/src/server.js

@@ -29,7 +29,7 @@ import { pickFolder } from './folder-picker.js';
 import { dataDirectory, legacyHistory, acquireDataLock, checkedHistoryPath, removeHistory, createUsageStore, createHistoryIndex } from './history.js';
 import { VERSION } from './version.js';
 import { LOCAL_API_VERSION } from './local-server.js';
-import { terminalBanner } from './terminal.js';
+import { terminalBanner, paintVendor } from './terminal.js';
 
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 const UI = path.join(ROOT, 'src', 'ui');
@@ -402,6 +402,9 @@ function synthesizeDebate(d, body = {}) {
 const quota = {}; // pool key -> { windows, plan, at, groups? }
 const readers = FAKE ? { claude: async () => fakeQuota('claude'), codex: async () => fakeQuota('codex'), agy: async () => fakeQuota('agy') } : quotaReaders;
 const keyOf = (vendor, account) => poolKey(vendor, account, poolsByAccount(ADAPTERS[vendor]));
+// A vendor whose CLI is not on PATH gets no quota read and no startup line: a CLI that is not
+// here is not a failed read. Demo mode seats every vendor with scripted replies.
+const installed = (vendor) => { if (FAKE || ADAPTERS[vendor]?.kind !== 'cli') return true; try { resolveBinary(ADAPTERS[vendor].binary, ADAPTERS[vendor].npmBin); return true; } catch { return false; } };
 
 function setQuota(key, q) {
   if (!q) return;
@@ -415,7 +418,7 @@ const reading = new Map();
 function refreshQuota(key, { acknowledged = false } = {}) {
   const vendor = poolVendor(key), account = poolAccount(key);
   // a reader that stopped itself (agy's latch, quota.js) said why once; no read, no repeat
-  if (!readers[vendor] || readers[vendor].stopped?.() || termsHeld(vendor, acknowledged)) return Promise.resolve(null);
+  if (!readers[vendor] || readers[vendor].stopped?.() || termsHeld(vendor, acknowledged) || !installed(vendor)) return Promise.resolve(null);
   if (reading.has(key)) return reading.get(key);
   // The readers resolve null on every failure (timeout, spawn error, no result) rather than
   // throwing, so say so here or a dead read is invisible on the console. Resolves to the figure
@@ -423,7 +426,7 @@ function refreshQuota(key, { acknowledged = false } = {}) {
   const p = (async () => {
     try {
       const q = await readers[vendor]({ home: account ? profileHome(vendor, account) : null });
-      if (!q) { diagnostics.write({ code: 'status-failed', action: 'quota', vendor }); console.warn(`[quota] ${key}: no figure (read failed or timed out); the strip keeps the last one`); }
+      if (!q) { diagnostics.write({ code: 'status-failed', action: 'quota', vendor }); console.warn(`[quota] ${paintVendor(ADAPTERS[vendor], { text: key })}: no figure (not logged in, or the read failed or timed out); the strip keeps the last one`); }
       setQuota(key, q);
       return q;
     } catch (e) { diagnostics.write({ code: 'status-failed', action: 'quota', vendor }, e); console.error(`[quota] ${key}: ${e.message}`); return null; } finally { reading.delete(key); }
@@ -876,15 +879,27 @@ function openBrowser(url) {
   const cmd = process.platform === 'win32' ? ['cmd', ['/c', 'start', '', url]] : process.platform === 'darwin' ? ['open', [url]] : ['xdg-open', [url]];
   try { spawn(cmd[0], cmd[1], { stdio: 'ignore', detached: true, windowsHide: true }).on('error', () => {}).unref(); return true; } catch { return false; }
 }
+// A port that cannot be taken is said plainly: in use, or a sandbox that forbids listening
+// (Codex on Linux, for one), where the board has to be started from a normal terminal instead.
+server.on('error', (e) => {
+  diagnostics.write({ code: 'server-start', action: 'startup' }, e);
+  const why = e.code === 'EADDRINUSE' ? `port ${PORT} is in use. Check roundtable server status, or start with --port`
+    : ['EPERM', 'EACCES'].includes(e.code) ? `this environment does not allow a local server on 127.0.0.1:${PORT} (${e.code}). Start the board from a normal terminal with roundtable server start; the assistant's tools then connect to it`
+    : e.message;
+  console.error(`[server] cannot listen: ${why}`);
+  process.exit(1);
+});
 server.listen(PORT, '127.0.0.1', () => {
   const url = `http://localhost:${PORT}`;
   const open = process.stdout.isTTY && !process.argv.includes('--no-open') && process.env.ROUNDTABLE_NO_OPEN !== '1' && !process.env.CI;
   const opened = open && openBrowser(url);
   process.stdout.write(terminalBanner());
   console.log(`roundtable${FAKE ? ' (fake seats)' : ''}: ${url}  token ${TOKEN}`);
-  console.log(`mode: ${FAKE ? 'demo (scripted replies and usage)' : 'live (configured providers)'}; data: ${DEBATES_DIR}`);
+  console.log(`mode: ${FAKE ? 'demo (scripted replies and usage)' : 'live'}; data: ${DEBATES_DIR}`);
+  const found = Object.entries(ADAPTERS).filter(([v, a]) => a.kind === 'cli' && installed(v)).map(([, a]) => paintVendor(a));
+  if (!FAKE) console.log(found.length ? `providers: ${found.join(', ')} (CLIs on PATH; an API endpoint is seated on the board)` : 'providers: no Claude, Codex or Antigravity CLI on PATH; seat an API endpoint on the board, or install one and restart. roundtable doctor has details');
   console.log('diagnostics: _diagnostics in the data folder; use Save error log on the board. Nothing is uploaded.');
-  if (opened) console.log('the board is open in your browser; Ctrl+C here stops the server and every CLI it started');
+  console.log(`${opened ? 'the board is open in your browser' : `open ${url} in your browser`}; Ctrl+C here stops the server and every CLI it started`);
 });
 
 // No CLI outlives the server: on a signal or an uncaught error every registered child goes

package/src/terminal.js

@@ -12,17 +12,40 @@ const TILE = [
 ];
 const TAGLINE = 'Local decision reviews';
 const RESET = '\x1b[0m';
+const BOLD = '\x1b[1m', DIM = '\x1b[2m', BLINK = '\x1b[5m';
 
 // Half blocks need a UTF-8 terminal. Windows consoles take UTF-16 from Node whatever the code
 // page; elsewhere the locale has to say so. ROUNDTABLE_ASCII=1 forces the plain form.
 const unicode = (env, platform) => env.ROUNDTABLE_ASCII !== '1'
   && (platform === 'win32' || /utf-?8/i.test(env.LC_ALL || env.LC_CTYPE || env.LANG || ''));
-// Tile and ink colours: true colour where the terminal says so, the nearest 256-colour or
-// basic pair otherwise. Returned as [tile background, ink foreground, orchid foreground].
-function palette(env, platform) {
-  if (/truecolor|24bit/i.test(env.COLORTERM || '') || env.WT_SESSION || platform === 'win32') return ['\x1b[48;2;199;154;208m', '\x1b[38;2;43;29;56m', '\x1b[38;2;199;154;208m'];
-  if (env.TERM?.includes('256color')) return ['\x1b[48;5;182m', '\x1b[38;5;234m', '\x1b[38;5;182m'];
-  return ['\x1b[45m', '\x1b[30m', '\x1b[35m'];
+// Which colours the terminal takes: true colour where it says so, 256 colours, or the basic 8.
+const tier = (env, platform) => (/truecolor|24bit/i.test(env.COLORTERM || '') || env.WT_SESSION || platform === 'win32') ? 'true'
+  : env.TERM?.includes('256color') ? '256' : 'basic';
+// Tile and ink colours per tier: [tile background, ink foreground, orchid foreground].
+const PALETTE = {
+  true: ['\x1b[48;2;199;154;208m', '\x1b[38;2;43;29;56m', '\x1b[38;2;199;154;208m'],
+  256: ['\x1b[48;5;182m', '\x1b[38;5;234m', '\x1b[38;5;182m'],
+  basic: ['\x1b[45m', '\x1b[30m', '\x1b[35m'],
+};
+// The family accents the board gives each vendor (adapters/config.js colour, design/app.css
+// --seat-*), per tier, so a vendor reads the same colour in the terminal as on its seat.
+const ACCENTS = {
+  rust: ['\x1b[38;2;223;107;85m', '\x1b[38;5;173m', '\x1b[31m'],
+  olive: ['\x1b[38;2;156;188;106m', '\x1b[38;5;149m', '\x1b[32m'],
+  teal: ['\x1b[38;2;111;179;169m', '\x1b[38;5;73m', '\x1b[36m'],
+  steel: ['\x1b[38;2;134;169;196m', '\x1b[38;5;110m', '\x1b[34m'],
+};
+const TIERS = ['true', '256', 'basic'];
+
+// Nothing is decorated for a pipe, CI or a dumb terminal; NO_COLOR keeps the text and drops
+// the codes.
+const decorated = (isTTY, env) => isTTY && !env.CI && env.TERM !== 'dumb';
+const painter = (env) => (s, code) => env.NO_COLOR ? s : `${code}${s}${RESET}`;
+
+// A vendor's name in its seat colour: paintVendor(ADAPTERS.codex) -> coloured "Codex".
+export function paintVendor({ label, colour }, { text = label, isTTY = process.stdout.isTTY, env = process.env, platform = process.platform } = {}) {
+  if (!decorated(isTTY, env) || !ACCENTS[colour]) return text;
+  return painter(env)(text, ACCENTS[colour][TIERS.indexOf(tier(env, platform))]);
 }
 
 function tileRows(colour) {
@@ -39,15 +62,16 @@ function tileRows(colour) {
 }
 
 export function terminalBanner({ isTTY = process.stdout.isTTY, columns = process.stdout.columns ?? 80, env = process.env, platform = process.platform } = {}) {
-  if (!isTTY || env.CI || env.TERM === 'dumb') return '';
-  const paint = (s, code) => env.NO_COLOR ? s : `${code}${s}${RESET}`;
-  const [tile, ink, orchid] = palette(env, platform);
+  if (!decorated(isTTY, env)) return '';
+  const paint = painter(env);
+  const [tile, ink, orchid] = PALETTE[tier(env, platform)];
   const version = `v${VERSION}`;
-  const name = paint('ROUNDTABLE', '\x1b[1m');
-  const compact = `${name}${columns >= 12 + version.length ? `  ${paint(version, '\x1b[2m')}` : ''}`;
+  const name = paint('ROUNDTABLE', BOLD);
+  const compact = `${name}${columns >= 12 + version.length ? `  ${paint(version, DIM)}` : ''}`;
   // 2 indent + 16 tile + 3 gap + the tagline, the widest line beside the tile
   if (!unicode(env, platform) || columns < 21 + TAGLINE.length) return `\n${compact}\n\n`;
-  const beside = { 2: `${name} ${paint('▌', orchid)}`, 3: paint(version, '\x1b[2m'), 5: paint(TAGLINE, '\x1b[2m') };
+  // the block cursor blinks like the board header's, where the terminal allows blinking text
+  const beside = { 2: `${name} ${paint('▌', orchid + BLINK)}`, 3: paint(version, DIM), 5: paint(TAGLINE, DIM) };
   const lines = tileRows((row) => paint(row, tile + ink)).map((row, y) => `  ${row}${beside[y] ? `   ${beside[y]}` : ''}`);
   return `\n${lines.join('\n')}\n\n`;
 }