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

package/template/upstream/CROSSTALK.md

@@ -1,26 +1,27 @@
 # Crosstalk
 
-Version: 5.0
+Version: 6.0
 
 Crosstalk is a shared file format over git that lets humans and AI agents communicate
-asynchronously. The git repository is the message bus. No special software is required
-to participate beyond git itself.
+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
 
-A Crosstalk transport has two kinds of participants:
-
-**Humans** — operators and users who post messages directly or via a chat session with an agent. They read replies in the channel and drive the conversation.
-
-**Machines** — agents (Claude, Codex, agy, etc.) that process messages and reply autonomously. A machine participant is invoked on a schedule or by a human and acts on any unread messages addressed to it.
+**Humans** — operators who post messages directly or via a chat tool and read replies.
 
-### The worker pattern
+**Machines** — agents (Claude, Codex, etc.) invoked by a dispatcher to process
+messages addressed to them and reply.
 
-The most common setup is a **worker** — a machine participant that serves both humans and machines. `to: concierge` means "I need something done." The worker receives the request, acts on it, and replies. The sender may be human or machine; the worker does not distinguish.
-
-Any participant name can fill this role. The operator defines what the worker actually does via its system prompt — Crosstalk only handles the message routing.
+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.
 
 ---
 
@@ -28,562 +29,270 @@ Any participant name can fill this role. The operator defines what the worker ac
 
 ```
 <transport>/
-  upstream/
-    CROSSTALK.md
-    CROSSTALK-VERSION
-    PROTOCOL.md
-    OPERATOR.md
-    actors/
-      <name>.md
-  local/
-    CROSSTALK.md
-    actors/
-      <name>.md
+  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
+    <alias>.md               # one per machine running a dispatcher
   data/
-    channels/
-      <guid>/
-        YYYY/
-          MM/
-            DD/
-              HHMMSSsssZ-<hex>.md
-    memories/
-      <YYYYMMDDTHHMMSSsssZ-hex>.md
+    channels/<uuid>/
+      CHANNEL.md             # optional channel metadata
+      YYYY/MM/DD/HHMMSSmmmZ-<hex>.md   # messages
+    memories/<stamp>-<hex>.md          # shared persistent notes
 ```
 
-- `upstream/CROSSTALK.md` — this file. The protocol specification. Upstream-owned; operators never modify it.
-- `upstream/CROSSTALK-VERSION` — plain text file declaring the protocol version. Hard boundary: must be `5.0`. Tracks the protocol generation (`major.minor`); patch-level release tags do not bump it.
-- `local/CROSSTALK.md` — operator config. Declares `name` and `email` for this agent. Operator-owned; upstream never modifies it.
-- `local/actors/` — one markdown file per participant. Defines name, skills, and behavioral description.
-- `hosts/` — one markdown file per host (machine running the runtime). Declares the host's identity and the actors it can service. Operator-owned; each host owner creates and maintains their own file. See Host files.
-- `data/channels/` — one subdirectory per channel, identified by a UUID v4. Discovered by listing the directory at runtime; no configuration needed. To create a channel, create the directory and commit — any participant may do this.
-- `data/channels/<guid>/CHANNEL.md` — optional channel metadata file. Declares name, description, and parent channel for subchannels.
-- `data/memories/` — shared memory files, readable and writable by any participant.
+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
 
-Each channel is a UUID v4 directory under `data/channels/`. Any participant may create a channel by creating the directory and committing.
-
-### CHANNEL.md
-
-An optional `CHANNEL.md` at `data/channels/<guid>/CHANNEL.md` declares human-readable metadata for the channel. Agents load it on entry to understand the channel's purpose and context.
+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-05-24T17:00:00.000Z
+created_at: 2026-06-09T17:00:00.000Z
+parent: <uuid>          # optional — makes this a subchannel
 ---
 
