talking-stick 0.2.0 → 0.3.0

package/docs/plans/2026-05-05-cli-only-coordination.md

@@ -0,0 +1,224 @@
+# CLI-Only Coordination And MCP Removal
+
+**Status:** draft by `codex:d4bc2492`, incorporating Claude OOB review. **Branch:** `oob-identity-fix-plan`.
+
+## Why This Change
+
+Out-of-band messaging exposed a deeper problem: Talking Stick has two harness integration paths, CLI and MCP, and they do not share the same process context. A message addressed to the MCP-side agent id can disappear from `tt msg recv --target self` if the CLI-side resolver produces a different id. Fixing one resolver bug helps, but keeping MCP in the active path preserves the same class of failure.
+
+The new direction is simpler: **the `tt` CLI is the only harness contract.** Agents coordinate by running `tt` commands. MCP is removed from install, docs, skills, tests, and eventually package dependencies. The SQLite-backed service/core can stay as internal implementation; the public automation surface is `tt`.
+
+## Goals
+
+- Make every agent workflow expressible through CLI commands: `tt join`, `tt wait`, `tt release`, `tt assign`, `tt take`, `tt state`, `tt events`, `tt notes`, and `tt msg`.
+- Make ambient receive CLI-first: `tt events --follow --json` for live stdout consumers, `tt events --wait --after <cursor> --json` for process-completion consumers, and `tt msg recv` only for messages-only consumers. `--wait` and `--follow` default to `--target self`.
+- Remove MCP registration from `tt install` and remove `tt mcp` as a supported command.
+- Automatically remove stale Talking Stick MCP registrations from every supported harness during update/first-run migration.
+- Update the bundled skill so harnesses prefer CLI even when MCP tools exist in older installations.
+- Replace MCP smoke coverage with real child-process CLI smoke coverage, including SIGTERM/cursor behavior.
+- Keep long turns safe by making the CLI-owned lease guardian a first-class contract of `tt wait` / `tt take`.
+- Preserve human-friendly CLI defaults: human shells get readable text unless `--json` is explicit; harness-detected shells get JSON where machine output is expected.
+
+## Non-Goals
+
+- No backward compatibility promise for MCP users beyond automatic cleanup of stale Talking Stick-owned MCP registrations. This is an intentional breaking simplification.
+- No plugin requirement. Plugins may later wrap the CLI, but v1 must work with subprocesses and stdout.
+- No daemon. The existing SQLite service and `tt guard` process model remain enough; do not reintroduce a long-running automation server under another name.
+- No change to the single-writer room semantics.
+
+## Target Architecture
+
+### Public Surface
+
+`tt` is the public API. Harnesses call it through shell/exec facilities and parse JSON when they need structured output.
+
+Core command mapping:
+
+| Need | CLI |
+|---|---|
+| Join room | `tt join [path] --json` |
+| Wait/claim | `tt wait [path] --json` |
+| Probe | `tt try [path] --json` |
+| Release | `tt release [path] --stdin` |
+| Assign specific next holder | `tt assign <agent_id> [path] --stdin` |
+| Operator takeover | `tt take [path] --operator-requested --reason ... --json` |
+| State | `tt state [path] --json` |
+| Events | `tt events [path] --after N --target any --json` |
+| Notes | `tt notes add/list ... --json` |
+| Send OOB | `tt msg send <recipient|room> <body...> --json` |
+| Ambient receive | `tt events --follow --json` |
+| Messages-only receive | `tt msg recv --follow --json` |
+
+The skill should teach these exact commands. It should not mention `join_path`, `wait_for_turn`, `release_stick`, `send_message`, or any MCP tool as a preferred path.
+
+Successful `tt wait` and `tt take` calls must start or repair the internal `tt guard` lease guardian and return its `guardian_pid` in JSON. That guardian is not a harness API; it is the CLI's mechanism for keeping long turns alive after the `tt wait` process exits.
+
+### Internal Surface
+
+Keep `TalkingStickService` / `TalkingStickCommands` as internal TypeScript modules backing the CLI. They are not the harness API. The command layer owns input parsing, identity, JSON/text output policy, guardian spawning, and child-process behavior.
+
+The CLI-only rule applies to external harness coordination. Same-package processes may still call internal modules when they are part of Talking Stick itself. The diff walker should use direct SQLite or internal service reads for its hot attribution/watch path, then use normal CLI commands for rare outward actions such as sending an annotation message or adding a note.
+
+### Holder Lease Guardian
+
+Claude's main review concern is load-bearing: if `tt wait` exits and no process continues heartbeating, a holder doing a long edit can time out and look stale. The current `tt wait` path already has the right shape: it spawns internal `tt guard` and records the guardian in the CLI session. The CLI-only migration should make that behavior explicit and tested, not incidental.
+
+Required behavior:
+
+- `tt wait --json` returning `your_turn` includes `guardian_pid`.
+- `tt take --json` returning success includes `guardian_pid`.
+- If the caller already owns the turn and the old guardian is gone, `tt wait` repairs it by spawning a replacement.
+- `tt release`, `tt pass`, and `tt assign` do not require the original `tt wait` process to still exist; they rely on the persisted CLI session and identity.
+- Tests kill the guardian and prove the next owner command either repairs or reports the problem clearly.
+
+This avoids a harness-level `tt heartbeat` timer and avoids wrapping all work in a daemon-like `tt hold` command.
+
+### Process Cost
+
+CLI-only coordination pays a Node startup and SQLite-open cost for every command. That is acceptable for `tt wait` cycles, handoffs, notes, and OOB messages. Do not answer this by adding a long-running daemon unless the operator explicitly reverses the CLI-only decision; a daemon would recreate the same dual-context class of failure that led to removing MCP.
+
+### Identity
+
+With MCP removed, issue #19 becomes a CLI-only identity reliability issue instead of a CLI-vs-MCP comparison. The resolver still needs to be stable across repeated shell-outs from the same harness:
+
+1. `TT_HARNESS_AGENT_ID` wins when explicitly exported.
+2. Harness-provided stable ids win next (`CODEX_THREAD_ID`, `OPENCODE_RUN_ID`, similar).
+3. Harness-root ancestry wins before terminal ids for no-session-id harnesses like Claude Code.
+4. Terminal ids (`ITERM_SESSION_ID`, `CMUX_TAB_ID`, etc.) are fallback only after no harness root can be found.
+5. Human fallback remains `human:<username>`.
+
+Live receivers should either use the resolved harness id directly or run under `TT_HARNESS_AGENT_ID=<agent_id>` when a wrapper has already joined a room as that id.
+
+### Install
+
+`tt install` should become a skill/bootstrap installer, not an MCP installer. Update paths should also clean up old MCP registrations automatically so existing harnesses stop seeing the removed integration surface.
+
+Proposed behavior:
+
+- `tt install <harness...> | --all [--print] [--copy] [--link]`: install/update the bundled skill only.
+- Remove `tt install-skill` / `tt uninstall-skill` once `tt install` owns skill installation. There is no compatibility requirement to keep parallel install verbs.
+- `tt uninstall`: remove the skill install and Talking Stick-owned stale MCP config entries.
+- Remove MCP config writes for Claude, Codex, Gemini, and OpenCode.
+- Remove `DEFAULT_SERVER_COMMAND = ["tt", "mcp"]`.
+- Remove native `harness mcp add/remove` command planning.
+
+### Update-Time MCP Cleanup
+
+Backward compatibility means removing the stale broken path, not keeping it alive. A user who updates from an MCP-capable version should not have to manually edit every harness config.
+
+Required behavior:
+
+- The package update lifecycle runs a cleanup pass when the package manager executes install/update scripts.
+- `tt self-update` in versions that know about this migration runs the cleanup pass after the package manager completes.
+- The first normal `tt` invocation after a package version change runs the same cleanup pass, covering users who update from an older `tt self-update`, skip lifecycle scripts, or use `npm update -g`, `mise`, `pnpm`, or another manager.
+- Cleanup targets all supported harness config locations, not only the currently detected harness. Old entries in Claude, Codex, Gemini, and OpenCode should be removed together.
+- The cleanup is idempotent and silent when nothing changes. If it modifies config during an interactive human CLI run, print a concise summary; harness JSON commands should not get noisy text.
+- Always append an audit entry for removals with harness, config path, and removed server key/name so an operator can inspect why an MCP entry disappeared.
+- Only remove Talking Stick-owned MCP entries by strict inverse-of-install matching: canonical server name/key `talking-stick` plus the exact command/args shape this installer previously wrote for that harness.
+- Leave hand-edited or custom entries alone, even if they mention `talking-stick`, when the name/key or command/args no longer match the canonical installed shape.
+- Do not remove unrelated MCP servers or unrelated harness settings.
+- Config writes remain atomic and should preserve formatting where the existing installer machinery already can.
+
+Implementation shape:
+
+- Add `removeStaleMcpRegistrations({ harnesses: "all", reason: "update" })` in the install/maintenance layer.
+- Track the last package version that completed migration in the Talking Stick data dir, separate from room state, so startup can cheaply decide whether to run it.
+- Expose a non-interactive internal cleanup entrypoint that package lifecycle scripts can call without joining rooms or emitting harness JSON.
+- Reuse the existing harness config discovery/write helpers and adapter-level install shape. Removal should be the inverse of install, not a second parser/matcher.
+- Delete MCP add planning after cleanup support lands, but keep the adapter-owned stale-entry removal path.
+- Add fixture tests for each supported harness proving a stale canonical Talking Stick MCP entry is removed, a neighboring unrelated MCP entry survives, and a hand-edited Talking Stick-looking entry survives.
+- The audit log lives in a dedicated `${TALKING_STICK_DATA_DIR}/update-migrations.log`, not the general maintenance log. Update migrations are infrequent destructive events that operators may need to grep for after the fact ("why did my MCP entry disappear?"); mixing them with daily startup chatter makes that grep noisy and the destructive history harder to see at a glance. Format: one JSON line per migration run with `{ ts, package_version_from, package_version_to, harness, config_path, action, server_name }`.
+
+### OOB Messaging And Ambient Receive
+
+OOB stays on the existing `room_events` / `message_sent` substrate, but all live receive UX is CLI-based.
+
+The recommended ambient consumer is **`tt events --follow --json`**, not `tt msg recv --follow`. The event stream surfaces direct messages, broadcasts, **and** turn passes/reservations on a single ordered feed. A messages-only receiver silently misses the moment another agent passes you the stick — exactly the gap that motivated this section. The skill teaches the unified consumer in §2 (start it right after `tt join`) and references it from §4.5.
+
+Required receive contract:
+
+- `tt events --follow --json` emits one JSON event per line for messages, broadcasts, and turn handoffs targeting the caller.
+- It exits cleanly on SIGTERM/SIGHUP and writes the cursor to stderr as today.
+- `tt events --wait --after <cursor> --json` exits after the next matching batch for harnesses that cannot monitor long-running stdout.
+- Event receive is observer-only. It does not claim the stick, does not start a guardian, and must not be treated as permission to edit. A receiver that wakes on `pass`, `release`, or `assignment` still has to run `tt wait --json` and get `your_turn` before touching shared files.
+- `tt msg recv --follow` and `tt msg recv --wait` remain available as messages-only feeds for harnesses that explicitly want the narrower stream, but the skill marks them as fallback rather than primary.
+- First launch starts at the room tail unless `--after` is explicit, avoiding historical replay.
+- Direct messages and room broadcasts are included for `target=self`; the caller's own broadcasts are excluded.
+
+## Implementation Sequence
+
+### Stage 1 — Skill And Plan
+
+This PR:
+
+- Add this plan.
+- Update `skills/talking-stick/SKILL.md` to be CLI-only.
+- Remove MCP-first language from the OOB skill section.
+- Keep source code unchanged except docs/skill, so Claude can review direction before the destructive code pass.
+
+### Stage 2 — CLI Identity Hardening
+
+- Change resolver precedence so harness-root ancestry beats terminal-session fallback when a harness env marker exists but no stable session id is present.
+- Add tests for Claude CLI shell-out matching repeated invocations from the same harness root.
+- Add child-process tests proving `tt events --wait` / `tt events --follow` default to self and receive direct messages and turn handoffs addressed to the active CLI member without `TT_HARNESS_AGENT_ID`.
+- Keep narrower coverage proving `tt msg recv` receives direct messages without widening into non-message events.
+- Add guardian tests proving `tt wait` / `tt take` return a live `guardian_pid`, and that a subsequent `tt wait` repairs a dead guardian for an existing owner.
+- Keep `TT_HARNESS_AGENT_ID` override as the explicit escape hatch.
+
+### Stage 3 — Installer De-MCP
+
+- Change `tt install` / `tt uninstall` to manage skill installs plus cleanup of stale Talking Stick MCP entries.
+- Add automatic stale MCP cleanup to package update lifecycle, `tt self-update`, and first-run-after-version-change startup maintenance.
+- Delete MCP add planning from `src/install.ts`; keep only the adapter-owned inverse-of-install removal/migration code needed to clean stale Talking Stick-owned entries.
+- Remove stale Talking Stick MCP entries during `tt uninstall` too; do not remove unrelated harness config.
+- Update README install instructions.
+- Add tests showing `tt install --all` skips missing harnesses silently and does not write MCP config.
+- Add update-migration tests covering all supported harnesses, idempotency, and preservation of unrelated MCP servers.
+
+### Stage 4 — Remove MCP Server Surface
+
+- Remove `tt mcp` from the command registry and help.
+- Delete `src/mcp-server.ts` and MCP-specific tests.
+- Delete `src/server.ts` unless another stdio entrypoint still needs it.
+- Remove `@modelcontextprotocol/sdk` from `package.json`.
+- Remove MCP exports from `src/index.ts`.
+- Replace MCP smoke tests with CLI child-process smoke tests covering join/wait/release/msg/notes.
+
+### Stage 5 — Docs And Release Notes
+
+- Rewrite README around CLI-first coordination.
+- Update `docs/receive-consumer-contract.md` to describe CLI subprocess consumers, not MCP wrappers.
+- Update older OOB plan docs with a superseded note pointing here.
+- Add a release note marking the change as breaking.
+
+### Stage 6 — Live Dogfood
+
+Before merging the code-removal PR:
+
+- Start Claude receiver with `tt events --follow --json`.
+- Start Codex receiver the same way.
+- Send direct and broadcast messages both directions.
+- Verify `tt wait --json`, `tt release --stdin`, and `tt assign <agent>` work from harness shell-outs.
+- Verify no MCP subprocess is required for the room to operate.
+
+## Risks
+
+- **Harnesses without reliable shell execution.** If a harness cannot run `tt`, it cannot use Talking Stick. That is acceptable under the new direction; the installer/skill should say so clearly.
+- **Lease expiry during long turns.** If guardian spawning regresses, long owner turns can time out after `tt wait` exits. Treat guardian behavior as required CLI surface and cover it with child-process tests.
+- **Per-command process cost.** Repeated `tt` shell-outs pay Node startup and SQLite open cost. Accept this as the cost of a single CLI context; do not reintroduce a daemon/MCP-like server without an explicit operator change.
+- **Long-running receiver lifecycle.** Some harnesses cannot monitor stdout from a running child. Keep `--wait --after` as the supported fallback.
+- **Combined wait/event command ambiguity.** A future `tt await`-style command needs a separate design pass. It must distinguish observer events from ownership results so an agent cannot mistake a message or handoff wake for permission to edit.
+- **Skill drift.** Installed skills may still have old MCP-first text. Human CLI startup sync helps file-based installs, but Gemini registry installs still need `tt install gemini`.
+- **Config cleanup safety.** Automatic update cleanup can be destructive if the matcher is too broad. Match only canonical inverse-of-install Talking Stick MCP entries and test with unrelated neighboring MCP servers plus hand-edited Talking Stick-looking entries in every harness fixture.
+- **Large test deletion.** Removing MCP tests can accidentally reduce protocol coverage. Replace them with CLI tests before deleting assertions.
+- **Diff walker hot path.** A live watcher should not spawn `tt` for every file event. Use direct SQLite/internal reads for hot attribution and CLI subprocesses only for outward coordination events.
+
+## Decisions From Claude Review
+
+1. `tt install` fully replaces `tt install-skill`; remove the parallel verb in the destructive code pass.
+2. `tt mcp` is removed immediately rather than kept as a migration shim.
+3. Update/first-run maintenance must automatically remove Talking Stick-owned stale MCP config entries across all supported harnesses, and `tt uninstall` should run the same cleanup. It must not touch unrelated harness config.
+4. Stale MCP cleanup must reuse each harness adapter's install resolver as the inverse operation. Do not reimplement config matching separately.
+5. The diff walker can read SQLite/internal state directly for its hot watch path because it ships in this package; user-facing annotations still go through `tt msg send` or `tt notes add`.
+6. The skill's primary ambient receiver is `tt events --follow --json`, not `tt msg recv --follow`. A messages-only consumer silently misses turn passes/reservations and forces harnesses back to polling for the most load-bearing event in the protocol. The unified event stream is the recommended primary path; `tt msg recv` becomes a narrower fallback.
+7. Cleanup audit lives in a dedicated `update-migrations.log`, not folded into general maintenance logging. Update migrations are infrequent destructive events; isolating them keeps "why did my MCP entry disappear" answerable by a single `cat`.

