@cordfuse/crosstalk 7.0.0-alpha.9 → 7.0.0-beta.1

package/template/CROSSTALK.md

@@ -0,0 +1,262 @@
+# 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 the crosstalk engine (`crosstalk daemon dispatch`, spawned by `crosstalk server start` or systemd). Identifies itself via `CROSSTALK_ALIAS` (defaults to the transport name). |
+| **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/crosstalk.yaml` — one file, shared by everyone. Schema is nested under providers (alpha.8+):
+
+```yaml
+providers:
+  anthropic-personal:
+    env_file: auth/anthropic-personal.env
+    models:
+      sonnet: claude --print --dangerously-skip-permissions --model sonnet
+      haiku:  claude --print --dangerously-skip-permissions --model haiku
+  google-personal:
+    env:
+      GEMINI_API_KEY: ${GOOGLE_PERSONAL_KEY}
+    models:
+      gemini-pro: gemini --skip-trust --yolo -p --model gemini-1.5-pro
+```
+
+Models are addressed as `provider/model` (e.g. `anthropic-personal/sonnet`). Bare `<model>` is also accepted when exactly one claimed model has that name; ambiguous bare names fail with a pick-list.
+
+**Command contract.** Each model's command is a whitespace-tokenized argv list — **not** a shell pipeline. The runtime splits on whitespace, treats the first token as the binary, and appends the message body as the final positional argument (stdin fallback for prompts > 64 KB). Quoting (`'…'`, `"…"`), command substitution (`$(…)`), pipes (`|`), and redirections (`>`, `<`) are NOT interpreted — they pass through as literal argv characters. If you need shell features, write a wrapper script and reference its path in the command. Wrappers can read the prompt from `$1` (the final argv) — never assume it's on stdin.
+
+**Per-provider auth.** Two layouts coexist per provider:
+- `env_file: <relpath>` — dotenv file, raw secrets, gitignore the file.
+- `env: { KEY: ${HOST_VAR} }` — inline ${HOST_VAR} references resolved from process.env at spawn. Raw values rejected at parse time.
+
+Spawn precedence (last-wins): `process.env → env_file → env → dispatch metadata`. See `auth/README.md` for per-agent recipes.
+
+**PATH-based self-selection.** Each dispatcher reads `data/crosstalk.yaml` at boot, takes the first token of each model'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 any model that maps to those CLIs; a server with only `claude` claims just the Claude entries.
+
+**Skip-bad-provider (alpha.11+).** A single typo'd provider is logged to stderr and skipped; the rest of the registry loads. The engine never goes dark on one bad entry.
+
+Adding a new model = one line under a provider in `data/crosstalk.yaml`. No PR to crosstalk. Custom or private agents: drop a wrapper script `crosstalk-myagent` on PATH and reference it in the command.
+
+---
+
+## 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.
+
+No `orchestrator` actor exists. Workflows are runtime-managed (see below); the model never plays an orchestration role, only content roles (drafting, synthesizing).
+
+---
+
+## Workflows
+
+A workflow is a markdown document with `type: workflow` in the frontmatter. Body is plain prose — no YAML steps, no `to:`, no `as:`:
+
+```markdown
+---
+type: workflow
+---
+
+Fan out 3 junior-developer drafts of the proposal using sonnet. Have opus synthesize the strongest unified version.
+```
+
+When the operator runs `crosstalk run --type workflow <file>`:
+
+1. **Marker**: the document is written into the operator's current channel as a marker message addressed to the reserved recipient `workflow`. The frontmatter includes `child_channel: <uuid>` (a new sibling channel for the workflow's sub-traffic) and `dispatch_host: <alias>` (the dispatcher that owns this workflow's progression — exactly one).
+2. **Compile pass**: the owning dispatcher's `workflowTick` invokes the first claimed model with a fixed `COMPILE_PROMPT` against the workflow body. The model returns a JSON plan: `{fanout: {to, count, body}, synthesize: {to, body}}`. The plan is persisted at `data/channels/<child>/PLAN.json` (idempotency: re-running compile would be wasteful and PLAN.json's existence guards against it).
+3. **Fanout dispatch**: the owning dispatcher writes `plan.fanout.count` sub-primitives into the child channel. Recipients are scoped (`to: <model>@<dispatcher-alias>`, round-robined across the dispatcher registry) to avoid duplicate work under at-least-once activation.
+4. **Synthesize dispatch**: once all fanout replies are in (re:-linked), the owning dispatcher writes one synthesis sub-primitive: `body = plan.synthesize.body + "\n\n" + concatenated candidates`. Pinned to a single dispatcher (no replication).
+5. **Route**: when the synthesis reply lands, the owning dispatcher writes a final reply in the **parent** channel addressed to the workflow marker's `from:`, `re:`-linked back to the marker. A `COMPLETE` side file in the child channel marks the workflow done so future ticks skip it.
+
+The model never sees state machinery: each invocation is a single-turn content task (draft, synthesize). The runtime owns orchestration deterministically. Failures (invalid compile output, unclaimed model in the compiled plan, fanout sub-failures) propagate as `failed: true` reply messages.
+
+---
+
+## 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`, then deleted entirely — see Workflows), the orchestrator actor itself, `crosstalk attach/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.
+
+Alpha.18 (the v8-native series) dropped the Docker container deployment and the dual-package split. Operators now install a single npm package — `@cordfuse/crosstalk` — that contains both the operator CLI and the engine. The engine runs as a native host process (or systemd unit), spawned by `crosstalk server start`; the dispatch loop itself lives as the internal subcommand `crosstalk daemon dispatch`. There is no `crosstalk-server` container and no separate `@cordfuse/crosstalkd` package (the latter is deprecated on npm).
+
+Subcommand surface (alpha.18+, strict noun-verb, mirrors `@cordfuse/llmux`):
+- `auth login|logout|whoami|list|use` · `token create|list|revoke|rename`
+- `server start|stop|restart|status|logs` · `transport init|rm`
+- `channel list|create|rename|delete` · `message send|replies`
+- `workflow compose|run|status` · `chat <agent>` · `agent list`
+- `logs list|tail` · `settings show` · `status` · `version`
+- `daemon dispatch|init|stop` (internal — spawned by `server start` + systemd)
+
+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,70 @@
+# 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 message send` (primitives) or `crosstalk workflow run` (workflows). 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 message send` 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 message 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 message send --to <model>[@<machine>] [--as <persona>] [--fanout <n>] [--channel <name|uuid>] <body|file|->` — 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. `<body>` can be inline, a file path, or `-` for stdin. Prints the sent relPath — keep it if you are orchestrating.
+- `crosstalk workflow run <file>` — dispatch a workflow document (markdown with `type: workflow` frontmatter) from a file path. The runtime auto-creates a child channel and runs compile → fanout → synthesize → route.
+- `crosstalk workflow compose "<prose>"` — interactive variant: the engine compiles your prose into a workflow plan, surfaces the YAML for `[y]es / [e]dit / [n]o` review, then submits.
+- `crosstalk message replies <relPath> [<relPath>...]` — shows which of your dispatched messages have replies. Exits 0 when every target is REPLIED or FAILED, 2 while anything is PENDING. This is ground truth: replies are matched by the runtime-written `re:` field, not by anything a peer claims in its body.
+- `crosstalk status` — transport snapshot: channels (name → uuid), dispatcher heartbeat, claimed models, error count.
+- `crosstalk channel list` — list all channels with their UUIDs.
+- `crosstalk channel create <name>` — create a channel; prints its UUID.
+- `crosstalk channel rename <handle> <new-name>` — rename a channel (handle = name or UUID).
+- `crosstalk channel delete <handle>` — delete a channel (the verb is your explicit consent).
+
+There is no `wake` subcommand — `crosstalk message send` automatically pokes the dispatcher.
+
+## Workflows
+
+A workflow is a markdown document with `type: workflow` in the frontmatter, dispatched via `crosstalk workflow run <file>` (or `crosstalk workflow compose "<prose>"` for the interactive prose variant). 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 message send`. 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 message send`.
+- Reply to messages addressed to other actors or models.
+- Fabricate channel UUIDs — run `crosstalk channel list` or `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,64 @@
+# transport/ — the seed template
+
+> Part of the [Crosstalk repo](../README.md) — the root README has the full problem statement, solution overview, and repository layout. As of alpha.18 the engine and operator CLI ship as one npm package (`@cordfuse/crosstalk`); the daemon is an internal subcommand (`crosstalk daemon dispatch`), not a separate binary.
+
+Source-of-truth content that `crosstalk daemon init` copies into every new transport. Not a runtime artifact, not a published package on its own — it lives here in the monorepo and gets bundled into the published npm tarball at `prepack` time (`package.json` copies `transport/` → `template/`).
+
+> **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/crosstalk.yaml` | Seed provider + model registry. Operators edit this file to add or remove providers and models. Each dispatcher claims the models whose CLI is on its PATH. |
+| `local/actors/` | Optional persona files (`<name>.md` each). Operator-authored. Empty by default in alpha.1+ — the v6/early-v7 `orchestrator.md` persona was deleted when workflows became runtime-managed (see `CROSSTALK.md` § Workflows). |
+| `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 create <name>`.
+- `local/actors/<name>.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 `CROSSTALK_ALIAS` (dispatcher boot env) or the transport name.
+- `README.md` for the operator's own transport — `crosstalk daemon init` generates a minimal one but operators edit freely.
+
+---
+
+## How `crosstalk transport init` consumes this
+
+Alpha.18 ships the template inside the npm tarball at `template/` (copied from `transport/` by `package.json` `prepack`). At install time, `crosstalk transport init` (the operator verb) calls into `crosstalk daemon init <target-dir>` under the hood, which:
+
+1. Finds the bundled template at `<package-root>/template/` (or `<repo-root>/transport/` in monorepo dev).
+2. Recursively copies the template into the target directory under the operator's storage base.
+3. Renames the copied `gitignore` to `.gitignore`.
+
+`crosstalk transport init` then runs `git init --initial-branch=main && git add -A && git commit -m "initial transport"` so the operator's local git config is the author identity, allocates a free API port, and records it at `<base>/<name>/api-port`.
+
+No host file is generated. No first channel is generated. Operators create their first channel with `crosstalk channel create <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 transport 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, new CLI verbs the agent should use). Agents inherit this at dispatch time, so changes affect every actor immediately on next dispatch.
+- **`data/crosstalk.yaml`** — when the canonical seed set of providers/models changes. Operators edit their own copy after init, so changes here only affect *newly initialized* transports.
+- **`CLAUDE.md`** — orientation for repo-savvy agents that land inside a transport directory.
+
+Existing transports do **not** automatically pick up template changes. Operators wanting newer template content can manually copy the file they want (or re-init fresh and migrate `data/`).
+
+---
+
+## License
+
+MIT. See [LICENSE](../LICENSE).