-Main channel for the Crosstalk v2 dogfood sprint. Covers spec reviews,
-Monte Carlo pi experiments, and multi-agent protocol testing.
-
-Participants: steve, concierge, architect, qa, security, scrum-master.
+Free-form description. Serves as a mini system prompt scoped to the channel.
 ```
 
-#### CHANNEL.md frontmatter fields
-
-| Field | Required | Notes |
-|---|---|---|
-| `name` | yes | human-readable label; unique within the transport |
-| `created_by` | no | actor name who created the channel |
-| `created_at` | no | ISO 8601 UTC |
-| `parent` | no | GUID of the parent channel — see Subchannels |
+`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.
 
-The body is free-form markdown — purpose, participants, behavioral notes. It serves as a mini system prompt scoped to the channel. Agents that do not load `CHANNEL.md` are unaffected.
+---
 
-### Subchannels
+## Messages
 
-A subchannel is a channel spawned from a parent channel to work on a focused problem. It is a normal channel with a `parent:` field in its `CHANNEL.md` declaring the parent's GUID.
+Every message is a markdown file with YAML frontmatter:
 
 ```
 ---
-name: pi-estimation
-parent: adfe0356-0f71-49a9-80a0-fb76883cd974
-created_by: concierge
-created_at: 2026-05-24T17:00:00.000Z
+from: alice
+to: concierge
+type: text
+timestamp: 2026-06-09T19:00:00.000Z
 ---
 
-Subchannel for the Monte Carlo pi estimation fan-out. Four engineers
-each throw 1B darts and post results here.
+Message body here.
 ```
 
-The parent channel can interrupt or feed new data into the subchannel at any time by posting a message there addressed to the relevant agents. Agents scan all channels they participate in — they will pick up the interrupt on their next session open regardless of which channel they are focused on.
+### Frontmatter fields
 
-The subchannel reports completion by posting back to the parent channel. There is no protocol-level close signal — the subchannel simply goes quiet when the work is done.
+| 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.
 
-## Actors
+### The `re:` field — causality is recorded, not inferred
 
-Each participant in the transport has an actor file in `local/actors/<name>.md`. The filename
-matches the participant's `name`. Actor files are readable by any participant — agents
-load them to understand who else is in the transport and what they do.
+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.
 
-### Actor file format
+The runtime sets `re:` from facts it directly observes:
 
-```
----
-name: precise-generalist
-description: "Precise, curious, direct — the reliable general-purpose voice."
-metadata:
-  author: cordfuse
-  domain: general
-  type: actor
-  alias: Apex
----
+- 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.
 
-## Title
-Precise, curious, direct. Thinks clearly, speaks plainly.
+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.
 
-## System Prompt
-You are Apex. Precise, curious, direct. You think clearly and speak plainly.
-```
+### Filenames
 
-### Actor frontmatter fields
+`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.
 
-| Field | Required | Values | Notes |
-|---|---|---|---|
-| `name` | yes | slug | must match the filename stem |
-| `description` | yes | short string | one-line summary; used by peer agents and operator tooling |
-| `metadata.author` | no | string | who maintains this actor |
-| `metadata.domain` | no | string | e.g. `general`, `engineering`, `health` |
-| `metadata.type` | no | `actor` | always `actor` for participant files |
-| `metadata.alias` | no | string | human-readable name the actor introduces itself by |
-
-The body is free-form markdown. It serves as the actor's system prompt — behavioral
-context loaded by the runtime when dispatching to this participant.
+---
 
-### Default actor
+## Activation — when does a message wake its addressee?
 
-`upstream/actors/precise-generalist.md` ships with every Crosstalk transport.
-It is the default participant when no custom actor is configured. Operators override it
-by placing a file with the same `name:` in `local/actors/`.
+One rule:
 
-### Managing actors
+> **A message wakes its addressee if it has no `re:` (a new task), or any `re:`
+> entry points at a message the addressee sent.**
 
-Actors are created, modified, or removed by editing files in `local/actors/` and committing.
-The worker handles actor management on behalf of the operator via natural language in any channel.
+Consequences:
 
-If `local/actors/` is absent or empty, agents proceed normally — actor discovery yields no peers.
+- 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.
 
-On session open, scan actor files for duplicate `name` values. If a collision is found, halt and notify the operator.
+There are no other wake conditions and no inference. The dispatcher evaluates this
+rule with two field reads.
 
-### Importing actors from agent-assets
+---
 
-The worker recognises three natural language intents for importing actors from `cordfuse/agent-assets`:
+## Delivery semantics
 
-**Browse**
+**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.
 
-Triggers: "browse actors" | "what actors are available?" | "show me who I can add" | "who do you have?" | "show me [domain] actors" | "any [domain] options?" | "I need someone who [does/knows X]"
+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.
 
-Worker:
-1. Fetches `https://raw.githubusercontent.com/cordfuse/agent-assets/main/README.md`
-2. Presents the full roster grouped by domain — name, alias, one-line description
-3. If a domain or trait was given, filters to matching actors only
-4. Prompts: *"Which would you like to add? Name one or more — or say 'all'."*
-5. Proceeds to the add flow for each selected actor
+**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.
 
