talking-stick 0.4.8 → 0.4.9

package/README.md

@@ -105,7 +105,7 @@ tt msg send/recv   — out-of-band chat into the room event log
 tt instructions    — editable collaboration prompt loaded by the skill
 ```
 
-A workspace maps to a room — usually the `git` root or nearest project marker — so two agents `cd`'d anywhere under the same repo join the same room automatically.
+A workspace maps to a room — usually the `git` root or nearest project marker — so two agents `cd`'d anywhere under the same repo join the same room automatically. Marker files directly in your home directory are ignored for descendant paths, so scratch directories under `$HOME` do not collapse into one broad home-scoped room unless you explicitly join home itself.
 
 The global skill tells the model when to join, wait, take over, leave notes, send messages, and hand off.
 

package/dist/cli/event-stream.js

@@ -20,7 +20,11 @@ export async function runEventStream(runtime, parsed, identity, roomId, options)
         event_type: options.event_type,
         target_agent_id: targetAgentId,
         from_agent_id: fromAgentId,
-        max_wait_ms: follow || wait ? parseWaitTimeout(parsed) : 0
+        max_wait_ms: follow || wait ? parseWaitTimeout(parsed) : 0,
+        // Carry the caller's identity so a sustained self-receiver registers and
+        // refreshes presence (issue #29 Defect 1) — a `tt events --follow` /
+        // `--wait` watcher stays visible even if it never ran `tt join`.
+        process_metadata: identity.process_metadata
     };
     if (!follow) {
         const result = await runtime.commands.waitForEvents(waitInput);
@@ -38,7 +42,8 @@ export function resolveOptionalAgentSelector(runtime, identity, roomId, raw) {
 export function resolveAgentSelector(runtime, identity, roomId, raw) {
     const members = runtime.commands.getRoomState({
         room_id: roomId,
-        agent_id: identity.agent_id
+        agent_id: identity.agent_id,
+        process_metadata: identity.process_metadata
     }).members;
     const exact = members.find((member) => member.agent_id === raw);
     if (exact) {

package/dist/cli/guardian.js

@@ -14,11 +14,12 @@ export async function runGuardCommand(parsed) {
         displayName: requireStringOption(parsed, "agent").replace(/^human:/, ""),
         sessionKind: "human_guardian"
     });
+    const harnessMetadata = parseHarnessMetadataOptions(parsed);
     const identity = {
         ...baseIdentity,
         process_metadata: {
             ...baseIdentity.process_metadata,
-            ...parseHarnessMetadataOptions(parsed)
+            ...harnessMetadata
         }
     };
     const runtime = createRuntime();
@@ -32,8 +33,28 @@ export async function runGuardCommand(parsed) {
             expected_turn_id: parseRequiredInteger(parsed, "turn-id")
         };
         const intervalMs = joined.policy.heartbeatIntervalMs;
+        const harnessRef = {
+            pid: harnessMetadata.harness_pid,
+            process_started_at: harnessMetadata.harness_process_started_at
+        };
+        const inspector = createSystemProcessInspector();
         process.stdout.write(`${GUARD_READY}\n`);
         const timer = setInterval(() => {
+            // Tier-1 stale-guardian purge: if our own harness process is provably
+            // gone, surrender the turn instead of renewing the lease forever. This is
+            // the definitive case (no timeout): an orphaned guardian must not pin the
+            // stick once the harness it represents has exited. `unknown`/`alive` both
+            // fall through to the normal heartbeat; we only act on a definite `gone`.
+            if (checkGuardianLiveness(harnessRef, inspector) === "gone") {
+                try {
+                    runtime.commands.relinquishOwnership(identity, heartbeatInput);
+                }
+                catch {
+                    // Best effort: a takeover or graceful release may have already moved
+                    // the turn on. Either way the harness is gone, so we exit.
+                }
+                process.exit(0);
+            }
             try {
                 runtime.commands.heartbeat(identity, heartbeatInput);
             }

package/dist/cli/room-commands.js

@@ -95,7 +95,8 @@ export function handleStateCommand(runtime, parsed) {
     const session = resolveSessionForReads(runtime, parsed, identity);
     const state = runtime.commands.getRoomState({
         room_id: session.room_id,
-        agent_id: identity.agent_id
+        agent_id: identity.agent_id,
+        process_metadata: identity.process_metadata
     });
     printResult(parsed, { room: state.room, members: state.members }, () => {
         const lines = [
@@ -144,7 +145,8 @@ export async function handleEventsCommand(runtime, parsed) {
         room_id: session.room_id,
         agent_id: identity.agent_id,
         after_event_seq: parseOptionalInteger(parsed, "after"),
-        limit: parseOptionalInteger(parsed, "limit")
+        limit: parseOptionalInteger(parsed, "limit"),
+        process_metadata: identity.process_metadata
     });
     printResult(parsed, events, () => {
         if (events.length === 0) {

package/dist/cli/turn-commands.js

@@ -245,7 +245,8 @@ function resolveAssignmentTarget(runtime, identity, session, selector) {
     }
     const state = runtime.commands.getRoomState({
         room_id: session.room_id,
-        agent_id: identity.agent_id
+        agent_id: identity.agent_id,
+        process_metadata: identity.process_metadata
     });
     const normalizedSelector = selector.toLowerCase();
     const candidates = state.members.filter((member) => {
@@ -265,7 +266,8 @@ function resolveAssignmentTarget(runtime, identity, session, selector) {
     const events = runtime.commands.getRoomEvents({
         room_id: session.room_id,
         agent_id: identity.agent_id,
-        limit: 500
+        limit: 500,
+        process_metadata: identity.process_metadata
     });
     return pickFairAssignmentCandidate(candidates, events).agent_id;
 }

package/dist/commands.js

@@ -41,7 +41,8 @@ export class TalkingStickCommands {
             auto_claim: input.auto_claim,
             include_events: input.include_events,
             after_event_seq: input.after_event_seq,
-            target_agent_id: input.target_agent_id
+            target_agent_id: input.target_agent_id,
+            process_metadata: identity.process_metadata
         });
     }
     heartbeat(identity, input) {
@@ -52,6 +53,14 @@ export class TalkingStickCommands {
             expected_turn_id: input.expected_turn_id
         });
     }
+    relinquishOwnership(identity, input) {
+        return this.service.relinquishOwnership({
+            agent_id: identity.agent_id,
+            room_id: input.room_id,
+            lease_id: input.lease_id,
+            expected_turn_id: input.expected_turn_id
+        });
+    }
     releaseStick(identity, input) {
         return this.service.releaseStick({
             agent_id: identity.agent_id,
@@ -92,7 +101,8 @@ export class TalkingStickCommands {
             room_id: input.room_id,
             body: input.body,
             to_agent_id: input.to_agent_id,
-            delivery_hint: input.delivery_hint
+            delivery_hint: input.delivery_hint,
+            process_metadata: identity.process_metadata
         });
     }
     waitForEvents(input) {
@@ -106,7 +116,8 @@ export class TalkingStickCommands {
             agent_id: identity.agent_id,
             room_id: input.room_id,
             body: input.body,
-            turn_id: input.turn_id
+            turn_id: input.turn_id,
+            process_metadata: identity.process_metadata
         });
     }
     listNotes(identity, input) {
@@ -115,7 +126,8 @@ export class TalkingStickCommands {
             agent_id: identity?.agent_id,
             after_note_id: input.after_note_id,
             include_resolved: input.include_resolved,
-            limit: input.limit
+            limit: input.limit,
+            process_metadata: identity?.process_metadata
         });
     }
 }

package/dist/config.js

@@ -2,6 +2,7 @@ import os from "node:os";
 import path from "node:path";
 export const defaultPolicy = {
     ownerLeaseTtlMs: 45 * 60 * 1000,
+    ownerActivityTtlMs: 45 * 60 * 1000,
     heartbeatIntervalMs: 5 * 60 * 1000,
     claimTtlMs: 20 * 60 * 1000,
     waitForTurnMaxWaitMs: 110 * 1000,

package/dist/path-resolution.js

@@ -1,5 +1,6 @@
 import { execFileSync } from "node:child_process";
 import fs from "node:fs";
+import os from "node:os";
 import path from "node:path";
 const workspaceMarkers = [
     "CLAUDE.md",
@@ -78,8 +79,12 @@ function resolveGitRoot(canonicalContextPath) {
     }
 }
 function findNearestWorkspaceMarker(startPath) {
+    const homeMarkerBoundary = resolveHomeMarkerBoundary(startPath);
     let current = startPath;
     while (true) {
+        if (homeMarkerBoundary && samePath(current, homeMarkerBoundary)) {
+            return null;
+        }
         for (const marker of workspaceMarkers) {
             if (fs.existsSync(path.join(current, marker))) {
                 return current;
@@ -92,6 +97,32 @@ function findNearestWorkspaceMarker(startPath) {
         current = parent;
     }
 }
+function resolveHomeMarkerBoundary(startPath) {
+    const homeDir = os.homedir();
+    if (!homeDir) {
+        return null;
+    }
+    const resolvedHomeDir = path.resolve(homeDir);
+    const candidateHomes = [
+        canonicalizeDirectoryPath(resolvedHomeDir),
+        path.normalize(resolvedHomeDir)
+    ];
+    for (const candidateHome of candidateHomes) {
+        if (!samePath(startPath, candidateHome) &&
+            isWithinOrSame(startPath, candidateHome)) {
+            return candidateHome;
+        }
+    }
+    return null;
+}
+function canonicalizeDirectoryPath(directoryPath) {
+    try {
+        return fs.realpathSync.native(directoryPath);
+    }
+    catch {
+        return path.normalize(directoryPath);
+    }
+}
 function samePath(left, right) {
     return path.normalize(left) === path.normalize(right);
 }

package/dist/service.js

@@ -306,7 +306,14 @@ export class TalkingStickService {
         return withImmediateTransaction(this.db, () => {
             const room = this.requireRoom(input.room_id);
             this.assertOwnerMutation(room, input, now);
-            this.touchMember(input.room_id, input.agent_id, timestamp);
+            // Deliberately do NOT touch the member's last_seen_at here. Lease renewal
+            // is the guardian's job and must not be mistaken for harness presence:
+            // an abandoned-but-alive owner whose guardian keeps renewing would
+            // otherwise look permanently active and its turn could never be reclaimed
+            // (`owner_idle`). The lease itself (lease_expires_at, below) is the
+            // guardian's liveness signal; harness presence is recorded only by the
+            // harness's own `tt` commands. assertOwnerMutation already guarantees the
+            // owning member still exists.
             this.db
                 .prepare(`
           UPDATE path_rooms
