@cordfuse/crosstalk 5.0.0-alpha.7 → 6.0.0-alpha.2

package/src/replies.ts

@@ -0,0 +1,59 @@
+// crosstalk replies — have my messages been answered yet?
+//
+// Checks each given relPath for a message whose `re:` points back at it.
+// This replaces v5's read-receipt machinery: instead of recipients writing
+// "I saw it" markers into the channel, the asker just looks for actual
+// replies. Exit 0 when everything is answered, 2 while anything is pending
+// — so agents can poll cheaply in a loop.
+
+import { resolve } from 'path';
+import { gitPull, discoverChannels, listChannelMessages } from './transport.js';
+import { reList } from './activation.js';
+
+const transportRoot = resolve(process.cwd());
+const argv = process.argv.slice(2);
+
+function flag(name: string): string | undefined {
+  const i = argv.indexOf(name);
+  if (i === -1 || i === argv.length - 1) return undefined;
+  return argv[i + 1];
+}
+
+const reArg = flag('--re');
+const channelArg = flag('--channel') ?? process.env['CROSSTALK_DISPATCH_CHANNEL'];
+
+if (!reArg) {
+  console.error('Usage: crosstalk replies --re <relPath[,relPath...]> [--channel <uuid>]');
+  process.exit(1);
+}
+
+const targets = reArg.split(',').map((s) => s.trim()).filter(Boolean);
+
+gitPull(transportRoot); // best-effort freshness; a failed pull just means slightly stale answers
+
+const channels = channelArg ? [channelArg] : discoverChannels(transportRoot);
+
+// target relPath -> reply found
+const found = new Map<string, { from: string; relPath: string }>();
+for (const channel of channels) {
+  for (const msg of listChannelMessages(transportRoot, channel)) {
+    for (const entry of reList(msg.data['re'])) {
+      if (targets.includes(entry) && !found.has(entry)) {
+        found.set(entry, { from: String(msg.data['from']), relPath: msg.relPath });
+      }
+    }
+  }
+}
+
+let pending = 0;
+for (const target of targets) {
+  const reply = found.get(target);
+  if (reply) {
+    console.log(`REPLIED  ${target}  <- ${reply.from} (${reply.relPath})`);
+  } else {
+    console.log(`PENDING  ${target}`);
+    pending++;
+  }
+}
+
+process.exit(pending > 0 ? 2 : 0);

package/src/send.ts

@@ -1,9 +1,19 @@
+// crosstalk send — write a message into a channel and push it.
+//
+// `re:` is the whole activation story (CROSSTALK.md "Activation"):
+// inside a dispatched turn, CROSSTALK_DISPATCH_RE carries the relPath(s)
+// of the message(s) being answered (comma-separated for a batch), and
+// send links them all automatically. `--new` suppresses that — the
+// message becomes a fresh task and wakes its addressee unconditionally.
+// Operators (no env) always send new tasks.
+
 import { resolve, join } from 'path';
 import { mkdirSync, writeFileSync } from 'fs';
 import { now, messageFilename } from './filenames.js';
 import { serializeFrontmatter } from './frontmatter.js';
 import { gitCommitAndPush } from './transport.js';
 import { withLock } from './turnq.js';
+import { sendWakeSignal } from './state.js';
 
 const transportRoot = resolve(process.cwd());
 const argv = process.argv.slice(2);
