talking-stick 0.2.0 → 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.2.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` and the matching MCP tools.
+**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.2.0`. 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,32 +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
-kick_member        — evict an idle member whose process is gone
-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
-send_message       — out-of-band chat into the room event log (direct or broadcast)
-wait_for_events    — observer-safe long-poll over the event log with type/target/sender filters
+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
 
@@ -135,7 +129,9 @@ tt events --wait|--follow [--event TYPE[,TYPE]] [--target self|any|agent]
 - `--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.
 
 **When to message vs note vs handoff.**
 
@@ -145,26 +141,11 @@ tt events --wait|--follow [--event TYPE[,TYPE]] [--target self|any|agent]
 
 **`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.
 
-## How installation works per harness
-
-`tt install` installs both pieces a harness needs: the MCP server registration and the bundled `talking-stick` skill.
-
-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.
-
-| 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`    |
+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.
 
-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.
-
-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.
-
-## Skill paths per harness
+## How installation works per harness
 
-Talking Stick also ships with a portable `talking-stick` skill:
+`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`
@@ -173,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
@@ -184,7 +167,7 @@ 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] [--wait|--follow] [--event TYPE[,TYPE]] [--target self|any|agent]  # room event log; --wait/--follow long-polls
@@ -197,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`.
 
@@ -231,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/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/output.js

@@ -123,7 +123,7 @@ 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] [--wait|--follow] [--event TYPE[,TYPE]] [--target self|any|agent]
@@ -136,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]
@@ -144,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

package/dist/cli/registry.js

@@ -1,20 +1,10 @@
-import { runStdioServer } from "../index.js";
 import { runGuardCommand } from "./guardian.js";