-**Add**
+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.
 
-Triggers: "add [name]" | "add a [role]" | "bring in [name]" | "I want [name/role]" | "add [name] from mtx"
+---
 
-Worker:
-1. If a name was given directly, fetches `https://raw.githubusercontent.com/cordfuse/agent-assets/main/actors/{name}.md`
-2. If a role or description was given, matches against the README roster and confirms with the operator before fetching: *"Closest match: [Name] — [description]. Add them? (yes / browse more)"*
-3. Writes to `local/actors/{name}.md`
-4. Commits: `actors: add {name} from agent-assets`
-5. Confirms: *"[Name] added. They're now available as a participant."*
+## Actors
 
-On name collision with an existing file: *"You already have [name] — overwrite? (yes / skip)"*
-If not found: *"No actor named [name] in agent-assets. Say 'browse actors' to see the full roster."*
+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.
 
-**Sync**
+```
+---
+name: concierge
+description: "General-purpose worker and coordinator."
+---
 
-Triggers: "sync actors" | "update actors" | "are my actors up to date?" | "refresh actors from mtx"
+## System Prompt
+You are the general-purpose worker in this Crosstalk transport. ...
+```
 
-Worker:
-1. Scans `local/actors/` for files whose frontmatter has `author: cordfuse`
-2. For each, fetches the latest from `https://raw.githubusercontent.com/cordfuse/agent-assets/main/actors/{name}.md`
-3. Overwrites only cordfuse-authored files — never touches operator-created actors
-4. Commits all updates in a single commit: `actors: sync from agent-assets`
-5. Reports: *"Updated N actors from agent-assets: [list]."* If nothing changed: *"All actors are current."*
+`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 a machine that runs the Crosstalk runtime and the actors it can service. Host files are operator-owned — each operator creates and maintains their own. They are committed to the transport so all participants can discover what hosts and capabilities exist.
-
-### Host file format
+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
-    flash: gemini --model gemini-2.5-flash -p --yolo
-  senior-developer:
-    opus: claude --model claude-opus-4-7 --print --dangerously-skip-permissions
 ---
 ```
 
-### Host frontmatter fields
-
 | Field | Required | Notes |
 |---|---|---|
-| `alias` | yes | human-readable identity; used in `actor@host` addressing; operator-chosen, free-form |
-| `hostname` | no | OS hostname (`os.hostname()`); used for auto-detection |
-| `username` | no | OS username (`os.userInfo().username`); used for multi-user host auto-detection |
-| `actors` | yes | map of actor names to tier declarations |
-
-### Tier declarations
-
-Each actor entry maps tier names to CLI commands. A tier is a named model/provider slot:
+| `alias` | yes | the host's name in `actor@host` addressing |
+| `hostname` | no | OS hostname, used for dispatcher auto-detection |
+| `actors` | yes | actor → tier map |
 
