npm - talking-stick - Versions diffs - 0.1.4 → 0.3.0 - Mend

talking-stick 0.1.4 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (32) hide show

package/README.md +56 -43
package/dist/cli/event-stream.js +124 -0
package/dist/cli/install-commands.js +76 -36
package/dist/cli/msg-commands.js +81 -0
package/dist/cli/output.js +5 -3
package/dist/cli/registry.js +24 -33
package/dist/cli/room-commands.js +13 -2
package/dist/cli/startup-maintenance.js +27 -1
package/dist/cli.js +2 -2
package/dist/commands.js +15 -0
package/dist/config.js +4 -1
package/dist/db.js +7 -0
package/dist/identity.js +4 -4
package/dist/index.js +2 -2
package/dist/install-audit.js +21 -0
package/dist/install-migration.js +84 -0
package/dist/install.js +0 -69
package/dist/service.js +161 -4
package/dist/update-migration.js +135 -0
package/docs/plans/2026-05-04-diff-walker-design.md +585 -0
package/docs/plans/2026-05-05-cli-only-coordination.md +224 -0
package/docs/plans/out-of-band-signaling-implementation.md +854 -0
package/docs/plans/out-of-band-signaling.md +255 -176
package/docs/receive-consumer-contract.md +32 -0
package/docs/releases/0.2.0.md +85 -0
package/docs/releases/0.3.0.md +77 -0
package/docs/talking-stick-plan.md +3 -2
package/package.json +4 -3
package/scripts/postinstall-mcp-cleanup.cjs +25 -0
package/skills/talking-stick/SKILL.md +131 -88
package/dist/mcp-server.js +0 -212
package/dist/server.js +0 -3

package/docs/receive-consumer-contract.md ADDED Viewed

@@ -0,0 +1,32 @@
+# Receive Consumer Contract
+`send_message` appends `message_sent` events to the room event log. `wait_for_events` is the canonical receive primitive. CLI consumers (`tt events --wait`, `tt events --follow`, `tt msg recv --wait`, `tt msg recv --follow`) and future harness-native consumers should share the same cursor and retry rules.
+## Delivery
+- Delivery is at least once. Consumers must tolerate duplicates after restart.
+- `event_seq` is monotonic per database and is the receive cursor.
+- Consumers should persist the highest processed `event_seq` after each emitted batch.
+- Directed messages are routing only. Any room member can read messages through `get_room_events` or `tt events --target any`.
+## Receive Modes
+- Use `tt events --follow --after <cursor>` when the harness can monitor stdout from a long-running child. Each output line is one `RoomEvent` JSON object.
+- Use `tt events --wait --after <cursor>` when the harness can only notice process completion. The process exits after the next matching batch or timeout; restart it with the latest processed cursor.
+- Use `tt msg recv --wait` or `tt msg recv --follow` only when the consumer intentionally wants messages without turn handoffs.
+- If no `--after` is supplied in `--wait` or `--follow` mode, the CLI starts from the current event tail to avoid flooding a new consumer with history.
+- A one-shot `tt msg recv --after <cursor>` is a non-blocking drain operation.
+## Filtering
+- `target=self` is the default for `--wait` and `--follow`. It receives direct messages to the caller plus broadcasts from other agents. It excludes the caller's own broadcasts.
+- `target=any` receives all matching events/messages and is intended for audit/debug views.
+- `--from <agent>` resolves a full `agent_id` or unambiguous active display name and is enforced server-side.
+## Consumer Responsibilities
+- Keep `wait_for_turn` / `tt wait` running separately. Receive processes do not claim or grant the stick, even when they return pass, release, or assignment events.
+- Treat an event wake as a prompt to read, reply, or retry `tt wait`. It is not permission to mutate shared files; only a `your_turn` wait result with a live guardian grants ownership.
+- Decide how to surface `delivery_hint=interrupt`; the server only records the hint.
+- Dedupe on `event_id` if restart replay is possible.
+- Treat message bodies as room-visible text, not private data.

package/docs/releases/0.2.0.md ADDED Viewed

