@cordfuse/crosstalk 6.0.0-alpha.9 → 7.0.0-alpha.10

package/commands/init.js

@@ -0,0 +1,243 @@
+// crosstalk init — scaffold a transport into <base>/<name>/.
+//
+// alpha.7 rewrite: phased + idempotent. Each phase is independent and
+// safe to re-run; re-init detects missing markers and repairs them.
+// Mac caught bug A in alpha.6 where the api-port file was written at
+// the end of the pipeline, so any disruption (image pull, git failure)
+// left storage existing but unstartable — and re-init silently
+// no-op-ed instead of fixing it.
+//
+// Phases:
+//   1. Storage layout — mkdir subdirs + write api-port. Pure FS, fast,
+//      runs first so the resolver-visible marker exists before anything
+//      else can go wrong.
+//   2. Transport scaffold — `crosstalkd init` in a one-shot container.
+//      Skipped if transport/.git already exists. stdout/stderr captured
+//      (mac's bug B — in-container scaffold output was leaking).
+//   3. Git init + initial commit. Skipped if .git exists.
+//   4. Remote setup if --remote given (errors if a different origin
+//      is already set; idempotent on same-value).
+//   5. Summary.
+//
+// Each phase reports created/skipped/repaired so operators can tell
+// what just happened.
+
+import { mkdirSync, existsSync, writeFileSync, readFileSync } from 'fs';
+import { spawnSync } from 'child_process';
+import { join } from 'path';
+import { has, flag } from '../lib/argv.js';
+import {
+  parseContainerName,
+  storagePaths,
+  pickFreePort,
+  DEFAULT_CONTAINER_NAME,
+} from '../lib/resolve.js';
+
+const DEFAULT_IMAGE = process.env.CROSSTALK_IMAGE
+  ?? 'ghcr.io/cordfuse/crosstalk-server:7.0.0-alpha.8';
+
+function usage(exit = 0) {
+  const w = exit === 0 ? process.stdout : process.stderr;
+  w.write(
+`Usage:
+  crosstalk init [--containername <name>] [--remote <url>]
+
+Creates a new transport on this machine, or repairs an existing
+incomplete one. Idempotent — re-running fills in any missing markers
+without disturbing existing state.
+
+The transport git repo lives at <base>/<name>/transport/ where <base> is:
+  Linux:   $XDG_DATA_HOME/crosstalk/   (or ~/.local/share/crosstalk/)
+  macOS:   ~/Library/Application Support/crosstalk/
+  Windows: %LOCALAPPDATA%\\crosstalk\\
+
+Set CROSSTALK_STORAGE_MODE=system to use the system-wide path (sudo/UAC
+required; intended for headless multi-operator hosts).
+
+Options:
+  --containername <name>   Container name (default: 'crosstalk'). Must be
+                           lowercase alphanumeric + ._- (no leading . or -).
+                           One default + N named containers per machine.
+  --remote <url>           Set git upstream. If a different remote is
+                           already set, errors instead of overwriting.
+  --image <tag>            Override the engine image (default: bundled
+                           GHCR tag; or CROSSTALK_IMAGE env).
+  -c <name>                Shorthand for --containername.
+
+Examples:
+  crosstalk init                                   # default container
+  crosstalk init --containername uat               # second container
+  crosstalk init --remote git\\@github.com:me/t.git # with upstream
+`,
+  );
+  process.exit(exit);
+}
+
+export async function run(argv) {
+  if (has(argv, '--help') || has(argv, '-h')) usage(0);
+
+  let name;
+  try {
+    name = parseContainerName(argv);
+  } catch (err) {
+    process.stderr.write(`crosstalk init: ${err.message}\n`);
+    return 1;
+  }
+
+  const remote = flag(argv, '--remote');
+  const image = flag(argv, '--image') ?? DEFAULT_IMAGE;
+  const paths = storagePaths(name);
+  const report = [];
+
+  // ── Phase 1: Storage layout ────────────────────────────────────────
+  // mkdir is idempotent (recursive: true). Write api-port if absent.
+  // This is the load-bearing fix for bug A — port file lands FIRST,
+  // before anything else can go wrong (image pull, git init, etc.).
+  try {
+    mkdirSync(paths.transportDir,   { recursive: true });
+    mkdirSync(paths.crosstalkRoot,  { recursive: true });
+    mkdirSync(paths.crosstalkState, { recursive: true });
+  } catch (err) {
+    process.stderr.write(
+      `crosstalk init: failed to create storage at ${paths.storageRoot} — ${err.message}\n`,
+    );
+    if (paths.mode === 'system') {
+      process.stderr.write(
+        `  System-mode storage requires write access to ${paths.base}.\n` +
+        `  Try: sudo mkdir -p ${paths.storageRoot} && sudo chown -R $USER ${paths.storageRoot}\n`,
+      );
+    }
+    return 1;
+  }
+
+  let port;
+  if (existsSync(paths.portFile)) {
+    const v = Number(readFileSync(paths.portFile, 'utf-8').trim());
+    if (Number.isInteger(v) && v > 0 && v < 65536) {
+      port = v;
+      report.push(`  api port:   ${port} (existing)`);
+    }
+  }
+  if (!port) {
+    try {
+      port = pickFreePort(name);
+      writeFileSync(paths.portFile, `${port}\n`);
+      report.push(`  api port:   ${port} (allocated)`);
+    } catch (err) {
+      process.stderr.write(`crosstalk init: port allocation failed — ${err.message}\n`);
+      return 1;
+    }
+  }
+
+  // ── Phase 2: Transport scaffold ────────────────────────────────────
+  // The template-scaffold check is "does CROSSTALK-VERSION exist?" NOT
+  // ".git exists" — git init is a separate phase, and the engine refuses
+  // to re-scaffold over an existing CROSSTALK-VERSION (without --force).
+  // Decoupling means a disrupted init (template written, git init never
+  // ran) re-enters Phase 3 cleanly on re-run.
+  const transportGitDir      = join(paths.transportDir, '.git');
+  const crosstalkVersionFile = join(paths.transportDir, 'CROSSTALK-VERSION');
+  if (!existsSync(crosstalkVersionFile)) {
+    const uid = typeof process.getuid === 'function' ? process.getuid() : null;
+    const gid = typeof process.getgid === 'function' ? process.getgid() : null;
+    const userArgs = (uid != null && gid != null) ? ['--user', `${uid}:${gid}`] : [];
+
+    const dockerArgs = [
+      'run', '--rm',
+      '-v', `${paths.transportDir}:/init-target`,
+      ...userArgs,
+      '--entrypoint', 'crosstalkd',
+      image,
+      'init', '/init-target',
+    ];
+
+    // Bug B fix: don't inherit stdio — the engine prints next-steps that
+    // confuse operators ("Transport initialized at /init-target" with
+    // container-internal paths). Capture, show only on failure.
+    const initRun = spawnSync('docker', dockerArgs, { stdio: 'pipe' });
+    if (initRun.status !== 0) {
+      const stderr = initRun.stderr?.toString() ?? '';
+      const stdout = initRun.stdout?.toString() ?? '';
+      process.stderr.write(`crosstalk init: docker run exited ${initRun.status}\n`);
+      if (stderr.trim()) process.stderr.write(`  stderr: ${stderr.trim()}\n`);
+      if (stdout.trim()) process.stderr.write(`  stdout: ${stdout.trim()}\n`);
+      process.stderr.write(`  command was: docker ${dockerArgs.join(' ')}\n`);
+      return initRun.status ?? 1;
+    }
+    report.push(`  template:   scaffolded via ${image}`);
+  } else {
+    report.push(`  template:   present (skipped scaffold)`);
+  }
+
+  // ── Phase 3: Git init + initial commit ─────────────────────────────
+  if (!existsSync(crosstalkVersionFile)) {
+    // Engine init succeeded but didn't leave files. Bail clearly — we
+    // won't proceed to git init on an empty dir.
+    process.stderr.write(
+      `crosstalk init: transport template missing at ${paths.transportDir}\n` +
+      `  Engine init didn't write template files. Try 'crosstalk rm' then re-init.\n`,
+    );
+    return 1;
+  }
+
+  const gitSteps = [
+    ['init', '--quiet', '--initial-branch=main'],
+    ['add', '-A'],
+    ['commit', '--quiet', '-m', 'initial transport'],
+  ];
+  let gitOk = true;
+  for (const args of gitSteps) {
+    const gr = spawnSync('git', args, { cwd: paths.transportDir, stdio: 'pipe' });
+    if (gr.status !== 0) {
+      // 'git init' on existing repo is fine (it re-runs idempotently);
+      // 'add -A' is also idempotent. 'commit' fails when there's
+      // nothing to commit — that means a previous run already committed.
+      // Only the first call (git init) is load-bearing; the rest are
+      // best-effort to populate the initial state.
+      gitOk = false;
+      break;
+    }
+  }
+  report.push(gitOk ? `  git:        initialized + committed` : `  git:        already present (skipped)`);
+
+  // ── Phase 4: Remote setup ──────────────────────────────────────────
+  if (remote) {
+    const cur = spawnSync('git', ['remote', 'get-url', 'origin'], {
+      cwd: paths.transportDir,
+      stdio: 'pipe',
+    });
+    const currentUrl = cur.status === 0 ? cur.stdout.toString().trim() : null;
+    if (!currentUrl) {
+      const rr = spawnSync('git', ['remote', 'add', 'origin', remote], {
+        cwd: paths.transportDir,
+        stdio: 'pipe',
+      });
+      if (rr.status !== 0) {
+        process.stderr.write(
+          `crosstalk init: 'git remote add origin ${remote}' failed — ${rr.stderr?.toString().trim()}\n`,
+        );
+      } else {
+        report.push(`  remote:     ${remote} (added)`);
+      }
+    } else if (currentUrl === remote) {
+      report.push(`  remote:     ${remote} (already set)`);
+    } else {
+      process.stderr.write(
+        `crosstalk init: remote already set to '${currentUrl}'; refusing to overwrite with '${remote}'.\n` +
+        `  Use 'crosstalk status' to see the transport path; cd there and adjust git config manually if intended.\n`,
+      );
+      return 1;
+    }
+  }
+
+  // ── Phase 5: Summary ───────────────────────────────────────────────
+  process.stdout.write(
+    `\nTransport '${name}' ready:\n` +
+    `  storage:    ${paths.storageRoot}\n` +
+    `  transport:  ${paths.transportDir}\n` +
+    `  image:      ${image}\n` +
+    report.join('\n') + '\n' +
+    `\nNext: crosstalk up${name === DEFAULT_CONTAINER_NAME ? '' : ` --containername ${name}`}\n`,
+  );
+  return 0;
+}

