talking-stick 0.1.4 → 0.3.0

package/README.md

@@ -1,8 +1,8 @@
 # Talking Stick
 
-An MCP coordination server that lets multiple AI coding agents share a single workspace without stepping on each other. One agent holds the stick at a time; handoffs carry structured context so the next agent doesn't have to re-derive it.
+A CLI coordination tool that lets multiple AI coding agents share a single workspace without stepping on each other. One agent holds the stick at a time; handoffs carry structured context so the next agent doesn't have to re-derive it.
 
-**Version:** 0.1.2. Multi-process-safe (SQLite WAL), liveness-aware, no daemon. Supports Claude Code, Codex CLI, Gemini CLI, and OpenCode out of the box.
+**Version:** 0.3.0. Multi-process-safe (SQLite WAL), liveness-aware, no daemon. Supports Claude Code, Codex CLI, Gemini CLI, and OpenCode out of the box. Two agents in the same room can also chat out-of-band — without passing the stick — via `tt msg send/recv`.
 
 ## Quickstart
 
@@ -14,13 +14,13 @@ Three steps, then you're coordinating two agents in the same repo.
 npm i -g talking-stick
 ```
 
-### 2. Register the MCP server and skill in every harness
+### 2. Install the skill in every harness
 
 ```bash
 tt install --all
 ```
 
-Restart any harness that was already running so it loads the new MCP server. The `talking_stick` tools and skill now appear in every workspace.
+Restart any harness that was already running so it loads the updated skill. The skill teaches agents to coordinate by running `tt` CLI commands from the workspace.
 
 ### 3. Try it: two agents, one repo
 
@@ -46,7 +46,7 @@ That's the whole workflow. They negotiate turns automatically, hand off structur
 
 | Method | Command | Notes |
 |---|---|---|
-| **From npm** | `npm i -g talking-stick` | Published as `0.1.2`. Requires Node ≥ 22. |
+| **From npm** | `npm i -g talking-stick` | Published as `0.3.0`. Requires Node ≥ 22. |
 | **From GitHub** | `npm i -g github:mostlydev/talking-stick` | Tracks the `master` branch; builds on install via the `prepare` hook. |
 | **From source** | `git clone … && npm install && npm link` | For contributors. |
 
@@ -76,7 +76,7 @@ Uses the right npm/pnpm/yarn by default:
 tt self-update
 ```
 
-Skills are symlinked automatically, so they don't need an update.
+`tt self-update` also removes stale Talking Stick MCP registrations left by older installs. The first normal `tt` invocation after a package-version change runs the same cleanup if the package manager skipped lifecycle scripts.
 
 ### Remove
 
@@ -86,29 +86,26 @@ tt uninstall --all
 
 ## What it gives your agent
 
-Once installed, each agent harness sees these tools:
+Once installed, each agent harness has a skill that tells it to coordinate through the `tt` CLI:
 
 ```
-list_rooms         — which rooms exist under a path
-join_path          — join the room for this workspace
-leave_room         — explicitly leave a room; deletes it when no active members remain
-wait_for_turn      — block until the stick is available, with takeover signals
-heartbeat          — prove liveness while holding the stick
-release_stick      — normal handoff to the next fair waiter, with structured Handoff
-pass_stick         — explicit handoff to a named agent
-takeover_stick     — deliberate claim when the prior holder is gone/stuck
-get_room_state     — authoritative state projection
-get_room_events    — audit log of turn transitions
-add_note           — leave an async observation for the current owner
-list_notes         — read notes left for the room
+tt list            — which rooms exist under a path
+tt join            — join the room for this workspace
+tt leave           — explicitly leave a room; deletes it when no active members remain
+tt wait            — block until the stick is available, with takeover signals
+tt release         — normal handoff to the next fair waiter, with structured Handoff
+tt assign          — explicit handoff to a named agent
+tt take            — deliberate claim when the prior holder is gone/stuck
+tt kick            — evict an idle member whose process is gone
+tt state           — authoritative state projection
+tt events          — audit log and long-poll stream of turn transitions/messages
+tt notes add/list  — durable async observations for the room
+tt msg send/recv   — out-of-band chat into the room event log
 ```
 
 A workspace maps to a room — usually the `git` root or nearest project marker — so two agents `cd`'d anywhere under the same repo join the same room automatically.
 
