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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cordfuse/crosstalk",
-  "version": "5.0.0-alpha.5",
+  "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/dispatch.ts

@@ -124,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)
@@ -145,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);
@@ -153,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(); });
@@ -193,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);
@@ -225,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 {
@@ -257,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;
   }
@@ -269,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 {
@@ -296,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(
@@ -304,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,
@@ -320,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', {
@@ -338,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;
 }
 
@@ -397,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) {
@@ -412,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;
         }
       }

package/src/send.ts

@@ -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;

package/template/upstream/PROTOCOL.md

@@ -50,8 +50,22 @@ 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" → `crosstalk status`.
@@ -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.

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.