package/commands/logs.js

@@ -0,0 +1,37 @@
+// crosstalk logs — tail a transport's engine logs.
+
+import { existsSync } from 'fs';
+import { spawnSync } from 'child_process';
+import { has } from '../lib/argv.js';
+import { requireInitialized } from '../lib/resolve.js';
+
+function usage(exit = 0) {
+  const w = exit === 0 ? process.stdout : process.stderr;
+  w.write(
+`Usage: crosstalk logs [--containername <name>] [-f|--follow] [-n <lines>]
+
+Streams the engine container's stdout/stderr. -f to follow (Ctrl-C to stop).
+`,
+  );
+  process.exit(exit);
+}
+
+export async function run(argv) {
+  if (has(argv, '--help') || has(argv, '-h')) usage(0);
+
+  const { name, paths } = requireInitialized(argv);
+  if (!existsSync(paths.composeFile)) {
+    process.stderr.write(`crosstalk logs: '${name}' has no compose file — run 'crosstalk up' first.\n`);
+    return 1;
+  }
+  const args = ['compose', '-f', paths.composeFile, 'logs'];
+  if (has(argv, '-f') || has(argv, '--follow')) args.push('--follow');
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === '-n' || argv[i] === '--tail') {
+      args.push('--tail', argv[i + 1] ?? '100');
+      i++;
+    }
+  }
+  const r = spawnSync('docker', args, { stdio: 'inherit' });
+  return r.status ?? 1;
+}