-The skill complements the MCP tools:
-
-- MCP gives the harness the coordination surface
-- the global skill tells the model when to join, wait, heartbeat, take over, and hand off
+The global skill tells the model when to join, wait, verify its guardian, take over, leave notes, send messages, and hand off.
 
 ## Non-owner notes
 
@@ -118,26 +115,37 @@ While you wait your turn you may still need to flag something to the current own
 - `list_notes` returns notes for the room; readers can paginate with `after_note_id` and opt into resolved entries with `include_resolved`.
 - Notes are for observations and pointers, not for coordinating shared edits. Shared workspace changes still require holding the stick.
 
-## How installation works per harness
+## Out-of-band messaging
 
-`tt install` installs both pieces a harness needs: the MCP server registration and the bundled `talking-stick` skill.
+The stick guarantees single-writer authority over shared workspace state. It is **not** a chat protocol. When two agents need to talk — design questions, "are you about to break X?", live coordination — use messages instead of churning the stick.
 
-For MCP registration, it prefers each harness's own `mcp add` subcommand when available (so the server ends up in the right user-global config with the right schema), and falls back to direct JSON editing when it isn't.
+```bash
+tt msg send <recipient|room> "<body>" [--interrupt] [--stdin]
+tt msg recv [--wait|--follow] [--from agent] [--after N] [--target self|any|agent]
+tt events --wait|--follow [--event TYPE[,TYPE]] [--target self|any|agent]
+```
 
-| Harness       | Scope        | Under the hood                                                              |
-|---------------|--------------|-----------------------------------------------------------------------------|
-| claude-code   | user         | `claude mcp add -s user talking-stick -- tt mcp`                            |
-| codex         | user         | `codex mcp add talking-stick -- tt mcp`                                     |
-| gemini        | user         | `gemini mcp add -s user -t stdio talking-stick tt mcp`                      |
-| opencode      | user         | Merge `mcp.talking-stick` into `$XDG_CONFIG_HOME/opencode/opencode.json`    |
+- `<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; receivers decide whether to act on it now.
+- `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.
+- `tt events --wait` and `tt events --follow` default to `--target self`; pass `--target any` only for audit/debug views.
+- `wait_for_events` is observer-safe: it never mutates room state, so non-holders can use it freely without disturbing turn-fairness bookkeeping.
+- Event receive does not grant the stick. Agents must still use `tt wait` for ownership and verify the returned guardian before editing shared files.
 
-All four install into **user-global scope**, not project-local. A coordination server is only useful if every workspace your agent enters can see the same rooms — project-scoped MCP would defeat the point.
+**When to message vs note vs handoff.**
 
-If you'd rather apply setup by hand, run `tt install --print <harness>` to see the exact MCP and skill actions, then apply them yourself.
+- **Message** — conversational, ephemeral, between live processes. Six round-trips of "what about line 84?" cost about as much as one structured handoff and zero stick churn.
+- **Note** (`tt notes add`) — durable, resolvable artifacts. Leave a note when the next holder should consider something at handoff, or when the observation should outlive the conversation.
+- **Handoff** (`release_stick` / `pass_stick`) — transfer of work. Messages do not replace handoffs; they live alongside them.
 
-## Skill paths per harness
+**`to_agent_id` is routing, not ACL.** Any room member can read any message via `get_room_events` or `tt events --follow --target any`. Messages are not private. They also do not grant the stick — a non-holder paging the holder gets attention, not write authority.
 
-Talking Stick also ships with a portable `talking-stick` skill:
+For harnesses that only notice completed subprocesses, run `tt events --wait --after <cursor> --json` as a wake process alongside the normal `tt wait --json` loop. A message, pass, release, or assignment event should make the agent read/reply/retry `tt wait`; it is not permission to mutate the workspace.
+
+## How installation works per harness
+
+`tt install` installs or refreshes the bundled `talking-stick` skill. It does not add MCP servers. During install, uninstall, package update, and first run after an installed package version changes, `tt` removes stale MCP registrations written by older Talking Stick releases.
 
 - Claude Code: copied or linked into `~/.claude/skills/talking-stick`
 - Codex: copied or linked into `~/.codex/skills/talking-stick`
