talking-stick 0.4.4 → 0.4.5

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) {
@@ -1439,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() {
@@ -1542,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) {
@@ -1552,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";
         }
@@ -1586,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.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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "talking-stick",
-  "version": "0.4.4",
+  "version": "0.4.5",
   "description": "CLI coordination tool for path-scoped agent handoffs.",
   "type": "module",
   "bin": {

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
@@ -95,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
@@ -110,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:
 
@@ -177,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
@@ -210,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.