@cordfuse/crosstalkd 7.0.0-alpha.1

package/GUIDE-CLI.md

@@ -0,0 +1,315 @@
+# Crosstalk CLI Guide
+
+> **This guide is being rewritten for v7.0.0-alpha.1's engine/client split.** The body below describes the original pre-split surface — host commands like `crosstalk dispatch` and `crosstalk stop` no longer exist. Live surface is documented inline via `crosstalk --help` (host client, 12 subcommands) and `crosstalkd --help` inside the container (engine, 7 subcommands).
+>
+> **Quick mapping for operators upgrading from a pre-split build:**
+> - `crosstalk init <dir>` — works (now also auto-`git init`s on `main`)
+> - `crosstalk up` / `down` / `restart` / `pull` / `logs` — new (manage the engine container)
+> - `crosstalk dispatch` — gone from host; engine runs inside the container, managed via `crosstalk up`
+> - `crosstalk stop` — gone from host; `crosstalk down` stops the container
+> - `crosstalk run` / `replies` / `status` / `channel` — same surface, now talks to the engine via HTTP API on 127.0.0.1
+> - `crosstalk chat [--agent X] [--login] [--shell]` — new (single interactive entry point — daily agent chat, OAuth flow with browser-open, sysadmin shell)
+>
+> A proper rewrite of this guide ships in v7.0.0-alpha.2.
+
+---
+
+> **Original (pre-split) reference — preserved for now:**
+
+Quick reference for the `crosstalk` CLI. Run `crosstalk <subcommand> --help` for flags.
+
+Requires: Node.js ≥ 20. All subcommands (except `init` and `version`) must be run from inside a transport (a directory containing `CROSSTALK-VERSION`).
+
+The whole surface is **eight subcommands**: `init`, `run`, `dispatch`, `stop`, `status`, `replies`, `channel`, `version`.
+
+---
+
+## Setup
+
+### `crosstalk init <dir>`
+
+Scaffold a new transport in the given directory:
+
+```sh
+mkdir my-transport && cd my-transport
+git init
+crosstalk init .
+```
+
+Copies the template into the directory:
+
+- `CROSSTALK-VERSION` — protocol version (`7`). The runtime checks this on every boot and refuses to operate on incompatible transports.
+- `PROTOCOL.md` — agent orientation file; the dispatcher prepends this to every model invocation.
+- `CROSSTALK.md` — the protocol specification for humans.
+- `data/models.yaml` — the model registry seed. Edit this to add or remove model entries.
+- `local/actors/orchestrator.md` — the orchestrator persona file (interprets workflow documents).
+- `CLAUDE.md` — agent orientation for repo-savvy CLIs landing inside the transport.
+
+What `init` does **not** do:
+
+- No host file is generated. v7 has no host files at all — machine identity comes from `--alias` at dispatch boot.
+- No first channel is created. Make one yourself with `crosstalk channel <name>`.
+- No git remote is configured.
+
+Commit and push to your git remote when you have one; that repo is now the message bus. Single-machine and local-only is fine — you can skip the remote entirely while you're trying things out.
+
+---
+
+## Models
+
+Crosstalk is **agent-agnostic**. A "model" in v7 is a named entry in `data/models.yaml` mapping a name to a shell command that invokes some agent CLI in non-interactive mode.
+
+```yaml
+# data/models.yaml
+sonnet:      claude --print --model claude-sonnet-4 --dangerously-skip-permissions
+haiku:       claude --print --model claude-haiku-4-5 --dangerously-skip-permissions
+opus:        claude --print --model claude-opus-4 --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
+```
+
+### PATH-based self-selection
+
+Each dispatcher reads `data/models.yaml` at boot, takes the first token of each entry (`claude`, `codex`, `gemini`, …), and checks PATH. **Only models whose CLI is installed locally are claimed.** No declarations, no host files.
+
+A laptop with `claude` and `gemini` installed claims `sonnet`, `haiku`, `opus`, `gemini-pro`. A server with only `claude` claims just the Claude entries.
+
+### The dispatch contract
+
+When the dispatcher invokes a model it:
+
+1. Composes `[persona-file body] + [pending messages]` and **appends it as the last argument** to the shell command.
+2. Reads the CLI's **stdout** as the reply body; expects exit code **0**.
+
+Two things to get right per model:
+
+- **Non-interactive flag.** Each agent has a flag that stops it from pausing for confirmation or opening a TUI. Without it, every dispatch hangs.
+- **Trailing-argument shape.** The dispatcher tacks the prompt on the end of whatever you put in the command. `claude --print` becomes `claude --print "<prompt>"`. Every modern agent CLI accepts this shape.
+
+> For prompts larger than 64 KB, the dispatcher falls back to writing the prompt to **stdin** automatically.
+
+### Recipes
+
+Starting points — **verify flags against your installed CLI version**; vendors change them.
+
+| Agent | Example entry | Notes |
+|---|---|---|
+| Claude Code | `sonnet: claude --print --dangerously-skip-permissions` | accepts the prompt as a positional arg |
+| OpenAI Codex | `codex-o3: codex exec --model o3` | `exec` is non-interactive. Auth: `OPENAI_API_KEY` in env is not sufficient on its own — Codex caches mode in `~/.codex/auth.json`; run `printenv OPENAI_API_KEY \| codex login --with-api-key` once per fresh volume. |
+| Gemini CLI | `gemini-pro: gemini --skip-trust --yolo -p` | `--skip-trust` is required for headless dispatch; `--yolo` skips approvals; `-p` must be last so it captures the appended prompt. |
+| Qwen Code | `qwen3-coder: qwen --yolo` | `--yolo` skips approvals; prompt is appended as positional. |
+| opencode | `opencode: opencode -p` | `-p` = one-shot, OAuth via `opencode auth login`. Auth persists in `~/.local/share/opencode/auth.json`. |
+| Antigravity | `agy: agy -p` | `-p` is non-interactive. OAuth-only in 1.0.7 — no API-key env-var path; complete the device-code sign-in once interactively per fresh volume. |
+
+You can mix agents in one transport — different models can run entirely different vendors. Senders never know or care which agent answered.
+
+> **Privacy note for shared infrastructure.** The prompt is passed as an argv arg, which means it's visible to anything that can read the dispatcher process's `/proc/<pid>/cmdline`. On a single-user laptop or dedicated dispatcher VM that's a non-issue; on multi-user machines, plan accordingly.
+
+---
+
+## 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 passed to `run`.
+
+```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 seed transport ships one actor: **`orchestrator`** — the persona that teaches a model how to interpret workflow markdown documents. Used implicitly when a workflow is dispatched.
+
+---
+
+## `crosstalk run`
+
+The unified dispatch verb. Two modes: `primitive` (atomic single send, optionally fanned-out) and `workflow` (orchestrator-interpreted multi-step document).
+
+### Primitive
+
+```sh
+crosstalk run --type primitive --to sonnet@laptop "What is the capital of France?"
+```
+
+Prints `Sent: <relPath>` — save that path if you need to check for replies.
+
+| Flag | Required | Notes |
+|---|---|---|
+| `--type primitive` | yes | distinguishes from workflow |
+| `--to <model>[@<machine>]` | yes | bare model name reaches any dispatcher claiming it; `@<machine>` pins to one alias |
+| `--as <actor>` | no | persona file from `local/actors/<actor>.md`, prepended as system context |
+| `--fanout <n>` | no, default 1 | parallel instances of the same send; all N replies share `from:`, differentiated by relPath |
+| `--channel <name-or-uuid>` | only if multiple channels exist | auto-detected when transport has exactly one channel |
+| `--from <name>` | no | defaults to `$USER` / `operator` |
+| `--new` | no | suppress automatic `re:` linking (start new work, not a reply) |
+| `<body>` | yes | inline string, file path, or `-` for stdin |
+
+### Workflow
+
+```sh
+crosstalk run --type workflow workflows/review-and-synthesize.md
+crosstalk run --type workflow -                   # stdin
+```
+
+The document's frontmatter must declare:
+
+```yaml
+---
+type: workflow
+to: opus@cachy
+as: orchestrator
+---
+
+1. Fan out 3 junior developers running sonnet@laptop.
+2. Send the drafts to a reviewer running opus@cachy.
+3. Return the synthesis to the original requester.
+```
+
+At dispatch the runtime:
+
+1. Creates a new child channel parented to the operator's current channel.
+2. Writes the workflow document as a message into the parent channel addressed to the declared model with `as: orchestrator`.
+3. Adds `child_channel: <uuid>` to the dispatched message's frontmatter; the dispatcher injects this as `CROSSTALK_CHILD_CHANNEL` when invoking the orchestrator.
+4. The orchestrator persona interprets the steps and fires sub-`crosstalk run --type primitive` calls into the child channel.
+
+| Flag | Required | Notes |
+|---|---|---|
+| `--type workflow` | yes | |
+| `--channel <name-or-uuid>` | only if multiple channels exist | runs the workflow inside an existing channel instead of auto-creating a child |
+| `<file-or-->` | yes | path to a workflow markdown document, or `-` to read from stdin |
+
+---
+
+## `crosstalk dispatch --alias <name>`
+
+Start the dispatch loop in the current transport. Runs forever, polling for new messages, invoking claimed models.
+
+```sh
+crosstalk dispatch --alias laptop &
+```
+
+| Flag | Required | Notes |
+|---|---|---|
+| `--alias <name>` | yes | this machine's identity within the bus; appears in `from:` of replies and routing targets in `to:` |
+| `--poll <seconds>` | no, default 30 | quiet-tick interval; active ticks drop to 1s automatically |
+| `--json` | no | structured JSON log lines |
+| `--log-file <path>` | no | mirror logs to a file |
+| `--once` | no | run one tick then exit (useful for testing) |
+
+Dispatcher state (cursor, heartbeat, pidfile, wake.signal) is stored at `~/.config/crosstalk/state/<transport-name>/` — never in the transport repo. Four files, machine-global.
+
+### Stopping
+
+```sh
+crosstalk stop
+```
+
+Reads the pidfile, sends SIGTERM.
+
+---
+
+## Observability
+
+### `crosstalk status`
+
+Prints:
+
+- Transport root and protocol version
+- Channels (name → uuid)
+- Dispatcher heartbeat (last tick timestamp, current cursor SHA)
+- Claimed models on this machine (from `data/models.yaml` PATH-filter)
+
+```sh
+crosstalk status
+```
+
+### `crosstalk replies <relPath>...`
+
+Show which of your dispatched messages have replies. Matches via the runtime-written `re:` field — ground truth, not body-parsing.
+
+```sh
+crosstalk replies 2026/06/10/130847758Z-780a8b90.md
+crosstalk replies path1.md path2.md path3.md     # multiple, space-separated
+```
+
+---
+
+## Channels
+
+### `crosstalk channel <name>`
+
+Create a new channel and print its UUID.
+
+```sh
+crosstalk channel sprint-42
+```
+
+Errors on name collision (strict mode — duplicate names rejected at create time). Errors if `<name>` matches a UUID regex (reserved for the actual UUID).
+
+### `crosstalk channel <name-or-uuid> --rename <new>`
+
+Rename the channel. UUID stays; only the label changes. Errors on collision.
+
+```sh
+crosstalk channel sprint-42 --rename sprint-43
+```
+
+### `crosstalk channel <name-or-uuid> --delete`
+
+Hard delete the channel. `rm -rf data/channels/<uuid>/`, commit. Requires typed-name confirmation:
+
+```sh
+crosstalk channel sprint-42 --delete
+# prompt: type "sprint-42" to confirm deletion of channel sprint-42 (<uuid>):
+```
+
+No archive, no restore, no `--force` flag. History remains in `git log` if you ever need it back (`git revert` or `git checkout <commit> -- data/channels/<uuid>/`).
+
+For scripted deletion, pipe stdin: `echo sprint-42 | crosstalk channel sprint-42 --delete`.
+
+---
+
+## `crosstalk version`
+
+Print the installed runtime version.
+
+```sh
+crosstalk version
+```
+
+---
+
+## Common patterns
+
+**One-shot task from a script:**
+
+```sh
+crosstalk channel "batch-$(date +%s)" > /tmp/chan.txt
+crosstalk run --type primitive --to sonnet --channel "batch-$(date +%s)" "Summarise this file: ..."
+```
+
+**Check if fan-out replies are all in:**
+
+```sh
+crosstalk replies path1.md path2.md path3.md path4.md path5.md
+```
+
+**Send a multi-line prompt from a file:**
+
+```sh
+crosstalk run --type primitive --to sonnet ./prompt.md
+# or
+cat prompt.md | crosstalk run --type primitive --to sonnet -
+```
+
+**Troubleshooting a stuck dispatcher:**
+
+```sh
+crosstalk status         # check heartbeat freshness and last cursor SHA
+```
+
+If failures land in the channel as `failed: true` replies, inspect the channel directly — no separate DLQ subsystem.

package/GUIDE-PROMPTS.md

@@ -0,0 +1,107 @@
+# Crosstalk Natural-Language Guide
+
+> **Updated for v7.0.0-alpha.1's engine/client split.** Interactive mode is now via `crosstalk chat` (host client) — runs the agent CLI inside the engine container with the operator's TTY attached and the transport bind-mounted in. The agent sees the same `PROTOCOL.md` it would have natively.
+
+You don't have to memorise the `crosstalk` CLI to use Crosstalk. You can just **talk to it.**
+
+The interactive Crosstalk pattern in v7: **`cd` into a transport directory and run `crosstalk chat`.** That opens a PTY-attached `docker exec` session into the engine container, running your default agent CLI (`claude`; use `--agent <name>` for others). The transport's `PROTOCOL.md` orients the agent — it learns the layout, the six core nouns, and which `crosstalkd` commands (the in-container engine) it can run on your behalf. From there you speak in plain language; the agent translates into commands, waits for answers, and tells you what came back.
+
+```sh
+cd ~/my-transport && crosstalk chat
+> ask sonnet on cachy to summarise report.md
+```
+
+The agent CLI owns the (container's) terminal; Crosstalk owns the bus; they meet at the bind-mounted filesystem.
+
+> **New to Crosstalk?** The [main README](README.md) has the six-word glossary (Transport / Machine / Message / Model / Actor / Channel) plus a local-only quickstart. Worth a 60-second read first.
+
+This is the companion to the **[CLI guide](GUIDE-CLI.md)**. Same system, two front doors: type commands, or just speak.
+
+> The natural-language interface is **agent-agnostic**, like the rest of Crosstalk. Whatever coding agent you already run — Claude Code, Codex, Gemini, Qwen Code, opencode, Antigravity — can be your interactive front door, as long as it can read `PROTOCOL.md` and run shell commands.
+
+---
+
+## Starting an interactive session
+
+```sh
+cd ~/my-transport
+claude            # or: gemini --skip-trust, codex, agy, opencode, qwen
+```
+
+When the agent CLI starts, it reads `PROTOCOL.md` and any `CLAUDE.md` / `GEMINI.md` / equivalent orientation file at the transport root. Those files tell the agent it's inside a Crosstalk transport, list the six nouns, and document the `crosstalk` subcommands it can use to send messages on your behalf.
+
+You don't need to teach the agent anything. Start talking.
+
+> **Interactive ≠ being a model.** When you're talking to the agent this way, *you* (through the agent) are the human's front door. You are not a model in the bus and you do not process incoming messages. Leave message processing to the running dispatcher (`crosstalk dispatch --alias <name>`). Don't start a dispatcher from inside this session — it would compete with the one already running.
+
+---
+
+## The phrasebook
+
+Say it however feels natural; these are the intents the interactive agent recognises and what it does for you. The default `orchestrator` actor is referenced in some examples — it's the persona file `crosstalk init` ships, used for interpreting workflow documents. Substitute any other model name (`sonnet`, `opus`, `codex-o3`, …) or actor name you've wired up.
+
+| You say… | What happens |
+|---|---|
+| "ask sonnet to summarise `report.md`" | sends a primitive to `sonnet`, waits, surfaces the reply |
+| "ask sonnet on cachy to look for typos" | sends to `sonnet@cachy`, waits, reports back |
+| "fan out three drafts running sonnet" | runs `crosstalk run --type primitive --to sonnet --fanout 3 "..."`, surfaces all three replies when they arrive |
+| "in the *sprint-42* channel, ask opus to plan the work" | scopes the message to that channel by name |
+| "run this workflow" (with file path or pasted document) | dispatches a workflow document via `crosstalk run --type workflow`; auto-creates a child channel for the chatter |
+| "is the dispatcher alive?" / "check status" | runs `crosstalk status`, explains the heartbeat plainly |
+| "what failed?" | inspects the current channel for `failed: true` replies and summarises |
+| "make a channel called *release-7*" | runs `crosstalk channel release-7`, tells you the UUID |
+| "what channels exist?" | runs `crosstalk status`, lists channels by their human names |
+| "rename this channel to *release-8*" | runs `crosstalk channel <current> --rename release-8` |
+| "delete the *batch-old* channel" | runs `crosstalk channel batch-old --delete`, types the confirmation |
+| "tweak the orchestrator persona to be more terse" | edits `local/actors/orchestrator.md`, commits, pushes |
+| "add a new model called fable" | adds a line to `data/models.yaml`, commits, pushes |
+| "pull the latest" | runs `git pull --rebase` |
+
+There is no "what's in the DLQ?" — v7 has no DLQ. Failures land in the channel as normal messages with `failed: true` + `error:` in frontmatter; "what failed?" asks the agent to grep the current channel for those.
+
+---
+
+## Coordinating a team in plain language
+
+The real power is workflows. Describe the goal and let the orchestrator dispatch:
+
+> **You:** "Ask the orchestrator on cachy to fan out three drafts of the release notes via sonnet, then have opus review and synthesize them."
+
+The interactive agent translates that into a workflow document, runs `crosstalk run --type workflow -` (stdin), and the runtime auto-creates a child channel for the work. The orchestrator on cachy receives the workflow, parses the prose, fires the sub-primitives into the child channel, waits for replies via `re:` links, aggregates, and posts the synthesis back to you in the parent channel. You see:
+
+> *(waiting for orchestrator…)*
+> **opus@cachy:** Synthesis attached. All three drafts emphasized X; consolidated and tightened. …
+
+You never see the orchestration — only the result. To drill into how the work happened, ask "show me the child channel for that workflow."
+
+---
+
+## What to expect
+
+- **It's asynchronous.** Each round-trip is roughly 5–30 seconds — your message is committed and pushed, the recipient's dispatcher polls, the agent runs, its reply is committed and pulled back. The interactive agent will say something like *"(waiting for sonnet…)"* and surface the answer when it arrives.
+- **Replies are matched by fact, not by claim.** Crosstalk records which message each reply answers via the `re:` field, so "has it replied yet?" is always answered from ground truth — a busy or confused model can't fake completion.
+- **At-least-once delivery.** For anything with side effects (sending an email, deploying), the interactive agent — and the models — check the channel for prior completion before repeating. For lookups and advice, the occasional duplicate is harmless.
+- **Failures are loud.** A failed dispatch lands as a normal reply with `failed: true` + `error: <text>`. The interactive agent will surface failures the same way it surfaces successes — no separate place to check.
+- **If nothing comes back** (~10 minutes), the interactive agent will offer to check `crosstalk status` for the dispatcher heartbeat. Usually it's a dispatcher that's down or a model whose CLI isn't wired correctly (see [GUIDE-CLI.md → Models](GUIDE-CLI.md#models)).
+
+---
+
+## Tips for good results
+
+- **Name the machine when it matters.** "ask sonnet" reaches sonnet on whichever dispatcher claims it first; "ask sonnet on cachy" pins it to one machine. Use the machine when *where* the work runs is part of the ask.
+- **Name the channel for threaded work.** If you don't, and there's more than one channel, the agent will ask which one rather than guess.
+- **Be explicit for non-idempotent actions.** "deploy to staging" is a side effect; say so clearly and the model will verify it hasn't already happened.
+- **You don't need to know UUIDs or paths — ever.** If the agent starts showing you raw file paths or git output, tell it to "talk to me like a person"; hiding that machinery is its job.
+
+---
+
+## When to drop to the CLI
+
+Natural language covers day-to-day operation. Reach for the **[CLI guide](GUIDE-CLI.md)** when you're:
+
+- scripting or automating (cron jobs, CI),
+- editing `data/models.yaml` to wire a new agent,
+- running the dispatcher itself (`crosstalk dispatch --alias <name>`), or
+- inspecting state at a low level (cursor SHA, heartbeat freshness).
+
+Both drive the exact same transport — use whichever is faster for the task in front of you.

package/README.md

@@ -0,0 +1,118 @@
+# @cordfuse/crosstalkd — engine
+
+> **README is mid-rewrite.** v7 splits the runtime into an in-container daemon (`@cordfuse/crosstalkd`, this package) and a host-side client (`@cordfuse/crosstalk`, separate package landing in P2). Operators should NOT install this package directly — install `@cordfuse/crosstalk` on the host instead. This package is baked into the `crosstalk-server` container image; operators never interact with `crosstalkd` directly. The body of this README below pre-dates the split and is being rewritten in the docs-consolidation pass (P6).
+
+> Part of the [Crosstalk repo](https://github.com/cordfuse/crosstalk) — the root README has the full problem statement, design philosophy, and repository layout. The other tier in the same repo is the [transport template](../transport/).
+
+The `crosstalkd` daemon binary. Installs as a single Node.js binary; runs as the long-lived process inside the `crosstalk-server` container. Provides every protocol-layer verb in the Crosstalk protocol: scaffold a transport, dispatch primitives and workflows, run the per-machine loop, manage channels.
+
+> **What Crosstalk is.** Crosstalk is an agent-agnostic swarm communication protocol built on git. A git repo is the message bus. Any CLI that accepts a prompt and prints a reply can be a model; messages are committed files; coordination is peer-to-peer with no broker. Full background: **[github.com/cordfuse/crosstalk](https://github.com/cordfuse/crosstalk#why-crosstalk-exists)**.
+
+> **v7 status.** This package is in active development. The quickstart below describes the v7.0 surface and works end-to-end at the v7.0.0-alpha.1 tag. Branch state precedes runtime readiness — check `crosstalkd version` if in doubt.
+
+---
+
+## Install
+
+```sh
+npm install -g @cordfuse/crosstalk
+```
+
+Requires Node.js ≥ 20. Works on Linux and macOS. Windows is untested.
+
+Verify:
+
+```sh
+crosstalk version
+```
+
+## Quickstart (local-only — no remote git required)
+
+```sh
+# 1. Install an agent CLI. Easiest is Claude Code:
+curl -fsSL https://claude.ai/install.sh | bash
+claude                        # one-time interactive login
+
+# 2. Scaffold a transport in a fresh directory.
+mkdir my-bus && cd my-bus && git init
+crosstalk init .
+git add -A && git commit -m "initial transport"
+
+# 3. Start the dispatcher with this machine's alias.
+crosstalk dispatch --alias laptop &
+#   To stop it later:  crosstalk stop
+
+# 4. Create a channel.
+crosstalk channel general
+
+# 5. Ask sonnet a question.
+crosstalk run --type primitive --to sonnet "What is the capital of France?"
+
+# 6. Check for replies.
+crosstalk replies <relPath printed by step 5>
+```
+
+The dispatcher reads `data/models.yaml`, checks PATH for the first token of each entry, and claims the models whose CLI is installed locally. Step 5 succeeds because `claude` is on PATH and the `sonnet` entry's command starts with `claude`.
+
+To use a different agent, edit `data/models.yaml` — one line per model. No host file to author. No tier wiring. To add a second machine, configure a git remote and have the other machine clone and run `crosstalk dispatch --alias <its-name>`.
+
+## Subcommand reference
+
+Eight subcommands. Full flag reference: **[GUIDE-CLI.md](./GUIDE-CLI.md)**.
+
+| Subcommand | Purpose |
+|---|---|
+| `crosstalk init <dir>` | Scaffold a new transport into the given directory (copies the [template](../transport/)). |
+| `crosstalk run --type primitive\|workflow` | Dispatch a single message or a workflow document. |
+| `crosstalk dispatch --alias <name>` | Run the per-machine dispatch loop with this identity. |
+| `crosstalk stop` | Stop the running dispatcher on this machine cleanly. Reads pidfile, sends SIGTERM. |
+| `crosstalk status` | Print channels (name → uuid), dispatcher heartbeat, claimed models. |
+| `crosstalk replies <relPath>...` | Check which dispatched messages have replies. |
+| `crosstalk channel <name> [--rename \| --delete]` | Channel operations. |
+| `crosstalk version` | Print runtime version. |
+
+For natural-language operator use ("ask the orchestrator to fan out three drafts") see **[GUIDE-PROMPTS.md](./GUIDE-PROMPTS.md)**.
+
+---
+
+## What ships in this package
+
+- `bin/crosstalk.js` — the subcommand dispatcher; `npm install -g` links it as `crosstalk`.
+- `src/` — TypeScript source; the runtime is executed via [tsx](https://www.npmjs.com/package/tsx) at run time (no compile step at install).
+- `template/` — a snapshot of the [transport template](../transport/) at publish time. `crosstalk init` copies from here.
+- `GUIDE-CLI.md`, `GUIDE-PROMPTS.md` — operator guides published alongside this package.
+
+---
+
+## Local development
+
+```sh
+cd runtime
+npm install
+npm run build        # tsc --noEmit type-check
+node bin/crosstalk.js version   # invoke the dev binary directly
+```
+
+The runtime is type-checked but not transpiled — `tsx` runs the TypeScript sources directly at invocation time. No build step is required for an end-user install.
+
+To work on the source while testing against a local transport, point the binary at the dev path:
+
+```sh
+cd /path/to/your/transport
+node /path/to/crosstalk/runtime/bin/crosstalk.js status
+```
+
+---
+
+## Dependencies
+
+- [`tsx`](https://www.npmjs.com/package/tsx) — run TypeScript directly without a build step.
+- [`yaml`](https://www.npmjs.com/package/yaml) — frontmatter and `data/models.yaml` parsing.
+
+That's it. v7 deliberately ships with two runtime dependencies. The advisory-locking subsystem (`@cordfuse/turnq`) and the pty layer (`@lydell/node-pty`) that v6 carried are both gone — git rebase-retry handles concurrent writers; the pty was only needed for the deleted `attach` subcommand.
+
+---
+
+## License
+
+MIT. See [LICENSE](https://github.com/cordfuse/crosstalk/blob/main/LICENSE) in the repo.

package/bin/crosstalkd.js

@@ -0,0 +1,101 @@
+#!/usr/bin/env node
+// crosstalkd — the daemon binary inside the crosstalk-server container.
+//
+// Operators talk to crosstalkd via the host-side `crosstalk` client
+// (@cordfuse/crosstalk), which shells out via `docker exec`. This binary
+// is the in-container subcommand dispatcher: walks up from cwd to find
+// a Crosstalk transport (identified by CROSSTALK-VERSION at the
+// transport root), then runs the requested subcommand from the engine's
+// installed source via tsx. All args after the subcommand are forwarded.
+// `init` is the one subcommand that runs outside a transport.
+
+import { existsSync, statSync } from 'fs';
+import { resolve, join, dirname } from 'path';
+import { spawnSync, spawn } from 'child_process';
+import { fileURLToPath } from 'url';
+import { createRequire } from 'module';
+
+const SUBCOMMANDS = [
+  'dispatch', 'stop', 'run', 'replies', 'status', 'init', 'channel',
+];
+const STANDALONE_SUBCOMMANDS = new Set(['init']);
+
+function findTransportRoot(startDir) {
+  let dir = resolve(startDir);
+  while (true) {
+    const versionFile = join(dir, 'CROSSTALK-VERSION');
+    if (existsSync(versionFile) && statSync(versionFile).isFile()) return dir;
+    const parent = dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+function printUsage(exitCode = 0) {
+  process.stdout.write(
+    `Usage: crosstalkd <subcommand> [args...]\n\nSubcommands:\n` +
+    SUBCOMMANDS.map((s) => `  ${s}`).join('\n') +
+    `\n\nThis is the in-container daemon binary. Operators normally\n` +
+    `interact via the host-side 'crosstalk' client, which shells out\n` +
+    `here via docker exec.\n\n` +
+    `Most subcommands require you to be inside a Crosstalk transport\n` +
+    `(a directory containing CROSSTALK-VERSION). 'init' can run\n` +
+    `from anywhere to scaffold a new transport.\n`,
+  );
+  process.exit(exitCode);
+}
+
+const argv = process.argv.slice(2);
+if (argv.length === 0 || argv[0] === '-h' || argv[0] === '--help') printUsage(0);
+
+if (argv[0] === '--version' || argv[0] === 'version') {
+  const require = createRequire(import.meta.url);
+  const { version } = require('../package.json');
+  process.stdout.write(`${version}\n`);
+  process.exit(0);
+}
+
+const cmd = argv[0];
+if (!SUBCOMMANDS.includes(cmd)) {
+  console.error(`crosstalkd: unknown subcommand '${cmd}'\n`);
+  printUsage(1);
+}
+
+const thisDir = dirname(fileURLToPath(import.meta.url));
+const srcFile = join(thisDir, '..', 'src', `${cmd}.ts`);
+
+let cwd = process.cwd();
+if (!STANDALONE_SUBCOMMANDS.has(cmd)) {
+  const root = findTransportRoot(cwd);
+  if (!root) {
+    console.error(
+      `crosstalkd ${cmd}: not inside a Crosstalk transport ` +
+      `(no CROSSTALK-VERSION found from ${cwd} upward).`,
+    );
+    process.exit(2);
+  }
+  cwd = root;
+}
+
+const require = createRequire(import.meta.url);
+const tsxCli = require.resolve('tsx/cli');
+
+// dispatch is long-running: use async spawn so SIGTERM/SIGINT forwarded to
+// the tsx child kills the whole chain cleanly. All other subcommands are
+// short-lived and spawnSync is fine.
+if (cmd === 'dispatch') {
+  const child = spawn(process.execPath, [tsxCli, srcFile, ...argv.slice(1)], {
+    cwd,
+    stdio: 'inherit',
+  });
+  const forward = (sig) => { try { child.kill(sig); } catch {} };
+  process.on('SIGTERM', () => forward('SIGTERM'));
+  process.on('SIGINT',  () => forward('SIGTERM'));
+  child.on('exit', (code, signal) => process.exit(signal ? 1 : (code ?? 0)));
+} else {
+  const r = spawnSync(process.execPath, [tsxCli, srcFile, ...argv.slice(1)], {
+    cwd,
+    stdio: 'inherit',
+  });
+  process.exit(r.status ?? 1);
+}