@cordfuse/crosstalk 5.0.0-alpha.3 → 5.0.0-alpha.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cordfuse/crosstalk",
-  "version": "5.0.0-alpha.3",
+  "version": "5.0.0-alpha.6",
   "description": "Crosstalk runtime — async messaging between agents over git. The crosstalk CLI plus dispatch, send, attach, chat, and supporting tools.",
   "type": "module",
   "license": "MIT",

package/src/chat.ts

@@ -25,7 +25,7 @@ import { createInterface } from 'readline/promises';
 import { spawnSync } from 'child_process';
 import { now, messageFilename } from './filenames.js';
 import { serializeFrontmatter, parseFrontmatter } from './frontmatter.js';
-import { gitCommitAndPush, writeErrorLog } from './transport.js';
+import { gitCommitAndPush } from './transport.js';
 import { withLock } from './turnq.js';
 
 const transportRoot = resolve(process.cwd());
@@ -132,9 +132,11 @@ async function sendMessage(body: string): Promise<void> {
       `chat: ${fromName} -> ${toActor} in ${channelUuid!.slice(0, 8)}`,
     );
     if (!r.ok && r.error) {
-      const kind = r.committed ? 'git_push' : 'git_commit';
-      writeErrorLog(transportRoot, kind, r.error);
-      console.error(`(${kind} failed: ${r.error.slice(0, 120)} — message is local-only)`);
+      // Same anti-pattern as send.ts: writing to errors/ from an operator-
+      // side command dirties the working tree and breaks subsequent
+      // git pull --rebase. Stay on stderr only.
+      const kind = r.committed ? 'push' : 'commit';
+      console.error(`(${kind} failed: ${r.error.slice(0, 200)} — message is local-only)`);
     }
   });
 }

package/src/dispatch.ts

@@ -1,4 +1,4 @@
-import { resolve, join } from 'path';
+import { resolve, join, dirname } from 'path';
 import { spawn } from 'child_process';
 import {
   mkdirSync,
@@ -10,6 +10,21 @@ import {
   closeSync,
 } 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,
@@ -53,6 +68,16 @@ const logFile = flag('--log-file');
 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).
@@ -80,7 +105,7 @@ function writeHeartbeat(): void {
   try {
     const dir = join(transportRoot, '.turnq');
     mkdirSync(dir, { recursive: true });
-    const data = { ts: new Date().toISOString(), pid: process.pid, version: '5.0.0-alpha.3' };
+    const data = { ts: new Date().toISOString(), pid: process.pid, version: RUNTIME_VERSION };
     writeFileSync(join(dir, 'heartbeat'), JSON.stringify(data) + '\n');
   } catch { /* best-effort */ }
 }
@@ -99,6 +124,87 @@ function recipients(toField: unknown): string[] {
   return [];
 }
 
+// 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;
+    const mFrom = typeof m.data['from'] === 'string' ? m.data['from'] : '';
+    if (!toList.includes(mFrom)) continue;
+    if ((m.data['kind'] ?? 'work') === 'result') continue;
+    if (recipients(m.data['to']).includes(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;
+    if (typeof m.data['from'] !== 'string' || m.data['from'] !== addressee) continue;
+    if (effectiveKind(channelMessages, m) !== 'work') continue;
+    const toList = recipients(m.data['to']);
+    if (toList.includes(sender)) return true;
+  }
+  return false;
+}
+
 function composeSystemPrompt(actorPrompt: string): string {
   return [protocolPrompt, actorPrompt]
     .filter((p) => p.length > 0)
@@ -120,7 +226,12 @@ interface CliResult {
   stderr: string;
 }
 
-function invokeCli(cli: string, systemPrompt: string, userMessage: string): Promise<CliResult> {
+function invokeCli(
+  cli: string,
+  systemPrompt: string,
+  userMessage: string,
+  actorName: string,
+): Promise<CliResult> {
   return new Promise((res) => {
     const fullPrompt = `${systemPrompt}\n\n---\n\n${userMessage}`;
     const parts = tokenizeCli(cli);
@@ -128,14 +239,34 @@ function invokeCli(cli: string, systemPrompt: string, userMessage: string): Prom
       res({ status: 1, stdout: '', stderr: 'tokenized cli is empty' });
       return;
     }
-    const child = spawn(parts[0], parts.slice(1), { stdio: ['pipe', 'pipe', 'pipe'] });
+    // 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), {
+      stdio: ['pipe', 'pipe', 'pipe'],
+      detached: true,
+      env: { ...process.env, CROSSTALK_DISPATCH_ACTOR: actorName },
+    });
     let stdout = '';
     let stderr = '';
     let resolved = false;
     const timeout = setTimeout(() => {
       if (resolved) return;
       resolved = true;
-      child.kill('SIGKILL');
+      // 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');
+        }
+      } catch {
+        try { child.kill('SIGKILL'); } catch { /* already dead */ }
+      }
       res({ status: 124, stdout, stderr: stderr + '\n[timeout]' });
     }, 5 * 60_000);
     child.stdout.on('data', (d) => { stdout += d.toString(); });