package/docs/plans/out-of-band-signaling-implementation.md

@@ -350,7 +350,7 @@ Four bound parameters of the caller's agent_id. Acceptable; SQLite's planner han
 Add three policy values:
 
 ```ts
-waitForEventsMaxWaitMs: number;   // default 30_000 (matches waitForTurn)
+waitForEventsMaxWaitMs: number;   // default 110_000 (matches waitForTurn)
 waitForEventsPollMs: number;      // default 250  (matches waitForTurn)
 waitForEventsBatchLimit: number;  // default 100
 ```
@@ -662,7 +662,7 @@ The talking stick guarantees single-writer authority over shared workspace state
 
 **Send.** `tt msg send <recipient> "<body>"` (or `mcp send_message`). Recipient is a full `agent_id`, an unambiguous active display name, or the literal `room` for broadcast. `--interrupt` flags the message as time-sensitive; the receiver decides whether to act on it now.
 
-**Receive.** Use the receive mode your harness can actually observe. If it can monitor stdout from a long-running child, run `tt msg recv --follow`; each incoming event lands as one JSON line. If it can only notice that a background command completed, run `tt msg recv --wait --after <last_event_seq>`; it exits on the next matching batch, then you start it again with the returned cursor. SIGTERM exits cleanly; restart with `--after <last_event_seq>` to resume.
+**Receive.** Use the receive mode your harness can actually observe. If it can monitor stdout from a long-running child, run `tt events --follow`; each incoming event lands as one JSON line. If it can only notice that a background command completed, run `tt events --wait --after <last_event_seq>`; it exits on the next matching batch, then you start it again with the returned cursor. SIGTERM exits cleanly; restart with `--after <last_event_seq>` to resume. Use `tt msg recv` only for messages-only consumers that intentionally do not want turn handoff events.
 
 **When to message vs note vs handoff.**
 