@@ -146,6 +154,8 @@ Talking Stick also ships with a portable `talking-stick` skill:
 
 By default, `tt install` links the bundled skill into each harness so local updates are picked up immediately. Pass `--copy` if you want a standalone snapshot instead.
 
+Stale MCP cleanup is strict for OpenCode JSON entries: it removes only the canonical `mcp.talking-stick` value with `["tt", "mcp"]` and leaves hand-edited entries alone. Claude Code, Codex, and Gemini cleanup uses their own `mcp remove` commands when the old server name exists. Every cleanup run appends JSONL audit entries to `${TALKING_STICK_DATA_DIR}/update-migrations.log`.
+
 Human CLI invocations also perform a silent best-effort sync for already-installed file-based skills in Claude Code, Codex, and OpenCode. If the installed skill is a copy, it is refreshed from the bundled skill; if it is a stale symlink, it is relinked. Missing harness config directories and missing skill installs are skipped. Gemini skills are managed by Gemini's own registry, so use `tt install gemini` after updating when needed.
 
 ## Human CLI
@@ -157,10 +167,12 @@ tt whoami [--explain]                                      # show the resolved C
 tt list [path]                                            # list rooms
 tt join [path] [--force-new]                              # join the room for path
 tt leave [path]                                           # leave the room for path
-tt wait [path] [--timeout 30s]                            # block until your turn
+tt wait [path] [--timeout 110s]                           # block until your turn
 tt try [path]                                             # non-blocking claim attempt
 tt state [path]                                           # full room state
-tt events [path] [--after N] [--limit N]                  # room event log
+tt events [path] [--after N] [--limit N] [--wait|--follow] [--event TYPE[,TYPE]] [--target self|any|agent]  # room event log; --wait/--follow long-polls
+tt msg send <recipient|room> <body...> [--interrupt] [--stdin] [--path DIR]  # send an OOB message
+tt msg recv [--wait|--follow] [--from agent] [--after N] [--target self|any|agent] [--path DIR]  # receive OOB messages
 tt release [path] --status TEXT --next-action TEXT        # normal handoff
 tt pass [path] --status TEXT --next-action TEXT           # pass/end your turn
 tt assign <target|next> [path] --status TEXT --next-action TEXT  # explicit handoff
@@ -168,13 +180,14 @@ tt take [path] [--reason TEXT]                            # human-friendly take/
 tt takeover [path] [--reason TEXT]                        # alias for take
 tt notes add <body> [--turn N] [--path DIR] [--stdin]     # leave an async note
 tt notes list [--all] [--after ID] [--limit N] [--path DIR] # read notes
