talking-stick 0.1.1 → 0.1.3

package/README.md

@@ -2,7 +2,7 @@
 
 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.
 
-**Version:** 0.1.1. Multi-process-safe (SQLite WAL), liveness-aware, no daemon. Supports Claude Code, Codex CLI, Gemini CLI, and OpenCode out of the box.
+**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.
 
 ## Quickstart
 
@@ -18,7 +18,6 @@ npm i -g talking-stick
 
 ```bash
 tt install --all
-tt install-skill --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.
@@ -47,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.1`. Requires Node ≥ 22. |
+| **From npm** | `npm i -g talking-stick` | Published as `0.1.2`. 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. |
 
@@ -55,21 +54,19 @@ All three produce a `tt` binary on your `PATH`. Everything else below works iden
 
 ### Verify without installing
 
-Want to see exactly what `tt install`/`tt install-skill` would change before touching anything?
+Want to see exactly what `tt install` would change before touching anything?
 
 ```bash
 tt install --all --print
-tt install-skill --all --print
 ```
 
 ### Install into a subset
 
 ```bash
 tt install claude-code codex
-tt install-skill gemini
 ```
 
-During normal execution, install commands skip harnesses that are not present instead of failing or creating new harness config roots. For example, `tt install-skill codex` only creates `~/.codex/skills/` if `~/.codex/` already exists.
+During normal execution, install commands skip harnesses that are not present instead of failing or creating new harness config roots.
 
 ### Update
 
@@ -85,7 +82,6 @@ Skills are symlinked automatically, so they don't need an update.
 
 ```bash
 tt uninstall --all
-tt uninstall-skill --all
 ```
 
 ## What it gives your agent
@@ -124,7 +120,9 @@ While you wait your turn you may still need to flag something to the current own
 
 ## How installation works per harness
 
-`tt install` 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.
+`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                                                              |
 |---------------|--------------|-----------------------------------------------------------------------------|
@@ -135,9 +133,9 @@ While you wait your turn you may still need to flag something to the current own
 
 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 register it by hand, run `tt install --print <harness>` to see the exact command or JSON edit, then apply it yourself.
+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.
 
-## How skill installation works per harness
+## Skill paths per harness
 
 Talking Stick also ships with a portable `talking-stick` skill:
 
@@ -146,9 +144,9 @@ Talking Stick also ships with a portable `talking-stick` skill:
 - Gemini: installed with `gemini skills install ... --scope user` or linked with `gemini skills link ... --scope user`
 - OpenCode: copied or linked into `~/.opencode/skills/talking-stick`
 
-By default, `tt install-skill` links the bundled skill into each harness so local updates are picked up immediately. Pass `--copy` if you want a standalone snapshot instead.
+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.
 
-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-skill gemini` after updating when needed.
+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
 