package/commands/pull.js

@@ -0,0 +1,22 @@
+// crosstalk pull — refresh the engine image for a transport.
+
+import { existsSync } from 'fs';
+import { spawnSync } from 'child_process';
+import { has } from '../lib/argv.js';
+import { requireInitialized } from '../lib/resolve.js';
+
+export async function run(argv) {
+  if (has(argv, '--help') || has(argv, '-h')) {
+    process.stdout.write('Usage: crosstalk pull [--containername <name>]\n');
+    return 0;
+  }
+  const { name, paths } = requireInitialized(argv);
+  if (!existsSync(paths.composeFile)) {
+    process.stderr.write(`crosstalk pull: '${name}' has no compose file — run 'crosstalk up' first.\n`);
+    return 1;
+  }
+  const r = spawnSync('docker', ['compose', '-f', paths.composeFile, 'pull'], {
+    stdio: 'inherit',
+  });
+  return r.status ?? 1;
+}

package/commands/replies.js

@@ -0,0 +1,40 @@
+// crosstalk replies <relPath> [<relPath>...] — poll reply status.
+//
+// Exit 0 if all targets have REPLIED or FAILED, exit 2 while any PENDING
+// — agents can poll cheaply in a loop. Mirrors crosstalkd replies.
+
+import { apiFor } from '../lib/api-client.js';
+import { reportAndExit } from '../lib/errors.js';
+import { positionals, has } from '../lib/argv.js';
+
+function usage(exit = 0) {
+  const w = exit === 0 ? process.stdout : process.stderr;
+  w.write('Usage: crosstalk replies [--containername <name>] <relPath> [<relPath>...]\n');
+  process.exit(exit);
+}
+
+export async function run(argv) {
+  if (has(argv, '--help') || has(argv, '-h')) usage(0);
+  const api = apiFor(argv);
+  const targets = positionals(argv, ['--containername', '-c']);
+  if (targets.length === 0) usage(1);
+
+  let resp;
+  try {
+    resp = await api.get(`/replies?relPaths=${encodeURIComponent(targets.join(','))}`);
+  } catch (err) {
+    reportAndExit(err, 'crosstalk replies');
+  }
+
+  let pending = 0;
+  for (const r of resp.replies) {
+    if (r.status === 'PENDING') {
+      process.stdout.write(`PENDING  ${r.target}\n`);
+      pending++;
+    } else {
+      const tag = r.status === 'FAILED' ? 'FAILED  ' : 'REPLIED ';
+      process.stdout.write(`${tag} ${r.target}  <- ${r.from} (${r.replyRelPath})\n`);
+    }
+  }
+  return pending > 0 ? 2 : 0;
+}

