@cordfuse/crosstalk 7.0.0-beta.1 → 8.1.0

package/src/dispatch.ts

@@ -20,16 +20,8 @@ import { readFileSync, existsSync, appendFileSync } from 'fs';
 import { watch } from 'fs/promises';
 import { fileURLToPath } from 'url';
 
-import { loadRegistry, type ModelEntry, type ModelsRegistry } from './models.js';
-import {
-  discoverChannels,
-  listChannelMessages,
-  gitPull,
-  gitCommitAndPush,
-  cursorBaseline,
-  newFilesSince,
-  type ChannelMessage,
-} from './transport.js';
+import { loadRegistry, loadTransportKind, type ModelEntry, type ModelsRegistry } from './models.js';
+import { GitTransport, LocalFsTransport, type Transport, type ChannelMessage } from './transport.js';
 import {
   stateDir,
   readCursor,
@@ -72,7 +64,10 @@ const RUNTIME_VERSION: string = (() => {
   }
 })();
 
-const transportRoot = resolve(process.cwd());
+// CROSSTALK_TRANSPORT_PATH points the engine at a transport directory
+// directly (defaults to cwd) — pairs with CROSSTALK_TRANSPORT_TYPE to run the
+// bus on a given directory (e.g. a mounted share) without a cd.
+const transportRoot = resolve(process.env['CROSSTALK_TRANSPORT_PATH'] ?? process.cwd());
 const argv = process.argv.slice(2);
 
 function flag(name: string): string | undefined {
@@ -87,6 +82,21 @@ const jsonMode = argv.includes('--json');
 const pollSeconds = Number(flag('--poll')) || 30;
 const logFile = flag('--log-file');
 
+// v8: the dispatch loop drives the bus through a Transport, not git calls.
+// Selection precedence: --transport flag > CROSSTALK_TRANSPORT_TYPE env >
+// `transport:` in crosstalk.yaml > git default. local = plain-fs, incl. a
+// mounted SMB/NFS share. The fs transport drops in with zero changes below.
+const transportOverride = flag('--transport') ?? process.env['CROSSTALK_TRANSPORT_TYPE'];
+if (transportOverride !== undefined && transportOverride !== 'git' && transportOverride !== 'local') {
+  console.error(`crosstalk daemon dispatch: unknown transport '${transportOverride}' (expected git|local); falling back to config/default.`);
+}
+const transportKind = (transportOverride === 'git' || transportOverride === 'local')
+  ? transportOverride
+  : loadTransportKind(transportRoot);
+const transport: Transport = transportKind === 'local'
+  ? new LocalFsTransport(transportRoot)
+  : new GitTransport(transportRoot);
+
 if (!alias) {
   console.error('crosstalk daemon dispatch: --alias <name> is required (machine identity in the bus).');
   process.exit(1);
@@ -208,14 +218,14 @@ async function dispatchTick(registry: ModelsRegistry, protocolPrompt: string): P
   const claimed = registry.claimed;
   writeHeartbeat(transportRoot, RUNTIME_VERSION, alias!);
 
-  const pullResult = gitPull(transportRoot);
+  const pullResult = transport.sync();
   if (!pullResult.ok) {
     logError(transportRoot, `git pull failed: ${pullResult.error}`, 'warn');
     log('git_pull_failed', { error: (pullResult.error ?? '').slice(0, 200) });
     return false;
   }
 
-  const head = cursorBaseline(transportRoot);
+  const head = transport.head();
   if (!head) {
     logError(transportRoot, 'git rev-parse failed for origin/HEAD and HEAD — skipping tick');
     return false;
@@ -231,7 +241,7 @@ async function dispatchTick(registry: ModelsRegistry, protocolPrompt: string): P
     cursor = head;
     log('cursor_seeded', { commit: head.slice(0, 12) });
   }
-  const channels = discoverChannels(transportRoot);
+  const channels = transport.discoverChannels();
   const activationDue = cursor !== head;
 
   let didWork = false;
@@ -252,7 +262,7 @@ async function dispatchTick(registry: ModelsRegistry, protocolPrompt: string): P
 
   const writeNeeded = didWork || workflowProgressed;
   if (writeNeeded) {
-    const push = gitCommitAndPush(transportRoot, `dispatch(${alias}): replies ${new Date().toISOString()}`);
+    const push = transport.publish(`dispatch(${alias}): replies ${new Date().toISOString()}`);
     if (!push.ok && push.error) {
       // Commit failed is a real error (local state out of sync); push
       // failed with the commit landing is a warning (push will retry).
@@ -271,17 +281,15 @@ async function runActivationPass(
   cursor: string,
   head: string,
 ): Promise<boolean> {
-  const addedList = newFilesSince(transportRoot, cursor);
+  const addedList = transport.newFilesSince(cursor, head);
   if (addedList === null) {
     logError(transportRoot, `cursor ${cursor.slice(0, 12)} unknown — re-scanning all channels`, 'warn');
   }
   const added: Set<string> | null = addedList === null ? null : new Set(addedList);
-
-  void head;  // head is the diff's upper bound implicitly (newFilesSince uses HEAD).
   const pending: PendingDispatch[] = [];
 
   for (const channelUuid of channels) {
-    const messages = listChannelMessages(transportRoot, channelUuid);
+    const messages = transport.listChannelMessages(channelUuid);
     const senderByRelPath = new Map(messages.map((m) => [m.relPath, messageSender(m)]));
     // Normalize asker identity the same way self-suppression does: strip
     // the @machine suffix before comparing against actorName. Without
@@ -336,18 +344,46 @@ async function runActivationPass(
   return results.some(Boolean);
 }
 
+// Block until something worth a tick happens, or `ms` elapses (the poll
+// fallback). Two wake sources race the timeout:
+//   • the state dir's `wake.signal` — written by sendWakeSignal on a
+//     same-host API post (channel/message create).
+//   • the transport's inbound dir (local-fs: data/channels, watched
+//     recursively) — zero-lag pickup when a writer drops a message straight
+//     onto the bus (a peer on a shared mount, a file drop). git returns null
+//     (a remote isn't watchable); fs.watch also won't fire over SMB/NFS — so
+//     the poll timeout stays the always-on backstop.
 async function waitForWakeOrTimeout(ms: number): Promise<void> {
-  const dir = stateDir(transportRoot);
   const ac = new AbortController();
   const timer = setTimeout(() => ac.abort(), ms);
-  try {
-    const watcher = watch(dir, { signal: ac.signal });
-    for await (const ev of watcher) {
-      if (ev.filename === 'wake.signal') return;
+
+  const watchFor = async (dir: string, recursive: boolean): Promise<void> => {
+    try {
+      const watcher = watch(dir, { signal: ac.signal, recursive });
+      for await (const ev of watcher) {
+        // state dir: only wake.signal. bus dir: any new .md is a candidate
+        // message — wake and let the tick's cursor decide if it's new.
+        if (recursive ? (ev.filename?.endsWith('.md') ?? false) : ev.filename === 'wake.signal') return;
+      }
+    } catch {
+      if (ac.signal.aborted) return;  // timeout — expected
+      // watch unavailable (recursive unsupported, network FS, missing dir):
+      // don't spin — wait out the poll interval via the abort signal.
+      await new Promise<void>((res) => {
+        if (ac.signal.aborted) res();
+        else ac.signal.addEventListener('abort', () => res(), { once: true });
+      });
     }
-  } catch {
-    /* abort = timeout */
+  };
+
+  const waits: Promise<void>[] = [watchFor(stateDir(transportRoot), false)];
+  const busDir = transport.watchDir();
+  if (busDir && existsSync(busDir)) waits.push(watchFor(busDir, true));
+
+  try {
+    await Promise.race(waits);
   } finally {
+    ac.abort();
     clearTimeout(timer);
   }
 }
@@ -371,7 +407,7 @@ async function main(): Promise<void> {
     }
     removePidfile(transportRoot);
     if (alias) removeRegistryEntry(transportRoot, alias);
-    const push = gitCommitAndPush(transportRoot, `dispatch(${alias}): deregister entry`);
+    const push = transport.publish(`dispatch(${alias}): deregister entry`);
     if (!push.ok && push.error) {
       logError(transportRoot, `registry deregister failed: ${push.error}`, 'warn');
     }
@@ -414,13 +450,14 @@ async function main(): Promise<void> {
   // races to duplicate. Commit+push immediately so cross-machine
   // visibility doesn't wait for first reply traffic.
   writeRegistryEntry(transportRoot, alias!, [...registry.claimed.keys()], RUNTIME_VERSION);
-  const registryPush = gitCommitAndPush(transportRoot, `dispatch(${alias}): register entry`);
+  const registryPush = transport.publish(`dispatch(${alias}): register entry`);
   if (!registryPush.ok && registryPush.error) {
     logError(transportRoot, `registry publish failed: ${registryPush.error}`, 'warn');
   }
 
   log('dispatch_start', {
     transport: transportRoot,
+    transport_kind: transport.kind,
     alias,
     version: RUNTIME_VERSION,
     state_dir: stateDir(transportRoot),
@@ -454,6 +491,7 @@ async function main(): Promise<void> {
     apiServer = startApi(
       {
         transportRoot,
+        transport,
         alias: alias!,
         version: RUNTIME_VERSION,
         registry,
@@ -466,6 +504,35 @@ async function main(): Promise<void> {
     );
   }
 
+  // Hot-reload the model registry on SIGHUP, no restart. The dispatcher
+  // loads crosstalk.yaml once at startup; the onboarding wizard (and any
+  // operator who edits the yaml) raises SIGHUP so newly-added providers/
+  // models are claimed live. Mutate the EXISTING registry maps in place —
+  // the running API context captured these map references at startApi(), so
+  // reassigning `registry` would leave /status + the dashboard stale.
+  process.on('SIGHUP', () => {
+    try {
+      const fresh = loadRegistry(transportRoot);
+      registry.all.clear();
+      for (const [k, v] of fresh.all) registry.all.set(k, v);
+      registry.byBareName.clear();
+      for (const [k, v] of fresh.byBareName) registry.byBareName.set(k, v);
+      registry.claimed.clear();
+      for (const [k, v] of fresh.claimed) registry.claimed.set(k, v);
+      writeRegistryEntry(transportRoot, alias!, [...registry.claimed.keys()], RUNTIME_VERSION);
+      const push = transport.publish(`dispatch(${alias}): reload registry (SIGHUP)`);
+      if (!push.ok && push.error) {
+        logError(transportRoot, `registry publish after reload failed: ${push.error}`, 'warn');
+      }
+      log('registry_reloaded', {
+        claimed_models: [...registry.claimed.keys()],
+        total_models: registry.all.size,
+      });
+    } catch (err) {
+      logError(transportRoot, `registry reload (SIGHUP) failed — keeping current set: ${(err as Error).message}`, 'warn');
+    }
+  });
+
   if (onceMode) {
     await dispatchTick(registry, protocolPrompt);
     process.exit(0);

package/src/models.ts

@@ -102,6 +102,23 @@ function parseInlineEnv(
   return Object.keys(out).length > 0 ? out : null;
 }
 
+export type TransportKind = 'git' | 'local';
+
+// The optional top-level `transport:` key in data/crosstalk.yaml selects the
+// bus medium. 'local' = the filesystem transport (a plain directory, incl. a
+// mounted SMB/NFS share); absent / anything else / unreadable → 'git'. A
+// --transport flag at dispatch boot overrides this.
+export function loadTransportKind(transportRoot: string): TransportKind {
+  const path = crosstalkYamlPath(transportRoot);
+  if (!existsSync(path)) return 'git';
+  try {
+    const parsed = parseYaml(readFileSync(path, 'utf8')) as Record<string, unknown> | null;
+    return parsed && parsed['transport'] === 'local' ? 'local' : 'git';
+  } catch {
+    return 'git';
+  }
+}
+
 export function readModels(transportRoot: string): {
   all: Map<string, ModelEntry>;
   byBareName: Map<string, ModelEntry[]>;

package/src/onboarding.ts

@@ -0,0 +1,136 @@
+// onboarding.ts — agent catalog + config writers backing the first-run
+// wizard. The wizard turns "0 agents connected" into a working agent by
+// writing a provider block to data/crosstalk.yaml (and, optionally, an API
+// key to auth/<provider>.env) and raising SIGHUP so the dispatcher claims
+// the new model live. See src/dispatch.ts SIGHUP handler + src/web/wizard.ts.
+
+import { readFileSync, writeFileSync, mkdirSync } from 'fs';
+import { join, dirname } from 'path';
+import { parseDocument, YAMLMap } from 'yaml';
+import { crosstalkYamlPath } from './models.js';
+
+export interface AgentCatalogEntry {
+  cli: string;            // binary name (matches KNOWN_AGENT_BINARIES in api.ts)
+  label: string;          // display name for the wizard
+  provider: string;       // provider key written to the yaml
+  model: string;          // model name written under the provider
+  command: string;        // command string the dispatcher runs
+  keyEnv: string | null;  // env var the key goes in, or null if host-authed
+  keyHint: string;        // guidance shown next to the (optional) key field
+}
+
+// Default command strings mirror the documented examples in the template
+// crosstalk.yaml. Most of these CLIs authenticate via their own host
+// credential store (codex ~/.codex/auth.json, claude/gemini interactive
+// login), so the key field is optional — on a host where the CLI is already
+// logged in, just writing the model entry yields a working agent.
+export const AGENT_CATALOG: Record<string, AgentCatalogEntry> = {
+  claude: {
+    cli: 'claude', label: 'Claude (Anthropic)', provider: 'anthropic', model: 'sonnet',
+    command: 'claude --print --dangerously-skip-permissions --model sonnet',
+    keyEnv: 'ANTHROPIC_API_KEY',
+    keyHint: 'Leave blank if `claude` is already logged in on this host; otherwise paste an Anthropic API key.',
+  },
+  codex: {
+    cli: 'codex', label: 'Codex (OpenAI)', provider: 'openai-codex', model: 'codex',
+    command: 'codex --skip-git-repo-check',
+    keyEnv: null,
+    keyHint: 'Codex uses its own login (`codex login`) — no key needed here.',
+  },
+  gemini: {
+    cli: 'gemini', label: 'Gemini (Google)', provider: 'google', model: 'gemini',
+    command: 'gemini --skip-trust --yolo -p',
+    keyEnv: 'GEMINI_API_KEY',
+    keyHint: 'Leave blank if `gemini` is already logged in; otherwise paste a Google AI Studio key.',
+  },
+  agy: {
+    cli: 'agy', label: 'Antigravity (Google)', provider: 'google-agy', model: 'agy',
+    command: 'agy --print',
+    keyEnv: 'GEMINI_API_KEY',
+    keyHint: 'Leave blank if already authenticated; otherwise paste a Google AI Studio key.',
+  },
+  qwen: {
+    cli: 'qwen', label: 'Qwen', provider: 'qwen', model: 'qwen',
+    command: 'qwen --yolo -p',
+    keyEnv: null,
+    keyHint: 'Qwen uses its own login — no key needed here.',
+  },
+  opencode: {
+    cli: 'opencode', label: 'OpenCode', provider: 'opencode', model: 'opencode',
+    command: 'opencode run',
+    keyEnv: null,
+    keyHint: 'OpenCode uses its own provider config — no key needed here.',
+  },
+};
+
+export interface ConnectResult {
+  provider: string;
+  model: string;
+  qualified: string;
+  wroteKey: boolean;
+}
+
+/**
+ * Write a provider/model block to data/crosstalk.yaml (preserving the file's
+ * comments via the YAML Document API) and, when an apiKey is supplied for a
+ * key-based provider, an auth/<provider>.env file (0600). Idempotent: adding
+ * a provider/model that already exists just overwrites that leaf.
+ *
+ * Does NOT reload the dispatcher — the caller raises SIGHUP after this returns.
+ */
+export function connectAgent(transportRoot: string, cli: string, apiKey?: string): ConnectResult {
+  const entry = AGENT_CATALOG[cli];
+  if (!entry) throw new Error(`unknown agent CLI '${cli}'`);
+
+  let envFile: string | null = null;
+  const key = (apiKey ?? '').trim();
+  if (entry.keyEnv && key.length > 0) {
+    envFile = `auth/${entry.provider}.env`;
+    const envPath = join(transportRoot, envFile);
+    mkdirSync(dirname(envPath), { recursive: true });
+    // 0600 — secrets file, owner-only. env_file (a relpath) is what lands in
+    // the committable yaml; the raw key stays out of it.
+    writeFileSync(envPath, `${entry.keyEnv}=${key}\n`, { mode: 0o600 });
+  }
+
+  const yamlPath = crosstalkYamlPath(transportRoot);
+  const raw = readFileSync(yamlPath, 'utf-8');
+  const doc = parseDocument(raw);
+  const providers = doc.get('providers');
+  const provExists = providers instanceof YAMLMap && providers.has(entry.provider);
+
+  if (provExists) {
+    // Provider already present (re-run, or adding a second model) — merge
+    // via the Document API so the existing structure's comments survive.
+    const prov = (providers as YAMLMap).get(entry.provider) as YAMLMap;
+    let models = prov.get('models');
+    if (!(models instanceof YAMLMap)) { models = new YAMLMap(); prov.set('models', models); }
+    (models as YAMLMap).set(entry.model, entry.command);
+    if (envFile) prov.set('env_file', envFile);
+    writeFileSync(yamlPath, doc.toString());
+  } else {
+    // New provider — append as text rather than restructuring, so the
+    // template's commented schema docs + example blocks are preserved
+    // verbatim (rewriting the Document drops comments attached to the empty
+    // `providers:` node). The file ends inside the `providers:` mapping, so
+    // a two-space-indented block becomes its child.
+    const block = envFile
+      ? `  ${entry.provider}:\n    env_file: ${envFile}\n    models:\n      ${entry.model}: ${entry.command}\n`
+      : `  ${entry.provider}:\n    models:\n      ${entry.model}: ${entry.command}\n`;
+    // Only synthesize a top-level `providers:` if the file genuinely lacks
+    // one — checked against the raw text so a present-but-null `providers:`
+    // (the template default) doesn't get a duplicate key appended.
+    const hasProvidersKey = /^providers\s*:/m.test(raw);
+    let out = raw.replace(/\s*$/, '') + '\n';
+    if (!hasProvidersKey) out += '\nproviders:\n';
+    out += block;
+    writeFileSync(yamlPath, out);
+  }
+
+  return {
+    provider: entry.provider,
+    model: entry.model,
+    qualified: `${entry.provider}/${entry.model}`,
+    wroteKey: envFile !== null,
+  };
+}

package/src/state.ts

@@ -44,18 +44,23 @@ export function stateDir(transportRoot: string): string {
 
 // ── cursor (single, machine-global) ──
 //
-// A cursor is the git commit hash the transport was last scanned at. NOT a
-// message relPath: filenames order by sender timestamp, but messages reach
-// origin in PUSH order — a message that loses a push race can land on
-// origin with a timestamp earlier than one already processed, and a
-// relPath cursor would skip it forever. Commit-based cursors can't.
+// The cursor is an opaque, transport-OWNED token marking where this machine
+// last scanned. Storage here is format-agnostic: any non-empty string round-
+// trips, and each transport validates + interprets its own token. An
+// unrecognized token (e.g. after switching transports) makes the transport's
+// newFilesSince return null, and the loop full-scans to recover.
+//
+// Git's token is a commit SHA, and that choice is deliberate: filenames order
+// by sender timestamp, but messages reach origin in PUSH order — a message
+// that loses a push race can land with a timestamp earlier than one already
+// processed, and a relPath/time cursor would skip it forever. Commit cursors
+// can't. The local-fs transport uses an mtime watermark instead, which is
+// safe ONLY because a single local machine has one clock and no push races.
 //
 // v6 kept one cursor per (actor × channel). v7 collapses to a single
 // machine-global cursor: a dispatcher processes everything new since the
 // cursor in one tick, regardless of channel or claimed model.
 
-const VALID_CURSOR = /^[0-9a-f]{40}$/;
-
 export function cursorPath(transportRoot: string): string {
   return join(stateDir(transportRoot), 'cursor');
 }
@@ -71,15 +76,11 @@ export function readCursor(transportRoot: string): string | null {
     return null;
   }
   if (raw.length === 0) return null;
-  if (!VALID_CURSOR.test(raw)) {
-    logError(transportRoot, `invalid cursor '${raw.slice(0, 80)}' — re-scanning from origin`, 'warn');
-    return null;
-  }
   return raw;
 }
 
-export function writeCursor(transportRoot: string, commit: string): void {
-  writeFileSync(cursorPath(transportRoot), commit + '\n');
+export function writeCursor(transportRoot: string, token: string): void {
+  writeFileSync(cursorPath(transportRoot), token + '\n');
 }
 
 // ── pidfile ──

package/src/transport.ts

@@ -1,4 +1,6 @@
-// Git transport layer. The dispatcher's commits contain ONLY data/ —
+// Transport layer. The git transport functions are here; the Transport
+// interface + GitTransport/LocalFsTransport live at the foot of this file.
+// The git dispatcher's commits contain ONLY data/ —
 // machine-local state lives in the state dir (state.ts), so there is
 // nothing to exclude, untrack, or heal. Push rejection means another
 // machine won the race: pull --rebase and retry at the call site.
@@ -78,9 +80,9 @@ export function cursorBaseline(transportRoot: string): string | null {
 // HEAD. Returns null when the commit is unknown to this clone (state dir
 // copied across transports, history rewritten) — caller falls back to a
 // full channel scan.
-export function newFilesSince(transportRoot: string, sinceCommit: string): string[] | null {
+export function newFilesSince(transportRoot: string, sinceCommit: string, head: string): string[] | null {
   const r = captureGit(transportRoot, [
-    'diff', '--name-only', '--diff-filter=A', `${sinceCommit}..HEAD`, '--', 'data/channels/',
+    'diff', '--name-only', '--diff-filter=A', `${sinceCommit}..${head}`, '--', 'data/channels/',
   ]);
   if (r.status !== 0) return null;
   return r.stdout.split('\n').filter(Boolean);
@@ -241,3 +243,111 @@ export function listChannelMessages(transportRoot: string, channelUuid: string):
   walk(channelDir, '');
   return results.sort((a, b) => a.relPath.localeCompare(b.relPath));
 }
+
+// ── Transport abstraction (v8) ──
+//
+// The dispatch loop talks to a medium through this interface, never to git
+// directly. The CURSOR is an opaque, transport-owned token: dispatch.ts
+// persists whatever string a transport hands back and round-trips it to
+// `newFilesSince` next tick without interpreting it. Git's token is a
+// 40-hex commit SHA (see state.ts on why commit cursors, not relPaths);
+// a future fs transport is free to use a different token shape that is
+// correct for its medium. `head()` returns the upper bound for this tick;
+// `newFilesSince(cursor)` returns repo-relative message paths added in
+// (cursor, head], or null when the cursor is unrecognizable (caller then
+// full-scans). `sync()` pulls remote state in; `publish()` flushes locally
+// written replies out. Message reads (discoverChannels/listChannelMessages)
+// are already plain-fs and identical across every transport.
+export interface Transport {
+  readonly kind: string;
+  sync(): GitResult;
+  head(): string | null;
+  newFilesSince(cursor: string, head: string): string[] | null;
+  publish(message: string): GitPushResult;
+  discoverChannels(): string[];
+  listChannelMessages(channelUuid: string): ChannelMessage[];
+  /** A directory to fs.watch for inbound messages (zero-lag wake), or null
+   *  if the medium can't be watched (git: a remote isn't watchable — the
+   *  poll loop covers it). fs.watch also won't fire over SMB/NFS, so the
+   *  poll stays the backstop even when this is non-null. */
+  watchDir(): string | null;
+}
+
+// Git transport — the original and, until the fs transport lands, the only
+// implementation. A thin pass-through to the module functions above; it
+// adds no behavior, it only moves them behind the interface so dispatch.ts
+// stops importing git operations by name.
+export class GitTransport implements Transport {
+  readonly kind = 'git';
+  constructor(private readonly root: string) {}
+  sync(): GitResult { return gitPull(this.root); }
+  head(): string | null { return cursorBaseline(this.root); }
+  newFilesSince(cursor: string, head: string): string[] | null { return newFilesSince(this.root, cursor, head); }
+  publish(message: string): GitPushResult { return gitCommitAndPush(this.root, message); }
+  discoverChannels(): string[] { return discoverChannels(this.root); }
+  listChannelMessages(channelUuid: string): ChannelMessage[] { return listChannelMessages(this.root, channelUuid); }
+  watchDir(): string | null { return null; }  // a git remote isn't fs.watchable — poll covers inbound
+}
+
+// Local filesystem transport — single machine, no remote, no git. The bus is
+// just a directory tree (it can sit on an SMB/NFS mount; from here it's all
+// the same plain fs). Mount this on /mnt/share and two daemons on the same
+// host, or on hosts sharing the mount, see each other's messages with zero
+// infrastructure.
+//
+// sync()/publish() are no-ops: there's no remote to pull from, and replies
+// are written straight to disk by writeReply — the write IS the publish.
+//
+// The cursor is an epoch-millis mtime watermark. head() is "now" at tick
+// start; newFilesSince returns message files with mtime in (cursor, head].
+// mtime is a sound ordering key HERE and ONLY here: a single local machine
+// has one monotonic clock and no push-race reordering — the exact failure
+// mode state.ts forbids relPath/time cursors over for git/remote media. Do
+// NOT lift this watermark onto SMB/NFS spanning multiple writers without
+// revisiting that guarantee.
+export class LocalFsTransport implements Transport {
+  readonly kind = 'local';
+  constructor(private readonly root: string) {}
+
+  sync(): GitResult { return { ok: true }; }
+  publish(_message: string): GitPushResult { return { ok: true, committed: true, pushed: false }; }
+  head(): string | null { return String(Date.now()); }
+  discoverChannels(): string[] { return discoverChannels(this.root); }
+  listChannelMessages(channelUuid: string): ChannelMessage[] { return listChannelMessages(this.root, channelUuid); }
+  // Watch the channels tree for inbound message drops — event-driven, zero
+  // lag, the v1.1.0 "real-time local" property. Fires only on a true local
+  // FS; a share-mounted dir falls back to the dispatch loop's poll.
+  watchDir(): string | null { return join(this.root, 'data', 'channels'); }
+
+  newFilesSince(cursor: string, head: string): string[] | null {
+    const since = Number(cursor);
+    const until = Number(head);
+    // Unrecognized token (e.g. a git SHA left over from a transport switch)
+    // → null tells the loop to full-scan, after which we write our own.
+    if (!Number.isFinite(since) || !Number.isFinite(until)) return null;
+    const channelsDir = join(this.root, 'data', 'channels');
+    if (!existsSync(channelsDir)) return [];
+    const out: string[] = [];
+    for (const channelUuid of this.discoverChannels()) {
+      const walk = (dir: string, prefix: string): void => {
+        let entries: string[];
+        try { entries = readdirSync(dir); } catch { return; }
+        for (const entry of entries) {
+          const full = join(dir, entry);
+          let stat;
+          try { stat = statSync(full); } catch { continue; }
+          if (stat.isDirectory()) {
+            walk(full, prefix ? `${prefix}/${entry}` : entry);
+          } else if (entry.endsWith('.md') && entry !== 'CHANNEL.md') {
+            if (stat.mtimeMs > since && stat.mtimeMs <= until) {
+              const rel = prefix ? `${prefix}/${entry}` : entry;
+              out.push(`data/channels/${channelUuid}/${rel}`);
+            }
+          }
+        }
+      };
+      walk(join(channelsDir, channelUuid), '');
+    }
+    return out;
+  }
+}

package/src/web/channels.ts

@@ -21,7 +21,7 @@ export function channelListPage(d: ChannelListData): string {
     <span>Channels (${d.channels.length})</span>
     <button id="open-new-channel" class="primary" type="button" style="font-size:11px;font-weight:600">+ new channel</button>
   </h3>
-  <p class="sub">Each channel is a directory under <code>data/channels/&lt;uuid&gt;/</code>. Messages and replies live as committed markdown files.</p>
+  <p class="sub">A channel is a conversation thread. Post a message addressed to an agent and the dispatcher delivers its reply here. (Under the hood, each channel is a folder of markdown files on the bus.)</p>
   <div id="new-channel-form" style="display:none;background:#0b0c10;border:1px solid #1f2329;border-radius:6px;padding:12px;margin-bottom:14px">
     <div class="field" style="margin-bottom:8px">
       <label for="new-channel-name">Channel name</label>
@@ -352,36 +352,38 @@ export interface AgentsPageData {
 }
 
 export function agentsPage(d: AgentsPageData): string {
-  function chips(list: string[], highlightedList: string[], emptyMsg: string): string {
-    if (list.length === 0) return `<p class="empty">${escapeHtml(emptyMsg)}</p>`;
-    return list.map(a => {
-      const cls = highlightedList.includes(a) ? 'chip brand' : 'chip';
-      return `<span class="${cls}">${escapeHtml(a)}</span>`;
-    }).join('');
+  // One row per supported CLI with its resolved status, rather than four
+  // cards of look-alike chips (the catalog and the installed list were
+  // identical whenever every supported CLI happened to be on PATH, and the
+  // chips read as tappable buttons when they're just labels). Iterate the
+  // union of the catalog + anything the yaml references, so a stray
+  // reference to an unknown CLI still surfaces.
+  const allClis = Array.from(new Set([...d.known, ...d.yamlReferenced, ...d.installed])).sort();
+  function statusFor(cli: string): { label: string; cls: string } {
+    const installed = d.installed.includes(cli);
+    const referenced = d.yamlReferenced.includes(cli);
+    const claimed = d.claimed.includes(cli);
+    if (claimed) return { label: 'claimed · ready to dispatch', cls: 'ok' };
+    if (installed && referenced) return { label: 'configured · restart engine to claim', cls: 'warn' };
+    if (installed) return { label: 'installed · add to crosstalk.yaml to use', cls: 'warn' };
+    if (referenced) return { label: 'in crosstalk.yaml · binary not on PATH', cls: 'warn' };
+    return { label: 'not installed', cls: 'dim' };
   }
+  const rows = allClis.length === 0
+    ? '<p class="empty">No supported agent CLIs found.</p>'
+    : allClis.map(cli => {
+        const s = statusFor(cli);
+        return `<div class="kv"><span class="key">${escapeHtml(cli)}</span><span class="val ${s.cls}">${s.label}</span></div>`;
+      }).join('');
+  const cta = d.claimed.length === 0
+    ? '<section class="card" style="border-left:3px solid #d29922"><h3 style="color:#d29922">Nothing connected yet</h3><p class="sub" style="margin-bottom:0">Run the guided setup to wire one of these up — Crosstalk writes the config and claims it live. <a href="/welcome"><strong>Set up an agent →</strong></a></p></section>'
+    : '';
   const body = `
+${cta}
 <section class="card">
-  <h3>Installed agent CLIs</h3>
-  <p class="sub">CLI binaries crosstalk knows how to PTY-wrap, detected on this engine's PATH.</p>
-  ${chips(d.installed, d.claimed, 'No supported agent CLIs found on PATH.')}
-</section>
-
-<section class="card">
-  <h3>Referenced in data/crosstalk.yaml</h3>
-  <p class="sub">CLIs that have at least one model entry in this transport's registry (whether claimed or not).</p>
-  ${chips(d.yamlReferenced, d.claimed, 'No model entries reference any known agent CLI yet.')}
-</section>
-
-<section class="card">
-  <h3>Claimed by this dispatcher</h3>
-  <p class="sub">CLIs with at least one entry whose binary was on PATH at dispatcher startup. Restart after installing a new CLI to claim its models.</p>
-  ${chips(d.claimed, d.claimed, 'No CLIs claimed yet — restart the engine after installing.')}
-</section>
-
-<section class="card">
-  <h3>Supported (catalog)</h3>
-  <p class="sub">The full set of agent CLIs crosstalk has built-in support for.</p>
-  ${chips(d.known, d.installed, '')}
+  <h3>Agent CLIs</h3>
+  <p class="sub">Every agent CLI crosstalk supports and its status on this engine. The <a href="/welcome">guided setup</a> wires one up live; to do it by hand, add a model entry under <code>providers:</code> in <code>data/crosstalk.yaml</code> and restart the engine.</p>
+  ${rows}
 </section>
 `;
   return page({