@cordfuse/crosstalk 7.0.0-alpha.8 → 7.0.0-beta.1

package/src/init.ts

@@ -0,0 +1,116 @@
+// crosstalk daemon init <directory> — scaffold a new transport.
+//
+// Copies the bundled flat template (CROSSTALK-VERSION, PROTOCOL.md,
+// CROSSTALK.md, data/crosstalk.yaml, auth/README.md, local/actors/...)
+// into the target directory and renames `gitignore` → `.gitignore`.
+//
+// v7 vs v6 init differences:
+//  - No host file is generated. v7 has no host files at all; machine
+//    identity comes from the --alias flag at dispatch boot.
+//  - No first channel is auto-created. Operator runs
+//    `crosstalk channel create <name>` themselves.
+//  - Template layout is flat: no upstream/ prefix on CROSSTALK-VERSION
+//    or PROTOCOL.md.
+//
+// Template lookup order:
+//   1. <runtime_root>/template/   — bundled at publish time (production —
+//      package.json prepack copies transport/ → template/)
+//   2. <runtime_root>/transport/  — monorepo layout (local dev: working
+//      from a checked-out clone where transport/ is the canonical source)
+
+import { existsSync, mkdirSync, writeFileSync, cpSync, renameSync } from 'fs';
+import { resolve, join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+const argv = process.argv.slice(2);
+const force = argv.includes('--force');
+
+const positional = argv.filter((a) => !a.startsWith('--'));
+if (positional.length === 0) {
+  console.error('Usage: crosstalk daemon init <directory> [--force]');
+  console.error('       crosstalk daemon init .                  (scaffold into current dir)');
+  process.exit(1);
+}
+
+const targetDir = resolve(positional[0]!);
+
+if (existsSync(join(targetDir, 'CROSSTALK-VERSION')) && !force) {
+  console.error(`crosstalk daemon init: ${targetDir} already contains a transport.`);
+  console.error('Pass --force to overwrite.');
+  process.exit(1);
+}
+
+const runtimeRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const candidates = [
+  join(runtimeRoot, 'template'),
+  join(runtimeRoot, 'transport'),
+];
+const templateDir = candidates.find((c) => existsSync(join(c, 'CROSSTALK-VERSION')));
+
+if (!templateDir) {
+  console.error('crosstalk daemon init: cannot find the transport template.');
+  console.error('Looked in:');
+  for (const c of candidates) console.error(`  ${c}`);
+  console.error('The @cordfuse/crosstalk installation may be corrupted; try reinstalling.');
+  process.exit(1);
+}
+
+mkdirSync(targetDir, { recursive: true });
+// Skip the template directory's own README — that's the meta-readme
+// documenting the seed template itself, not content the operator wants
+// inside their transport. (We write a fresh operator-facing README below.)
+const templateReadme = join(templateDir, 'README.md');
+cpSync(templateDir, targetDir, {
+  recursive: true,
+  force,
+  filter: (src) => src !== templateReadme,
+});
+// npm strips .gitignore from published packages; the template ships it as
+// `gitignore` and we rename it here.
+const gitignoreSrc = join(targetDir, 'gitignore');
+const gitignoreDst = join(targetDir, '.gitignore');
+if (existsSync(gitignoreSrc)) renameSync(gitignoreSrc, gitignoreDst);
+
+const readmePath = join(targetDir, 'README.md');
+if (!existsSync(readmePath) || force) {
+  writeFileSync(
+    readmePath,
+    `# Transport
+
+A Crosstalk transport created by \`crosstalk transport init\`.
+
+- Protocol spec:        [\`CROSSTALK.md\`](./CROSSTALK.md)
+- Agent orientation:    [\`PROTOCOL.md\`](./PROTOCOL.md)
+- Operator config:      [\`data/crosstalk.yaml\`](./data/crosstalk.yaml) — providers + models
+- Auth recipes:         [\`auth/README.md\`](./auth/README.md) — per-agent env vars
+- Actor persona files:  [\`local/actors/\`](./local/actors/)
+
+## First-run setup
+
+1. Edit \`data/crosstalk.yaml\` — uncomment at least one provider + model block.
+2. Drop your auth secrets into \`auth/<provider>.env\` per \`auth/README.md\`.
+3. Then:
+
+\`\`\`sh
+crosstalk up                                                       # start the engine container
+crosstalk channel general                                          # create your first channel
+crosstalk run --type primitive --to anthropic-personal/sonnet "hi" # send your first message
+crosstalk status                                                   # check state
+\`\`\`
+
+Bare model names also work when unambiguous: \`--to sonnet\` resolves cleanly if only one provider has a \`sonnet\` model.
+`,
+  );
+}
+
+console.log('');
+console.log(`Transport initialized at ${targetDir}`);
+console.log('');
+console.log('First-run setup:');
+console.log('  1. Edit data/crosstalk.yaml — uncomment at least one provider + model.');
+console.log('  2. Drop auth secrets into auth/<provider>.env per auth/README.md.');
+console.log('  3. Then (from a host with the `crosstalk` client installed):');
+console.log(`     cd ${targetDir}`);
+console.log('     crosstalk up                                                          # start the engine container');
+console.log('     crosstalk channel general                                             # create your first channel');
+console.log('     crosstalk run --type primitive --to anthropic-personal/sonnet "hi"    # send your first message');

package/src/invoke.ts

@@ -0,0 +1,201 @@
+// invoke.ts — model invocation, persona loading, reply writing.
+//
+// Called from dispatch.ts when a message wakes a claimed model. Composes
+// the system prompt (PROTOCOL.md + optional actor persona), invokes the
+// model CLI from data/crosstalk.yaml, captures stdout, writes a reply
+// message back into the same channel (success or failed:true).
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
+import { join } from 'path';
+import { spawn } from 'child_process';
+import { now, messageFilename } from './filenames.js';
+import { serializeFrontmatter } from './frontmatter.js';
+import type { ModelEntry } from './models.js';
+import type { ChannelMessage } from './transport.js';
+
+// Parse a .env-style file: KEY=value per line, # comments ignored, blank
+// lines ignored. No shell expansion, no escaping. First `=` splits the
+// key from the value; trailing/leading whitespace trimmed on both.
+export function readEnvFile(path: string): Record<string, string> {
+  if (!existsSync(path)) return {};
+  const out: Record<string, string> = {};
+  const raw = readFileSync(path, 'utf-8');
+  for (const line of raw.split('\n')) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('#')) continue;
+    const eq = trimmed.indexOf('=');
+    if (eq < 1) continue;  // no key, or starts with `=`
+    const key = trimmed.slice(0, eq).trim();
+    const value = trimmed.slice(eq + 1).trim();
+    if (!key) continue;
+    out[key] = value;
+  }
+  return out;
+}
+
+export interface InvokeResult {
+  status: number;
+  stdout: string;
+  stderr: string;
+}
+
+// 10 minutes — orchestrator-persona workflows can take 3-5 minutes
+// of model thinking before the first tool call. v6's 5-minute timeout
+// was tight for any orchestrator pattern.
+const CLI_TIMEOUT_MS = 10 * 60_000;
+const ARGV_PROMPT_LIMIT = 64 * 1024;
+
+export function loadProtocolPrompt(transportRoot: string): string {
+  const p = join(transportRoot, 'PROTOCOL.md');
+  return existsSync(p) ? readFileSync(p, 'utf-8').trim() : '';
+}
+
+export function loadActorPersona(transportRoot: string, actorName: string | undefined): string {
+  if (!actorName) return '';
+  const p = join(transportRoot, 'local', 'actors', `${actorName}.md`);
+  if (!existsSync(p)) return '';
+  return readFileSync(p, 'utf-8').trim();
+}
+
+export function composeSystemPrompt(parts: string[]): string {
+  return parts.filter((p) => p && p.length > 0).join('\n\n---\n\n');
+}
+
+export function messageSender(msg: ChannelMessage): string {
+  return typeof msg.data['from'] === 'string' ? (msg.data['from'] as string) : 'unknown';
+}
+
+// Resolve a provider's inline `env:` block against the host process env.
+// Each value is a `${VAR}` reference (validated at parse time in models.ts).
+// Undefined host vars are dropped silently — agent CLI surfaces its own
+// auth error and the failure path captures both streams (alpha.9 F1 fix).
+// This matches env_file semantics where a missing file contributes nothing
+// rather than crashing the spawn.
+function resolveInlineEnv(
+  inlineEnv: Record<string, string> | null,
+  hostEnv: NodeJS.ProcessEnv,
+): Record<string, string> {
+  if (inlineEnv == null) return {};
+  const out: Record<string, string> = {};
+  for (const [key, ref] of Object.entries(inlineEnv)) {
+    const varName = ref.slice(2, -1);  // strip `${` and `}` — parse-time validated
+    const value = hostEnv[varName];
+    if (typeof value === 'string') out[key] = value;
+  }
+  return out;
+}
+
+// Pass the prompt as the CLI's last argv entry. Every modern agent CLI
+// (Claude --print, codex exec, gemini -p, qwen --yolo, opencode -p,
+// agy -p) reads its prompt from the trailing positional, so appending
+// works universally. Fallback to stdin when the prompt would exceed a
+// safe argv size — ARG_MAX is ~128 KB on Linux and ~256 KB on macOS.
+//
+// Env merge precedence at spawn (last-wins via spread order):
+//   1. process.env       — container baseline (PATH, IS_SANDBOX, etc.)
+//   2. provider env_file — model's provider auth from a dotenv file
+//   3. provider env      — model's provider auth from inline ${VAR} refs
+//                          (alpha.10 — overrides env_file per-key when both
+//                          set, so an operator can bulk-load from a file
+//                          and override one key inline)
+//   4. dispatchEnv       — per-spawn dispatch metadata (CROSSTALK_DISPATCH_*)
+// Dispatch wins because per-spawn truth must override per-provider config;
+// provider wins over baseline because auth varies per model.
+export function invokeModelCli(
+  model: ModelEntry,
+  systemPrompt: string,
+  userMessage: string,
+  dispatchEnv: Record<string, string>,
+): Promise<InvokeResult> {
+  return new Promise((res) => {
+    const fullPrompt = systemPrompt.length > 0
+      ? `${systemPrompt}\n\n---\n\n${userMessage}`
+      : userMessage;
+    const useStdin = Buffer.byteLength(fullPrompt, 'utf-8') > ARGV_PROMPT_LIMIT;
+    const argv = useStdin ? [...model.args] : [...model.args, fullPrompt];
+    const envFileEnv = model.envFile ? readEnvFile(model.envFile) : {};
+    const inlineProviderEnv = resolveInlineEnv(model.inlineEnv, process.env);
+    // detached: new process group, so the timeout SIGKILL takes the model's
+    // children with it — orphans writing to the transport after a timeout
+    // was an observed v5/v6 hazard.
+    const child = spawn(model.cli, argv, {
+      stdio: ['pipe', 'pipe', 'pipe'],
+      detached: true,
+      env: { ...process.env, ...envFileEnv, ...inlineProviderEnv, ...dispatchEnv },
+    });
+    let stdout = '';
+    let stderr = '';
+    let resolved = false;
+    const timeout = setTimeout(() => {
+      if (resolved) return;
+      resolved = true;
+      try {
+        if (typeof child.pid === 'number') process.kill(-child.pid, 'SIGKILL');
+        else child.kill('SIGKILL');
+      } catch {
+        try { child.kill('SIGKILL'); } catch { /* already dead */ }
+      }
+      res({ status: 124, stdout, stderr: stderr + '\n[timeout]' });
+    }, CLI_TIMEOUT_MS);
+    child.stdout.on('data', (d) => { stdout += d.toString(); });
+    child.stderr.on('data', (d) => { stderr += d.toString(); });
+    child.on('close', (code) => {
+      if (resolved) return;
+      resolved = true;
+      clearTimeout(timeout);
+      res({ status: code ?? 1, stdout, stderr });
+    });
+    child.on('error', (err) => {
+      if (resolved) return;
+      resolved = true;
+      clearTimeout(timeout);
+      res({ status: 1, stdout, stderr: stderr + '\n' + err.message });
+    });
+    child.stdin.on('error', () => { /* child closed stdin */ });
+    if (useStdin) {
+      try { child.stdin.write(fullPrompt); } catch { /* same */ }
+    }
+    try { child.stdin.end(); } catch { /* ignore */ }
+  });
+}
+
+export function formatBatchedUserMessage(msgs: ChannelMessage[]): string {
+  if (msgs.length === 1) return msgs[0]!.body;
+  const parts = [`You have ${msgs.length} new messages in this channel. Process them collectively and reply once.`];
+  for (let i = 0; i < msgs.length; i++) {
+    const m = msgs[i]!;
+    const ts = typeof m.data['timestamp'] === 'string' ? `, ts: ${m.data['timestamp']}` : '';
+    parts.push(`--- Message ${i + 1} of ${msgs.length} (from: ${messageSender(m)}, ref: ${m.relPath}${ts}) ---`);
+    parts.push(m.body);
+  }
+  return parts.join('\n\n');
+}
+
+export interface ReplyOpts {
+  transportRoot: string;
+  channelUuid: string;
+  fromModel: string;     // e.g. "sonnet@cachy"
+  to: string;            // the requester
+  re: string | string[];
+  body: string;
+  failed?: { error: string };
+}
+
+export function writeReply(opts: ReplyOpts): string {
+  const ts = now();
+  const dir = join(opts.transportRoot, 'data', 'channels', opts.channelUuid, ts.pathDate);
+  mkdirSync(dir, { recursive: true });
+  const fm: Record<string, unknown> = {
+    from: opts.fromModel,
+    to: opts.to,
+    timestamp: ts.iso,
+    re: opts.re,
+  };
+  if (opts.failed) {
+    fm['failed'] = true;
+    fm['error'] = opts.failed.error.slice(0, 2000);
+  }
+  const filename = messageFilename(ts);
+  writeFileSync(join(dir, filename), serializeFrontmatter(fm, opts.body));
+  return join(ts.pathDate, filename);
+}