package/commands/restart.js

@@ -0,0 +1,29 @@
+// crosstalk restart — restart a transport's engine container.
+//
+// Uses `compose up -d --force-recreate` (not `compose restart`) so
+// changes to env_file (e.g. tokens added via `crosstalk auth paste`)
+// are picked up. Plain `compose restart` just stops + starts the same
+// container without re-reading config.
+
+import { existsSync } from 'fs';
+import { spawnSync } from 'child_process';
+import { has } from '../lib/argv.js';
+import { requireInitialized } from '../lib/resolve.js';
+
+export async function run(argv) {
+  if (has(argv, '--help') || has(argv, '-h')) {
+    process.stdout.write('Usage: crosstalk restart [--containername <name>]\n');
+    return 0;
+  }
+  const { name, paths } = requireInitialized(argv);
+  if (!existsSync(paths.composeFile)) {
+    process.stderr.write(`crosstalk restart: '${name}' has no compose file — run 'crosstalk up' first.\n`);
+    return 1;
+  }
+  const r = spawnSync(
+    'docker',
+    ['compose', '-f', paths.composeFile, 'up', '-d', '--force-recreate'],
+    { stdio: 'inherit' },
+  );
+  return r.status ?? 1;
+}

package/commands/rm.js

@@ -0,0 +1,109 @@
+// crosstalk rm — remove a transport completely.
+//
+// Stops the container if running, removes the container, deletes the
+// entire <base>/<name>/ tree (transport git repo, installed CLIs, auth
+// state, dispatcher state, compose file, port file). Confirmation
+// prompt by default; --force / -f to skip for scripted use.
+//
+// Cannot undo. All message history is lost.
+
+import { existsSync, rmSync } from 'fs';
+import { spawnSync } from 'child_process';
+import { createInterface } from 'readline';
+import { has } from '../lib/argv.js';
+import {
+  parseContainerName,
+  storagePaths,
+  isInitialized,
+  isRunning,
+  containerExists,
+  DEFAULT_CONTAINER_NAME,
+} from '../lib/resolve.js';
+
+function usage(exit = 0) {
+  const w = exit === 0 ? process.stdout : process.stderr;
+  w.write(
+`Usage: crosstalk rm [--containername <name>] [--force]
+
+Stops and removes the engine container, then deletes the entire
+storage tree under <base>/<name>/. Includes the transport git repo
+(all message history), installed agent CLIs + auth tokens, and
+dispatcher state. CANNOT BE UNDONE.
+
+Options:
+  --containername <name>   Container to remove (default: 'crosstalk').
+  --force, -f              Skip the confirmation prompt.
+`,
+  );
+  process.exit(exit);
+}
+
+function confirm(promptText) {
+  return new Promise((resolve) => {
+    const rl = createInterface({ input: process.stdin, output: process.stderr });
+    rl.question(promptText, (ans) => {
+      rl.close();
+      const yes = /^y(es)?$/i.test(ans.trim());
+      resolve(yes);
+    });
+  });
+}
+
+export async function run(argv) {
+  if (has(argv, '--help') || has(argv, '-h')) usage(0);
+
+  let name;
+  try {
+    name = parseContainerName(argv);
+  } catch (err) {
+    process.stderr.write(`crosstalk rm: ${err.message}\n`);
+    return 1;
+  }
+
+  const paths = storagePaths(name);
+  const haveStorage = isInitialized(name) || existsSync(paths.storageRoot);
+  const haveContainer = containerExists(name);
+
+  if (!haveStorage && !haveContainer) {
+    process.stderr.write(`crosstalk rm: transport '${name}' not found.\n`);
+    return 1;
+  }
+
+  if (!has(argv, '--force') && !has(argv, '-f')) {
+    process.stderr.write(
+      `Remove '${name}'?\n` +
+      `  This deletes:\n` +
+      `    - transport git repo at ${paths.transportDir}\n` +
+      `      (all message history, channels, replies)\n` +
+      `    - installed agent CLIs + auth tokens (claude, codex, ...)\n` +
+      `    - dispatcher state (cursor, heartbeat, errors.log)\n` +
+      `  Cannot undo.\n`,
+    );
+    const ok = await confirm('[y/N]: ');
+    if (!ok) {
+      process.stderr.write('crosstalk rm: cancelled.\n');
+      return 1;
+    }
+  }
+
+  // Stop + remove the container (best-effort).
+  if (isRunning(name) && existsSync(paths.composeFile)) {
+    spawnSync('docker', ['compose', '-f', paths.composeFile, 'down'], { stdio: 'inherit' });
+  } else if (haveContainer) {
+    spawnSync('docker', ['rm', '-f', name], { stdio: 'ignore' });
+  }
+
+  // Wipe storage.
+  try {
+    rmSync(paths.storageRoot, { recursive: true, force: true });
+  } catch (err) {
+    process.stderr.write(
+      `crosstalk rm: failed to remove ${paths.storageRoot} — ${err.message}\n` +
+      `  (container is removed, but storage cleanup needs intervention)\n`,
+    );
+    return 1;
+  }
+
+  process.stdout.write(`Removed '${name}'.\n`);
+  return 0;
+}