@@ -171,10 +169,8 @@ 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]                 # register MCP server
-tt uninstall <harness...> | --all [--print]               # remove MCP server
-tt install-skill <harness...> | --all [--print] [--copy] [--link]  # install global talking-stick skill
-tt uninstall-skill <harness...> | --all [--print]         # remove global talking-stick skill
+tt install <harness...> | --all [--print] [--copy] [--link]  # install MCP server and skill
+tt uninstall <harness...> | --all [--print]               # remove MCP server and skill
 tt self-update [--print] [--manager npm|pnpm|yarn|bun]    # update to the latest published tt
 ```
 

package/dist/cli/install-commands.js

@@ -5,17 +5,21 @@ import { detectInstallSource, isPackageManager, planSelfUpdate, resolveCurrentBi
 import { getStringOption, hasOption, normalizeBooleanFlag } from "./parser.js";
 export async function runInstallCommand(parsed) {
     normalizeBooleanFlag(parsed, "print");
+    normalizeBooleanFlag(parsed, "copy");
+    normalizeBooleanFlag(parsed, "link");
     const harnesses = selectHarnesses(parsed);
     const dryRun = hasOption(parsed, "print");
-    const installOptions = { skipMissing: true };
-    const actions = harnesses.map((harness) => planInstall(harness, installOptions));
+    const installOptions = {
+        link: resolveSkillInstallLinkMode(parsed),
+        skipMissing: true
+    };
     if (dryRun) {
-        for (const action of actions) {
+        for (const action of planCombinedInstallActions(harnesses, installOptions)) {
             printActionPlan(action);
         }
         return;
     }
-    const results = await Promise.all(actions.map((action) => runAction(action, installOptions)));
+    const results = (await Promise.all(harnesses.map((harness) => runCombinedInstall(harness, installOptions)))).flat();
     reportInstallResults(results, "install");
 }
 export async function runUninstallCommand(parsed) {
@@ -23,14 +27,14 @@ export async function runUninstallCommand(parsed) {
     const harnesses = selectHarnesses(parsed);
     const dryRun = hasOption(parsed, "print");
     const installOptions = { skipMissing: true };
-    const actions = harnesses.map((harness) => planUninstall(harness, installOptions));
+    const actions = planCombinedUninstallActions(harnesses, installOptions);
     if (dryRun) {
         for (const action of actions) {
             printActionPlan(action);
         }
         return;
     }
-    const results = await Promise.all(actions.map((action) => runAction(action, installOptions)));
+    const results = (await Promise.all(harnesses.map((harness) => runCombinedUninstall(harness, installOptions)))).flat();
     reportInstallResults(results, "uninstall");
 }
 export async function runInstallSkillCommand(parsed) {
@@ -107,6 +111,49 @@ 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 planCombinedUninstallActions(harnesses, installOptions) {
+    return harnesses.flatMap((harness) => [
+        planUninstall(harness, installOptions),
+        planSkillUninstall(harness, {
+            ...installOptions,
+            skipMissing: false
+        })
+    ]);
+}
+async function runCombinedInstall(harness, installOptions) {
+    const mcpAction = planInstall(harness, installOptions);
+    const mcpResult = await runAction(mcpAction, installOptions);
+    if (!mcpResult.ok || mcpResult.skipped) {
+        return [mcpResult];
+    }
+    const skillAction = planSkillInstall(harness, installOptions);
+    const skillResult = await runAction(skillAction, installOptions);
+    return [mcpResult, skillResult];
+}
+async function runCombinedUninstall(harness, installOptions) {
+    const mcpAction = planUninstall(harness, installOptions);
+    const mcpResult = await runAction(mcpAction, installOptions);
+    const skillAction = planSkillUninstall(harness, installOptions);
+    const skillResult = await runAction(skillAction, installOptions);
+    return [mcpResult, skillResult];
+}
 function selectHarnesses(parsed) {
     if (hasOption(parsed, "all")) {
         const detected = SUPPORTED_HARNESSES.filter((harness) => detectHarness(harness).detected);

package/dist/cli/output.js

@@ -122,6 +122,7 @@ Commands:
   tt list [path]
   tt join [path] [--force-new]
   tt leave [path]
+  tt kick <agent_id> [path] [--reason TEXT] [--force]
   tt wait [path] [--timeout 30s]
   tt try [path]
   tt state [path]
@@ -134,10 +135,8 @@ Commands:
   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]
+  tt install <harness...> | --all [--print] [--copy] [--link]
   tt uninstall <harness...> | --all [--print]
-  tt install-skill <harness...> | --all [--print] [--copy] [--link]
-  tt uninstall-skill <harness...> | --all [--print]
   tt self-update [--print] [--manager npm|pnpm|yarn|bun]
 
 Harnesses: ${SUPPORTED_HARNESSES.join(", ")}

package/dist/cli/registry.js

@@ -2,7 +2,7 @@ import { runStdioServer } from "../index.js";
 import { runGuardCommand } from "./guardian.js";
 import { runInstallCommand, runInstallSkillCommand, runSelfUpdateCommand, runUninstallCommand, runUninstallSkillCommand } from "./install-commands.js";
 import { handleNotesCommand } from "./notes-commands.js";
-import { handleEventsCommand, handleJoinCommand, handleLeaveCommand, handleListCommand, handleStateCommand, handleWhoAmICommand } from "./room-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 = [
     {
@@ -28,8 +28,8 @@ export const COMMAND_REGISTRY = [
         needsRuntime: false,
         startupMaintenance: false,
         internal: false,
-        usage: "tt install <harness...> | --all [--print]",
-        description: "Install Talking Stick into harness MCP configs.",
+        usage: "tt install <harness...> | --all [--print] [--copy] [--link]",
+        description: "Install Talking Stick into harness MCP configs and skills.",
         handler: ({ parsed }) => runInstallCommand(parsed)
     },
     {
@@ -38,7 +38,7 @@ export const COMMAND_REGISTRY = [
         startupMaintenance: false,
         internal: false,
         usage: "tt uninstall <harness...> | --all [--print]",
-        description: "Remove Talking Stick from harness MCP configs.",
+        description: "Remove Talking Stick from harness MCP configs and skills.",
         handler: ({ parsed }) => runUninstallCommand(parsed)
     },
     {
@@ -104,6 +104,15 @@ export const COMMAND_REGISTRY = [
         description: "Leave this agent's room membership.",
         handler: ({ runtime, parsed }) => handleLeaveCommand(requireRuntime(runtime), parsed)
     },
+    {
+        name: "kick",
+        needsRuntime: true,
+        startupMaintenance: true,
+        internal: false,
+        usage: "tt kick <agent_id> [path] [--reason TEXT] [--force]",
+        description: "Kick an idle member out of the room.",
+        handler: ({ runtime, parsed }) => handleKickCommand(requireRuntime(runtime), parsed)
+    },
     {
         name: "state",
         needsRuntime: true,

package/dist/cli/room-commands.js

@@ -1,7 +1,7 @@
 import { deriveCliIdentity, resolveCliIdentity } from "./identity.js";
 import { removeCliSession, removeCliSessionsForRoom, resolveCliSessionPath } from "../index.js";
 import { stopGuardian } from "./guardian.js";
-import { parseOptionalInteger } from "./parser.js";
+import { getStringOption, hasOption, parseOptionalInteger } from "./parser.js";
 import { formatRelativeTime, printResult } from "./output.js";
 import { resolveSessionForReads, upsertSessionFromJoin } from "./session.js";
 export function handleListCommand(runtime, parsed) {
@@ -56,6 +56,35 @@ export function handleLeaveCommand(runtime, parsed) {
         return `Left ${session.canonical_path}; ${result.remaining_members} ${memberLabel}.`;
     });
 }
+export function handleKickCommand(runtime, parsed) {
+    const [target, ...rest] = parsed.positionals;
+    if (!target) {
+        throw new Error("Missing required argument: <agent_id>");
+    }
+    const sessionParsed = { ...parsed, positionals: rest };
+    const identity = deriveCliIdentity(sessionParsed);
+    const session = resolveSessionForReads(runtime, sessionParsed, identity);
+    const result = runtime.commands.kickMember(identity, {
+        room_id: session.room_id,
+        target_agent_id: target,
+        force: hasOption(parsed, "force"),
+        reason: getStringOption(parsed, "reason")
+    });
+    const sessionPath = resolveCliSessionPath();
+    if (result.status === "room_deleted") {
+        removeCliSessionsForRoom(sessionPath, session.room_id);
+    }
+    else {
+        removeCliSession(sessionPath, result.kicked_agent_id, session.room_id);
+    }
+    printResult(parsed, result, () => {
+        if (result.status === "room_deleted") {
+            return `Kicked ${result.kicked_agent_id}; room deleted.`;
+        }
+        const memberLabel = result.remaining_members === 1 ? "member remains" : "members remain";
+        return `Kicked ${result.kicked_agent_id}; ${result.remaining_members} ${memberLabel}.`;
+    });
+}
 export function handleStateCommand(runtime, parsed) {
     const identity = deriveCliIdentity(parsed);
     const session = resolveSessionForReads(runtime, parsed, identity);

package/dist/commands.js

@@ -24,6 +24,15 @@ export class TalkingStickCommands {
             room_id: input.room_id
         });
     }
+    kickMember(identity, input) {
+        return this.service.kickMember({
+            agent_id: identity.agent_id,
+            room_id: input.room_id,
+            target_agent_id: input.target_agent_id,
+            force: input.force,
+            reason: input.reason
+        });
+    }
     waitForTurn(identity, input) {
         return this.service.waitForTurn({
             agent_id: identity.agent_id,

package/dist/identity.js

@@ -41,7 +41,7 @@ export function deriveMcpHarnessIdentity(options = {}) {
     const signal = detectHarnessSignal(env);
     if (signal) {
         const processRef = resolveSignalProcessRef(signal, parentPid, parentInspection, inspector);
-        const sessionId = resolveHarnessSessionId(signal, env, processRef.pid, processRef.inspection, username, hostId);
+        const sessionId = resolveHarnessSessionId(signal, env, processRef.pid, processRef.inspection, username, hostId, inspector);
         const agentId = options.agentId ?? harnessAgentId(signal.harness, sessionId, hostId, username);
         return {
             agent_id: agentId,
@@ -103,7 +103,7 @@ export function deriveHarnessCliIdentity(options = {}) {
         return null;
     const processRef = resolveSignalProcessRef(signal, parentPid, parentInspection, inspector);
     const username = options.username ?? safeUsername();
-    const sessionId = resolveHarnessSessionId(signal, env, processRef.pid, processRef.inspection, username, hostId);
+    const sessionId = resolveHarnessSessionId(signal, env, processRef.pid, processRef.inspection, username, hostId, inspector);
     const agentId = options.agentId ?? harnessAgentId(signal.harness, sessionId, hostId, username);
     return {
         agent_id: agentId,
@@ -124,17 +124,47 @@ function harnessAgentId(harness, sessionId, hostId, username) {
         sanitizeIdentityComponent(username)
     ])}`;
 }