@@ -371,6 +378,56 @@ export class TalkingStickService {
             };
         });
     }
+    /**
+     * Tier-1 stale-guardian purge: the lease guardian discovered that its own
+     * harness process is provably gone, so it surrenders the turn before exiting.
+     * Unlike `releaseStick` this carries no handoff and is a no-op unless this
+     * agent still owns this exact turn/lease (the guardian may race a takeover or
+     * a graceful release). The room drops straight to `idle` so any waiter can
+     * claim it immediately, instead of waiting out the full lease TTL.
+     */
+    relinquishOwnership(input) {
+        const now = this.now();
+        const timestamp = now.toISOString();
+        this.purgeExpiredIdleRooms(now);
+        return withImmediateTransaction(this.db, () => {
+            const room = this.requireRoom(input.room_id);
+            if (room.owner !== input.agent_id ||
+                room.turn_id !== input.expected_turn_id ||
+                room.lease_id !== input.lease_id) {
+                return { status: "noop", room_id: input.room_id };
+            }
+            const eventSeq = this.appendEvent({
+                room_id: input.room_id,
+                turn_id: room.turn_id,
+                event_type: "release",
+                from_agent_id: input.agent_id,
+                to_agent_id: null,
+                handoff: null,
+                reason: "harness_gone",
+                created_at: timestamp
+            });
+            this.db
+                .prepare(`
+          UPDATE path_rooms
+          SET owner = NULL,
+              reserved_for = NULL,
+              pending_handoff_event_seq = NULL,
+              lease_id = NULL,
+              lease_expires_at = NULL,
+              claim_expires_at = NULL,
+              state = 'idle',
+              updated_at = ?
+          WHERE room_id = ?
+        `)
+                .run(timestamp, input.room_id);
+            return {
+                status: "relinquished",
+                room_id: input.room_id,
+                event_seq: eventSeq
+            };
+        });
+    }
     passStick(input) {
         validateHandoff(input.handoff);
         assertNonEmpty(input.to_agent_id, "to_agent_id");
@@ -486,7 +543,7 @@ export class TalkingStickService {
         const timestamp = now.toISOString();
         this.purgeExpiredIdleRooms(now);
         const room = this.requireRoom(input.room_id);
-        this.touchKnownMember(input.room_id, input.agent_id, timestamp);
+        this.touchKnownMember(input.room_id, input.agent_id, timestamp, input.process_metadata);
         const inspection = this.inspectRoom(room, now);
         return {
             room: this.mapRoom(inspection, now),
@@ -495,7 +552,7 @@ export class TalkingStickService {
     }
     getRoomEvents(input) {
         this.purgeExpiredIdleRooms(this.now());
-        this.touchKnownMember(input.room_id, input.agent_id, this.now().toISOString());
+        this.touchKnownMember(input.room_id, input.agent_id, this.now().toISOString(), input.process_metadata);
         const afterEventSeq = input.after_event_seq ?? 0;
         const limit = Math.min(input.limit ?? 100, 500);
         return this.db
@@ -532,7 +589,7 @@ export class TalkingStickService {
             if (room.state === "closed") {
                 throw new ProtocolError("room_closed", "Messages cannot be sent to a closed room.", { room_id: input.room_id });
             }
-            this.touchMember(input.room_id, input.agent_id, timestamp);
+            this.touchMember(input.room_id, input.agent_id, timestamp, input.process_metadata);
             if (input.to_agent_id) {
                 const target = this.getMember(input.room_id, input.to_agent_id);
                 if (!target) {
@@ -567,6 +624,17 @@ export class TalkingStickService {
         if (targetFilter === "self" && !input.agent_id) {
             throw new ProtocolError("agent_id_required", "agent_id is required when target_agent_id is 'self'.");
         }
+        // The default `target=self` event wait is the documented per-session
+        // presence primitive (the §2 ambient receiver): "watching" the room keeps
+        // the member visible. Refresh — and, for a receiver that never ran
+        // `tt join`, register — presence at entry (each long-poll cycle re-enters
+        // with a fresh cursor), re-stamping current harness metadata but never
+        // recording turn interest. An audit/debug `target=any` (or a third-party
+        // `target=<other>`) wait deliberately does NOT touch presence: it is not
+        // participation and must not resurrect a stale peer into an active waiter.
+        if (targetFilter === "self" && input.agent_id) {
+            this.recordReceiverPresence(input.room_id, input.agent_id, this.now().toISOString(), input.process_metadata);
+        }
         const eventTypes = normalizeEventTypeFilter(input.event_type);
         const afterEventSeq = input.after_event_seq ?? 0;
         const maxWaitMs = Math.min(Math.max(input.max_wait_ms ?? this.policy.waitForEventsMaxWaitMs, 0), this.policy.waitForEventsMaxWaitMs);
@@ -622,7 +690,7 @@ export class TalkingStickService {
                     input.turn_id > room.turn_id)) {
                 throw new ProtocolError("invalid_turn_id", "turn_id must be an integer between 0 and the current room turn_id.", { supplied: input.turn_id, current_turn_id: room.turn_id });
             }
-            this.touchMember(input.room_id, input.agent_id, timestamp);
+            this.touchMember(input.room_id, input.agent_id, timestamp, input.process_metadata);
             const noteId = randomUUID();
             const turnId = input.turn_id ?? null;
             this.db
@@ -645,7 +713,7 @@ export class TalkingStickService {
         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());
+        this.touchKnownMember(input.room_id, input.agent_id, this.now().toISOString(), input.process_metadata);
         const limit = Math.min(Math.max(input.limit ?? 50, 1), 200);
         const includeResolved = input.include_resolved === true;
         let anchorCreatedAt = null;
@@ -693,7 +761,7 @@ export class TalkingStickService {
         const now = this.now();
         const timestamp = now.toISOString();
         const room = this.requireRoom(input.room_id);
-        this.touchWaitingMember(input.room_id, input.agent_id, timestamp);
+        this.touchWaitingMember(input.room_id, input.agent_id, timestamp, input.process_metadata);
         const inspection = this.inspectRoomForMutation(room, now);
         if (room.state === "closed") {
             return { status: "closed", room_id: input.room_id };
@@ -807,6 +875,19 @@ export class TalkingStickService {
                 current_owner: room.owner
             };
         }
+        if (room.owner &&
+            room.owner !== input.agent_id &&
+            inspection.state === "owned" &&
+            this.isOwnerHarnessIdle(inspection.ownerMember, now)) {
+            return {
+                status: "takeover_available",
+                room_id: input.room_id,
+                turn_id: room.turn_id,
+                room_state: "owner_idle",
+                reason: "owner_idle",
+                current_owner: room.owner
+            };
+        }
         return {
             status: "not_yet",
             room_state: inspection.state,
@@ -821,7 +902,7 @@ export class TalkingStickService {
         const now = this.now();
         const timestamp = now.toISOString();
         const room = this.requireRoom(input.room_id);
-        this.touchWaitingMember(input.room_id, input.agent_id, timestamp);
+        this.touchWaitingMember(input.room_id, input.agent_id, timestamp, input.process_metadata);
         const inspection = this.inspectRoomForMutation(room, now);
         if (room.state === "closed") {
             return { status: "closed", room_id: input.room_id };
@@ -980,30 +1061,57 @@ export class TalkingStickService {
         return this.requireRoom(roomId);
     }
     upsertMember(roomId, agentId, timestamp, processMetadata) {
+        // `tt join`: create the member if absent, refresh presence, record wait
+        // interest, and re-stamp process metadata.
+        this.applyPresence(roomId, agentId, timestamp, {
+            processMetadata,
+            recordWait: true,
+            allowCreate: true,
+            requireMember: false
+        });
+    }
+    /**
+     * Unified presence write. Every non-guardian command routes through here so a
+     * member's last_seen_at and current process metadata are refreshed by
+     * ordinary `tt` use, not only by `tt join` (issue #29 Defect 1, and the
+     * operator's "liveness updates on all tt tool use" rule).
+     *
+     * - `recordWait` also bumps last_wait_at (turn interest) — wait/try/join only;
+     *   reads and event receivers leave it untouched (watching is not a claim).
+     * - Metadata is re-stamped only when the caller carries a usable process
+     *   identity, and the merge preserves a live owner/recipient's exact (guardian)
+     *   identity so a holder's own command never clobbers the guardian pid.
+     * - `allowCreate` inserts a missing row (join, and sustained self-receivers
+     *   that never ran `tt join`); `requireMember` instead throws for write-RPCs.
+     */
+    applyPresence(roomId, agentId, timestamp, options) {
         const existing = this.getMember(roomId, agentId);
-        const normalizedMetadata = normalizeProcessMetadata(processMetadata);
+        const normalized = normalizeProcessMetadata(options.processMetadata);
+        const hasIdentity = hasExactProcessIdentity(normalized) ||
+            hasHarnessProcessIdentity(normalized);
         if (existing) {
-            const room = this.requireRoom(roomId);
-            const mergedMetadata = this.mergeMemberProcessMetadata(room, existing, normalizedMetadata);
+            const sets = ["last_seen_at = ?", "status = 'active'"];
+            const params = [timestamp];
+            if (options.recordWait) {
+                sets.push("last_wait_at = ?");
+                params.push(timestamp);
+            }
+            if (hasIdentity) {
+                const room = this.requireRoom(roomId);
+                const merged = this.mergeMemberProcessMetadata(room, existing, normalized);
+                sets.push("host_id = ?", "pid = ?", "process_started_at = ?", "session_kind = ?", "display_name = ?", "harness_name = ?", "harness_session_id = ?", "harness_host_id = ?", "harness_pid = ?", "harness_process_started_at = ?");
+                params.push(merged.host_id, merged.pid, merged.process_started_at, merged.session_kind, merged.display_name, merged.harness_name, merged.harness_session_id, merged.harness_host_id, merged.harness_pid, merged.harness_process_started_at);
+            }
+            params.push(roomId, agentId);
             this.db
-                .prepare(`
-          UPDATE room_members
-          SET last_seen_at = ?,
-              last_wait_at = ?,
-              status = 'active',
-              host_id = ?,
-              pid = ?,
-              process_started_at = ?,
-              session_kind = ?,
-              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, mergedMetadata.harness_name, mergedMetadata.harness_session_id, mergedMetadata.harness_host_id, mergedMetadata.harness_pid, mergedMetadata.harness_process_started_at, roomId, agentId);
+                .prepare(`UPDATE room_members SET ${sets.join(", ")} WHERE room_id = ? AND agent_id = ?`)
+                .run(...params);
+            return;
+        }
+        if (options.requireMember) {
+            throw new ProtocolError("unknown_member", "Agent must join the room before using this tool.", { to_agent_id: agentId });
+        }
+        if (!options.allowCreate) {
             return;
         }
         const nextOrdinal = this.db
@@ -1032,7 +1140,21 @@ export class TalkingStickService {
         )
         VALUES (?, ?, ?, ?, ?, ?, 'active', ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
       `)
-            .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);
+            .run(roomId, agentId, nextOrdinal, timestamp, timestamp, options.recordWait ? timestamp : null, normalized.host_id, normalized.pid, normalized.process_started_at, normalized.session_kind, normalized.display_name, normalized.harness_name, normalized.harness_session_id, normalized.harness_host_id, normalized.harness_pid, normalized.harness_process_started_at);
+    }
+    /**
+     * Presence for a sustained self-targeted event receiver (the §2 ambient
+     * receiver). Watching the room is the documented per-session presence
+     * primitive, so it refreshes — and, for a receiver that never ran `tt join`,
+     * registers — the member, but never records turn interest (last_wait_at).
+     */
+    recordReceiverPresence(roomId, agentId, timestamp, processMetadata) {
+        this.applyPresence(roomId, agentId, timestamp, {
+            processMetadata,
+            recordWait: false,
+            allowCreate: true,
+            requireMember: false
+        });
     }
     mergeMemberProcessMetadata(room, existing, incoming) {
         if (!this.shouldPreserveExactMemberProcessMetadata(room, existing, incoming)) {
@@ -1130,17 +1252,13 @@ export class TalkingStickService {
         return (sessionKindPriority(incoming.session_kind) <
             sessionKindPriority(existing.session_kind));
     }
-    touchMember(roomId, agentId, timestamp) {
-        const result = this.db
-            .prepare(`
-        UPDATE room_members
-        SET last_seen_at = ?, status = 'active'
-        WHERE room_id = ? AND agent_id = ?
-      `)
-            .run(timestamp, roomId, agentId);
-        if (result.changes === 0) {
-            throw new ProtocolError("unknown_member", "Agent must join the room before using this tool.", { to_agent_id: agentId });
-        }
+    touchMember(roomId, agentId, timestamp, processMetadata) {
+        this.applyPresence(roomId, agentId, timestamp, {
+            processMetadata,
+            recordWait: false,
+            allowCreate: false,
+            requireMember: true
+        });
     }
     recordParkHint(roomId, agentId, pendingHandoffEventSeq) {
         this.db
@@ -1151,26 +1269,24 @@ export class TalkingStickService {
       `)
             .run(pendingHandoffEventSeq, roomId, agentId);
     }
-    touchWaitingMember(roomId, agentId, timestamp) {
-        const result = this.db
-            .prepare(`
-        UPDATE room_members
-        SET last_seen_at = ?, last_wait_at = ?, status = 'active'
-        WHERE room_id = ? AND agent_id = ?
-      `)
-            .run(timestamp, timestamp, roomId, agentId);
-        if (result.changes === 0) {
-            throw new ProtocolError("unknown_member", "Agent must join the room before using this tool.", { to_agent_id: agentId });
-        }
+    touchWaitingMember(roomId, agentId, timestamp, processMetadata) {
+        this.applyPresence(roomId, agentId, timestamp, {
+            processMetadata,
+            recordWait: true,
+            allowCreate: false,
+            requireMember: true
+        });
     }
-    touchKnownMember(roomId, agentId, timestamp) {
+    touchKnownMember(roomId, agentId, timestamp, processMetadata) {
         if (!agentId) {
             return;
         }
-        if (!this.getMember(roomId, agentId)) {
-            return;
-        }
-        this.touchMember(roomId, agentId, timestamp);
+        this.applyPresence(roomId, agentId, timestamp, {
+            processMetadata,
+            recordWait: false,
+            allowCreate: false,
+            requireMember: false
+        });
     }
     assertOwnerMutation(room, input, now) {
         const inspection = this.inspectRoomForMutation(room, now);
@@ -1252,6 +1368,15 @@ export class TalkingStickService {
             }
             return "owner_timeout";
         }
+        if (room.owner &&
+            room.owner !== agentId &&
+            inspection.state === "owned" &&
+            this.isOwnerHarnessIdle(inspection.ownerMember, now)) {
+            // Tier-2: the owner's harness is alive but idle, and `agentId` is the
+            // waiting peer exercising the takeover it was offered. This is the peer
+            // gate — a takeover is only resolved here on behalf of an actual waiter.
+            return "owner_idle";
+        }
         throw new ProtocolError("takeover_not_available", "No takeover timeout is currently available for this room.", { room_state: inspection.state });
     }
     isClaimTakeoverEligible(room, agentId, now, inspection) {
@@ -1465,6 +1590,25 @@ export class TalkingStickService {
         }
         return this.hasRecentPresence(member, now);
     }
+    /**
+     * Tier-2 stale-guardian detection: the owner's harness process is alive (so
+     * this is neither `owner_gone` nor a `stale_owner` lease timeout — the
+     * guardian is faithfully renewing), yet the harness itself has run no `tt`
+     * command for longer than `ownerActivityTtlMs`. Surfacing this as
+     * `takeover_available` is always peer-gated: it is only ever evaluated for a
+     * caller who is themselves waiting for the turn, so a long solo edit with no
+     * peers waiting is never disturbed.
+     */
+    isOwnerHarnessIdle(ownerMember, now) {
+        if (!ownerMember) {
+            return false;
+        }
+        if (this.getMemberProcessLiveness(ownerMember) === "gone") {
+            return false;
+        }
+        return (now.getTime() - Date.parse(ownerMember.last_seen_at) >
+            this.policy.ownerActivityTtlMs);
+    }
     shouldRetainIdleRoom(member, now) {
         const liveness = this.getMemberProcessLiveness(member);
         if (liveness === "alive") {
@@ -1660,6 +1804,27 @@ export class TalkingStickService {
         }
     }
     getMemberProcessLiveness(member) {
+        // Prefer the durable harness identity over the bare pid. The bare pid is
+        // frequently the per-turn guardian process (sessionKind `human_guardian`),
+        // which the metadata merge pins onto the member row. Inspecting the bare
+        // pid would let a dead guardian mark a live harness `inactive`, and let a
+        // still-renewing guardian keep an abandoned harness looking `active`. The
+        // harness pid is what actually represents the participant. Fall back to the
+        // bare pid only when no harness identity was recorded (e.g. raw CLI use).
+        if (hasHarnessProcessIdentity(member)) {
+            return this.processLivenessChecker({
+                host_id: member.harness_host_id ?? member.host_id,
+                pid: member.harness_pid,
+                process_started_at: member.harness_process_started_at,
+                session_kind: member.session_kind,
+                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
+            });
+        }
         return this.processLivenessChecker({
             host_id: member.host_id,
             pid: member.pid,
@@ -1824,6 +1989,13 @@ function hasExactProcessIdentity(metadata) {
         metadata.process_started_at !== undefined &&
         metadata.process_started_at.trim() !== "");
 }
+function hasHarnessProcessIdentity(metadata) {
+    return (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 hasHarnessInstanceIdentity(metadata) {
     return (metadata.harness_name !== null &&
         metadata.harness_name !== undefined &&

package/docs/releases/0.4.9.md

@@ -0,0 +1,17 @@
+# Talking Stick 0.4.9
+
+Date: 2026-06-03
+
+## Fixed
+- **Home-level workspace markers no longer capture scratch directories.** `resolveContextPath` now treats the user's home directory as a marker boundary for descendant paths, so an incidental `~/package.json`, `~/AGENTS.md`, or similar marker does not make unrelated markerless paths under `$HOME` join a home-scoped room. Explicitly joining `$HOME` still resolves to home, and real project markers below home still win.
+
+## 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

@@ -54,7 +54,7 @@ This avoids the common monorepo failure mode where one agent starts in `/repo/pa
 Preferred workspace root resolution:
 
 1. If the request path is inside a git worktree, use the git top-level path.
-2. Otherwise, use the nearest ancestor containing a recognized workspace marker such as `CLAUDE.md`, `AGENTS.md`, `package.json`, `pyproject.toml`, `Cargo.toml`, or `go.mod`.
+2. Otherwise, use the nearest ancestor containing a recognized workspace marker such as `CLAUDE.md`, `AGENTS.md`, `package.json`, `pyproject.toml`, `Cargo.toml`, or `go.mod`. When the request path is a child of the user's home directory, marker files directly in home are ignored so incidental home-level files do not capture unrelated scratch workspaces.
 3. Otherwise, use the canonical request path.
 
 Canonicalization applied before room lookup:

package/package.json

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