package/commands/run.js

@@ -0,0 +1,115 @@
+// crosstalk run — dispatch a primitive or workflow via POST /messages.
+//
+// Mirrors crosstalkd's run surface:
+//   crosstalk run --type primitive --to <model>[@<machine>] [--as <persona>]
+//                 [--fanout <n>] [--channel <name|uuid>] [--from <name>]
+//                 [--new] <body|file|->
+//   crosstalk run --type workflow [--channel <name|uuid>] [--from <name>]
+//                 [--new] <file|->
+
+import { readFileSync, existsSync, statSync } from 'fs';
+import { apiFor } from '../lib/api-client.js';
+import { reportAndExit } from '../lib/errors.js';
+import { flag, has, positionals } from '../lib/argv.js';
+
+const FLAGS_WITH_VALUE = new Set(['--type', '--to', '--as', '--fanout', '--channel', '--from', '--containername', '-c']);
+
+function usage(exit = 0) {
+  const w = exit === 0 ? process.stdout : process.stderr;
+  w.write(
+`Usage:
+  crosstalk run --type primitive --to <model>[@<machine>] \\
+                 [--as <persona>] [--fanout <n>] \\
+                 [--channel <name|uuid>] [--from <name>] [--new] \\
+                 <body|file|->
+
+  crosstalk run --type workflow [--channel <name|uuid>] \\
+                 [--from <name>] [--new] <file|->
+`,
+  );
+  process.exit(exit);
+}
+
+function readStdin() {
+  try {
+    return readFileSync(0, 'utf-8');
+  } catch {
+    return '';
+  }
+}
+
+function resolveBody(arg) {
+  if (arg == null) return null;
+  if (arg === '-') return readStdin();
+  if (existsSync(arg)) {
+    try {
+      if (statSync(arg).isFile()) return readFileSync(arg, 'utf-8');
+    } catch { /* fall through to inline */ }
+  }
+  return arg;
+}
+
+export async function run(argv) {
+  if (has(argv, '--help') || has(argv, '-h')) usage(0);
+
+  const api = apiFor(argv);
+  const type = flag(argv, '--type');
+  if (type !== 'primitive' && type !== 'workflow') usage(1);
+
+  // Body is the last positional. positionals() skips flag values so the
+  // body resolves regardless of flag order — `--containername a8 hello`
+  // and `hello --containername a8` both work.
+  const pos = positionals(argv, [...FLAGS_WITH_VALUE]);
+  const bodyArg = pos[pos.length - 1];
+
+  const body = resolveBody(bodyArg);
+  if (body == null || body.length === 0) {
+    process.stderr.write('crosstalk run: missing body (file path, inline string, or `-` for stdin)\n');
+    return 1;
+  }
+
+  const channel = flag(argv, '--channel');
+  const from = flag(argv, '--from') ?? process.env.USER ?? 'operator';
+
+  let payload;
+  if (type === 'primitive') {
+    const to = flag(argv, '--to');
+    if (!to) {
+      process.stderr.write('crosstalk run --type primitive: --to <model> is required\n');
+      return 1;
+    }
+    const fanoutRaw = flag(argv, '--fanout');
+    const fanout = fanoutRaw ? Math.max(1, parseInt(fanoutRaw, 10)) : 1;
+    payload = {
+      type: 'primitive',
+      to,
+      as: flag(argv, '--as'),
+      channel,
+      from,
+      fanout,
+      body,
+    };
+  } else {
+    payload = {
+      type: 'workflow',
+      channel,
+      from,
+      body,
+    };
+  }
+
+  let resp;
+  try {
+    resp = await api.post('/messages', payload);
+  } catch (err) {
+    reportAndExit(err, 'crosstalk run');
+  }
+
+  if (resp.type === 'primitive') {
+    for (const p of resp.relPaths) process.stdout.write(`Sent: ${p}\n`);
+  } else {
+    process.stdout.write(`Workflow dispatched: ${resp.relPath}\n`);
+    process.stdout.write(`Child channel: ${resp.childChannel} (parent: ${resp.channel.slice(0, 8)})\n`);
+  }
+  return 0;
+}

