@cordfuse/crosstalk 7.0.0-beta.1 → 8.1.0

package/GUIDE-CLI.md

@@ -2,7 +2,7 @@
 
 Reference for the `crosstalk` CLI. Run `crosstalk <noun> --help` (or `crosstalk <noun> <verb> --help`) for inline flags.
 
-Requires: Node.js ≥ 20 + git on PATH. alpha.18 is a single-package install — `npm install -g @cordfuse/crosstalk`. The daemon lives as `crosstalk daemon …` inside the same package; there's no separate `crosstalkd` binary anymore.
+Requires: Node.js ≥ 20 + git on PATH. Single-package install: `npm install -g @cordfuse/crosstalk` (current: beta.1). The daemon lives as `crosstalk daemon …` inside the same package; there's no separate `crosstalkd` binary anymore (collapse landed in alpha.18; `@cordfuse/crosstalkd` is deprecated on npm).
 
 The surface is strict **noun-verb**, mirroring [`@cordfuse/llmux`](https://www.npmjs.com/package/@cordfuse/llmux):
 

package/README.md

@@ -1,16 +1,16 @@
 # Crosstalk
 
-**A shared message bus for humans and AI agents, built on git.**
+**A shared message bus for humans and AI agents. The bus is a directory — carried by git, or a plain/shared filesystem.**
 
-> **alpha.18 status.** Crosstalk is now a single npm package — `@cordfuse/crosstalk`. The separate `@cordfuse/crosstalkd` daemon package is deprecated; the daemon lives as `crosstalk daemon dispatch` inside this same package. CLI surface is strict noun-verb, mirroring `@cordfuse/llmux`. Operators on v7 (Docker) or alpha.17 should follow the upgrade notes at the bottom of this file.
+> **Status (8.x).** Crosstalk is a single npm package — `@cordfuse/crosstalk` (the separate `@cordfuse/crosstalkd` daemon package is deprecated; the daemon lives as `crosstalk daemon dispatch` inside this same package). CLI surface is strict noun-verb, mirroring `@cordfuse/llmux`. **As of 8.x the bus is transport-pluggable:** git (distributed, versioned, auditable) is the default; a local or shared filesystem — `transport: local`, including a mounted SMB/NFS share — needs no git and no remote. Select per transport with the `transport:` key in `data/crosstalk.yaml`.
 
 ---
 
 > ### Six words that come up everywhere on this page
 >
-> - **Transport** — a git repo, scaffolded by `crosstalk transport init`. It IS the message bus.
+> - **Transport** — the message bus, scaffolded by `crosstalk transport init`. A directory: a git repo (default — distributed, versioned) or a plain/shared filesystem (`transport: local`). It IS the bus.
 > - **Machine** — a host running one crosstalk engine. Identifies itself via the dispatcher `--alias` (defaulting to the transport name).
-> - **Message** — a markdown file with YAML frontmatter, committed to a channel. The unit of work.
+> - **Message** — a markdown file with YAML frontmatter, written to a channel. The unit of work.
 > - **Model** — a named agent invocation declared in `data/crosstalk.yaml` (e.g. `sonnet`, `codex-o3`).
 > - **Actor** — an optional persona file (`local/actors/<name>.md`) that prepends to a model's prompt as system context.
 > - **Channel** — a UUID directory under `data/channels/`. A conversation thread. Optionally parented.
@@ -32,15 +32,15 @@ The missing piece: a way to make **any** agent CLI talk to **any** other agent C
 
 ## The solution
 
-Crosstalk is that missing layer. The whole protocol is one idea — **a git repo is the message bus.**
+Crosstalk is that missing layer. The whole protocol is one idea — **a directory is the message bus.** Carry that directory with git (distributed, versioned, auditable) or a plain/shared filesystem (local, LAN, a mounted share) — same protocol either way.
 
 - **Any CLI participates.** If an agent's CLI runs one prompt non-interactively and prints a reply, it's a valid model. Mix Claude Code, Codex, Gemini CLI, Qwen Code, opencode, Antigravity — or any future CLI that follows the same shape — in one transport.
-- **Messages are commits.** Every send is a markdown file with YAML frontmatter, committed and pushed. The whole conversation is the git history: nothing to lose, nothing hidden, nothing to back up separately.
+- **Messages are files.** Every send is a markdown file with YAML frontmatter dropped into a channel. On the git transport each is a commit, so the whole conversation is git history — nothing to lose, nothing hidden, nothing to back up separately. On the filesystem transport it's just the files on disk.
 - **Peer-to-peer.** Each machine runs its own crosstalk engine. No broker, no central runtime, no registry.
-- **Multi-machine for free.** Git already solves "synchronize this across hosts." Crosstalk inherits that.
-- **Self-coordinating.** Collision-free filenames + rebase-retry on push mean the bus works correctly even with no central coordinator and concurrent writers.
+- **Multi-machine for free.** Git already solves "synchronize this across hosts"; a shared mount (SMB/NFS) does the same on a LAN. Crosstalk inherits whichever you point it at.
+- **Self-coordinating.** Collision-free filenames mean concurrent writers never clash; the git transport adds rebase-retry on push, the filesystem transport relies on the unique filenames alone. Either way the bus works correctly with no central coordinator.
 
-If you can `git push`, you can participate. No infrastructure to provision, no central server holding your conversation.
+No infrastructure to provision, no central server holding your conversation — just a directory, on git or a filesystem.
 
 ---
 
@@ -235,6 +235,26 @@ Same flow works for self-hosted Gitea or GitLab. Crosstalk doesn't care; it only
 
 ---
 
+## Local filesystem transport (no git)
+
+Don't want a git remote? Point Crosstalk at a plain directory instead — a local folder for a single host, or a **mounted SMB/NFS share** for several hosts on a LAN. No git, no remote, no infrastructure.
+
+```sh
+# Scaffold a local-fs transport straight onto the directory (e.g. a NAS mount):
+crosstalk transport init --transport local --path /mnt/share/crosstalk
+
+# Run the engine on it — the bus lives on the share, state stays machine-local:
+crosstalk server start --path /mnt/share/crosstalk
+```
+
+`--transport local` writes `transport: local` into `data/crosstalk.yaml` (no git init), and the dispatcher self-selects the filesystem transport: it reads/writes message files directly and picks up new ones via an mtime cursor — event-driven `fs.watch` on a true local FS, polling over a network mount. Each host that mounts the share runs its own engine and keeps its own machine-local cursor/heartbeat, so concurrent writers never clash (collision-free filenames).
+
+Tradeoffs vs. git: no version history, no audit trail, no conflict resolution beyond the unique filenames — but zero setup and no SSH/credentials. Reach for git when *what was said* matters; reach for the filesystem transport for quick local/LAN swarms.
+
+> **SFTP?** Mount it with `sshfs` and use `transport: local` — Crosstalk just sees a directory.
+
+---
+
 ## Adding a second machine
 
 Multi-machine adds exactly one new idea: **routing by alias.**
@@ -424,8 +444,8 @@ Transport git repos are portable — the storage path is unchanged (`~/.local/sh
 If you have a v7 Docker install:
 
 1. `docker compose -f <your-compose-file> down` first.
-2. `npm install -g @cordfuse/crosstalk@latest` — pulls alpha.18.
-3. If you previously installed `@cordfuse/crosstalkd`: `npm uninstall -g @cordfuse/crosstalkd` (deprecated, no longer published from alpha.18).
+2. `npm install -g @cordfuse/crosstalk@latest` — pulls the latest 8.x.
+3. If you previously installed `@cordfuse/crosstalkd`: `npm uninstall -g @cordfuse/crosstalkd` (deprecated, no longer published since alpha.18).
 4. In user mode: `export CROSSTALK_USER_MODE=1 && crosstalk server start --containername <name>`.
 5. In system mode: rerun `sudo ./deploy/install.sh` to lay down the new `crosstalk@.service` unit, then `sudo systemctl daemon-reload && sudo systemctl enable --now crosstalk@<name>`. The old `crosstalkd@<name>.service` files can be removed.
 
@@ -435,4 +455,4 @@ The v7 GHCR image `ghcr.io/cordfuse/crosstalk-server:*` is no longer being updat
 
 ## Status
 
-Crosstalk alpha.18 — single-package monorepo + strict noun-verb CLI. The protocol version lives at `CROSSTALK-VERSION` (single integer) at the transport root. Published as [`@cordfuse/crosstalk`](https://www.npmjs.com/package/@cordfuse/crosstalk).
+Crosstalk 8.x — single-package monorepo + strict noun-verb CLI, transport-pluggable (git or a local/shared filesystem). The protocol version lives at `CROSSTALK-VERSION` (single integer) at the transport root. Published as [`@cordfuse/crosstalk`](https://www.npmjs.com/package/@cordfuse/crosstalk).

package/commands/server.js

@@ -20,9 +20,10 @@
 
 import { spawn } from 'child_process';
 import { existsSync } from 'fs';
-import { has } from '../lib/argv.js';
+import { join, resolve } from 'path';
+import { has, flag } from '../lib/argv.js';
 import {
-  requireInitialized, storageMode,
+  requireInitialized, storageMode, parseContainerName,
   DEFAULT_CONTAINER_NAME,
 } from '../lib/resolve.js';
 import { startEngine, stopEngine, engineStatus } from '../lib/nativeServer.js';
@@ -56,7 +57,9 @@ function usage(exit = 0) {
 `Usage: crosstalk server <subverb> [--containername <name>]
 
 Subverbs:
-  start                start the engine as a detached host process
+  start [--path <dir>] start the engine; --path runs it on a transport at an
+                       arbitrary directory (e.g. a mounted share), state stays
+                       machine-local (user mode only)
   stop                 SIGTERM the running engine; SIGKILL after 5s grace
   restart              stop + start
   status [--probe]     report pid + uptime; --probe also pings /healthz
@@ -68,6 +71,35 @@ Storage mode defaults to 'system'; set CROSSTALK_USER_MODE=1 for user mode.
 }
 
 async function cmdStart(argv) {
+  // --path <dir>: run the engine on a transport at an arbitrary directory
+  // (e.g. a mounted SMB/NFS share) instead of the managed storage layout.
+  // State (cursor/heartbeat/pid/port) stays machine-local, keyed by name.
+  const transportPath = flag(argv, '--path');
+  if (transportPath) {
+    if (storageMode() === 'system') {
+      process.stderr.write(`crosstalk server start: --path is user-mode only (set CROSSTALK_USER_MODE=1).\n`);
+      return 1;
+    }
+    if (!existsSync(join(transportPath, 'CROSSTALK-VERSION'))) {
+      process.stderr.write(
+        `crosstalk server start: '${transportPath}' is not a crosstalk transport (no CROSSTALK-VERSION).\n` +
+        `  Scaffold it first:  crosstalk daemon init ${transportPath}\n`,
+      );
+      return 1;
+    }
+    const name = parseContainerName(argv);
+    const r = startEngine(name, { transportPath });
+    if (!r.ok) {
+      process.stderr.write(`crosstalk server start: ${r.error}\n`);
+      return 1;
+    }
+    process.stdout.write(
+      `'${name}' started on ${resolve(transportPath)} (pid ${r.pid}, api 127.0.0.1:${r.port}).\n` +
+      `  state stays machine-local; logs: crosstalk server logs${nameSuffix(name)} -f\n`,
+    );
+    return 0;
+  }
+
   const { name } = requireInitialized(argv);
   if (storageMode() === 'system') return redirectToSystemctl('start', name);
   const r = startEngine(name);

package/commands/transport.js

@@ -14,7 +14,7 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync, rmSync } from 'fs';
 import { spawnSync } from 'child_process';
 import { createInterface } from 'readline';
-import { join } from 'path';
+import { join, resolve } from 'path';
 import { has, flag } from '../lib/argv.js';
 import {
   parseContainerName,
@@ -29,7 +29,7 @@ function usage(exit = 0) {
   const w = exit === 0 ? process.stdout : process.stderr;
   w.write(
 `Usage:
-  crosstalk transport init [--containername <name>] [--remote <url>]
+  crosstalk transport init [--containername <name>] [--transport git|local] [--path <dir>] [--remote <url>]
   crosstalk transport rm   [--containername <name>] [--force]
   crosstalk transport --help
 
@@ -75,12 +75,22 @@ async function runInit(argv) {
   }
 
   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(paths.transportDir,   { recursive: true });
+    mkdirSync(transportDir,         { recursive: true });
     mkdirSync(paths.crosstalkRoot,  { recursive: true });
     mkdirSync(paths.crosstalkState, { recursive: true });
   } catch (err) {
@@ -116,7 +126,7 @@ async function runInit(argv) {
   }
 
   // ── Phase 2: Transport scaffold ────────────────────────────────────
-  const crosstalkVersionFile = join(paths.transportDir, 'CROSSTALK-VERSION');
+  const crosstalkVersionFile = join(transportDir, 'CROSSTALK-VERSION');
   if (!existsSync(crosstalkVersionFile)) {
     // Scaffold via `crosstalk daemon init <path>` — the same self-bin
     // call pattern startEngine() uses.
@@ -129,7 +139,7 @@ async function runInit(argv) {
     }
     const initRun = spawnSync(
       process.execPath,
-      [selfBin, 'daemon', 'init', paths.transportDir],
+      [selfBin, 'daemon', 'init', transportDir],
       { stdio: 'pipe' },
     );
     if (initRun.status !== 0) {
@@ -145,40 +155,59 @@ async function runInit(argv) {
     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 ${paths.transportDir}\n` +
+      `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;
   }
 
-  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) {
-      gitOk = false;
-      break;
+  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)`);
   }
-  report.push(gitOk ? `  git:        initialized + committed` : `  git:        already present (skipped)`);
 
-  // ── Phase 4: Remote setup ──────────────────────────────────────────
-  if (remote) {
+  // ── Phase 4: Remote setup (git only) ───────────────────────────────
+  if (remote && transportKind === 'git') {
     const cur = spawnSync('git', ['remote', 'get-url', 'origin'], {
-      cwd: paths.transportDir,
+      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: paths.transportDir,
+        cwd: transportDir,
         stdio: 'pipe',
       });
       if (rr.status !== 0) {
@@ -202,9 +231,9 @@ async function runInit(argv) {
   process.stdout.write(
     `\nTransport '${name}' ready:\n` +
     `  storage:    ${paths.storageRoot}\n` +
-    `  transport:  ${paths.transportDir}\n` +
+    `  transport:  ${transportDir}\n` +
     report.join('\n') + '\n' +
-    `\nNext: crosstalk server start${name === DEFAULT_CONTAINER_NAME ? '' : ` --containername ${name}`}\n`,
+    `\nNext: crosstalk server start${customPath ? ` --path ${transportDir}` : (name === DEFAULT_CONTAINER_NAME ? '' : ` --containername ${name}`)}\n`,
   );
   return 0;
 }

package/lib/nativeServer.js

@@ -67,18 +67,36 @@ export function startEngine(name, opts = {}) {
   const poll = String(opts.pollSeconds ?? process.env.DISPATCH_POLL_SECONDS ?? 30);
   const port = String(apiPortFor(name));
 
+  // --path: the transport lives at an arbitrary directory (e.g. a mounted
+  // share). Point the engine there via CROSSTALK_TRANSPORT_PATH, and pin
+  // state machine-local (by name) so cursor/heartbeat never land on the
+  // share — each machine sharing the dir keeps its own local state.
+  const transportDir = opts.transportPath ? resolve(opts.transportPath) : paths.transportDir;
   const env = {
     ...process.env,
     CROSSTALK_API_PORT: port,
-    TRANSPORT_DIR: paths.transportDir,
+    TRANSPORT_DIR: transportDir,
   };
+  // Default state to per-instance (keyed by name). Without this the
+  // dispatcher falls back to stateDir()'s default, keyed on
+  // basename(transportRoot) — always "transport" for a local-fs transport —
+  // so every named local instance would share one cursor/heartbeat/errors
+  // dir and clobber each other. Honor an explicit CROSSTALK_STATE_DIR if the
+  // caller already set one (the MC harness pins its heartbeat/cursor/errors
+  // there to isolate its run) — only fill in the default when it's absent.
+  if (!env.CROSSTALK_STATE_DIR) {
+    env.CROSSTALK_STATE_DIR = paths.crosstalkState;
+  }
+  if (opts.transportPath) {
+    env.CROSSTALK_TRANSPORT_PATH = transportDir;
+  }
 
   const logFd = openSync(paths.logFile, 'a');
   const child = spawn(
     process.execPath,
     [selfBin, 'daemon', 'dispatch', '--alias', alias, '--poll', poll, '--json'],
     {
-      cwd: paths.transportDir,
+      cwd: transportDir,
       env,
       stdio: ['ignore', logFd, logFd],
       detached: true,

package/lib/resolve.js

@@ -187,11 +187,13 @@ export function pickFreePort(name, mode = storageMode()) {
   throw new Error('Could not find a free port between 7001 and 7999.');
 }
 
-// True if `<base>/<name>/transport/.git` exists. The cheapest signal that
-// a transport has been initialized for this name.
+// True if the transport has been scaffolded for this name. Checks the
+// CROSSTALK-VERSION marker that `daemon init` writes for EVERY transport —
+// git and local-fs alike. (Was '.git', which wrongly rejected no-git local
+// transports: `server start` reported "no transport 'mc'".)
 export function isInitialized(name) {
   const paths = storagePaths(name);
-  return existsSync(join(paths.transportDir, '.git'));
+  return existsSync(join(paths.transportDir, 'CROSSTALK-VERSION'));
 }
 
 // True if the crosstalk engine is running for this transport. Source of truth:

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@cordfuse/crosstalk",
-  "version": "7.0.0-beta.1",
-  "description": "Crosstalk — agent-agnostic swarm communication protocol built on git. Operator CLI + daemon in one binary.",
+  "version": "8.1.0",
+  "description": "Crosstalk — agent-agnostic swarm communication protocol over a shared directory (git or filesystem transport). Operator CLI + daemon in one binary.",
   "type": "module",
   "license": "MIT",
   "homepage": "https://github.com/cordfuse/crosstalk",
@@ -26,7 +26,7 @@
   "scripts": {
     "build": "tsc --noEmit",
     "lint": "tsc --noEmit",
-    "test": "bun test",
+    "test": "node --import tsx --test tests/*.test.ts",
     "prepack": "cp -r transport template",
     "postpack": "rm -rf template"
   },

package/src/api.ts

@@ -33,14 +33,16 @@ import { now, messageFilename } from './filenames.js';
 import { parseFrontmatter, serializeFrontmatter } from './frontmatter.js';
 import {
   discoverChannels,
-  gitCommitAndPush,
   listChannelMessages,
+  type Transport,
 } from './transport.js';
 import { sendWakeSignal, readHeartbeat, readCursor, countErrors } from './state.js';
 import { reList } from './activation.js';
 import { isOnPath, type ModelEntry, type ModelsRegistry } from './models.js';
+import { AGENT_CATALOG, connectAgent } from './onboarding.js';
 import { resolveToField } from './resolve.js';
 import { dashboardPage } from './web/dashboard.js';
+import { wizardPage } from './web/wizard.js';
 import { channelListPage, channelViewPage, agentsPage, type BusMessage } from './web/channels.js';
 import { workflowsListPage, workflowDetailPage, type WorkflowSummary } from './web/workflows.js';
 import { setupPage as authSetupPage, loginPage as authLoginPage } from './web/auth-pages.js';
@@ -66,6 +68,9 @@ export interface ApiContext {
   version: string;
   registry: ModelsRegistry;
   claimed: Map<string, ModelEntry>;  // shorthand for registry.claimed
+  /** v8: the bus medium (git default, or local-fs). Web-UI writes publish
+   *  through this so a local-fs deployment never shells out to git. */
+  transport: Transport;
   /** Auth stores; v8-native. Optional — engine still runs without auth
    *  if the operator doesn't want it (just the web UI gating turns off). */
   userStore?: UserStore;
@@ -205,6 +210,7 @@ function handleStatus(ctx: ApiContext): JsonRes {
     status: 200,
     body: {
       transport_root: transportRoot,
+      transport_kind: ctx.transport.kind,
       alias: ctx.alias,
       version: ctx.version,
       claimed_models: [...ctx.claimed.keys()],
@@ -281,7 +287,7 @@ function handleCreateChannel(ctx: ApiContext, body: CreateChannelReq): JsonRes {
   const dir = join(transportRoot, 'data', 'channels', uuid);
   mkdirSync(dir, { recursive: true });
   writeFileSync(join(dir, 'CHANNEL.md'), serializeFrontmatter({ name: body.name }, ''));
-  const push = gitCommitAndPush(transportRoot, `channel(create): ${body.name} (${uuid.slice(0, 8)})`);
+  const push = ctx.transport.publish(`channel(create): ${body.name} (${uuid.slice(0, 8)})`);
   if (!push.committed && push.error) {
     // Commit itself failed (e.g. file system / git config issue).
     throw new HttpError(500, `commit failed: ${push.error.slice(0, 300)}`);
@@ -316,8 +322,7 @@ function handleRenameChannel(ctx: ApiContext, handle: string, body: RenameChanne
   const fm: Record<string, unknown> = { name: body.name };
   if (meta.parent) fm['parent'] = meta.parent;
   writeFileSync(chPath, serializeFrontmatter(fm, ''));
-  const push = gitCommitAndPush(
-    transportRoot,
+  const push = ctx.transport.publish(
     `channel(rename): ${meta.name ?? '(unnamed)'} -> ${body.name} (${meta.uuid.slice(0, 8)})`,
   );
   if (!push.committed && push.error) {
@@ -348,8 +353,7 @@ function handleDeleteChannel(ctx: ApiContext, handle: string, confirm: string |
   }
   const dir = join(transportRoot, 'data', 'channels', meta.uuid);
   rmSync(dir, { recursive: true, force: true });
-  const push = gitCommitAndPush(
-    transportRoot,
+  const push = ctx.transport.publish(
     `channel(delete): ${meta.name ?? '(unnamed)'} (${meta.uuid.slice(0, 8)})`,
   );
   if (!push.committed && push.error) {
@@ -458,7 +462,7 @@ function handlePostMessage(ctx: ApiContext, body: PostMessageReq): JsonRes {
       fanout === 1
         ? `run: ${from} -> ${toQualified} in ${channelUuid.slice(0, 8)}`
         : `run: ${from} -> ${toQualified} x${fanout} in ${channelUuid.slice(0, 8)}`;
-    const push = gitCommitAndPush(transportRoot, commitMsg);
+    const push = ctx.transport.publish(commitMsg);
     sendWakeSignal(transportRoot);
     if (!push.committed && push.error) {
       throw new HttpError(500, `commit failed: ${push.error.slice(0, 300)}`);
@@ -494,8 +498,7 @@ function handlePostMessage(ctx: ApiContext, body: PostMessageReq): JsonRes {
       extraFrontmatter,
       workflow: true,
     });
-    const push = gitCommitAndPush(
-      transportRoot,
+    const push = ctx.transport.publish(
       `run(workflow): ${from} child ${childUuid.slice(0, 8)}`,
     );
     sendWakeSignal(transportRoot);
@@ -663,7 +666,7 @@ async function tryWebAuthFlow(ctx: ApiContext, req: IncomingMessage, res: Server
   // setup/api-setup path, redirect to /setup so the first browser visit
   // bootstraps the admin account.
   const HTML_GATED_PATHS = new Set([
-    '/', '/agents', '/chat',
+    '/', '/welcome', '/agents', '/chat',
     '/tokens', '/logs', '/settings', '/account', '/users', '/about',
   ]);
   if (method === 'GET' && (HTML_GATED_PATHS.has(path) || path.startsWith('/c') || path.startsWith('/w'))) {
@@ -713,6 +716,7 @@ async function tryWebApiRoute(ctx: ApiContext, req: IncomingMessage, res: Server
     path === '/api/account' || path === '/api/account/passphrase' ||
     path === '/api/users' || path.startsWith('/api/users/') ||
     path === '/api/workflows' || path.startsWith('/api/workflows/') ||
+    path === '/api/onboarding/agents' || path === '/api/onboarding/connect' ||
     path === '/api/logs' || path === '/api/logs/stream' ||
     path === '/api/settings';
   if (!isApiPath) return false;
@@ -784,6 +788,41 @@ async function tryWebApiRoute(ctx: ApiContext, req: IncomingMessage, res: Server
     }
   }
 
+  // ── Onboarding wizard ────────────────────────────────────────────
+  // GET /api/onboarding/agents → catalog entries annotated with whether
+  // each CLI is installed on this engine's PATH and already claimed.
+  if (method === 'GET' && path === '/api/onboarding/agents') {
+    const agents = Object.values(AGENT_CATALOG).map((e) => ({
+      cli: e.cli, label: e.label, provider: e.provider, model: e.model,
+      installed: isOnPath(e.cli),
+      claimed: ctx.registry.claimed.has(`${e.provider}/${e.model}`),
+      needsKey: e.keyEnv !== null, keyHint: e.keyHint,
+    }));
+    writeJson(res, 200, { agents }, ctx.version);
+    return true;
+  }
+  // POST /api/onboarding/connect {cli, apiKey?} → admin: write the provider
+  // block (+ optional key file) and SIGHUP so the dispatcher claims it live.
+  if (method === 'POST' && path === '/api/onboarding/connect') {
+    if (!me.admin) { writeJson(res, 403, { error: 'admin only' }, ctx.version); return true; }
+    const body = await readJson<{ cli?: string; apiKey?: string }>(req);
+    const cli = (body.cli ?? '').trim();
+    if (!AGENT_CATALOG[cli]) { writeJson(res, 400, { error: `unknown agent CLI '${cli}'` }, ctx.version); return true; }
+    if (!isOnPath(cli)) { writeJson(res, 400, { error: `'${cli}' is not installed on this engine's PATH` }, ctx.version); return true; }
+    let result;
+    try {
+      result = connectAgent(ctx.transportRoot, cli, body.apiKey);
+    } catch (err) {
+      writeJson(res, 500, { error: `failed to write config: ${(err as Error).message}` }, ctx.version);
+      return true;
+    }
+    // Reload the registry live — the API runs in the dispatcher process, so
+    // SIGHUP to self triggers the registry hot-reload (see src/dispatch.ts).
+    try { process.kill(process.pid, 'SIGHUP'); } catch { /* best-effort */ }
+    writeJson(res, 200, { ok: true, ...result }, ctx.version);
+    return true;
+  }
+
   // ── Account: change passphrase ───────────────────────────────────
   if (method === 'POST' && path === '/api/account/passphrase') {
     const body = await readJson<{ oldPassphrase?: string; newPassphrase?: string }>(req);
@@ -1007,8 +1046,7 @@ async function tryWebApiRoute(ctx: ApiContext, req: IncomingMessage, res: Server
       extraFrontmatter,
       workflow: true,
     });
-    const push = gitCommitAndPush(
-      ctx.transportRoot,
+    const push = ctx.transport.publish(
       `run(workflow): ${me.username} child ${childUuid.slice(0, 8)} (composed)`,
     );
     sendWakeSignal(ctx.transportRoot);
@@ -1088,6 +1126,7 @@ async function tryHtmlRoute(ctx: ApiContext, req: IncomingMessage, res: ServerRe
     const channels = allChannelMeta(ctx.transportRoot);
     writeHtml(res, 200, dashboardPage({
       host, alias: ctx.alias, version: ctx.version, transportRoot: ctx.transportRoot,
+      transportKind: ctx.transport.kind,
       heartbeat: hb ? { ts: hb.ts, pid: hb.pid, version: hb.version, alias: hb.alias } : null,
       cursor: cursor ?? null,
       claimedModels: [...ctx.claimed.keys()],
@@ -1098,6 +1137,11 @@ async function tryHtmlRoute(ctx: ApiContext, req: IncomingMessage, res: ServerRe
     return true;
   }
 
+  if (path === '/welcome') {
+    writeHtml(res, 200, wizardPage({ host, alias: ctx.alias }), ctx.version);
+    return true;
+  }
+
   if (path === '/c') {
     const channels = allChannelMeta(ctx.transportRoot);
     writeHtml(res, 200, channelListPage({