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

package/GUIDE-CLI.md

@@ -0,0 +1,298 @@
+# Crosstalk CLI Guide
+
+Quick reference for the `crosstalk` CLI. Run `crosstalk <subcommand> --help` for flags.
+
+Requires: Node.js ≥ 20. All subcommands (except `init`) must be run from inside a transport (a directory containing `upstream/CROSSTALK-VERSION`).
+
+---
+
+## Setup
+
+### `crosstalk init`
+
+Scaffold a new transport in the current directory:
+
+```sh
+mkdir my-transport && cd my-transport
+git init
+crosstalk init
+```
+
+Creates `upstream/` (spec + protocol docs), `hosts/`, `data/`, and `local/actors/`. Commit and push to your git remote; that repo is now the message bus.
+
+> ### Multi-host: seed every host file before sending
+>
+> Each host's delivery waterline is the commit that first added **its** host
+> file to the transport. A message addressed to a host *before* that host's
+> file exists in history sits below the waterline and is never delivered.
+>
+> **Therefore, when adding a host to a multi-host bus, commit + push its
+> `hosts/<alias>.md` BEFORE anyone sends messages to it.** A host that joins
+> an existing transport must seed its host file first; messages sent to it
+> earlier won't be received.
+>
+> `crosstalk send` warns when `--to <actor>@<host>` names a host with no host
+> file in the transport, so the silent drop becomes a visible error at send
+> time.
+>
+> **Single-host operators don't need to think about this** — `crosstalk init`
+> seeds your host file at setup, before any messaging, so the ordering can
+> never bite you.
+
+---
+
+## Choosing and wiring an agent
+
+Crosstalk is **agent-agnostic**. An actor is any CLI that reads a prompt and
+prints a reply — there is no built-in model and no vendor requirement. You wire
+your agent in the host file, under the actor's tier, as a `cli:` string:
+
+```yaml
+# hosts/<your-host>.md
+---
+alias: my-laptop
+hostname: my-laptop
+actors:
+  concierge:
+    default:
+      cli: <your-agent-cli>      # the command crosstalk runs to invoke the agent
+---
+```
+
+### The contract
+
+When the dispatcher invokes an actor it:
+
+1. composes `system prompt + the message(s)` and **appends it as the last
+   argument to your CLI command**, then
+2. reads the CLI's **stdout** as the reply body, and expects exit code **0**.
+
+So a `cli:` works if the command runs **one prompt non-interactively** (taking
+the prompt as its trailing positional or flag-value) and **prints the answer
+to stdout**. Two things to get right per agent:
+
+- **Non-interactive / skip-approval flag.** Each agent has a flag that stops it
+  from pausing for confirmation or opening a TUI. Use it, or every dispatch will
+  hang until the 5-minute timeout and land in the DLQ.
+- **Trailing argument shape.** The dispatcher tacks the prompt on the end of
+  whatever you put in `cli:`. So `cli: codex exec` becomes
+  `codex exec "<prompt>"`, `cli: gemini -p` becomes `gemini -p "<prompt>"`,
+  and `cli: claude --print --dangerously-skip-permissions` becomes
+  `claude --print --dangerously-skip-permissions "<prompt>"`. Every modern
+  agent CLI is happy with one of those shapes.
+
+> For prompts larger than 64 KB (huge batches) the dispatcher falls back to
+> writing the prompt to **stdin** automatically — the default argv path covers
+> every supported agent, and the stdin fallback keeps things working past the
+> OS `ARG_MAX` limit.
+
+### Recipes
+
+Starting points — **verify flags against your installed CLI version**;
+vendors change them.
+
+| Agent | Example `cli:` | Notes |
+|---|---|---|
+| Claude Code | `claude --print --dangerously-skip-permissions` | accepts the prompt as a positional arg |
+| OpenAI Codex | `codex exec` | `exec` = non-interactive; add its bypass/sandbox flag |
+| Gemini CLI | `gemini -p` | `-p` one-shot prompt; add `--yolo` to skip approvals |
+| Qwen Code | `qwen -p` | Gemini-CLI-family flags |
+| opencode | `opencode run` | `run` = one-shot |
+| Antigravity | `agy -p` | `-p`/`--print` non-interactive |
+
+You can mix agents in one transport — different actors (or different hosts) 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` (e.g. `ps auxww`). On a single-
+> user laptop or dedicated dispatcher VM that's a non-issue; on multi-user
+> machines, plan accordingly.
+
+### Tiers (optional)
+
+A tier is a named CLI slot under an actor. The bare-string shorthand is `count: 1`;
+the object form adds `count:` for parallel instances. Senders may request a tier
+with `--tier <name>`; the dispatcher falls back to the first declared tier when
+the requested one is absent.
+
+```yaml
+actors:
+  junior-developer:
+    fast:
+      cli: gemini -p --yolo
+      count: 5            # five parallel slots picking up work independently
+```
+
+---
+
+## Sending messages
+
+### `crosstalk send --to <actor> --channel <uuid> "<body>"`
+
+Post a message to an actor. The channel must already exist (see `crosstalk channel`).
+
+```sh
+crosstalk send \
+  --to concierge \
+  --channel 56f57ff9-7031-4ab2-9b98-4f299d3240fb \
+  "What is the capital of France?"
+```
+
+Prints `Sent: <relPath>` — save that path if you need to check for replies.
+
+| Flag | Required | Notes |
+|---|---|---|
+| `--to <actor[,actor]>` | yes | bare name or `actor@host`; comma-separated list OK |
+| `--channel <uuid>` | only if multiple channels exist | Auto-detected when the transport has exactly one channel; required to disambiguate when there are several. |
+| `--from <actor>` | no | defaults to `$USER` / `operator` |
+| `--tier <name>` | no | request a specific model tier |
+| `--new` | no | suppress automatic `re:` linking (start new work, not a reply) |
+
+---
+
+## Running a dispatcher
+
+### `crosstalk dispatch`
+
+Start the dispatch loop in the current transport. Runs forever, polling for new messages and invoking actor CLIs.
+
+```sh
+crosstalk dispatch --poll 30 --json
+```
+
+| Flag | Default | Notes |
+|---|---|---|
+| `--poll <seconds>` | `30` | quiet-tick interval; active ticks drop to 1s automatically |
+| `--host <alias>` | auto-detect | override which `hosts/<alias>.md` to load |
+| `--json` | off | structured JSON log lines |
+| `--log-file <path>` | none | mirror logs to a file |
+| `--once` | off | run one tick then exit (useful for testing) |
+
+> **macOS note — hostname auto-detect.** macOS's kernel hostname (`os.hostname()`) can drift across network state when the static **HostName** is unset (`configd` re-derives it from DHCP, reverse-DNS, or your VPN/Tailscale machine name). The dispatcher works around this on Darwin by also trying `scutil --get LocalHostName` and its `.local` form when matching against `hosts/<alias>.md`. If auto-detect still fails, either pin `--host <alias>` or pin your kernel hostname once:
+> ```sh
+> sudo scutil --set HostName <your-host-alias>
+> ```
+
+Dispatcher state (cursors, DLQ, heartbeat, error log) is stored under `$CROSSTALK_STATE_DIR` (default `~/.local/state/crosstalk/<transport-id>/`) — never in the transport repo.
+
+---
+
+## Observability
+
+### `crosstalk status`
+
+Print host file, active channels, cursor positions, DLQ count, and dispatcher heartbeat.
+
+```sh
+crosstalk status
+```
+
+### `crosstalk replies --re <relPath>[,<relPath>...]`
+
+Show which of your dispatched messages have replies. Matches via the runtime-written `re:` field — ground truth, not body-parsing.
+
+```sh
+crosstalk replies --re 2026/06/10/130847758Z-780a8b90.md
+```
+
+---
+
+## DLQ
+
+### `crosstalk dlq`
+
+Manage the dead-letter queue — messages that failed to dispatch repeatedly.
+
+```sh
+crosstalk dlq --list             # list quarantined entries
+crosstalk dlq --show <id>        # full detail for one entry
+crosstalk dlq --retry <id>       # re-queue for dispatch
+```
+
+A common first-run cause of DLQ entries: the actor's `cli:` isn't truly
+non-interactive (missing its skip-approval flag), so dispatches hang until the
+5-minute timeout. See **Choosing and wiring an agent**.
+
+---
+
+## Channels
+
+### `crosstalk channel --name <name>`
+
+Create a new channel and print its UUID.
+
+```sh
+crosstalk channel --name "sprint-42"
+```
+
+| Flag | Notes |
+|---|---|
+| `--name <name>` | required; unique within the transport |
+| `--parent <uuid>` | make this a subchannel; it reports back to the parent |
+
+---
+
+## Interactive
+
+### `crosstalk chat`
+
+Send a message and wait for the reply in one command. Useful for interactive sessions from the terminal.
+
+```sh
+crosstalk chat --to concierge --channel <uuid>
+```
+
+### `crosstalk open --actor <name>`
+
+Open an interactive REPL-style session with an actor — each exchange is a full dispatch cycle. Requires a TTY.
+
+```sh
+crosstalk open --actor concierge
+```
+
+### `crosstalk attach`
+
+Attach to a running dispatch loop's live log output (like `tail -f`, but structured).
+
+> Prefer talking to Crosstalk in plain language instead of memorising flags?
+> See **[GUIDE-PROMPTS.md](GUIDE-PROMPTS.md)** for the natural-language operator interface.
+
+---
+
+## Misc
+
+### `crosstalk wake`
+
+Poke the dispatcher to tick immediately. Rarely needed — `send` already signals the dispatcher.
+
+### `crosstalk version`
+
+Print the installed runtime version.
+
+### `crosstalk upgrade`
+
+Check whether the transport's protocol version matches the installed runtime and apply any necessary upgrades to `upstream/`.
+
+---
+
+## Common patterns
+
+**One-shot task from a script:**
+```sh
+UUID=$(crosstalk channel --name "batch-$(date +%s)" | grep -o '[0-9a-f-]\{36\}')
+crosstalk send --to concierge --channel "$UUID" "Summarise this file: ..." > /dev/null
+# dispatch loop will pick it up on next poll
+```
+
+**Check if fan-out replies are all in:**
+```sh
+# After dispatching to 5 peers, record their relPaths:
+crosstalk replies --re path1.md,path2.md,path3.md,path4.md,path5.md
+```
+
+**Troubleshooting a stuck dispatcher:**
+```sh
+crosstalk status          # check heartbeat freshness and DLQ count
+crosstalk dlq --list      # see what's quarantined
+```

package/GUIDE-PROMPTS.md

@@ -0,0 +1,132 @@
+# Crosstalk Natural-Language Guide
+
+You don't have to memorise the `crosstalk` CLI to use Crosstalk. You can just
+**talk to it.**
+
+Crosstalk has an *operator mode*: you open a conversation with an agent inside
+your transport and ask for things in plain language — "ask the test-runner on
+the server whether the build is green." The agent translates your words into the
+right `crosstalk` commands, waits for the answer, and tells you what came back —
+no UUIDs, no file paths, no git.
+
+This is the companion to the **[CLI guide](GUIDE-CLI.md)**. Same system, two
+front doors: type commands, or just speak.
+
+> Operator mode is **agent-agnostic**, like the rest of Crosstalk. Whatever
+> coding agent you already run — Claude Code, Codex, Gemini, Qwen, opencode,
+> Antigravity — can be your operator interface, as long as it can read the
+> transport's orientation file and run shell commands.
+
+---
+
+## Starting an operator conversation
+
+Pick whichever fits your setup:
+
+```sh
+# Purpose-built: open an actor in an interactive operator session
+crosstalk open --actor concierge
+```
+
+or simply **launch your agent CLI from inside the transport directory.** The
+transport ships an orientation file at its root (`CLAUDE.md`, and equivalents
+for other agents) that tells your agent it is in operator mode and how to drive
+Crosstalk. Start talking.
+
+> **Operator mode ≠ being an actor.** When you open a session this way, *you*
+> (through the agent) are the human's interface — you are not `concierge` or any
+> other actor, and you do **not** process incoming messages. Leave message
+> *processing* to the running dispatcher (`crosstalk dispatch`). Don't run
+> `crosstalk dispatch` or `crosstalk open` from an operator session — both
+> compete with the dispatcher.
+
+---
+
+## The phrasebook
+
+Say it however feels natural; these are the intents the operator agent
+recognises and what it does for you.
+
+| You say… | What happens |
+|---|---|
+| "ask concierge to summarise `report.md`" | sends the task to `concierge`, waits, surfaces the reply |
+| "ask the junior-dev on the server to run the tests" | sends to `junior-developer@server`, waits, reports back |
+| "ask everyone for a status update" | sends to `all`, collects the replies as they arrive |
+| "in the *sprint-42* channel, ask concierge to plan the work" | scopes the message to that channel |
+| "is the dispatcher alive?" / "check status" | runs `crosstalk status`, explains the heartbeat plainly |
+| "what's stuck?" / "what's in the dead-letter queue?" | runs `crosstalk dlq`, summarises the failures |
+| "retry that failed one" | runs `crosstalk dlq --retry <id>` |
+| "make a channel called *release-7*" | creates the channel, tells you it's ready |
+| "what channels exist?" | lists channels by their human names |
+| "tweak the concierge actor to be more terse" | edits `local/actors/concierge.md`, commits, pushes |
+| "pull the latest" | runs `git pull --rebase` |
+
+---
+
+## Coordinating a team in plain language
+
+The real power is fan-out. Tell the coordinator the goal and let it dispatch:
+
+> **You:** "Ask concierge to get three things done: update the changelog, run
+> the test suite on the server, and draft release notes — then summarise when
+> they're all back."
+
+Behind the scenes the coordinator sends one message per task to the right
+actors, ends its turn, and is automatically re-woken as each reply lands; when
+all are in, it aggregates and answers you. You just see:
+
+> *(waiting for concierge…)*
+> **concierge:** All three done. Changelog updated, 142 tests green on the
+> server, draft release notes attached below. …
+
+You never see the orchestration — only the result.
+
+---
+
+## 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 operator agent will say something like
+  *"(waiting for concierge…)"* and surface the answer when it arrives.
+- **Replies are matched by fact, not by claim.** Crosstalk records which message
+  each reply answers, so "has it replied yet?" is always answered from ground
+  truth — a busy or confused actor can't fake completion.
+- **At-least-once delivery.** For anything with side effects (sending an email,
+  deploying), the operator agent — and the actors — check the channel for prior
+  completion before repeating. For lookups and advice, the occasional duplicate
+  is harmless.
+- **If nothing comes back** (~10 minutes), the operator agent will offer to
+  check `status` and the DLQ for clues — usually a dispatcher that's down or an
+  actor whose CLI isn't wired correctly (see
+  [GUIDE-CLI.md → Choosing and wiring an agent](GUIDE-CLI.md#choosing-and-wiring-an-agent)).
+
+---
+
+## Tips for good results
+
+- **Name the actor when it matters.** "ask concierge" reaches it on every host
+  that runs it; "ask concierge **on cachy**" pins it to one machine. Use the host
+  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 operator 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 actor will verify it hasn't already happened.
+- **You don't need to know UUIDs or paths — ever.** If the operator 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),
+- setting up hosts and wiring agent CLIs,
+- running the dispatcher itself, or
+- debugging cursors / the DLQ in detail.
+
+Both drive the exact same transport — use whichever is faster for the task in
+front of you.

package/README.md

@@ -0,0 +1,136 @@
+# @cordfuse/crosstalk — runtime
+
+> Part of the [Crosstalk repo](https://github.com/cordfuse/crosstalk) — the
+> root README has the full problem statement, solution overview, and
+> repository layout. The other tiers in the same repo are the
+> [transport template](../transport/) and the
+> [reference server image](../server/).
+
+The `crosstalk` command-line tool. Installs as a single Node.js binary; runs
+on a developer laptop or inside a server container. Provides every operator
+verb in the Crosstalk protocol: scaffold a transport, send messages, run
+the dispatcher loop, manage channels, retry the DLQ.
+
+> **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 an actor; messages are committed files;
+> coordination is peer-to-peer with no broker. Full background and problem
+> space:
+> **[github.com/cordfuse/crosstalk](https://github.com/cordfuse/crosstalk#the-problem)**.
+
+---
+
+## Install
+
+```sh
+npm install -g @cordfuse/crosstalk
+```
+
+Requires Node.js ≥ 20. Works on Linux and macOS. Windows is untested.
+
+To verify:
+
+```sh
+crosstalk --version
+```
+
+## 60-second quickstart
+
+```sh
+# 1. Scaffold a transport (a git repo that is the message bus)
+mkdir my-bus && cd my-bus && git init
+crosstalk init .
+git add -A && git commit -m "initial transport"
+git remote add origin <your-repo-url> && git push -u origin main
+
+# 2. Edit hosts/<this-host>.md to wire your agent's CLI under the actor.
+#    For example, to use Claude Code as `concierge`:
+#      actors:
+#        concierge:
+#          default:
+#            cli: claude --print --dangerously-skip-permissions
+git add hosts && git commit -m "configure host" && git push
+
+# 3. Start the dispatch loop on this machine
+crosstalk dispatch &
+
+# 4. Send a message — the dispatcher invokes your agent and commits its reply
+crosstalk send --to concierge "What is the capital of France?"
+```
+
+The dispatcher invokes the configured CLI by appending the composed prompt as
+the CLI's last argument (with automatic stdin fallback for prompts > 64 KB),
+so almost any modern agent CLI works without a per-vendor wrapper.
+
+## Subcommand reference
+
+| Subcommand | Purpose |
+|---|---|
+| `crosstalk init <dir>` | Scaffold a new transport into the given directory (copies the [template](../transport/)). |
+| `crosstalk send --to <actor> [...]` | Write a message into a channel and push it. Auto-detects the channel if there's only one. |
+| `crosstalk dispatch` | Run the per-machine dispatch loop. Polls for new messages, invokes actor CLIs, commits + pushes replies. |
+| `crosstalk stop` | Stop the running dispatcher on this machine cleanly. Reads `dispatcher.pid` and sends SIGTERM. |
+| `crosstalk status` | Print host file, channels, cursors, DLQ count, dispatcher heartbeat. |
+| `crosstalk replies --re <relPath>` | Check which dispatched messages have replies. |
+| `crosstalk dlq [--retry <id>]` | Inspect or retry dead-letter entries. |
+| `crosstalk channel --name <name>` | Create a new channel; prints the UUID. |
+| `crosstalk chat / open / attach` | Interactive operator entrypoints. |
+| `crosstalk wake` | Poke a running dispatcher to tick immediately. |
+| `crosstalk upgrade` | Reconcile the transport's protocol version against this runtime. |
+| `crosstalk version` | Print runtime version. |
+
+Detailed flag reference for every subcommand: **[GUIDE-CLI.md](./GUIDE-CLI.md)**
+(also published alongside this package).
+
+For natural-language operator use ("ask concierge to summarise this file") 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
+# In the repo root
+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
+
+- [`@cordfuse/turnq`](https://www.npmjs.com/package/@cordfuse/turnq) — advisory
+  turn-coordination for serializing the commit+push window across hosts.
+  Optional in single-host setups; falls back to a local lockfile when no
+  turnq URL is configured.
+- [`tsx`](https://www.npmjs.com/package/tsx) — run TypeScript directly without a build step.
+- [`yaml`](https://www.npmjs.com/package/yaml) — frontmatter parsing.
+
+---
+
+## License
+
+MIT. See [LICENSE](https://github.com/cordfuse/crosstalk/blob/main/LICENSE) in the repo.

package/bin/crosstalk.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cordfuse/crosstalk",
-  "version": "6.0.0-alpha.1",
+  "version": "6.0.0-alpha.11",
   "description": "Crosstalk runtime — async messaging between agents over git, across machines.",
   "type": "module",
   "license": "MIT",
@@ -15,15 +15,19 @@
   "files": [
     "bin/",
     "src/",
-    "template/"
+    "template/",
+    "GUIDE-CLI.md",
+    "GUIDE-PROMPTS.md"
   ],
   "scripts": {
     "build": "tsc --noEmit",
     "lint": "tsc --noEmit",
-    "test": "bun test"
+    "test": "bun test",
+    "prepack": "cp -r ../transport template && cp ../GUIDE-CLI.md ../GUIDE-PROMPTS.md .",
+    "postpack": "rm -rf template GUIDE-CLI.md GUIDE-PROMPTS.md"
   },
   "dependencies": {
-    "@cordfuse/turnq": "^0.4.1",
+    "@cordfuse/turnq": "^0.4.2",
     "@lydell/node-pty": "^1.2.0-beta.12",
     "tsx": "^4.20.0",
     "yaml": "^2.8.0"

package/src/actor.ts

@@ -1,8 +1,31 @@
 import { existsSync, readFileSync, readdirSync } from 'fs';
 import { join } from 'path';
-import { hostname as osHostname } from 'os';
+import { hostname as osHostname, platform } from 'os';
+import { spawnSync } from 'child_process';
 import { parseFrontmatter } from './frontmatter.js';
 
+// Collect the names this machine might be known by. On macOS, the kernel
+// hostname (`os.hostname()`) drifts with DHCP/VPN/Tailscale when the static
+// HostName is unset — `scutil --get LocalHostName` is the stable Bonjour
+// name (e.g. `Steves-MacBook-Air`), and host files commonly use the `.local`
+// form. Trying all variants makes auto-detect deterministic across network
+// state without forcing every Mac operator to pin `--host`.
+function candidateHostNames(): string[] {
+  const names = new Set<string>();
+  names.add(osHostname());
+  if (platform() === 'darwin') {
+    const r = spawnSync('scutil', ['--get', 'LocalHostName'], { encoding: 'utf-8' });
+    if (r.status === 0) {
+      const local = r.stdout.trim();
+      if (local) {
+        names.add(local);
+        names.add(`${local}.local`);
+      }
+    }
+  }
+  return [...names];
+}
+
 export interface HostActorTier {
   cli: string;
   count?: number;
@@ -36,13 +59,15 @@ export function findHostFile(transportRoot: string, override?: string): HostFile
     if (!target) throw new Error(`Host file '${override}' not found in ${dir}`);
     return parseHostFile(join(dir, target));
   }
-  const hostName = osHostname();
+  const names = candidateHostNames();
   for (const f of files) {
     const parsed = parseHostFile(join(dir, f));
-    if (parsed.hostname === hostName || parsed.alias === hostName) return parsed;
+    for (const n of names) {
+      if (parsed.hostname === n || parsed.alias === n) return parsed;
+    }
   }
   throw new Error(
-    `No host file matches hostname '${hostName}' in ${dir}. ` +
+    `No host file matches any of [${names.join(', ')}] in ${dir}. ` +
       `Pass --host <alias> to override.`,
   );
 }