@cordfuse/crosstalk 7.0.0-alpha.9 → 8.0.0-alpha.1

package/commands/transport.js

@@ -0,0 +1,299 @@
+// crosstalk transport <init|rm> — scaffold or tear down a transport.
+//
+//   init [--containername <name>] [--remote <url>]
+//        Idempotent — re-running fills in missing markers without
+//        disturbing existing state. Engine scaffold runs via
+//        `crosstalk daemon init <path>` (the internal subcommand).
+//
+//   rm   [--containername <name>] [--force]
+//        Stops the engine (best-effort) then deletes <base>/<name>/.
+//        Confirmation prompt by default; --force to skip.
+//
+// Replaces v7's bare `crosstalk init` + `crosstalk rm` (both removed).
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync, rmSync } from 'fs';
+import { spawnSync } from 'child_process';
+import { createInterface } from 'readline';
+import { join, resolve } from 'path';
+import { has, flag } from '../lib/argv.js';
+import {
+  parseContainerName,
+  storagePaths,
+  isInitialized,
+  pickFreePort,
+  DEFAULT_CONTAINER_NAME,
+} from '../lib/resolve.js';
+import { stopEngine, resolveSelfBin } from '../lib/nativeServer.js';
+
+function usage(exit = 0) {
+  const w = exit === 0 ? process.stdout : process.stderr;
+  w.write(
+`Usage:
+  crosstalk transport init [--containername <name>] [--transport git|local] [--path <dir>] [--remote <url>]
+  crosstalk transport rm   [--containername <name>] [--force]
+  crosstalk transport --help
+
+init  — scaffold a new transport (or repair an incomplete one).
+rm    — stop the engine and delete the entire <base>/<name>/ tree.
+
+Options:
+  --containername <name>   Transport name (default: 'crosstalk'). Must be
+                           lowercase alphanumeric + ._- (no leading . or -).
+  -c <name>                Shorthand for --containername.
+  --remote <url>           (init only) set git upstream. Errors if a
+                           different remote is already set.
+  --force, -f              (rm only) skip the confirmation prompt.
+
+Default is system mode (/var/lib/crosstalk/, runs as the 'crosstalk'
+service user via the bundled systemd unit). CROSSTALK_USER_MODE=1
+switches to user mode (paths under the operator's home).
+`,
+  );
+  process.exit(exit);
+}
+
+export async function run(argv) {
+  if (has(argv, '--help') || has(argv, '-h')) usage(0);
+  const sub = argv[0];
+  if (!sub) usage(1);
+  const rest = argv.slice(1);
+
+  if (sub === 'init') return await runInit(rest);
+  if (sub === 'rm')   return await runRm(rest);
+
+  process.stderr.write(`crosstalk transport: unknown subcommand '${sub}'.\n`);
+  usage(1);
+}
+
+async function runInit(argv) {
+  let name;
+  try {
+    name = parseContainerName(argv);
+  } catch (err) {
+    process.stderr.write(`crosstalk transport init: ${err.message}\n`);
+    return 1;
+  }
+
+  const remote = flag(argv, '--remote');
+  const transportKind = flag(argv, '--transport') === 'local' ? 'local' : 'git';
+  if (transportKind === 'local' && remote) {
+    process.stderr.write(`crosstalk transport init: --remote is ignored for --transport local (no git, no upstream).\n`);
+  }
+  const paths = storagePaths(name);
+  // --path <dir>: scaffold the transport at an arbitrary directory (e.g. a
+  // mounted share) instead of the managed storage layout. Port + state stay
+  // machine-local under the name-keyed storage root; only the transport
+  // (template + channels) lives at the path. Pairs with `server start --path`.
+  const customPath = flag(argv, '--path');
+  const transportDir = customPath ? resolve(customPath) : paths.transportDir;
+  const report = [];
+
+  // ── Phase 1: Storage layout ────────────────────────────────────────
+  try {
+    mkdirSync(transportDir,         { recursive: true });
+    mkdirSync(paths.crosstalkRoot,  { recursive: true });
+    mkdirSync(paths.crosstalkState, { recursive: true });
+  } catch (err) {
+    process.stderr.write(
+      `crosstalk transport 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 transport init: port allocation failed — ${err.message}\n`);
+      return 1;
+    }
+  }
+
+  // ── Phase 2: Transport scaffold ────────────────────────────────────
+  const crosstalkVersionFile = join(transportDir, 'CROSSTALK-VERSION');
+  if (!existsSync(crosstalkVersionFile)) {
+    // Scaffold via `crosstalk daemon init <path>` — the same self-bin
+    // call pattern startEngine() uses.
+    const selfBin = resolveSelfBin();
+    if (!existsSync(selfBin)) {
+      process.stderr.write(
+        `crosstalk transport init: CLI entry missing at ${selfBin} — package install looks broken.\n`,
+      );
+      return 1;
+    }
+    const initRun = spawnSync(
+      process.execPath,
+      [selfBin, 'daemon', 'init', transportDir],
+      { stdio: 'pipe' },
+    );
+    if (initRun.status !== 0) {
+      const stderr = initRun.stderr?.toString() ?? '';
+      const stdout = initRun.stdout?.toString() ?? '';
+      process.stderr.write(`crosstalk transport init: 'daemon init' exited ${initRun.status}\n`);
+      if (stderr.trim()) process.stderr.write(`  stderr: ${stderr.trim()}\n`);
+      if (stdout.trim()) process.stderr.write(`  stdout: ${stdout.trim()}\n`);
+      return initRun.status ?? 1;
+    }
+    report.push(`  template:   scaffolded`);
+  } else {
+    report.push(`  template:   present (skipped scaffold)`);
+  }
+
+  // ── Phase 2.5: local transport marker ──────────────────────────────
+  // Local (fs) transports carry no git history; persist the medium in the
+  // config so the dispatcher self-selects it (no --transport flag needed).
+  if (transportKind === 'local') {
+    const yamlPath = join(transportDir, 'data', 'crosstalk.yaml');
+    try {
+      const cur = existsSync(yamlPath) ? readFileSync(yamlPath, 'utf8') : '';
+      if (!/^\s*transport\s*:/m.test(cur)) {
+        writeFileSync(yamlPath, `transport: local\n${cur}`);
+      }
+      report.push(`  medium:     local (fs — no git)`);
+    } catch (err) {
+      process.stderr.write(`crosstalk transport init: failed to write transport key to ${yamlPath} — ${err.message}\n`);
+      return 1;
+    }
+  }
+
+  // ── Phase 3: Git init + initial commit ─────────────────────────────
+  if (!existsSync(crosstalkVersionFile)) {
+    process.stderr.write(
+      `crosstalk transport init: transport template missing at ${transportDir}\n` +
+      `  Engine init didn't write template files. Try 'crosstalk transport rm' then re-init.\n`,
+    );
+    return 1;
+  }
+
+  if (transportKind === 'git') {
+    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: transportDir, stdio: 'pipe' });
+      if (gr.status !== 0) {
+        gitOk = false;
+        break;
+      }
+    }
+    report.push(gitOk ? `  git:        initialized + committed` : `  git:        already present (skipped)`);
+  }
+
+  // ── Phase 4: Remote setup (git only) ───────────────────────────────
+  if (remote && transportKind === 'git') {
+    const cur = spawnSync('git', ['remote', 'get-url', 'origin'], {
+      cwd: transportDir,
+      stdio: 'pipe',
+    });
+    const currentUrl = cur.status === 0 ? cur.stdout.toString().trim() : null;
+    if (!currentUrl) {
+      const rr = spawnSync('git', ['remote', 'add', 'origin', remote], {
+        cwd: transportDir,
+        stdio: 'pipe',
+      });
+      if (rr.status !== 0) {
+        process.stderr.write(
+          `crosstalk transport 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 transport init: remote already set to '${currentUrl}'; refusing to overwrite with '${remote}'.\n`,
+      );
+      return 1;
+    }
+  }
+
+  // ── Phase 5: Summary ───────────────────────────────────────────────
+  process.stdout.write(
+    `\nTransport '${name}' ready:\n` +
+    `  storage:    ${paths.storageRoot}\n` +
+    `  transport:  ${transportDir}\n` +
+    report.join('\n') + '\n' +
+    `\nNext: crosstalk server start${customPath ? ` --path ${transportDir}` : (name === DEFAULT_CONTAINER_NAME ? '' : ` --containername ${name}`)}\n`,
+  );
+  return 0;
+}
+
+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);
+    });
+  });
+}
+
+async function runRm(argv) {
+  let name;
+  try {
+    name = parseContainerName(argv);
+  } catch (err) {
+    process.stderr.write(`crosstalk transport rm: ${err.message}\n`);
+    return 1;
+  }
+
+  const paths = storagePaths(name);
+  const haveStorage = isInitialized(name) || existsSync(paths.storageRoot);
+
+  if (!haveStorage) {
+    process.stderr.write(`crosstalk transport 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 transport rm: cancelled.\n');
+      return 1;
+    }
+  }
+
+  stopEngine(name);
+
+  try {
+    rmSync(paths.storageRoot, { recursive: true, force: true });
+  } catch (err) {
+    process.stderr.write(
+      `crosstalk transport rm: failed to remove ${paths.storageRoot} — ${err.message}\n`,
+    );
+    return 1;
+  }
+
+  process.stdout.write(`Removed '${name}'.\n`);
+  return 0;
+}

package/commands/version.js

@@ -20,13 +20,13 @@ export async function run(argv) {
     // Skew detection happens passively in api-client.js via the
     // X-Crosstalk-Engine-Version response header — no duplication here.
     const v = await api.get('/version');
-    process.stdout.write(`crosstalkd engine: ${v.version} (alias: ${v.alias})\n`);
+    process.stdout.write(`crosstalk engine: ${v.version} (alias: ${v.alias})\n`);
   } catch (err) {
     if (err instanceof ConnectError) {
-      process.stdout.write(`crosstalkd engine: (unreachable on 127.0.0.1:${err.port})\n`);
+      process.stdout.write(`crosstalk engine: (unreachable on 127.0.0.1:${err.port})\n`);
       return 0;
     }
-    process.stdout.write(`crosstalkd engine: (error: ${err.message})\n`);
+    process.stdout.write(`crosstalk engine: (error: ${err.message})\n`);
     return 0;
   }
   return 0;

package/commands/workflow.js

@@ -0,0 +1,234 @@
+// crosstalk workflow <compose|run|status> — multi-step workflow ops.
+//
+//   compose <prompt>  Interactive: engine compiles the prompt into a
+//                     workflow plan, prints the YAML for review, then
+//                     submits it. Operator can edit before submit.
+//   run <file>        Submit an already-authored workflow YAML file
+//                     (replaces v7's `crosstalk run --type workflow`).
+//   status [--id <id>] Snapshot in-flight workflows (parent channel,
+//                     phase, fanout state, completion). Without --id
+//                     lists every workflow on the transport.
+
+import { readFileSync, writeFileSync, existsSync, mkdtempSync, unlinkSync } from 'fs';
+import { spawnSync } from 'child_process';
+import { tmpdir } from 'os';
+import { join } from 'path';
+import { apiFor } from '../lib/api-client.js';
+import { reportAndExit } from '../lib/errors.js';
+import { flag, has, positionals } from '../lib/argv.js';
+
+function usage(exit = 0) {
+  const w = exit === 0 ? process.stdout : process.stderr;
+  w.write(
+`Usage:
+  crosstalk workflow compose <prompt>   [--channel <name|uuid>] [--compiler <model>]
+  crosstalk workflow run <file>         [--channel <name|uuid>] [--from <name>]
+  crosstalk workflow status [--id <childUuid>]
+`,
+  );
+  process.exit(exit);
+}
+
+export async function run(argv) {
+  if (has(argv, '--help') || has(argv, '-h')) usage(0);
+  const sub = argv[0];
+  if (!sub) usage(1);
+  const rest = argv.slice(1);
+
+  if (sub === 'compose') return await runCompose(rest);
+  if (sub === 'run')     return await runRun(rest);
+  if (sub === 'status')  return await runStatus(rest);
+
+  process.stderr.write(`crosstalk workflow: unknown subcommand '${sub}'.\n`);
+  usage(1);
+}
+
+function promptLine(label) {
+  return new Promise((resolve) => {
+    process.stdout.write(label);
+    const stdin = process.stdin;
+    stdin.setEncoding('utf-8');
+    stdin.resume();
+    let buf = '';
+    const onData = (chunk) => {
+      buf += chunk;
+      const nl = buf.indexOf('\n');
+      if (nl !== -1) {
+        stdin.removeListener('data', onData);
+        stdin.pause();
+        resolve(buf.slice(0, nl).replace(/\r$/, ''));
+      }
+    };
+    stdin.on('data', onData);
+  });
+}
+
+function editInEditor(initial) {
+  // Resolve editor: $VISUAL → $EDITOR → vi (POSIX default). Returns the
+  // edited contents, or null if the operator quit without saving.
+  const editor = process.env.VISUAL || process.env.EDITOR || 'vi';
+  const tmp = join(mkdtempSync(join(tmpdir(), 'crosstalk-wf-')), 'workflow.yaml');
+  writeFileSync(tmp, initial);
+  const r = spawnSync(editor, [tmp], { stdio: 'inherit' });
+  if (r.status !== 0) {
+    try { unlinkSync(tmp); } catch { /* best-effort */ }
+    return null;
+  }
+  let edited;
+  try { edited = readFileSync(tmp, 'utf-8'); } catch { edited = null; }
+  try { unlinkSync(tmp); } catch { /* best-effort */ }
+  return edited;
+}
+
+async function runCompose(argv) {
+  const pos = positionals(argv, [
+    '--channel', '--compiler', '--containername', '-c',
+    '--profile', '--server',
+  ]);
+  const prompt = pos.join(' ').trim();
+  if (!prompt) {
+    process.stderr.write('crosstalk workflow compose: <prompt> required.\n');
+    return 1;
+  }
+
+  const api = apiFor(argv);
+  const compilerAgent = flag(argv, '--compiler');
+  const channel = flag(argv, '--channel');
+
+  process.stderr.write('compiling workflow plan...\n');
+  let composed;
+  try {
+    composed = await api.post('/api/workflows/compose', {
+      prompt,
+      ...(compilerAgent ? { compilerAgent } : {}),
+    });
+  } catch (err) {
+    reportAndExit(err, 'crosstalk workflow compose');
+  }
+
+  let yaml = composed.yaml;
+  process.stdout.write(`\n--- compiled plan (via ${composed.compiler}) ---\n${yaml}\n--- end plan ---\n\n`);
+
+  while (true) {
+    const choice = (await promptLine('Submit? [y]es / [e]dit / [n]o: ')).trim().toLowerCase() || 'n';
+    if (choice === 'n' || choice === 'no') {
+      process.stdout.write('aborted.\n');
+      return 0;
+    }
+    if (choice === 'e' || choice === 'edit') {
+      const edited = editInEditor(yaml);
+      if (edited == null) {
+        process.stderr.write('editor exited non-zero; keeping original yaml.\n');
+        continue;
+      }
+      yaml = edited;
+      process.stdout.write(`\n--- edited plan ---\n${yaml}\n--- end plan ---\n\n`);
+      continue;
+    }
+    if (choice === 'y' || choice === 'yes') break;
+  }
+
+  let submitted;
+  try {
+    submitted = await api.post('/api/workflows/submit', {
+      yaml,
+      ...(channel ? { channel } : {}),
+      prompt,
+    });
+  } catch (err) {
+    reportAndExit(err, 'crosstalk workflow compose (submit)');
+  }
+  if (submitted.relPath) {
+    process.stdout.write(`Workflow dispatched: ${submitted.relPath}\n`);
+  }
+  if (submitted.childChannel) {
+    process.stdout.write(`Child channel: ${submitted.childChannel.slice(0, 8)} (parent: ${(submitted.channel || '').slice(0, 8)})\n`);
+  }
+  return 0;
+}
+
+async function runRun(argv) {
+  const pos = positionals(argv, [
+    '--channel', '--from', '--containername', '-c',
+    '--profile', '--server',
+  ]);
+  const file = pos[0];
+  if (!file) {
+    process.stderr.write('crosstalk workflow run: <file> required.\n');
+    return 1;
+  }
+  if (!existsSync(file)) {
+    process.stderr.write(`crosstalk workflow run: file not found — ${file}\n`);
+    return 1;
+  }
+  const body = readFileSync(file, 'utf-8');
+  if (body.length === 0) {
+    process.stderr.write('crosstalk workflow run: file is empty.\n');
+    return 1;
+  }
+
+  const api = apiFor(argv);
+  const payload = {
+    type: 'workflow',
+    channel: flag(argv, '--channel'),
+    from: flag(argv, '--from') ?? process.env.USER ?? 'operator',
+    body,
+  };
+  let resp;
+  try {
+    resp = await api.post('/messages', payload);
+  } catch (err) {
+    reportAndExit(err, 'crosstalk workflow run');
+  }
+  process.stdout.write(`Workflow dispatched: ${resp.relPath}\n`);
+  process.stdout.write(`Child channel: ${(resp.childChannel || '').slice(0, 8)} (parent: ${(resp.channel || '').slice(0, 8)})\n`);
+  return 0;
+}
+
+async function runStatus(argv) {
+  const api = apiFor(argv);
+  const id = flag(argv, '--id');
+  if (id) {
+    let r;
+    try { r = await api.get(`/api/workflows/${encodeURIComponent(id)}`); }
+    catch (err) { reportAndExit(err, 'crosstalk workflow status'); }
+    printDetail(r);
+    return 0;
+  }
+  let r;
+  try { r = await api.get('/api/workflows'); }
+  catch (err) { reportAndExit(err, 'crosstalk workflow status'); }
+  const list = r.workflows || [];
+  if (list.length === 0) {
+    process.stdout.write('(no workflows on this transport)\n');
+    return 0;
+  }
+  for (const w of list) printSummaryLine(w);
+  return 0;
+}
+
+function printSummaryLine(w) {
+  const id = (w.childUuid || '').slice(0, 8);
+  const parent = (w.parentName || (w.parentUuid || '').slice(0, 8) || '-');
+  const phase = w.phase || (w.isComplete ? 'complete' : 'in-flight');
+  const fan = w.fanoutDispatched != null
+    ? `${w.fanoutReplied}/${w.fanoutDispatched} replies`
+    : '';
+  process.stdout.write(`  ${id}  ${parent.padEnd(20)}  ${phase.padEnd(12)}  ${fan}\n`);
+}
+
+function printDetail(d) {
+  if (!d) {
+    process.stdout.write('(no detail)\n');
+    return;
+  }
+  const lines = [];
+  if (d.childUuid)      lines.push(`uuid:    ${d.childUuid}`);
+  if (d.parentUuid)     lines.push(`parent:  ${d.parentUuid}`);
+  if (d.markerRelPath)  lines.push(`marker:  ${d.markerRelPath}`);
+  if (d.phase)          lines.push(`phase:   ${d.phase}`);
+  if (d.fanoutDispatched != null) lines.push(`fanout:  ${d.fanoutReplied}/${d.fanoutDispatched} replies`);
+  if (d.synthesizeStatus) lines.push(`synth:   ${d.synthesizeStatus}`);
+  if (d.isComplete != null) lines.push(`complete: ${d.isComplete}`);
+  process.stdout.write(lines.join('\n') + '\n');
+}

package/deploy/crosstalk@.service

@@ -0,0 +1,62 @@
+# crosstalk@<transport>.service — systemd template for v8-native system mode.
+#
+# Install:
+#   sudo deploy/install.sh
+#   sudo systemctl daemon-reload
+#   sudo systemctl enable --now crosstalk@main
+#
+# Instances: one per named transport. The instance name (the `<name>` in
+# `crosstalk@<name>`) becomes the storage subdirectory under /var/lib/
+# crosstalk and the dispatcher alias the engine boots with.
+#
+# alpha.18 monorepo: the daemon is now an internal subcommand of the
+# same `crosstalk` CLI — `crosstalk daemon dispatch …` replaces the
+# dropped `crosstalkd` bin.
+#
+# Prereqs (handled by deploy/install.sh):
+#   - 'crosstalk' system user + group exist
+#   - /var/lib/crosstalk/<name>/ exists (crosstalk:crosstalk 0750)
+#   - /var/log/crosstalk/ exists (crosstalk:crosstalk 0750)
+#   - The transport for <name> has been initialized via
+#     `sudo -u crosstalk crosstalk transport init --containername <name>`
+
+[Unit]
+Description=crosstalk engine (transport: %i)
+Documentation=https://github.com/cordfuse/crosstalk
+After=network.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+User=crosstalk
+Group=crosstalk
+Environment=CROSSTALK_USER_MODE=
+Environment=DISPATCH_POLL_SECONDS=30
+Environment=DISPATCH_JSON=true
+WorkingDirectory=/var/lib/crosstalk/%i/transport
+ExecStart=/usr/bin/crosstalk daemon dispatch --alias %i --poll ${DISPATCH_POLL_SECONDS} --json
+Restart=on-failure
+RestartSec=5
+StandardOutput=append:/var/log/crosstalk/%i.log
+StandardError=append:/var/log/crosstalk/%i.log
+
+# Hardening — daemon needs nothing outside its own state + transport dirs.
+# Mirrors @cordfuse/llmux v2's llmuxd.service profile.
+NoNewPrivileges=true
+ProtectSystem=strict
+ProtectHome=true
+ReadWritePaths=/var/lib/crosstalk /var/log/crosstalk
+PrivateTmp=true
+PrivateDevices=true
+ProtectKernelTunables=true
+ProtectKernelModules=true
+ProtectControlGroups=true
+RestrictSUIDSGID=true
+RestrictAddressFamilies=AF_INET AF_INET6 AF_UNIX
+SystemCallFilter=@system-service
+SystemCallErrorNumber=EPERM
+LimitNOFILE=65536
+CapabilityBoundingSet=
+
+[Install]
+WantedBy=multi-user.target

package/deploy/install.sh

@@ -0,0 +1,82 @@
+#!/usr/bin/env bash
+# crosstalk v8-native system-mode install.
+#
+# Run as root. Sets up the `crosstalk` system user + group, /etc + /var
+# directories, the systemd template unit, and points operators at the
+# next step (initializing a transport + enabling its instance).
+#
+# Mirrors the @cordfuse/llmux v2 install pattern so Cordfuse family
+# deployments use the same shape: npm-install the binary globally,
+# run this script to set up the OS-level scaffolding, then enable
+# the systemd unit instance per named transport.
+
+set -euo pipefail
+
+# ─── prerequisite checks ─────────────────────────────────────────────────
+if [ "${EUID:-$(id -u)}" -ne 0 ]; then
+  echo "error: this installer must run as root" >&2
+  exit 1
+fi
+if ! command -v systemctl >/dev/null 2>&1; then
+  echo "error: systemd not detected. v8-native system mode currently requires systemd." >&2
+  echo "       For non-systemd hosts, run user mode: CROSSTALK_USER_MODE=1 crosstalk server start" >&2
+  exit 1
+fi
+if ! command -v crosstalk >/dev/null 2>&1; then
+  echo "error: crosstalk binary not on PATH." >&2
+  echo "       Install first: npm install -g @cordfuse/crosstalk" >&2
+  exit 1
+fi
+
+# ─── service user + group ────────────────────────────────────────────────
+if ! getent group crosstalk >/dev/null; then
+  groupadd --system crosstalk
+  echo "created group: crosstalk"
+fi
+if ! id crosstalk >/dev/null 2>&1; then
+  # --home-dir /var/lib/crosstalk: agent CLI auth tokens (~/.claude/,
+  # ~/.codex/, ~/.gemini/) live under the service user's home. Daemon
+  # never reaches into /home/* — same $HOME-principle as llmux v2.
+  useradd --system --gid crosstalk --home-dir /var/lib/crosstalk \
+          --shell /usr/sbin/nologin --comment "crosstalk engine daemon" crosstalk
+  echo "created user: crosstalk"
+fi
+
+# ─── directories ─────────────────────────────────────────────────────────
+install -d -o root      -g crosstalk -m 0750 /etc/crosstalk
+install -d -o crosstalk -g crosstalk -m 0750 /var/lib/crosstalk
+install -d -o crosstalk -g crosstalk -m 0750 /var/log/crosstalk
+# Per-transport state dirs (e.g., /var/lib/crosstalk/main/) are created on
+# first `crosstalk transport init --containername <name>` run by the
+# service user.
+
+# ─── systemd unit ────────────────────────────────────────────────────────
+SOURCE_DIR="$(cd "$(dirname "$0")" && pwd)"
+install -o root -g root -m 0644 \
+  "$SOURCE_DIR/crosstalk@.service" \
+  /etc/systemd/system/crosstalk@.service
+
+systemctl daemon-reload
+echo "installed: /etc/systemd/system/crosstalk@.service"
+
+# ─── next steps ──────────────────────────────────────────────────────────
+cat <<'EOF'
+
+crosstalk v8-native system-mode install complete.
+
+Initialize a transport (system mode is the default now; no env var needed):
+
+  sudo -u crosstalk crosstalk transport init --containername main
+
+Then enable + start the systemd instance for it:
+
+  sudo systemctl enable --now crosstalk@main
+  sudo systemctl status crosstalk@main
+  sudo journalctl -u crosstalk@main -f      # or: tail -f /var/log/crosstalk/main.log
+
+To run additional named transports, repeat with a different name:
+
+  sudo -u crosstalk crosstalk transport init --containername staging
+  sudo systemctl enable --now crosstalk@staging
+
+EOF