talking-stick 0.1.0-alpha.4 → 0.1.0-alpha.5

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Talking Stick contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

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.0-alpha.4. 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.0-alpha.5. Multi-process-safe (SQLite WAL), liveness-aware, no daemon. Supports Claude Code, Codex CLI, Gemini CLI, and OpenCode out of the box.
 
 ## Quickstart
 
@@ -27,7 +27,7 @@ That's it. The next time two agents `cd` into the same repo, they see each other
 
 | Method | Command | Notes |
 |---|---|---|
-| **From npm** | `npm i -g talking-stick` | Published as `0.1.0-alpha.4`. Requires Node ≥ 22. |
+| **From npm** | `npm i -g talking-stick` | Published as `0.1.0-alpha.5`. 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. |
 
@@ -65,6 +65,7 @@ Once installed, each agent harness sees these tools:
 ```
 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
@@ -127,6 +128,7 @@ The same `tt` binary also works as a human CLI, useful for watching or participa
 tt whoami [--explain]                                      # show the resolved CLI identity
 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 try [path]                                             # non-blocking claim attempt
 tt state [path]                                           # full room state
@@ -152,14 +154,15 @@ Human CLI commands use a stable identity like `human:<username>`. When `tt wait`
 
 ### CLI identity
 
-By default, `tt` behaves like a human CLI and resolves to `human:<username>`, even when you run it from a shell embedded inside Claude Code, Codex, Gemini, or OpenCode.
+By default, `tt` behaves like a human CLI and resolves to `human:<username>` only when no harness environment is detected.
 
-Harness-aware CLI identity is now explicit:
+Harness-aware CLI identity is resolved before the human fallback:
 
-- Set `TT_HARNESS_EXPORT=1` if you want `tt` to derive a harness-style identity from the current environment and process ancestry.
+- Known harness environment markers such as `CLAUDECODE=1`, `CODEX_THREAD_ID`, `GEMINI_CLI=1`, or `OPENCODE=1` make `tt` derive a harness-style identity automatically.
 - Set `TT_HARNESS_AGENT_ID=<agent-id>` if the harness wants to export the exact agent id directly.
+- Set `TT_HARNESS_EXPORT=1` only when you need ancestry-based harness detection without a known harness environment marker.
 
-If neither variable is set, `tt` stays on the human CLI path. That keeps ordinary shell usage predictable and avoids silently turning a human terminal into a harness participant.
+If no harness signal is present, `tt` stays on the human CLI path. That keeps ordinary shell usage predictable while preventing harness-launched shells from silently joining rooms as `human:<username>`.
 
 Use `tt whoami --explain` to see which identity path the CLI chose.
 
@@ -168,6 +171,8 @@ Use `tt whoami --explain` to see which identity path the CLI chose.
 - **Workspace-root room resolution.** An agent at any depth under `/repo/` joins the `/repo/` room automatically. Nested rooms require explicit `force_new`.
 - **Structured handoffs.** `release_stick` and `pass_stick` carry a typed `Handoff` with required `status` / `next_action` and optional `artifacts[]` pointing at specific files and line ranges.
 - **Fair handoff selection.** Normal release prefers a recent waiter that is new or has gone longest without holding the stick; if the best-known candidate is between wait polls, a short grace window prevents immediate recycling to a less-fair claimant.
+- **No immediate take-backs.** If release leaves a handoff idle, the prior owner waits through the short grace window before reclaiming while another member exists.
+- **Ephemeral rooms.** `leave_room`/`tt leave` removes membership, rooms with no active members are physically deleted, and long-idle rooms are purged opportunistically on later invocations.
 - **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.
@@ -204,4 +209,4 @@ See [`CHANGELOG.md`](CHANGELOG.md) for a per-version summary; full release notes
 
 ## License
 
-Unlicensed WIP. To be decided before the first release.
+MIT. See [LICENSE](LICENSE).

package/dist/cli/identity.js

@@ -25,10 +25,17 @@ export function resolveCliIdentity(parsed, env = process.env) {
                 detail: "Resolved from explicit TT_HARNESS_AGENT_ID export."
             };
         }
+        if (env.TT_HARNESS_EXPORT === "1" || env.TT_HARNESS_EXPORT?.toLowerCase() === "true") {
+            return {
+                identity: harnessIdentity,
+                source: "harness_cli_exported_detection",
+                detail: "Resolved as harness CLI because TT_HARNESS_EXPORT enabled harness-aware detection."
+            };
+        }
         return {
             identity: harnessIdentity,
-            source: "harness_cli_exported_detection",
-            detail: "Resolved as harness CLI because TT_HARNESS_EXPORT enabled harness-aware detection."
+            source: "harness_cli_env_detection",
+            detail: "Resolved as harness CLI from known harness environment variables."
         };
     }
     if (env.TT_HARNESS_EXPORT?.trim()) {

package/dist/cli/output.js

@@ -1,4 +1,5 @@
 import { SUPPORTED_HARNESSES } from "../install.js";
+import { isKnownHarnessCliEnv } from "./identity.js";
 import { hasOption } from "./parser.js";
 export function printResult(parsed, result, renderText) {
     if (shouldUseJson(parsed)) {
@@ -12,12 +13,13 @@ export function shouldUseJson(parsed, env = process.env) {
         return true;
     if (hasOption(parsed, "text"))
         return false;
-    // Auto-JSON when invoked from a harness, using the same opt-in gate as
-    // identity resolution.
+    // Auto-JSON when invoked from a harness, using the same detection as
+    // identity resolution. TT_HARNESS_EXPORT remains an explicit opt-in for
+    // ancestry-only detection where no harness env marker is present.
     const exportFlag = env.TT_HARNESS_EXPORT;
     if (exportFlag === "1" || exportFlag?.toLowerCase() === "true")
         return true;
-    if (env.TT_HARNESS_AGENT_ID?.trim())
+    if (isKnownHarnessCliEnv(env))
         return true;
     return false;
 }
@@ -119,6 +121,7 @@ Commands:
   tt whoami [--explain]
   tt list [path]
   tt join [path] [--force-new]
+  tt leave [path]
   tt wait [path] [--timeout 30s]
   tt try [path]
   tt state [path]

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, handleListCommand, handleStateCommand, handleWhoAmICommand } from "./room-commands.js";
+import { handleEventsCommand, handleJoinCommand, handleLeaveCommand, handleListCommand, handleStateCommand, handleWhoAmICommand } from "./room-commands.js";
 import { handleAssignCommand, handlePassCommand, handleReleaseCommand, handleTakeCommand, handleWaitCommand } from "./turn-commands.js";
 export const COMMAND_REGISTRY = [
     {
@@ -95,6 +95,15 @@ export const COMMAND_REGISTRY = [
         description: "Join the room for a workspace path.",
         handler: ({ runtime, parsed }) => handleJoinCommand(requireRuntime(runtime), parsed)
     },
+    {
+        name: "leave",
+        needsRuntime: true,
+        startupMaintenance: true,
+        internal: false,
+        usage: "tt leave [path]",
+        description: "Leave this agent's room membership.",
+        handler: ({ runtime, parsed }) => handleLeaveCommand(requireRuntime(runtime), parsed)
+    },
     {
         name: "state",
         needsRuntime: true,

package/dist/cli/room-commands.js

@@ -1,4 +1,6 @@
 import { deriveCliIdentity, resolveCliIdentity } from "./identity.js";
+import { removeCliSession, removeCliSessionsForRoom, resolveCliSessionPath } from "../index.js";
+import { stopGuardian } from "./guardian.js";
 import { parseOptionalInteger } from "./parser.js";
 import { formatRelativeTime, printResult } from "./output.js";
 import { resolveSessionForReads, upsertSessionFromJoin } from "./session.js";
@@ -32,6 +34,28 @@ export function handleJoinCommand(runtime, parsed) {
         return `Joined ${joined.canonical_path} as ${joined.agent_id}`;
     });
 }
+export function handleLeaveCommand(runtime, parsed) {
+    const identity = deriveCliIdentity(parsed);
+    const session = resolveSessionForReads(runtime, parsed, identity);
+    const result = runtime.commands.leaveRoom(identity, {
+        room_id: session.room_id
+    });
+    const sessionPath = resolveCliSessionPath();
+    if (result.status === "room_deleted") {
+        removeCliSessionsForRoom(sessionPath, session.room_id);
+    }
+    else {
+        removeCliSession(sessionPath, identity.agent_id, session.room_id);
+    }
+    stopGuardian(session.guardian_pid ?? null, session.guardian_process_started_at ?? null);
+    printResult(parsed, result, () => {
+        if (result.status === "room_deleted") {
+            return `Left ${session.canonical_path}; room deleted.`;
+        }
+        const memberLabel = result.remaining_members === 1 ? "member remains" : "members remain";
+        return `Left ${session.canonical_path}; ${result.remaining_members} ${memberLabel}.`;
+    });
+}
 export function handleStateCommand(runtime, parsed) {
     const identity = deriveCliIdentity(parsed);
     const session = resolveSessionForReads(runtime, parsed, identity);

package/dist/commands.js

@@ -18,6 +18,12 @@ export class TalkingStickCommands {
             process_metadata: identity.process_metadata
         });
     }
+    leaveRoom(identity, input) {
+        return this.service.leaveRoom({
+            agent_id: identity.agent_id,
+            room_id: input.room_id
+        });
+    }
     waitForTurn(identity, input) {
         return this.service.waitForTurn({
             agent_id: identity.agent_id,

package/dist/config.js

@@ -7,7 +7,8 @@ export const defaultPolicy = {
     waitForTurnMaxWaitMs: 30 * 1000,
     waitForTurnPollMs: 250,
     presenceTtlMs: 4 * 60 * 60 * 1000,
-    waiterGraceMs: 10 * 1000
+    waiterGraceMs: 10 * 1000,
+    idleRoomTtlMs: 7 * 24 * 60 * 60 * 1000
 };
 export function resolveDataDir(options = {}) {
     const env = options.env ?? process.env;

package/dist/identity.js

@@ -34,39 +34,40 @@ export function deriveHumanCliIdentity(options = {}) {
 export function deriveMcpHarnessIdentity(options = {}) {
     const env = options.env ?? process.env;
     const inspector = options.inspector ?? createSystemProcessInspector();
-    const pid = options.parentPid ?? process.ppid;
+    const parentPid = options.parentPid ?? process.ppid;
     const hostId = options.hostId ?? os.hostname();
     const username = options.username ?? safeUsername();
-    const inspection = inspector.inspect(pid);
+    const parentInspection = inspector.inspect(parentPid);
     const signal = detectHarnessSignal(env);
     if (signal) {
-        const sessionId = resolveHarnessSessionId(signal, env, pid, inspection, username, hostId);
+        const processRef = resolveSignalProcessRef(signal, parentPid, parentInspection, inspector);
+        const sessionId = resolveHarnessSessionId(signal, env, processRef.pid, processRef.inspection, username, hostId);
         const agentId = options.agentId ?? harnessAgentId(signal.harness, sessionId, hostId, username);
         return {
             agent_id: agentId,
             process_metadata: {
                 host_id: hostId,
-                pid,
-                process_started_at: inspection?.startTime ?? null,
+                pid: processRef.pid,
+                process_started_at: processRef.inspection?.startTime ?? null,
                 session_kind: "mcp_harness",
                 display_name: signal.harness
             }
         };
     }
-    const displayName = options.displayName ?? deriveCommandLabel(inspection?.command ?? null);
+    const displayName = options.displayName ?? deriveCommandLabel(parentInspection?.command ?? null);
     const agentId = options.agentId ??
         `${sanitizeIdentityComponent(displayName)}:${hashIdentityParts([
             hostId,
-            String(pid),
-            inspection?.startTime ?? "",
+            String(parentPid),
+            parentInspection?.startTime ?? "",
             options.sessionId ?? ""
         ])}`;
     return {
         agent_id: agentId,
         process_metadata: {
             host_id: hostId,
-            pid,
-            process_started_at: inspection?.startTime ?? null,
+            pid: parentPid,
+            process_started_at: parentInspection?.startTime ?? null,
             session_kind: "mcp_harness",
             display_name: displayName
         }
@@ -91,24 +92,25 @@ export function deriveHarnessCliIdentity(options = {}) {
             }
         };
     }
-    if (!isHarnessCliExportEnabled(env)) {
+    let signal = detectHarnessSignal(env);
+    if (!signal && !isHarnessCliExportEnabled(env)) {
         return null;
     }
-    let signal = detectHarnessSignal(env);
     if (!signal) {
         signal = detectHarnessViaAncestry(parentPid, inspector);
     }
     if (!signal)
         return null;
+    const processRef = resolveSignalProcessRef(signal, parentPid, parentInspection, inspector);
     const username = options.username ?? safeUsername();
-    const sessionId = resolveHarnessSessionId(signal, env, parentPid, parentInspection, username, hostId);
+    const sessionId = resolveHarnessSessionId(signal, env, processRef.pid, processRef.inspection, username, hostId);
     const agentId = options.agentId ?? harnessAgentId(signal.harness, sessionId, hostId, username);
     return {
         agent_id: agentId,
         process_metadata: {
             host_id: hostId,
-            pid: parentPid,
-            process_started_at: parentInspection?.startTime ?? null,
+            pid: processRef.pid,
+            process_started_at: processRef.inspection?.startTime ?? null,
             session_kind: "harness_cli",
             display_name: options.displayName ?? signal.harness
         }
@@ -180,7 +182,8 @@ function detectHarnessViaAncestry(pid, inspector, maxDepth = 10) {
         if (HARNESS_COMMAND_MAPPING[label]) {
             return {
                 harness: HARNESS_COMMAND_MAPPING[label],
-                sessionId: `pid:${inspection.pid}@${inspection.startTime}`
+                sessionId: `pid:${inspection.pid}@${inspection.startTime}`,
+                pidHint: null
             };
         }
         currentPid = inspection.ppid;
@@ -189,22 +192,53 @@ function detectHarnessViaAncestry(pid, inspector, maxDepth = 10) {
 }
 function detectHarnessSignal(env) {
     if (env.CLAUDECODE === "1") {
-        return { harness: "claude", sessionId: nonEmpty(env.CLAUDE_CODE_EXECPATH) };
+        return {
+            harness: "claude",
+            sessionId: null,
+            pidHint: parsePositiveInteger(env.CMUX_CLAUDE_PID)
+        };
     }
     if (env.CODEX_MANAGED_BY_NPM === "1" || nonEmpty(env.CODEX_THREAD_ID)) {
-        return { harness: "codex", sessionId: nonEmpty(env.CODEX_THREAD_ID) };
+        return {
+            harness: "codex",
+            sessionId: nonEmpty(env.CODEX_THREAD_ID),
+            pidHint: null
+        };
     }
     if (env.GEMINI_CLI === "1") {
-        return { harness: "gemini", sessionId: null };
+        return { harness: "gemini", sessionId: null, pidHint: null };
     }
     if (env.OPENCODE === "1") {
         return {
             harness: "opencode",
-            sessionId: nonEmpty(env.OPENCODE_RUN_ID) ?? nonEmpty(env.OPENCODE_PID)
+            sessionId: nonEmpty(env.OPENCODE_RUN_ID) ?? nonEmpty(env.OPENCODE_PID),
+            pidHint: null
         };
     }
     return null;
 }
+function resolveSignalProcessRef(signal, fallbackPid, fallbackInspection, inspector) {
+    if (signal.pidHint && signal.pidHint !== fallbackPid) {
+        const hintedInspection = inspector.inspect(signal.pidHint);
+        if (hintedInspection?.startTime) {
+            return {
+                pid: signal.pidHint,
+                inspection: hintedInspection
+            };
+        }
+    }
+    return {
+        pid: fallbackPid,
+        inspection: fallbackInspection
+    };
+}
+function parsePositiveInteger(value) {
+    if (!value || !/^\d+$/.test(value.trim())) {
+        return null;
+    }
+    const parsed = Number(value.trim());
+    return Number.isSafeInteger(parsed) && parsed > 0 ? parsed : null;
+}
 function nonEmpty(value) {
     return value && value.trim().length > 0 ? value : null;
 }

package/dist/index.js

@@ -8,5 +8,5 @@ export { createMcpServer, runStdioServer } from "./mcp-server.js";
 export { SUPPORTED_HARNESSES, MissingHarnessError, detectHarness, parseHarnessList, planInstall, planUninstall, resolveHarnessConfigDir, resolveOpencodeConfigDir, resolveOpencodeConfigPath, runAction, skipAction } from "./install.js";
 export { DEFAULT_SKILL_NAME, planSkillInstall, planSkillUninstall, resolveBundledSkillPath, resolveSkillTargetPath, syncInstalledSkills } from "./skill-install.js";
 export { createSystemProcessInspector, terminateKnownProcess } from "./process-utils.js";
-export { clearCliSessionLease, findCliSessionByRoom, findCliSessionForContextPath, readCliSessions, resolveCliSessionPath, upsertCliSession, upsertJoinedCliSession, writeCliSessions } from "./session-store.js";
+export { clearCliSessionLease, findCliSessionByRoom, findCliSessionForContextPath, readCliSessions, removeCliSession, removeCliSessionsForRoom, resolveCliSessionPath, upsertCliSession, upsertJoinedCliSession, writeCliSessions } from "./session-store.js";
 export { TalkingStickService, createDefaultProcessLivenessChecker } from "./service.js";

package/dist/mcp-server.js

@@ -48,6 +48,13 @@ export function createMcpServer(service = new TalkingStickService()) {
         context_path: input.context_path,
         force_new: input.force_new
     })));
+    server.registerTool("leave_room", {
+        title: "Leave Room",
+        description: "Explicitly leave a room. The room is deleted when no active members remain.",
+        inputSchema: {
+            room_id: z.string().min(1)
+        }
+    }, async (input, extra) => toolJson(() => commands.leaveRoom(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

@@ -31,6 +31,7 @@ export class TalkingStickService {
     }
     listRooms(input = {}) {
         const now = this.now();
+        this.purgeExpiredIdleRooms(now);
         if (!input.context_path) {
             const rows = this.db
                 .prepare("SELECT * FROM path_rooms ORDER BY canonical_path")
@@ -51,6 +52,7 @@ export class TalkingStickService {
         const resolved = resolveContextPath(input.context_path);
         const now = this.now();
         const timestamp = now.toISOString();
+        this.purgeExpiredIdleRooms(now);
         return withImmediateTransaction(this.db, () => {
             const roomSelection = this.findOrCreateRoomForJoin(resolved, input.force_new === true, timestamp);
             this.upsertMember(roomSelection.room.room_id, input.agent_id, timestamp, input.process_metadata);
@@ -69,9 +71,67 @@ export class TalkingStickService {
             };
         });
     }
+    leaveRoom(input) {
+        assertNonEmpty(input.agent_id, "agent_id");
+        assertNonEmpty(input.room_id, "room_id");
+        const now = this.now();
+        const timestamp = now.toISOString();
+        this.purgeExpiredIdleRooms(now);
+        return withImmediateTransaction(this.db, () => {
+            const room = this.requireRoom(input.room_id);
+            const member = this.getMember(input.room_id, input.agent_id);
+            if (!member) {
+                throw new ProtocolError("unknown_member", "Agent is not a member of this room.", { to_agent_id: input.agent_id });
+            }
+            this.db
+                .prepare("DELETE FROM room_members WHERE room_id = ? AND agent_id = ?")
+                .run(input.room_id, input.agent_id);
+            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,
+                    remaining_members: 0
+                };
+            }
+            const nextOwner = room.owner === input.agent_id ? null : room.owner;
+            const nextReservedFor = room.reserved_for === input.agent_id ? 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, room.owner === input.agent_id ? null : room.pending_handoff_event_seq, room.owner === input.agent_id ? null : room.lease_id, room.owner === input.agent_id ? null : room.lease_expires_at, room.reserved_for === input.agent_id ? null : room.claim_expires_at, nextState, timestamp, input.room_id);
+            return {
+                status: "left",
+                room_id: input.room_id,
+                canonical_path: room.canonical_path,
+                remaining_members: remainingMembers.length
+            };
+        });
+    }
     async waitForTurn(input) {
         assertNonEmpty(input.agent_id, "agent_id");
         assertNonEmpty(input.room_id, "room_id");
+        this.purgeExpiredIdleRooms(this.now());
         const maxWaitMs = input.max_wait_ms ?? this.policy.waitForTurnMaxWaitMs;
         const deadline = Date.now() + Math.max(0, maxWaitMs);
         while (true) {
@@ -88,6 +148,7 @@ export class TalkingStickService {
         const now = this.now();
         const timestamp = now.toISOString();
         const nextLeaseExpiresAt = this.expiresAt(now, this.policy.ownerLeaseTtlMs);
+        this.purgeExpiredIdleRooms(now);
         this.warmRoomTurnLiveness(input.room_id);
         return withImmediateTransaction(this.db, () => {
             const room = this.requireRoom(input.room_id);
@@ -113,6 +174,7 @@ export class TalkingStickService {
         validateHandoff(input.handoff);
         const now = this.now();
         const timestamp = now.toISOString();
+        this.purgeExpiredIdleRooms(now);
         this.warmRoomTurnLiveness(input.room_id);
         return withImmediateTransaction(this.db, () => {
             const room = this.requireRoom(input.room_id);
@@ -161,6 +223,7 @@ export class TalkingStickService {
         assertNonEmpty(input.to_agent_id, "to_agent_id");
         const now = this.now();
         const timestamp = now.toISOString();
+        this.purgeExpiredIdleRooms(now);
         this.warmRoomTurnLiveness(input.room_id);
         return withImmediateTransaction(this.db, () => {
             const room = this.requireRoom(input.room_id);
@@ -209,6 +272,7 @@ export class TalkingStickService {
         assertNonEmpty(input.reason, "reason");
         const now = this.now();
         const timestamp = now.toISOString();
+        this.purgeExpiredIdleRooms(now);
         this.warmRoomTurnLiveness(input.room_id);
         return withImmediateTransaction(this.db, () => {
             const room = this.requireRoom(input.room_id);
@@ -267,6 +331,7 @@ export class TalkingStickService {
     getRoomState(input) {
         const now = this.now();
         const timestamp = now.toISOString();
+        this.purgeExpiredIdleRooms(now);
         const room = this.requireRoom(input.room_id);
         this.touchKnownMember(input.room_id, input.agent_id, timestamp);
         const inspection = this.inspectRoom(room, now);
@@ -276,6 +341,7 @@ export class TalkingStickService {
         };
     }
     getRoomEvents(input) {
+        this.purgeExpiredIdleRooms(this.now());
         this.touchKnownMember(input.room_id, input.agent_id, this.now().toISOString());
         const afterEventSeq = input.after_event_seq ?? 0;
         const limit = Math.min(input.limit ?? 100, 500);
@@ -302,6 +368,7 @@ export class TalkingStickService {
         }
         const now = this.now();
         const timestamp = now.toISOString();
+        this.purgeExpiredIdleRooms(now);
         return withImmediateTransaction(this.db, () => {
             const room = this.requireRoom(input.room_id);
             if (room.state === "closed") {
@@ -334,6 +401,7 @@ export class TalkingStickService {
     }
     listNotes(input) {
         assertNonEmpty(input.room_id, "room_id");
+        this.purgeExpiredIdleRooms(this.now());
         this.requireRoom(input.room_id);
         this.touchKnownMember(input.room_id, input.agent_id, this.now().toISOString());
         const limit = Math.min(Math.max(input.limit ?? 50, 1), 200);
@@ -884,6 +952,40 @@ export class TalkingStickService {
             .prepare("SELECT * FROM room_events WHERE event_seq = ?")
             .get(eventSeq) ?? null);
     }
+    purgeExpiredIdleRooms(now) {
+        if (this.policy.idleRoomTtlMs <= 0) {
+            return;
+        }
+        const cutoffMs = now.getTime() - this.policy.idleRoomTtlMs;
+        withImmediateTransaction(this.db, () => {
+            const rooms = this.db
+                .prepare("SELECT * FROM path_rooms")
+                .all();
+            for (const room of rooms) {
+                const members = this.getMembers(room.room_id);
+                if (this.latestRoomActivityMs(room, members) > cutoffMs) {
+                    continue;
+                }
+                if (members.some((member) => this.isMemberActive(member, now))) {
+                    continue;
+                }
+                this.deleteRoom(room.room_id);
+            }
+        });
+    }
+    latestRoomActivityMs(room, members) {
+        let latest = parseTimestampMs(room.updated_at);
+        for (const member of members) {
+            latest = Math.max(latest, parseTimestampMs(member.joined_at), parseTimestampMs(member.last_seen_at), parseTimestampMs(member.last_wait_at));
+        }
+        return latest;
+    }
+    deleteRoom(roomId) {
+        this.db.prepare("DELETE FROM notes WHERE room_id = ?").run(roomId);
+        this.db.prepare("DELETE FROM room_events WHERE room_id = ?").run(roomId);
+        this.db.prepare("DELETE FROM room_members WHERE room_id = ?").run(roomId);
+        this.db.prepare("DELETE FROM path_rooms WHERE room_id = ?").run(roomId);
+    }
     expiresAt(now, ttlMs) {
         return new Date(now.getTime() + ttlMs).toISOString();
     }
@@ -922,9 +1024,16 @@ export class TalkingStickService {
         }
         const pendingEvent = this.getEventBySeq(room.pending_handoff_event_seq);
         const priorOwner = pendingEvent?.from_agent_id ?? null;
+        if (priorOwner === agentId &&
+            this.hasOtherRoomMember(room.room_id, agentId)) {
+            return true;
+        }
         const bestKnownMember = this.findBestFairKnownMember(room.room_id, priorOwner, now);
         return bestKnownMember !== null && bestKnownMember.agent_id !== agentId;
     }
+    hasOtherRoomMember(roomId, agentId) {
+        return this.getMembers(roomId).some((member) => member.agent_id !== agentId);
+    }
     inspectRoom(room, now) {
         const members = this.getMembers(room.room_id);
         const ownerMember = room.owner
@@ -1161,6 +1270,13 @@ function sequenceDistance(ordinal, referenceOrdinal, memberCount) {
     const distance = (ordinal - referenceOrdinal + memberCount) % memberCount;
     return distance === 0 ? memberCount : distance;
 }
+function parseTimestampMs(timestamp) {
+    if (!timestamp) {
+        return 0;
+    }
+    const parsed = Date.parse(timestamp);
+    return Number.isFinite(parsed) ? parsed : 0;
+}
 function normalizeProcessMetadata(processMetadata) {
     return {
         host_id: processMetadata?.host_id ?? null,

package/dist/session-store.js

@@ -61,6 +61,14 @@ export function clearCliSessionLease(sessionPath, agentId, roomId) {
         updated_at: new Date().toISOString()
     });
 }
+export function removeCliSession(sessionPath, agentId, roomId) {
+    const sessions = readCliSessions(sessionPath).filter((session) => !(session.agent_id === agentId && session.room_id === roomId));
+    writeCliSessions(sessionPath, sessions);
+}
+export function removeCliSessionsForRoom(sessionPath, roomId) {
+    const sessions = readCliSessions(sessionPath).filter((session) => session.room_id !== roomId);
+    writeCliSessions(sessionPath, sessions);
+}
 export function findCliSessionForContextPath(sessionPath, agentId, contextPath) {
     const resolved = resolveContextPath(contextPath);
     const candidates = readCliSessions(sessionPath).filter((session) => session.agent_id === agentId &&

package/docs/ambient-presence.md

@@ -57,9 +57,9 @@ Ambient presence needs two distinct operating modes:
 - **Participant mode** — the runtime can reliably infer or receive the harness identity that the MCP layer would use. In this mode, a spawned shell helper may join, wait, or claim on behalf of that participant.
 - **Observer mode** — the runtime cannot reliably infer the harness identity. In this mode, ambient surfaces may read room state and tail room events, but they must not join the room or represent themselves as a protocol participant.
 
-This distinction matters because `tt` is currently the human CLI. A shell process launched from inside a harness should not silently become `human:<username>` and pollute room membership. If we can cheaply export the harness identity into child shells, great; if not, observer mode is still useful and should ship first.
+This distinction matters because `tt` also serves ordinary human terminals. A shell process launched from inside a harness must not silently become `human:<username>` and pollute room membership.
 
-Current contract: CLI participant mode is explicit. A harness must set `TT_HARNESS_EXPORT=1` to let `tt` derive a harness-style identity from signals and ancestry, or `TT_HARNESS_AGENT_ID=<agent-id>` to export the exact agent id directly. Without that opt-in, `tt` remains on the human CLI path.
+Current contract: known harness environment markers such as `CLAUDECODE=1`, `CODEX_THREAD_ID`, `GEMINI_CLI=1`, or `OPENCODE=1` make `tt` derive a harness-style identity before the human fallback. `TT_HARNESS_AGENT_ID=<agent-id>` exports the exact agent id directly. `TT_HARNESS_EXPORT=1` remains available for ancestry-based detection when no known harness environment marker is present.
 
 That same rule applies to invoked shell helpers: if identity can be inferred or inherited, they may render participant-local state; if not, they should limit themselves to room-level observer status rather than pretending to be a participant.
 

package/docs/releases/0.1.0-alpha.5.md

@@ -0,0 +1,67 @@
+# Talking Stick 0.1.0-alpha.5
+
+Date: 2026-04-26
+
+Room lifecycle and licensing alpha. Talking Stick rooms are coordination state,
+not a durable history store.
+
+## Added
+
+### Explicit leave
+
+Added `leave_room` to the MCP server and `tt leave [path]` to the CLI.
+
+Leaving removes the caller's room membership. The CLI also removes the local
+session entry for that room and stops any recorded guardian process for the
+departing identity.
+
+### MIT license
+
+The package is now released under MIT:
+
+- `LICENSE` contains the MIT license text.
+- `package.json` and `package-lock.json` declare `"license": "MIT"`.
+- `README.md` links to the repository license.
+
+## Changed
+
+### Ephemeral rooms
+
+Rooms are physically deleted once no active members remain. This includes the
+simple last-member case and the case where explicit leave removes the only
+recently-active participant while stale member rows remain.
+
+Long-idle rooms are also purged opportunistically when the service is invoked.
+The default idle retention is seven days.
+
+### Take-back delay
+
+If `release_stick` leaves a handoff idle because no peer is currently waiting,
+the prior owner can no longer immediately reclaim while another room member
+exists. The existing `policy.waiterGraceMs` window now acts as a minimum
+take-back delay so a slower peer has a chance to poll first.
+
+## Fixed
+
+### Harness-launched CLI identity
+
+`tt` now checks known harness environment markers before falling back to the
+human CLI identity. A Claude Code shell with `CLAUDECODE=1`, for example,
+resolves to a `claude:*` identity without requiring `TT_HARNESS_EXPORT=1`.
+
+`TT_HARNESS_EXPORT=1` remains available for ancestry-based detection when no
+known harness environment marker is present, and `TT_HARNESS_AGENT_ID` still
+exports an exact agent id directly.
+
+For Claude sessions, `CMUX_CLAUDE_PID` is treated only as an optional process
+hint after `CLAUDECODE=1` has already identified the shell as Claude. It is not
+a harness signal by itself.
+
+## Verification
+
+- `npm run typecheck`
+- `npm test` — 204 tests across 14 files
+- `npm run build`
+- `node dist/cli.js --help`
+- `git diff --check`
+- `npm pack --dry-run`

package/docs/talking-stick-plan.md

@@ -80,7 +80,7 @@ Derivation signals, in order of preference:
 
 1. `clientInfo.name` and `clientInfo.version` from the MCP `initialize` handshake. Every MCP client sends these; Claude Code, Codex, and Gemini CLI all set distinctive values.
 2. The MCP server's own parent process identity: `(parent_pid, parent_start_time)`. Together these uniquely identify the harness instance on a host. `parent_pid` alone is unsafe because PIDs are reused after exit.
-3. Environment variables the harness exports, such as `CLAUDECODE`, `CLAUDE_CODE_ENTRYPOINT`, `TERM_PROGRAM`, `ITERM_SESSION_ID`, `TMUX`, `SSH_TTY`.
+3. Environment variables the harness exports, such as `CLAUDECODE`, `CODEX_THREAD_ID`, `GEMINI_CLI`, `OPENCODE`, `TERM_PROGRAM`, `ITERM_SESSION_ID`, `TMUX`, `SSH_TTY`.
 
 Composed identity, stable for the life of one harness instance:
 
@@ -98,7 +98,7 @@ The hash is a short digest over the signals above, so reconnects from the same h
 For the Human CLI (see deferred extension), the same idea applies with different signals: `$USER`, parent shell `(pid, start_time)`, and tty yield identities like:
 
 ```text
-human:wojtek:s003
+human:alice:s003
 ```
 
 The derived string is the protocol-facing identity, but the server must also persist the source liveness facts behind it:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "talking-stick",
-  "version": "0.1.0-alpha.4",
+  "version": "0.1.0-alpha.5",
   "description": "MCP coordination server for path-scoped agent handoffs.",
   "type": "module",
   "bin": {
@@ -36,5 +36,5 @@
   "engines": {
     "node": ">=22"
   },
-  "license": "UNLICENSED"
+  "license": "MIT"
 }

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`, `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`, `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,7 +26,7 @@ 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 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 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.
 
@@ -176,11 +176,14 @@ Exit the wait loop only when one of these is true:
 
 In every other case: after `release_stick` or `pass_stick`, go straight back into the wait loop (ideally backgrounded — see §4).
 
+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.
+
 ## 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
 - `get_room_state`: authoritative current room projection
 - `get_room_events`: replay recent claims, releases, passes, and takeovers