@@ -15,93 +25,64 @@ function flag(name: string): string | undefined {
 }
 
 async function main(): Promise<void> {
-  const channelUuid = flag('--channel');
+  const channelUuid = flag('--channel') ?? process.env['CROSSTALK_DISPATCH_CHANNEL'];
   const to = flag('--to');
-  // Sender identity precedence:
-  //   1. --from on the command line (explicit operator/actor choice)
-  //   2. CROSSTALK_DISPATCH_ACTOR env var (set by dispatch.ts when it spawns
-  //      an actor's CLI — so the actor's outbound messages route as itself,
-  //      not as the operator). Fixes the alpha.5 finding where concierge's
-  //      fan-out messages went out as `from=steve` because send.ts fell
-  //      through to USER instead.
-  //   3. $USER (interactive operator default)
-  //   4. literal 'steve' as last resort
   const from = flag('--from')
     ?? process.env['CROSSTALK_DISPATCH_ACTOR']
     ?? process.env['USER']
-    ?? 'steve';
+    ?? 'operator';
   const tier = flag('--tier');
-  // Lifecycle kind. `work` (default) — recipient is being asked to act, will
-  // wake on receipt. `result` — informational reply, wakes the recipient only
-  // if it previously asked the sender for work (reply causality). See
-  // PROTOCOL.md "Message kinds". Proactive sends default to `work`; the
-  // runtime's auto-reply path defaults to `result`.
-  const kind = flag('--kind') ?? 'work';
+  const isNew = argv.includes('--new');
   const body = argv[argv.length - 1];
 
   if (!channelUuid || !to || !body || body.startsWith('--')) {
     console.error(
-      'Usage: crosstalk send --channel <uuid> --to <actor> [--from <actor>] [--tier <name>] [--kind work|result] "<message body>"',
+      'Usage: crosstalk send --to <actor[,actor...]> [--channel <uuid>] [--from <actor>] [--tier <name>] [--new] "<message body>"',
     );
     process.exit(1);
   }
 
-  if (kind !== 'work' && kind !== 'result') {
-    console.error(`Invalid --kind '${kind}'. Must be 'work' or 'result'.`);
-    process.exit(1);
-  }
+  const reTargets = (isNew ? '' : process.env['CROSSTALK_DISPATCH_RE'] ?? '')
+    .split(',')
+    .map((s) => s.trim())
+    .filter(Boolean);
 
-  await withLock('dispatch', async () => {
-    const ts = now();
-    const dir = join(transportRoot, 'data', 'channels', channelUuid, ts.pathDate);
-    mkdirSync(dir, { recursive: true });
+  const ts = now();
+  const dir = join(transportRoot, 'data', 'channels', channelUuid, ts.pathDate);
+  mkdirSync(dir, { recursive: true });
 
-    const frontmatter: Record<string, unknown> = {
-      from,
-      to,
-      type: 'text',
-      kind,
-      timestamp: ts.iso,
-    };
-    if (tier) frontmatter.tier = tier;
-    const content = serializeFrontmatter(frontmatter, body);
+  const frontmatter: Record<string, unknown> = {
+    from,
+    to: to.includes(',') ? to.split(',').map((s) => s.trim()).filter(Boolean) : to,
+    type: 'text',
+    timestamp: ts.iso,
+  };
+  if (reTargets.length === 1) frontmatter['re'] = reTargets[0];
+  else if (reTargets.length > 1) frontmatter['re'] = reTargets;
+  if (tier) frontmatter['tier'] = tier;
 
-    const filename = messageFilename(ts);
-    writeFileSync(join(dir, filename), content);
+  const filename = messageFilename(ts);
+  writeFileSync(join(dir, filename), serializeFrontmatter(frontmatter, body));
 
-    const pushResult = gitCommitAndPush(
-      transportRoot,
-      `send: ${from} -> ${to} in ${channelUuid.slice(0, 8)}`,
-    );
+  // Lock only the commit+push — the narrow critical section. If the lock
+  // can't be had, git arbitrates anyway (see turnq.ts).
+  const pushResult = await withLock(transportRoot, 'git', async () =>
+    gitCommitAndPush(transportRoot, `send: ${from} -> ${to} in ${channelUuid.slice(0, 8)}`),
+  );
 
-    // Poke dispatch to tick immediately (even if push failed — local cursor still advances).
-    try {
-      const wakeDir = join(transportRoot, '.turnq');
-      mkdirSync(wakeDir, { recursive: true });
-      writeFileSync(join(wakeDir, 'wake.signal'), `${Date.now()}\n`);
-    } catch {
-      /* wake is best-effort */
-    }
+  sendWakeSignal(transportRoot);
 
-    if (!pushResult.ok && pushResult.error) {
-      // Note: deliberately NOT writing to errors/. That directory is dispatcher-
-      // owned state, and operator-side writes from `crosstalk send` were
-      // dirtying the working tree, causing subsequent `git pull --rebase` to
-      // fail with "unstaged changes". Surface the error to stderr only.
-      const kind = pushResult.committed ? 'push' : 'commit';
-      console.error(`Wrote locally: ${join(ts.pathDate, filename)}`);
-      console.error(`but git ${kind} FAILED:`);
-      console.error(`  ${pushResult.error.slice(0, 300)}`);
-      console.error('');
-      console.error('Your message is in your local clone but not on origin.');
-      console.error('Recover with:');
-      console.error('  git pull --rebase');
-      console.error('  git push');
-      process.exit(3);
-    }
+  if (!pushResult.ok && pushResult.error) {
+    console.error(`Wrote locally: ${join(ts.pathDate, filename)}`);
+    console.error(`but git ${pushResult.committed ? 'push' : 'commit'} FAILED:`);
+    console.error(`  ${pushResult.error.slice(0, 300)}`);
+    console.error('\nYour message is in the local clone but not on origin. Recover with:');
+    console.error('  git fetch origin && git rebase origin/main && git push');
+    process.exit(3);
+  }
 
-    console.log(`Sent: ${join(ts.pathDate, filename)}`);
-  });
+  console.log(`Sent: ${join(ts.pathDate, filename)}${reTargets.length ? ` (re: ${reTargets.join(', ')})` : ''}`);
+  process.exit(0);
 }
 
 main();

