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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cordfuse/crosstalk",
-  "version": "5.0.0-alpha.6",
+  "version": "5.0.0-alpha.7",
   "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,59 @@ function recipients(toField: unknown): string[] {
   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.
@@ -153,10 +206,23 @@ function isCausalReply(channelMessages: ChannelMessage[], msg: ChannelMessage):
   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'] : '';
-    if (!toList.includes(mFrom)) continue;
+    // 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 (recipients(m.data['to']).includes(sender)) return true;
+    if (namesActor(recipients(m.data['to']), sender)) return true;
   }
   return false;
 }
@@ -197,10 +263,15 @@ function hasPriorWork(
 ): 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 (toList.includes(sender)) return true;
+    if (namesActor(toList, sender)) return true;
   }
   return false;
 }
@@ -630,7 +701,27 @@ async function dispatchTick(): Promise<TickResult> {
           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';
-          if (!to.includes(actorName) || from === actorName || msgType === 'read') {
+          // 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;
           }

package/template/upstream/PROTOCOL.md

@@ -66,6 +66,14 @@ If you are unsure, ask. Better to ask once than to pollute an aggregate with bia
 
 **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.
 
+### Echo assigned identifiers verbatim
+
+If an orchestrator assigns you an identifier — instance number, seed value, task token, anything specific — **echo it back exactly as given.** Do not paraphrase, renumber, substitute, or pick your own. If you were asked to be instance 8 with seed 8000024, your reply names instance 8 with seed 8000024.
+
+This rule is for *your* honesty about your own identity. **The orchestrator does not depend on it.** Concierge (and any other orchestrator) reconciles fan-in by the relPath of the dispatched work message, not by what you write in your body — so a lie about your identifier doesn't break the system; it just makes the log harder to read and you look like an unreliable peer. The runtime is robust to peer mislabeling by design (the alpha.7 multi-host harness verified this), but reliable peers cost less to debug.
+
+If you genuinely cannot tell what your assigned identifier was (e.g. the orchestrator's prompt was ambiguous), say so explicitly rather than invent one. Inventing an identifier and hoping the orchestrator sorts it out is the worst case.
+
 ## 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`.
@@ -198,6 +206,19 @@ Because kind is runtime-inferred, getting the declared field "wrong" rarely hurt
 
 A host file can declare `count: N` under an actor's tier. That means the dispatch loop may spawn up to N concurrent CLI invocations of that actor per tick — useful for fan-out workloads (e.g. 10 junior-developer instances processing 10 separate messages in parallel). You behave the same regardless of which slot you occupy.
 
+## Host-aware routing
+
+When the transport is shared by multiple dispatchers on different hosts (each running its own `hosts/<alias>.md` declaration), the `to:` field accepts two forms:
+
+- **Bare actor name** — `to: junior-developer`. Broadcast to every host whose host file declares this actor. Every matching dispatcher will wake an instance on every such message.
+- **Actor@host** — `to: junior-developer@cachy`. Narrowed to the named host only. Only the dispatcher whose host file's `alias:` equals `cachy` will wake an instance; others see the message addressed to a different host and skip it.
+
+The runtime parses recipients by splitting on `@` — the part before is the actor name, the part after (if present) is the target host alias. Causality scans (the `effectiveKind` / `hasPriorWork` activation logic) ignore the host suffix; only the actual addressing decision honors it.
+
+If a dispatcher sees a message that names its actor but targets a different host, it logs `host_routing_mismatch` with the recipient list, this host alias, and the message path — so silent wrong-host drops are surfaced rather than disappearing without trace.
+
+**When to use which.** Use bare names for stateless work-pool patterns where any matching host is fine. Use `@host` when the orchestration depends on which machine runs the work (resource locality, host-specific state, validating cross-host behavior). Profile authors orchestrating fan-out across hosts should prefer `@host` so the topology is explicit in the message frontmatter.
+
 ## Failure handling and where to look
 
 There are two persistent failure logs in the transport:

package/template/upstream/actors/concierge.md

@@ -119,7 +119,12 @@ When the peers reply, the runtime dispatches you a NEW turn. Use THAT turn to re
 
 - **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.
+- **Aggregate exactly once — reconcile by dispatched message identity, never by what the peer says.** Wait until you've received N replies, 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. **How you count "N replies" is load-bearing:**
+   - **Track the relPaths of the N work messages YOU dispatched.** When you call `crosstalk send --to <peer> --kind work ...` the tool prints `Sent: <relPath>` — those relPaths (e.g. `2026/06/09/123802614Z-5a16ec07.md`) are your dispatched-identity set. Scan the channel directory for them so you have a precise list of what you asked for.
+   - **Count replies by causal predecessor, not by peer-reported content.** A "reply to dispatch X" is a `kind: text` message from one of X's recipients (host-agnostic match — `junior-developer` matches `to: junior-developer@cachy`) addressed back to you, and landing AFTER X in `relPath` order. The runtime's reply-causality fix from alpha.6 enforces this same notion at the activation level — you're applying the same reasoning at the application level.
+   - **Do NOT count by peer-reported seed, instance number, content fingerprint, or any other identifier the peer wrote in its body.** LLM peers will lie — they will report seeds you didn't assign, claim to be instance 8 while computing for seed 7000021, or echo what they think you wanted to hear. *"Would this still work if every peer lied about what it is?"* Yes — when reconciliation is by your dispatched relPath, not by what the peer claims about itself.
+   - **A peer that sends multiple replies counts as one** if you only dispatched it one work message — pick its latest causally-paired reply and discard the rest. The runtime can't dedupe these for you; you must.
+   - When the dispatched-relPath set is fully covered (every dispatched relPath has at least one causally-paired reply), aggregate. Until then, this dispatch's job is "wait" — exit and let the runtime re-dispatch you when more replies land.
 - **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.