package/commands/status.js

@@ -0,0 +1,90 @@
+// crosstalk status — mirror of crosstalkd status output, fetched via API.
+//
+// alpha.6: also prints the host path of the transport git repo as an
+// escape hatch for operators who want to poke around with raw git.
+
+import { apiFor } from '../lib/api-client.js';
+import { reportAndExit } from '../lib/errors.js';
+import { requireInitialized } from '../lib/resolve.js';
+
+export async function run(argv) {
+  const { name, paths } = requireInitialized(argv);
+  const api = apiFor(argv);
+
+  let s;
+  try {
+    s = await api.get('/status');
+  } catch (err) {
+    reportAndExit(err, 'crosstalk status');
+  }
+
+  process.stdout.write(`Container:           ${name}\n`);
+  process.stdout.write(`Transport host path: ${paths.transportDir}\n`);
+  process.stdout.write(`Engine alias:        ${s.alias}\n`);
+  process.stdout.write(`Engine version:      ${s.version}\n`);
+  process.stdout.write('\n');
+
+  process.stdout.write(`Claimed models: ${s.claimed_models.length}\n`);
+  if (s.claimed_models.length === 0) {
+    let installed = null;
+    let yamlReferenced = null;
+    try {
+      const r = await api.get('/agents/installed');
+      installed = r.installed;
+      yamlReferenced = r.yaml_referenced;
+    } catch { /* ignore — fall back to generic message */ }
+    if (installed && installed.length > 0) {
+      // M2 (alpha.10): differentiate "yaml references it but the claim
+      // list is stale" from "yaml has no entry yet". The dispatcher
+      // claims at startup; a CLI installed after `crosstalk up` doesn't
+      // surface until `crosstalk restart`.
+      const referencedSet = new Set(yamlReferenced ?? []);
+      const installedAndReferenced = installed.filter((b) => referencedSet.has(b));
+      const installedNotReferenced = installed.filter((b) => !referencedSet.has(b));
+      if (installedAndReferenced.length > 0) {
+        const verb = installedAndReferenced.length === 1 ? 'is' : 'are';
+        process.stdout.write(
+          `  (${installedAndReferenced.join(', ')} ${verb} installed and referenced in data/crosstalk.yaml ` +
+          `but not yet claimed — run 'crosstalk restart' to refresh the dispatcher's claim list)\n`,
+        );
+      }
+      if (installedNotReferenced.length > 0) {
+        const verb = installedNotReferenced.length === 1 ? 'references it' : 'references them';
+        process.stdout.write(
+          `  (${installedNotReferenced.join(', ')} installed in the container but no data/crosstalk.yaml entry ${verb} — add one to claim)\n`,
+        );
+      }
+    } else {
+      process.stdout.write('  (no model CLIs found inside the container — install one via `crosstalk chat --shell` and add an entry to data/crosstalk.yaml)\n');
+    }
+  } else {
+    for (const m of s.claimed_models) process.stdout.write(`  - ${m}\n`);
+  }
+  process.stdout.write('\n');
+
+  if (s.heartbeat) {
+    const ageS = Math.floor((Date.now() - new Date(s.heartbeat.ts).getTime()) / 1000);
+    const label = ageS < 120 ? 'LIVE' : ageS > 300 ? 'STALE' : 'idle';
+    process.stdout.write(`Dispatch heartbeat: ${label} (pid ${s.heartbeat.pid}, last tick ${ageS}s ago, ${s.heartbeat.version})\n`);
+  } else {
+    process.stdout.write('Dispatch heartbeat: never\n');
+  }
+
+  if (s.cursor) {
+    process.stdout.write(`Cursor: ${s.cursor.slice(0, 12)} (global, machine-local)\n`);
+  } else {
+    process.stdout.write('Cursor: (none yet — first tick will seed to HEAD)\n');
+  }
+  process.stdout.write('\n');
+
+  process.stdout.write(`Channels: ${s.channels.length}\n`);
+  for (const ch of s.channels) {
+    const chName = ch.name ?? '(unnamed)';
+    const parentSuffix = ch.parent ? ` [child of ${ch.parent.slice(0, 8)}]` : '';
+    process.stdout.write(`  ${ch.uuid.slice(0, 8)}... — ${chName}${parentSuffix}\n`);
+  }
+  process.stdout.write('\n');
+
+  process.stdout.write(`Infrastructure errors logged: ${s.errors_logged}\n`);
+  return 0;
+}