@@ -168,14 +299,19 @@ function invokeCli(cli: string, systemPrompt: string, userMessage: string): Prom
 function writeReply(
   channelUuid: string,
   fromActor: string,
-  toActor: string,
+  toActor: 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', timestamp: ts.iso },
+    { from: fromActor, to: toActor, type: 'text', kind: 'result', timestamp: ts.iso },
     body,
   );
   writeFileSync(join(dir, messageFilename(ts)), content);
@@ -200,16 +336,76 @@ function writeReadReceipt(
 interface PendingDispatch {
   actorName: string;
   channelUuid: string;
-  msg: ChannelMessage;
-  from: 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];
+  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}` : ''}) ---`);
+    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;
+}
+
 async function dispatchOne(p: PendingDispatch): Promise<boolean> {
-  // Resolve CLI per-message — message frontmatter may request a specific
-  // tier via `tier: <name>`. Falls back to first declared tier.
-  const preferredTier = typeof p.msg.data['tier'] === 'string'
-    ? (p.msg.data['tier'] as string)
+  // 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 {
@@ -232,11 +428,17 @@ async function dispatchOne(p: PendingDispatch): Promise<boolean> {
     return false;
   }
   const cli = resolved.cli;
-  if (isQuarantined(transportRoot, 'dispatch', p.actorName, p.channelUuid, p.msg.relPath)) {
+
+  // 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)) {
     log('dispatch_skipped_quarantined', {
       actor: p.actorName,
       channel: p.channelUuid.slice(0, 8),
-      msg: p.msg.relPath,
+      msg: lastMsg.relPath,
     });
     return false;
   }
@@ -244,10 +446,17 @@ async function dispatchOne(p: PendingDispatch): Promise<boolean> {
   log('dispatch', {
     actor: p.actorName,
     channel: p.channelUuid.slice(0, 8),
-    msg: p.msg.relPath,
+    batch_size: p.msgs.length,
+    first_msg: firstMsg.relPath,
+    last_msg: lastMsg.relPath,
   });
 
-  writeReadReceipt(p.channelUuid, p.actorName, p.from, p.msg.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 {
@@ -271,7 +480,8 @@ async function dispatchOne(p: PendingDispatch): Promise<boolean> {
   }
 
   const systemPrompt = composeSystemPrompt(profile.systemPrompt);
-  const result = await invokeCli(cli, systemPrompt, p.msg.body);
+  const userMessage = formatBatchedUserMessage(p.msgs);
+  const result = await invokeCli(cli, systemPrompt, userMessage, p.actorName);
 
   if (result.status !== 0) {
     const r = writeDlqEntry(
@@ -279,12 +489,13 @@ async function dispatchOne(p: PendingDispatch): Promise<boolean> {
       'dispatch',
       p.actorName,
       p.channelUuid,
-      p.msg.relPath,
+      lastMsg.relPath,
       `cli exit=${result.status}\n${result.stderr.slice(0, 1000)}`,
     );
     log('dispatch_failed', {
       actor: p.actorName,
       channel: p.channelUuid.slice(0, 8),
+      batch_size: p.msgs.length,
       dlq_id: r.id,
       attempts: r.attempts,
       quarantined: r.quarantined,
@@ -295,12 +506,25 @@ 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,
-      p.msg.relPath,
+      lastMsg.relPath,
       'cli returned empty reply',
     );
     log('dispatch_empty_reply', {
@@ -313,7 +537,14 @@ async function dispatchOne(p: PendingDispatch): Promise<boolean> {
     return false;
   }
 
-  writeReply(p.channelUuid, p.actorName, p.from, reply);
+  // 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);
   return true;
 }
 
@@ -330,8 +561,13 @@ async function dispatchTick(): Promise<TickResult> {
 
     const pullResult = gitPull(transportRoot);
     if (!pullResult.ok && pullResult.error) {
-      const errId = writeErrorLog(transportRoot, 'git_pull', pullResult.error);
-      log('git_pull_failed', { error_id: errId, error: pullResult.error.slice(0, 120) });
+      // 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;
     }
 
@@ -367,6 +603,13 @@ async function dispatchTick(): Promise<TickResult> {
       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) {
@@ -382,27 +625,50 @@ async function dispatchTick(): Promise<TickResult> {
           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';
-          if (!to.includes(actorName) || from === actorName) {
+          const msgType = typeof msg.data['type'] === 'string' ? msg.data['type'] : 'text';
+          if (!to.includes(actorName) || from === actorName || msgType === 'read') {
+            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;
           }
-          pending.push({ actorName, channelUuid, msg, from, tiers });
+          channelBatch.push(msg);
+        }
+        if (channelBatch.length > 0) {
+          const groups = splitForConcurrency(channelBatch, concurrency);
+          for (const g of groups) {
+            pending.push({ actorName, channelUuid, msgs: g, tiers });
+          }
         }
       }
 
+      // 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++) {
-          writeCursor(
-            transportRoot,
-            batch[j].actorName,
-            batch[j].channelUuid,
-            batch[j].msg.relPath,
-          );
+          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;
         }
       }
@@ -420,12 +686,14 @@ async function dispatchTick(): Promise<TickResult> {
       : `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';
-      const errId = writeErrorLog(transportRoot, kind, pushResult.error);
       log('git_push_failed', {
-        error_id: errId,
+        kind,
         committed_locally: pushResult.committed,
-        error: pushResult.error.slice(0, 120),
+        error: pushResult.error.slice(0, 200),
       });
       infraOk = false;
     }
@@ -467,7 +735,7 @@ async function waitForWakeOrTimeout(ms: number): Promise<'wake' | 'timeout'> {
 async function main(): Promise<void> {
   log('dispatch_start', {
     transport: transportRoot,
-    version: '5.0.0-alpha.3',
+    version: RUNTIME_VERSION,
     log_file: logFile ?? null,
   });
   if (onceMode) {
@@ -501,6 +769,43 @@ async function main(): Promise<void> {
         });
       }
 
+      // 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 (r.didWork) {
         await new Promise((res) => setTimeout(res, 1_000 * backoffFactor));
       } else {

package/src/send.ts

@@ -2,7 +2,7 @@ import { resolve, join } from 'path';
 import { mkdirSync, writeFileSync } from 'fs';
 import { now, messageFilename } from './filenames.js';
 import { serializeFrontmatter } from './frontmatter.js';
-import { gitCommitAndPush, writeErrorLog } from './transport.js';
+import { gitCommitAndPush } from './transport.js';
 import { withLock } from './turnq.js';
 
 const transportRoot = resolve(process.cwd());
@@ -17,17 +17,40 @@ function flag(name: string): string | undefined {
 async function main(): Promise<void> {
   const channelUuid = flag('--channel');
   const to = flag('--to');
-  const from = flag('--from') ?? 'steve';
+  // 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';
   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 body = argv[argv.length - 1];
 
   if (!channelUuid || !to || !body || body.startsWith('--')) {
     console.error(
-      'Usage: npx tsx runtime/src/send.ts --channel <uuid> --to <actor> [--from <actor>] [--tier <name>] "<message body>"',
+      'Usage: crosstalk send --channel <uuid> --to <actor> [--from <actor>] [--tier <name>] [--kind work|result] "<message body>"',
     );
     process.exit(1);
   }
 
+  if (kind !== 'work' && kind !== 'result') {
+    console.error(`Invalid --kind '${kind}'. Must be 'work' or 'result'.`);
+    process.exit(1);
+  }
+
   await withLock('dispatch', async () => {
     const ts = now();
     const dir = join(transportRoot, 'data', 'channels', channelUuid, ts.pathDate);
@@ -37,6 +60,7 @@ async function main(): Promise<void> {
       from,
       to,
       type: 'text',
+      kind,
       timestamp: ts.iso,
     };
     if (tier) frontmatter.tier = tier;
@@ -60,16 +84,19 @@ async function main(): Promise<void> {
     }
 
     if (!pushResult.ok && pushResult.error) {
-      const kind = pushResult.committed ? 'git_push' : 'git_commit';
-      const errId = writeErrorLog(transportRoot, kind, 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 === 'git_push' ? 'push' : 'commit'} FAILED (errors/${errId}.md):`,
-      );
-      console.error(`  ${pushResult.error.slice(0, 200)}`);
-      console.error(
-        '  Message is in your local clone but not on origin. Resolve the git issue and re-push manually.',
-      );
+      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);
     }
 

package/src/transport.ts

@@ -70,13 +70,40 @@ export function gitCommitAndPush(transportRoot: string, message: string): GitPus
     return { ok: true, committed: false, pushed: false };
   }
 
-  const add = captureGit(transportRoot, ['add', '-A']);
-  if (add.status !== 0) {
+  // Stage everything EXCEPT .turnq/ (machine-local runtime state; commits of
+  // this directory cause modify/delete conflicts the moment another clone
+  // untracks it via gitignore). Pathspec exclusion is independent of the
+  // transport's .gitignore — defensive against gitignore drift.
+  //
+  // Edge: `git add -A . :(exclude).turnq` exits non-zero with "The following
+  // paths are ignored by one of your .gitignore files: .turnq" because the
+  // exclude pathspec itself matches a gitignored path. The add still stages
+  // every other change correctly — only the exit code is misleading. So we
+  // treat that specific failure-pattern as benign and let the subsequent
+  // commit step decide whether anything actually got staged.
+  const add = captureGit(transportRoot, ['add', '-A', '.', ':(exclude).turnq']);
+  const addBenignIgnoredPath = add.status !== 0 &&
+                                /paths are ignored/.test(add.stderr);
+  if (add.status !== 0 && !addBenignIgnoredPath) {
     return { ok: false, committed: false, pushed: false, error: add.stderr.trim().slice(0, 500) };
   }
 
+  // If .turnq/ was previously committed (pre-alpha.4 transport), the index
+  // may still hold tracked .turnq/* entries. Untrack them here so subsequent
+  // pulls don't fight with operator clones that have untracked .turnq/. This
+  // is a one-time-per-transport heal; on a clean transport it's a no-op.
+  const indexedTurnq = captureGit(transportRoot, ['ls-files', '.turnq']);
+  if (indexedTurnq.status === 0 && indexedTurnq.stdout.trim().length > 0) {
+    captureGit(transportRoot, ['rm', '-r', '--cached', '--quiet', '.turnq']);
+  }
+
   const commit = captureGit(transportRoot, ['commit', '-m', message]);
   if (commit.status !== 0) {
+    // Empty commit ("nothing to commit") is fine — the exclusion may have
+    // dropped the only change. Treat exit-1 with no error text as no-op.
+    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) };
   }
 

package/template/upstream/PROTOCOL.md

@@ -50,17 +50,31 @@ This does NOT apply to:
 
 If you are *authoring* an actor profile for a compute role, write the system prompt to require evidence. Without that requirement, downstream validators can't distinguish shortcut results from honest ones — and shortcut results silently corrupt aggregates.
 
+### PRNG requirement for compute tasks
+
+When a compute task requires pseudo-random numbers (Monte Carlo simulations, sampling, statistical estimation, etc.), **do not pick an ad-hoc PRNG.** Many languages' default `random()` functions, naive LCGs (`a*seed + c mod m` with arbitrary constants), or homegrown XOR-shift schemes produce streams with statistical defects that bias aggregates — particularly when multiple instances run with adjacent seeds and produce correlated streams.
+
+Use one of these:
+
+- **JavaScript/Node:** `mulberry32(seed)` (one canonical implementation: `function mulberry32(a){return function(){a|=0;a=a+0x6D2B79F5|0;var t=Math.imul(a^a>>>15,1|a);t=t+Math.imul(t^t>>>7,61|t)^t;return((t^t>>>14)>>>0)/4294967296}}`). Derive distinct seeds per instance via a large multiplier (e.g., `instance_index * 1000003`) to decorrelate streams.
+- **Python:** `random.Random(seed)` (per-instance instance, NOT the module-level `random.random`). For higher-quality requirements use `secrets.SystemRandom()` or `numpy.random.Generator(np.random.PCG64(seed))`.
+- **Other:** any well-documented passing-Big-Crush PRNG (PCG, xoshiro256++, ChaCha20-based, etc.) with explicit seeding.
+
+If you are unsure, ask. Better to ask once than to pollute an aggregate with biased samples.
+
 **Worked example from this protocol's UAT.** 10 junior-developer instances were given "throw 100M darts" with a loose prompt. 7 ran the canonical Monte Carlo loop and produced statistically clean results. 1 produced an estimate 633σ from the expected mean — almost certainly a shortcut. 2 others produced identical wrong values, suggesting a shared shortcut path. When the same 10 were re-prompted with "show your code" plus literal pseudocode, all 10 produced canonical implementations and clean results. The senior validator caught the original outlier; without it, the aggregate would have been silently corrupted.
 
+**Second UAT worked example (PRNG-quality).** A subsequent 10-junior fan-out without PRNG guidance got 5/10 valid: instance 1 used a 16-bit-truncated LCG (π≈3.032, badly broken); instances 2/5/8 picked the same `a=1103515245 / 0x7fffffff` LCG and produced **identical** inside-counts from adjacent seeds (correlated streams); instance 9 picked a third biased option. After moving the PRNG requirement into the spec, the same 10-junior fan-out hit 10/10 valid (every instance used the prescribed mulberry32 with the prescribed seed formula). This is why this section exists.
+
 ## Available tools
 
-You have shell access. You can invoke these tools any time you decide they help with your reply. All of them run from the transport root (the current working directory). The tools are documented here so you can pick the right one from natural-language intent — e.g. "check what the dispatch state looks like" → `npm run status`.
+You have shell access. You can invoke these tools any time you decide they help with your reply. All of them run from the transport root (the current working directory). The tools are documented here so you can pick the right one from natural-language intent — e.g. "check what the dispatch state looks like" → `crosstalk status`.
 
 ### `send` — initiate a message to another actor
 
 Use this when you want to **proactively** message someone, not just reply to the prompt you're processing. (If you only want to reply to what you received, just answer — do not call `send`.)
 
-    npm run send -- --channel <channel-uuid> --to <actor> [--from <your-name>] [--tier <tier-name>] "<message body>"
+    crosstalk send --channel <channel-uuid> --to <actor> [--from <your-name>] [--tier <tier-name>] "<message body>"
 
 `send` also pokes dispatch to tick immediately so the recipient sees the message right away.
 
@@ -70,13 +84,13 @@ Use this when you want to **proactively** message someone, not just reply to the
 
 Use this to bypass the quiet-poll interval. Rarely needed manually — `send` already pokes dispatch automatically. Use this if you've directly written a message file and want dispatch to notice it now.
 
-    npm run wake
+    crosstalk wake
 
 ### `status` — inspect transport state
 
 Use this when an operator asks "what's happening?" or before deciding whether to retry something.
 
-    npm run status
+    crosstalk status
 
 Outputs: host file summary, per-actor cursors, turnq lock state, channel list with message counts, DLQ entry count.
 
@@ -89,24 +103,24 @@ Use this when you want to inspect or retry failures. DLQ entries have one of two
 
 Entries also carry an `attempts` count and a `quarantined: true|false` flag. If the same failure repeats 4+ times within an hour, the entry is quarantined: dispatch starts skipping that message (for `dispatch` kind) or that actor (for `config` kind). The retry command clears the quarantine and lets the next dispatch tick try again.
 
-    npm run dlq                       # same as --list
-    npm run dlq -- --list             # list all DLQ entries (incl. quarantine markers + counts by kind)
-    npm run dlq -- --show <id>        # show full details of one entry
-    npm run dlq -- --retry <id>       # for dispatch: rewind cursor; for config: clear quarantine
-    npm run dlq -- --clear            # delete all entries (destructive)
+    crosstalk dlq                       # same as --list
+    crosstalk dlq --list             # list all DLQ entries (incl. quarantine markers + counts by kind)
+    crosstalk dlq --show <id>        # show full details of one entry
+    crosstalk dlq --retry <id>       # for dispatch: rewind cursor; for config: clear quarantine
+    crosstalk dlq --clear            # delete all entries (destructive)
 
 ### `init` — scaffold a new transport
 
 Use this only when an operator is setting up a fresh transport directory. Creates a default host file (for the current hostname), a `general` channel, and the empty `custom/actors/`, `cursors/`, and `dlq/` directories.
 
-    npm run init
-    npm run init -- --force          # overwrite existing files
+    crosstalk init
+    crosstalk init --force          # overwrite existing files
 
 ### `channel` — create a new channel or subchannel
 
 Use this when you want to spin up a new conversation space — either a top-level channel or a focused subchannel of an existing one. Generates a UUID and writes `data/channels/<uuid>/CHANNEL.md`.
 
-    npm run channel -- --name <name> [--parent <parent-uuid>] [--created-by <name>]
+    crosstalk channel --name <name> [--parent <parent-uuid>] [--created-by <name>]
 
 Prints the new channel UUID. Use that UUID in subsequent `send` calls.
 
@@ -130,6 +144,51 @@ Subchannels exist for focused work — a channel with a `parent:` field in its `
 
 When dispatch processes your message, it writes a `type: read` receipt before invoking you and a `type: text` reply after you respond. You only ever produce the text reply — the read receipt is the runtime's signal that a message was claimed. You can rely on read receipts when reasoning about whether a previous message was actually processed.
 
+Read receipts do NOT themselves trigger a dispatch. They are bookkeeping artefacts; the runtime filters them out of the dispatch scan so a receipt addressed to you will not wake you. If you want a peer to act on something, send a `type: text` message via `crosstalk send`.
+
+## Batched delivery
+
+When the runtime activates you, it hands you **all** the unread messages addressed to you in the same channel — not one at a time. If there are N pending messages, you'll see one prompt containing all N, prefixed by `--- Message K of N (from: ..., ref: ...) ---` delimiters. Process them collectively and emit a single reply that addresses the batch.
+
+This is the mailbox semantics aggregating actors depend on: a coordinator that fans out to 10 peers wakes once after all 10 reply, sees all 10 results in one prompt, and dispatches the aggregator exactly once. Same actor model as Erlang / Akka — one activation drains the mailbox.
+
+If your work for the batch is fully routed via `crosstalk send` (e.g. you forwarded results to an aggregator) and you have nothing further to say, you may leave stdout empty — for multi-message batches this is treated as success, not a DLQ entry. For a single-message dispatch, empty stdout remains a protocol violation (you were addressed; respond).
+
+## Message kinds
+
+Every message carries a `kind:` field describing its purpose. Two kinds are defined:
+
+| Kind | Meaning | Wakes recipient? |
+|---|---|---|
+| `work` | A task. Recipient is being asked to act. | **Always.** |
+| `result` | The output of work. Informational. | **Iff reply-causal** — the recipient previously sent the sender a `kind: work` in this channel. |
+
+Plus `type: read` (receipts; never wake — already documented above).
+
+**The kind is RUNTIME-INFERRED, not authoritative as declared.** When the dispatcher considers waking an actor on a message, it does not trust the declared `kind:` field directly. Instead, it computes the *effective* kind from the channel's interaction graph: if some earlier message in the channel was sent FROM one of this message's recipients TO this message's sender with declared kind `work`, then this message is *causally a reply* and is treated as `kind: result` regardless of how it was labelled. Only genuine unsolicited messages (no prior opposite-direction work) are treated as `work`.
+
+This is the load-bearing principle of the dispatch layer: **the runtime derives message semantics from the interaction graph; it never trusts an actor's declaration.** Actors are fallible declarers — LLMs given two valid reply paths (stdout vs. `crosstalk send`) pick between them probabilistically, and `crosstalk send`'s `--kind work` default is the wrong tag when the actor is using `send` to reply. Inferring kind structurally neutralizes mislabels at the dispatcher level so a fan-in peer mis-tagging its reply can't forge a wake-up loop.
+
+**Reply causality:** a `kind: result` (declared or inferred) wakes its addressee **only if** the addressee previously sent a `kind: work` (effective kind) to the result's sender in the same channel. Replies wake the asker. If you never asked, a result addressed to you is informational and the runtime will not activate you on it.
+
+This is what stops fan-in patterns from oscillating. When a coordinator processes a batch of N peer results and emits a stdout reply, the runtime auto-addresses that reply to the peers — but none of them woke the coordinator with a `work`, so the reply doesn't wake them back. Loop closed at the dispatcher level, no actor profile heroics required.
+
+**Defaults:**
+- `crosstalk send` without `--kind` produces `kind: work` (proactive dispatches are tasks).
+- Runtime auto-replies from stdout are `kind: result` (the actor is answering, not initiating).
+- Override either with `crosstalk send --kind work` or `--kind result`.
+
+Because kind is runtime-inferred, getting the declared field "wrong" rarely hurts — the effective-kind computation usually fixes it. But declaring it correctly still helps log readability and DLQ diagnostics, and remains the right thing to do.
+
+**Backwards compat:** legacy messages without a `kind:` field are treated as `kind: work` declared; effective-kind inference still applies. Existing transports continue to function; older history doesn't need to be re-tagged.
+
+**When to use which (still useful as intent, even if non-load-bearing):**
+- Dispatching a peer to do something → `--kind work` (or omit; default).
+- Forwarding finished output to whoever asked (operator, aggregator) → `--kind result` (or rely on the stdout auto-reply).
+- Broadcasting an FYI you don't want peers to act on → `--kind result` addressed to peers who never asked you for work; they won't wake.
+
+**Known v1 limitation:** the causality scan is conservative on multi-recipient `to:` lists — if ANY recipient previously tasked the sender, the message is treated as causally a reply for ALL recipients. In practice the per-addressee causality check (only the actual asker wakes on a result) compensates correctly. The edge case worth knowing: genuine multi-recipient fan-out where one recipient happens to have prior unrelated work to the sender will suppress wakes for the other recipients. Not observed in Monte Carlo; revisit if it surfaces in a real topology.
+
 ## Other actors
 
 - Host files at `hosts/<alias>.md` declare which actors run on which machines.
@@ -146,7 +205,7 @@ There are two persistent failure logs in the transport:
 - **`dlq/`** — failed dispatches and config errors. Per-message and per-actor. Use the `dlq` tool to inspect/retry.
 - **`errors/`** — infrastructure failures (git pull/push/commit, filesystem, message parse). Deduped by signature with a `count` field. If you see something not working as expected (replies aren't reaching origin, dispatch keeps reporting `skip_tick_locked`, etc.), check this directory — operator hostile state often surfaces here first.
 
-`npm run status` shows counts for both at a glance, plus a **dispatch heartbeat** line — the timestamp of the most recent tick. If the heartbeat is fresh (under 2 min old), dispatch is running. If stale (over 5 min), dispatch has stopped or hung; check `errors/` and the process state.
+`crosstalk status` shows counts for both at a glance, plus a **dispatch heartbeat** line — the timestamp of the most recent tick. If the heartbeat is fresh (under 2 min old), dispatch is running. If stale (over 5 min), dispatch has stopped or hung; check `errors/` and the process state.
 
 **Persistent infrastructure failures trigger exponential backoff.** After 2+ consecutive ticks with failed git pull or push, dispatch doubles its poll interval each tick, capped at 10× the configured quiet poll. The `backoff_active` log event fires when active; `backoff_cleared` fires when a tick succeeds again.
 
@@ -177,4 +236,4 @@ For idempotent work (information lookup, calculation, advice), duplicates are ha
 - **Do not modify `errors/` directly.** Same reasoning — entries are deduped by signature and the count field matters.
 - **Do not modify `.turnq/`.** That holds turnq lock state.
 - **Do not reply to messages addressed to other actors.** You only act on messages where the `to:` field includes your name.
-- **Do not fabricate channel UUIDs.** Look at existing directories under `data/channels/` to find real ones — or run `npm run status` to list them.
+- **Do not fabricate channel UUIDs.** Look at existing directories under `data/channels/` to find real ones — or run `crosstalk status` to list them.

package/template/upstream/actors/concierge.md

@@ -103,3 +103,23 @@ You receive requests from any participant — human or machine — and act on th
    - **Empty hosts directory:** if `manifest/hosts/` is absent or empty, proceed normally — routing table is empty, use bare actor names only.
 
 You do not write production code. You do not make architectural decisions.
+
+**Orchestration termination — this is load-bearing.** When your job in a given dispatch is to ROUTE work (fan-out to specialists, forward replies, dispatch follow-ups), the right pattern is:
+
+1. Read the incoming message and decide what to dispatch.
+2. Write the dispatch messages via `crosstalk send` (one per recipient).
+3. Write a short stdout reply to the original sender confirming what you dispatched (e.g. "dispatched 10 Monte Carlo runs to junior-developer; will forward aggregation when results arrive").
+4. **EXIT immediately. Do NOT poll the channel waiting for replies.** Do NOT loop reading messages "until the work is done." The runtime re-dispatches you the moment any new message addresses you. Your job in any single dispatch is one turn of work, not a long-running orchestration loop.
+
+If you stay alive after step 3 — polling, waiting, "checking back" — you burn the dispatch wall-clock budget until SIGKILL fires at the timeout. That looks like a hang to the operator and pollutes the DLQ even though your useful work already landed. Exit promptly.
+
+When the peers reply, the runtime dispatches you a NEW turn. Use THAT turn to read replies and continue the work. Each step is its own dispatch. You don't have to keep state in memory across them — the channel IS the state.
+
+**Routing topology — do not fragment fan-outs into subchannels or chain replies through other actors.** When you orchestrate N peers, hold this shape:
+
+- **Same channel.** Dispatch all N peers in the SAME channel as the original request. The runtime routes by `to:` field; you do not need a subchannel for isolation. Subchannels are for the operator's narrative organization (e.g. "weekly planning", "incident review"), not for orchestration topology. Creating a fan-out subchannel makes the cursor space sprawl and complicates aggregation.
+- **Peers reply to YOU, not to downstream consumers.** When you dispatch peers, include explicit reply-to guidance in each message body (e.g. "reply to concierge with your result; do NOT send your result to any other actor"). You are the collection point. If peers also send copies to a downstream aggregator, that aggregator will be re-dispatched once per peer message — wasting calls and producing redundant aggregations.
+- **Aggregate exactly once.** Wait until you've seen all N peer replies (across however many subsequent dispatches that takes; you can count by scanning the channel for messages from each peer addressed to you). Only THEN dispatch the aggregator (e.g. senior-software-engineer) in a SINGLE message containing the collected results. Never N messages, never one per peer reply.
+- **Forward the aggregator's final reply to the operator — explicitly, via `crosstalk send`.** When the aggregator replies to you, your stdout auto-reply goes back to the *aggregator*, NOT to the operator — so a stdout-only response means the operator never sees the answer. On the dispatch turn where you read the aggregator's final reply you MUST run `crosstalk send --to <original-requester> --kind result "<the aggregator's final answer, quoted in full>"` so the operator actually receives it. The original requester is the `from:` of the kickoff message that started this orchestration (e.g. `steve`). Do this, then exit. Delivering the final only as a reply to the aggregator is an orchestration failure — the operator asked the question and must get the answer.
+
+If you find yourself dispatching the aggregator multiple times for a single orchestration task, you have the topology wrong — peers must reply to you, you must collect, and you must dispatch the aggregator exactly once.