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

package/src/resolve.ts

@@ -0,0 +1,100 @@
+// resolve.ts — model reference resolution.
+//
+// Operator-facing references can be either:
+//   - qualified:  "google-personal/gemini-direct" (provider/model form)
+//   - bare:       "gemini-direct" (model name only)
+//
+// Qualified references are looked up against the FULL parsed registry
+// — including models declared in data/crosstalk.yaml but NOT locally
+// claimed by this dispatcher. This is the cross-machine routing surface:
+// the sender's API resolves the reference to its canonical qualified
+// form and writes a commit; whichever peer dispatcher claims the model
+// picks it up at its next tick (per PROTOCOL.md addressing rules).
+// Restricting qualified lookups to `claimed` blocked cross-machine
+// asymmetric dispatch — F-CROSS, caught in the alpha.14 capstone gate.
+//
+// Bare references still resolve via auto-disambiguation against the
+// CLAIMED registry. Cross-machine bare-name dispatch is intentionally
+// out of scope for v7.0 — the byBareName index can't pick a global
+// unique across providers, and the disambiguation pick-list UX is
+// rooted in "what's actually claimed here". Operators wanting cross-
+// machine routing should use the qualified form (or `bare@machine`,
+// which currently still requires the bare name to resolve locally; an
+// alpha.15+ enhancement could lift that).
+//
+//   - qualified, in registry      → ok
+//   - qualified, not in registry  → unknown
+//   - bare, 1 claimed match       → ok
+//   - bare, 2+ claimed matches    → ambiguous (pick-list)
+//   - bare, 0 claimed matches     → unknown
+//
+// Same rule applies in every place a model is referenced: --to flag,
+// frontmatter `to:` field, workflow PLAN.json targets, activation
+// matching. resolve.ts is the single source of truth so the semantics
+// are uniform.
+
+import type { ModelEntry, ModelsRegistry } from './models.js';
+
+export type ResolutionResult =
+  | { kind: 'ok'; model: ModelEntry }
+  | { kind: 'unknown'; ref: string }
+  | { kind: 'ambiguous'; ref: string; candidates: string[] };
+
+export function resolveModelRef(ref: string, registry: ModelsRegistry): ResolutionResult {
+  const trimmed = ref.trim();
+  if (trimmed === '') return { kind: 'unknown', ref };
+  if (trimmed.includes('/')) {
+    // F-CROSS (alpha.15): look in the full registry, not just claimed.
+    // Sender's API resolves cross-machine references too; the per-tick
+    // claim check on each peer dispatcher is the correct enforcement
+    // point for "who actually handles this".
+    const m = registry.all.get(trimmed);
+    return m ? { kind: 'ok', model: m } : { kind: 'unknown', ref: trimmed };
+  }
+  // Bare name: scan byBareName, filter to claimed entries.
+  const matches = (registry.byBareName.get(trimmed) ?? [])
+    .filter((m) => registry.claimed.has(m.qualified));
+  if (matches.length === 1) return { kind: 'ok', model: matches[0]! };
+  if (matches.length === 0) return { kind: 'unknown', ref: trimmed };
+  return {
+    kind: 'ambiguous',
+    ref: trimmed,
+    candidates: matches.map((m) => m.qualified).sort(),
+  };
+}
+
+export function formatResolutionError(r: Exclude<ResolutionResult, { kind: 'ok' }>): string {
+  if (r.kind === 'unknown') {
+    return `unknown model '${r.ref}'`;
+  }
+  return (
+    `'${r.ref}' is ambiguous (${r.candidates.length} matches). Specify one:\n  ` +
+    r.candidates.join('\n  ')
+  );
+}
+
+// Resolve a `to:` field value that may carry an `@host` suffix. The host
+// suffix is split off, the actor part resolved, then re-attached. This
+// lets workflow scoping (`model@cachy`) work uniformly with bare or
+// qualified model references.
+export interface ToResolution {
+  kind: 'ok' | 'unknown' | 'ambiguous' | 'reserved';
+  qualified?: string;   // for 'ok' or 'reserved' — full `<provider>/<model>[@host]`
+  error?: string;       // for 'unknown' | 'ambiguous'
+}
+
+// Reserved recipient names that are not models — workflow markers, etc.
+// These pass through unchanged.
+const RESERVED_RECIPIENTS = new Set(['workflow', 'all']);
+
+export function resolveToField(toRaw: string, registry: ModelsRegistry): ToResolution {
+  const at = toRaw.indexOf('@');
+  const actorPart = at === -1 ? toRaw : toRaw.slice(0, at);
+  const hostSuffix = at === -1 ? '' : toRaw.slice(at);
+  if (RESERVED_RECIPIENTS.has(actorPart)) {
+    return { kind: 'reserved', qualified: toRaw };
+  }
+  const r = resolveModelRef(actorPart, registry);
+  if (r.kind === 'ok') return { kind: 'ok', qualified: r.model.qualified + hostSuffix };
+  return { kind: r.kind, error: formatResolutionError(r) };
+}