-function resolveHarnessSessionId(signal, env, parentPid, parentInspection, username, hostId) {
+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}`;
+    }
     if (parentInspection?.startTime) {
         return `pid:${parentPid}@${parentInspection.startTime}`;
     }
     return `userhost:${sanitizeIdentityComponent(username)}@${hostId}`;
 }
+// Walks the process ancestry (inclusive of startPid) looking for the deepest
+// process whose command matches the named harness. Anchoring session id to
+// that root keeps `tt` invocations stable whether they're spawned directly
+// by the harness (MCP subprocess) or through intermediate shells (CLI shell-out).
+function findHarnessRootInAncestry(harness, startPid, startInspection, inspector, maxDepth = 10) {
+    let result = null;
+    let currentPid = startPid;
+    let currentInspection = startInspection;
+    for (let i = 0; i < maxDepth; i++) {
+        if (currentPid == null || currentPid <= 1)
+            break;
+        if (currentInspection === undefined) {
+            currentInspection = inspector.inspect(currentPid);
+        }
+        if (!currentInspection)
+            break;
+        const label = deriveCommandLabel(currentInspection.command);
+        if (HARNESS_COMMAND_MAPPING[label] === harness &&
+            currentInspection.startTime) {
+            result = { pid: currentPid, startTime: currentInspection.startTime };
+        }
+        currentPid = currentInspection.ppid ?? null;
+        currentInspection = undefined;
+    }
+    return result;
+}
 const TERMINAL_SESSION_ENV_VARS = [
     "ITERM_SESSION_ID",
     "CMUX_TAB_ID",

package/dist/mcp-server.js

@@ -27,7 +27,7 @@ export function createMcpServer(service = new TalkingStickService()) {
     const resolveConnectionIdentity = createConnectionIdentityResolver();
     const server = new McpServer({
         name: "talking-stick",
-        version: "0.1.1"
+        version: "0.1.2"
     });
     server.registerTool("list_rooms", {
         title: "List Rooms",
@@ -55,6 +55,16 @@ export function createMcpServer(service = new TalkingStickService()) {
             room_id: z.string().min(1)
         }
     }, async (input, extra) => toolJson(() => commands.leaveRoom(resolveConnectionIdentity(extra.sessionId), input)));
+    server.registerTool("kick_member", {
+        title: "Kick Member",
+        description: "Remove an idle member from a room. Without force, only succeeds if the target's process is detected gone past the silence-grace window.",
+        inputSchema: {
+            room_id: z.string().min(1),
+            target_agent_id: z.string().min(1),
+            force: z.boolean().optional(),
+            reason: z.string().optional()
+        }
+    }, async (input, extra) => toolJson(() => commands.kickMember(resolveConnectionIdentity(extra.sessionId), input)));
     server.registerTool("wait_for_turn", {
         title: "Wait For Turn",
         description: "Poll until the caller can claim the stick or takeover is available.",

package/dist/service.js

@@ -128,6 +128,92 @@ export class TalkingStickService {
             };
         });
     }
+    kickMember(input) {
+        assertNonEmpty(input.agent_id, "agent_id");
+        assertNonEmpty(input.room_id, "room_id");
+        assertNonEmpty(input.target_agent_id, "target_agent_id");
+        if (input.target_agent_id === input.agent_id) {
+            throw new ProtocolError("cannot_kick_self", "Use leave_room to remove yourself.", { to_agent_id: input.target_agent_id });
+        }
+        const now = this.now();
+        const timestamp = now.toISOString();
+        this.purgeExpiredIdleRooms(now);
+        return withImmediateTransaction(this.db, () => {
+            const room = this.requireRoom(input.room_id);
+            this.touchMember(input.room_id, input.agent_id, timestamp);
+            const target = this.getMember(input.room_id, input.target_agent_id);
+            if (!target) {
+                throw new ProtocolError("unknown_target", "Target agent is not a member of this room.", { to_agent_id: input.target_agent_id });
+            }
+            if (!input.force) {
+                const liveness = this.getMemberProcessLiveness(target);
+                if (!this.isGonePersistent(target, liveness, now)) {
+                    throw new ProtocolError("target_active", "Target is still active. Pass force=true to kick anyway.", { to_agent_id: input.target_agent_id });
+                }
+            }
+            const targetWasOwner = room.owner === input.target_agent_id;
+            const targetWasReservedFor = room.reserved_for === input.target_agent_id;
+            this.db
+                .prepare("DELETE FROM room_members WHERE room_id = ? AND agent_id = ?")
+                .run(input.room_id, input.target_agent_id);
+            this.appendEvent({
+                room_id: input.room_id,
+                turn_id: room.turn_id,
+                event_type: "kick",
+                from_agent_id: input.agent_id,
+                to_agent_id: input.target_agent_id,
+                handoff: null,
+                reason: input.reason ?? null,
+                created_at: timestamp
+            });
+            const remainingMembers = this.getMembers(input.room_id);
+            if (remainingMembers.length === 0 ||
+                !remainingMembers.some((remaining) => this.isMemberActive(remaining, now))) {
+                this.deleteRoom(input.room_id);
+                return {
+                    status: "room_deleted",
+                    room_id: input.room_id,
+                    canonical_path: room.canonical_path,
+                    kicked_agent_id: input.target_agent_id,
+                    remaining_members: 0,
+                    target_was_owner: targetWasOwner,
+                    target_was_reserved_for: targetWasReservedFor
+                };
+            }
+            const nextOwner = targetWasOwner ? null : room.owner;
+            const nextReservedFor = targetWasReservedFor ? null : room.reserved_for;
+            const nextState = room.state === "closed"
+                ? "closed"
+                : nextOwner
+                    ? "owned"
+                    : nextReservedFor
+                        ? "reserved"
+                        : "idle";
+            this.db
+                .prepare(`
+          UPDATE path_rooms
+          SET owner = ?,
+              reserved_for = ?,
+              pending_handoff_event_seq = ?,
+              lease_id = ?,
+              lease_expires_at = ?,
+              claim_expires_at = ?,
+              state = ?,
+              updated_at = ?
+          WHERE room_id = ?
+        `)
+                .run(nextOwner, nextReservedFor, targetWasOwner ? null : room.pending_handoff_event_seq, targetWasOwner ? null : room.lease_id, targetWasOwner ? null : room.lease_expires_at, targetWasReservedFor ? null : room.claim_expires_at, nextState, timestamp, input.room_id);
+            return {
+                status: "kicked",
+                room_id: input.room_id,
+                canonical_path: room.canonical_path,
+                kicked_agent_id: input.target_agent_id,
+                remaining_members: remainingMembers.length,
+                target_was_owner: targetWasOwner,
+                target_was_reserved_for: targetWasReservedFor
+            };
+        });
+    }
     async waitForTurn(input) {
         assertNonEmpty(input.agent_id, "agent_id");
         assertNonEmpty(input.room_id, "room_id");

package/docs/ambient-presence.md

@@ -44,7 +44,7 @@ Important distinction: the marker directory is an **ambient-presence enablement
 Two immediate surfaces, both driven by the local SQLite store:
 
 - **Shell prompt fragment** — a `tt status --prompt` subcommand that prints a short PS1-safe string (or nothing). Wired into Bash `PROMPT_COMMAND`, Zsh `precmd`, Fish `fish_prompt`.
-- **Background room event stream** — an extension of `tt events`, most likely `tt events --follow`, that emits one JSON line per room event to stdout and can resume from a stored `event_seq`.
+- **Background room event stream** — an extension of `tt events`, most likely `tt events --follow`, that emits one line per room event to stdout and can resume from a stored `event_seq`. Harness-detected runs default to JSON lines; plain human CLI runs default to readable text.
 
 The existing `tt wait` command keeps its current meaning: claimant-side wait for `your_turn` / `takeover_available`. Ambient presence should not overload `wait` into a second, room-wide event API.
 
@@ -108,10 +108,10 @@ Shell integration snippets ship under `integrations/shell/` with a `tt prompt in
 
 ### `tt events --follow`
 