package/src/log-buffer.ts

@@ -0,0 +1,67 @@
+// log-buffer.ts — in-memory ring buffer for engine log events.
+//
+// The engine's structured-JSON log lines (emitted via dispatch.ts's
+// log()) are tee'd here in addition to stdout, so the /logs web page
+// and /api/logs/stream SSE endpoint can serve a live tail without
+// reading stdout from another process.
+//
+// Design choices:
+//   - Single global singleton; the engine is one process per transport.
+//   - Bounded ring buffer (LOG_BUFFER_CAPACITY entries) so memory
+//     stays predictable on long-running engines.
+//   - Subscribers receive every new entry (push, not pull). Browser
+//     SSE handlers register here; when the connection closes, they
+//     unsubscribe.
+
+export interface LogEntry {
+  /** Monotonic id; lets clients dedupe + request "since this id." */
+  seq: number;
+  /** ISO timestamp. */
+  ts: string;
+  /** Short event name (e.g. 'dispatch', 'workflow_compile_start'). */
+  event: string;
+  /** Structured fields. Stringifies safely as JSON. */
+  fields: Record<string, unknown>;
+}
+
+const LOG_BUFFER_CAPACITY = 500;
+
+class LogBuffer {
+  private entries: LogEntry[] = [];
+  private nextSeq = 1;
+  private subscribers = new Set<(entry: LogEntry) => void>();
+
+  push(event: string, fields: Record<string, unknown>): LogEntry {
+    const entry: LogEntry = {
+      seq: this.nextSeq++,
+      ts: new Date().toISOString(),
+      event,
+      fields,
+    };
+    this.entries.push(entry);
+    if (this.entries.length > LOG_BUFFER_CAPACITY) {
+      this.entries.splice(0, this.entries.length - LOG_BUFFER_CAPACITY);
+    }
+    for (const sub of this.subscribers) {
+      try { sub(entry); } catch { /* subscriber threw; ignore */ }
+    }
+    return entry;
+  }
+
+  /** Return entries with seq > sinceSeq. Defaults to all buffered. */
+  recent(sinceSeq: number = 0): LogEntry[] {
+    if (sinceSeq <= 0) return [...this.entries];
+    return this.entries.filter((e) => e.seq > sinceSeq);
+  }
+
+  subscribe(fn: (entry: LogEntry) => void): () => void {
+    this.subscribers.add(fn);
+    return () => { this.subscribers.delete(fn); };
+  }
+
+  get currentSeq(): number {
+    return this.nextSeq - 1;
+  }
+}
+
+export const logBuffer = new LogBuffer();

