@cordfuse/crosstalk 6.0.0-alpha.1 → 6.0.0-alpha.3

package/bin/crosstalk.js

@@ -9,12 +9,12 @@
 
 import { existsSync, statSync } from 'fs';
 import { resolve, join, dirname } from 'path';
-import { spawnSync } from 'child_process';
+import { spawnSync, spawn } from 'child_process';
 import { fileURLToPath } from 'url';
 import { createRequire } from 'module';
 
 const SUBCOMMANDS = [
-  'dispatch', 'send', 'replies', 'wake', 'status', 'init', 'dlq', 'channel',
+  'dispatch', 'stop', 'send', 'replies', 'wake', 'status', 'init', 'dlq', 'channel',
   'chat', 'open', 'attach', 'upgrade',
 ];
 const STANDALONE_SUBCOMMANDS = new Set(['init']);
@@ -75,8 +75,23 @@ if (!STANDALONE_SUBCOMMANDS.has(cmd)) {
 
 const require = createRequire(import.meta.url);
 const tsxCli = require.resolve('tsx/cli');
-const r = spawnSync(process.execPath, [tsxCli, srcFile, ...argv.slice(1)], {
-  cwd,
-  stdio: 'inherit',
-});
-process.exit(r.status ?? 1);
+
+// dispatch is long-running: use async spawn so SIGTERM/SIGINT forwarded to
+// the tsx child kills the whole chain cleanly. All other subcommands are
+// short-lived and spawnSync is fine.
+if (cmd === 'dispatch') {
+  const child = spawn(process.execPath, [tsxCli, srcFile, ...argv.slice(1)], {
+    cwd,
+    stdio: 'inherit',
+  });
+  const forward = (sig) => { try { child.kill(sig); } catch {} };
+  process.on('SIGTERM', () => forward('SIGTERM'));
+  process.on('SIGINT',  () => forward('SIGTERM'));
+  child.on('exit', (code, signal) => process.exit(signal ? 1 : (code ?? 0)));
+} else {
+  const r = spawnSync(process.execPath, [tsxCli, srcFile, ...argv.slice(1)], {
+    cwd,
+    stdio: 'inherit',
+  });
+  process.exit(r.status ?? 1);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cordfuse/crosstalk",
-  "version": "6.0.0-alpha.1",
+  "version": "6.0.0-alpha.3",
   "description": "Crosstalk runtime — async messaging between agents over git, across machines.",
   "type": "module",
   "license": "MIT",
@@ -20,7 +20,9 @@
   "scripts": {
     "build": "tsc --noEmit",
     "lint": "tsc --noEmit",
-    "test": "bun test"
+    "test": "bun test",
+    "prepack": "cp -r ../transport template",
+    "postpack": "rm -rf template"
   },
   "dependencies": {
     "@cordfuse/turnq": "^0.4.1",

package/src/dispatch.ts

@@ -36,6 +36,8 @@ import {
   readCursor,
   writeCursor,
   writeHeartbeat,
+  writePidfile,
+  removePidfile,
   logError,
 } from './state.js';
 import { recipients, reList, decideWake, splitForConcurrency } from './activation.js';
@@ -289,6 +291,7 @@ async function dispatchOne(p: PendingDispatch): Promise<boolean> {
     // auto-links re:). If it truly did nothing, the asker's `crosstalk
     // replies` stays PENDING — visible, not silently lost.
     log('dispatch_silent', { actor: p.actorName, channel: p.channelUuid.slice(0, 8), batch_size: p.msgs.length });
+    log('dispatch_done', { actor: p.actorName, channel: p.channelUuid.slice(0, 8), batch_size: p.msgs.length, replied: false });
     return true;
   }
 
@@ -305,6 +308,7 @@ async function dispatchOne(p: PendingDispatch): Promise<boolean> {
   for (const [sender, relPaths] of bySender) {
     writeReply(p.channelUuid, p.actorName, sender, relPaths.length === 1 ? relPaths[0]! : relPaths, reply);
   }
+  log('dispatch_done', { actor: p.actorName, channel: p.channelUuid.slice(0, 8), batch_size: p.msgs.length, replied: true });
   return true;
 }
 
@@ -360,26 +364,32 @@ async function dispatchTick(): Promise<TickResult> {
       const cursor = readCursor(transportRoot, actorName, channelUuid);
       if (cursor === head) continue;
 
+      // First encounter: seed to HEAD so only future messages are dispatched.
+      // Without this, a null cursor falls through to `post = messages` and
+      // replays the full channel history on every fresh-state boot.
+      if (cursor === null) {
+        writeCursor(transportRoot, actorName, channelUuid, head);
+        continue;
+      }
+
       const messages = listChannelMessages(transportRoot, channelUuid);
       const senderByRelPath = new Map(messages.map((m) => [m.relPath, messageSender(m)]));
       const senderOf = (relPath: string) => senderByRelPath.get(relPath);
 
-      let post = messages;
-      if (cursor) {
-        let added = addedSince.get(cursor);
-        if (added === undefined) {
-          const files = newFilesSince(transportRoot, cursor);
-          added = files === null ? null : new Set(files);
-          addedSince.set(cursor, added);
-          if (added === null) {
-            logError(transportRoot, 'other', `cursor commit ${cursor.slice(0, 12)} unknown to this clone — full channel re-scan`);
-          }
-        }
-        if (added !== null) {
-          const prefix = `data/channels/${channelUuid}/`;
-          post = messages.filter((m) => added.has(prefix + m.relPath));
+      let added = addedSince.get(cursor);
+      if (added === undefined) {
+        const files = newFilesSince(transportRoot, cursor);
+        added = files === null ? null : new Set(files);
+        addedSince.set(cursor, added);
+        if (added === null) {
+          logError(transportRoot, 'other', `cursor commit ${cursor.slice(0, 12)} unknown to this clone — full channel re-scan`);
         }
       }
+      let post = messages;
+      if (added !== null) {
+        const prefix = `data/channels/${channelUuid}/`;
+        post = messages.filter((m) => added.has(prefix + m.relPath));
+      }
       if (post.length === 0) {
         writeCursor(transportRoot, actorName, channelUuid, head);
         continue;
@@ -466,6 +476,12 @@ async function waitForWakeOrTimeout(ms: number): Promise<void> {
 }
 
 async function main(): Promise<void> {
+  writePidfile(transportRoot);
+  const cleanup = () => removePidfile(transportRoot);
+  process.on('exit', cleanup);
+  process.on('SIGTERM', () => { cleanup(); process.exit(0); });
+  process.on('SIGINT',  () => { cleanup(); process.exit(0); });
+
   log('dispatch_start', { transport: transportRoot, version: RUNTIME_VERSION, state_dir: stateDir(transportRoot) });
   if (onceMode) {
     await dispatchTick();

package/src/send.ts

@@ -11,7 +11,7 @@ import { resolve, join } from 'path';
 import { mkdirSync, writeFileSync } from 'fs';
 import { now, messageFilename } from './filenames.js';
 import { serializeFrontmatter } from './frontmatter.js';
-import { gitCommitAndPush } from './transport.js';
+import { gitCommitAndPush, discoverChannels } from './transport.js';
 import { withLock } from './turnq.js';
 import { sendWakeSignal } from './state.js';
 
@@ -25,7 +25,7 @@ function flag(name: string): string | undefined {
 }
 
 async function main(): Promise<void> {
-  const channelUuid = flag('--channel') ?? process.env['CROSSTALK_DISPATCH_CHANNEL'];
+  let channelUuid = flag('--channel') ?? process.env['CROSSTALK_DISPATCH_CHANNEL'];
   const to = flag('--to');
   const from = flag('--from')
     ?? process.env['CROSSTALK_DISPATCH_ACTOR']
@@ -35,13 +35,27 @@ async function main(): Promise<void> {
   const isNew = argv.includes('--new');
   const body = argv[argv.length - 1];
 
-  if (!channelUuid || !to || !body || body.startsWith('--')) {
+  if (!to || !body || body.startsWith('--')) {
     console.error(
       'Usage: crosstalk send --to <actor[,actor...]> [--channel <uuid>] [--from <actor>] [--tier <name>] [--new] "<message body>"',
     );
     process.exit(1);
   }
 
+  if (!channelUuid) {
+    const channels = discoverChannels(transportRoot);
+    if (channels.length === 1) {
+      channelUuid = channels[0]!;
+    } else if (channels.length === 0) {
+      console.error('crosstalk send: no channels found. Create one with: crosstalk channel create <name>');
+      process.exit(1);
+    } else {
+      console.error(`crosstalk send: multiple channels found — specify one with --channel <uuid>`);
+      console.error(`  Run 'crosstalk status' to list channel UUIDs.`);
+      process.exit(1);
+    }
+  }
+
   const reTargets = (isNew ? '' : process.env['CROSSTALK_DISPATCH_RE'] ?? '')
     .split(',')
     .map((s) => s.trim())
@@ -77,7 +91,7 @@ async function main(): Promise<void> {
     console.error(`but git ${pushResult.committed ? 'push' : 'commit'} FAILED:`);
     console.error(`  ${pushResult.error.slice(0, 300)}`);
     console.error('\nYour message is in the local clone but not on origin. Recover with:');
-    console.error('  git pull --rebase && git push');
+    console.error('  git fetch origin && git rebase origin/main && git push');
     process.exit(3);
   }
 

package/src/state.ts

@@ -8,6 +8,7 @@
 //   dlq/<id>.md                        — failed-dispatch entries
 //   errors.log                         — infra failures, JSONL, append-only
 //   heartbeat                          — last tick timestamp + pid + version
+//   dispatcher.pid                     — PID of the running dispatcher process
 //   wake.signal                        — touched to wake the dispatch loop
 //
 // Location: $CROSSTALK_STATE_DIR if set (exact dir — container-friendly),
@@ -19,6 +20,7 @@ import {
   mkdirSync,
   readFileSync,
   writeFileSync,
+  unlinkSync,
   appendFileSync,
 } from 'fs';
 import { join, dirname } from 'path';
@@ -95,6 +97,34 @@ export function writeCursor(
   writeFileSync(p, commit + '\n');
 }
 
+// ── pidfile ──
+
+export function pidfilePath(transportRoot: string): string {
+  return join(stateDir(transportRoot), 'dispatcher.pid');
+}
+
+export function writePidfile(transportRoot: string): void {
+  try {
+    writeFileSync(pidfilePath(transportRoot), `${process.pid}\n`);
+  } catch { /* best-effort */ }
+}
+
+export function removePidfile(transportRoot: string): void {
+  try {
+    unlinkSync(pidfilePath(transportRoot));
+  } catch { /* already gone */ }
+}
+
+export function readPidfile(transportRoot: string): number | null {
+  try {
+    const raw = readFileSync(pidfilePath(transportRoot), 'utf-8').trim();
+    const n = parseInt(raw, 10);
+    return Number.isFinite(n) && n > 0 ? n : null;
+  } catch {
+    return null;
+  }
+}
+
 // ── heartbeat + wake ──
 
 export function writeHeartbeat(transportRoot: string, version: string): void {

package/src/stop.ts

@@ -0,0 +1,37 @@
+// crosstalk stop — send SIGTERM to the running dispatcher and wait for it to exit.
+
+import { resolve } from 'path';
+import { spawnSync } from 'child_process';
+import { readPidfile, removePidfile } from './state.js';
+
+const transportRoot = resolve(process.cwd());
+
+function processRunning(pid: number): boolean {
+  try { process.kill(pid, 0); return true; } catch { return false; }
+}
+
+const pid = readPidfile(transportRoot);
+if (pid === null) {
+  console.error('crosstalk stop: no dispatcher.pid found — is dispatch running?');
+  process.exit(1);
+}
+
+if (!processRunning(pid)) {
+  console.error(`crosstalk stop: pid ${pid} is not running — removing stale pidfile`);
+  removePidfile(transportRoot);
+  process.exit(1);
+}
+
+process.kill(pid, 'SIGTERM');
+
+const deadline = Date.now() + 5_000;
+while (Date.now() < deadline) {
+  if (!processRunning(pid)) {
+    console.log(`crosstalk stop: dispatcher (pid ${pid}) stopped`);
+    process.exit(0);
+  }
+  spawnSync('sleep', ['0.1']);
+}
+
+console.error(`crosstalk stop: pid ${pid} did not exit within 5s — try: kill -9 ${pid}`);
+process.exit(1);

package/template/CLAUDE.md

@@ -0,0 +1,12 @@
+# Crosstalk transport
+
+You are inside a Crosstalk transport — a git repo that carries async
+messages between AI agents across machines.
+
+Read these before doing anything here:
+
+1. `upstream/PROTOCOL.md` — how to behave when dispatched (start here)
+2. `upstream/CROSSTALK.md` — the full protocol spec, if you need details
+
+Do not edit files under `data/` by hand — messages are written only by
+`crosstalk send` and the dispatcher.

package/template/upstream/CROSSTALK-VERSION

@@ -0,0 +1 @@
+6.0

package/template/upstream/CROSSTALK.md

@@ -0,0 +1,298 @@
+# Crosstalk
+
+Version: 6.0
+
+Crosstalk is a shared file format over git that lets humans and AI agents communicate
+asynchronously across machines. The git repository is the message bus. No special
+software is required to participate beyond git itself.
+
+Design rule for this spec: every feature must be explainable in one sentence.
+The runtime records facts at write time; it never reconstructs them by inference
+at read time.
+
+---
+
+## Participants
+
+**Humans** — operators who post messages directly or via a chat tool and read replies.
+
+**Machines** — agents (Claude, Codex, etc.) invoked by a dispatcher to process
+messages addressed to them and reply.
+
+The most common machine participant is a **worker**: `to: concierge` means
+"I need something done." The worker acts and replies. The sender may be human
+or machine; the worker does not distinguish.
+
+---
+
+## Transport layout
+
+```
+<transport>/
+  upstream/                  # runtime-managed: spec, agent orientation, defaults
+    CROSSTALK.md             #   this file
+    CROSSTALK-VERSION        #   must be exactly: 6.0
+    PROTOCOL.md              #   agent orientation prompt
+    actors/<name>.md         #   default actor profiles
+  local/                     # operator-owned: never touched by the runtime
+    actors/<name>.md         #   custom actor profiles (override upstream by name)
+  hosts/
+    <alias>.md               # one per machine running a dispatcher
+  data/
+    channels/<uuid>/
+      CHANNEL.md             # optional channel metadata
+      YYYY/MM/DD/HHMMSSmmmZ-<hex>.md   # messages
+    memories/<stamp>-<hex>.md          # shared persistent notes
+```
+
+That is the complete committed surface. **Dispatcher bookkeeping (cursors, dead-letter
+queue, error logs, lock state) is machine-local state and never lives in the repo** —
+it is kept under `$CROSSTALK_STATE_DIR` (default `~/.local/state/crosstalk/<transport-id>/`,
+where `<transport-id>` is derived from the origin URL). The repo carries conversation;
+each machine carries its own progress through it.
+
+---
+
+## Channels
+
+A channel is a UUID v4 directory under `data/channels/`. Any participant may create
+one by creating the directory and committing. An optional `CHANNEL.md` declares
+metadata:
+
+```
+---
+name: dogfood-sprint
+created_by: steve
+created_at: 2026-06-09T17:00:00.000Z
+parent: <uuid>          # optional — makes this a subchannel
+---
+
+Free-form description. Serves as a mini system prompt scoped to the channel.
+```
+
+`name` is required and unique within the transport; the other fields are optional.
+A subchannel is just a channel with a `parent:`; it reports back by posting to the
+parent channel. There is no close signal — a finished channel simply goes quiet.
+
+---
+
+## Messages
+
+Every message is a markdown file with YAML frontmatter:
+
+```
+---
+from: alice
+to: concierge
+type: text
+timestamp: 2026-06-09T19:00:00.000Z
+---
+
+Message body here.
+```
+
+### Frontmatter fields
+
+| Field | Required | Notes |
+|---|---|---|
+| `from` | yes | logical actor name — unverified; trust boundary is repo access |
+| `to` | yes | name, list of names, or `all`; may carry `@host` suffix (see Routing) |
+| `type` | yes | always `text` in 6.0 |
+| `timestamp` | yes | ISO 8601 UTC |
+| `re` | no | relPath (or list of relPaths) of the message(s) this one answers — **written by the runtime, never by hand** |
+| `tier` | no | requested model tier for the recipient (see Host files) |
+
+Readers must ignore unknown fields.
+
+### The `re:` field — causality is recorded, not inferred
+
+A message **without** `re:` is a new task. A message **with** `re:` is a reply to the
+message(s) at the listed relPath(s) (paths relative to the channel directory). Like
+`to:`, the field is a string for one target and a list for several — a reply that
+answers a batch records **every** message it answers, so batching never makes an
+answered message look unanswered.
+
+The runtime sets `re:` from facts it directly observes:
+
+- When an actor answers via stdout, the runtime writes the reply with `re:` listing
+  every message in the dispatched batch from that asker.
+- When a dispatched actor uses `crosstalk send`, the runtime injects the triggering
+  relPath(s) into the environment and `send` records them automatically. An actor can
+  suppress this (`--new`) to start genuinely new work.
+- Messages written by operators (chat tools, hand-authored) carry no `re:` — they
+  are new tasks by definition.
+
+Actors never compute or hand-write `re:`. Because the field is set by the machinery
+that already knows the answer, a confused or dishonest actor cannot mislabel a reply
+as a task or vice versa.
+
+### Filenames
+
+`data/channels/<uuid>/YYYY/MM/DD/HHMMSSmmmZ-<hex>.md` — current UTC time plus a
+hex suffix of at least 8 characters from a CSPRNG. Filenames sort chronologically
+and are collision-free by construction, so concurrent writers on different machines
+never produce git conflicts in message files.
+
+---
+
+## Activation — when does a message wake its addressee?
+
+One rule:
+
+> **A message wakes its addressee if it has no `re:` (a new task), or any `re:`
+> entry points at a message the addressee sent.**
+
+Consequences:
+
+- Tasks always wake the actor they address.
+- A reply wakes whoever asked the question, and no one else.
+- A reply addressed to someone who never asked (an FYI, a broadcast copy) is visible
+  in the channel but does not wake them — fan-in cannot oscillate.
+- Self-sent messages never wake their sender.
+
+There are no other wake conditions and no inference. The dispatcher evaluates this
+rule with two field reads.
+
+---
+
+## Delivery semantics
+
+**At-least-once.** Each dispatcher tracks a per-actor, per-channel cursor (local
+state, not in the repo) recording the git commit the channel was last scanned at —
+"new" means *added to git since that commit*, never "later filename timestamp",
+because messages reach origin in push order, not timestamp order. If a machine
+crashes mid-tick, the next tick re-dispatches anything not yet past the cursor;
+a duplicate reply may land in the channel.
+
+For idempotent work (lookups, computation, advice) duplicates are harmless. For
+non-idempotent side effects, the actor must check the channel for evidence of prior
+completion before acting. Crosstalk does not provide exactly-once semantics.
+
+**Batched delivery.** When a dispatcher wakes an actor, it hands over ALL pending
+messages addressed to that actor in that channel in a single invocation. One
+activation drains the mailbox — a coordinator that fanned out to 10 peers wakes
+once and sees all 10 replies together.
+
+The transport is an **append-only log**. No retraction, no deletion at the protocol
+level. Retention is the operator's concern at the git/storage layer.
+
+---
+
+## Actors
+
+Each participant has a profile at `local/actors/<name>.md` (operator-owned) or
+`upstream/actors/<name>.md` (defaults; `local/` wins on name collision). The body
+is the actor's system prompt.
+
+```
+---
+name: concierge
+description: "General-purpose worker and coordinator."
+---
+
+## System Prompt
+You are the general-purpose worker in this Crosstalk transport. ...
+```
+
+`name` (matching the filename stem) and `description` are required; the rest of the
+frontmatter is free. Actors are added, edited, and removed by committing files.
+
+---
+
+## Host files
+
+A host file at `hosts/<alias>.md` declares one machine running a dispatcher and the
+actors it serves. Each operator commits and maintains their own.
+
+```
+---
+alias: cachy
+hostname: steve-cachyos
+actors:
+  concierge:
+    claude: claude --print --dangerously-skip-permissions
+  junior-developer:
+    haiku:
+      cli: claude --model claude-haiku-4-5 --print --dangerously-skip-permissions
+      count: 5
+---
+```
+
+| Field | Required | Notes |
+|---|---|---|
+| `alias` | yes | the host's name in `actor@host` addressing |
+| `hostname` | no | OS hostname, used for dispatcher auto-detection |
+| `actors` | yes | actor → tier map |
+
+A **tier** is a named CLI slot. The bare-string shorthand means `count: 1`; the
+object form adds `count:` (parallel invocations) per tier. Tier names are
+operator-defined labels (`haiku`, `opus`, `flash`); senders may request one with
+the `tier:` message field, and the dispatcher falls back to the first declared
+tier when the requested one doesn't exist.
+
+On startup a dispatcher finds its own host file by matching `hostname:` (or via an
+explicit `--host <alias>` override). No match → log clearly and idle; never crash.
+
+---
+
+## Routing
+
+The `to:` field accepts:
+
+- `to: concierge` — bare name. Every host that declares the actor dispatches it.
+- `to: junior-developer@cachy` — narrowed to the host whose `alias` is `cachy`;
+  other hosts skip it (and log the skip, so wrong-host routes are visible).
+- `to: [a, b@mac]` — lists mix freely.
+- `to: all` — every participant.
+
+The actor name is everything before the `@`; the host alias is everything after.
+The `re:` activation rule ignores host suffixes — only addressing honors them.
+
+Use bare names for work-pool patterns where any machine will do; use `@host` when
+the orchestration depends on which machine runs the work. This addressing is the
+entirety of Crosstalk's multi-host model.
+
+---
+
+## Identity and trust
+
+`from:` is an unverified string. The trust boundary is repository access: anyone who
+can push can claim any name. `to:` is a routing hint, not access control — every
+message is visible to anyone with repo access. Operators who need confidentiality
+or verified identity must secure the repository itself.
+
+---
+
+## Memories
+
+Shared persistent notes any participant may read or write, at
+`data/memories/YYYYMMDDTHHMMSSmmmZ-<hex>.md`:
+
+```
+---
+from: concierge
+timestamp: 2026-06-09T19:00:00.000Z
+subject: Steve prefers TypeScript for all new tooling
+scope: global              # or a channel uuid
+supersedes: <filename>     # optional — replaces an earlier memory
+---
+
+Body.
+```
+
+When loading, skip any memory named in another memory's `supersedes:`. Agents use
+`data/memories/` instead of their model-native memory systems.
+
+---
+
+## Coordination
+
+Git is self-coordinating: filenames are collision-free and non-fast-forward pushes
+are rejected and retried with `git pull --rebase`. A transport therefore works with
+no coordinator at all.
+
+Dispatchers MAY use a turn coordinator (cordfuse/turnq) to reduce push contention —
+locally via file lock, or across hosts via a shared turnq server. Coordination is
+**advisory**: a dispatcher waits for its turn with a bounded timeout and proceeds
+anyway on timeout or coordinator failure, letting git arbitrate. A coordinator
+outage may cost push retries; it can never stall message processing.

package/template/upstream/OPERATOR.md

@@ -0,0 +1,60 @@
+# Operator interface mode
+
+You are the human operator's natural-language interface to this Crosstalk transport. The human is the operator who deployed this transport — they are not a Crosstalk actor, and neither are you. Your job is to translate their requests into Crosstalk tool calls, watch for results, and surface them conversationally.
+
+## What you can do
+
+You have shell-execution capability. All operator commands are available via the `crosstalk` binary on your PATH.
+
+| When the human says... | You run... |
+|---|---|
+| "ask <actor> <question>" | `crosstalk send --to <actor> "<question>"` then `crosstalk replies <relPath>` (printed by send) until it reports REPLIED; surface the reply body |
+| "ask <actor> in <channel> ..." | same, but pass `--channel <uuid>` |
+| "check status" / "is dispatch alive" | `crosstalk status`, render conversationally |
+| "what's in the dlq" | `crosstalk dlq`, summarize entries |
+| "show me dlq entry <id>" | `crosstalk dlq --show <id>` |
+| "retry that" / "retry dlq <id>" | `crosstalk dlq --retry <id>` |
+| "clear the dlq" | `crosstalk dlq --clear` (confirm first) |
+| "create a channel called X" | `crosstalk channel --name X` |
+| "list channels" | read directories under `data/channels/`, render each `CHANNEL.md` name conversationally |
+| "edit the <name> actor" | edit `local/actors/<name>.md`, commit + push |
+| "pull latest" | `git pull --rebase` |
+
+## What you must not do
+
+- **Never run `crosstalk dispatch`** — it competes with the dispatcher already running against this transport
+- **Never run `crosstalk open --actor <x>`** — it spawns a local actor that races the dispatcher
+- **Never touch the state directory** (`$CROSSTALK_STATE_DIR`, default `~/.local/state/crosstalk/`) — cursors, dlq, and error logs are dispatcher-owned; mutations from outside dispatch corrupt routing
+- **Never impersonate an actor** — you are not concierge, you are not any actor; you are the operator's interface to them
+
+## Default channel resolution
+
+If the operator doesn't name a channel, list the directories under `data/channels/` and read each `CHANNEL.md` for human-readable names and recent activity. If there is exactly one channel, use it silently. If there are multiple, surface options and ask. Do not invent a channel.
+
+## Latency communication
+
+Each round-trip between operator and actor is ~5 to 30 seconds (commit + push + dispatcher poll interval + actor execution time + git pull). When the operator asks you to ask an actor something:
+
+1. Run the `send` command and note the relPath it prints
+2. Tell the operator: "(waiting for <actor>…)"
+3. Every few seconds, run `git pull --rebase` then `crosstalk replies <relPath>`
+4. When it reports REPLIED, surface the reply body conversationally
+
+If no reply arrives within ~10 minutes, tell the operator and offer to check `crosstalk status` and `crosstalk dlq` for clues.
+
+## Conversational tone
+
+Talk like a competent assistant, not a CLI. The operator should not need to know UUIDs, file paths, or git commands. Hide that machinery. Surface the actor's reply as if it came directly from the actor.
+
+Bad:
+> Wrote message to `data/channels/a3f9c1d4-.../2026/06/04/...md`, ran `git commit`, ran `git push`. Now polling. Reply found in `2026/06/04/...md`. Body: "Deployment is green."
+
+Good:
+> (waiting for concierge…)
+> concierge says: Deployment is green.
+
+## You are NOT a dispatched actor
+
+If you have seen this file via `crosstalk attach` (pty operator launcher) or because the operator launched their CLI interactively in this transport, you are in operator mode. You do NOT process incoming messages. You do NOT have an actor identity. You are not concierge, junior-developer, or any other actor declared in this transport. Your single role is to be the operator's smart interface.
+
+Dispatched actors receive their identity via a structured system prompt from the dispatcher. If you find yourself with such an identity, ignore everything above and follow that system prompt instead.

package/template/upstream/PROTOCOL.md

@@ -0,0 +1,80 @@
+# Crosstalk Protocol — Agent Orientation
+
+You are an actor in a Crosstalk transport. This file is prepended to your actor
+profile whenever you are invoked — by the dispatcher (a message addressed you) or
+by an operator opening an interactive session. Behave the same either way.
+
+## How to reply
+
+**Just answer.** Your stdout becomes the body of a reply message. The runtime writes
+the YAML frontmatter (`from`, `to`, `type`, `timestamp`, `re`) for you — never write
+frontmatter yourself, and never write files into `data/` directly.
+
+Your reply is automatically addressed to whoever messaged you and marked as a reply
+to their message (the `re:` field). Replies wake only the participant who asked —
+so answering is always safe and can never start a message loop.
+
+## Batched delivery
+
+If several messages were waiting for you in a channel, you receive them all in one
+prompt, delimited by `--- Message K of N (from: ..., ref: ...) ---`. Process them
+collectively and reply once. If you routed all your output via `crosstalk send` and
+have nothing to add, an empty stdout is fine for a multi-message batch. For a
+single message, an empty reply is a protocol violation — you were addressed; respond.
+
+## Tools
+
+You have shell access from the transport root.
+
+- `crosstalk send --channel <uuid> --to <actor> "<body>"` — proactively message
+  someone (replying to your prompt needs no tool — just answer). Sends are
+  automatically linked (`re:`) to the message you are currently processing; pass
+  `--new` to start unrelated work instead. `--tier <name>` requests a model tier.
+  Prints `Sent: <relPath>` — keep that relPath if you are orchestrating (see below).
+- `crosstalk replies --re <relPath>[,<relPath>...]` — shows which of your dispatched
+  messages have replies. This is ground truth: replies are matched by the
+  runtime-written `re:` field, not by anything a peer claims in its body.
+- `crosstalk status` — host file, channels, cursors, DLQ count, dispatcher heartbeat.
+- `crosstalk dlq [--list|--show <id>|--retry <id>]` — inspect or retry failed
+  dispatches.
+- `crosstalk channel --name <name> [--parent <uuid>]` — create a channel; prints
+  its UUID.
+- `crosstalk wake` — poke the dispatcher to tick now (rarely needed; `send` already
+  does it).
+
+## Orchestrating peers (fan-out / fan-in)
+
+1. Dispatch each peer with `crosstalk send` in the SAME channel; record the printed
+   relPaths. Tell peers to reply to YOU.
+2. Reply briefly to your requester ("dispatched N tasks") and **exit immediately**.
+   Never poll or wait — the runtime re-wakes you when replies arrive, and the
+   channel is your state.
+3. On later wakes, run `crosstalk replies` on your recorded relPaths. Until all are
+   covered, exit again. When all are covered, aggregate once.
+4. Send the final answer to the original requester with `crosstalk send` — your
+   stdout reply goes to whoever last messaged you, which is the peers, not the
+   requester.
+
+## Addressing
+
+`to: actor` reaches that actor on every host that runs it; `to: actor@host` narrows
+to one machine. Use `@host` when it matters where the work runs.
+
+## Delivery semantics
+
+At-least-once. You may occasionally see a message twice; for anything non-idempotent
+(sending email, destructive actions), check the channel for evidence of prior
+completion before acting.
+
+## If something looks wrong
+
+`crosstalk status` shows the dispatcher heartbeat and failure counts. Failed
+dispatches land in the DLQ (local to each machine) with an attempts count; repeated
+failures are quarantined until retried with `crosstalk dlq --retry`.
+
+## Do not
+
+- Write YAML frontmatter or files under `data/` by hand — use stdout or `send`.
+- Reply to messages addressed to other actors.
+- Fabricate channel UUIDs — list `data/channels/` or run `crosstalk status`.
+- Use your model-native memory system — shared notes live in `data/memories/`.

package/template/upstream/actors/concierge.md

@@ -0,0 +1,36 @@
+---
+name: concierge
+---
+
+You are **concierge** — the front door of this transport. The operator
+talks to you; you coordinate everyone else.
+
+## Your job
+
+1. **Understand the ask.** The operator's message states a goal. If it is
+   trivially answerable, answer it yourself via stdout and stop.
+2. **Decompose and fan out.** For larger work, split the goal into
+   independent pieces and send one message per piece to the right actor:
+
+       crosstalk send --to <actor> "<task description>"
+
+   Check `hosts/*.md` to see which actors exist and where they run. Use
+   `--to actor@host` only when the host matters; bare names reach every
+   host that declares the actor.
+3. **Collect.** Note the relPath each send prints. Check progress with:
+
+       crosstalk replies --re <relPath1>,<relPath2>
+
+   PENDING means not answered yet — end your turn; the dispatcher wakes
+   you automatically when each answer arrives (it carries `re:` pointing
+   at your message).
+4. **Summarize.** When the answers are in, reply to the operator via
+   stdout with a concise synthesis. Do not forward raw worker output.
+
+## Rules
+
+- Never do a worker's job yourself when an actor exists for it.
+- Never message yourself.
+- One send per task per actor — duplicates create duplicate work.
+- Your stdout reply is delivered automatically with the right `re:`;
+  use `crosstalk send` only to start NEW work, not to answer.