talking-stick 0.4.3 → 0.4.5

package/README.md

@@ -230,7 +230,7 @@ Use `tt whoami --explain` to see which identity path the CLI chose.
 - **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.
+- **Ephemeral rooms.** `leave_room`/`tt leave` removes membership, rooms with no active members are physically deleted, and long-idle rooms with no recent activity or provably live member process are purged opportunistically on later invocations. The default idle retention is seven days.
 - **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.
@@ -258,6 +258,11 @@ npm run build
 
 See [`CHANGELOG.md`](CHANGELOG.md) for a per-version summary; full release notes live in [`docs/releases/`](docs/releases/).
 
+When cutting a release, add entries under `CHANGELOG.md`'s `Unreleased` section,
+then run `npm version <new-version>`. The version lifecycle script moves those
+entries into the new version section, writes `docs/releases/<version>.md`, and
+adds the GitHub release link before npm commits and tags the version.
+
 ## Read next
 
 - [`docs/talking-stick-plan.md`](docs/talking-stick-plan.md) — full protocol, state transitions, persistence model, design rationale, and open questions.

package/dist/cli/guardian.js

@@ -3,17 +3,24 @@ import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { createSystemProcessInspector, deriveHumanCliIdentity, isProtocolError, terminateKnownProcess } from "../index.js";
-import { parseRequiredInteger, requireStringOption } from "./parser.js";
+import { getStringOption, parseRequiredInteger, requireStringOption } from "./parser.js";
 import { createRuntime } from "./runtime.js";
 const GUARD_READY = "READY";
 const GUARD_READY_TIMEOUT_MS = 10_000;
 const STALE_GUARD_ERRORS = new Set(["stale_lease", "turn_mismatch", "room_not_found"]);
 export async function runGuardCommand(parsed) {
-    const identity = deriveHumanCliIdentity({
+    const baseIdentity = deriveHumanCliIdentity({
         agentId: requireStringOption(parsed, "agent"),
         displayName: requireStringOption(parsed, "agent").replace(/^human:/, ""),
         sessionKind: "human_guardian"
     });
+    const identity = {
+        ...baseIdentity,
+        process_metadata: {
+            ...baseIdentity.process_metadata,
+            ...parseHarnessMetadataOptions(parsed)
+        }
+    };
     const runtime = createRuntime();
     try {
         const joined = runtime.commands.joinPath(identity, {
@@ -51,6 +58,7 @@ export async function runGuardCommand(parsed) {
 }
 export async function spawnGuardian(input) {
     const self = resolveSelfSpawn(input.cliEntryUrl);
+    const harnessArgs = serializeHarnessMetadataOptions(input.processMetadata);
     const child = spawn(self.command, [
         ...self.args,
         "guard",
@@ -63,7 +71,8 @@ export async function spawnGuardian(input) {
         "--lease-id",
         input.leaseId,
         "--turn-id",
-        String(input.turnId)
+        String(input.turnId),
+        ...harnessArgs
     ], {
         detached: true,
         stdio: ["ignore", "pipe", "pipe"],
@@ -105,6 +114,33 @@ export async function spawnGuardian(input) {
         });
     });
 }
+function parseHarnessMetadataOptions(parsed) {
+    const harnessPid = getStringOption(parsed, "harness-pid");
+    return {
+        harness_name: getStringOption(parsed, "harness-name") ?? null,
+        harness_session_id: getStringOption(parsed, "harness-session-id") ?? null,
+        harness_host_id: getStringOption(parsed, "harness-host-id") ?? null,
+        harness_pid: harnessPid ? Number.parseInt(harnessPid, 10) : null,
+        harness_process_started_at: getStringOption(parsed, "harness-process-started-at") ?? null
+    };
+}
+function serializeHarnessMetadataOptions(metadata) {
+    const args = [];
+    appendOption(args, "harness-name", metadata?.harness_name);
+    appendOption(args, "harness-session-id", metadata?.harness_session_id);
+    appendOption(args, "harness-host-id", metadata?.harness_host_id);
+    appendOption(args, "harness-pid", metadata?.harness_pid === null || metadata?.harness_pid === undefined
+        ? null
+        : String(metadata.harness_pid));
+    appendOption(args, "harness-process-started-at", metadata?.harness_process_started_at);
+    return args;
+}
+function appendOption(args, key, value) {
+    if (!value) {
+        return;
+    }
+    args.push(`--${key}`, value);
+}
 function resolveSelfSpawn(cliEntryUrl) {
     const scriptPath = fileURLToPath(cliEntryUrl);
     if (scriptPath.endsWith(".ts")) {

package/dist/cli/output.js

@@ -61,7 +61,7 @@ export function formatWaitResult(result) {
                 return `Not your turn — turn ${result.turn_id ?? "?"} is reserved for ${result.reserved_for}${deadline}.`;
             }
             if (result.reason === "auto_claim_disabled") {
-                return "Parked — auto-claim disabled; idle room left untouched.";
+                return result.hint ?? "Parked — idle room left unclaimed.";
             }
             return "Not your turn yet.";
         }

package/dist/cli/turn-commands.js

@@ -34,7 +34,8 @@ export async function handleWaitCommand(runtime, parsed, isTry, cliEntryUrl) {
                     roomId: joined.room_id,
                     leaseId: waitResult.lease_id,
                     turnId: waitResult.turn_id,
-                    cliEntryUrl
+                    cliEntryUrl,
+                    processMetadata: identity.process_metadata
                 });
                 upsertCliSession(sessionPath, {
                     agent_id: identity.agent_id,
@@ -71,7 +72,8 @@ export async function handleWaitCommand(runtime, parsed, isTry, cliEntryUrl) {
             roomId: joined.room_id,
             leaseId: waitResult.lease_id,
             turnId: waitResult.turn_id,
-            cliEntryUrl
+            cliEntryUrl,
+            processMetadata: identity.process_metadata
         });
         upsertCliSession(resolveCliSessionPath(), {
             agent_id: identity.agent_id,
@@ -110,7 +112,8 @@ export async function handleTakeCommand(runtime, parsed, cliEntryUrl) {
             roomId: joined.room_id,
             leaseId: availability.lease_id,
             turnId: availability.turn_id,
-            cliEntryUrl
+            cliEntryUrl,
+            processMetadata: identity.process_metadata
         });
         upsertCliSession(resolveCliSessionPath(), {
             agent_id: identity.agent_id,
@@ -144,7 +147,8 @@ export async function handleTakeCommand(runtime, parsed, cliEntryUrl) {
         roomId: joined.room_id,
         leaseId: result.lease_id,
         turnId: result.turn_id,
-        cliEntryUrl
+        cliEntryUrl,
+        processMetadata: identity.process_metadata
     });
     upsertCliSession(resolveCliSessionPath(), {
         agent_id: identity.agent_id,

package/dist/db.js

@@ -103,6 +103,17 @@ const migrations = [
         up: `
       ALTER TABLE room_events ADD COLUMN payload_json TEXT;
     `
+    },
+    {
+        id: 6,
+        name: "room_member_harness_instance_metadata",
+        up: `
+      ALTER TABLE room_members ADD COLUMN harness_name TEXT;
+      ALTER TABLE room_members ADD COLUMN harness_session_id TEXT;
+      ALTER TABLE room_members ADD COLUMN harness_host_id TEXT;
+      ALTER TABLE room_members ADD COLUMN harness_pid INTEGER;
+      ALTER TABLE room_members ADD COLUMN harness_process_started_at TEXT;
+    `
     }
 ];
 export function resolveDatabasePath(options = {}) {

package/dist/identity.js

@@ -42,6 +42,7 @@ export function deriveMcpHarnessIdentity(options = {}) {
     if (signal) {
         const processRef = resolveSignalProcessRef(signal, parentPid, parentInspection, inspector);
         const sessionId = resolveHarnessSessionId(signal, env, processRef.pid, processRef.inspection, username, hostId, inspector);
+        const harnessProcess = resolveHarnessProcessRef(signal, processRef, inspector);
         const agentId = options.agentId ?? harnessAgentId(signal.harness, sessionId, hostId, username);
         return {
             agent_id: agentId,
@@ -50,7 +51,12 @@ export function deriveMcpHarnessIdentity(options = {}) {
                 pid: processRef.pid,
                 process_started_at: processRef.inspection?.startTime ?? null,
                 session_kind: "mcp_harness",
-                display_name: signal.harness
+                display_name: signal.harness,
+                harness_name: signal.harness,
+                harness_session_id: sessionId,
+                harness_host_id: hostId,
+                harness_pid: harnessProcess.pid,
+                harness_process_started_at: harnessProcess.startTime
             }
         };
     }
@@ -105,6 +111,7 @@ export function deriveHarnessCliIdentity(options = {}) {
     const username = options.username ?? safeUsername();
     const sessionId = resolveHarnessSessionId(signal, env, processRef.pid, processRef.inspection, username, hostId, inspector);
     const agentId = options.agentId ?? harnessAgentId(signal.harness, sessionId, hostId, username);
+    const harnessProcess = resolveHarnessProcessRef(signal, processRef, inspector);
     return {
         agent_id: agentId,
         process_metadata: {
@@ -112,7 +119,12 @@ export function deriveHarnessCliIdentity(options = {}) {
             pid: processRef.pid,
             process_started_at: processRef.inspection?.startTime ?? null,
             session_kind: "harness_cli",
-            display_name: options.displayName ?? signal.harness
+            display_name: options.displayName ?? signal.harness,
+            harness_name: signal.harness,
+            harness_session_id: sessionId,
+            harness_host_id: hostId,
+            harness_pid: harnessProcess.pid,
+            harness_process_started_at: harnessProcess.startTime
         }
     };
 }
@@ -139,6 +151,16 @@ function resolveHarnessSessionId(signal, env, parentPid, parentInspection, usern
     }
     return `userhost:${sanitizeIdentityComponent(username)}@${hostId}`;
 }
+function resolveHarnessProcessRef(signal, processRef, inspector) {
+    const harnessRoot = findHarnessRootInAncestry(signal.harness, processRef.pid, processRef.inspection, inspector);
+    if (harnessRoot) {
+        return harnessRoot;
+    }
+    return {
+        pid: processRef.pid,
+        startTime: processRef.inspection?.startTime ?? null
+    };
+}
 // 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

package/dist/instructions.js

@@ -6,7 +6,7 @@ import { resolveContextPath } from "./path-resolution.js";
 export const DEFAULT_MAX_INSTRUCTION_FILE_BYTES = 256 * 1024;
 export const DEFAULT_INSTRUCTIONS_MARKDOWN = `# Talking Stick collaboration instructions
 
-Keep using Talking Stick until the shared task is done. After releasing or handing off, re-enter the wait loop by default. Prefer continued action unless the task is complete or the operator explicitly redirects or stops the room. If you are the only active member of the room, stop polling after a clear handoff rather than churning release/reclaim turns. If you have no expected work and are blocked on operator input or an external signal, use \`tt wait --park --json\` so you stay coordinated without auto-claiming idle turns.
+Keep using Talking Stick until the shared task is done. After releasing or handing off, re-enter the wait loop by default. Prefer continued action unless the task is complete or the operator explicitly redirects or stops the room. If a handoff, message, or operator instruction leaves review, release, or other work pending, use normal \`tt wait --json\`; do not park. Use \`tt wait --park --json\` only for passive standby when no task is pending and you are blocked on operator input or an external signal.
 
 On freshly invoked multi-agent tasks, give peers a short window to join before deciding you are alone. Use a normal wait timeout or spend about a minute on read-only repo orientation while other harnesses appear.
 

package/dist/service.js

@@ -15,6 +15,7 @@ const KNOWN_EVENT_TYPES = [
     "takeover",
     "close",
     "kick",
+    "session_superseded",
     "message_sent"
 ];
 export class TalkingStickService {
@@ -66,7 +67,11 @@ export class TalkingStickService {
         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);
+            const supersededAgentIds = this.retireSupersededHarnessSessions(roomSelection.room.room_id, input.agent_id, normalizeProcessMetadata(input.process_metadata), timestamp);
             const freshRoom = this.requireRoom(roomSelection.room.room_id);
+            const warning = joinWarnings(roomSelection.warning, supersededAgentIds.length > 0
+                ? `Superseded previous harness session(s): ${supersededAgentIds.join(", ")}.`
+                : undefined);
             return {
                 agent_id: input.agent_id,
                 room_id: freshRoom.room_id,
@@ -74,7 +79,7 @@ export class TalkingStickService {
                 requested_path: resolved.requested_path,
                 workspace_root: resolved.workspace_root,
                 joined_existing_room: roomSelection.joinedExistingRoom,
-                warning: roomSelection.warning,
+                warning,
                 policy: { ...this.policy },
                 room_state: this.mapRoom(this.inspectRoom(freshRoom, now), now),
                 handoff_template: handoffTemplate()
@@ -233,7 +238,9 @@ export class TalkingStickService {
         while (true) {
             this.warmRoomTurnLiveness(input.room_id);
             const result = withImmediateTransaction(this.db, () => this.waitForTurnOnce(input));
-            if (result.status !== "not_yet" || Date.now() >= deadline) {
+            if (result.status !== "not_yet" ||
+                result.reason === "auto_claim_disabled" ||
+                Date.now() >= deadline) {
                 return result;
             }
             const remainingMs = deadline - Date.now();
@@ -666,7 +673,8 @@ export class TalkingStickService {
                     reserved_for: room.reserved_for ?? undefined,
                     lease_expires_at: room.lease_expires_at ?? undefined,
                     claim_expires_at: room.claim_expires_at ?? undefined,
-                    reason: "auto_claim_disabled"
+                    reason: "auto_claim_disabled",
+                    hint: "Idle room left unclaimed because park mode disables auto-claim. If work is pending, run `tt wait --json` or ask for an explicit assignment."
                 };
             }
             if (this.shouldDeferIdleClaim(room, input.agent_id, now)) {
@@ -855,10 +863,15 @@ export class TalkingStickService {
               pid = ?,
               process_started_at = ?,
               session_kind = ?,
-              display_name = ?
+              display_name = ?,
+              harness_name = ?,
+              harness_session_id = ?,
+              harness_host_id = ?,
+              harness_pid = ?,
+              harness_process_started_at = ?
           WHERE room_id = ? AND agent_id = ?
         `)
-                .run(timestamp, timestamp, mergedMetadata.host_id, mergedMetadata.pid, mergedMetadata.process_started_at, mergedMetadata.session_kind, mergedMetadata.display_name, roomId, agentId);
+                .run(timestamp, timestamp, mergedMetadata.host_id, mergedMetadata.pid, mergedMetadata.process_started_at, mergedMetadata.session_kind, mergedMetadata.display_name, mergedMetadata.harness_name, mergedMetadata.harness_session_id, mergedMetadata.harness_host_id, mergedMetadata.harness_pid, mergedMetadata.harness_process_started_at, roomId, agentId);
             return;
         }
         const nextOrdinal = this.db
@@ -878,11 +891,16 @@ export class TalkingStickService {
           pid,
           process_started_at,
           session_kind,
-          display_name
+          display_name,
+          harness_name,
+          harness_session_id,
+          harness_host_id,
+          harness_pid,
+          harness_process_started_at
         )
-        VALUES (?, ?, ?, ?, ?, ?, 'active', ?, ?, ?, ?, ?)
+        VALUES (?, ?, ?, ?, ?, ?, 'active', ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
       `)
-            .run(roomId, agentId, nextOrdinal, timestamp, timestamp, timestamp, normalizedMetadata.host_id, normalizedMetadata.pid, normalizedMetadata.process_started_at, normalizedMetadata.session_kind, normalizedMetadata.display_name);
+            .run(roomId, agentId, nextOrdinal, timestamp, timestamp, timestamp, normalizedMetadata.host_id, normalizedMetadata.pid, normalizedMetadata.process_started_at, normalizedMetadata.session_kind, normalizedMetadata.display_name, normalizedMetadata.harness_name, normalizedMetadata.harness_session_id, normalizedMetadata.harness_host_id, normalizedMetadata.harness_pid, normalizedMetadata.harness_process_started_at);
     }
     mergeMemberProcessMetadata(room, existing, incoming) {
         if (!this.shouldPreserveExactMemberProcessMetadata(room, existing, incoming)) {
@@ -893,9 +911,76 @@ export class TalkingStickService {
             pid: existing.pid,
             process_started_at: existing.process_started_at,
             session_kind: existing.session_kind,
-            display_name: existing.display_name
+            display_name: existing.display_name,
+            harness_name: existing.harness_name,
+            harness_session_id: existing.harness_session_id,
+            harness_host_id: existing.harness_host_id,
+            harness_pid: existing.harness_pid,
+            harness_process_started_at: existing.harness_process_started_at
         };
     }
+    retireSupersededHarnessSessions(roomId, incomingAgentId, incomingMetadata, timestamp) {
+        if (!hasHarnessInstanceIdentity(incomingMetadata)) {
+            return [];
+        }
+        const room = this.requireRoom(roomId);
+        const targetAgentIds = [...new Set([room.owner, room.reserved_for])].filter((agentId) => agentId !== null && agentId !== incomingAgentId);
+        const supersededAgentIds = [];
+        for (const targetAgentId of targetAgentIds) {
+            const target = this.getMember(roomId, targetAgentId);
+            if (!target ||
+                !isSupersededHarnessInstance(target, incomingMetadata)) {
+                continue;
+            }
+            supersededAgentIds.push(targetAgentId);
+            this.db
+                .prepare("DELETE FROM room_members WHERE room_id = ? AND agent_id = ?")
+                .run(roomId, targetAgentId);
+            this.appendEvent({
+                room_id: roomId,
+                turn_id: room.turn_id,
+                event_type: "session_superseded",
+                from_agent_id: incomingAgentId,
+                to_agent_id: targetAgentId,
+                handoff: null,
+                reason: `superseded by newer ${incomingMetadata.harness_name} session from the same harness process`,
+                created_at: timestamp
+            });
+        }
+        if (supersededAgentIds.length === 0) {
+            return [];
+        }
+        const ownerSuperseded = room.owner
+            ? supersededAgentIds.includes(room.owner)
+            : false;
+        const recipientSuperseded = room.reserved_for
+            ? supersededAgentIds.includes(room.reserved_for)
+            : false;
+        const nextOwner = ownerSuperseded ? null : room.owner;
+        const nextReservedFor = recipientSuperseded ? 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, ownerSuperseded ? null : room.pending_handoff_event_seq, ownerSuperseded ? null : room.lease_id, ownerSuperseded ? null : room.lease_expires_at, recipientSuperseded ? null : room.claim_expires_at, nextState, timestamp, roomId);
+        return supersededAgentIds;
+    }
     shouldPreserveExactMemberProcessMetadata(room, existing, incoming) {
         const isCurrentHolderOrRecipient = room.owner === existing.agent_id || room.reserved_for === existing.agent_id;
         if (!isCurrentHolderOrRecipient) {
@@ -1207,7 +1292,7 @@ export class TalkingStickService {
                 if (this.latestRoomActivityMs(room, members) > cutoffMs) {
                     continue;
                 }
-                if (members.some((member) => this.isMemberActive(member, now))) {
+                if (members.some((member) => this.shouldRetainIdleRoom(member, now))) {
                     continue;
                 }
                 this.deleteRoom(room.room_id);
@@ -1239,6 +1324,16 @@ export class TalkingStickService {
         }
         return this.hasRecentPresence(member, now);
     }
+    shouldRetainIdleRoom(member, now) {
+        const liveness = this.getMemberProcessLiveness(member);
+        if (liveness === "alive") {
+            return true;
+        }
+        if (liveness === "gone") {
+            return false;
+        }
+        return this.hasRecentPresence(member, now);
+    }
     hasRecentPresence(member, now) {
         return (now.getTime() - Date.parse(member.last_seen_at) <=
             this.policy.presenceTtlMs);
@@ -1429,7 +1524,12 @@ export class TalkingStickService {
             pid: member.pid,
             process_started_at: member.process_started_at,
             session_kind: member.session_kind,
-            display_name: member.display_name
+            display_name: member.display_name,
+            harness_name: member.harness_name,
+            harness_session_id: member.harness_session_id,
+            harness_host_id: member.harness_host_id,
+            harness_pid: member.harness_pid,
+            harness_process_started_at: member.harness_process_started_at
         });
     }
     goneGraceMs() {
@@ -1532,7 +1632,12 @@ function normalizeProcessMetadata(processMetadata) {
         pid: processMetadata?.pid ?? null,
         process_started_at: processMetadata?.process_started_at ?? null,
         session_kind: processMetadata?.session_kind ?? "mcp_harness",
-        display_name: processMetadata?.display_name ?? null
+        display_name: processMetadata?.display_name ?? null,
+        harness_name: processMetadata?.harness_name ?? null,
+        harness_session_id: processMetadata?.harness_session_id ?? null,
+        harness_host_id: processMetadata?.harness_host_id ?? null,
+        harness_pid: processMetadata?.harness_pid ?? null,
+        harness_process_started_at: processMetadata?.harness_process_started_at ?? null
     };
 }
 export function createDefaultProcessLivenessChecker(currentHostId, injectedInspector) {
@@ -1542,7 +1647,9 @@ export function createDefaultProcessLivenessChecker(currentHostId, injectedInspe
     const inspector = injectedInspector ?? createSystemProcessInspector({ cacheTtlMs: 1_000 });
     return (metadata) => {
         if (metadata.pid === null ||
+            metadata.pid === undefined ||
             metadata.process_started_at === null ||
+            metadata.process_started_at === undefined ||
             metadata.process_started_at.trim() === "") {
             return "unknown";
         }
@@ -1576,6 +1683,34 @@ function hasExactProcessIdentity(metadata) {
         metadata.process_started_at !== undefined &&
         metadata.process_started_at.trim() !== "");
 }
+function hasHarnessInstanceIdentity(metadata) {
+    return (metadata.harness_name !== null &&
+        metadata.harness_name !== undefined &&
+        metadata.harness_name.trim() !== "" &&
+        metadata.harness_session_id !== null &&
+        metadata.harness_session_id !== undefined &&
+        metadata.harness_session_id.trim() !== "" &&
+        metadata.harness_pid !== null &&
+        metadata.harness_pid !== undefined &&
+        metadata.harness_process_started_at !== null &&
+        metadata.harness_process_started_at !== undefined &&
+        metadata.harness_process_started_at.trim() !== "");
+}
+function isSupersededHarnessInstance(existing, incoming) {
+    if (!hasHarnessInstanceIdentity(existing) || !hasHarnessInstanceIdentity(incoming)) {
+        return false;
+    }
+    return (existing.harness_name === incoming.harness_name &&
+        existing.harness_host_id === incoming.harness_host_id &&
+        existing.harness_pid === incoming.harness_pid &&
+        existing.harness_process_started_at ===
+            incoming.harness_process_started_at &&
+        existing.harness_session_id !== incoming.harness_session_id);
+}
+function joinWarnings(...warnings) {
+    const present = warnings.filter((warning) => Boolean(warning?.trim()));
+    return present.length > 0 ? present.join(" ") : undefined;
+}
 function sessionKindPriority(sessionKind) {
     switch (sessionKind) {
         case "human_guardian":

package/docs/plans/2026-05-12-zombie-session-eviction.md

@@ -0,0 +1,157 @@
+# Zombie Session Eviction (`/clear` Stale Stick Fix)
+
+## Problem
+
+When a harness like Codex or Claude Code runs `/clear`, the in-process
+session resets but the host harness process keeps running. The room sees:
+
+- old `agent_id` (derived from the prior `CODEX_THREAD_ID` /
+  `CLAUDE_CODE_SESSION_ID`) still listed as owner or recipient
+- liveness check via the stored `(pid, process_started_at)` still reports
+  "alive" — because the harness process is in fact alive
+- new session joins with a different `agent_id`, sees the room owned, and
+  has no way to make progress
+
+The old session can never reply (its thread is gone), so the room is
+permanently stuck until an operator forces a takeover.
+
+## Predicate
+
+A member M in a room is **superseded** when, on `tt join` by a new member
+M', all of the following hold:
+
+- `M.harness_name == M'.harness_name`
+- `M.harness_host_id == M'.harness_host_id`
+- `M.harness_pid == M'.harness_pid`
+- `M.harness_process_started_at == M'.harness_process_started_at`
+- `M.harness_session_id != M'.harness_session_id`
+- both members have non-null harness-instance metadata (legacy rows with
+  NULL fields are skipped — safe migration)
+- M is currently the room owner or reserved recipient
+
+Non-owner, non-reserved members are not evaluated. They are harmless
+(they cannot block coordination) and age out through the existing
+presence TTL.
+
+## Identity Capture
+
+`(harness_pid, harness_process_started_at)` is the **harness root**
+process identity — the user-launched Codex/Claude process, not any
+guardian subprocess or the current MCP child. Codex and Claude both keep
+this process alive across `/clear`, so it is the durable fingerprint.
+
+`identity.ts` walks the process ancestry from the `tt` invocation back to
+the deepest ancestor whose command matches a known harness name and
+records that process's PID + start time as the harness root. The current
+in-process session id (`CODEX_THREAD_ID`, `CLAUDE_CODE_SESSION_ID`, or
+the ancestry-derived fallback) is recorded as `harness_session_id`.
+
+These fields are written to `room_members` on join. They are independent
+from the existing `pid` / `process_started_at` columns, which continue
+to track the *currently active* process (initially the harness, later
+the guardian once `tt wait` succeeds).
+
+## Schema
+
+Migration 6 (`src/db.ts`) adds five nullable columns to `room_members`:
+
+- `harness_name TEXT`
+- `harness_session_id TEXT`
+- `harness_host_id TEXT`
+- `harness_pid INTEGER`
+- `harness_process_started_at TEXT`
+
+All columns are nullable so the migration is safe for existing rows.
+Rows with NULL fields are excluded from the supersession predicate.
+
+## Guardian Propagation
+
+`tt wait` and `tt take` spawn a `tt guard` subprocess that holds the
+lease and rejoins the room with `session_kind: human_guardian`. The
+guardian must carry forward the original harness-instance fields, not
+its own (it is not a harness). This is done by passing
+`--harness-name`, `--harness-session-id`, `--harness-host-id`,
+`--harness-pid`, and `--harness-process-started-at` to `tt guard` on
+spawn. The guardian merges them into its derived identity before
+rejoining.
+
+The result: the member row's `pid` / `process_started_at` columns get
+overwritten with the guardian's process (correct for liveness), but the
+`harness_*` columns stay pinned to the original harness root.
+
+## Eviction Action
+
+On a qualifying join, in one transaction:
+
+1. `DELETE FROM room_members WHERE room_id = ? AND agent_id = ?` for each
+   superseded member.
+2. Append a `session_superseded` event with
+   `from_agent_id = incoming`, `to_agent_id = superseded`, and a reason
+   string identifying the harness.
+3. If the superseded member was the room owner, clear
+   `owner`, `lease_id`, `lease_expires_at`, and
+   `pending_handoff_event_seq`.
+4. If the superseded member was the reserved recipient, clear
+   `reserved_for` and `claim_expires_at`. **Preserve**
+   `pending_handoff_event_seq` so the next claimant still receives the
+   original handoff.
+5. Recompute `state` to `owned`, `reserved`, `idle`, or `closed` as
+   appropriate.
+
+The `joinPath` response includes a `warning` listing the superseded
+agent ids.
+
+## Event Type Choice: `session_superseded`
+
+A new event type rather than reusing `kick`. Rationale:
+
+- `kick` is operator-coded — humans reading `tt events` interpret a kick
+  as an explicit intervention.
+- A supersession is automatic, not operator-driven, and never blocks the
+  new session.
+- A dedicated type lets skill text instruct harnesses to treat it as
+  informational, distinct from `takeover_available`.
+
+The CLI's default event formatter renders `session_superseded` the same
+way as any other event (timestamp, type, from→to, reason) — no special
+display logic needed.
+
+## What Stays Out
+
+- No notification to the old session before eviction. By construction
+  the old session cannot read or reply.
+- No silent retention of a deactivated member row. The append-only event
+  log is the audit record; member rows are operational state.
+- No change to `tt take` / `takeover_available` semantics. The
+  supersession path runs strictly on `tt join`, before any takeover
+  decision.
+- No change to plain human sessions. A `human_guardian` row is only
+  subject to supersession when it carries harness-instance metadata from
+  a harness-launched guardian; standalone human CLI rows have NULL
+  harness fields and are skipped.
+
+## Tests
+
+`tests/talking-stick.test.ts` covers:
+
+1. **Owner supersession.** Same-process new session joins, prior owner
+   is deleted, `session_superseded` event recorded, room returns to
+   `idle`, new session's `tt wait` immediately grants the turn with
+   `reason: open_claim`.
+2. **Different-process non-supersession.** A different Codex process
+   joins; the existing owner is untouched; the new joiner gets
+   `not_yet` and sees the original owner.
+3. **Recipient supersession preserves handoff.** Prior recipient is
+   evicted, but the handoff event remains pending; the new session's
+   `tt wait` returns `reason: sequence` with the original handoff
+   intact.
+
+## Open Questions
+
+None blocking. Possible follow-ups:
+
+- Surface superseded events in `tt state --json` as a recent-history
+  field for operators inspecting why ownership changed.
+- Consider supersession during `tt wait` as a defensive sweep (currently
+  join-only; depends on whether real-world failure modes show join
+  being skipped).

package/docs/releases/0.4.4.md

@@ -0,0 +1,23 @@
+# Talking Stick 0.4.4
+
+Date: 2026-05-12
+
+## Added
+- **Automatic release prep.** `npm version <new-version>` now runs `scripts/prepare-release.mjs`, moving `CHANGELOG.md`'s `Unreleased` entries into the new version section, creating `docs/releases/<version>.md`, and adding the GitHub release link before npm creates the version commit/tag.
+
+## Changed
+- **Ambient receiver guidance.** The shipped skill now says to run exactly one streaming ambient receiver per session, and warns that exit-notify background commands silently swallow `tt events --follow` output instead of surfacing mid-task events.
+
+## Fixed
+- **Idle-room retention.** Opportunistic cleanup still deletes long-idle rooms after the seven-day default retention, but it now preserves a room when any recorded member process is provably still alive. Once no member is recently active or live, the same cleanup path removes the room and its member, event, and note rows.
+
+## Verification
+
+```bash
+npm run typecheck
+npm test
+npm run build
+node dist/cli.js --help
+git diff --check
+npm pack --dry-run
+```

package/docs/releases/0.4.5.md

@@ -0,0 +1,22 @@
+# Talking Stick 0.4.5
+
+Date: 2026-05-12
+
+## Added
+- **Harness-instance member metadata.** New nullable columns on `room_members` (`harness_name`, `harness_session_id`, `harness_host_id`, `harness_pid`, `harness_process_started_at`) track the root harness process and the in-process session id independently of the row's current liveness fields. Identity resolution walks the process ancestry to populate them; `tt guard` carries them forward on spawn so guardian rejoins do not clobber them.
+- **`session_superseded` event type.** Emitted when `tt join` detects that the room's owner or reserved recipient comes from the same harness process but a different in-process session (the `/clear` case). The superseded member row is deleted, owner/reservation/lease state is cleared as appropriate, and pending recipient handoffs are preserved for the next claimant. Legacy member rows with NULL harness-instance fields are skipped, so the migration is safe.
+
+## Fixed
+- **`/clear` no longer leaves a permanent stale stick holder.** When a harness like Codex or Claude Code resets its in-process session (e.g. `/clear`) while still holding or being reserved for the stick, the next `tt join` from the new in-process session evicts the prior agent and clears the lease so the new session can proceed. Previously the room stayed stuck until an operator forced a takeover.
+- **Park mode no longer looks like active pending work.** `tt wait --park` now returns immediately when the room is idle and unreserved, with a JSON hint telling agents to use normal `tt wait --json` when a handoff or operator instruction leaves review/release work pending. The bundled instructions now reserve park mode for true passive standby.
+
+## Verification
+
+```bash
+npm run typecheck
+npm test
+npm run build
+node dist/cli.js --help
+git diff --check
+npm pack --dry-run
+```

package/docs/talking-stick-plan.md

@@ -747,6 +747,7 @@ wait_for_turn_poll_ms      = 250;                  // transport polling cadence
 wait_for_events_max_wait_ms = 110 * 1000;          // 110 seconds
 presence_ttl_ms            =  4 * 60 * 60 * 1000;  // 4 hours
 waiter_grace_ms            = 10 * 1000;            // 10 seconds
+idle_room_ttl_ms           =  7 * 24 * 60 * 60 * 1000; // 7 days
 ```
 
 Timeout meanings:
@@ -757,6 +758,7 @@ Timeout meanings:
 - `owner_lease_ttl` is how long an owner may remain silent before takeover becomes possible.
 - `presence_ttl` determines whether a member is active for sequence selection and takeover eligibility.
 - `waiter_grace_ms` is the short window used to identify recent waiters and to avoid immediately recycling the turn while a fairer known member is between wait polls.
+- `idle_room_ttl` is the retention window for dormant coordination history. Opportunistic cleanup only purges a long-idle room when no member has recent presence and no recorded member process is provably still alive.
 
 Rationale for these defaults: a real agent turn often runs 20-30 minutes (plan-and-edit, build-and-verify, review-and-respond), and a human collaborator walking through a few rooms may easily be idle for an hour without being "gone." Earlier drafts inherited chat-scale defaults (5-minute lease, 10-minute presence) which would silently open takeover windows mid-turn. The selected values accept a slower takeover response in exchange for not interrupting legitimate long work; operators who want faster response can shorten them via per-room policy once that ships.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "talking-stick",
-  "version": "0.4.3",
+  "version": "0.4.5",
   "description": "CLI coordination tool for path-scoped agent handoffs.",
   "type": "module",
   "bin": {
@@ -21,6 +21,7 @@
     "postinstall": "node scripts/postinstall-mcp-cleanup.cjs",
     "prepare": "tsc -p tsconfig.build.json && chmod +x dist/cli.js",
     "test": "vitest run",
+    "version": "node scripts/prepare-release.mjs --from-package",
     "typecheck": "tsc -p tsconfig.json --noEmit"
   },
   "dependencies": {

package/scripts/prepare-release.mjs

@@ -0,0 +1,261 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import path from "node:path";
+import process from "node:process";
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+const CHANGELOG_PATH = "CHANGELOG.md";
+const RELEASES_DIR = path.join("docs", "releases");
+const PACKAGE_PATH = "package.json";
+const RELEASE_URL_PREFIX =
+  "https://github.com/mostlydev/talking-stick/releases/tag/v";
+
+function main() {
+  const options = parseArgs(process.argv.slice(2));
+  const version = options.fromPackage
+    ? readPackageVersion()
+    : options.version;
+  if (!version) {
+    throw new Error("Usage: prepare-release --from-package | --version VERSION");
+  }
+  assertVersion(version);
+
+  const date = options.date ?? new Date().toISOString().slice(0, 10);
+  const changelog = readText(CHANGELOG_PATH);
+  const { nextChangelog, releaseBody } = prepareChangelog({
+    changelog,
+    version,
+    date
+  });
+
+  const releasePath = path.join(RELEASES_DIR, `${version}.md`);
+  if (fs.existsSync(releasePath)) {
+    throw new Error(`${releasePath} already exists.`);
+  }
+
+  fs.mkdirSync(RELEASES_DIR, { recursive: true });
+  writeText(CHANGELOG_PATH, nextChangelog);
+  writeText(releasePath, renderReleaseNotes(version, date, releaseBody));
+  stageGeneratedFiles([CHANGELOG_PATH, releasePath]);
+
+  console.log(`Prepared release notes for ${version}.`);
+}
+
+function parseArgs(args) {
+  const options = {
+    fromPackage: false,
+    version: undefined,
+    date: undefined
+  };
+
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === "--from-package") {
+      options.fromPackage = true;
+      continue;
+    }
+    if (arg === "--version") {
+      options.version = requireValue(args, (index += 1), "--version");
+      continue;
+    }
+    if (arg === "--date") {
+      options.date = requireValue(args, (index += 1), "--date");
+      continue;
+    }
+    throw new Error(`Unknown option: ${arg}`);
+  }
+
+  if (options.fromPackage && options.version) {
+    throw new Error("Use either --from-package or --version, not both.");
+  }
+
+  return options;
+}
+
+function requireValue(args, index, name) {
+  const value = args[index];
+  if (!value || value.startsWith("--")) {
+    throw new Error(`${name} requires a value.`);
+  }
+  return value;
+}
+
+function readPackageVersion() {
+  const parsed = JSON.parse(readText(PACKAGE_PATH));
+  if (typeof parsed.version !== "string") {
+    throw new Error("package.json does not contain a string version.");
+  }
+  return parsed.version;
+}
+
+function assertVersion(version) {
+  if (!/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/.test(version)) {
+    throw new Error(`Invalid release version: ${version}`);
+  }
+}
+
+export function prepareChangelog({ changelog, version, date }) {
+  const lines = changelog.replace(/\r\n/g, "\n").split("\n");
+  const unreleasedIndex = lines.findIndex((line) => line === "## Unreleased");
+  if (unreleasedIndex === -1) {
+    throw new Error("CHANGELOG.md must contain a '## Unreleased' section.");
+  }
+
+  const duplicateIndex = lines.findIndex(
+    (line) => line === `## [${version}] — ${date}` || line.startsWith(`## [${version}] `)
+  );
+  if (duplicateIndex !== -1) {
+    throw new Error(`CHANGELOG.md already contains a ${version} section.`);
+  }
+
+  const nextSectionIndex = findNextVersionHeading(lines, unreleasedIndex + 1);
+  const unreleasedBody = trimBlankLines(
+    lines.slice(unreleasedIndex + 1, nextSectionIndex)
+  );
+
+  if (unreleasedBody.length === 0) {
+    throw new Error("CHANGELOG.md Unreleased section is empty.");
+  }
+
+  const releaseSection = [
+    "## Unreleased",
+    "",
+    `## [${version}] — ${date}`,
+    "",
+    `Full notes: [\`docs/releases/${version}.md\`](docs/releases/${version}.md).`,
+    "",
+    ...unreleasedBody,
+    ""
+  ];
+
+  const nextLines = [
+    ...lines.slice(0, unreleasedIndex),
+    ...releaseSection,
+    ...lines.slice(nextSectionIndex)
+  ];
+
+  const nextChangelog = ensureReleaseLink(
+    `${nextLines.join("\n").replace(/\n*$/, "")}\n`,
+    version
+  );
+
+  return {
+    nextChangelog,
+    releaseBody: unreleasedBody.join("\n")
+  };
+}
+
+function findNextVersionHeading(lines, startIndex) {
+  const nextIndex = lines.findIndex(
+    (line, index) => index >= startIndex && /^##\s+/.test(line)
+  );
+  return nextIndex === -1 ? lines.length : nextIndex;
+}
+
+function trimBlankLines(lines) {
+  let start = 0;
+  let end = lines.length;
+  while (start < end && lines[start].trim() === "") {
+    start += 1;
+  }
+  while (end > start && lines[end - 1].trim() === "") {
+    end -= 1;
+  }
+  return lines.slice(start, end);
+}
+
+function ensureReleaseLink(changelog, version) {
+  const reference = `[${version}]: ${RELEASE_URL_PREFIX}${version}`;
+  const lines = changelog.replace(/\r\n/g, "\n").split("\n");
+
+  if (lines.some((line) => line.startsWith(`[${version}]:`))) {
+    return changelog;
+  }
+
+  const firstReferenceIndex = lines.findIndex((line) =>
+    /^\[[^\]]+\]:\s+/.test(line)
+  );
+  if (firstReferenceIndex === -1) {
+    return `${changelog.replace(/\n*$/, "")}\n\n${reference}\n`;
+  }
+
+  lines.splice(firstReferenceIndex, 0, reference);
+  return `${lines.join("\n").replace(/\n*$/, "")}\n`;
+}
+
+function renderReleaseNotes(version, date, changelogBody) {
+  return `# Talking Stick ${version}
+
+Date: ${date}
+
+${renderReleaseBody(changelogBody)}
+
+## Verification
+
+\`\`\`bash
+npm run typecheck
+npm test
+npm run build
+node dist/cli.js --help
+git diff --check
+npm pack --dry-run
+\`\`\`
+`;
+}
+
+function renderReleaseBody(changelogBody) {
+  return changelogBody
+    .split("\n")
+    .map((line) => {
+      const heading = /^(#{3,})\s+(.+)$/.exec(line);
+      if (!heading) {
+        return line;
+      }
+      return `${heading[1].slice(1)} ${heading[2]}`;
+    })
+    .join("\n");
+}
+
+function readText(filePath) {
+  return fs.readFileSync(filePath, "utf8");
+}
+
+function writeText(filePath, content) {
+  fs.writeFileSync(filePath, content, "utf8");
+}
+
+function stageGeneratedFiles(filePaths) {
+  if (
+    process.env.npm_lifecycle_event !== "version" ||
+    process.env.npm_config_git_tag_version === "false"
+  ) {
+    return;
+  }
+
+  const insideWorkTree = spawnSync("git", ["rev-parse", "--is-inside-work-tree"], {
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "ignore"]
+  });
+  if (
+    insideWorkTree.status !== 0 ||
+    insideWorkTree.stdout.trim() !== "true"
+  ) {
+    return;
+  }
+
+  const add = spawnSync("git", ["add", ...filePaths], {
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "pipe"]
+  });
+  if (add.status !== 0) {
+    throw new Error(add.stderr.trim() || "Failed to stage release files.");
+  }
+}
+
+if (
+  process.argv[1] &&
+  path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)
+) {
+  main();
+}

package/skills/talking-stick/SKILL.md

@@ -63,6 +63,8 @@ Keep the returned room id and canonical path in mind. The current working direct
 
 On freshly invoked multi-agent tasks, give peers a short window to join before deciding you are alone. Use a normal wait timeout or spend about a minute on read-only repo orientation while other harnesses appear.
 
+If `tt join` returns a `warning` containing `Superseded previous harness session(s): ...`, that is the normal path after a harness `/clear` (or equivalent in-process session reset). The prior session in this same harness process held or was reserved for the stick, can no longer reply, and has been removed from the room. A `session_superseded` event records who replaced whom. This is informational, not a takeover decision — proceed normally.
+
 After joining, load editable collaboration instructions once:
 
 ```sh
@@ -71,13 +73,17 @@ tt instructions show --json
 
 If that command fails, continue with this bundled skill. Editable instructions can add local preferences, but they do not override the safety rules in this skill.
 
-Right after joining, start a background ambient receiver so direct messages and turn passes/reservations surface as soon as they happen instead of waiting for the next time you poll:
+Right after joining, start exactly one background ambient receiver so direct messages and turn passes/reservations surface as soon as they happen instead of waiting for the next time you poll:
 
 ```sh
 tt events --follow --json
 ```
 
-For `tt events --wait` and `tt events --follow`, the default target is `self`; add `--target any` only for audit/debug views. If your harness can stream a child process's stdout into the model's context (Claude Code's Monitor, Codex `attach`-style), this is enough — each line becomes an event you see mid-task. If your harness can only notice that a backgrounded command exits, use the polling fallback in §4.5. Without an ambient receiver, neither messages nor turn handoffs reach you between deliberate `tt wait` / `tt events` calls.
+For `tt events --wait` and `tt events --follow`, the default target is `self`; add `--target any` only for audit/debug views.
+
+The receiver must stream stdout line-by-line into your model context (Claude Code's Monitor, Codex `attach`-style) so each event becomes a notification you see mid-task. A backgrounded shell that only notifies when the process exits is **not** an ambient receiver — it silently swallows every event until termination, then fires a single useless notification at the end. If your harness can only observe process-exit, use the polling fallbacks in §4.5 instead; do not dress an exit-notify background command up as a stream consumer.
+
+Run exactly one ambient receiver per session. A second `tt events --follow` does not add coverage — both instances compete for the same stream, and one of them is likely silently consuming events you will never see. If you need a different filter, stop the existing receiver first.
 
 The ambient receiver is not a turn claimant. It never grants the stick and never starts the lease guardian. Keep using `tt wait --json` for ownership.
 
@@ -91,6 +97,8 @@ tt wait --json
 
 The default wait timeout is `110s`, which is the normal active-coordination setting. If your harness has a shorter tool timeout, override with the longest safe value and immediately wait again when it returns without granting the turn. Do not busy-loop with short waits.
 
+If a handoff, message, or operator instruction leaves review, release, or other task work pending, use normal `tt wait --json`; do not use park mode. `tt wait --park --json` is only for passive standby when no task is pending and you are waiting for operator input or another external signal.
+
 Possible outcomes:
 
 - `your_turn`: you may proceed
@@ -106,7 +114,7 @@ Prefer to run `tt wait` in the background if your harness supports background co
 
 Prefer wait cycles over scheduled wakeups. A direct long-poll stays aligned with other agents and usually notices a released stick within the same cycle. Use scheduled wakeups only when your harness cannot keep a wait running in the background.
 
-Do not replace `tt wait` with an event receiver. `tt events --wait` is only a wake channel for messages and handoff/reservation events. If it exits with a pass, release, assignment, or message, process the event, then run or continue `tt wait --json`; do not touch shared files unless that wait returns `your_turn`.
+Do not replace `tt wait` with an event receiver. `tt events --wait` is only a wake channel for messages and handoff/reservation events. If it exits with a pass, release, assignment, or message, process the event, then run or continue normal `tt wait --json` whenever work is pending; do not touch shared files unless that wait returns `your_turn`.
 
 If you do not have the stick:
 
@@ -173,6 +181,8 @@ If `tt wait` reports `takeover_available`:
 - if takeover is chosen, run `tt take --reason "..." --json`
 - after takeover, run `tt events --target any --json` so you can reconstruct the last handoff before touching code
 
+`session_superseded` is **not** a takeover reason — it is a separate informational event emitted on `tt join` when a new in-process harness session replaces a prior one (see §2). It never requires a takeover decision.
+
 If the operator explicitly tells you to take over despite a reservation or live owner, use:
 
 ```sh
@@ -206,6 +216,7 @@ Use `tt assign <agent_id> . --stdin` only when a specific named member must go n
 - they have unique context the next step requires
 - they hold a credential or capability others lack
 - the operator explicitly addressed the work to them
+- the handoff asks that named peer for a concrete review or release action
 
 Otherwise release. Pinning turns between two agents is an antipattern because it can lock humans out of their own room.