package/src/models.ts

@@ -0,0 +1,283 @@
+// models.ts — model registry parsing and PATH-based self-selection.
+//
+// Reads data/crosstalk.yaml from the transport root.
+//
+//   providers:
+//     <provider-name>:
+//       env_file: <relpath>           # optional — dotenv file under transport
+//       env:                          # optional — inline ${VAR} interpolation
+//         <KEY>: ${HOST_VAR}
+//       models:
+//         <model-name>: <cli command string>
+//
+// alpha.8 introduced env_file (per-provider auth files). alpha.10 adds
+// the inline env: block — same per-provider scoping, but the provider→
+// credential mapping is visible in the yaml. Inline values MUST be
+// `${VAR}` references; raw secrets are refused at parse time so the yaml
+// stays committable. Spawn-time precedence (last-wins) in invoke.ts:
+//   process.env → env_file → env (inline) → dispatch env
+//
+// ModelEntry is keyed by qualified form `provider/model` throughout the
+// engine. resolve.ts handles bare-name auto-disambiguation at the call
+// boundary; this module produces the canonical qualified-keyed registry
+// plus a bareName → matches index that resolve.ts consumes.
+
+import { existsSync, readFileSync, statSync } from 'fs';
+import { join, delimiter, isAbsolute, resolve as pathResolve } from 'path';
+import { parse as parseYaml } from 'yaml';
+
+export interface ModelEntry {
+  qualified: string;       // "google-personal/gemini-direct"
+  provider: string;        // "google-personal"
+  name: string;            // "gemini-direct"
+  envFile: string | null;  // absolute path to provider's .env, or null
+  inlineEnv: Record<string, string> | null;  // { KEY: "${HOST_VAR}" }, or null
+  command: string;         // raw command-template string
+  cli: string;             // first token — binary the dispatcher checks PATH for
+  args: string[];          // remaining tokens (the body is appended at invocation time)
+}
+
+export interface ModelsRegistry {
+  all:        Map<string, ModelEntry>;       // keyed by qualified
+  byBareName: Map<string, ModelEntry[]>;     // bare model name → all matches (for resolver)
+  claimed:    Map<string, ModelEntry>;       // qualified-keyed subset this dispatcher claims
+}
+
+export function crosstalkYamlPath(transportRoot: string): string {
+  return join(transportRoot, 'data', 'crosstalk.yaml');
+}
+
+interface RawProvider {
+  env_file?: unknown;
+  env?: unknown;
+  models?: unknown;
+}
+
+function resolveEnvFilePath(transportRoot: string, envFile: string): string {
+  // Tolerate any path the operator writes (per V8-AUTH-DESIGN.md decision).
+  // Absolute path: trust as-is. Relative: resolve against transport root.
+  if (isAbsolute(envFile)) return envFile;
+  return pathResolve(transportRoot, envFile);
+}
+
+// Inline env values must be `${VAR}` references — no raw secrets in the
+// yaml. The regex matches a single VAR-form interpolation occupying the
+// whole value. Mixed strings ("Bearer ${TOKEN}") are intentionally
+// rejected for v7 simplicity; if the use case shows up, alpha.11+ can
+// relax to full template-style interpolation.
+const INLINE_ENV_REF_RE = /^\$\{([A-Z_][A-Z0-9_]*)\}$/;
+
+function parseInlineEnv(
+  providerName: string,
+  raw: unknown,
+): Record<string, string> | null {
+  if (raw == null) return null;
+  // F-LOG (alpha.14): inner throw messages no longer carry the
+  // `crosstalk:` prefix — the outer skip-provider log wrapper at the
+  // readModels() catch site is the single prefix-bearer. Mac caught
+  // the doubled prefix during the alpha.13 beta-readiness sweep.
+  if (typeof raw !== 'object' || Array.isArray(raw)) {
+    throw new Error(
+      `provider '${providerName}' 'env:' must be a mapping ` +
+      `(got ${Array.isArray(raw) ? 'array' : typeof raw})`,
+    );
+  }
+  const out: Record<string, string> = {};
+  for (const [key, value] of Object.entries(raw as Record<string, unknown>)) {
+    if (typeof value !== 'string') {
+      throw new Error(
+        `provider '${providerName}' env.${key} must be a string ` +
+        `(got ${typeof value})`,
+      );
+    }
+    if (!INLINE_ENV_REF_RE.test(value)) {
+      throw new Error(
+        `provider '${providerName}' env.${key} = '${value}' is not a ` +
+        `\${VAR} reference. Inline env values must be of the form \${HOST_VAR} ` +
+        `so the yaml stays committable. Use env_file: <path> if you need raw values.`,
+      );
+    }
+    out[key] = value;
+  }
+  return Object.keys(out).length > 0 ? out : null;
+}
+
+export function readModels(transportRoot: string): {
+  all: Map<string, ModelEntry>;
+  byBareName: Map<string, ModelEntry[]>;
+} {
+  const path = crosstalkYamlPath(transportRoot);
+  if (!existsSync(path)) {
+    throw new Error(
+      `crosstalk: data/crosstalk.yaml not found at ${path}. ` +
+      `Run from a transport root, or regenerate via 'crosstalk transport init'.`,
+    );
+  }
+  const raw = readFileSync(path, 'utf8');
+  const parsed = parseYaml(raw);
+  if (parsed == null || typeof parsed !== 'object') {
+    throw new Error(`crosstalk: data/crosstalk.yaml parsed to non-object (got ${typeof parsed})`);
+  }
+  const root = parsed as Record<string, unknown>;
+  const providers = root['providers'];
+  if (providers === undefined) {
+    throw new Error(
+      `crosstalk: data/crosstalk.yaml missing top-level 'providers:' key. ` +
+      `Schema is providers.<name>.{env_file?, models}. ` +
+      `See transport/auth/README.md for the expected shape.`,
+    );
+  }
+
+  const all = new Map<string, ModelEntry>();
+  const byBareName = new Map<string, ModelEntry[]>();
+
+  // Empty providers: (operator hasn't uncommented any yet). Valid — engine
+  // boots with no claimed models; operators see this in `crosstalk status`.
+  if (providers === null) return { all, byBareName };
+
+  if (typeof providers !== 'object' || Array.isArray(providers)) {
+    throw new Error(
+      `crosstalk: data/crosstalk.yaml 'providers:' must be a mapping (got ${typeof providers})`,
+    );
+  }
+
+  // N3 (alpha.11): per-provider try/catch so one typo doesn't tank the
+  // whole registry. Bad providers are warned to stderr and skipped; the
+  // rest of the registry loads. Operators still see the diagnostic via
+  // `crosstalk logs` (stderr → docker logs) and the dispatcher continues
+  // serving the agents that ARE valid. Before alpha.11, one
+  // raw-value-instead-of-${VAR} mistake on a single provider produced
+  // total_models:0 — every agent went dark.
+  const errors: string[] = [];
+  for (const [providerName, providerRaw] of Object.entries(providers as Record<string, unknown>)) {
+    try {
+      parseProvider(transportRoot, providerName, providerRaw, all, byBareName);
+    } catch (err) {
+      const msg = (err as Error).message;
+      errors.push(msg);
+      console.error(`crosstalk: skipping provider '${providerName}': ${msg}`);
+    }
+  }
+
+  return { all, byBareName };
+}
+
+function parseProvider(
+  transportRoot: string,
+  providerName: string,
+  providerRaw: unknown,
+  all: Map<string, ModelEntry>,
+  byBareName: Map<string, ModelEntry[]>,
+): void {
+  if (providerRaw == null || typeof providerRaw !== 'object') {
+    throw new Error(
+      `data/crosstalk.yaml provider '${providerName}' is not a mapping`,
+    );
+  }
+  const p = providerRaw as RawProvider;
+  const envFile = (typeof p.env_file === 'string' && p.env_file.trim())
+    ? resolveEnvFilePath(transportRoot, p.env_file.trim())
+    : null;
+  const inlineEnv = parseInlineEnv(providerName, p.env);
+  const models = p.models;
+  if (models == null || typeof models !== 'object') {
+    throw new Error(`provider '${providerName}' has no 'models:' map`);
+  }
+  for (const [modelName, cmdRaw] of Object.entries(models as Record<string, unknown>)) {
+    if (typeof cmdRaw !== 'string') {
+      throw new Error(
+        `provider '${providerName}' model '${modelName}' has non-string value ` +
+        `(expected a command-template string, got ${typeof cmdRaw})`,
+      );
+    }
+    const command = cmdRaw.trim();
+    const tokens = command.split(/\s+/);
+    if (tokens.length === 0 || tokens[0] === '') {
+      throw new Error(
+        `provider '${providerName}' model '${modelName}' has empty command`,
+      );
+    }
+    const qualified = `${providerName}/${modelName}`;
+    if (all.has(qualified)) {
+      throw new Error(
+        `duplicate model '${qualified}' in data/crosstalk.yaml`,
+      );
+    }
+    const entry: ModelEntry = {
+      qualified,
+      provider: providerName,
+      name: modelName,
+      envFile,
+      inlineEnv,
+      command,
+      cli: tokens[0]!,
+      args: tokens.slice(1),
+    };
+    all.set(qualified, entry);
+    const existing = byBareName.get(modelName) ?? [];
+    existing.push(entry);
+    byBareName.set(modelName, existing);
+  }
+}
+
+// Resolve a model's `cli` token to an absolute, executable file path — or
+// null if it can't be resolved. Absolute paths are stat'd directly so
+// operators can point `cli:` at a wrapper anywhere under the persistent
+// /crosstalk-root mount; relative tokens are looked up across $PATH
+// (which already includes /crosstalk-root/.local/bin, the documented
+// drop-in dir for operator-installed CLIs and wrappers).
+export function resolveCli(binary: string, env: NodeJS.ProcessEnv = process.env): string | null {
+  if (isAbsolute(binary)) {
+    try {
+      if (existsSync(binary) && statSync(binary).isFile()) return binary;
+    } catch {
+      // unreadable, fall through
+    }
+    return null;
+  }
+  const pathVar = env.PATH ?? '';
+  for (const dir of pathVar.split(delimiter)) {
+    if (!dir) continue;
+    const candidate = join(dir, binary);
+    try {
+      if (existsSync(candidate) && statSync(candidate).isFile()) return candidate;
+    } catch {
+      // unreadable entry, skip
+    }
+  }
+  return null;
+}
+
+export function isOnPath(binary: string, env: NodeJS.ProcessEnv = process.env): boolean {
+  return resolveCli(binary, env) !== null;
+}
+
+// Walk every parsed model and decide which the local dispatcher can serve.
+// Unclaimed models are logged to stderr with the specific reason —
+// alpha.11 fixed the silent-drop for bad-provider parse errors; alpha.12
+// extends the same diagnostic to the claim step so an operator with a
+// wrapper at the wrong path (or a typo in the binary name) gets a clear
+// line in `crosstalk logs` instead of a silently-missing model.
+export function claimModels(
+  all: Map<string, ModelEntry>,
+  env: NodeJS.ProcessEnv = process.env,
+): Map<string, ModelEntry> {
+  const claimed = new Map<string, ModelEntry>();
+  for (const [qualified, entry] of all) {
+    if (isOnPath(entry.cli, env)) {
+      claimed.set(qualified, entry);
+    } else {
+      const reason = isAbsolute(entry.cli)
+        ? `absolute path '${entry.cli}' is not an existing file`
+        : `binary '${entry.cli}' not found on PATH (${env.PATH ?? ''})`;
+      console.error(`crosstalk: skipping model '${qualified}': ${reason}`);
+    }
+  }
+  return claimed;
+}
+
+export function loadRegistry(transportRoot: string): ModelsRegistry {
+  const { all, byBareName } = readModels(transportRoot);
+  const claimed = claimModels(all);
+  return { all, byBareName, claimed };
+}