-Line-oriented room event stream. Stdout is JSON lines, one event per line. Stderr is for diagnostics only.
+Line-oriented room event stream. Stdout is one event per line. Stderr is for diagnostics only.
 
 ```
-tt events [path] --follow [--after <event_seq>] [--event <types>] [--json|--pretty]
+tt events [path] --follow [--after <event_seq>] [--event <types>] [--json|--text]
 ```
 
 Flags:
@@ -119,7 +119,9 @@ Flags:
 - `--follow` — continue polling for new room events instead of returning a bounded page.
 - `--after` — resume after the last seen `event_seq`.
 - `--event` — comma-separated filter over raw room event types.
-- `--json` / `--pretty` — output format.
+- `--json` / `--text` — output format override.
+
+Default output follows identity. If the CLI detects a supported harness identity (`TT_HARNESS_AGENT_ID`, `CLAUDECODE`, `CODEX_THREAD_ID`, `GEMINI_CLI`, or `OPENCODE`), the stream emits JSON lines suitable for background harness glue. If no harness is detected and the CLI falls back to a human identity, the stream emits human-readable text. Humans should not need to pipe through `jq` just to make room activity readable; scripts can still pass `--json`.
 
 The stream should align with the core room event log, not invent a second taxonomy. For the MVP, the on-the-wire event types should be the existing `RoomEvent` types:
 
@@ -165,7 +167,7 @@ The skill body covers:
 - **Identity in spawned shells.** This is the real fork in the road. If a harness can cheaply export its protocol identity into child shells, participant-mode shell helpers are viable. If not, observer mode should ship first and participant mode moves to a later release.
 - **Event granularity.** Coarse events (room-event log only) minimize context pollution; fine events (every lease poke, every presence blip) enable richer UX but flood. Start with raw room events plus caller-centric `tt wait`.
 - **Skill activation reliability.** Skills load on description match or bootstrap, not on `cd`. The repo marker plus an `AGENTS.md` / `CLAUDE.md` line is the most reliable trigger we have without harness-specific hooks.
-- **Cross-harness event format.** The event stream must be plain JSON lines — no dependency on any one harness's notification shape. Harnesses read lines; they map to their own notification system.
+- **Cross-harness event format.** The machine event stream must be plain JSON lines — no dependency on any one harness's notification shape. Harnesses read lines; they map to their own notification system. Human CLI output remains readable by default unless `--json` is requested.
 - **Current task in ambient status.** Showing the owner's current task would be high-signal, but it should come from the handoff that granted the current turn, not from guessed free text. That likely requires the core room projection to retain the granting handoff pointer or a current-task snapshot. Good follow-up; not a v1 requirement for the prompt fragment.
 - **Non-interactive shells.** This is intentionally deferred, not dropped. `PS1` only covers interactive shells; harness command runners need a different hook. A future shell prelude or harness-specific command hook should render ambient state for invoked commands. If it can prove participant identity, it may render participant-local status; otherwise it should emit observer-only conversation status. Treat this as a follow-on stage, not as part of the first shippable surface.
 - **Multiple rooms per repo.** Out of scope for v1; assume one active room per workspace path. The CLI surface should not preclude multi-room later.

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

