@cordfuse/crosstalkd 7.0.0-alpha.1

package/template/CLAUDE.md

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

package/template/CROSSTALK-VERSION

@@ -0,0 +1 @@
+7

package/template/CROSSTALK.md

@@ -0,0 +1,242 @@
+# Crosstalk
+
+Version: 7
+
+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.
+
+---
+
+## The six nouns
+
+Every concept in Crosstalk maps to exactly one of these:
+
+| Noun | Definition |
+|---|---|
+| **Transport** | A git repo, scaffolded by `crosstalk init`. The bus. |
+| **Machine** | A host running one `crosstalk dispatch` loop. Identifies itself via `--alias`. |
+| **Message** | A markdown file with YAML frontmatter, committed to a channel. The unit of work. |
+| **Model** | A named agent invocation declared in `data/models.yaml` (e.g. `sonnet`, `codex-o3`). |
+| **Actor** | An optional persona file (`local/actors/<name>.md`) that prepends to a model's prompt. |
+| **Channel** | A UUID directory under `data/channels/`. A conversation thread. Optionally parented. |
+
+---
+
+## Transport layout
+
+```
+<transport-root>/
+  CROSSTALK-VERSION              # protocol version, single integer
+  PROTOCOL.md                    # agent orientation, prepended to every dispatch
+  CROSSTALK.md                   # this file
+  data/
+    models.yaml                  # the shared model vocabulary
+    channels/<uuid>/
+      CHANNEL.md                 # { name, optional parent }
+      YYYY/MM/DD/<msg>.md        # messages
+  local/
+    actors/<name>.md             # optional persona files
+  workflows/                     # convention, not enforced — reusable workflow markdown
+```
+
+That is the complete committed surface. **Dispatcher bookkeeping (cursor, heartbeat, pidfile, wake signal) is machine-local state and never lives in the repo** — it is kept under `~/.config/crosstalk/state/<transport-name>/`. The repo carries conversation; each machine carries its own progress through it.
+
+There is no `hosts/` directory and no `upstream/` directory at all — v6's `upstream/`-vs-`local/` override hierarchy is gone. `local/` still exists as the home for actor persona files (`local/actors/<name>.md`). The model vocabulary in `data/models.yaml` is shared by everyone; each dispatcher claims the entries whose CLI is on its PATH.
+
+---
+
+## Channels
+
+A channel is a UUID v4 directory under `data/channels/`. Create one with `crosstalk channel <name>`; the runtime generates the UUID and writes a `CHANNEL.md`:
+
+```
+---
+name: review-and-synthesize
+parent: 550e8400-e29b-41d4-a716-446655440000   # optional
+---
+```
+
+Two fields. `name` is required and must be unique within the transport (the runtime rejects collisions at create / rename time). `parent` makes this a subchannel — a workflow's child channel uses this to record its provenance.
+
+There is no `created_by`, no `created_at`, no prose body. Git's commit history records who and when.
+
+There is no close signal; a finished channel simply goes quiet. To remove one: `crosstalk channel <name> --delete` (hard delete with typed-name confirmation).
+
+---
+
+## Messages
+
+Every message is a markdown file with YAML frontmatter:
+
+```
+---
+from: alice
+to: sonnet@cachy
+timestamp: 2026-06-11T19:00:00.000Z
+---
+
+Message body here.
+```
+
+### Frontmatter fields
+
+| Field | Required | Notes |
+|---|---|---|
+| `from` | yes | logical actor or operator name — unverified; trust boundary is repo access |
+| `to` | yes | `<model>[@<machine>]`; bare model name reaches any dispatcher claiming it |
+| `timestamp` | yes | ISO 8601 UTC |
+| `re` | no | relPath (or list) of the message(s) this one answers — **written by the runtime, never by hand** |
+| `as` | no | actor persona to prepend on dispatch |
+| `wake_as` | no | persona to invoke the asker with when replies to this message wake them — written automatically by `crosstalk run` when invoked from a dispatched turn that had `--as`. Powers workflow persona continuity. |
+| `child_channel` | no | UUID of a child channel created for this workflow message (set automatically by `crosstalk run --type workflow`) |
+| `type` | no | always omitted on regular messages; `workflow` on workflow documents only |
+| `failed` | no | `true` on failure replies written by the dispatcher |
+| `error` | no | failure detail, paired with `failed: true` |
+
+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). The field is a string for one target and a list for several.
+
+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 run`, the runtime injects the triggering relPath(s) into the environment and `run` records them automatically. An actor can suppress this (`--new`) to start genuinely new work.
+- Messages written by operators carry no `re:` — they are new tasks by definition.
+
+Actors never compute or hand-write `re:`.
+
+### 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 model 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 one cursor (machine-global, not per-channel-per-model) recording the git commit the transport was last scanned at. If a machine crashes mid-tick, the next tick re-dispatches anything not 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 a model, it hands over ALL pending messages addressed to that model 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 at the protocol level. Retention is the operator's concern at the git/storage layer.
+
+---
+
+## Models
+
+Models are declared in `data/models.yaml` — one file, shared by everyone:
+
+```yaml
+sonnet:      claude --print --model claude-sonnet-4 --dangerously-skip-permissions
+haiku:       claude --print --model claude-haiku-4-5 --dangerously-skip-permissions
+codex-o3:    codex exec --model o3
+gemini-pro:  gemini --skip-trust --yolo -p --model gemini-1.5-pro
+qwen3-coder: qwen --yolo --model qwen3-coder
+agy:         agy -p
+```
+
+Keys are model names (used in `--to`). Values are shell command templates. The runtime appends the message body as the final positional argument, with stdin fallback for prompts > 64 KB.
+
+**PATH-based self-selection.** Each dispatcher reads `models.yaml` at boot, takes the first token of each entry's command (`claude`, `codex`, `gemini`, …), and checks PATH. Only models whose CLI is installed locally are claimed. A laptop with `claude` and `gemini` installed claims `sonnet`, `haiku`, `gemini-pro`; a server with only `claude` claims just the Claude entries.
+
+Adding a new model = one line in `models.yaml`. No PR to crosstalk. Custom or private agents: drop a wrapper script `crosstalk-myagent` on PATH and reference it in the file.
+
+---
+
+## Actors
+
+An actor is an optional persona file at `local/actors/<name>.md`. Plain markdown, no required frontmatter. The full body is prepended to a model's prompt as system context when `--as <name>` is used.
+
+```sh
+crosstalk run --type primitive --to sonnet --as junior-developer "implement this"
+crosstalk run --type primitive --to opus --as senior-architect "review this"
+```
+
+Actors are not bound to machines or models. Any model can be invoked with any actor. There are no declarations, no tier wiring, no host file lookup. The runtime concatenates persona body + message body and ships.
+
+The **orchestrator** actor ships with `crosstalk init`. It contains the prompt that teaches a model how to interpret workflow documents and execute their steps. See [Workflows](#workflows).
+
+---
+
+## Workflows
+
+A workflow is a markdown document with `type: workflow` in the frontmatter:
+
+```markdown
+---
+type: workflow
+to: opus@cachy
+as: orchestrator
+---
+
+1. Fan out 3 junior developers running sonnet@laptop. Each drafts the proposal in their own voice.
+2. Send the 3 drafts to a reviewer running opus@cachy to synthesize.
+3. Return the synthesis to the original requester.
+```
+
+When the operator runs `crosstalk run --type workflow <file>`:
+
+1. The runtime creates a new child channel UUID, parented to the operator's current channel. The child channel's name is derived from the workflow filename.
+2. The workflow document is written as a message into the **parent** channel, addressed to `opus@cachy` with `as: orchestrator`.
+3. The opus dispatcher on cachy picks it up, loads the orchestrator persona, parses the workflow's prose steps.
+4. Orchestrator fires sub-`crosstalk run --type primitive` calls into the **child** channel.
+5. Sub-primitive replies wake the orchestrator via `re:` links.
+6. Orchestrator aggregates and posts the final reply to the **parent** with `re:` linking back to the workflow message.
+
+The runtime contains no workflow engine. The orchestrator persona is just an actor whose system prompt teaches a model how to interpret workflow markdown.
+
+---
+
+## Routing
+
+The `to:` field accepts:
+
+- `to: sonnet` — bare model name. Any dispatcher claiming `sonnet` may pick it up; first-grab wins via git push race.
+- `to: sonnet@cachy` — narrowed to the dispatcher whose `--alias` is `cachy`.
+
+The model name is everything before the `@`; the machine alias is everything after. The `re:` activation rule ignores `@machine` suffixes — only addressing honors them.
+
+Use bare names for work-pool patterns where any machine will do; use `@machine` when which machine runs the work matters. This addressing is the entirety of Crosstalk's multi-machine 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 (private remote, SSH keys, branch protection).
+
+---
+
+## Coordination
+
+Git is self-coordinating: filenames are collision-free and non-fast-forward pushes are rejected and retried with `git pull --rebase`. A transport works with no broker, no coordinator, no advisory lock service.
+
+There is no turnq, no advisory locking, no token server. v6 carried these as churn-reducers; v7 confirmed git rebase-retry is the actual correctness mechanism and the rest was overhead.
+
+---
+
+## What v7 dropped vs v6
+
+For operators familiar with v6: the entire `hosts/` directory, all tier declarations, the DLQ subsystem, operator-mode, the concierge actor name (renamed `orchestrator`), the Docker server tier, `crosstalk attach/chat/open/wake/dlq/upgrade` subcommands, the `@cordfuse/turnq` dependency, the `local/`-vs-`upstream/` actor override hierarchy, and the `data/memories/` shared-notes subsystem are all gone.
+
+The v6 → v7 transition is a clean break. There is no auto-migration tool; v6 transports stay on v6 (the runtime checks `CROSSTALK-VERSION` and refuses to operate on incompatible versions).

package/template/PROTOCOL.md

@@ -0,0 +1,66 @@
+# Crosstalk Protocol — Agent Orientation
+
+You are an actor in a Crosstalk transport. This file is prepended to your prompt every time a dispatcher invokes you. Read it once per session and behave accordingly.
+
+## The single most important rule
+
+**Never write files under `data/channels/` by hand.** All message creation goes through `crosstalk run`. The runtime owns frontmatter; you own message bodies. Violating this rule will desync the bus and break every receiver. There is no exception, ever, even if "it would be faster."
+
+If you find yourself wanting to use `cat <<EOF`, `printf`, or `echo` to write a markdown file into `data/channels/`, **stop**. Use `crosstalk run` instead.
+
+## How to reply
+
+**Just answer.** Your stdout becomes the body of a reply message. The runtime writes the YAML frontmatter (`from`, `to`, `timestamp`, `re`) for you. Never write frontmatter yourself.
+
+Your reply is automatically addressed to whoever messaged you and `re:`-linked to their message. Replies wake only the participant who asked — answering is always safe and cannot start a message loop.
+
+If you have nothing useful to say (e.g. the message is a reply that doesn't need acknowledging), exit with empty stdout. The dispatcher logs that as `dispatch_silent` and the asker's `crosstalk replies` stays PENDING — visible, not lost.
+
+## 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.
+
+## Tools
+
+You have shell access from the transport root.
+
+- `crosstalk run --type primitive --to <model>[@<machine>] [--as <actor>] [--fanout <n>] [--channel <uuid>] "<body>"` — proactively message a model. Replying to your prompt needs no tool; just answer. Sends are automatically linked (`re:`) to the message you are currently processing. Prints `Sent: <relPath>` — keep that relPath if you are orchestrating.
+- `crosstalk run --type workflow <file-or-->` — dispatch a workflow document (markdown with frontmatter). Use `-` to read from stdin.
+- `crosstalk replies <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` — channels (name → uuid), dispatcher heartbeat, claimed models.
+- `crosstalk channel <name>` — create a channel; prints its UUID. Use `--rename <new>` or `--delete` for the other operations.
+
+There is no `wake` subcommand — `crosstalk run` automatically pokes the dispatcher.
+
+## Workflows
+
+A workflow is a markdown document with `type: workflow` in the frontmatter, dispatched via `crosstalk run --type workflow`. The runtime handles execution: it compiles the prose body into a structured plan and runs the fan-out → synthesize → reply loop deterministically. No model is ever asked to orchestrate.
+
+You do not need to know whether the message you are processing was produced by a workflow or by a hand-rolled `crosstalk run`. Treat every wake as a single task and just answer.
+
+## Addressing
+
+`to: model` (bare) reaches any machine claiming that model.
+`to: model@machine` narrows to one machine's dispatcher.
+
+## Delivery semantics
+
+**At-least-once.** Each dispatcher tracks one cursor recording the git commit the transport was last scanned at. If a machine crashes mid-tick, the next tick re-dispatches anything not 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 (sending email, file deletion, payments), check the channel for evidence of prior completion before acting.
+
+## Failure handling
+
+If your invocation fails (non-zero exit, no stdout when stdout was required, timeout), the dispatcher writes a failure reply with `failed: true` and `error: <text>` in the frontmatter. This is a normal message that wakes the original sender the same as a success reply. There is no DLQ subsystem and no retry subcommand.
+
+## Frontmatter contract (v7)
+
+Required fields the runtime writes on every message: `from`, `to`, `timestamp`. Optional fields: `re`, `as`, `child_channel`, `failed`, `error`. The `type:` field is only valid as `type: workflow` on workflow documents — any other value (including v6's `type: text`) is a protocol violation and gets rejected by the dispatcher at parse time.
+
+## Do not
+
+- **Write YAML frontmatter or files under `data/channels/` by hand** — the cardinal sin. Use stdout or `crosstalk run`.
+- Reply to messages addressed to other actors or models.
+- Fabricate channel UUIDs — list `data/channels/` or run `crosstalk status`.
+- Use your model-native memory or scratchpad systems for cross-session state — the channel IS your state.
+- Hand-write `type: text` in any frontmatter — v6 muscle memory. v7 messages omit `type:` on regular messages.

package/template/README.md

@@ -0,0 +1,69 @@
+# transport/ — the seed template
+
+> Part of the [Crosstalk repo](../README.md) — the root README has the full problem statement, solution overview, and repository layout. The other tier in the same repo is the [runtime](../runtime/) (the `crosstalk` CLI itself).
+
+Source-of-truth content that `crosstalk init` copies into every new transport. Not a runtime artifact, not a published package on its own — it lives here in the monorepo so a single edit propagates to the npm tarball at build time.
+
+> **What Crosstalk is.** Crosstalk is an agent-agnostic swarm communication protocol built on git. A git repo is the message bus. Full background: **[the root README](../README.md)**.
+
+---
+
+## What lives here
+
+| File | Purpose in the scaffolded transport |
+|---|---|
+| `CROSSTALK-VERSION` | Protocol version this transport is on (`7`). The runtime checks compatibility on every boot and refuses to dispatch against an incompatible version. |
+| `CROSSTALK.md` | **The protocol specification.** Every behavioral rule the runtime obeys — message shape, activation, batching, cursors, durability semantics — is defined here. Authoritative. |
+| `PROTOCOL.md` | Agent-facing orientation: prepended to every dispatched model's prompt so a fresh invocation knows it's running inside a Crosstalk transport and what's expected of it. |
+| `data/models.yaml` | Seed model registry. Operators edit this file to add or remove model entries. Each dispatcher claims the models whose CLI is on its PATH. |
+| `local/actors/orchestrator.md` | Persona file for the orchestrator actor. Teaches a model how to interpret workflow markdown documents. Used implicitly when `--as orchestrator` is passed or when a workflow document is dispatched. |
+| `CLAUDE.md` | Repo-style orientation for an AI coding agent that lands inside the transport directory. Mirrors the librarian / monorepo convention used across Cordfuse projects. |
+| `gitignore` | Becomes the transport's `.gitignore` after init renames it. (npm strips files literally named `.gitignore` from published tarballs; we ship it without the leading dot and the runtime renames it on copy.) |
+
+What does **not** live here:
+
+- `data/channels/<uuid>/` — created on demand by `crosstalk channel <name>`.
+- `local/actors/<other>.md` — operator-authored, not in the template.
+- `workflows/` — convention not enforced; operators put workflow markdown wherever they like.
+- `hosts/` — v7 has no host files. Routing is by `--alias` flag at dispatch boot.
+- `README.md` for the operator's own transport — that is their content, not ours.
+
+---
+
+## How `crosstalk init` consumes this
+
+At publish time, `runtime/package.json`'s `prepack` script copies this entire directory into `runtime/template/`, which is what ships inside the npm tarball:
+
+```json
+"prepack": "cp -r ../transport template && cp ../GUIDE-CLI.md ../GUIDE-PROMPTS.md ."
+```
+
+At install time, `crosstalk init <dir>`:
+
+1. Finds the bundled template (first under `runtime/template/`, falling back to `../transport/` in a monorepo dev checkout).
+2. Recursively copies the template into the target directory.
+3. Renames the copied `gitignore` to `.gitignore`.
+
+That is the whole init sequence. No host file is generated. No first channel is generated. Operators create their first channel with `crosstalk channel <name>` and start sending.
+
+The runtime never reads from this directory at dispatch time — only at `init` time, and only from the bundled copy.
+
+---
+
+## Editing the template
+
+Anything in this directory is the source of truth for every future transport scaffolded by `crosstalk init`. Edit conservatively:
+
+- **`CROSSTALK.md`** — only when changing the protocol itself. Bump `CROSSTALK-VERSION` in the same change.
+- **`PROTOCOL.md`** — when the agent-facing contract changes (new envelope fields, new activation rules). Agents inherit this at dispatch time, so changes affect every actor immediately on next dispatch.
+- **`data/models.yaml`** — when the canonical seed set of models changes. Operators edit their own copy after init, so changes here only affect *newly initialized* transports.
+- **`local/actors/orchestrator.md`** — when the orchestrator persona needs to teach a different workflow interpretation model.
+- **`CLAUDE.md`** — orientation for repo-savvy agents that land inside a transport directory.
+
+Existing transports do **not** automatically pick up template changes. There is no `crosstalk upgrade` subcommand in v7 — operators wanting newer template content can manually copy the file they want.
+
+---
+
+## License
+
+MIT. See [LICENSE](../LICENSE).

package/template/data/models.yaml

@@ -0,0 +1,27 @@
+# Crosstalk model registry.
+#
+# Each entry maps a model name (used in --to) to a shell command that
+# invokes the model in non-interactive mode. The runtime appends the
+# message body as the final positional argument, with stdin fallback
+# for prompts > 64 KB.
+#
+# Each dispatcher reads this file, takes the first token of each entry,
+# and checks PATH. Only models whose CLI is installed locally are
+# claimed by that dispatcher.
+#
+# Adding a model: append a line and commit. No PR to the crosstalk
+# runtime needed. For private agents: drop a wrapper script
+# `crosstalk-myagent` on PATH and reference it here.
+#
+# Tip: agent CLIs accept aliases (sonnet, opus, haiku, etc.) that auto-
+# track the latest model version. Prefer aliases over pinned full names
+# unless you need a specific version.
+
+sonnet:      claude --print --model sonnet --dangerously-skip-permissions
+haiku:       claude --print --model haiku --dangerously-skip-permissions
+opus:        claude --print --model opus --dangerously-skip-permissions
+codex-o3:    codex exec --model o3
+gemini-pro:  gemini --skip-trust --yolo -p --model gemini-1.5-pro
+qwen3-coder: qwen --yolo --model qwen3-coder
+opencode:    opencode -p
+agy:         agy -p

package/template/gitignore

@@ -0,0 +1,4 @@
+.DS_Store
+Thumbs.db
+node_modules/
+.turnq/