@@ -672,12 +672,12 @@ The talking stick guarantees single-writer authority over shared workspace state
 
 **Messages are not private.** Any room member can read any message via `get_room_events` or `tt events --follow --target any`. `to_agent_id` is routing, not ACL.
 
-**Messages do not grant the stick.** A non-holder paging the holder does not gain write authority. The holder may act on the message immediately or defer until handoff.
+**Messages and event wakes do not grant the stick.** A non-holder paging the holder does not gain write authority, and a receiver waking on `pass`, `release`, or `assignment` still has to run `tt wait` and receive `your_turn` before editing. The holder may act on the message immediately or defer until handoff.
 
-**Stay in the wait loop in parallel.** A `tt msg recv --wait` or `--follow` subprocess does not replace `wait_for_turn`. Keep waiting for your turn; messages are a side channel.
+**Stay in the wait loop in parallel.** A `tt events --wait`, `tt events --follow`, or `tt msg recv` subprocess does not replace `wait_for_turn`. Keep waiting for your turn; receive processes are side channels.
 ```
 
-Also: a one-line addition to §1 ("Check that Talking Stick is available") noting that `tt msg recv --wait` / `--follow` may be running as sibling processes and should be left alone.
+Also: a one-line addition to §1 ("Check that Talking Stick is available") noting that `tt events --follow`, `tt msg recv --wait`, or `tt msg recv --follow` may be running as sibling processes and should be left alone.
 
 ### 4.1 Skill propagation
 

package/docs/receive-consumer-contract.md

@@ -1,6 +1,6 @@
 # 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 msg recv --wait`, `tt msg recv --follow`) and future harness-native consumers should share the same cursor and retry rules.
+`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
 
@@ -11,20 +11,22 @@
 
 ## Receive Modes
 
-- Use `tt msg recv --follow --after <cursor>` when the harness can monitor stdout from a long-running child. Each output line is one `RoomEvent` JSON object.
-- Use `tt msg recv --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 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` receives direct messages to the caller plus broadcasts from other agents. It excludes the caller's own broadcasts.
-- `target=any` receives all matching messages and is intended for audit/debug views.
+- `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` running separately. Message receive processes do not claim or grant the stick.
+- 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.3.0.md

@@ -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

@@ -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

@@ -1,7 +1,7 @@
 {
   "name": "talking-stick",
-  "version": "0.2.0",
-  "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

@@ -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);