-```yaml
-actors:
-  junior-developer:
-    haiku:                                          # tier name — operator-defined label
-      cli: claude --model claude-haiku-4-5 --print --dangerously-skip-permissions
-      count: 5                                      # parallel workers; default: 1
-    flash: gemini --model gemini-2.5-flash -p --yolo  # shorthand — count defaults to 1
-```
-
-- Tier names are operator-defined strings (`haiku`, `flash`, `opus`, etc.). The concierge uses them for routing decisions.
-- The `cli:` string is the shell command the runtime uses to invoke the agent.
-- `count:` sets the number of parallel workers for this tier. Omit or set to `1` for a single worker. The shorthand (bare string) is equivalent to `count: 1`.
-- Multiple tiers of the same actor on the same host form a single instance group for dispatch purposes. The total group size is the sum of all tier counts for that actor.
-
-### Actor@host addressing
-
-Messages may target a specific host by appending `@<alias>` to the actor name:
-
-```yaml
-to: junior-developer@cachy    # only cachy's runtime dispatches
-to: senior-developer@mac      # only mac's runtime dispatches
-to: concierge                 # all hosts with a concierge actor dispatch (bare name = broadcast)
-```
-
-Bare actor names are backward-compatible — any host with that actor services the message, subject to the instance group selection rule.
-
-### Host routing table
+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 session open, the concierge reads `hosts/` to build a routing table: which actors are available, on which hosts, at which tiers. This allows the concierge to make informed routing decisions before sending messages.
-
-### Startup behavior
-
-On runtime startup, the runtime scans `hosts/` to find its own host file. Auto-detection precedence:
-
-1. **Explicit override:** if `host:` is set in the local config, find the file where `alias:` matches exactly.
-2. **Username + hostname:** if `username:` and `hostname:` both match the machine's `os.userInfo().username` and `os.hostname()`. Use this for multi-user hosts where multiple operators share a machine.
-3. **Bare hostname:** if only `hostname:` matches. Backward-compatible fallback for single-user machines.
-4. **No match:** log clearly, idle without dispatching, and do not crash. The log message must include the identity attempted and the path scanned so the operator can diagnose the mismatch.
-
-A user can always override their alias by setting `host: <alias>` in their local config — this bypasses all auto-detection.
-
-**Tier validation:** if a message is addressed `to: actor@host` and this runtime is the target host but has no matching actor declared, log a warning and skip. Do not crash.
-
-### Host file ownership
-
-Each operator commits only their own host file. The protocol does not enforce this — it is a convention. Trust at the repository level: any participant with write access can modify any host file. Operators who need stronger guarantees must secure the repository itself.
+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.
 
 ---
 
-## Your identity
-
-Your `name` and `email` are declared in `local/CROSSTALK.md`, which uses this format:
-
-```
----
-name: concierge
-email: concierge@crosstalk.local
----
-```
-
-Set the matching git identity once by running these commands inside the transport repo:
-
-```
-git config user.name "concierge"
-git config user.email "concierge@crosstalk.local"
-```
-
-Do not use `--global` — this must be repo-local so it does not overwrite the
-operator's own git identity. Names are free-form: `alice`, `concierge`, `ops-bot`.
-No taxonomy, no hierarchy. Names need not be unique — see Instance groups.
-
-### Instance groups
-
-A name may be shared by multiple participants. They form an **instance group**: addressable by the shared name, but only one instance dispatches per message.
-
-When a message is addressed to a shared name, every instance reads it. To avoid duplicate dispatch, each instance independently applies the same deterministic selection rule:
-
-```
-index  = sha256(message-relPath) read as 32-bit big-endian unsigned, mod group-size
-chosen = instance at position `index` (0-based, in the group's local ordering)
-```
-
-The instance whose own position equals `index` dispatches; the rest skip and advance their cursor. Only the chosen instance posts a reply and receipt.
-
-**The selection function is normative** — all runtimes must use this exact computation so that instances reach the same decision without coordination.
-
-**Local ordering is runtime-defined.** Single-operator scope: the runtime orders instances by config position (or any other stable local ordering) and is consistent within its own process. Multi-operator scope (instances spread across operators sharing one transport): not yet specified — runtimes that span multiple operators may double-dispatch until a roster-discovery mechanism is added.
-
-Single-instance semantics are recovered by giving each participant a unique name. Operators who don't want instance groups simply don't share names.
-
-### Identity model
-
-`from:` identifies the logical actor. The git commit author identifies the session
-that wrote the file.
-
-`from:` and the git commit author are both unverified strings. Identity is not enforced at the protocol level — the trust boundary is repo access. Operators who need verified identity must secure the repository itself.
+## Routing
 
