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

package/src/dispatch.ts

@@ -1,30 +1,19 @@
+// crosstalk dispatch — the loop.
+//
+// Tick: pull → for each local actor, scan channels for messages past the
+// cursor → decideWake (activation.ts, the one rule) → invoke the actor's
+// CLI per batch → write replies (re: linked per sender) → commit+push.
+//
+// Only the commit+push is locked, and the lock is advisory (turnq.ts) —
+// git arbitrates correctness. Cursors, DLQ, heartbeat and the error log
+// live in the machine-local state dir (state.ts), so a tick's commit only
+// ever contains data/ and there is no self-inflicted git deadlock to heal.
+
 import { resolve, join, dirname } from 'path';
 import { spawn } from 'child_process';
-import {
-  mkdirSync,
-  writeFileSync,
-  readFileSync,
-  existsSync,
-  appendFileSync,
-  openSync,
-  closeSync,
-} from 'fs';
+import { mkdirSync, writeFileSync, readFileSync, existsSync, appendFileSync } from 'fs';
 import { watch } from 'fs/promises';
 import { fileURLToPath } from 'url';
-
-// Read runtime version from the installed package's package.json at startup
-// so dispatch_start logs and heartbeat content always match the actual
-// installed @cordfuse/crosstalk version. Avoids hand-editing on every release.
-const RUNTIME_VERSION: string = (() => {
-  try {
-    const thisFileDir = dirname(fileURLToPath(import.meta.url));
-    const pkgPath = join(thisFileDir, '..', 'package.json');
-    const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8')) as { version?: string };
-    return pkg.version ?? 'unknown';
-  } catch {
-    return 'unknown';
-  }
-})();
 import {
   findHostFile,
   loadActorProfile,
@@ -38,15 +27,34 @@ import {
   listChannelMessages,
   gitPull,
   gitCommitAndPush,
-  writeErrorLog,
-  sweepStaleReadReceipts,
+  cursorBaseline,
+  newFilesSince,
+  hostFileCommit,
   type ChannelMessage,
 } from './transport.js';
-import { readCursor, writeCursor } from './cursor.js';
+import {
+  stateDir,
+  readCursor,
+  writeCursor,
+  writeHeartbeat,
+  writePidfile,
+  removePidfile,
+  logError,
+} from './state.js';
+import { recipients, reList, decideWake, splitForConcurrency } from './activation.js';
 import { now, messageFilename } from './filenames.js';
 import { serializeFrontmatter } from './frontmatter.js';
 import { withLock } from './turnq.js';
-import { writeDlqEntry, isQuarantined, isActorQuarantined } from './dlq.js';
+import { writeDlqEntry, isQuarantined } from './dlq.js';
+
+const RUNTIME_VERSION: string = (() => {
+  try {
+    const pkgPath = join(dirname(fileURLToPath(import.meta.url)), '..', 'package.json');
+    return (JSON.parse(readFileSync(pkgPath, 'utf-8')) as { version?: string }).version ?? 'unknown';
+  } catch {
+    return 'unknown';
+  }
+})();
 
 const transportRoot = resolve(process.cwd());
 const argv = process.argv.slice(2);
@@ -63,27 +71,9 @@ const hostOverride = flag('--host');
 const pollSeconds = Number(flag('--poll')) || 30;
 const logFile = flag('--log-file');
 
-// Backoff config — persistent infra failures (git pull/push) trigger
-// exponential delay. Reset on any successful pull+push cycle.
-const MAX_BACKOFF_MULTIPLIER = 10; // cap: pollSeconds * 10
-const BACKOFF_GRACE = 2; // first N failures don't trigger backoff
-
-// Per-tick heal: when N consecutive infra failures pile up, the dispatch
-// loop is stuck in a deadlock that entrypoint's boot-time auto-recovery
-// can't break (because dispatch is already running). At HEAL_THRESHOLD
-// consecutive failures, attempt a `git fetch && reset --hard origin/<branch>
-// && clean -fd` from inside the tick loop. Mirrors the entrypoint logic.
-// Throttled — won't reattempt until fully BACKOFF_GRACE+HEAL_THRESHOLD more
-// failures pile up after a heal, to avoid heal-loop-storms.
-const HEAL_THRESHOLD = 5;
-let lastHealAtFailureCount = 0;
-
-// Stale-read-receipt sweep config — runs at most every SWEEP_INTERVAL_MS
-// of wall-clock to surface read receipts that never produced a reply
-// (indicates dispatch crashed mid-tick or CLI hung silently).
-const SWEEP_INTERVAL_MS = 5 * 60_000;
-const STALE_RECEIPT_THRESHOLD_MS = 5 * 60_000;
-let lastSweepAt = 0;
+const CLI_TIMEOUT_MS = 5 * 60_000;
+const MAX_BACKOFF_MULTIPLIER = 10;
+const BACKOFF_GRACE = 2;
 
 function log(event: string, fields: Record<string, unknown> = {}): void {
   let line: string;
@@ -101,185 +91,24 @@ function log(event: string, fields: Record<string, unknown> = {}): void {
   }
 }
 
-function writeHeartbeat(): void {
-  try {
-    const dir = join(transportRoot, '.turnq');
-    mkdirSync(dir, { recursive: true });
-    const data = { ts: new Date().toISOString(), pid: process.pid, version: RUNTIME_VERSION };
-    writeFileSync(join(dir, 'heartbeat'), JSON.stringify(data) + '\n');
-  } catch { /* best-effort */ }
+// Config errors (bad host file, bad actor profile) repeat every tick until
+// fixed — log each distinct one once per process run, not once per tick.
+const loggedConfigErrors = new Set<string>();
+function logConfigError(scope: string, message: string): void {
+  const key = `${scope}::${message}`;
+  if (loggedConfigErrors.has(key)) return;
+  loggedConfigErrors.add(key);
+  logError(transportRoot, 'parse', `${scope}: ${message}`);
+  log('config_error', { scope, message: message.slice(0, 200) });
 }
 
-function loadProtocolPrompt(): string {
+const protocolPrompt = (() => {
   const p = join(transportRoot, 'upstream', 'PROTOCOL.md');
-  if (!existsSync(p)) return '';
-  return readFileSync(p, 'utf-8').trim();
-}
-
-const protocolPrompt = loadProtocolPrompt();
-
-function recipients(toField: unknown): string[] {
-  if (Array.isArray(toField)) return toField.map(String);
-  if (typeof toField === 'string') return [toField];
-  return [];
-}
-
-// A `to:` recipient is either a bare actor name (`junior-developer`) or
-// an actor@host pair (`junior-developer@cachy`). Bare names broadcast to
-// every host that declares the actor; @host narrows to one host.
-//
-// Documented in concierge.md "Host-aware routing"; honored by the runtime
-// as of alpha.7 step 1. Prior to this, the recipient string was matched
-// verbatim against the actor name, so `junior-developer@cachy` never
-// matched the cachy dispatcher's `junior-developer` actor declaration —
-// the harness's first cross-host bug.
-function extractActor(recipient: string): string {
-  const at = recipient.indexOf('@');
-  return at === -1 ? recipient : recipient.slice(0, at);
-}
-
-function targetHost(recipient: string): string | null {
-  const at = recipient.indexOf('@');
-  return at === -1 ? null : recipient.slice(at + 1);
-}
-
-// Does `recipientList` address `actorName` on `thisHost`? Returns the match
-// outcome plus a flag for "actor was named but every instance targeted a
-// different host" — useful as a diagnostic so silent wrong-host routes are
-// logged rather than dropped without trace.
-function matchHostRouting(
-  recipientList: string[],
-  actorName: string,
-  thisHost: string,
-): { addressed: boolean; wrongHost: boolean } {
-  let addressed = false;
-  let actorNamedAtAll = false;
-  for (const r of recipientList) {
-    if (extractActor(r) !== actorName) continue;
-    actorNamedAtAll = true;
-    const host = targetHost(r);
-    if (host === null || host === thisHost) {
-      addressed = true;
-      break;
-    }
-  }
-  return { addressed, wrongHost: !addressed && actorNamedAtAll };
-}
-
-// Host-agnostic actor name check, used by causality scans (isCausalReply,
-// hasPriorWork) where the question is "does this recipient list name actor
-// X at all?" — host doesn't matter because the `from` field of replies
-// doesn't carry a host suffix either.
-function namesActor(recipientList: string[], actorName: string): boolean {
-  for (const r of recipientList) {
-    if (extractActor(r) === actorName) return true;
-  }
-  return false;
-}
-
-// Declared lifecycle kind for a message. `work` (default for legacy messages
-// without the field) is the as-tagged intent. The runtime does NOT trust this
-// value directly for the activation decision — see effectiveKind() below.
-// Kept for use as the seed of the effective-kind computation.
-function messageKind(msg: ChannelMessage): 'work' | 'result' {
-  const raw = msg.data['kind'];
-  return raw === 'result' ? 'result' : 'work';
-}
-
-// Is `msg` causally a reply to a prior ask? True iff some message strictly
-// before `msg` was sent FROM one of `msg`'s recipients TO `msg`'s sender with
-// declared kind `work`. If so, `msg` is that recipient's answer coming back —
-// regardless of how its sender (a fallible LLM actor, or `crosstalk send`'s
-// `work` default) labelled it.
-//
-// Conservative on multi-recipient `to:` lists: if ANY recipient previously
-// tasked the sender, the message is treated as causally a reply for all
-// recipients. The per-addressee asymmetry in hasPriorWork (below) compensates
-// — only the recipient that actually asked wakes on it. Known v1 limitation:
-// genuine multi-recipient fan-out where one recipient happens to have prior
-// unrelated work to the sender will be demoted to result and suppress wakes
-// for the other recipients. Not observed in Monte Carlo; revisit if it
-// surfaces.
-function isCausalReply(channelMessages: ChannelMessage[], msg: ChannelMessage): boolean {
-  const sender = typeof msg.data['from'] === 'string' ? msg.data['from'] : '';
-  if (!sender) return false;
-  const toList = recipients(msg.data['to']);
-  for (const m of channelMessages) {
-    if (m.relPath >= msg.relPath) break;
-    // Read receipts are bookkeeping, never causal evidence. The activation
-    // scan already filters them out before considering a message for
-    // dispatch — this filter is the same guard at the causality-helper
-    // level, so a receipt from one of msg's recipients to msg's sender
-    // can't forge a false causal-reply edge (which would then demote a
-    // legitimate `work` to `result` and silently skip it). This was the
-    // alpha.7 step 2 finding from the cross-host harness — receipts
-    // pre-existing in the channel from cachy's first dispatch burst
-    // misclassified mac's subsequent fan-out msgs as replies.
-    if (m.data['type'] === 'read') continue;
-    const mFrom = typeof m.data['from'] === 'string' ? m.data['from'] : '';
-    // Host-agnostic actor name match: `from` fields are bare actor names,
-    // but `to` fields may include `@host` suffixes that don't change
-    // causal semantics.
-    if (!namesActor(toList, mFrom)) continue;
-    if ((m.data['kind'] ?? 'work') === 'result') continue;
-    if (namesActor(recipients(m.data['to']), sender)) return true;
-  }
-  return false;
-}
-
-// Effective lifecycle kind. The runtime INFERS kind from the causality graph
-// rather than trusting the declared field: a message that is causally a reply
-// is a `result` even if it was labelled `work` (actors routinely report
-// results via `crosstalk send`, which defaults to `work`, and that mislabel
-// forges false reply-causality edges → wake-up loops). Genuine unsolicited
-// tasks (kickoffs, fresh dispatches) have no prior opposite-direction work
-// and keep their `work` kind. See PROTOCOL.md "Message kinds".
-//
-// This is the load-bearing principle the rest of the activation rule rides
-// on: the dispatcher derives semantics from the interaction graph; it never
-// trusts an actor's declaration.
-function effectiveKind(channelMessages: ChannelMessage[], msg: ChannelMessage): 'work' | 'result' {
-  if (messageKind(msg) === 'result') return 'result';
-  return isCausalReply(channelMessages, msg) ? 'result' : 'work';
-}
-
-// Reply causality — does `addressee` have a prior `kind: work` outbound to
-// `sender` somewhere in the channel's history strictly before `before`? If
-// yes, an inbound `kind: result` from `sender` to `addressee` is the answer
-// to that ask, and the addressee should wake on it. If no, the result is
-// unsolicited from addressee's POV and is informational only.
-//
-// Uses effectiveKind (not messageKind) when checking prior messages — a
-// mislabeled "work" reply from a prior peer would otherwise forge a false
-// causality edge here, which was the ping-pong root.
-//
-// The channel is already sorted by relPath ascending in
-// listChannelMessages(), so the scan walks chronologically.
-function hasPriorWork(
-  channelMessages: ChannelMessage[],
-  addressee: string,
-  sender: string,
-  before: string,
-): boolean {
-  for (const m of channelMessages) {
-    if (m.relPath >= before) break;
-    // Same receipt filter as isCausalReply — a receipt from `addressee`
-    // to `sender` would otherwise look like a prior work outbound and
-    // forge a false causal edge here too. Defense against the same
-    // bug class at every causality-walking helper.
-    if (m.data['type'] === 'read') continue;
-    if (typeof m.data['from'] !== 'string' || m.data['from'] !== addressee) continue;
-    if (effectiveKind(channelMessages, m) !== 'work') continue;
-    const toList = recipients(m.data['to']);
-    if (namesActor(toList, sender)) return true;
-  }
-  return false;
-}
+  return existsSync(p) ? readFileSync(p, 'utf-8').trim() : '';
+})();
 
 function composeSystemPrompt(actorPrompt: string): string {
-  return [protocolPrompt, actorPrompt]
-    .filter((p) => p.length > 0)
-    .join('\n\n---\n\n');
+  return [protocolPrompt, actorPrompt].filter((p) => p.length > 0).join('\n\n---\n\n');
 }
 
 function actorConcurrency(tiers: HostActorTiers): number {
@@ -291,17 +120,29 @@ function actorConcurrency(tiers: HostActorTiers): number {
   return 1;
 }
 
+function messageSender(msg: ChannelMessage): string {
+  return typeof msg.data['from'] === 'string' ? (msg.data['from'] as string) : 'unknown';
+}
+
 interface CliResult {
   status: number;
   stdout: string;
   stderr: string;
 }
 
+// Pass the prompt as the CLI's last argv entry. Every modern agent CLI
+// (Claude --print, codex exec, gemini -p, qwen -p, opencode run, agy -p)
+// reads its prompt from the trailing positional or flag-value, so appending
+// it works universally — no per-agent `bash -c '... "$(cat)"'` wrapper.
+// Fallback to stdin when the prompt would exceed a safe argv size, since
+// ARG_MAX is ~128KB on Linux and ~256KB on macOS.
+const ARGV_PROMPT_LIMIT = 64 * 1024;
+
 function invokeCli(
   cli: string,
   systemPrompt: string,
   userMessage: string,
-  actorName: string,
+  env: Record<string, string>,
 ): Promise<CliResult> {
   return new Promise((res) => {
     const fullPrompt = `${systemPrompt}\n\n---\n\n${userMessage}`;
@@ -310,15 +151,15 @@ function invokeCli(
       res({ status: 1, stdout: '', stderr: 'tokenized cli is empty' });
       return;
     }
-    // detached: true creates a new process group so we can SIGKILL the
-    // group (not just the parent) on timeout — orphan children writing
-    // to the transport after parent SIGKILL was an observed alpha.5 hazard.
-    // Env: CROSSTALK_DISPATCH_ACTOR tells send.ts what to use as --from when
-    // the dispatched actor invokes `crosstalk send` without explicit --from.
-    const child = spawn(parts[0], parts.slice(1), {
+    const useStdin = Buffer.byteLength(fullPrompt, 'utf-8') > ARGV_PROMPT_LIMIT;
+    const argv = useStdin ? parts.slice(1) : [...parts.slice(1), fullPrompt];
+    // detached: new process group, so the timeout SIGKILL takes the actor's
+    // children with it — orphans writing to the transport after a timeout
+    // was an observed v5 hazard.
+    const child = spawn(parts[0]!, argv, {
       stdio: ['pipe', 'pipe', 'pipe'],
       detached: true,
-      env: { ...process.env, CROSSTALK_DISPATCH_ACTOR: actorName },
+      env: { ...process.env, ...env },
     });
     let stdout = '';
     let stderr = '';
@@ -326,20 +167,14 @@ function invokeCli(
     const timeout = setTimeout(() => {
       if (resolved) return;
       resolved = true;
-      // SIGKILL the process group (negative pid) so any children the actor
-      // spawned (e.g. crosstalk send subprocesses) die with the parent.
-      // Fallback to single-pid kill if the group signal fails (some envs).
       try {
-        if (typeof child.pid === 'number') {
-          process.kill(-child.pid, 'SIGKILL');
-        } else {
-          child.kill('SIGKILL');
-        }
+        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]' });
-    }, 5 * 60_000);
+    }, CLI_TIMEOUT_MS);
     child.stdout.on('data', (d) => { stdout += d.toString(); });
     child.stderr.on('data', (d) => { stderr += d.toString(); });
     child.on('close', (code) => {
@@ -354,158 +189,55 @@ function invokeCli(
       clearTimeout(timeout);
       res({ status: 1, stdout, stderr: stderr + '\n' + err.message });
     });
-    // The child may exit before reading stdin (e.g. cli=`false`). Attach
-    // an error handler so EPIPE is swallowed instead of crashing dispatch,
-    // and guard the write itself.
-    child.stdin.on('error', () => { /* EPIPE/etc. — child closed stdin */ });
-    try {
-      child.stdin.write(fullPrompt);
-    } catch { /* same: child closed stdin before we could write */ }
-    try {
-      child.stdin.end();
-    } catch { /* ignore */ }
+    child.stdin.on('error', () => { /* child closed stdin */ });
+    if (useStdin) {
+      try { child.stdin.write(fullPrompt); } catch { /* same */ }
+    }
+    try { child.stdin.end(); } catch { /* ignore */ }
   });
 }
 
 function writeReply(
   channelUuid: string,
   fromActor: string,
-  toActor: string | string[],
+  toActor: string,
+  re: string | string[],
   body: string,
 ): void {
   const ts = now();
   const dir = join(transportRoot, 'data', 'channels', channelUuid, ts.pathDate);
   mkdirSync(dir, { recursive: true });
-  // Auto-replies emitted via stdout are `kind: result` by default — the actor
-  // is answering, not initiating new work. Recipients only wake on a result if
-  // they previously asked the sender for work in this channel (reply
-  // causality, see activation rule below). Actors that want to dispatch new
-  // work do so explicitly via `crosstalk send --kind work`.
   const content = serializeFrontmatter(
-    { from: fromActor, to: toActor, type: 'text', kind: 'result', timestamp: ts.iso },
+    { from: fromActor, to: toActor, type: 'text', timestamp: ts.iso, re },
     body,
   );
   writeFileSync(join(dir, messageFilename(ts)), content);
 }
 
-function writeReadReceipt(
-  channelUuid: string,
-  fromActor: string,
-  toActor: string,
-  ref: string,
-): void {
-  const ts = now();
-  const dir = join(transportRoot, 'data', 'channels', channelUuid, ts.pathDate);
-  mkdirSync(dir, { recursive: true });
-  const content = serializeFrontmatter(
-    { from: fromActor, to: toActor, type: 'read', ref, timestamp: ts.iso },
-    '',
-  );
-  writeFileSync(join(dir, messageFilename(ts)), content);
-}
-
-interface PendingDispatch {
-  actorName: string;
-  channelUuid: string;
-  msgs: ChannelMessage[]; // all unread messages addressed to this actor in this channel
-  tiers: HostActorTiers;
-}
-
-function messageSender(msg: ChannelMessage): string {
-  return typeof msg.data['from'] === 'string' ? msg.data['from'] : 'unknown';
-}
-
 function formatBatchedUserMessage(msgs: ChannelMessage[]): string {
-  if (msgs.length === 1) return msgs[0].body;
-  const header = `You have ${msgs.length} new messages in this channel. Process them collectively and reply once.`;
-  const parts: string[] = [header];
+  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 from = messageSender(m);
-    const ts = typeof m.data['timestamp'] === 'string' ? (m.data['timestamp'] as string) : '';
-    parts.push(`--- Message ${i + 1} of ${msgs.length} (from: ${from}, ref: ${m.relPath}${ts ? `, ts: ${ts}` : ''}) ---`);
+    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');
 }
 
-// Split a channel's pending messages (already sorted by relPath) into
-// contiguous batches sized for the actor's concurrency. Contiguous (not
-// round-robin) so each batch's highest relPath is monotone across batches —
-// the cursor advances safely after the dispatch loop's per-batch writes
-// without leaving a gap that would re-dispatch on the next tick.
-//
-// When pending fits within concurrency, every batch is a single message
-// (preserves parallel fan-out — junior-developer with count: 10 and 10
-// pending fan-out messages dispatches 10 parallel CLI invocations of 1
-// message each). When pending exceeds concurrency, batches collapse pending
-// into ~concurrency parallel invocations, each handling ceil(N/concurrency)
-// messages (preserves the fan-in collapse — concierge with count: 1 and 10
-// pending replies dispatches 1 invocation of 10 messages).
-function splitForConcurrency(
-  msgs: ChannelMessage[],
-  concurrency: number,
-): ChannelMessage[][] {
-  if (concurrency <= 1 || msgs.length <= 1) return [msgs];
-  const chunkSize = Math.max(1, Math.ceil(msgs.length / concurrency));
-  const out: ChannelMessage[][] = [];
-  for (let i = 0; i < msgs.length; i += chunkSize) {
-    out.push(msgs.slice(i, i + chunkSize));
-  }
-  return out;
-}
-
-function distinctSenders(msgs: ChannelMessage[]): string[] {
-  const seen = new Set<string>();
-  const out: string[] = [];
-  for (const m of msgs) {
-    const s = messageSender(m);
-    if (s !== 'unknown' && !seen.has(s)) {
-      seen.add(s);
-      out.push(s);
-    }
-  }
-  return out;
+interface PendingDispatch {
+  actorName: string;
+  channelUuid: string;
+  msgs: ChannelMessage[];
+  tiers: HostActorTiers;
 }
 
 async function dispatchOne(p: PendingDispatch): Promise<boolean> {
-  // Tier resolution uses the first message's `tier:` hint (if any). Batched
-  // dispatches assume homogeneous tier preference within an (actor, channel)
-  // pairing — true for fan-in (all peer replies omit tier) and for explicit
-  // single-message dispatches alike.
-  const firstMsg = p.msgs[0];
-  const lastMsg = p.msgs[p.msgs.length - 1];
-  const preferredTier = typeof firstMsg.data['tier'] === 'string'
-    ? (firstMsg.data['tier'] as string)
-    : undefined;
-  let resolved;
-  try {
-    resolved = pickTier(p.tiers, preferredTier);
-  } catch (err) {
-    const r = writeDlqEntry(
-      transportRoot,
-      'config',
-      p.actorName,
-      '(config)',
-      '(config)',
-      `tier selection failed: ${(err as Error).message}`,
-    );
-    log('actor_config_error', {
-      actor: p.actorName,
-      dlq_id: r.id,
-      attempts: r.attempts,
-      quarantined: r.quarantined,
-    });
-    return false;
-  }
-  const cli = resolved.cli;
-
-  // Quarantine check uses the LAST message's relPath as the batch's identity.
-  // Per-message quarantine semantics are preserved because batch boundaries
-  // align with cursor checkpoints; if a single message in a batch keeps
-  // failing, the cursor never advances past it and it surfaces as a singleton
-  // batch on the next tick.
-  if (isQuarantined(transportRoot, 'dispatch', p.actorName, p.channelUuid, lastMsg.relPath)) {
+  const firstMsg = p.msgs[0]!;
+  const lastMsg = p.msgs[p.msgs.length - 1]!;
+
+  if (isQuarantined(transportRoot, p.actorName, p.channelUuid, lastMsg.relPath)) {
     log('dispatch_skipped_quarantined', {
       actor: p.actorName,
       channel: p.channelUuid.slice(0, 8),
@@ -514,6 +246,17 @@ async function dispatchOne(p: PendingDispatch): Promise<boolean> {
     return false;
   }
 
+  const preferredTier = typeof firstMsg.data['tier'] === 'string' ? (firstMsg.data['tier'] as string) : undefined;
+  let cli: string;
+  let profile;
+  try {
+    cli = pickTier(p.tiers, preferredTier).cli;
+    profile = loadActorProfile(transportRoot, p.actorName);
+  } catch (err) {
+    logConfigError(`actor:${p.actorName}`, (err as Error).message);
+    return false;
+  }
+
   log('dispatch', {
     actor: p.actorName,
     channel: p.channelUuid.slice(0, 8),
@@ -522,42 +265,22 @@ async function dispatchOne(p: PendingDispatch): Promise<boolean> {
     last_msg: lastMsg.relPath,
   });
 
-  // Read receipt per message — preserves the audit trail (each original
-  // message gets exactly one receipt) and keeps the stale-receipt sweep
-  // correct.
-  for (const m of p.msgs) {
-    writeReadReceipt(p.channelUuid, p.actorName, messageSender(m), m.relPath);
-  }
-
-  let profile;
-  try {
-    profile = loadActorProfile(transportRoot, p.actorName);
-  } catch (err) {
-    const r = writeDlqEntry(
-      transportRoot,
-      'config',
-      p.actorName,
-      '(config)',
-      '(config)',
-      `actor profile load failed: ${(err as Error).message}`,
-    );
-    log('dispatch_config_error', {
-      actor: p.actorName,
-      dlq_id: r.id,
-      attempts: r.attempts,
-      quarantined: r.quarantined,
-    });
-    return false;
-  }
-
-  const systemPrompt = composeSystemPrompt(profile.systemPrompt);
-  const userMessage = formatBatchedUserMessage(p.msgs);
-  const result = await invokeCli(cli, systemPrompt, userMessage, p.actorName);
+  const result = await invokeCli(
+    cli,
+    composeSystemPrompt(profile.systemPrompt),
+    formatBatchedUserMessage(p.msgs),
+    {
+      CROSSTALK_DISPATCH_ACTOR: p.actorName,
+      CROSSTALK_DISPATCH_CHANNEL: p.channelUuid,
+      // Every relPath in the batch — `crosstalk send` records them all as
+      // the reply's re: list, so batching never loses an answered message.
+      CROSSTALK_DISPATCH_RE: p.msgs.map((m) => m.relPath).join(','),
+    },
+  );
 
   if (result.status !== 0) {
     const r = writeDlqEntry(
       transportRoot,
-      'dispatch',
       p.actorName,
       p.channelUuid,
       lastMsg.relPath,
@@ -577,45 +300,28 @@ async function dispatchOne(p: PendingDispatch): Promise<boolean> {
 
   const reply = result.stdout.trim();
   if (reply.length === 0) {
-    // Empty stdout on a multi-message batch is treated as success — the
-    // actor likely routed via `crosstalk send` and has nothing to add as
-    // an auto-reply. For a single-message batch we keep the prior DLQ
-    // semantics: a single dispatched message that produces no reply is a
-    // protocol violation.
-    if (p.msgs.length > 1) {
-      log('dispatch_batch_silent_ok', {
-        actor: p.actorName,
-        channel: p.channelUuid.slice(0, 8),
-        batch_size: p.msgs.length,
-      });
-      return true;
-    }
-    const r = writeDlqEntry(
-      transportRoot,
-      'dispatch',
-      p.actorName,
-      p.channelUuid,
-      lastMsg.relPath,
-      'cli returned empty reply',
-    );
-    log('dispatch_empty_reply', {
-      actor: p.actorName,
-      channel: p.channelUuid.slice(0, 8),
-      dlq_id: r.id,
-      attempts: r.attempts,
-      quarantined: r.quarantined,
-    });
-    return false;
+    // Legitimate: the actor routed its answer via `crosstalk send` (which
+    // auto-links re:). If it truly did nothing, the asker's `crosstalk
+    // replies` stays PENDING — visible, not silently lost.
+    log('dispatch_silent', { actor: p.actorName, channel: p.channelUuid.slice(0, 8), batch_size: p.msgs.length });
+    log('dispatch_done', { actor: p.actorName, channel: p.channelUuid.slice(0, 8), batch_size: p.msgs.length, replied: false });
+    return true;
   }
 
-  // Auto-reply addressing: single-sender batches reply to that sender
-  // (preserves prior behavior). Multi-sender batches address all distinct
-  // senders so each peer sees the response.
-  const senders = distinctSenders(p.msgs);
-  const replyTo: string | string[] = senders.length <= 1
-    ? (senders[0] ?? messageSender(firstMsg))
-    : senders;
-  writeReply(p.channelUuid, p.actorName, replyTo, reply);
+  // One reply per distinct sender, re:-linked to EVERY message that sender
+  // had in the batch — the asker's activation rule fires, and `crosstalk
+  // replies` sees each individual message as answered.
+  const bySender = new Map<string, string[]>();
+  for (const m of p.msgs) {
+    const sender = messageSender(m);
+    bySender.set(sender, [...(bySender.get(sender) ?? []), m.relPath]);
+  }
+  bySender.delete('unknown');
+  if (bySender.size === 0) bySender.set(messageSender(firstMsg), [firstMsg.relPath]);
+  for (const [sender, relPaths] of bySender) {
+    writeReply(p.channelUuid, p.actorName, sender, relPaths.length === 1 ? relPaths[0]! : relPaths, reply);
+  }
+  log('dispatch_done', { actor: p.actorName, channel: p.channelUuid.slice(0, 8), batch_size: p.msgs.length, replied: true });
   return true;
 }
 
@@ -625,278 +331,200 @@ interface TickResult {
 }
 
 async function dispatchTick(): Promise<TickResult> {
-  writeHeartbeat();
-
-  return withLock('dispatch', async () => {
-    let infraOk = true;
-
-    const pullResult = gitPull(transportRoot);
-    if (!pullResult.ok && pullResult.error) {
-      // Note: deliberately NOT calling writeErrorLog here. Repeated pull
-      // failures (deadlock loop) would otherwise write a new errors/*.md
-      // every tick, which dispatch then has to commit, which the next
-      // pull then chokes on — a positive feedback that contributed to
-      // the alpha.3/alpha.4 Mac UAT wedge. The structured log line below
-      // gives operators full diagnostic info via stdout/json logs.
-      log('git_pull_failed', { error: pullResult.error.slice(0, 200) });
-      infraOk = false;
-    }
+  writeHeartbeat(transportRoot, RUNTIME_VERSION);
+  let infraOk = true;
+
+  const pullResult = gitPull(transportRoot);
+  if (!pullResult.ok) {
+    // Skip the whole tick: a failed pull can leave origin/HEAD (the cursor
+    // baseline) ahead of the working tree, and scanning against that would
+    // advance cursors past messages that never materialized.
+    logError(transportRoot, 'git_pull', pullResult.error ?? 'unknown');
+    log('git_pull_failed', { error: (pullResult.error ?? '').slice(0, 200) });
+    return { didWork: false, infraOk: false };
+  }
 
-    let host: HostFile;
-    try {
-      host = findHostFile(transportRoot, hostOverride);
-    } catch (err) {
-      const r = writeDlqEntry(
-        transportRoot,
-        'config',
-        '(host)',
-        '(config)',
-        '(config)',
-        `host file load failed: ${(err as Error).message}`,
-      );
-      log('tick_config_error', {
-        scope: 'host',
-        dlq_id: r.id,
-        attempts: r.attempts,
-        quarantined: r.quarantined,
-      });
-      return { didWork: false, infraOk };
-    }
+  let host: HostFile;
+  try {
+    host = findHostFile(transportRoot, hostOverride);
+  } catch (err) {
+    logConfigError('host', (err as Error).message);
+    return { didWork: false, infraOk };
+  }
 
-    let didWork = false;
+  // Cursors are commit hashes, not relPaths: filenames order by sender
+  // timestamp but arrive in push order, so a relPath cursor can advance
+  // past a slower writer's earlier-stamped message and lose it forever.
+  // "New since cursor" is asked of git, which records arrival truthfully.
+  const head = cursorBaseline(transportRoot);
+  if (!head) {
+    logError(transportRoot, 'other', 'git rev-parse failed for origin/HEAD and HEAD — skipping tick');
+    return { didWork: false, infraOk: false };
+  }
+  // diff results keyed by cursor commit (shared across actors on the same
+  // cursor); null = commit unknown to this clone -> full re-scan.
+  const addedSince = new Map<string, Set<string> | null>();
+
+  let didWork = false;
+  const channels = discoverChannels(transportRoot);
+
+  for (const actorName of Object.keys(host.actors)) {
+    const tiers = host.actors[actorName]!;
+    const concurrency = actorConcurrency(tiers);
+    const pending: PendingDispatch[] = [];
+
+    for (const channelUuid of channels) {
+      const persistedCursor = readCursor(transportRoot, actorName, channelUuid);
+      if (persistedCursor === head) continue;
+
+      // First encounter: seed to the commit that introduced this actor's host
+      // file. Messages sent after the host joined are delivered (store-and-
+      // forward); pre-join history is ignored. Seeding to HEAD would silently
+      // drop messages sent while the dispatcher was offline — the wrong trade.
+      // Fall through after seeding so this tick processes the post-join backlog
+      // (otherwise `--once` users hit a seed-then-dispatch two-tick gotcha).
+      let cursor: string;
+      if (persistedCursor === null) {
+        const joinCommit = hostFileCommit(transportRoot, host.alias);
+        cursor = joinCommit ?? head;
+        writeCursor(transportRoot, actorName, channelUuid, cursor);
+        if (cursor === head) continue;
+      } else {
+        cursor = persistedCursor;
+      }
 
-    for (const actorName of Object.keys(host.actors)) {
-      if (isActorQuarantined(transportRoot, actorName)) {
-        log('actor_skipped_quarantined', { actor: actorName });
+      const messages = listChannelMessages(transportRoot, channelUuid);
+      const senderByRelPath = new Map(messages.map((m) => [m.relPath, messageSender(m)]));
+      const senderOf = (relPath: string) => senderByRelPath.get(relPath);
+
+      let added = addedSince.get(cursor);
+      if (added === undefined) {
+        const files = newFilesSince(transportRoot, cursor);
+        added = files === null ? null : new Set(files);
+        addedSince.set(cursor, added);
+        if (added === null) {
+          logError(transportRoot, 'other', `cursor commit ${cursor.slice(0, 12)} unknown to this clone — full channel re-scan`);
+        }
+      }
+      let post = messages;
+      if (added !== null) {
+        const prefix = `data/channels/${channelUuid}/`;
+        post = messages.filter((m) => added.has(prefix + m.relPath));
+      }
+      if (post.length === 0) {
+        writeCursor(transportRoot, actorName, channelUuid, head);
         continue;
       }
 
-      const tiers = host.actors[actorName];
-      const concurrency = actorConcurrency(tiers);
-
-      // Mailbox batch-drain: for each channel, collect ALL unread messages
-      // addressed to this actor into a single PendingDispatch. This collapses
-      // fan-in O(N) into O(1) CLI invocations and prevents one actor's deep
-      // backlog from starving its peers in the (actor, channel) scan order.
-      // Read receipts and self-sent messages are filtered here — receipts
-      // are bookkeeping the actor already produced, and self-messages would
-      // create a wake-up loop.
-      const pending: PendingDispatch[] = [];
-      const channels = discoverChannels(transportRoot);
-      for (const channelUuid of channels) {
-        const cursor = readCursor(transportRoot, actorName, channelUuid);
-        const messages = listChannelMessages(transportRoot, channelUuid);
-        const post = cursor ? messages.filter((m) => m.relPath > cursor) : messages;
-
-        log('tick_scan', {
-          actor: actorName,
-          channel: channelUuid.slice(0, 8),
-          cursor: cursor ?? '(none)',
-          total_msgs: messages.length,
-          post_cursor_msgs: post.length,
-        });
-
-        const channelBatch: ChannelMessage[] = [];
-        for (const msg of post) {
-          const to = recipients(msg.data['to']);
-          const from = typeof msg.data['from'] === 'string' ? msg.data['from'] : 'unknown';
-          const msgType = typeof msg.data['type'] === 'string' ? msg.data['type'] : 'text';
-          // Host-aware routing match. A recipient may target this actor
-          // either by bare name (`junior-developer` — broadcast to every
-          // host that declares the actor) or by `actor@host` (narrowed to
-          // a specific host). Bare-name match always succeeds when the
-          // actor name matches; @host match succeeds only when the host
-          // alias also matches this dispatcher's host. A recipient that
-          // names this actor but targets a different host is flagged as
-          // `host_routing_mismatch` so silent wrong-host routes are
-          // surfaced rather than dropped without trace. See concierge.md
-          // "Host-aware routing" + PROTOCOL.md.
-          const routing = matchHostRouting(to, actorName, host.alias);
-          if (!routing.addressed || from === actorName || msgType === 'read') {
-            if (routing.wrongHost) {
-              log('host_routing_mismatch', {
-                actor: actorName,
-                this_host: host.alias,
-                channel: channelUuid.slice(0, 8),
-                msg: msg.relPath,
-                to,
-              });
-            }
-            writeCursor(transportRoot, actorName, channelUuid, msg.relPath);
-            continue;
-          }
-          // Lifecycle activation rule. `work` always wakes. `result` wakes
-          // only if reply-causal — actor previously sent the sender a `work`
-          // in this channel. The kind used here is the runtime's INFERRED
-          // effective kind, not the actor's declared kind: a message that's
-          // causally a reply is treated as `result` even when an actor (or
-          // `crosstalk send`'s default) labelled it `work`, so a fan-in peer
-          // mislabeling its reply can't forge a wake-up loop. See PROTOCOL.md
-          // "Message kinds".
-          const kind = effectiveKind(messages, msg);
-          if (kind === 'result' && !hasPriorWork(messages, actorName, from, msg.relPath)) {
-            writeCursor(transportRoot, actorName, channelUuid, msg.relPath);
-            continue;
-          }
-          channelBatch.push(msg);
-        }
-        if (channelBatch.length > 0) {
-          const groups = splitForConcurrency(channelBatch, concurrency);
-          for (const g of groups) {
-            pending.push({ actorName, channelUuid, msgs: g, tiers });
-          }
+      const batch: ChannelMessage[] = [];
+      for (const msg of post) {
+        if (msg.data['type'] !== 'text') continue;
+        const decision = decideWake(
+          {
+            from: messageSender(msg),
+            to: recipients(msg.data['to']),
+            re: reList(msg.data['re']),
+          },
+          actorName,
+          host.alias,
+          senderOf,
+        );
+        if (decision === 'wake') {
+          batch.push(msg);
+        } else if (decision === 'wrong-host') {
+          log('host_routing_mismatch', {
+            actor: actorName,
+            this_host: host.alias,
+            channel: channelUuid.slice(0, 8),
+            msg: msg.relPath,
+            to: recipients(msg.data['to']),
+          });
         }
       }
 
-      // Concurrency now applies across (channel) batches, not individual
-      // messages. Each batch is one CLI invocation regardless of how many
-      // messages it carries. Cursor advances to the last message in the batch
-      // on success or skip — failure (DLQ) leaves the cursor behind so the
-      // tail of the batch retries.
-      for (let i = 0; i < pending.length; i += concurrency) {
-        const batch = pending.slice(i, i + concurrency);
-        const results = await Promise.all(batch.map((p) => dispatchOne(p)));
-        for (let j = 0; j < batch.length; j++) {
-          const p = batch[j];
-          const lastRelPath = p.msgs[p.msgs.length - 1].relPath;
-          writeCursor(transportRoot, p.actorName, p.channelUuid, lastRelPath);
-          if (results[j]) didWork = true;
-        }
+      if (batch.length === 0) {
+        writeCursor(transportRoot, actorName, channelUuid, head);
+        continue;
+      }
+      for (const g of splitForConcurrency(batch, concurrency)) {
+        pending.push({ actorName, channelUuid, msgs: g, tiers });
       }
     }
 
-    // Always attempt commit+push at end of tick — gitCommitAndPush
-    // short-circuits if the working tree is clean. This is required
-    // even when no replies were produced, because cursors advance for
-    // messages addressed to other actors (the actor's own replies and
-    // read receipts appear on the next pull and need to be skipped past).
-    // Without this commit, the orphan cursor change blocks the next
-    // git pull --rebase and dispatch dead-ends in backoff.
-    const commitMsg = didWork
-      ? `dispatch: replies + cursor advance ${new Date().toISOString()}`
-      : `dispatch: cursor advance ${new Date().toISOString()}`;
-    const pushResult = gitCommitAndPush(transportRoot, commitMsg);
-    if (!pushResult.ok && pushResult.error) {
-      // Same rationale as the pull case above: no writeErrorLog.
-      // Repeated push failures shouldn't flood errors/ since that
-      // contributes to the same git-deadlock-feedback that pull does.
-      const kind = pushResult.committed ? 'git_push' : 'git_commit';
-      log('git_push_failed', {
-        kind,
-        committed_locally: pushResult.committed,
-        error: pushResult.error.slice(0, 200),
-      });
-      infraOk = false;
+    // Waves of `concurrency` parallel CLI invocations. The cursor advances
+    // to the scanned commit whether each batch succeeded or DLQ'd —
+    // at-least-once was attempted; `crosstalk dlq --retry` rewinds the
+    // cursor explicitly. A crash mid-wave leaves the cursor behind, so the
+    // whole span replays next tick (at-least-once, never lost).
+    for (let i = 0; i < pending.length; i += concurrency) {
+      const wave = pending.slice(i, i + concurrency);
+      const results = await Promise.all(wave.map((p) => dispatchOne(p)));
+      if (results.some(Boolean)) didWork = true;
+    }
+    for (const p of pending) {
+      writeCursor(transportRoot, p.actorName, p.channelUuid, head);
     }
+  }
 
-    // Periodic stale-read-receipt sweep
-    if (Date.now() - lastSweepAt > SWEEP_INTERVAL_MS) {
-      const surfaced = sweepStaleReadReceipts(transportRoot, STALE_RECEIPT_THRESHOLD_MS);
-      lastSweepAt = Date.now();
-      if (surfaced > 0) {
-        log('stale_receipts_surfaced', { count: surfaced });
-      }
+  if (didWork) {
+    const pushResult = await withLock(transportRoot, 'git', async () =>
+      gitCommitAndPush(transportRoot, `dispatch: replies ${new Date().toISOString()}`),
+    );
+    if (!pushResult.ok && pushResult.error) {
+      logError(transportRoot, pushResult.committed ? 'git_push' : 'git_commit', pushResult.error);
+      log('git_push_failed', { committed_locally: pushResult.committed, error: pushResult.error.slice(0, 200) });
+      infraOk = false;
     }
+  }
 
-    return { didWork, infraOk };
-  });
+  return { didWork, infraOk };
 }
 
-async function waitForWakeOrTimeout(ms: number): Promise<'wake' | 'timeout'> {
-  const wakeDir = join(transportRoot, '.turnq');
-  mkdirSync(wakeDir, { recursive: true });
+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(wakeDir, { signal: ac.signal });
+    const watcher = watch(dir, { signal: ac.signal });
     for await (const ev of watcher) {
-      if (ev.filename === 'wake.signal') {
-        clearTimeout(timer);
-        return 'wake';
-      }
+      if (ev.filename === 'wake.signal') return;
     }
-    return 'timeout';
   } catch {
-    return 'timeout';
+    /* abort = timeout */
   } finally {
     clearTimeout(timer);
   }
 }
 
 async function main(): Promise<void> {
-  log('dispatch_start', {
-    transport: transportRoot,
-    version: RUNTIME_VERSION,
-    log_file: logFile ?? null,
-  });
+  writePidfile(transportRoot);
+  const cleanup = () => removePidfile(transportRoot);
+  process.on('exit', cleanup);
+  process.on('SIGTERM', () => { cleanup(); process.exit(0); });
+  process.on('SIGINT',  () => { cleanup(); process.exit(0); });
+
+  log('dispatch_start', { transport: transportRoot, version: RUNTIME_VERSION, state_dir: stateDir(transportRoot) });
   if (onceMode) {
     await dispatchTick();
-    return;
+    process.exit(0);
   }
-  log('coordinator_running', { quiet_poll_s: pollSeconds, active_poll_s: 1 });
+  log('dispatch_running', { quiet_poll_s: pollSeconds });
 
   let consecutiveInfraFailures = 0;
-
   while (true) {
     try {
       const r = await dispatchTick();
       if (r.infraOk) {
-        if (consecutiveInfraFailures > 0) {
-          log('backoff_cleared', { previous_consecutive_failures: consecutiveInfraFailures });
-        }
+        if (consecutiveInfraFailures > 0) log('backoff_cleared', { previous_failures: consecutiveInfraFailures });
         consecutiveInfraFailures = 0;
       } else {
         consecutiveInfraFailures++;
       }
-
-      // Backoff kicks in only after a grace period of failures.
       const beyondGrace = Math.max(0, consecutiveInfraFailures - BACKOFF_GRACE);
       const backoffFactor = Math.min(MAX_BACKOFF_MULTIPLIER, 2 ** beyondGrace);
-
-      if (consecutiveInfraFailures > BACKOFF_GRACE) {
-        log('backoff_active', {
-          consecutive_failures: consecutiveInfraFailures,
-          factor: backoffFactor,
-        });
-      }
-
-      // Per-tick heal: deadlock-break when the dispatch loop has been
-      // failing for HEAL_THRESHOLD consecutive ticks AND we haven't healed
-      // recently. Hard-resets the working tree to origin/<current branch>.
-      // Trades any uncommitted local state for forward progress — acceptable
-      // because messages/cursors/dlq are pulled back from origin and
-      // .turnq/errors are regenerated.
-      if (
-        consecutiveInfraFailures >= HEAL_THRESHOLD &&
-        consecutiveInfraFailures - lastHealAtFailureCount >= HEAL_THRESHOLD
-      ) {
-        try {
-          const branchProc = spawn('git', ['rev-parse', '--abbrev-ref', 'HEAD'], {
-            cwd: transportRoot,
-            stdio: ['ignore', 'pipe', 'ignore'],
-          });
-          let branchName = '';
-          branchProc.stdout.on('data', (d) => { branchName += d.toString(); });
-          await new Promise<void>((res) => branchProc.on('close', () => res()));
-          const branch = branchName.trim() || 'main';
-          log('per_tick_heal_start', {
-            consecutive_failures: consecutiveInfraFailures,
-            target: `origin/${branch}`,
-          });
-          await new Promise<void>((res) => {
-            const p = spawn('sh', [
-              '-c',
-              `git rebase --abort 2>/dev/null; git fetch --quiet origin '${branch}' && git reset --hard --quiet 'origin/${branch}' && git clean -fdq`,
-            ], { cwd: transportRoot, stdio: 'inherit' });
-            p.on('close', () => res());
-          });
-          log('per_tick_heal_done', { target: `origin/${branch}` });
-          lastHealAtFailureCount = consecutiveInfraFailures;
-        } catch (err) {
-          log('per_tick_heal_failed', { error: (err as Error).message });
-        }
+      if (backoffFactor > 1) {
+        log('backoff_active', { consecutive_failures: consecutiveInfraFailures, factor: backoffFactor });
       }
-
       if (r.didWork) {
         await new Promise((res) => setTimeout(res, 1_000 * backoffFactor));
       } else {
@@ -904,7 +532,7 @@ async function main(): Promise<void> {
       }
     } catch (err) {
       const msg = (err as Error).message;
-      writeErrorLog(transportRoot, 'other', `tick error: ${msg}`);
+      logError(transportRoot, 'other', `tick error: ${msg}`);
       log('tick_error', { message: msg });
       consecutiveInfraFailures++;
       await new Promise((res) => setTimeout(res, pollSeconds * 1_000));