package/src/state.ts

@@ -0,0 +1,173 @@
+// 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).
+//
+// Layout under the state dir:
+//   cursors/<actor>/<channel-uuid>     — last-scanned git commit hash
+//   dlq/<id>.md                        — failed-dispatch entries
+//   errors.log                         — infra failures, JSONL, append-only
+//   heartbeat                          — last tick timestamp + pid + version
+//   dispatcher.pid                     — PID of the running dispatcher process
+//   wake.signal                        — touched to wake the dispatch loop
+//
+// Location: $CROSSTALK_STATE_DIR if set (exact dir — container-friendly),
+// else ~/.local/state/crosstalk/<transport-id> where <transport-id> is a
+// hash of the git origin URL (or the repo path when there is no origin).
+
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  writeFileSync,
+  unlinkSync,
+  appendFileSync,
+} from 'fs';
+import { join, dirname } from 'path';
+import { homedir } from 'os';
+import { createHash } from 'crypto';
+import { spawnSync } from 'child_process';
+
+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) {
+    const origin = spawnSync('git', ['config', '--get', 'remote.origin.url'], {
+      cwd: transportRoot,
+      encoding: 'utf-8',
+    });
+    const identity = origin.status === 0 && origin.stdout.trim()
+      ? origin.stdout.trim()
+      : transportRoot;
+    const id = createHash('sha256').update(identity).digest('hex').slice(0, 12);
+    dir = join(homedir(), '.local', 'state', 'crosstalk', id);
+  }
+  mkdirSync(dir, { recursive: true });
+  resolved.set(transportRoot, dir);
+  return dir;
+}
+
+// ── cursors ──
+
+// A cursor is the git commit hash the channel 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: a late
+// arrival is always in a new commit. (Found by the Monte Carlo harness.)
+const VALID_CURSOR = /^[0-9a-f]{40}$/;
+
+export function cursorPath(transportRoot: string, actor: string, channelUuid: string): string {
+  return join(stateDir(transportRoot), 'cursors', actor, channelUuid);
+}
+
+export function readCursor(transportRoot: string, actor: string, channelUuid: string): string | null {
+  const p = cursorPath(transportRoot, actor, channelUuid);
+  if (!existsSync(p)) return null;
+  let raw: string;
+  try {
+    raw = readFileSync(p, 'utf-8').trim();
+  } catch (err) {
+    logError(transportRoot, 'fs', `cursor read failed for ${actor}@${channelUuid}: ${(err as Error).message}`);
+    return null;
+  }
+  if (raw.length === 0) return null;
+  if (!VALID_CURSOR.test(raw)) {
+    logError(
+      transportRoot,
+      'parse',
+      `invalid cursor for ${actor}@${channelUuid}: '${raw.slice(0, 80)}' — re-scanning channel from start`,
+    );
+    return null;
+  }
+  return raw;
+}
+
+export function writeCursor(
+  transportRoot: string,
+  actor: string,
+  channelUuid: string,
+  commit: string,
+): void {
+  const p = cursorPath(transportRoot, actor, channelUuid);
+  mkdirSync(dirname(p), { recursive: true });
+  writeFileSync(p, 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): void {
+  try {
+    const data = { ts: new Date().toISOString(), pid: process.pid, version };
+    writeFileSync(join(stateDir(transportRoot), 'heartbeat'), JSON.stringify(data) + '\n');
+  } catch { /* best-effort */ }
+}
+
+export function readHeartbeat(transportRoot: string): { ts: string; pid: number; version: 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 failures, JSONL append ──
+
+export type ErrorKind = 'git_pull' | 'git_push' | 'git_commit' | 'fs' | 'parse' | 'turnq' | 'other';
+
+export function logError(transportRoot: string, kind: ErrorKind, message: string): void {
+  try {
+    const line = JSON.stringify({ ts: new Date().toISOString(), kind, 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');
+    return raw.split('\n').filter((l) => l.trim().length > 0).length;
+  } catch {
+    return 0;
+  }
+}

package/src/status.ts

@@ -1,14 +1,16 @@
+// crosstalk status — transport + dispatcher health at a glance.
+
 import { existsSync, readFileSync, readdirSync, statSync } from 'fs';
 import { resolve, join } from 'path';
 import { findHostFile } from './actor.js';
-import { discoverChannels, countErrorEntries } from './transport.js';
-import { readCursor } from './cursor.js';
-import { parseFrontmatter } from './frontmatter.js';
-import type { DlqEntry } from './dlq.js';
+import { discoverChannels } from './transport.js';
+import { stateDir, readCursor, readHeartbeat, countErrors } from './state.js';
+import { countDlqEntries } from './dlq.js';
 
 const transportRoot = resolve(process.cwd());
 
 console.log(`Crosstalk transport: ${transportRoot}`);
+console.log(`Machine state dir:   ${stateDir(transportRoot)}`);
 console.log('');
 
 let actorNames: string[] = [];
@@ -17,8 +19,7 @@ try {
   console.log(`Host file: hosts/${host.alias}.md`);
   actorNames = Object.keys(host.actors);
   for (const a of actorNames) {
-    const tiers = Object.entries(host.actors[a]);
-    const tierDescs = tiers.map(([t, v]) => {
+    const tierDescs = Object.entries(host.actors[a]!).map(([t, v]) => {
       const count = typeof v === 'object' && v.count ? `x${v.count}` : '';
       return `${t}${count}`;
     });
@@ -30,33 +31,13 @@ try {
 
 console.log('');
 
-const lockPath = join(transportRoot, '.turnq', 'dispatch.lock');
-if (existsSync(lockPath)) {
-  try {
-    const meta = JSON.parse(readFileSync(lockPath, 'utf-8')) as { pid: number; acquired: string };
-    const ageS = Math.floor((Date.now() - new Date(meta.acquired).getTime()) / 1000);
-    console.log(`turnq lock: HELD by pid ${meta.pid} for ${ageS}s (since ${meta.acquired})`);
-  } catch {
-    console.log('turnq lock: HELD (unparseable metadata)');
-  }
-} else {
-  console.log('turnq lock: free');
-}
-
-const heartbeatPath = join(transportRoot, '.turnq', 'heartbeat');
-if (existsSync(heartbeatPath)) {
-  try {
-    const hb = JSON.parse(readFileSync(heartbeatPath, 'utf-8')) as { ts: string; pid: number; version?: string };
-    const ageS = Math.floor((Date.now() - new Date(hb.ts).getTime()) / 1000);
-    const fresh = ageS < 120;
-    const stale = ageS > 300;
-    const label = fresh ? 'LIVE' : stale ? 'STALE' : 'idle';
-    console.log(`dispatch heartbeat: ${label} (pid ${hb.pid}, last tick ${ageS}s ago${hb.version ? `, ${hb.version}` : ''})`);
-  } catch {
-    console.log('dispatch heartbeat: (unparseable)');
-  }
+const hb = readHeartbeat(transportRoot);
+if (hb) {
+  const ageS = Math.floor((Date.now() - new Date(hb.ts).getTime()) / 1000);
+  const label = ageS < 120 ? 'LIVE' : ageS > 300 ? 'STALE' : 'idle';
+  console.log(`dispatch heartbeat: ${label} (pid ${hb.pid}, last tick ${ageS}s ago, ${hb.version})`);
 } else {
-  console.log('dispatch heartbeat: never (no dispatch has run on this clone)');
+  console.log('dispatch heartbeat: never (no dispatch has run on this machine)');
 }
 
 console.log('');
@@ -69,7 +50,7 @@ for (const ch of channels) {
   const chPath = join(channelDir, 'CHANNEL.md');
   if (existsSync(chPath)) {
     const m = readFileSync(chPath, 'utf-8').match(/^name:\s*(.+)$/m);
-    if (m) name = m[1].trim();
+    if (m) name = m[1]!.trim();
   }
   let msgCount = 0;
   const walk = (d: string): void => {
@@ -81,34 +62,14 @@ for (const ch of channels) {
   };
   try { walk(channelDir); } catch { /* ignore */ }
   console.log(`  ${ch.slice(0, 8)}... — ${name} (${msgCount} msgs)`);
-
   for (const actor of actorNames) {
     const cursor = readCursor(transportRoot, actor, ch);
-    if (cursor) console.log(`    cursor[${actor}] → ${cursor}`);
+    if (cursor) console.log(`    cursor[${actor}] -> ${cursor}`);
   }
 }
 
 console.log('');
 
-const dlqDir = join(transportRoot, 'dlq');
-let dlqTotal = 0;
-let dlqQuarantined = 0;
-let dlqDispatch = 0;
-let dlqConfig = 0;
-if (existsSync(dlqDir)) {
-  for (const f of readdirSync(dlqDir).filter((x) => x.endsWith('.md'))) {
-    try {
-      const { data } = parseFrontmatter<DlqEntry>(readFileSync(join(dlqDir, f), 'utf-8'));
-      dlqTotal++;
-      if (data.quarantined) dlqQuarantined++;
-      if (data.kind === 'dispatch') dlqDispatch++;
-      if (data.kind === 'config') dlqConfig++;
-    } catch { /* skip unparseable */ }
-  }
-}
-console.log(
-  `DLQ entries: ${dlqTotal} (${dlqDispatch} dispatch, ${dlqConfig} config, ${dlqQuarantined} quarantined)`,
-);
-
-const errorCount = countErrorEntries(transportRoot);
-console.log(`Infrastructure errors logged: ${errorCount}`);
+const dlq = countDlqEntries(transportRoot);
+console.log(`DLQ entries: ${dlq.total} (${dlq.quarantined} quarantined)`);
+console.log(`Infrastructure errors logged: ${countErrors(transportRoot)}`);

package/src/stop.ts

@@ -0,0 +1,37 @@
+// crosstalk 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 stop: no dispatcher.pid found — is dispatch running?');
+  process.exit(1);
+}
+
+if (!processRunning(pid)) {
+  console.error(`crosstalk 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 stop: dispatcher (pid ${pid}) stopped`);
+    process.exit(0);
+  }
+  spawnSync('sleep', ['0.1']);
+}
+
+console.error(`crosstalk stop: pid ${pid} did not exit within 5s — try: kill -9 ${pid}`);
+process.exit(1);