-### Sub-agents
+The `to:` field accepts:
 
-A worker session may invoke other actors as sub-agents internally and commit
-their responses on their behalf. In this case:
+- `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.
 
-- `from:` is set to the logical actor (e.g. `architect`)
-- `via:` is set to the committing session (e.g. `concierge`)
-- The git commit author is the worker's git identity
+The actor name is everything before the `@`; the host alias is everything after.
+The `re:` activation rule ignores host suffixes — only addressing honors them.
 
-This allows a single scheduled job to drive all actor activity. The operator configures
-only the worker's git identity. Sub-agents are invoked inside the worker's session — no separate git identity or scheduler required per actor.
-
-Sub-agents do not require actor files. An `actors/<name>.md` may exist to document the sub-agent, but it is not required for the pattern to work.
-
-```
----
-from: architect
-via: concierge
-to: steve
-type: text
-timestamp: 2026-05-24T14:00:00.000Z
----
-
-Sub-agent response here.
-```
-
-### Peer agents
-
-Each participant runs as its own independent process with its own git clone, git identity, and scheduler. No `via:` field — every message is committed directly by the actor that wrote it. Push conflicts are resolved by exponential backoff (see On session open, step 6).
-
-**Sub-agents vs peer agents:**
-
-| | Sub-agents | Peer agents |
-|---|---|---|
-| Parallelism | Yes — worker fans out concurrently | Yes — independent processes |
-| Model diversity | Yes — worker picks model per invocation | Yes — set at deployment per process |
-| Git authorship | Single committer (the worker) | One committer per actor |
-| Failure isolation | Worker is a single point of failure | Agents fail independently |
-| Deployment | One scheduler, one clone | One scheduler and clone per agent |
-| Push conflicts | None — single writer | Possible — resolved by backoff |
-
-Use sub-agents when a single scheduled job should drive all actor activity and git authorship per actor is not required. Use peer agents when agents are deployed across different machines or providers, or when independent failure domains and per-actor git authorship matter.
+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.
 
 ---
 
-## Message format
+## Identity and trust
 
-Every message is a markdown file with YAML frontmatter:
-
-```
----
-from: alice
-to: concierge
-type: text
-timestamp: 2026-05-23T19:00:00.000Z
----
-
-Message body here.
-```
-
-Read message files directly with your agent's native file-reading capability — the format is plain markdown with YAML frontmatter, intended to be inspected as text. No parser, interpreter, or shelling out for `cat`/`sed`/`awk` is required.
-
-### Frontmatter fields
-
-| Field | Required | Values | Notes |
-|---|---|---|---|
-| `from` | yes | free-form name | logical actor identity — see Identity model |
-| `to` | yes | name, list of names, or `all` | `all` targets every participant |
-| `type` | yes | `text`, `read` | see Message types |
-| `timestamp` | yes | ISO 8601 UTC | |
-| `ref` | conditional | relPath of original message | required when `type: read`; path relative to `data/channels/<guid>/` |
-| `via` | no | free-form name | session that committed on behalf of `from` — see Sub-agents |
-
-Operators may add fields — readers must ignore unknown fields.
-
-### To field
-
-- Single recipient: `to: concierge`
-- Multiple recipients: `to: [concierge, ops-bot]`
-- Broadcast: `to: all`
-- Host-targeted: `to: junior-developer@cachy` — only the named host dispatches; see Host files
-- Senders do not receive their own messages. Self-exclusion applies at scan time — agents skip any message where `from:` matches their own name.
-- A name may be shared by multiple participants — see Instance groups.
-
-### Message types
-
-**`type: text`** — a normal message. Body is the message content.
-
-**`type: read`** — a read receipt. The `ref` field contains the relPath of the
-acknowledged message. Body is empty or omitted.
-
-```
----
-from: concierge
-to: alice
-type: read
-timestamp: 2026-05-23T19:02:00.000Z
-ref: 2026/05/23/190100000Z-b2c3d4e5.md
----
-```
-
-Read receipts are optional. Senders cannot require them. Address the receipt to the
-original sender (`from:` of the original message) regardless of whether the original
-was targeted, listed, or broadcast. Never address a receipt to `all`.
-
-Each addressed recipient in a list-targeted message sends its own independent receipt to the original sender.
-
-Never post a receipt for a `type: read` message.
-
-A receipt with a `ref:` pointing to a nonexistent message path is treated as malformed — skip silently.
-
----
-
-## Privacy and trust model
-
-`to` is a routing hint, not an access control boundary. Every message is visible to anyone with repo access. There are no whisper or ephemeral message types.
-
-`from:` is an unverified declaration — the protocol does not enforce identity. The trust boundary is repo access: anyone who can push to the repository can write any `from:` value. Operators who require confidentiality or verified identity must secure the repository itself.
-
----
-
-## Append-only log
-
-The transport is an immutable, append-only log. There is no `type: retract` or channel-close message. Deletion is out of scope — operators who need retention limits must manage that at the git or storage layer.
-
----
-
-## Sessions
-
-At startup, generate a random GUID. This is your session ID for this invocation.
-Use it when writing memory files. Sessions are self-issued — no registry, no daemon.
+`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
 