-import { runInstallCommand, runInstallSkillCommand, runSelfUpdateCommand, runUninstallCommand, runUninstallSkillCommand } from "./install-commands.js";
+import { runInstallCommand, runMcpMigrationCommand, runSelfUpdateCommand, runUninstallCommand } from "./install-commands.js";
 import { handleMsgCommand } from "./msg-commands.js";
 import { handleNotesCommand } from "./notes-commands.js";
 import { handleEventsCommand, handleJoinCommand, handleKickCommand, handleLeaveCommand, handleListCommand, handleStateCommand, handleWhoAmICommand } from "./room-commands.js";
 import { handleAssignCommand, handlePassCommand, handleReleaseCommand, handleTakeCommand, handleWaitCommand } from "./turn-commands.js";
 export const COMMAND_REGISTRY = [
-    {
-        name: "mcp",
-        needsRuntime: false,
-        startupMaintenance: false,
-        internal: true,
-        usage: "tt mcp",
-        description: "Run the MCP server over stdio.",
-        handler: () => runStdioServer()
-    },
     {
         name: "guard",
         needsRuntime: false,
@@ -30,7 +20,7 @@ export const COMMAND_REGISTRY = [
         startupMaintenance: false,
         internal: false,
         usage: "tt install <harness...> | --all [--print] [--copy] [--link]",
-        description: "Install Talking Stick into harness MCP configs and skills.",
+        description: "Install the Talking Stick skill and remove stale MCP registrations.",
         handler: ({ parsed }) => runInstallCommand(parsed)
     },
     {
@@ -39,35 +29,26 @@ export const COMMAND_REGISTRY = [
         startupMaintenance: false,
         internal: false,
         usage: "tt uninstall <harness...> | --all [--print]",
-        description: "Remove Talking Stick from harness MCP configs and skills.",
+        description: "Remove the Talking Stick skill and stale MCP registrations.",
         handler: ({ parsed }) => runUninstallCommand(parsed)
     },
     {
-        name: "install-skill",
+        name: "self-update",
         needsRuntime: false,
         startupMaintenance: false,
         internal: false,
-        usage: "tt install-skill <harness...> | --all [--print] [--copy] [--link]",
-        description: "Install the bundled Talking Stick skill.",
-        handler: ({ parsed }) => runInstallSkillCommand(parsed)
+        usage: "tt self-update [--print] [--manager npm|pnpm|yarn|bun]",
+        description: "Update the globally installed tt package.",
+        handler: ({ parsed, cliEntryUrl }) => runSelfUpdateCommand(parsed, cliEntryUrl)
     },
     {
-        name: "uninstall-skill",
+        name: "migrate-mcp",
         needsRuntime: false,
         startupMaintenance: false,
-        internal: false,
-        usage: "tt uninstall-skill <harness...> | --all [--print]",
-        description: "Remove the bundled Talking Stick skill.",
-        handler: ({ parsed }) => runUninstallSkillCommand(parsed)
-    },
-    {
-        name: "self-update",
-        needsRuntime: false,
-        startupMaintenance: true,
-        internal: false,
-        usage: "tt self-update [--print] [--manager npm|pnpm|yarn|bun]",
-        description: "Update the globally installed tt package.",
-        handler: ({ parsed, cliEntryUrl }) => runSelfUpdateCommand(parsed, cliEntryUrl)
+        internal: true,
+        usage: "tt migrate-mcp [--reason update|first-run|uninstall|manual] [--quiet]",
+        description: "Remove stale Talking Stick MCP registrations.",
+        handler: ({ parsed }) => runMcpMigrationCommand(parsed)
     },
     {
         name: "whoami",
@@ -146,7 +127,7 @@ export const COMMAND_REGISTRY = [
         needsRuntime: true,
         startupMaintenance: true,
         internal: false,
-        usage: "tt wait [path] [--timeout 30s]",
+        usage: "tt wait [path] [--timeout 110s]",
         description: "Wait until this agent can claim the stick.",
         handler: ({ runtime, parsed, cliEntryUrl }) => handleWaitCommand(requireRuntime(runtime), parsed, false, cliEntryUrl)
     },

package/dist/cli/room-commands.js

@@ -135,7 +135,7 @@ export async function handleEventsCommand(runtime, parsed) {
     if (hasOption(parsed, "wait") || hasOption(parsed, "follow")) {
         await runEventStream(runtime, parsed, identity, session.room_id, {
             event_type: parseEventTypeFilter(getStringOption(parsed, "event")),
-            default_target: "any",
+            default_target: "self",
             force_tail_cursor: false
         });
         return;

package/dist/cli/startup-maintenance.js

@@ -1,7 +1,20 @@
 import { syncInstalledSkills } from "../skill-install.js";
+import { runFirstRunMcpMigration } from "../update-migration.js";
+import { detectInstallSource, resolveCurrentBinaryPath } from "../self-update.js";
 import { isKnownHarnessCliEnv } from "./identity.js";
 import { getCommand } from "./registry.js";
-export function runStartupMaintenance(parsed, env = process.env) {
+export async function runStartupMaintenance(parsed, cliEntryUrl, env = process.env) {
+    if (shouldRunFirstRunMcpMigration(parsed, cliEntryUrl, env)) {
+        try {
+            await runFirstRunMcpMigration({
+                installOptions: { env }
+            });
+        }
+        catch {
+            // Startup cleanup is best-effort. Explicit install, uninstall, and
+            // self-update paths surface cleanup failures directly.
+        }
+    }
     if (!shouldAutoSyncInstalledSkills(parsed, env)) {
         return;
     }
@@ -13,6 +26,19 @@ export function runStartupMaintenance(parsed, env = process.env) {
         // unrelated tt command fail.
     }
 }
+export function shouldRunFirstRunMcpMigration(parsed, cliEntryUrl, env = process.env) {
+    if (env.TALKING_STICK_DISABLE_MCP_MIGRATION?.trim()) {
+        return false;
+    }
+    const command = getCommand(parsed.name);
+    if (!command?.startupMaintenance) {
+        return false;
+    }
+    const source = detectInstallSource({
+        binaryPath: resolveCurrentBinaryPath(cliEntryUrl)
+    });
+    return source !== "dev" && source !== "unknown";
+}
 export function shouldAutoSyncInstalledSkills(parsed, env = process.env) {
     if (env.TALKING_STICK_DISABLE_SKILL_SYNC?.trim()) {
         return false;

package/dist/cli.js

@@ -11,10 +11,10 @@ import { runStartupMaintenance } from "./cli/startup-maintenance.js";
 export { checkGuardianLiveness } from "./cli/guardian.js";
 export { parseHandoffJson } from "./cli/handoff.js";
 export { formatRelativeTime, shouldUseJson } from "./cli/output.js";
-export { shouldAutoSyncInstalledSkills } from "./cli/startup-maintenance.js";
+export { shouldAutoSyncInstalledSkills, shouldRunFirstRunMcpMigration } from "./cli/startup-maintenance.js";
 export async function runCli(argv = process.argv.slice(2)) {
     const parsed = parseCommand(argv);
-    runStartupMaintenance(parsed);
+    await runStartupMaintenance(parsed, import.meta.url);
     if (!parsed.name || parsed.name === "help" || parsed.name === "--help") {
         printHelp();
         return;

package/dist/config.js

@@ -4,9 +4,9 @@ export const defaultPolicy = {
     ownerLeaseTtlMs: 45 * 60 * 1000,
     heartbeatIntervalMs: 5 * 60 * 1000,
     claimTtlMs: 20 * 60 * 1000,
-    waitForTurnMaxWaitMs: 30 * 1000,
+    waitForTurnMaxWaitMs: 110 * 1000,
     waitForTurnPollMs: 250,
-    waitForEventsMaxWaitMs: 30 * 1000,
+    waitForEventsMaxWaitMs: 110 * 1000,
     waitForEventsPollMs: 250,
     waitForEventsBatchLimit: 100,
     presenceTtlMs: 4 * 60 * 60 * 1000,

package/dist/identity.js

@@ -127,13 +127,13 @@ function harnessAgentId(harness, sessionId, hostId, username) {
 function resolveHarnessSessionId(signal, env, parentPid, parentInspection, username, hostId, inspector) {
     if (signal.sessionId)
         return `harness:${signal.sessionId}`;
-    const terminalId = resolveTerminalSessionId(env);
-    if (terminalId)
-        return terminalId;
     const harnessRoot = findHarnessRootInAncestry(signal.harness, parentPid, parentInspection, inspector);
     if (harnessRoot) {
         return `pid:${harnessRoot.pid}@${harnessRoot.startTime}`;
     }
+    const terminalId = resolveTerminalSessionId(env);
+    if (terminalId)
+        return terminalId;
     if (parentInspection?.startTime) {
         return `pid:${parentPid}@${parentInspection.startTime}`;
     }
@@ -224,7 +224,7 @@ function detectHarnessSignal(env) {
     if (env.CLAUDECODE === "1") {
         return {
             harness: "claude",
-            sessionId: null,
+            sessionId: nonEmpty(env.CLAUDE_CODE_SESSION_ID),
             pidHint: parsePositiveInteger(env.CMUX_CLAUDE_PID)
         };
     }

package/dist/index.js

@@ -4,9 +4,9 @@ export { applyPragmas, assertLocalFilesystem, detectFilesystemType, migrate, ope
 export { ProtocolError, isProtocolError } from "./errors.js";
 export { deriveHarnessCliIdentity, deriveHumanCliIdentity, deriveMcpHarnessIdentity } from "./identity.js";
 export { ancestorPaths, canonicalizeContextPath, resolveContextPath, resolveWorkspaceRoot } from "./path-resolution.js";
-export { createMcpServer, runStdioServer } from "./mcp-server.js";
-export { SUPPORTED_HARNESSES, MissingHarnessError, detectHarness, parseHarnessList, planInstall, planUninstall, resolveHarnessConfigDir, resolveOpencodeConfigDir, resolveOpencodeConfigPath, runAction, skipAction } from "./install.js";
+export { SUPPORTED_HARNESSES, MissingHarnessError, detectHarness, parseHarnessList, planUninstall, resolveHarnessConfigDir, resolveOpencodeConfigDir, resolveOpencodeConfigPath, runAction, skipAction } from "./install.js";
 export { DEFAULT_SKILL_NAME, planSkillInstall, planSkillUninstall, resolveBundledSkillPath, resolveSkillTargetPath, syncInstalledSkills } from "./skill-install.js";
+export { readPackageVersion, readUpdateMigrationState, resolveUpdateMigrationStatePath, runFirstRunMcpMigration, runStaleMcpCleanup, writeUpdateMigrationState } from "./update-migration.js";
 export { createSystemProcessInspector, terminateKnownProcess } from "./process-utils.js";
 export { clearCliSessionLease, findCliSessionByRoom, findCliSessionForContextPath, readCliSessions, removeCliSession, removeCliSessionsForRoom, resolveCliSessionPath, upsertCliSession, upsertJoinedCliSession, writeCliSessions } from "./session-store.js";
 export { TalkingStickService, createDefaultProcessLivenessChecker } from "./service.js";

package/dist/install-audit.js

@@ -0,0 +1,21 @@
+import fs from "node:fs";
+import path from "node:path";
+export class FileAuditLog {
+    filePath;
+    constructor(filePath) {
+        this.filePath = filePath;
+    }
+    append(entry) {
+        const fullEntry = { ts: entry.ts ?? new Date().toISOString(), ...entry };
+        fs.mkdirSync(path.dirname(this.filePath), { recursive: true });
+        fs.appendFileSync(this.filePath, `${JSON.stringify(fullEntry)}\n`, "utf8");
+    }
+}
+export class NoopAuditLog {
+    append() {
+        // intentionally blank
+    }
+}
+export function defaultAuditLogPath(dataDir) {
+    return path.join(dataDir, "update-migrations.log");
+}