package/src/state.ts

@@ -0,0 +1,190 @@
+// Machine-local dispatcher state. NONE of this lives in the transport repo —
+// the repo carries conversation; each machine carries its own progress
+// through it. That separation is what makes the dispatcher's git operations
+// conflict-free: its commits only ever contain data/ (messages).
+//
+// v7 layout under the state dir (four files, no subdirectories):
+//   dispatcher.pid    — PID of the running dispatcher process
+//   cursor            — last-scanned git commit hash (single global cursor)
+//   heartbeat         — last tick timestamp + pid + version (JSON)
+//   wake.signal       — touched to wake the dispatch loop
+//   errors.log        — infra failures, JSONL, append-only (best-effort)
+//
+// Location: $CROSSTALK_STATE_DIR if set (exact dir — container-friendly),
+// else ~/.config/crosstalk/state/<basename(transportRoot)>/. v6 used a
+// hashed-origin-URL dir under ~/.local/state; v7 uses the working tree's
+// directory name for operator readability. Operators with two clones of
+// the same transport get two state dirs — acceptable; different working
+// trees may have genuinely different progress through the conversation.
+
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  writeFileSync,
+  unlinkSync,
+  appendFileSync,
+} from 'fs';
+import { join, basename } from 'path';
+import { homedir } from 'os';
+
+const resolved = new Map<string, string>();
+
+export function stateDir(transportRoot: string): string {
+  const cached = resolved.get(transportRoot);
+  if (cached) return cached;
+  let dir = process.env['CROSSTALK_STATE_DIR'];
+  if (!dir) {
+    dir = join(homedir(), '.config', 'crosstalk', 'state', basename(transportRoot));
+  }
+  mkdirSync(dir, { recursive: true });
+  resolved.set(transportRoot, dir);
+  return dir;
+}
+
+// ── 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.
+//
+// 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');
+}
+
+export function readCursor(transportRoot: string): string | null {
+  const p = cursorPath(transportRoot);
+  if (!existsSync(p)) return null;
+  let raw: string;
+  try {
+    raw = readFileSync(p, 'utf-8').trim();
+  } catch (err) {
+    logError(transportRoot, `cursor read failed: ${(err as Error).message}`);
+    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');
+}
+
+// ── pidfile ──
+
+export function pidfilePath(transportRoot: string): string {
+  return join(stateDir(transportRoot), 'dispatcher.pid');
+}
+
+export function writePidfile(transportRoot: string): void {
+  try {
+    writeFileSync(pidfilePath(transportRoot), `${process.pid}\n`);
+  } catch { /* best-effort */ }
+}
+
+export function removePidfile(transportRoot: string): void {
+  try {
+    unlinkSync(pidfilePath(transportRoot));
+  } catch { /* already gone */ }
+}
+
+export function readPidfile(transportRoot: string): number | null {
+  try {
+    const raw = readFileSync(pidfilePath(transportRoot), 'utf-8').trim();
+    const n = parseInt(raw, 10);
+    return Number.isFinite(n) && n > 0 ? n : null;
+  } catch {
+    return null;
+  }
+}
+
+// ── heartbeat + wake ──
+
+export function writeHeartbeat(transportRoot: string, version: string, alias?: string): void {
+  try {
+    const data: Record<string, unknown> = { ts: new Date().toISOString(), pid: process.pid, version };
+    if (alias) data['alias'] = alias;
+    writeFileSync(join(stateDir(transportRoot), 'heartbeat'), JSON.stringify(data) + '\n');
+  } catch { /* best-effort */ }
+}
+
+export function readHeartbeat(
+  transportRoot: string,
+): { ts: string; pid: number; version: string; alias?: string } | null {
+  try {
+    return JSON.parse(readFileSync(join(stateDir(transportRoot), 'heartbeat'), 'utf-8'));
+  } catch {
+    return null;
+  }
+}
+
+export function wakeSignalPath(transportRoot: string): string {
+  return join(stateDir(transportRoot), 'wake.signal');
+}
+
+export function sendWakeSignal(transportRoot: string): void {
+  try {
+    writeFileSync(wakeSignalPath(transportRoot), `${Date.now()}\n`);
+  } catch { /* best-effort */ }
+}
+
+// ── error log — infra events, JSONL append, best-effort ──
+//
+// Two levels:
+//   error  — real failures the operator needs to investigate
+//            (corrupted state, unrecoverable runtime errors)
+//   warn   — degraded-but-functional conditions
+//            (git push failed because remote unreachable; cursor
+//            unknown but we recovered by re-scanning; etc.)
+//
+// Dashboard counts only level=error. Legacy entries (pre-2026-06-22)
+// have no level field — they're treated as 'error' for backcompat
+// since they were written by call sites that hadn't been classified
+// yet. Once those are reclassified, old entries fade out of the
+// rolling window.
+
+export type LogErrorLevel = 'error' | 'warn';
+
+export function logError(
+  transportRoot: string,
+  message: string,
+  level: LogErrorLevel = 'error',
+): void {
+  try {
+    const line = JSON.stringify({ ts: new Date().toISOString(), level, message: message.slice(0, 500) });
+    appendFileSync(join(stateDir(transportRoot), 'errors.log'), line + '\n');
+  } catch { /* best-effort */ }
+}
+
+export function countErrors(transportRoot: string): number {
+  try {
+    const raw = readFileSync(join(stateDir(transportRoot), 'errors.log'), 'utf-8');
+    let n = 0;
+    for (const line of raw.split('\n')) {
+      const t = line.trim();
+      if (t.length === 0) continue;
+      try {
+        const parsed = JSON.parse(t) as { level?: string };
+        // Legacy entries (no level field) count as errors.
+        if (parsed.level === undefined || parsed.level === 'error') n++;
+      } catch {
+        n++; // malformed JSON — count as error so it doesn't go silent
+      }
+    }
+    return n;
+  } catch {
+    return 0;
+  }
+}

package/src/stop.ts

@@ -0,0 +1,37 @@
+// crosstalk daemon stop — send SIGTERM to the running dispatcher and wait for it to exit.
+
+import { resolve } from 'path';
+import { spawnSync } from 'child_process';
+import { readPidfile, removePidfile } from './state.js';
+
+const transportRoot = resolve(process.cwd());
+
+function processRunning(pid: number): boolean {
+  try { process.kill(pid, 0); return true; } catch { return false; }
+}
+
+const pid = readPidfile(transportRoot);
+if (pid === null) {
+  console.error('crosstalk daemon stop: no dispatcher.pid found — is dispatch running?');
+  process.exit(1);
+}
+
+if (!processRunning(pid)) {
+  console.error(`crosstalk daemon stop: pid ${pid} is not running — removing stale pidfile`);
+  removePidfile(transportRoot);
+  process.exit(1);
+}
+
+process.kill(pid, 'SIGTERM');
+
+const deadline = Date.now() + 5_000;
+while (Date.now() < deadline) {
+  if (!processRunning(pid)) {
+    console.log(`crosstalk daemon stop: dispatcher (pid ${pid}) stopped`);
+    process.exit(0);
+  }
+  spawnSync('sleep', ['0.1']);
+}
+
+console.error(`crosstalk daemon stop: pid ${pid} did not exit within 5s — try: kill -9 ${pid}`);
+process.exit(1);

package/src/transport.ts

@@ -0,0 +1,243 @@
+// Git transport layer. The 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.
+
+import { existsSync, readdirSync, readFileSync, statSync } from 'fs';
+import { join } from 'path';
+import { spawnSync } from 'child_process';
+import { parseFrontmatter } from './frontmatter.js';
+import { logError } from './state.js';
+
+export interface ChannelMessage {
+  relPath: string;
+  fullPath: string;
+  data: Record<string, unknown>;
+  body: string;
+}
+
+export interface GitResult {
+  ok: boolean;
+  error?: string;
+}
+
+export interface GitPushResult {
+  ok: boolean;
+  committed: boolean;
+  pushed: boolean;
+  error?: string;
+}
+
+function captureGit(cwd: string, args: string[]): { status: number; stdout: string; stderr: string } {
+  const r = spawnSync('git', args, { cwd, encoding: 'utf-8' });
+  return { status: r.status ?? 1, stdout: r.stdout ?? '', stderr: r.stderr ?? '' };
+}
+
+// Detect and abort an interrupted rebase/merge left by a killed process.
+// Returns true if recovery was performed.
+export function recoverInterruptedGit(transportRoot: string): boolean {
+  const halfStates: { dir: string; abortArgs: string[] }[] = [
+    { dir: '.git/rebase-merge', abortArgs: ['rebase', '--abort'] },
+    { dir: '.git/rebase-apply', abortArgs: ['rebase', '--abort'] },
+    { dir: '.git/MERGE_HEAD', abortArgs: ['merge', '--abort'] },
+    { dir: '.git/CHERRY_PICK_HEAD', abortArgs: ['cherry-pick', '--abort'] },
+  ];
+  for (const { dir, abortArgs } of halfStates) {
+    if (existsSync(join(transportRoot, dir))) {
+      const r = captureGit(transportRoot, abortArgs);
+      logError(
+        transportRoot,
+        `recovered from interrupted git state at ${dir} via 'git ${abortArgs.join(' ')}' (exit=${r.status})`,
+      );
+      return true;
+    }
+  }
+  return false;
+}
+
+// The commit cursors anchor to. Use local HEAD: gitPull (called first
+// in dispatchTick) already rebased origin commits into HEAD, so HEAD
+// includes both remote and local-unpushed work. Using origin/HEAD
+// would have stranded the dispatcher whenever push broke (commits
+// pile up on HEAD past stale origin/HEAD; cursor never advances past
+// origin/HEAD; activation pass thinks nothing's new). Caught
+// 2026-06-22 — push failed silently due to missing ssh key, workflows
+// got stuck in FANOUT forever.
+//
+// origin/* fallback only kicks in when local HEAD doesn't resolve
+// (truly empty repo, no branch checked out — defensive only).
+export function cursorBaseline(transportRoot: string): string | null {
+  for (const ref of ['HEAD', 'origin/HEAD', 'origin/main']) {
+    const r = captureGit(transportRoot, ['rev-parse', ref]);
+    if (r.status === 0) return r.stdout.trim();
+  }
+  return null;
+}
+
+// Repo-relative paths of message files added between `sinceCommit` and
+// 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 {
+  const r = captureGit(transportRoot, [
+    'diff', '--name-only', '--diff-filter=A', `${sinceCommit}..HEAD`, '--', 'data/channels/',
+  ]);
+  if (r.status !== 0) return null;
+  return r.stdout.split('\n').filter(Boolean);
+}
+
+export function gitPull(transportRoot: string): GitResult {
+  recoverInterruptedGit(transportRoot);
+  const fetch = captureGit(transportRoot, ['fetch', 'origin', '--quiet']);
+  if (fetch.status !== 0) {
+    // No origin remote configured → not an error. Single-machine and
+    // local-only transports are valid; the dispatcher just operates on
+    // local commits.
+    const stderr = fetch.stderr.trim();
+    if (stderr.includes("does not appear to be a git repository") ||
+        stderr.includes("Could not read from remote") ||
+        stderr.includes("origin") && stderr.includes("does not appear")) {
+      return { ok: true };
+    }
+    return { ok: false, error: (fetch.stderr || fetch.stdout).trim().slice(0, 500) };
+  }
+  const rebase = captureGit(transportRoot, ['rebase', 'origin/main']);
+  if (rebase.status !== 0) {
+    // No origin/main (single-machine, no remote) → not an error.
+    if (rebase.stderr.includes('unknown revision') || rebase.stderr.includes('not a valid object name')) {
+      return { ok: true };
+    }
+    return { ok: false, error: (rebase.stderr || rebase.stdout).trim().slice(0, 500) };
+  }
+  return { ok: true };
+}
+
+// Stage data/ only, commit, push. On push rejection, one pull --rebase +
+// re-push — collision-free filenames make the rebase trivially clean.
+// In single-machine transports with no remote, the push step is a no-op
+// (gracefully — git push fails fast on "No configured push destination",
+// which we treat as success since the commit is already local).
+export function gitCommitAndPush(transportRoot: string, message: string): GitPushResult {
+  const status = captureGit(transportRoot, ['status', '--porcelain', '--', 'data/']);
+  if (status.status !== 0) {
+    return { ok: false, committed: false, pushed: false, error: status.stderr.trim().slice(0, 500) };
+  }
+  if (!status.stdout.trim()) {
+    return { ok: true, committed: false, pushed: false };
+  }
+
+  const add = captureGit(transportRoot, ['add', '--', 'data/']);
+  if (add.status !== 0) {
+    return { ok: false, committed: false, pushed: false, error: add.stderr.trim().slice(0, 500) };
+  }
+
+  const commit = captureGit(transportRoot, ['commit', '-m', message, '--', 'data/']);
+  if (commit.status !== 0) {
+    const noop = commit.stdout.includes('nothing to commit') ||
+                 commit.stderr.includes('nothing to commit');
+    if (noop) return { ok: true, committed: false, pushed: false };
+    return { ok: false, committed: false, pushed: false, error: commit.stderr.trim().slice(0, 500) };
+  }
+
+  // Push rejection is NORMAL under concurrent writers — git is the
+  // arbiter and collision-free filenames make every rebase clean. Retry
+  // with jitter; many writers racing one origin converge within a few
+  // rounds. v6 used turnq as an advisory lock to reduce churn; v7 dropped
+  // it — rebase-retry is the correctness mechanism, turnq was overhead.
+  let push = captureGit(transportRoot, ['push', '--quiet']);
+  if (push.status !== 0) {
+    // No remote configured → push fails with "No configured push destination".
+    // Treat as success: commits stay local, which is the intended state
+    // for single-machine transports.
+    if (push.stderr.includes('No configured push destination') ||
+        push.stderr.includes("does not appear to be a git repository")) {
+      return { ok: true, committed: true, pushed: false };
+    }
+  }
+  for (let attempt = 0; push.status !== 0 && attempt < 5; attempt++) {
+    spawnSync('sleep', [(0.05 + Math.random() * 0.3 * (attempt + 1)).toFixed(2)]);
+    const pull = gitPull(transportRoot);
+    if (!pull.ok) continue;
+    push = captureGit(transportRoot, ['push', '--quiet']);
+  }
+  if (push.status !== 0) {
+    return {
+      ok: false,
+      committed: true,
+      pushed: false,
+      error: (push.stderr || push.stdout).trim().slice(0, 500),
+    };
+  }
+  return { ok: true, committed: true, pushed: true };
+}
+
+export function discoverChannels(transportRoot: string): string[] {
+  const channelsDir = join(transportRoot, 'data', 'channels');
+  if (!existsSync(channelsDir)) return [];
+  let entries: string[];
+  try {
+    entries = readdirSync(channelsDir);
+  } catch (err) {
+    logError(transportRoot, `discoverChannels readdir failed on ${channelsDir}: ${(err as Error).message}`);
+    return [];
+  }
+  return entries.filter((name) => {
+    try {
+      return statSync(join(channelsDir, name)).isDirectory();
+    } catch {
+      return false;
+    }
+  });
+}
+
+// v7 frontmatter contract (see transport/CROSSTALK.md §Messages):
+//   required: from (string), to (string), timestamp (string)
+//   optional: re, as, type ('workflow' only), failed, error, child_channel
+// v6 required `type: text` on every message; v7 omits `type:` on regular
+// messages. Readers must ignore UNKNOWN fields, but known fields with
+// invalid values are protocol violations and rejected at parse time.
+// This catches LLM models that revert to v6 muscle memory (writing
+// `type: text` in hand-crafted frontmatter) — a real failure mode
+// surfaced by the S10 fan-out workflow test.
+function isValidMessageFrontmatter(data: Record<string, unknown>): boolean {
+  if (typeof data['from'] !== 'string') return false;
+  if (typeof data['to'] !== 'string' && !Array.isArray(data['to'])) return false;
+  if (typeof data['timestamp'] !== 'string') return false;
+  // `type:` is optional; only 'workflow' is valid in v7. Reject v6's
+  // `type: text` and any other invalid value.
+  if (data['type'] !== undefined && data['type'] !== 'workflow') return false;
+  return true;
+}
+
+export function listChannelMessages(transportRoot: string, channelUuid: string): ChannelMessage[] {
+  const channelDir = join(transportRoot, 'data', 'channels', channelUuid);
+  if (!existsSync(channelDir)) return [];
+  const results: ChannelMessage[] = [];
+  const walk = (dir: string, prefix: string): void => {
+    for (const entry of readdirSync(dir)) {
+      const full = join(dir, entry);
+      const rel = prefix ? `${prefix}/${entry}` : entry;
+      let stat;
+      try { stat = statSync(full); } catch { continue; }
+      if (stat.isDirectory()) {
+        walk(full, rel);
+      } else if (entry.endsWith('.md') && entry !== 'CHANNEL.md') {
+        const raw = readFileSync(full, 'utf-8');
+        let parsed;
+        try {
+          parsed = parseFrontmatter(raw);
+        } catch (err) {
+          logError(transportRoot, `frontmatter parse failed in ${channelUuid}/${rel}: ${(err as Error).message}`, 'warn');
+          continue;
+        }
+        if (!isValidMessageFrontmatter(parsed.data)) {
+          logError(transportRoot, `invalid message frontmatter in ${channelUuid}/${rel}: missing required field(s) (from, to, timestamp)`, 'warn');
+          continue;
+        }
+        results.push({ relPath: rel, fullPath: full, data: parsed.data, body: parsed.body });
+      }
+    }
+  };
+  walk(channelDir, '');
+  return results.sort((a, b) => a.relPath.localeCompare(b.relPath));
+}