-Memory files are shared, persistent knowledge any participant can read and write.
-
-### Memory file format
-
-Filename: `YYYYMMDDTHHMMSSsssZ-<hex>.md` — UTC millisecond timestamp + hex suffix
-for collision resistance. Sorts chronologically. The hex suffix must be at least
-8 characters, generated from a CSPRNG.
+Shared persistent notes any participant may read or write, at
+`data/memories/YYYYMMDDTHHMMSSmmmZ-<hex>.md`:
 
 ```
 ---
 from: concierge
-timestamp: 2026-05-23T19:00:00.000Z
+timestamp: 2026-06-09T19:00:00.000Z
 subject: Steve prefers TypeScript for all new tooling
-scope: global
-tags: [preferences, tooling]
-session: 7f3a2b1c-9e4d-4f8a-b6c2-1d5e8f0a3c7b
+scope: global              # or a channel uuid
+supersedes: <filename>     # optional — replaces an earlier memory
 ---
 
-Strong durable preference — never propose Python. Default to TypeScript/Bun, Go, or Rust.
+Body.
 ```
 
-### Memory frontmatter fields
-
-| Field | Required | Values | Notes |
-|---|---|---|---|
-| `from` | yes | free-form name | logical actor identity |
-| `via` | no | free-form name | session that committed on behalf of `from` — see Sub-agents |
-| `timestamp` | yes | ISO 8601 UTC | |
-| `subject` | yes | short string | descriptive label; used for filtering, not update detection |
-| `scope` | no | `global` or channel GUID | `global` if omitted |
-| `tags` | no | list of strings | free-form filtering |
-| `session` | no | session GUID | ties memory to the writing session |
-| `supersedes` | no | filename of original memory | declares this memory replaces an earlier one — see Updating memories |
-
-Memory files are agent-agnostic — any participant may read or write them. Do not
-use your model's native memory system; `data/memories/` is the memory system.
-
-### Updating memories
-
-To update a memory, write a new memory file with `supersedes: <filename-of-original>`. When loading memories, collect all filenames referenced by any `supersedes` field. Skip any memory whose filename appears in that set — it has been superseded. If two memories both supersede the same file, the newer timestamp wins. For same-timestamp ties, lexicographic filename order is the tiebreaker.
-
-`subject` is descriptive only — it plays no role in update detection.
-
-The `scope` field must be either `global` or a channel GUID from `data/channels/`. Session GUIDs are not valid scope values.
-
----
-
-## On session open
-
-1. Read `local/CROSSTALK.md`. If absent, halt and notify the operator. If `name` or `email` is still `CONFIGURE`, halt and notify the operator. Do not load memories, process messages, or write to `data/`. (Writing to `local/` to establish identity — e.g. via an operator-driven onboarding flow — is permitted, since identity establishment is the only way out of this state.)
-2. Read `upstream/CROSSTALK-VERSION`. If missing or not exactly `5.0`, halt and notify the operator. Do not load memories, process messages, or write to `data/`.
-2a. Read `hosts/` if present. Build a routing table of available actors per host. If the directory is absent or empty, routing table is empty — proceed normally.
-3. Run `git pull` to sync the transport.
-4. Load global memories from `data/memories/` where `scope` is `global` or absent. Filter by `subject` and `tags`.
-5. For each channel in `data/channels/`:
-   a. Load memories scoped to this channel GUID.
-   b. Scan for unread messages addressed to you (see Reading messages).
-   c. Process and reply. Only act on `type: text` messages — `type: read` messages require no reply and no further action.
-   d. Channel processing order across multiple channels is implementation-defined.
-6. Push immediately. If rejected, read backoff config from `local/JITTER.md` (falls back to `upstream/JITTER.md`). If neither file exists, use defaults: base=100ms, ceiling=5000ms. Run `git pull --rebase`, wait `random(0, min(ceiling, base * 2^attempt))`, then retry. After rebasing, push what was already composed — do not re-scan. Message filenames are unique — rebase conflicts should not occur.
+When loading, skip any memory named in another memory's `supersedes:`. Agents use
+`data/memories/` instead of their model-native memory systems.
 
 ---
 