-tt mcp                                                    # run the MCP stdio server
-tt install <harness...> | --all [--print] [--copy] [--link]  # install MCP server and skill
-tt uninstall <harness...> | --all [--print]               # remove MCP server and skill
+tt install <harness...> | --all [--print] [--copy] [--link]  # install skill and clean stale MCP entries
+tt uninstall <harness...> | --all [--print]               # remove skill and stale MCP entries
 tt self-update [--print] [--manager npm|pnpm|yarn|bun]    # update to the latest published tt
 ```
 
-`tt self-update` detects how `tt` was installed (npm / pnpm / yarn / bun, including npm-via-Homebrew/mise/asdf/nvm) and runs the right global-update command. Pass `--print` to see the inferred command without running it; pass `--manager` to override detection. Running `tt self-update` from a development checkout (where `tt` resolves outside `node_modules/talking-stick`) refuses and tells you to `git pull && npm install && npm run build` instead.
+`[path]` defaults to the current working directory. Omit it for normal in-repo coordination; pass it only when you intentionally want a different or nested room.
+
+`tt self-update` detects how `tt` was installed (npm / pnpm / yarn / bun, including npm-via-Homebrew/mise/asdf/nvm), runs the right global-update command, then removes stale MCP registrations from older Talking Stick installs. Pass `--print` to see the inferred command without running it; pass `--manager` to override detection. Running `tt self-update` from a development checkout (where `tt` resolves outside `node_modules/talking-stick`) refuses and tells you to `git pull && npm install && npm run build` instead.
 
 Human CLI commands use a stable identity like `human:<username>`. When `tt wait`, `tt take`, or `tt takeover` wins the turn, a small background guardian keeps the lease alive on your behalf until you release, pass, or assign it. Human CLI `take` intentionally works without a required reason so an operator can step into a stuck room quickly; harness-aware CLI takeovers still require `--reason` unless the command includes `--operator-requested`.
 
@@ -202,7 +215,7 @@ Use `tt whoami --explain` to see which identity path the CLI chose.
 - **Fencing tokens.** `lease_id` + `turn_id` make stale writes impossible — an agent who lost their turn cannot commit anything under the room's name.
 - **Liveness-aware recovery.** Dead or crashed holders are detected with OS-level process checks; claim-timeout takeover skips the prior owner when another active member is waiting.
 - **Multi-process safe.** Shared SQLite with WAL mode, `BEGIN IMMEDIATE` writes, 250 ms polling for `wait_for_turn`. No daemon required.
-- **Per-call identity derivation.** MCP callers don't supply `agent_id`; the adapter derives identity from the spawning harness process. Human CLI callers get a stable `human:<username>` identity.
+- **Per-call identity derivation.** Harness-launched CLI calls derive identity from harness environment or ancestry. Human CLI callers get a stable `human:<username>` identity.
 
 ## Storage
 

package/dist/cli/event-stream.js

@@ -0,0 +1,124 @@
+import { ProtocolError } from "../errors.js";
+import { getStringOption, parseOptionalInteger, parseWaitTimeout } from "./parser.js";
+import { shouldUseJson } from "./output.js";
+export async function runEventStream(runtime, parsed, identity, roomId, options) {
+    const follow = parsed.options.has("follow");
+    const wait = parsed.options.has("wait");
+    if (follow && wait) {
+        throw new Error("Pass only one of --wait or --follow.");
+    }
+    const tailMode = follow || wait || options.force_tail_cursor;
+    const explicitAfter = parseOptionalInteger(parsed, "after");
+    const afterEventSeq = explicitAfter ??
+        (tailMode ? runtime.commands.getLatestEventSeq({ room_id: roomId }) : 0);
+    const targetAgentId = resolveTargetFilter(runtime, identity, roomId, getStringOption(parsed, "target") ?? options.default_target);
+    const fromAgentId = resolveOptionalAgentSelector(runtime, identity, roomId, getStringOption(parsed, "from"));
+    const waitInput = {
+        agent_id: identity.agent_id,
+        room_id: roomId,
+        after_event_seq: afterEventSeq,
+        event_type: options.event_type,
+        target_agent_id: targetAgentId,
+        from_agent_id: fromAgentId,
+        max_wait_ms: follow || wait ? parseWaitTimeout(parsed) : 0
+    };
+    if (!follow) {
+        const result = await runtime.commands.waitForEvents(waitInput);
+        writeEventLines(parsed, result.events);
+        return;
+    }
+    await followEvents(runtime, parsed, waitInput);
+}
+export function resolveOptionalAgentSelector(runtime, identity, roomId, raw) {
+    if (!raw) {
+        return undefined;
+    }
+    return resolveAgentSelector(runtime, identity, roomId, raw);
+}
+export function resolveAgentSelector(runtime, identity, roomId, raw) {
+    const members = runtime.commands.getRoomState({
+        room_id: roomId,
+        agent_id: identity.agent_id
+    }).members;
+    const exact = members.find((member) => member.agent_id === raw);
+    if (exact) {
+        return exact.agent_id;
+    }
+    const candidates = members.filter((member) => member.status === "active" && member.display_name === raw);
+    if (candidates.length === 1) {
+        return candidates[0].agent_id;
+    }
+    if (candidates.length > 1) {
+        throw new ProtocolError("ambiguous_recipient", `Multiple active room members match '${raw}'.`, { candidates: candidates.map((member) => member.agent_id) });
+    }
+    throw new ProtocolError("unknown_recipient", `No active room member matches '${raw}'.`);
+}
+export function parseEventTypeFilter(value) {
+    if (!value) {
+        return undefined;
+    }
+    const values = value
+        .split(",")
+        .map((item) => item.trim())
+        .filter(Boolean);
+    if (values.length === 0) {
+        return undefined;
+    }
+    return values.length === 1 ? values[0] : values;
+}
+export function writeEventLines(parsed, events) {
+    for (const event of events) {
+        const line = shouldUseJson(parsed)
+            ? JSON.stringify(event)
+            : formatEventLine(event);
+        process.stdout.write(`${line}\n`);
+    }
+}
+export function formatEventLine(event) {
+    if (event.event_type === "message_sent") {
+        const target = event.to_agent_id ?? "room";
+        const hint = event.payload?.delivery_hint === "interrupt" ? " [interrupt]" : "";
+        return `[${event.created_at}] ${event.from_agent_id ?? "-"} -> ${target}${hint}: ${event.payload?.body ?? ""}`;
+    }
+    const reason = event.reason ? ` (${event.reason})` : "";
+    const target = event.from_agent_id && event.to_agent_id
+        ? `${event.from_agent_id} -> ${event.to_agent_id}`
+        : event.to_agent_id
+            ? `-> ${event.to_agent_id}`
+            : event.from_agent_id ?? "-";
+    return `[${event.created_at}] ${event.event_type} ${target}${reason}`;
+}
+async function followEvents(runtime, parsed, input) {
+    let cursor = input.after_event_seq ?? 0;
+    let shouldExit = false;
+    const markExit = () => {
+        shouldExit = true;
+    };
+    process.once("SIGTERM", markExit);
+    process.once("SIGHUP", markExit);
+    process.once("SIGINT", markExit);
+    try {
+        while (!shouldExit) {
+            const result = await runtime.commands.waitForEvents({
+                ...input,
+                after_event_seq: cursor
+            });
+            if (result.events.length > 0) {
+                writeEventLines(parsed, result.events);
+                cursor = result.cursor_event_seq;
+            }
+        }
+    }
+    finally {
+        process.off("SIGTERM", markExit);
+        process.off("SIGHUP", markExit);
+        process.off("SIGINT", markExit);
+        process.stderr.write(`cursor_event_seq=${cursor}\n`);
+    }
+}
+function resolveTargetFilter(runtime, identity, roomId, raw) {
+    if (raw === "self" || raw === "any") {
+        return raw;
+    }
+    return resolveAgentSelector(runtime, identity, roomId, raw);
+}

package/dist/cli/install-commands.js

@@ -1,7 +1,11 @@
 import { spawn } from "node:child_process";
-import { SUPPORTED_HARNESSES, detectHarness, parseHarnessList, planInstall, planUninstall, runAction } from "../install.js";
+import { SUPPORTED_HARNESSES, detectHarness, parseHarnessList, planUninstall, runAction } from "../install.js";
 import { planSkillInstall, planSkillUninstall } from "../skill-install.js";
+import { resolveDataDir } from "../config.js";
+import { FileAuditLog, defaultAuditLogPath } from "../install-audit.js";
+import { removeStaleMcpRegistrations } from "../install-migration.js";
 import { detectInstallSource, isPackageManager, planSelfUpdate, resolveCurrentBinaryPath } from "../self-update.js";
+import { readPackageVersion, runStaleMcpCleanup } from "../update-migration.js";
 import { getStringOption, hasOption, normalizeBooleanFlag } from "./parser.js";
 export async function runInstallCommand(parsed) {
     normalizeBooleanFlag(parsed, "print");
@@ -14,28 +18,33 @@ export async function runInstallCommand(parsed) {
         skipMissing: true
     };
     if (dryRun) {
-        for (const action of planCombinedInstallActions(harnesses, installOptions)) {
+        for (const action of planInstallActions(harnesses, installOptions)) {
+            printActionPlan(action);
+        }
+        for (const action of planCleanupActions(harnesses, installOptions)) {
             printActionPlan(action);
         }
         return;
     }
-    const results = (await Promise.all(harnesses.map((harness) => runCombinedInstall(harness, installOptions)))).flat();
+    const results = (await Promise.all(harnesses.map((harness) => runSkillInstall(harness, installOptions)))).flat();
     reportInstallResults(results, "install");
+    reportCleanupResults(await runCleanup(harnesses, "manual", installOptions), "install");
 }
 export async function runUninstallCommand(parsed) {
     normalizeBooleanFlag(parsed, "print");
     const harnesses = selectHarnesses(parsed);
     const dryRun = hasOption(parsed, "print");
     const installOptions = { skipMissing: true };
-    const actions = planCombinedUninstallActions(harnesses, installOptions);
+    const actions = planUninstallActions(harnesses, installOptions);
     if (dryRun) {
         for (const action of actions) {
             printActionPlan(action);
         }
         return;
     }
-    const results = (await Promise.all(harnesses.map((harness) => runCombinedUninstall(harness, installOptions)))).flat();
+    const results = (await Promise.all(harnesses.map((harness) => runSkillUninstall(harness, installOptions)))).flat();
     reportInstallResults(results, "uninstall");
+    reportCleanupResults(await runCleanup(harnesses, "uninstall", installOptions), "uninstall");
 }
 export async function runInstallSkillCommand(parsed) {
     normalizeBooleanFlag(parsed, "print");
@@ -85,6 +94,7 @@ export async function runSelfUpdateCommand(parsed, cliEntryUrl) {
         const binaryPath = resolveCurrentBinaryPath(cliEntryUrl);
         source = detectInstallSource({ binaryPath });
     }
+    const packageVersionFrom = readPackageVersion(cliEntryUrl);
     const plan = planSelfUpdate(source);
     if (!plan) {
         if (source === "dev") {
@@ -98,7 +108,29 @@ export async function runSelfUpdateCommand(parsed, cliEntryUrl) {
     }
     process.stdout.write(`Updating via: ${plan.description}\n`);
     await runInheritIo(plan.command, plan.args);
-    process.stdout.write("Done. Restart your harness MCP subprocess to pick up the new dist.\n");
+    const packageVersionTo = readPackageVersion(cliEntryUrl);
+    const cleanup = await runStaleMcpCleanup({
+        harnesses: "all",
+        reason: "update",
+        packageVersionFrom,
+        packageVersionTo,
+        installOptions: { skipMissing: true }
+    });
+    reportCleanupResults(cleanup.results, "self-update");
+    process.stdout.write("Done. Restart any long-running harness sessions to pick up the new tt.\n");
+}
+export async function runMcpMigrationCommand(parsed) {
+    normalizeBooleanFlag(parsed, "quiet");
+    const reason = parseAuditReason(getStringOption(parsed, "reason") ?? "manual");
+    const quiet = hasOption(parsed, "quiet");
+    const cleanup = await runStaleMcpCleanup({
+        harnesses: "all",
+        reason,
+        installOptions: { skipMissing: true }
+    });
+    if (!quiet) {
+        reportCleanupResults(cleanup.results, "self-update");
+    }
 }
 function resolveSkillInstallLinkMode(parsed) {
     const wantsCopy = hasOption(parsed, "copy");
@@ -111,48 +143,39 @@ function resolveSkillInstallLinkMode(parsed) {
     }
     return true;
 }
-function planCombinedInstallActions(harnesses, installOptions) {
-    return harnesses.flatMap((harness) => {
-        const mcpAction = planInstall(harness, installOptions);
-        if (mcpAction.kind === "skip") {
-            return [mcpAction];
-        }
-        return [
-            mcpAction,
-            planSkillInstall(harness, {
-                ...installOptions,
-                // In dry-run mode, show the skill action that will follow MCP setup
-                // even when the MCP installer is what creates the harness config root.
-                skipMissing: false
-            })
-        ];
-    });
+function planInstallActions(harnesses, installOptions) {
+    return harnesses.map((harness) => planSkillInstall(harness, installOptions));
 }
-function planCombinedUninstallActions(harnesses, installOptions) {
+function planUninstallActions(harnesses, installOptions) {
     return harnesses.flatMap((harness) => [
-        planUninstall(harness, installOptions),
         planSkillUninstall(harness, {
             ...installOptions,
             skipMissing: false
-        })
+        }),
+        planUninstall(harness, installOptions)
     ]);
 }
-async function runCombinedInstall(harness, installOptions) {
-    const mcpAction = planInstall(harness, installOptions);
-    const mcpResult = await runAction(mcpAction, installOptions);
-    if (!mcpResult.ok || mcpResult.skipped) {
-        return [mcpResult];
-    }
+function planCleanupActions(harnesses, installOptions) {
+    return harnesses.map((harness) => planUninstall(harness, installOptions));
+}
+async function runSkillInstall(harness, installOptions) {
     const skillAction = planSkillInstall(harness, installOptions);
     const skillResult = await runAction(skillAction, installOptions);
-    return [mcpResult, skillResult];
+    return [skillResult];
 }
-async function runCombinedUninstall(harness, installOptions) {
-    const mcpAction = planUninstall(harness, installOptions);
-    const mcpResult = await runAction(mcpAction, installOptions);
+async function runSkillUninstall(harness, installOptions) {
     const skillAction = planSkillUninstall(harness, installOptions);
     const skillResult = await runAction(skillAction, installOptions);
-    return [mcpResult, skillResult];
+    return [skillResult];
+}
+async function runCleanup(harnesses, reason, installOptions) {
+    const dataDir = resolveDataDir();
+    return removeStaleMcpRegistrations({
+        harnesses,
+        reason,
+        audit: new FileAuditLog(defaultAuditLogPath(dataDir)),
+        installOptions
+    });
 }
 function selectHarnesses(parsed) {
     if (hasOption(parsed, "all")) {
@@ -199,6 +222,23 @@ function reportInstallResults(results, mode) {
         throw new Error(`${mode} completed with failures.`);
     }
 }
+function reportCleanupResults(results, mode) {
+    let anyFailed = false;
+    for (const result of results) {
+        process.stdout.write(`[${result.harness}] mcp-cleanup ${result.action}: ${result.message}\n`);
+        if (result.action === "failed")
+            anyFailed = true;
+    }
+    if (anyFailed) {
+        throw new Error(`${mode} completed with MCP cleanup failures.`);
+    }
+}
 function formatInstallStatus(status) {
     return status.replaceAll("_", "-");
 }
+function parseAuditReason(value) {
+    if (value === "update" || value === "first-run" || value === "uninstall" || value === "manual") {
+        return value;
+    }
+    throw new Error(`--reason must be one of update | first-run | uninstall | manual (got ${value}).`);
+}

package/dist/cli/msg-commands.js

@@ -0,0 +1,81 @@
+import { deriveCliIdentity } from "./identity.js";
+import { readAllStdin } from "./handoff.js";
+import { hasOption } from "./parser.js";
+import { printResult } from "./output.js";
+import { resolveAgentSelector, runEventStream } from "./event-stream.js";
+import { resolveSessionForNotes } from "./session.js";
+export async function handleMsgCommand(runtime, parsed) {
+    const [subcommand, ...rest] = parsed.positionals;
+    if (!subcommand) {
+        throw new Error("Usage: tt msg <send|recv> [...]. See `tt --help` for details.");
+    }
+    const subParsed = {
+        name: `msg ${subcommand}`,
+        positionals: rest,
+        options: parsed.options
+    };
+    switch (subcommand) {
+        case "send":
+            await handleMsgSendCommand(runtime, subParsed);
+            return;
+        case "recv":
+            await handleMsgRecvCommand(runtime, subParsed);
+            return;
+        default:
+            throw new Error(`Unknown msg subcommand: ${subcommand}`);
+    }
+}
+async function handleMsgSendCommand(runtime, parsed) {
+    const identity = deriveCliIdentity(parsed);
+    const session = resolveSessionForNotes(runtime, parsed, identity);
+    const usesRoomFlag = hasOption(parsed, "room");
+    repairBooleanFlag(parsed, "room", 0);
+    repairBooleanFlag(parsed, "interrupt", usesRoomFlag ? 0 : 1);
+    const recipientSelector = usesRoomFlag ? "room" : parsed.positionals[0];
+    if (!recipientSelector) {
+        throw new Error("Usage: tt msg send <recipient|room> <body...> [--interrupt] [--stdin].");
+    }
+    const bodyStart = usesRoomFlag ? 0 : 1;
+    const positionalBody = parsed.positionals.slice(bodyStart).join(" ");
+    const body = positionalBody.length > 0
+        ? positionalBody
+        : hasOption(parsed, "stdin")
+            ? await readAllStdin()
+            : "";
+    if (body.length === 0) {
+        throw new Error("Message body is required (pass as a positional or use --stdin to read from stdin).");
+    }
+    const toAgentId = recipientSelector === "room"
+        ? null
+        : resolveAgentSelector(runtime, identity, session.room_id, recipientSelector);
+    const result = runtime.commands.sendMessage(identity, {
+        room_id: session.room_id,
+        body,
+        to_agent_id: toAgentId,
+        delivery_hint: hasOption(parsed, "interrupt") ? "interrupt" : "normal"
+    });
+    printResult(parsed, result, () => {
+        const target = toAgentId ?? "room";
+        const hint = hasOption(parsed, "interrupt") ? " interrupt" : "";
+        return `Sent${hint} message ${shortEventId(result.event_id)} to ${target}.`;
+    });
+}
+async function handleMsgRecvCommand(runtime, parsed) {
+    const identity = deriveCliIdentity(parsed);
+    const session = resolveSessionForNotes(runtime, parsed, identity);
+    await runEventStream(runtime, parsed, identity, session.room_id, {
+        event_type: "message_sent",
+        default_target: "self",
+        force_tail_cursor: false
+    });
+}
+function repairBooleanFlag(parsed, key, insertAt) {
+    const value = parsed.options.get(key);
+    if (typeof value === "string") {
+        parsed.positionals.splice(insertAt, 0, value);
+        parsed.options.set(key, true);
+    }
+}
+function shortEventId(eventId) {
+    return eventId.slice(0, 8);
+}

package/dist/cli/output.js

@@ -123,10 +123,12 @@ Commands:
   tt join [path] [--force-new]
   tt leave [path]
   tt kick <agent_id> [path] [--reason TEXT] [--force]
-  tt wait [path] [--timeout 30s]
+  tt wait [path] [--timeout 110s]
   tt try [path]
   tt state [path]
-  tt events [path] [--after N] [--limit N]
+  tt events [path] [--after N] [--limit N] [--wait|--follow] [--event TYPE[,TYPE]] [--target self|any|agent]
+  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 release [path] (--status TEXT --next-action TEXT | --stdin)
   tt pass [path] (--status TEXT --next-action TEXT | --stdin)
   tt assign <target|next> [path] (--status TEXT --next-action TEXT | --stdin)
@@ -134,7 +136,6 @@ Commands:
   tt takeover [path] [--reason TEXT] [--operator-requested]
   tt notes add <body> [--turn N] [--path DIR] [--stdin]
   tt notes list [--all] [--after NOTE_ID] [--limit N] [--path DIR]
-  tt mcp
   tt install <harness...> | --all [--print] [--copy] [--link]
   tt uninstall <harness...> | --all [--print]
   tt self-update [--print] [--manager npm|pnpm|yarn|bun]
@@ -142,6 +143,7 @@ Commands:
 Harnesses: ${SUPPORTED_HARNESSES.join(", ")}
 
 Common options:
+  [path]     Defaults to the current working directory when omitted
   --agent ID   Override the default human identity
   --json       Force JSON output (also default when invoked from a harness)
   --text       Force human-readable text even when invoked from a harness