@@ -0,0 +1,85 @@
+# Talking Stick 0.2.0
+Date: 2026-04-30
+Minor release that adds **out-of-band messaging** between agents in a room. Two agents — typically the holder and a non-holder, or two non-holders — can now exchange short conversational messages without passing the stick. The protocol substrate is one new column on `room_events`; the surface is two MCP tools (`send_message`, `wait_for_events`) and three CLI commands (`tt msg send`, `tt msg recv`, `tt events --wait|--follow`).
+The feature targets **Vignette H** from the design doc: holder + non-holder alternating short messages on a sub-question, paying ~80 tokens of body per round-trip instead of the ~600 tokens of structured-handoff scaffolding when the discussion would have otherwise required `pass_stick`/`release_stick` ping-pong.
+## Added
+### Out-of-band messaging
+Three CLI commands. All wrap the same MCP/service primitives.
+```bash
+tt msg send <recipient|room> "<body>" [--interrupt] [--stdin] [--path DIR]
+tt msg recv [--wait|--follow] [--from agent] [--after N] [--target self|any|agent] [--path DIR]
+tt events --wait|--follow [--event TYPE[,TYPE]] [--target self|any|agent]
+```
+- `<recipient>` is a full `agent_id`, an unambiguous active display name (`codex`, `claude`), or the literal `room` for broadcast.
+- `--interrupt` marks the message time-sensitive. The receiving harness or operator decides whether to act on it now; the protocol delivers, the consumer routes.
+- `tt msg recv --follow` is a long-running tail (one JSON line per event) suited to harnesses that can monitor child stdout (Claude Code Monitor, terminals).
+- `tt msg recv --wait` exits on the next matching batch — ideal for harnesses that can launch a background command and notice when it completes; restart with `--after <last_event_seq>` to resume.
+The matching MCP tools are `send_message` (write) and `wait_for_events` (observer-safe long-poll). `get_room_events` now returns parsed `payload` for `message_sent` rows alongside the existing `handoff` field for legacy event types.
+### Observer-safe event long-poll
+`wait_for_events` is non-mutating by contract. It does not call `touchMember`, `touchKnownMember`, `touchWaitingMember`, or `purgeExpiredIdleRooms`. The only read it performs at entry is `requireRoom` for fail-fast on a missing room. Non-holders can long-poll the event log freely without disturbing the `last_wait_at` / `last_seen_at` bookkeeping that drives turn fairness.
+### `getLatestEventSeq` cursor helper
+`tt msg recv --wait|--follow` defaults to "start at now" — the highest `event_seq` in the room at startup time — so first-launch receivers don't replay history. Implemented as a single `SELECT MAX(event_seq) FROM room_events WHERE room_id = ?`, exposed on the service and commands layer. Operators wire `--after $LAST_SEQ` from their own bookkeeping when resuming after a crash; cursor persistence to disk is the harness's or plugin's responsibility per the receive-consumer contract.
+### Splice-at-1 parser repair for boolean flags after positionals
+The CLI parser consumes the next non-`--` token as a flag's value. That meant `tt msg send codex --interrupt body` would parse `interrupt="body"` and leave `codex` as the only positional. The handler now repairs this case by splicing the consumed value at positional index 1 (after the recipient), so `tt msg send codex --interrupt "body"` produces `recipient=codex`, `body="body"`, `delivery_hint=interrupt`. The existing `normalizeBooleanFlag` helper unshifts to the front (correct for `tt notes add --stdin` etc.); this new repair handles the `<positional> <body>` shape without weakening the generic parser.
+### Receive-consumer contract
+[`docs/receive-consumer-contract.md`](../receive-consumer-contract.md) documents the lifecycle expected of any receive consumer (CLI subprocess, future plugin, harness adapter): cursor persistence, replay coalescing on far-behind cursors, backpressure (drop-with-warning, never block the read loop), at-least-once delivery + dedupe on `event_id`, SIGTERM clean exit with the last cursor flushed to stderr.
+## Skill
+The bundled skill at [`skills/talking-stick/SKILL.md`](../../skills/talking-stick/SKILL.md) gains a new §4.5 *Out-of-band messaging* section:
+- send via `tt msg send <recipient> "<body>"` or MCP `send_message`
+- receive via `tt msg recv --wait` or `--follow` depending on what the harness can observe
+- when to message (conversational, ephemeral, between live processes) vs note (durable, resolvable artifacts) vs handoff (transfer of work)
+- messages are routing not ACL — `to_agent_id` is delivery, not privacy
+- messages do not grant the stick — paging the holder gets attention, not write authority
+- a `tt msg recv` subprocess does not replace `wait_for_turn` — keep waiting for your turn in parallel
+The skill also picks up a small note in §1 reminding harnesses that sibling `tt msg recv --wait` / `--follow` subprocesses may be running and should be left alone unless the operator says otherwise.
+## Migration
+`room_events` gains a nullable `payload_json TEXT` column (migration #5). `ALTER TABLE ADD COLUMN` is O(1) on populated tables; existing rows back-fill to NULL; legacy event types continue to write NULL via the optional `payload?` parameter on `appendEvent`. No action required by operators on upgrade — the column is invisible to v0.1.x clients.
+## Design properties pinned by tests
+- **Self-broadcast exclusion** for `target=self`: caller's own broadcasts (`to_agent_id IS NULL AND from_agent_id = caller`) are excluded from their default receive view; the audit path (`target=any`) still includes them. The SQL clause is `(event_type='message_sent' AND (to_agent_id = ? OR (to_agent_id IS NULL AND from_agent_id != ?)))` — pinned by tests 13a/13b/13c in `tests/oob-substrate.test.ts`.
+- **Closed-room behavior** (deferred): `wait_for_events` on a `state='closed'` room returns empty after deadline; no short-circuit, no error. Pinned by test 19a so a future `close_room` PR has to opt in to changing it.
+- **Body cap.** 4096 bytes UTF-8; rejected with typed `message_too_large`. No silent truncation.
+- **Sender filter** (`from_agent_id`) applied server-side, so cursor advancement under `tt msg recv --from <agent>` is honest.
+- **SIGTERM lifecycle** for `tt msg recv --follow` covered by a real subprocess test that spawns the CLI, sends a message via MCP, asserts the JSON line on stdout, sends SIGTERM, and verifies clean exit.
+## Verification
+```bash
+npm run typecheck         # clean
+npm run build             # clean
+npm test                  # 263 passed (was 257 before fd67873)
+tt --help | grep "tt msg" # tt msg send/recv visible
+```
+End-to-end dogfood pre-release: claude (MCP) ↔ codex (MCP) ↔ codex (CLI) round-tripped 6 messages (events 668→675) in the live coordination room with zero `pass_stick`/`release_stick` calls during the chat. Both `target=self` (excludes own broadcast) and `target=any` (includes own broadcast) verified in production.
+## Plan and design
+- [`docs/plans/out-of-band-signaling.md`](../plans/out-of-band-signaling.md) — converged design (commit 8069d84)
+- [`docs/plans/out-of-band-signaling-implementation.md`](../plans/out-of-band-signaling-implementation.md) — file-by-file build sequence with R1/R2 review history
+- [`docs/receive-consumer-contract.md`](../receive-consumer-contract.md) — lifecycle, cursor, replay, backpressure
+- [`skills/talking-stick/SKILL.md`](../../skills/talking-stick/SKILL.md) §4.5 — when-to-message-vs-note-vs-handoff guidance

package/docs/releases/0.3.0.md ADDED Viewed

@@ -0,0 +1,77 @@
+# Talking Stick 0.3.0
+Date: 2026-05-05
+Breaking release that makes the `tt` CLI the only harness integration contract.
+Talking Stick no longer installs or serves an MCP adapter. Agents coordinate by
+running `tt` subprocesses for join/wait/handoff, notes, messages, and event
+receive.
+## Breaking Changes
+### MCP server surface removed
+Removed the MCP stdio server implementation, `tt mcp` command registration,
+MCP-specific tests, and the `@modelcontextprotocol/sdk` dependency. The package
+exports no MCP server helpers. `tt --help` no longer advertises MCP startup, and
+`tt install` no longer writes MCP server config.
+### `tt install` is skill-only
+`tt install <harness>` now installs or refreshes the bundled
+`talking-stick` skill for Claude Code, Codex, Gemini, and OpenCode. The older
+`tt install-skill` and `tt uninstall-skill` command surface is gone because
+`tt install` / `tt uninstall` own skill installation directly.
+## Migration
+### Stale MCP cleanup
+Updates remove stale Talking Stick MCP registrations from older installs instead
+of keeping the broken dual integration path alive.
+Cleanup runs from:
+- package postinstall when installed under `node_modules/talking-stick`
+- `tt self-update` after the package manager command returns
+- the first normal installed-package `tt` invocation after a package-version
+  change
+- explicit `tt install` and `tt uninstall`
+Each run appends JSONL audit entries to
+`${TALKING_STICK_DATA_DIR}/update-migrations.log`. OpenCode cleanup is
+shape-strict: only the canonical `mcp.talking-stick` entry with `["tt", "mcp"]`
+is removed. Claude Code, Codex, and Gemini use their native `mcp remove`
+commands for the old `talking-stick` server name.
+## CLI-Only Runtime
+The bundled skill now teaches harnesses to start
+`tt events --follow --json` as the ambient receiver, keep
+`tt wait --json` running for turn ownership, and verify the
+returned guardian pid before long edits. `tt msg recv` remains a messages-only
+fallback; the unified event stream is the primary OOB path because turn
+handoffs and messages share one ordered feed.
+For harnesses that cannot consume a long-running stdout stream, the documented
+fallback is `tt events --wait --after <cursor> --json` as an observer-only wake
+process alongside the normal `tt wait --json` ownership loop. Event wakes do not
+grant the stick; agents still need a `your_turn` wait result and live guardian
+before editing.
+CLI identity resolution now prefers stable harness ancestry over transient
+terminal ids when no explicit harness session id exists. That keeps repeated
+shell-outs from one harness attached to the same room member.
+## Verification
+```bash
+npm run typecheck
+npm test
+npm run build
+git diff --check
+```
+Stage validation covered the migration runner, install/uninstall/self-update
+cleanup wiring, child-process CLI receive behavior, guardian repair, full-suite
+tests after MCP deletion, and built `dist/` output with no MCP/server files.

package/docs/talking-stick-plan.md CHANGED Viewed

@@ -742,8 +742,9 @@ Recommended defaults (product scale, sized for real agent work rather than chat
 owner_lease_ttl_ms         = 45 * 60 * 1000;       // 45 minutes
 heartbeat_interval_ms      =  5 * 60 * 1000;       // 5 minutes
 claim_ttl_ms               = 20 * 60 * 1000;       // 20 minutes
-wait_for_turn_max_wait_ms  = 30 * 1000;            // 30 seconds
+wait_for_turn_max_wait_ms  = 110 * 1000;           // 110 seconds
 wait_for_turn_poll_ms      = 250;                  // transport polling cadence
+wait_for_events_max_wait_ms = 110 * 1000;          // 110 seconds
 presence_ttl_ms            =  4 * 60 * 60 * 1000;  // 4 hours
 waiter_grace_ms            = 10 * 1000;            // 10 seconds
 ```
@@ -1158,5 +1159,5 @@ presence TTL:            4 hours
 close semantics:         no `close_room` tool in the MVP implementation;
                          rooms remain resumable and can become dormant
                          when nobody is live
-wait_for_turn max wait:  30 seconds, polled at 250 ms
+wait_for_turn max wait:  110 seconds, polled at 250 ms
 ```

package/package.json CHANGED Viewed

@@ -1,7 +1,7 @@
 {
   "name": "talking-stick",
-  "version": "0.1.4",
-  "description": "MCP coordination server for path-scoped agent handoffs.",
+  "version": "0.3.0",
+  "description": "CLI coordination tool for path-scoped agent handoffs.",
   "type": "module",
   "bin": {
     "tt": "dist/cli.js"
@@ -11,18 +11,19 @@
   },
   "files": [
     "dist",
+    "scripts",
     "skills",
     "docs",
     "README.md"
   ],
   "scripts": {
     "build": "tsc -p tsconfig.build.json && chmod +x dist/cli.js",
+    "postinstall": "node scripts/postinstall-mcp-cleanup.cjs",
     "prepare": "tsc -p tsconfig.build.json && chmod +x dist/cli.js",
     "test": "vitest run",
     "typecheck": "tsc -p tsconfig.json --noEmit"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.29.0",
     "better-sqlite3": "^12.9.0",
     "zod": "^3.25.76"
   },

package/scripts/postinstall-mcp-cleanup.cjs ADDED Viewed

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+const { spawnSync } = require("node:child_process");
+const fs = require("node:fs");
+const path = require("node:path");
+const cliPath = path.resolve(__dirname, "..", "dist", "cli.js");
+const packageRoot = path.resolve(__dirname, "..").replace(/\\/g, "/");
+if (
+  process.env.TALKING_STICK_DISABLE_MCP_MIGRATION ||
+  !packageRoot.includes("/node_modules/talking-stick") ||
+  !fs.existsSync(cliPath)
+) {
+  process.exit(0);
+}
+spawnSync(process.execPath, [cliPath, "migrate-mcp", "--reason", "update", "--quiet"], {
+  stdio: "ignore",
+  env: {
+    ...process.env,
+    TALKING_STICK_SKIP_STARTUP_MAINTENANCE: "1"
+  }
+});
+process.exit(0);

package/skills/talking-stick/SKILL.md CHANGED Viewed

@@ -1,6 +1,6 @@
 ---
 name: talking-stick
-description: Use when working in a repo that coordinates multiple agent harnesses with Talking Stick (`tt` / `talking-stick`), or when the user asks you to avoid parallel work, wait your turn, pass structured handoffs, or coordinate with Claude, Codex, Gemini, or OpenCode in the same workspace. Also use when a workspace contains a `.talking-stick/` marker or when the MCP tools `list_rooms`, `join_path`, `leave_room`, `kick_member`, `wait_for_turn`, `heartbeat`, `release_stick`, `pass_stick`, `takeover_stick`, `get_room_state`, `get_room_events`, `add_note`, or `list_notes` are available.
+description: Use when working in a repo that coordinates multiple agent harnesses with Talking Stick (`tt` / `talking-stick`), or when the user asks you to avoid parallel work, wait your turn, pass structured handoffs, or coordinate with Claude, Codex, Gemini, or OpenCode in the same workspace. Also use when a workspace contains a `.talking-stick/` marker.
 ---
 This skill teaches a harness how to behave in a Talking Stick workspace.
@@ -18,46 +18,67 @@ Use this skill when any of these are true:
 - the user mentions `talking-stick`, `tt`, handoffs, turn-taking, or avoiding parallel work
 - the repo is known to use Talking Stick coordination
 - a `.talking-stick/` marker exists
-- the Talking Stick MCP tools are available in the current harness
 Do not use this skill for ordinary single-agent work in repos that are not using Talking Stick.
 ## Workflow
-### 1. Check that Talking Stick is actually available
+### 1. Use The CLI
-Prefer the Talking Stick MCP tools when they are available. If they are not available but the `tt` CLI is on `PATH`, use the CLI instead (`tt list`, `tt join`, `tt leave`, `tt kick`, `tt wait`, `tt state`, `tt release`, `tt pass`, `tt assign`, `tt take`). Do not treat missing MCP tools alone as proof that coordination is unavailable.
+Use the `tt` CLI for all Talking Stick coordination. Do not use old Talking Stick MCP tools for repo coordination, even if an older install exposes them; the CLI is the source of truth. Current updates should remove stale Talking Stick MCP registrations automatically.
-If coordination is required and neither the MCP tools nor the `tt` CLI are available, say so briefly and ask the user whether they want to install or enable Talking Stick first. Do not pretend coordination is active.
+Useful commands:
+- `tt whoami --json`
+- `tt join --json`
+- `tt wait --json`
+- `tt try --json`
+- `tt state --json`
+- `tt events --after N --target any --json`
+- `tt notes add "..." --json`
+- `tt notes list --json`
+- `tt events --follow --json`
+- `tt msg send <recipient|room> "..." --json`
+- `tt msg recv --follow --json` (messages-only fallback when an event-stream consumer is too broad)
+- `tt release --stdin`
+- `tt assign <agent_id|next> --stdin`
+- `tt take --reason "..." --json`
+Some workspaces may also have sibling receive processes running `tt events --follow`, `tt msg recv --wait`, or `tt msg recv --follow`; leave them alone unless the operator explicitly asks you to stop or restart them.
+If coordination is required and `tt` is unavailable, say so briefly and ask the user whether they want to install or enable Talking Stick first. Do not pretend coordination is active.
 Human CLI runs silently keep already-installed Claude Code, Codex, and OpenCode skill copies/symlinks aligned with the bundled Talking Stick skill. This is best effort and only updates existing installs; Gemini skills are registry-managed and should be refreshed with `tt install gemini` when needed.
-### 2. Join the workspace room once
+### 2. Join The Workspace Room Once
-On the first substantial task in a Talking Stick workspace:
+On the first substantial task in a Talking Stick workspace, run:
-1. call `join_path` with the current workspace path
-2. keep the returned `room_id`
-3. note the returned policy, especially `heartbeatIntervalMs`
+```sh
+tt join --json
+```
-If the workspace is nested, accept the resolved canonical path the server returns.
+Keep the returned room id and canonical path in mind. The current working directory is the implicit path for normal commands; pass an explicit path only when coordinating a different directory or intentionally selecting a nested room.
-### 3. Wait before doing shared work
+Right after joining, start a background ambient receiver so direct messages and turn passes/reservations surface as soon as they happen instead of waiting for the next time you poll:
-Before making shared edits or running owner-style actions, call `wait_for_turn`.
+```sh
+tt events --follow --json
+```
-Use the `room_id` returned by `join_path`. Do not pass the original filesystem path to `wait_for_turn`; path resolution belongs to `join_path`, and waiting must target the exact resolved room. This avoids ambiguity when a nested workspace resolves to an ancestor room or when multiple rooms could exist under the same tree.
+For `tt events --wait` and `tt events --follow`, the default target is `self`; add `--target any` only for audit/debug views. If your harness can stream a child process's stdout into the model's context (Claude Code's Monitor, Codex `attach`-style), this is enough — each line becomes an event you see mid-task. If your harness can only notice that a backgrounded command exits, use the polling fallback in §4.5. Without an ambient receiver, neither messages nor turn handoffs reach you between deliberate `tt wait` / `tt events` calls.
-Keep the wait input minimal:
+The ambient receiver is not a turn claimant. It never grants the stick and never starts the lease guardian. Keep using `tt wait --json` for ownership.
-```json
-{
-  "room_id": "<room_id from join_path>",
-  "max_wait_ms": 110000
-}
+### 3. Wait Before Shared Work
+Before making shared edits or running owner-style actions, run:
+```sh
+tt wait --json
 ```
-`max_wait_ms` is optional. Use the longest client-safe wait you can support: 110000 ms is a good MCP default when the harness can tolerate it; 180000 ms is fine only when the tool/client timeout is known to exceed that. If the call times out at the harness layer, fall back to a shorter value and call again. Do not send `cursor`, even if an old tool schema still exposes it; `wait_for_turn` is cursor-free, and resumable event replay belongs to `get_room_events`.
+The default wait timeout is `110s`, which is the normal active-coordination setting. If your harness has a shorter tool timeout, override with the longest safe value and immediately wait again when it returns without granting the turn. Do not busy-loop with short waits.
 Possible outcomes:
@@ -66,131 +87,153 @@ Possible outcomes:
 - `takeover_available`: surface the reason and make takeover explicit
 - `closed`: stop and explain that the room is closed
-### 4. While waiting
-**Prefer to run the wait in the background.** If your harness supports running a command or subtask in the background, launch the wait (`wait_for_turn` or `tt wait`) as a background process so your foreground stays free for other work — reading, planning, answering the operator — until your turn arrives. Blocking the whole harness on the wait defeats the point.
-**Prefer wait cycles over scheduled wakeups.** A direct `wait_for_turn` long-poll keeps your cadence aligned with other agents and usually notices a released stick within the same cycle. Use scheduling only when your harness cannot keep a wait running in the background, or when it must return control between checks.
-Wakeup pattern:
+A successful `tt wait` or `tt take` starts an internal `tt guard` lease guardian and returns `guardian_pid` in JSON. Verify the field is present and the pid is alive before you start a long edit; the guardian is what keeps your lease from expiring after the foreground `tt wait` process exits. If `guardian_pid` is missing or the pid is gone, stop, run `tt wait` again to repair the guardian (it will detect the existing ownership and respawn the guardian), and only then continue. Do not kill that guardian.
-1. Probe `wait_for_turn` with `max_wait_ms: 0`.
-2. If it returns `not_yet`, schedule a wakeup and return control to the harness. Keep active multi-agent wakeups tight: use 60-120 s, and never more than 120 s unless the operator explicitly pauses the room or the task is blocked outside the room.
-3. On wakeup, repeat from step 1.
+### 4. While Waiting
-Scheduled wakeups are a fallback, not a reason to check in more slowly than agents using `wait_for_turn` directly. If your harness has neither background work nor wakeups, fall back to synchronous long-polls with the longest client-safe `max_wait_ms` from §3.
+Prefer to run `tt wait` in the background if your harness supports background commands. That keeps the foreground free for reading, planning, answering the operator, and watching OOB messages until your turn arrives.
-Whether the wait runs in the foreground or the background, call it **once** with the client-safe `max_wait_ms` budget from above and let the server long-poll. When it returns without `your_turn`, call it again. Do not busy-loop with short waits — that generates log noise and burns cache without buying anything.
+Prefer wait cycles over scheduled wakeups. A direct long-poll stays aligned with other agents and usually notices a released stick within the same cycle. Use scheduled wakeups only when your harness cannot keep a wait running in the background.
-Coordination is meant to be lightweight. `wait_for_turn` is the only long-running call you should make. Room-inspection RPCs (`get_room_state`, `get_room_events`) exist to answer specific questions ("who holds the stick right now?", "what was in my predecessor's handoff?") — do not call them on a timer or repeatedly just to check on another agent's progress. If you find yourself inspecting the room more than a few times per turn, stop; long-poll on `wait_for_turn` instead and trust the protocol.
+Do not replace `tt wait` with an event receiver. `tt events --wait` is only a wake channel for messages and handoff/reservation events. If it exits with a pass, release, assignment, or message, process the event, then run or continue `tt wait --json`; do not touch shared files unless that wait returns `your_turn` and a live `guardian_pid`.
 If you do not have the stick:
 - do not make shared repo changes
 - do not silently race another harness
-- it is fine to read, plan, review, or help the user think — or any other work that does not mutate shared state
+- it is fine to read, plan, review, or help the user think
 - tell the user who currently holds or is reserved the turn when that is useful
-The wait is for *active* non-mutating work, not idle sleep. Re-read the holder's last handoff, follow up on its `artifacts[]`, investigate the area they are touching, and rethink the plan from your own angle. If you find something the holder should know — a missed invariant, a related bug, a sharper plan — leave a note with `add_note` rather than sitting on it until your next turn. Notes do not grant permission to edit shared files; they are observations and pointers, not coordination bypasses. The point: while you wait you can still move the work forward by feeding the holder, not by stalling.
+The wait is for active non-mutating work, not idle sleep. Re-read the holder's last handoff, follow up on its `artifacts[]`, investigate the area they are touching, and rethink the plan from your own angle. If you find something the holder should know, leave a durable note:
-When you do take the stick, first read the attached handoff and load any useful `artifacts[]`, then run `list_notes` once so you see what other members left for you. The owner's turn is the right place to act on a note, not to debate it with its author mid-turn.
+```sh
+tt notes add "Finding or pointer for the current/next holder." --json
+```
-### 5. While holding the stick
+Room inspection exists to answer specific questions, not to poll. Do not run `tt state` after a routine `tt wait`; the wait result already says who owns or is reserved for the turn. Use `tt state`, `tt events --target any`, and `tt notes list` sparingly when the wait result is insufficient or you are debugging stale members, takeover, or history.
-If the task may run longer than a few minutes, heartbeat periodically.
+When you do take the stick, first read the attached handoff and load any useful `artifacts[]`, then run `tt notes list --json` once so you see what other members left for you.
-Use the cadence from `join_path.policy.heartbeatIntervalMs` when available. Do not invent your own cadence if the server already told you one.
+### 4.5 Out-Of-Band Messaging
-**Holding the stick is for active work.** The moment you stop actively editing, reasoning through edits, or asking the operator a blocking question, release or pass. Do not idle-hold the room while waiting on long verification, non-blocking operator input, CI, or any other pause where another harness could make progress.
+The talking stick guarantees single-writer authority over shared workspace state. It is not a chat protocol. For transient signaling, use messages.
-### 6. Takeover is explicit
+Send:
-If `wait_for_turn` reports `takeover_available`:
+```sh
+tt msg send <recipient|room> "message body" --json
+```
-- explain why takeover is available (`owner_timeout`, `owner_gone`, `claim_timeout`, `recipient_gone`)
-- do not silently take over just because it is possible
-- if takeover is chosen, call `takeover_stick`
-- after takeover, call `get_room_events` so you can reconstruct the last handoff before touching code
+Recipient is a full `agent_id`, an unambiguous active display name, or the literal `room` for broadcast. `--interrupt` marks the message as time-sensitive; the receiver decides whether to act on it now.
-If the operator explicitly tells you to take over despite a reservation or live owner, use the CLI path when available: `tt take --operator-requested --reason "<operator requested takeover>"`. Do not invent this override yourself; it is for direct operator intervention.
+Receive with the mode your harness can observe. The recommended primary path is the unified event stream you started in §2:
-### 7. Finish with a real handoff
+```sh
+tt events --follow --json
+```
-When you are done with your turn, default to `release_stick`.
+That streams direct messages, broadcasts, and turn passes/reservations for you as a single ordered feed — one JSON event per line. Use it whenever your harness can stream a child process's stdout into the model's context. If the harness can only notice that a backgrounded command exits, use the polling fallbacks:
-**Default to `release_stick`.** Releasing lets the server pick the next fair waiter: a recent waiter that is new or has gone longest without holding the stick. If the best-known candidate is between wait polls, the room can briefly stay claimable instead of pinning a stale reservation. This keeps the room open instead of silently turning agent-to-agent handoffs into a duopoly.
+```sh
+tt events --wait --after <last_event_seq> --json   # all event types
+tt msg recv --wait --after <last_event_seq> --json # messages only
+```
-Use `pass_stick` only when you have a concrete reason a specific named member must go next:
+Restart with the returned cursor to resume. `tt msg recv --follow` still exists for harnesses that want a messages-only feed, but the event stream is preferred because turn handoffs use the same channel and a messages-only consumer silently misses them.
-- they have unique context the next step requires
-- they hold a credential or capability others lack
-- the operator explicitly addressed the work to them
+For Codex-style harnesses that cannot consume a continuous stdout stream, the safe loop is: keep `tt wait --json` as the ownership wait, and separately run `tt events --wait --after <last_event_seq> --json` as a short-lived wake process. An event wake can tell you to read, reply, or retry `tt wait`; it is never permission to edit.
-Otherwise release. Ping-ponging `pass_stick` between two agents is an antipattern because it can lock humans out of their own room.
+Messages are public room events. Any room member can read them with `tt events --target any`. `to_agent_id` is routing, not an ACL.
-Always include a non-empty handoff.
+Messages do not grant the stick. A non-holder paging the holder does not gain write authority. Keep waiting for your turn; messages are only a side channel.
-**Keep handoffs tight.** Handoffs are persisted in the event log and re-read on claims. Aim for roughly 150-300 words of `status`; reference commits by SHA instead of restating diffs, and use `artifacts[]` with path, line range, and role instead of pasting code. The handoff is the headline; long-form context belongs in `docs/` or a note.
+### 5. While Holding The Stick
-Minimum handoff quality:
+Holding the stick is for active work. The moment you stop actively editing, reasoning through edits, or asking the operator a blocking question, release or assign the turn. Do not idle-hold the room while waiting on long verification, non-blocking operator input, CI, or any other pause where another harness could make progress.
-- `status`: what you finished, what changed, and what remains true
-- `next_action`: the concrete next step for the next owner
+The `tt guard` process spawned by `tt wait` keeps the lease alive during active work. Later owner commands such as `tt release`, `tt assign`, and `tt take` must run under the same harness identity. If identity is ambiguous, use the exact active id with `TT_HARNESS_AGENT_ID=<agent_id>`.
-Add `artifacts`, `open_questions`, and `do_not` when they will save the next harness real time or prevent rework.
+### 6. Takeover Is Explicit
+If `tt wait` reports `takeover_available`:
+- explain why takeover is available (`owner_timeout`, `owner_gone`, `claim_timeout`, `recipient_gone`)
+- do not silently take over just because it is possible
+- if takeover is chosen, run `tt take --reason "..." --json`
+- after takeover, run `tt events --target any --json` so you can reconstruct the last handoff before touching code
+If the operator explicitly tells you to take over despite a reservation or live owner, use:
+```sh
+tt take --operator-requested --reason "operator requested takeover" --json
+```
+Do not invent this override yourself; it is for direct operator intervention.
+### 7. Finish With A Real Handoff
-Example:
+When you are done with your turn, default to releasing:
-```json
+```sh
+tt release --stdin <<'JSON'
 {
-  "status": "Added the MCP smoke test and verified it against two clients sharing one SQLite database.",
-  "next_action": "Run the same handoff path through the human CLI and confirm pass/release behavior matches the MCP flow.",
+  "status": "Updated the CLI-only coordination plan and the bundled skill so harnesses use tt subprocesses for join, wait, OOB messaging, notes, and handoffs.",
+  "next_action": "Review the plan and then start the code-removal pass.",
   "artifacts": [
     {
-      "path": "tests/mcp-smoke.test.ts",
+      "path": "docs/plans/2026-05-05-cli-only-coordination.md",
       "role": "review",
-      "note": "End-to-end MCP adapter smoke coverage."
+      "note": "CLI-only migration plan."
     }
-  ],
-  "open_questions": [
-    "Should tt install default to copy or link for local development?"
   ]
 }
+JSON
 ```
-**`pass_stick` requires the target to be an active room member.** If the intended recipient's harness session has ended and they show as `inactive` in `get_room_state.members`, `pass_stick` can return `unknown_member`. Use `release_stick` instead; the next fair waiter can claim through the normal sequence path.
+Use `tt assign <agent_id> . --stdin` only when a specific named member must go next:
-Remember that the operator can join their own room as `human:<user>`. Default behavior should leave room for them to claim turns naturally; releasing rather than passing keeps that door open.
+- they have unique context the next step requires
+- they hold a credential or capability others lack
+- the operator explicitly addressed the work to them
-### 8. After passing or releasing, stay in the loop
+Otherwise release. Pinning turns between two agents is an antipattern because it can lock humans out of their own room.
+Always include a non-empty handoff. Keep it tight: aim for roughly 150-300 words of `status`; reference commits by SHA instead of restating diffs, and use `artifacts[]` with path and role instead of pasting code.
+Minimum handoff quality:
+- `status`: what you finished, what changed, and what remains true
+- `next_action`: the concrete next step for the next owner
+Add `artifacts`, `open_questions`, and `do_not` when they will save the next harness real time or prevent rework.
-**The default after `release_stick` or `pass_stick` is to re-enter the wait loop and keep waiting until your next turn arrives.** Do not stop and ask the operator whether they want you back in the loop. Do not treat a handoff as end-of-session. In a multi-agent workspace, the expectation is: work on your turn, hand off, wait for your next turn, repeat.
+### 8. After Release, Stay In The Loop
-Stopping to ask questions after every handoff defeats the coordination protocol — the operator wired you into a room so that you *would* keep showing up without being asked.
+The default after `tt release` or `tt assign` is to re-enter the wait loop and keep waiting until your next turn arrives. Do not stop and ask the operator whether they want you back in the loop. Do not treat a handoff as end-of-session.
 Exit the wait loop only when one of these is true:
-- the shared task is explicitly finished (the operator said so, or the final handoff marks the work complete)
+- the shared task is explicitly finished
 - you are the only active member and there is no one to hand off to
-- the operator gives a direct redirect or stop ("that's enough," "drop out of the room," a new unrelated task, etc.)
+- the operator gives a direct redirect or stop
-In every other case: after `release_stick` or `pass_stick`, go straight back into the wait loop (ideally backgrounded — see §4).
+In every other case, after `tt release` or `tt assign`, go straight back into `tt wait --json`.
-If the operator tells you to drop out of coordination, call `leave_room` or `tt leave`. Rooms with no active members are deleted instead of kept as history, and long-idle rooms may be purged on later invocations.
+If the operator tells you to drop out of coordination, run `tt leave --json`. Rooms with no active members are deleted instead of kept as history, and long-idle rooms may be purged on later invocations.
-If the room state shows ghost members from past sessions whose processes are gone (visible as `inactive last seen ...` in `tt state`), call `kick_member` / `tt kick <agent_id>` to evict them. This is the right tool when liveness has already decided the target is dead — pass `force: true` only when the operator explicitly tells you to remove a still-active member.
+If the room state shows ghost members from past sessions whose processes are gone, run `tt kick <agent_id> --json` to evict them. Use `--force` only when the operator explicitly tells you to remove a still-active member.
-## Recovery and Inspection
+## Recovery And Inspection
 Use these reads when you need context:
-- `list_rooms`: discover active rooms under a path
-- `leave_room`: explicitly remove your membership from a room
-- `kick_member`: evict an idle member whose process is gone (use `force: true` only on operator instruction)
-- `get_room_state`: authoritative current room projection
-- `get_room_events`: replay recent claims, releases, passes, and takeovers
+- `tt list --json`: discover active rooms under the current path
+- `tt state --json`: authoritative current room projection
+- `tt events --target any --json`: replay recent claims, releases, assignments, messages, and takeovers
+- `tt notes list --json`: list durable notes
+- `tt whoami --explain`: inspect identity resolution
-Prefer `get_room_state` over guessing from local memory when ownership may have changed.
+Prefer `tt state` over guessing from local memory when ownership may have changed and you are not already looking at a fresh `tt wait` result.
 ## Behavior Priorities