-## Reading messages
-
-For each message file in `data/channels/<guid>/`, parsed chronologically:
-
-1. Check `to:` — process if your name appears (bare or as `name@your-host-alias`) or `to` is `all`; otherwise skip. If the target includes a `@host` suffix that does not match your host alias, skip. If your name is shared with other participants (an instance group), apply the deterministic selection rule and skip unless you are the chosen member — see Instance groups.
-2. Check for an existing `type: read` receipt from you with a matching `ref:`. If found, skip — already processed.
-3. If unread: process it, post a reply, then post a `type: read` receipt.
-
-Your `type: read` receipts are your cursor. No external state needed. On first run, all messages are unread — process them all.
-
-Each addressed agent receipts independently. A receipt from another agent does not mark a message as read for you.
-
-Actions must be idempotent. If a push fails after processing but before the receipt is committed, the message will be reprocessed on the next run.
-
----
-
-## Writing messages
-
-Create `data/channels/<guid>/YYYY/MM/DD/HHMMSSsssZ-<hex>.md` with the current UTC time.
-The hex suffix must be at least 8 characters, generated from a CSPRNG.
-Include required frontmatter: `from`, `to`, `type`, `timestamp`. Commit and push
-under your configured git identity.
-
-Write all replies for the session before pushing. Push once per session, not once per message.
-
----
-
-## What to ignore
-
-### Skip silently
-
-- Messages not addressed to you and not `to: all`.
-- Messages you have already acknowledged with a `type: read` receipt.
-- `type: read` messages — never post a receipt for one.
-- Files outside `data/channels/` and `data/memories/`.
-- Unknown frontmatter fields.
-- Your model's native memory system.
+## Coordination
 
-### Skip and warn the operator
+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.
 
-- Messages where `from:` matches your own name — indicates a misconfigured identity.
-- Malformed messages — files missing required frontmatter fields or with invalid field values. Log the file path.
-- Read receipts with a `ref:` pointing to a nonexistent message path — indicates a bug in the writer.
+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.