package/template/auth/README.md

@@ -0,0 +1,224 @@
+# Auth recipes — per-agent env vars
+
+Two layouts. Pick whichever fits — they coexist per provider in `data/crosstalk.yaml`.
+
+**`env_file:`** — points at a dotenv file under this directory. Engine reads it at agent spawn and merges KEY=VALUE pairs into the subprocess env. The dotenv file holds the raw secrets; it's operator-edited and should be gitignored (the `auth/` directory is gitignored by default in the transport scaffold).
+
+```yaml
+providers:
+  anthropic-personal:
+    env_file: auth/anthropic-personal.env
+    models:
+      sonnet: claude --print --dangerously-skip-permissions --model sonnet
+```
+
+**`env:`** (alpha.10) — inline map per provider. Values MUST be `${HOST_VAR}` references; raw secrets are refused at parse time so the yaml stays committable. Engine resolves each `${HOST_VAR}` from the host process environment at spawn time. Export the vars before `crosstalk up` (your shell rc, a sourced .env file, your secret store, etc.). Useful when running multiple accounts of the same provider so the provider→credential mapping is visible in one file.
+
+```yaml
+providers:
+  google-personal:
+    env:
+      GEMINI_API_KEY: ${GOOGLE_PERSONAL_KEY}
+    models:
+      gemini-pro: gemini --skip-trust --yolo -p
+
+  google-work:
+    env:
+      GEMINI_API_KEY: ${GOOGLE_WORK_KEY}
+    models:
+      gemini-work: gemini --skip-trust --yolo -p
+```
+
+**Both at once.** A provider can declare both `env_file:` AND `env:`. Precedence at spawn (last-wins): `process.env → env_file → env → dispatchEnv`. So `env:` overrides `env_file:` per-key — bulk-load from a file and override a single key inline.
+
+**If a value is wrong** or a referenced `${VAR}` is missing on the host, the agent CLI surfaces its own auth error and the dispatched message gets a `failed: true` reply with the error text (claude writes to stdout, codex to stderr — both are captured in alpha.9+).
+
+**Mode 0600 recommended** for `env_file:` paths. Crosstalk doesn't enforce it.
+
+---
+
+## Command contract (how the agent CLI is invoked)
+
+The `<cli command>` value under each provider's `models:` is a **whitespace-tokenized argv list, not a shell pipeline.** The first token is the binary, the rest are static argv passed to it, and the runtime appends the message body as the **final positional argument** (stdin fallback when the prompt > 64 KB).
+
+This matters when wiring a new agent:
+- Quoting (`'…'`, `"…"`), command substitution (`$(…)`), pipes (`|`), and redirection (`>`, `<`) **do not work** — they pass through as literal argv characters. A `models: m: bash -c 'echo X'` line will break at runtime because `'echo`, `X'` arrive as separate argv entries.
+- Most agent CLIs work fine because their invocation IS pure argv: `claude --print --model sonnet`, `gemini --skip-trust --yolo -p`, `codex exec --model o3`. The runtime appends the body, the CLI reads it as the trailing positional, done.
+- For agents that genuinely need shell features (a script that pipes the prompt, transforms it, sets a dynamic env), write a wrapper script that reads the prompt from `$1` and drop it at `/crosstalk-root/.local/bin/<name>` inside the container (via `crosstalk chat --shell`). That directory is already on `$PATH` AND lives under the persistent `/crosstalk-root` volume, so the wrapper survives `crosstalk restart`. **Do not use `/usr/local/bin/`** — it's in the container's writable layer and gets wiped on every restart, so a wrapper there is gone before the dispatcher can claim it.
+
+Example:
+```sh
+crosstalk chat --shell
+  cat > /crosstalk-root/.local/bin/qwen-via-pipe <<'WRAP'
+  #!/usr/bin/env bash
+  exec qwen --yolo --model qwen3-coder <<<"$1"
+  WRAP
+  chmod +x /crosstalk-root/.local/bin/qwen-via-pipe
+  exit
+crosstalk restart            # rescan PATH so the wrapper gets claimed
+```
+
+Then in `crosstalk.yaml`:
+```yaml
+providers:
+  custom-qwen:
+    env_file: auth/openrouter.env
+    models:
+      piped: qwen-via-pipe
+```
+
+**Absolute paths also work (alpha.12+).** If you'd rather keep wrappers organised under their own directory (`/crosstalk-root/wrappers/`, anywhere persistent), reference the absolute path directly: `piped: /crosstalk-root/wrappers/qwen-via-pipe`. The dispatcher resolves absolute first tokens by stat'ing the file rather than walking PATH.
+
+**Skip-bad-provider / skip-bad-model.** A typo'd provider (alpha.11+) or an unreachable model binary (alpha.12+) doesn't dark every agent on the dispatcher — it's logged to stderr (visible via `crosstalk logs` or `docker logs`) and skipped. The rest of the registry loads. If a wrapper you've just dropped doesn't appear in `claimed_models`, check the logs for the exact reason (wrong path, not executable, etc.).
+
+---
+
+## claude (Claude Code)
+
+Two paths:
+
+```
+# auth/anthropic-personal.env
+
+# Option 1 — subscription OAuth token (preferred for personal use):
+#   On a host with a browser, run once:  claude setup-token
+#   Copy the printed token here.
+CLAUDE_CODE_OAUTH_TOKEN=
+
+# Option 2 — Console API key (preferred for headless / CI):
+#   Get from console.anthropic.com.
+# ANTHROPIC_API_KEY=
+```
+
+**Precedence:** if both are set, `CLAUDE_CODE_OAUTH_TOKEN` wins.
+
+---
+
+## gemini (Google Gemini CLI)
+
+```
+# auth/google-personal.env
+
+# Get key: https://aistudio.google.com/apikey
+GEMINI_API_KEY=
+```
+
+**Required CLI flag:** `gemini --skip-trust` (already in the template). Without it gemini refuses to start headless.
+
+Vertex AI / Code Assist (GCA) alternatives: set `GOOGLE_GENAI_USE_VERTEXAI=1` or `GOOGLE_GENAI_USE_GCA=1` instead. See the gemini-cli docs for the full env list.
+
+---
+
+## agy (Antigravity CLI)
+
+Reads `GEMINI_API_KEY` — same env var as gemini-cli. Two reasonable patterns:
+
+- **Share one env file** with the google-* provider (the template's `google-agy` example points to `auth/google-personal.env`).
+- **Isolated keys** — declare a separate `google-agy` provider with its own `auth/agy.env`.
+
+agy also supports interactive Google OAuth (browser flow), but the env-key path is what crosstalk drives.
+
+---
+
+## codex (OpenAI Codex CLI)
+
+**Codex doesn't read env vars for auth.** It uses its own credential store at `~/.codex/auth.json`. Run once via `crosstalk chat --shell`:
+
+```
+crosstalk chat --shell
+  echo "$OPENAI_API_KEY" | codex login --with-api-key
+  exit
+```
+
+The credential file persists in `/crosstalk-root/.codex/` across container restarts. No `env_file:` needed on the codex provider — leave it off entirely.
+
+**Multi-account?** Express HOME isolation in the model's `cli:` string:
+
+```yaml
+openai-codex-work:
+  models:
+    codex-work: env HOME=/var/lib/crosstalk-transport/auth/homes/codex-work codex --skip-git-repo-check
+```
+
+Then `codex login --with-api-key` in that HOME gives you a second account, isolated.
+
+---
+
+## qwen (Qwen Code CLI)
+
+Multi-provider via `--auth-type`. The OpenAI-compatible path is the cleanest headless route:
+
+```
+# auth/openrouter.env  (or any OpenAI-compat backend)
+OPENAI_API_KEY=sk-or-v1-...
+OPENAI_BASE_URL=https://openrouter.ai/api/v1
+```
+
+**Required CLI flags:** `qwen --auth-type openai --yolo --model <provider/model>` (e.g. `qwen/qwen3-coder` on OpenRouter). The model id must match the backend's catalog.
+
+Qwen's native OAuth tier was discontinued 2026-04-15 — use the env-key path.
+
+---
+
+## opencode
+
+Reads multiple env vars depending on what providers you've configured:
+
+- `OPENROUTER_API_KEY` — native OpenRouter integration
+- `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, etc. — per-provider keys
+- Or its own config at `~/.config/opencode/`
+
+Mix and match per-provider in `data/crosstalk.yaml`:
+
+```yaml
+openrouter:
+  env_file: auth/openrouter.env       # OPENAI_API_KEY + OPENAI_BASE_URL (compat shim)
+  models:
+    opencode-or: opencode --model qwen/qwen3-coder
+```
+
+---
+
+## Local Ollama
+
+```
+# auth/ollama-local.env
+OPENAI_API_KEY=ollama                 # any non-empty string works — ollama has no auth
+OPENAI_BASE_URL=http://host.docker.internal:11434/v1
+```
+
+For a remote ollama on the tailnet (the "one GPU box serves the swarm" pattern):
+
+```
+# auth/ollama-tailnet.env
+OPENAI_API_KEY=ollama
+OPENAI_BASE_URL=http://100.x.x.x:11434/v1     # the GPU host's Tailscale IP
+```
+
+Then point qwen, codex, opencode (any OpenAI-compat client) at it.
+
+---
+
+## OpenRouter
+
+A gateway, not an agent. Use as the OpenAI-compat backend for codex / qwen / opencode:
+
+```
+# auth/openrouter.env
+OPENAI_API_KEY=sk-or-v1-...
+OPENAI_BASE_URL=https://openrouter.ai/api/v1
+```
+
+**Model ids** carry the provider prefix: `qwen/qwen3-coder`, `google/gemini-2.5-pro`, `anthropic/claude-sonnet-4-5`, etc. Pass via `--model` in the `cli:` string.
+
+---
+
+## How env files are read
+
+Standard dotenv:
+- `KEY=value` per line
+- Lines starting with `#` are comments
+- Blank lines ignored
+- No shell expansion, no escaping — value is taken literally after the first `=`
+
+No special quoting. If your value has a `#`, it's still part of the value (not a comment).