@@ -0,0 +1,290 @@
+# Out-of-Band Signaling Between Harnesses
+
+**Status:** Design proposal — not yet scheduled. Intended for cross-harness review (Codex + Claude Code).
+**Related:** [ambient-presence.md](../ambient-presence.md), [talking-stick-plan.md](../talking-stick-plan.md)
+
+## Purpose
+
+The talking stick today enforces **in-band, single-speaker** coordination: the holder is the only participant whose work actually mutates the workspace, and other participants either wait or observe. That is correct for write authority. It is too restrictive for *signaling*.
+
+There are real situations where a non-holder needs to reach the holder — or needs to be reached — *without* taking the stick:
+
+- The non-holder is watching the holder's work and notices a problem (wrong file, broken assumption, looming merge conflict). It should be able to say so without forcing a takeover.
+- A new participant joins the room mid-turn. The holder may want to greet, hand off, or just acknowledge. Today the holder finds out only when they next call `get_room_state`.
+- A participant leaves the room mid-task. The holder should know not to `pass_stick` to a harness that is no longer participating.
+- A holder finds an issue that another harness should address next. It should be able to page that harness before the formal handoff so the recipient is not surprised at claim time.
+- An operator drops a note ("we're scoping down — stop after the test passes"). The holder should see it before the next handoff boundary.
+- The watcher itself is an LLM ("guardian") spawned to keep the holder honest; its only job is to tail the room and raise its hand on specific conditions.
+- A release/pass event can be useful as an early wake-up signal for a waiting harness, even though `wait_for_turn` remains the authority that decides whether the harness may claim.
+
+This document proposes the smallest primitive set that lets harnesses exchange these signals over the existing room-event log, plus the harness-side glue (background watcher + stdout-line notification) that makes them feel ambient instead of poll-driven.
+
+It is a layer on top of [ambient-presence.md](../ambient-presence.md). Where ambient-presence proposes `tt events --follow` as a one-way *observer* stream for waiting agents, this document extends the same stream to be the channel for *directed* signals into an active turn, and defines what those signals look like.
+
+## Vision
+
+Vignette A — guardian catches a wrong turn:
+
+1. Codex holds the stick, working on `src/auth/session.ts`.
+2. Claude Code runs `tt events --follow` in the background under its Monitor tool. It is observer-only on the room.
+3. A `note_added` event arrives with severity `page` plus a capped body preview: *"You're editing session.ts but the bug is in token.ts — see line 84."*
+4. Claude Code's harness surfaces the line to the user, who can choose to interrupt Codex or let it self-correct on next read of room notes.
+5. Codex finishes, calls `release_stick`, picks up the note via existing `list_notes`, acknowledges, hands off.
+
+Vignette B — join awareness mid-turn:
+
+1. Claude Code holds the stick on a long refactor.
+2. A human runs `tt join` from a second terminal to observe.
+3. A `member_joined` event arrives on Claude's background watcher.
+4. Claude's watcher rule says: *member_joined is informational, not an interrupt — write it to the boundary buffer, not the loud Monitor stream.*
+5. At next handoff prep, Claude reads the buffered events and notes "Wojtek joined two minutes ago" in the handoff body.
+
+Vignette C — operator pages the active holder:
+
+1. The current holder is in the middle of a long edit.
+2. The operator posts `tt notes add --severity page --target <holder> "Scope down: stop after the parser test passes."`
+3. The holder's page channel emits one loud JSON line with the note id, author, severity, and capped preview.
+4. The holder may act immediately or acknowledge at handoff. The page does not grant or revoke write authority.
+
+Vignette D — a participant leaves before handoff:
+
+1. Claude Code holds the stick and originally expected to pass the next turn to Gemini for review.
+2. Gemini exits the room, or its membership is marked inactive after the implementation-defined debounce window.
+3. Claude's buffer channel records `member_left` with `from_agent_id = gemini:...` and a reason.
+4. At handoff prep, Claude sees the buffered leave event and does **not** `pass_stick` to Gemini. It either releases to the normal sequence or chooses a different active recipient with an explicit reason.
+
+Vignette E — the holder pages a future recipient:
+
+1. Codex holds the stick and finds a regression that Claude should address after Codex finishes the current edit.
+2. Codex posts `add_note` with `severity: "page"` and `target_agent_id = "claude:..."`: *"When I pass back, please start with tests/cli.test.ts; the install dry-run expectation is stale."*
+3. Claude's page channel receives the note while Claude is still a non-holder. Claude may read and prepare, but still must not mutate the workspace until it owns the stick.
+4. Codex later passes or releases with a handoff that references the same `note_id`, so the formal turn boundary and the earlier page line reconcile.
+
+Vignette F — a third harness joins an existing pair:
+
+1. Codex and Claude have been alternating on a feature.
+2. OpenCode joins the room to take over UI verification.
+3. Both active watchers see `member_joined` in their buffer channels. It is not page-worthy by default, but it changes the social shape of the next handoff.
+4. The current holder can mention the new participant in the next handoff, avoid hard-passing between only the original two harnesses, or explicitly pass to OpenCode if that is the right next owner.
+
+Vignette G — handoff as an early wake-up signal *(deferred future work, captured here for context):*
+
+1. Claude is waiting and, absent any other signal, would wake from its own scheduler in two minutes.
+2. Codex releases the stick ten seconds later.
+3. A future wait-helper sees the `release` event immediately and asks Claude to run a short `wait_for_turn` probe.
+4. `wait_for_turn` still decides whether Claude may claim. The event line is only an advisory wake-up, and this optimization remains deferred until wait intent is modeled explicitly.
+
+## Scope
+
+In scope:
+
+- Extending the `RoomEvent` taxonomy so the existing `event_seq` log carries presence and notes, not just stick mutations.
+- Defining a "page" semantic on top of notes so harnesses can distinguish *interrupt-worthy* from *buffer-until-boundary*.
+- Specifying the stdout-line watcher contract that lets a harness convert events into harness-native notifications.
+- Quantifying the token cost of running such a watcher continuously.
+
+Explicitly out of scope:
+
+- Any new write authority for non-holders. Notes/pages do not grant the stick. Takeover remains the only way to seize write authority and is unchanged.
+- A second event log, second cursor concept, or second identity model. Everything reuses `event_seq`, `agent_id`, and the existing room-resolution rules.
+- Push transports (websockets, MCP resource subscriptions). Pull-based long-poll over SQLite is sufficient for v1; see *Tradeoffs*.
+- Any harness-specific notification format. Harness-detected runs get machine-readable JSON lines; plain human CLI runs get human-readable text by default. `--json` and `--text` remain explicit overrides.
+- Event-driven stick claiming. `wait_for_turn` remains the authoritative wait/claim path in v1; using the event stream to wake waiters is deferred until wait intent is modeled explicitly.
+
+## Architecture
+
+Four layers, building on what exists.
+
+### Layer 1 — Extended event taxonomy
+
+Today `RoomEvent.event_type` is `"claim" | "release" | "pass" | "takeover" | "close"`. Notes (`addNote`) live in a separate `notes` table and emit nothing into `room_events`. Member join/leave does not emit events at all. That means the long-poll stream has nothing to say about anything except stick handoffs.
+
+Proposed additions to `event_type`:
+
+| New event         | Emitted when                                       | Fields beyond the common ones                  |
+|-------------------|----------------------------------------------------|------------------------------------------------|
+| `member_joined`   | `joinPath` adds a member or reactivates one        | `to_agent_id` = joiner                         |
+| `member_left`     | `leaveRoom` succeeds, or a member is GC'd inactive | `from_agent_id` = leaver, `reason`             |
+| `note_added`      | `addNote` succeeds                                 | `note_id`, `severity`, `target_agent_id?`, `body_preview?` |
+| `note_resolved`   | A future `resolve_note` (or implicit on takeover)  | `note_id`                                      |
+
+Rationale for putting notes into the event log rather than inventing a parallel notes-stream:
+
+- Single cursor. Watchers already need `event_seq` to resume after disconnect; folding notes in means no second cursor and no race between two streams.
+- Replay parity. Rebuilding room state from the event log already requires reading every mutation; adding notes to that stream means a fresh observer can reconstruct "what does the holder need to know?" without a second query.
+- Audit shape. The event log is append-only and ordered. Notes already are too. The shapes match.
+
+The persisted `note_added` event carries metadata: `note_id`, `severity`, optional `target_agent_id`, and a capped `body_preview` for page delivery. The full body still lives in the `notes` table and is fetched via `list_notes`. This keeps persisted event payloads bounded while making a page line actionable without a second foreground tool call.
+
+### Layer 2 — Note severity and targeting
+
+Notes today are flat: any member can post one, the holder reads them at handoff boundaries. To support out-of-band signaling we add two optional fields on `AddNoteInput`:
+
+```ts
+interface AddNoteInput {
+  agent_id: AgentId;
+  room_id: string;
+  body: string;
+  turn_id?: number;
+  severity?: "info" | "page";        // NEW — defaults to "info"
+  target_agent_id?: AgentId;          // NEW — null/undefined = whole room
+}
+```
+
+Semantics:
+
+- `severity: "info"` (default) — buffer until the recipient's next safe boundary. Watchers should NOT interrupt the active turn for these.
+- `severity: "page"` — recipient's watcher SHOULD interrupt the active turn. Use sparingly. The protocol does not enforce attention; it provides the signal and lets the receiving harness decide.
+- `target_agent_id` — addresses a specific member. If absent, the note is room-wide. The current holder is implicitly a target for any unaddressed page.
+
+The protocol does **not** define what "interrupt" means in any specific harness. That is each harness's call. The protocol guarantees only: the event arrives, the severity is preserved, and the cursor advances.
+
+### Layer 3 — `tt events --follow` as the harness channel
+
+Already proposed in [ambient-presence.md](../ambient-presence.md) §`tt events --follow`. We adopt it verbatim and extend it with the new event types. Restating the contract for completeness:
+
+```
+tt events [path] --follow
+              [--after <event_seq>]
+              [--event <type[,type...]>]
+              [--severity info|page]
+              [--target self|any|<agent_id>]
+              [--json|--text]
+```
+
+Stdout is line-oriented and flushed after each event. When the CLI detects one of the supported harness identities (`TT_HARNESS_AGENT_ID`, `CLAUDECODE`, `CODEX_THREAD_ID`, `GEMINI_CLI`, or `OPENCODE`), default stdout is one JSON object per line. When no harness is detected and the CLI falls back to a human identity, default stdout is human-readable text. `--json` forces JSON lines for scripts; `--text` forces human-readable text even from a harness. Stderr is diagnostics only. Exit on `SIGTERM`/`SIGHUP` with a final flush.
+
+The new `--severity` and `--target` flags filter `note_added` events specifically. A guardian-style harness uses two logical channels:
+
+```
+# Page channel — loud. One line here means "interrupt the holder now."
+tt events --follow --event note_added --severity page --target self --json
+
+# Buffer channel — quiet. Write to a local cursor/log and read at the next safe boundary.
+tt events --follow --event member_joined,member_left,note_added --severity info --target any --json
+```
+
+The distinction is not just severity in the JSON payload. Some harness glue, notably Claude Code's Monitor tool, treats *every stdout line* from a watched process as a conversation notification. Page output is suitable for that loud path. Buffer output is not; it should be drained into a local cursor/log and summarized by the foreground agent at handoff or another safe boundary.
+
+### Wait pattern — not changed by this plan
+
+This proposal does **not** replace `wait_for_turn` with event-stream notifications for stick availability.
+
+The current queue mechanics rely on `wait_for_turn` as both the claim authority and the wait-intent heartbeat. In the service today, `wait_for_turn` updates `last_wait_at`, and normal `release_stick` only reserves the stick for a candidate whose wait is recent according to `waiterGraceMs`. A participant that probes once and then sleeps only on event lines for minutes can therefore change the normal reservation behavior.
+
+The v1 skill should continue to teach direct `wait_for_turn` long-polls. A future event-driven wait helper can use the same event stream as an advisory wakeup channel, but it first needs an explicit wait-intent design, for example `waiting_since` / `wait_intent_expires_at` renewed by a helper. That follow-up helper would still run `wait_for_turn` to claim; event lines would be a bell, not the lock.
+
+### Layer 4 — Harness-side: background process + stdout-line notification
+
+The actual integration in Claude Code:
+
+1. Foreground agent starts the page channel in the background and attaches Monitor to that process only.
+2. Foreground agent starts the buffer channel separately, without Monitor, writing JSON lines plus the last seen `event_seq` to a local cursor/log.
+3. Page lines are injected into the conversation immediately. Buffer lines are read deliberately at handoff prep or another safe boundary.
+4. The agent still uses `wait_for_turn` for turn ownership; these channels are notification surfaces only.
+
+Equivalents in other harnesses:
+
+- **Codex** — spawn `tt events --follow` as a child process; map stdout lines to `attach` events on the active task. Same shape, different transport name.
+- **OpenCode / Gemini** — long-poll via shell subprocess; whatever the harness calls "background output" is the right hook.
+- **Plain shell (human operator)** — `tt events --follow` in a tmux pane, with human-readable output by default; add `--json` only when piping to a script.
+
+The protocol does not need to know which harness is on the other end. The contract is: line in, notification out.
+
+## Token-cost analysis
+
+Concrete numbers, since this was the explicit question.
+
+**Idle cost: zero.** A backgrounded `tt events --follow` is a child process. It consumes no model tokens while running. The harness keeps a process handle, not a context-window slot.
+
+**Per-event cost: small and proportional.** Each page line that Monitor surfaces becomes a notification message in the conversation. A typical page line is on the order of 100–300 tokens with a capped body preview; each `member_joined` buffer line is under 80 tokens and should not enter the conversation until the agent chooses to summarize buffered context.
+
+**Annual budget for a busy room:** at, say, 50 events per active hour (very high — typical rooms see far fewer), that is ~5 000 tokens per hour of room activity surfaced into the holder's context. By comparison, a single `get_room_state` call already costs several hundred tokens, and most agents call it on every turn. The watcher is cheap.
+
+**Where it actually gets expensive:**
+
+- If `note_added` events inline full bodies. Don't — keep full bodies in `list_notes`; page output gets only a capped preview.
+- If watchers don't filter. A holder doesn't need its own `claim` events echoed back. Filter via `--event` and `--target`.
+- If many idle agents all run watchers on the same room. The cost is per-agent-context, not per-room. With N agents, N watchers, N copies of each event in N contexts. Acceptable for small N (≤4 typical), worth revisiting if rooms grow.
+- If the watcher is replaced with a polling loop that calls `get_room_events` every few seconds. That defeats the design — the foreground agent burns tokens making the polling decisions. The watcher's whole point is to push that decision to a child process and only spend tokens on actual events.
+
+**On long-poll vs. push:** the watcher process can implement long-poll internally (block on SQLite for up to N seconds, emit on change, re-block). That makes the *process* efficient. But from the *foreground agent's* perspective, push and long-poll are identical — both surface as a stdout line when something happens. So the choice is a server-side performance question, not a token question. v1 can use a 1-second SQLite poll inside `tt events --follow` and still cost zero foreground tokens between events.
+
+## Concrete surface changes
+
+### Service / DB
+
+1. Add `member_joined`, `member_left`, `note_added`, `note_resolved` to the `event_type` enum in `src/types.ts`. The SQLite `room_events.event_type` column is already free text, but migration 5 should add nullable metadata columns for note events: `note_id`, `severity`, `target_agent_id`, and `body_preview`.
+2. `joinPath`, `leaveRoom`, `addNote` all call `appendEvent(...)` in their respective transactions. They already run inside the same transaction as the state mutation, so atomicity is free.
+3. Add optional `severity: "info" | "page"` and `target_agent_id` columns to the `notes` table. Default severity `info`. Existing rows back-fill to `info`, no `target`.
+4. New service method `resolveNote({ agent_id, room_id, note_id })` that flips `resolved_at` / `resolved_by_agent_id` and emits `note_resolved`. Optional for v1 but cheap.
+
+### CLI
+
+1. `tt notes add --severity page --target <agent_id> "body"` — pass-through of new fields.
+2. `tt events --follow [--after N] [--event T,...] [--severity ...] [--target ...] [--json|--text]` — per Layer 3. Default output follows detected identity: supported harness envs get JSON lines; human fallback gets readable text. `--target self` requires participant identity; observer-only shells must use `--target any` or an explicit agent id.
+3. `tt notes resolve <note_id>` — wraps `resolveNote`. Optional for v1.
+
+### MCP
+
+1. `add_note` tool gains optional `severity` and `target_agent_id` parameters.
+2. `get_room_events` already accepts `after_event_seq` and `limit`; no signature change needed for the new event types — they are additive on the discriminated union.
+3. New MCP tool `resolve_note` — optional for v1.
+
+### Skill
+
+The shipped `skills/talking-stick/SKILL.md` gets a section: *"While you hold the stick, you may receive `note_added` events with severity `page`. Read the page preview, call `list_notes` if you need the full body, decide whether to act now or at the next handoff boundary, and resolve it when addressed."* Include the mirror instruction for non-holders: *"To get the holder's attention without taking the stick, use `add_note` with severity `page`."*
+
+The skill's wait guidance should remain direct `wait_for_turn` long-polling. Event-stream wakeups for stick availability are future work and require explicit wait-intent state before they can replace the current polling cadence.
+
+## Tradeoffs and open questions
+
+- **Why notes-with-severity instead of a separate `messages` primitive?** Notes already are durable, addressable, and resolvable. Adding two fields is cheaper than a parallel messaging table, and the harness-side UX is identical. The risk is conceptual creep: notes today are "things the holder should consider before handoff," and pages stretch that toward "things the holder must consider now." Worth naming explicitly so the skill reflects it.
+- **Should `member_joined` be page-able by default?** No. Joins are too frequent (humans `cd` and out, harnesses restart). Default to `info`. A specific guardian setup can choose to elevate joins by spawning a second `tt events --follow --event member_joined` stream and rendering it loudly.
+- **Heartbeat-stale and takeover-available as events.** Tempting — the watcher could fire one line when the current holder goes stale and another when takeover unlocks. But these are derived states, not log entries; if we synthesize them into the event stream we either need a separate "synthetic events" cursor or we mix derived and persisted events on the same `event_seq`. Recommendation for v1: do not synthesize. Agents that care should continue to long-poll `wait_for_turn`; a future event-driven wait helper can handle derived deadlines after wait intent is modeled explicitly.
+- **Backpressure.** `tt events --follow` writes to stdout. If the harness Monitor stops draining (paused conversation, hit a tool error), the pipe will block. The watcher should use a small bounded write buffer and drop-with-warning rather than blocking forever; design parity with `tail -F`.
+- **Authentication of `target_agent_id`.** Anyone in the room can post a note targeted at anyone else. That matches the existing notes contract (any member can post). If we ever need permissioning, it is a separate concern from this design.
+- **Crash recovery.** Watcher process dies → harness restarts it with `--after <last_seen_event_seq>`. The harness must persist the last-seen seq across restarts; for Claude Code that means the agent writes it to a known location (a memory entry, or a `.talking-stick/` cursor file) before the watcher exits cleanly. Worth specifying in the skill.
+- **Multiple watchers per harness.** Layer 4 suggests two logical streams (page channel + buffer channel). That can be two child processes per agent, or one wrapper process that routes output to separate destinations. The important invariant is routing: page can be Monitor-injected; buffer should not be.
+- **Resolution semantics.** Does a `pass`/`release` auto-resolve outstanding pages? Probably not — the next holder may still need them. But we should mark them as "delivered to holder X at turn Y" so the page does not re-page on every turn. Either a `delivered_at` column on notes, or a per-turn dedup at the harness side. v1 recommendation: dedup at the harness side using `note_id`, no schema change.
+
+## What this plan does NOT yet specify
+
+This document is a design proposal for review, not an implementation specification. The following decisions are deliberately deferred to post-review so that reviewer pushback can shape them. Treat each as a real gap an implementer would hit on day one:
+
+1. **Exact migration 5 DDL.** The repo already has a `schema_migrations` runner in `src/db.ts`. Implementation still needs the exact `ALTER TABLE` sequence for `notes` and `room_events`, plus downgrade expectations for older binaries that see unknown event types.
+2. **`member_left` trigger sites.** Explicit `leaveRoom` is straightforward. Inactivity/GC is not: members can become inactive through liveness checks and opportunistic cleanup. Implementation must decide which transitions emit a durable `member_left`, which reason strings are valid (`"left"`, `"inactive"`, `"gc"`), and how to avoid repeated leave/reactivate noise.
+3. **`member_joined` debounce semantics.** `joinPath` upserts and touches members today, so harness reconnects, repeated `tt join` invocations, and idle CLI sessions can all retrigger the join path for the same `agent_id`. Implementation must define when a `member_joined` event is durable (first insert vs. inactive-after-meaningful-absence) and what reason strings distinguish first-join from reactivation. Without this, page-tier subscribers to joins get retrigger noise on every reconnect.
+4. **Skill prose, in full.** The "Skill" subsection above paraphrases the addition. The actual shipped skill text is what every harness reads on every relevant turn, so it needs to be drafted, reviewed, and kept as tight as the rest of `skills/talking-stick/SKILL.md`.
+5. **Page dedup persistence.** The plan recommends harness-side dedup of pages by `note_id` plus a cursor file for crash recovery. But the dedup set itself is in-memory; after a watcher restart the dedup set is empty, and a still-unresolved page can re-fire on the next event from the buffered tail. Either the cursor file must persist the dedup set too, or the server must offer a "since last delivery to <agent_id>" filter. Pick one before relying on dedup.
+6. **Test plan.** Not enumerated. At minimum: schema migration on a populated v0.1.x database, event ordering when `addNote` and `release_stick` race, filter correctness on `tt events --follow` for each `--event` / `--severity` / `--target` combination, resume-after-cursor with new event types interleaved with existing ones, and behavior when a watcher's stdout is blocked.
+
+These are not blockers for the design discussion — they are inputs to the implementation pass. The architectural decision to keep stick waiting on `wait_for_turn` is intentional; event-driven waiting belongs in a separate wait-intent design.
+
+## Staged rollout
+
+1. **Schema + service:** add new event types, emit on `joinPath`/`leaveRoom`/`addNote`. No CLI/MCP changes yet. Watchers that already follow the event log start seeing the new events immediately.
+2. **`tt events --follow` extended:** add `--severity` and `--target` filters. CLI tests for filter shape and resume-after-cursor.
+3. **`add_note` severity + targeting:** schema change to `notes`, plumbed through service, CLI, MCP. Skill updated.
+4. **Skill rewrite:** holder-side and watcher-side guidance, including page-vs-buffer routing and the reminder that `wait_for_turn` remains the ownership path.
+5. **Optional: `resolve_note` + `note_resolved` event.** Lets pages stop re-paging across handoffs without harness-side dedup.
+6. **Optional: derived-event synthesis** (`takeover_available`, `lease_stale`) as a follow-up document if observer demand justifies it.
+
+## What we are not building
+
+- No new transport. No websockets, no MCP resource subscriptions in v1 (see [ambient-presence.md](../ambient-presence.md) "Out of scope").
+- No write authority changes. Pages are signals, not commands.
+- No automatic takeover on page. Takeover stays a deliberate act gated on `claim_expires_at`.
+- No harness-specific notification format. Harnesses consume JSON lines; humans get readable text by default.
+- No event-driven replacement for `wait_for_turn`. Stick availability remains governed by the existing wait/claim path until a separate wait-intent design exists.
+
+## Summary
+
+The talking stick already has the right primitives for *what* coordinates (rooms, leases, handoffs) and the right primitives for *who* coordinates (agent identity, membership). It is missing primitives for *what flows alongside the work in progress*. This proposal closes that gap with the minimum viable additions:
+
+- Four new event types so the existing log carries presence and notes.
+- Two new fields on notes so non-holders can distinguish a hint from a page.
+- One existing CLI surface (`tt events --follow`) extended with two filter flags.
+- A documented harness pattern (page channel + quiet buffer channel) that costs zero idle tokens and proportional per-event tokens.
+
+Everything else — transports, write-authority changes, derived events, push channels — is deferred until the simple version is in use and we know what is actually missing.

