talking-stick 0.2.0 → 0.4.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/2026-05-06-harness-instructions-v6-converged.md

@@ -0,0 +1,220 @@
+# v6 converged design — harness instructions
+
+> **Status:** converged claude + codex design.
+>
+> **Convergence path:** independent drafts written in parallel, then debated
+> by cross-reference. Outcomes: claude conceded load-mechanism (separate
+> `tt instructions show` call, not piggyback on `tt join`); codex conceded
+> file-structure (single file per layer, not per-harness) and materialization
+> (lazy on edit, never on install). Naming, CLI surface, project-file scope,
+> and bundled-skill scope were already aligned.
+>
+> The pre-debate drafts (`v6-claude.md`, `v6-codex.md`) were deleted after
+> convergence per Wojtek: "if they write something they need to delete the
+> pre-debate versions after convergence."
+
+## Problem
+
+v5 collapsed the phase guidance into bundled `SKILL.md`. Wojtek's pushback:
+*"The skill ships with the binary, which means people won't be able to edit. I
+want them to be able to edit, but I still want it to be simple."* `tt install`
+links the bundled skill by default and startup sync can refresh copied
+installs — there is no durable user-edit affordance.
+
+v6 fixes this with editable Markdown instructions, seeded lazily, opened with
+`$EDITOR`. Not JSON profiles. Not a config subsystem.
+
+## Shape
+
+Two layers of concern, kept separate by design:
+
+### 1. Bundled skill floor (`skills/talking-stick/SKILL.md`)
+
+Immutable, package-owned. Covers join, wait, guardian checks, release/handoff,
+event-wake safety, takeover, notes, messages, and the "keep using the stick
+until done" rule. Tells agents how to load the editable collaboration
+instructions. **Does not include phase vocabulary or typical fits** — those
+live in the editable layer with bundled defaults as fallback inside the
+instructions code path, not duplicated into the safety contract.
+
+### 2. Editable collaboration instructions
+
+Single Markdown file per layer, with optional per-harness sections inside:
+
+```
+~/.local/share/talking-stick/instructions.md      # user override (optional, XDG-aware)
+<repo>/.talking-stick/instructions.md             # project override (optional)
+```
+
+Bundled defaults live as text constants in `src/instructions.ts` — they are
+the seed text and the always-available fallback if no editable file exists.
+
+The file uses `## <Harness>` section headers. The effective text for a given
+harness is: shared preamble (everything before the first `##`) + the matching
+harness section.
+
+## Effective-text resolution
+
+Additive concatenation in layer order: bundled → user → project. Later layers
+add or override by plain language; the model weighs the concatenated text. No
+merge semantics, no structured fields, no precedence rules beyond "later text
+typically wins by recency." Bundled safety floor (the SKILL.md content)
+remains higher than editable content always — operators cannot use
+instructions to override the coordination safety contract.
+
+## Loading
+
+Agents call `tt instructions show --json` once after `tt join` on the first
+substantial task in a room. The command infers the caller's harness from
+identity detection (no `--harness` flag needed). The JSON result includes the
+effective Markdown text and the file paths that contributed to it.
+
+If the command fails, agents continue with the bundled `SKILL.md` guidance
+alone. Coordination must never depend on instructions loading successfully.
+
+`tt join` returns membership/coordination state only; instructions are
+deliberately separate.
+
+## CLI surface
+
+```
+tt instructions show   [--harness <name>] [--scope effective|user|project|bundled] [--json]
+tt instructions edit   [--user|--project]
+tt instructions reset  [--user|--project]
+```
+
+- `show` defaults to `--scope effective` and the detected current harness.
+- `edit` opens `$VISUAL`, then `$EDITOR`, then a platform default if available;
+  prints the file path if no editor is found. Defaults to `--user`.
+- `edit` materializes the seed text on first use, then opens the editor.
+  Subsequent edits open the existing file in place.
+- `reset` requires explicit scope (no implicit `--user`); deletes the file at
+  the chosen scope so the layer below wins again.
+
+**Cut from both drafts:** `set`/`append`/`init`/`diff`. Editor-only for v1.
+Agents holding the stick can write to `<repo>/.talking-stick/instructions.md`
+directly via filesystem.
+
+## Materialization
+
+Lazy on first `tt instructions edit`, never on `tt install`. Reasoning:
+- Operators who never customize stay on shipped defaults forever — package
+  updates flow through automatically with no stale local copies.
+- Operators who customize get a one-time materialization at the moment they
+  show intent (running `edit`).
+- `tt install` stays fast and scriptable; no extra files written.
+
+`tt install` final output gains one hint:
+
+```
+Customize collaboration instructions with: tt instructions edit
+```
+
+No interactive prompt.
+
+## Bundled defaults (content)
+
+Text constants in `src/instructions.ts`. Short. Cover:
+
+- the "keep using Talking Stick until the shared task is done" rule,
+  including "prefer continued action unless the task is complete or the
+  operator explicitly redirects/stops",
+- the phase vocabulary: draft, adversarial review, convergence,
+  implementation, implementation review, test review, release,
+- typical fits (advisory, not enforced):
+  - Claude: prose, first-pass synthesis, tool-running, implementation review,
+    test review.
+  - Codex: adversarial review, convergence, implementation, edge cases,
+    release mechanics after operator approval.
+  - Gemini/OpenCode: conservative starter guidance until dogfood gives
+    evidence.
+
+These are defaults, not a scheduler. Talking Stick does not auto-route turns
+based on them.
+
+## Parallel drafting without workspace clutter
+
+Wojtek's target default is independent read-only planning first, then debate
+until convergence. His concern was not the independent thinking; it was
+workspace clutter and imposed file structure: *"I'm not sure I want to default
+to the models writing drafts or imposing a file structure on the workspace. I
+guess maybe if they write something they need to delete the pre-debate versions
+after convergence."*
+
+So the default is **read-only independent drafts**, not repo draft files.
+Rules when this happens:
+
+- **Drafts go in handoff `status` text or room notes by default**, not in
+  workspace files. Coordination channels are the natural place for read-only
+  position exchange.
+- **If files are unavoidable** (drafts too long for handoffs/notes), use
+  files in `docs/plans/` with clear `*-<harness>-draft.md` naming, and
+  **delete them after convergence**. Only the converged artifact remains.
+- Single-agent rooms and tiny tasks can skip parallel drafting.
+- The default for larger multi-agent planning is: draft independently, debate,
+  converge, then write only the converged artifact if a workspace file is
+  useful.
+
+This is still prompt guidance, not protocol. Talking Stick does not create
+draft files, track phases, or auto-route turns based on this pattern.
+
+## What we explicitly do not build
+
+- No JSON config, no schema, no validator beyond a soft size cap on read.
+- No structured merge semantics. Plain Markdown concatenation.
+- No `set`/`append`/`init`/`diff` commands.
+- No materialization on install.
+- No phase tracking in the protocol. No `tt phase set`. No `phase` field in
+  handoff types.
+- No `tt state` rendering changes.
+- No model overlays.
+- No auto-routing by harness.
+- No instruction-text override of the bundled safety floor.
+
+## Implementation order
+
+1. `src/instructions.ts` — bundled default text constants, layer resolver
+   (bundled → user → project, additive concatenation), XDG-aware path
+   resolution, `## <Harness>` section parser, soft size cap.
+2. Add `tt instructions show` (CLI + service plumbing).
+3. Add `tt instructions edit` with `$VISUAL` / `$EDITOR` / platform fallback.
+   Materializes seed on first use.
+4. Add `tt instructions reset`.
+5. Edit bundled `SKILL.md`: keep current safety contract, add one short line
+   pointing agents at `tt instructions show --json` after first `tt join`.
+6. Update `tt install` final output with the customize hint.
+7. Tests: `tests/instructions.test.ts` for layer resolution, missing files,
+   materialization-only-on-edit, section parsing, additive concatenation,
+   bundled-fallback when commands fail. Extend `tests/cli.test.ts` for the
+   new commands.
+8. README: replace `tt install-skill` references with `tt install`; add a
+   short paragraph on `tt instructions edit` for customization.
+9. Release notes entry.
+
+## Acceptance criteria
+
+- A fresh user can install with `npm i -g talking-stick && tt install --all`
+  and get useful defaults without answering prompts.
+- The same user can run `tt instructions edit` and customize collaboration
+  behavior in `$EDITOR`.
+- A package update never overwrites the user's instruction file.
+- An agent runs one command after join (`tt instructions show --json`) and
+  receives effective instruction text + source paths.
+- If instruction loading fails, the bundled `SKILL.md` still gives enough
+  guidance to coordinate safely (agents will lack phase vocabulary but
+  coordination/safety remains intact).
+- No new protocol state, no role enforcement, and no auto-routing are added.
+
+## Process notes (meta)
+
+This convergence used parallel-drafting one-off. Each harness wrote an
+independent v6 draft without reading the other's first. Both landed near
+the same shape but differed on three points (file structure, load
+mechanism, materialization). Reading both drafts side by side made the
+real trade-offs visible quickly; concessions went both ways within one
+round.
+
+The pre-debate draft files were deleted after convergence per Wojtek. The
+parallel-drafting workflow is captured above as an *optional* operator-
+driven pattern, not a shipped default — to avoid imposing file structure
+on workspaces by default.

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.