package/docs/releases/0.1.2.md

@@ -0,0 +1,40 @@
+# Talking Stick 0.1.2
+
+Date: 2026-04-27
+
+Patch release focused on simplifying first-time setup and keeping the README in
+sync with the CLI.
+
+## Changed
+
+### Combined harness setup
+
+`tt install` now installs both pieces each harness needs: the MCP server
+registration and the bundled Talking Stick skill. The command accepts the skill
+mode flags directly, so `tt install --all --copy` produces standalone skill
+copies while the default still links the bundled skill.
+
+`tt uninstall` now removes both the MCP registration and the installed skill for
+each selected harness.
+
+The older `tt install-skill` and `tt uninstall-skill` commands remain available
+for targeted maintenance, but they are no longer part of the normal README/help
+setup path.
+
+### README setup path
+
+The quickstart, dry-run instructions, subset install example, removal example,
+installation details, skill path section, and CLI reference now document a
+single-command setup flow:
+
+```bash
+tt install --all
+```
+
+## Verification
+
+- `npm run typecheck`
+- `npm test` — 212 tests across 14 files
+- `npm run build`
+- `git diff --check`
+- `npm pack --dry-run --ignore-scripts`

package/docs/releases/0.1.3.md

@@ -0,0 +1,78 @@
+# Talking Stick 0.1.3
+
+Date: 2026-04-28
+
+Patch release covering one stale-state cleanup tool and one bugfix that
+prevents the duplicate-member problem the cleanup tool addresses.
+
+## Added
+
+### `tt kick` / `kick_member`
+
+Rooms occasionally accumulate ghost members — agents that registered, then
+disappeared without leaving cleanly. Until now there was no first-class way to
+evict them. `tt kick <agent_id>` (CLI) and the `kick_member` MCP tool fill that
+gap.
+
+```bash
+tt kick codex:6e030b4c                 # only succeeds if target is gone
+tt kick codex:6e030b4c --force         # force-remove a still-active member
+tt kick codex:6e030b4c --reason "stale guardian"
+```
+
+Default behavior:
+
+- caller must be an active member of the room
+- target must not be the caller (use `tt leave` for self-removal)
+- target must be detected `gone` past the existing silence-grace window
+  (`2 * heartbeatIntervalMs`); otherwise the call rejects with `target_active`
+
+`--force` / `force: true` bypasses the idleness check for cases where liveness
+detection is wrong (PID reuse, suspended processes) or the operator explicitly
+wants to remove a still-running member.
+
+State transitions mirror `leave_room`: if the target was the owner, ownership
+and lease state are cleared; if the target was the reservation, the reservation
+is cleared; if no active members remain, the room is deleted. Each successful
+kick records a `kick` room event with `from_agent_id`, `to_agent_id`, and
+optional `reason` so other agents tailing `get_room_events` see the cleanup.
+
+New `ProtocolErrorCode`s: `unknown_target`, `target_active`, `cannot_kick_self`.
+
+The bundled skill points agents at `kick_member` for cleaning up `inactive`
+ghost members visible in `tt state`, with `force: true` reserved for explicit
+operator instruction.
+
+## Fixed
+
+### Stable codex agent ids across MCP and shelled-out CLI
+
+Codex sometimes runs `tt` directly as an MCP subprocess and sometimes shells
+out via Bash to invoke the `tt` CLI. Both paths derive the same `codex:<hash>`
+agent id when codex exposes `CODEX_THREAD_ID`, but when only
+`CODEX_MANAGED_BY_NPM=1` is set the previous logic anchored session id on the
+immediate parent pid:
+
+- MCP subprocess: parent = codex root → stable
+- shelled-out CLI: parent = bash subshell → fresh pid every invocation
+
+The result was that long codex sessions accumulated multiple `codex:<hash>`
+members in a single room (one per shell-out), each registering as a new
+`human_guardian` and lingering until liveness expired them.
+
+`resolveHarnessSessionId` now walks process ancestry when the harness env
+signal exists but no explicit session id is exposed, and uses the deepest
+matching ancestor's `pid+startTime` as the anchor. The harness root is stable
+across MCP subprocess and shell-out CLI invocations, so they collapse to one
+agent id.
+
+This is a CLI/MCP-time fix; it does not retroactively merge duplicate members
+already recorded in a room. Use `tt kick` (above) for that.
+
+## Verification
+
+- `npm run typecheck`
+- `npm test` — 222 tests across 14 files
+- `npm run build`
+- `git diff --check`
+- `npm pack --dry-run --ignore-scripts`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "talking-stick",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "MCP coordination server for path-scoped agent handoffs.",
   "type": "module",
   "bin": {

package/skills/talking-stick/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: talking-stick
-description: Use when working in a repo that coordinates multiple agent harnesses with Talking Stick (`tt` / `talking-stick`), or when the user asks you to avoid parallel work, wait your turn, pass structured handoffs, or coordinate with Claude, Codex, Gemini, or OpenCode in the same workspace. Also use when a workspace contains a `.talking-stick/` marker or when the MCP tools `list_rooms`, `join_path`, `leave_room`, `wait_for_turn`, `heartbeat`, `release_stick`, `pass_stick`, `takeover_stick`, `get_room_state`, `get_room_events`, `add_note`, or `list_notes` are available.
+description: Use when working in a repo that coordinates multiple agent harnesses with Talking Stick (`tt` / `talking-stick`), or when the user asks you to avoid parallel work, wait your turn, pass structured handoffs, or coordinate with Claude, Codex, Gemini, or OpenCode in the same workspace. Also use when a workspace contains a `.talking-stick/` marker or when the MCP tools `list_rooms`, `join_path`, `leave_room`, `kick_member`, `wait_for_turn`, `heartbeat`, `release_stick`, `pass_stick`, `takeover_stick`, `get_room_state`, `get_room_events`, `add_note`, or `list_notes` are available.
 ---
 
 This skill teaches a harness how to behave in a Talking Stick workspace.
@@ -26,11 +26,11 @@ Do not use this skill for ordinary single-agent work in repos that are not using
 
 ### 1. Check that Talking Stick is actually available
 
-Prefer the Talking Stick MCP tools when they are available. If they are not available but the `tt` CLI is on `PATH`, use the CLI instead (`tt list`, `tt join`, `tt leave`, `tt wait`, `tt state`, `tt release`, `tt pass`, `tt assign`, `tt take`). Do not treat missing MCP tools alone as proof that coordination is unavailable.
+Prefer the Talking Stick MCP tools when they are available. If they are not available but the `tt` CLI is on `PATH`, use the CLI instead (`tt list`, `tt join`, `tt leave`, `tt kick`, `tt wait`, `tt state`, `tt release`, `tt pass`, `tt assign`, `tt take`). Do not treat missing MCP tools alone as proof that coordination is unavailable.
 
 If coordination is required and neither the MCP tools nor the `tt` CLI are available, say so briefly and ask the user whether they want to install or enable Talking Stick first. Do not pretend coordination is active.
 
-Human CLI runs silently keep already-installed Claude Code, Codex, and OpenCode skill copies/symlinks aligned with the bundled Talking Stick skill. This is best effort and only updates existing installs; Gemini skills are registry-managed and should be refreshed with `tt install-skill gemini` when needed.
+Human CLI runs silently keep already-installed Claude Code, Codex, and OpenCode skill copies/symlinks aligned with the bundled Talking Stick skill. This is best effort and only updates existing installs; Gemini skills are registry-managed and should be refreshed with `tt install gemini` when needed.
 
 ### 2. Join the workspace room once
 
@@ -153,7 +153,7 @@ Example:
     }
   ],
   "open_questions": [
-    "Should install-skill default to copy or link for local development?"
+    "Should tt install default to copy or link for local development?"
   ]
 }
 ```
@@ -178,12 +178,15 @@ In every other case: after `release_stick` or `pass_stick`, go straight back int
 
 If the operator tells you to drop out of coordination, call `leave_room` or `tt leave`. Rooms with no active members are deleted instead of kept as history, and long-idle rooms may be purged on later invocations.
 
+If the room state shows ghost members from past sessions whose processes are gone (visible as `inactive last seen ...` in `tt state`), call `kick_member` / `tt kick <agent_id>` to evict them. This is the right tool when liveness has already decided the target is dead — pass `force: true` only when the operator explicitly tells you to remove a still-active member.
+
 ## Recovery and Inspection
 
 Use these reads when you need context:
 
 - `list_rooms`: discover active rooms under a path
 - `leave_room`: explicitly remove your membership from a room
+- `kick_member`: evict an idle member whose process is gone (use `force: true` only on operator instruction)
 - `get_room_state`: authoritative current room projection
 - `get_room_events`: replay recent claims, releases, passes, and takeovers