talking-stick 0.4.6 → 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) {
@@ -116,7 +121,7 @@ async function followEvents(runtime, parsed, input) {
         process.stderr.write(`cursor_event_seq=${cursor}\n`);
     }
 }
-function resolveTargetFilter(runtime, identity, roomId, raw) {
+export function resolveTargetFilter(runtime, identity, roomId, raw) {
     if (raw === "self" || raw === "any") {
         return raw;
     }

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/output.js

@@ -1,9 +1,23 @@
 import { SUPPORTED_HARNESSES } from "../install.js";
 import { isKnownHarnessCliEnv } from "./identity.js";
 import { hasOption } from "./parser.js";
+export const COORDINATION_PROMPT = "Keep `tt wait` or `tt events` active until all goals are met; re-read the Talking Stick skill if context slips.";
+const COORDINATION_PROMPT_COMMANDS = new Set([
+    "join",
+    "state",
+    "events",
+    "wait",
+    "try",
+    "take",
+    "takeover",
+    "release",
+    "pass",
+    "assign",
+    "msg send"
+]);
 export function printResult(parsed, result, renderText) {
     if (shouldUseJson(parsed)) {
-        process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+        process.stdout.write(`${JSON.stringify(withCoordinationPrompt(parsed, result), null, 2)}\n`);
         return;
     }
     process.stdout.write(`${renderText()}\n`);
@@ -23,6 +37,24 @@ export function shouldUseJson(parsed, env = process.env) {
         return true;
     return false;
 }
+export function withCoordinationPrompt(parsed, result) {
+    if (!COORDINATION_PROMPT_COMMANDS.has(parsed.name)) {
+        return result;
+    }
+    if (!isObjectRecord(result) || Array.isArray(result)) {
+        return result;
+    }
+    if ("coordination_prompt" in result) {
+        return result;
+    }
+    return {
+        ...result,
+        coordination_prompt: COORDINATION_PROMPT
+    };
+}
+function isObjectRecord(value) {
+    return typeof value === "object" && value !== null;
+}
 export function formatRelativeTime(iso, now = new Date()) {
     if (!iso)
         return "—";
@@ -126,8 +158,8 @@ Commands:
   tt join [path] [--force-new]
   tt leave [path]
   tt kick <agent_id> [path] [--reason TEXT] [--force]
-  tt wait [path] [--timeout 110s] [--park]
-  tt try [path] [--park]
+  tt wait [path] [--timeout 110s] [--park] [--events --after N]
+  tt try [path] [--park] [--events --after N]
   tt state [path]
   tt events [path] [--after N] [--limit N] [--wait|--follow] [--event TYPE[,TYPE]] [--target self|any|agent]
   tt msg send <recipient|room> <body...> [--interrupt] [--stdin] [--path DIR]

package/dist/cli/registry.js

@@ -137,7 +137,7 @@ export const COMMAND_REGISTRY = [
         needsRuntime: true,
         startupMaintenance: true,
         internal: false,
-        usage: "tt wait [path] [--timeout 110s] [--park]",
+        usage: "tt wait [path] [--timeout 110s] [--park] [--events --after N] [--target self|any|agent]",
         description: "Wait until this agent can claim the stick.",
         handler: ({ runtime, parsed, cliEntryUrl }) => handleWaitCommand(requireRuntime(runtime), parsed, false, cliEntryUrl)
     },
@@ -146,7 +146,7 @@ export const COMMAND_REGISTRY = [
         needsRuntime: true,
         startupMaintenance: true,
         internal: false,
-        usage: "tt try [path] [--park]",
+        usage: "tt try [path] [--park] [--events --after N] [--target self|any|agent]",
         description: "Check turn availability without waiting.",
         handler: ({ runtime, parsed, cliEntryUrl }) => handleWaitCommand(requireRuntime(runtime), parsed, true, cliEntryUrl)
     },

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

@@ -2,20 +2,35 @@ import { clearCliSessionLease, createSystemProcessInspector, findCliSessionByRoo
 import { checkGuardianLiveness, spawnGuardian, stopGuardian } from "./guardian.js";
 import { resolveHandoff } from "./handoff.js";
 import { deriveCliIdentity, resolveTakeoverReason, shouldUseOperatorOverride } from "./identity.js";
-import { hasOption, normalizeBooleanFlag, parseWaitTimeout } from "./parser.js";
+import { getStringOption, hasOption, normalizeBooleanFlag, parseRequiredInteger, parseWaitTimeout } from "./parser.js";
+import { resolveTargetFilter } from "./event-stream.js";
 import { formatWaitResult, printResult } from "./output.js";
 import { requireLeaseSession, upsertSessionFromJoin } from "./session.js";
 export async function handleWaitCommand(runtime, parsed, isTry, cliEntryUrl) {
     normalizeBooleanFlag(parsed, "park");
+    normalizeBooleanFlag(parsed, "events");
     const park = hasOption(parsed, "park");
+    const includeEvents = hasOption(parsed, "events");
+    const afterEventSeq = includeEvents
+        ? parseRequiredInteger(parsed, "after")
+        : undefined;
+    if (!includeEvents && hasOption(parsed, "after")) {
+        throw new Error("Pass --after only with --events.");
+    }
     const contextPath = parsed.positionals[0] ?? process.cwd();
     const identity = deriveCliIdentity(parsed);
     const joined = runtime.commands.joinPath(identity, { context_path: contextPath });
     upsertSessionFromJoin(identity, joined);
+    const targetAgentId = includeEvents
+        ? resolveTargetFilter(runtime, identity, joined.room_id, getStringOption(parsed, "target") ?? "self")
+        : undefined;
     const waitResult = await runtime.commands.waitForTurn(identity, {
         room_id: joined.room_id,
         max_wait_ms: isTry ? 0 : parseWaitTimeout(parsed),
-        auto_claim: park ? false : undefined
+        auto_claim: park ? false : undefined,
+        include_events: includeEvents,
+        after_event_seq: afterEventSeq,
+        target_agent_id: targetAgentId
     });
     if (waitResult.status === "your_turn") {
         if (waitResult.reason === "already_owner") {
@@ -230,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) => {
@@ -250,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/cli.js

@@ -10,7 +10,7 @@ import { createRuntime } from "./cli/runtime.js";
 import { runStartupMaintenance } from "./cli/startup-maintenance.js";
 export { checkGuardianLiveness } from "./cli/guardian.js";
 export { parseHandoffJson } from "./cli/handoff.js";
-export { formatRelativeTime, shouldUseJson } from "./cli/output.js";
+export { COORDINATION_PROMPT, formatRelativeTime, shouldUseJson, withCoordinationPrompt } from "./cli/output.js";
 export { shouldAutoSyncInstalledSkills, shouldRunFirstRunMcpMigration } from "./cli/startup-maintenance.js";
 export async function runCli(argv = process.argv.slice(2)) {
     const parsed = parseCommand(argv);

package/dist/commands.js

@@ -38,7 +38,11 @@ export class TalkingStickCommands {
             agent_id: identity.agent_id,
             room_id: input.room_id,
             max_wait_ms: input.max_wait_ms,
-            auto_claim: input.auto_claim
+            auto_claim: input.auto_claim,
+            include_events: input.include_events,
+            after_event_seq: input.after_event_seq,
+            target_agent_id: input.target_agent_id,
+            process_metadata: identity.process_metadata
         });
     }
     heartbeat(identity, input) {
@@ -49,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,
@@ -89,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) {
@@ -103,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) {
@@ -112,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

@@ -233,6 +233,9 @@ export class TalkingStickService {
         assertNonEmpty(input.agent_id, "agent_id");
         assertNonEmpty(input.room_id, "room_id");
         this.purgeExpiredIdleRooms(this.now());
+        if (input.include_events) {
+            return this.waitForTurnWithEvents(input);
+        }
         const maxWaitMs = input.max_wait_ms ?? this.policy.waitForTurnMaxWaitMs;
         const deadline = Date.now() + Math.max(0, maxWaitMs);
         while (true) {
@@ -247,6 +250,53 @@ export class TalkingStickService {
             await sleep(Math.min(this.policy.waitForTurnPollMs, remainingMs));
         }
     }
+    async waitForTurnWithEvents(input) {
+        if (input.after_event_seq === undefined) {
+            throw new ProtocolError("invalid_cursor", "after_event_seq is required when include_events is true.");
+        }
+        if (!Number.isInteger(input.after_event_seq) || input.after_event_seq < 0) {
+            throw new ProtocolError("invalid_cursor", "after_event_seq must be a non-negative integer.");
+        }
+        const targetFilter = input.target_agent_id ?? "self";
+        if (targetFilter === "self" && !input.agent_id) {
+            throw new ProtocolError("agent_id_required", "agent_id is required when target_agent_id is 'self'.");
+        }
+        this.requireRoom(input.room_id);
+        this.warmRoomTurnLiveness(input.room_id);
+        const startedAsOwner = this.isActiveOwner(input.room_id, input.agent_id, this.now());
+        const afterEventSeq = input.after_event_seq;
+        const maxWaitMs = input.max_wait_ms ?? this.policy.waitForTurnMaxWaitMs;
+        const deadline = Date.now() + Math.max(0, maxWaitMs);
+        while (true) {
+            this.warmRoomTurnLiveness(input.room_id);
+            const waitResult = withImmediateTransaction(this.db, () => startedAsOwner
+                ? this.waitForOwnerEventTurnOnce(input)
+                : this.waitForTurnOnce(input));
+            const events = this.queryEvents({
+                room_id: input.room_id,
+                after_event_seq: afterEventSeq,
+                event_types: null,
+                target: targetFilter,
+                caller_agent_id: input.agent_id,
+                from_agent_id: null,
+                limit: this.policy.waitForEventsBatchLimit
+            });
+            if (waitResult.status === "closed") {
+                return this.withWaitEvents(waitResult, events, afterEventSeq, "closed");
+            }
+            if (this.isTurnWake(waitResult, startedAsOwner)) {
+                return this.withWaitEvents(waitResult, events, afterEventSeq, "turn");
+            }
+            if (events.length > 0) {
+                return this.withWaitEvents(waitResult, events, afterEventSeq, "event");
+            }
+            if (Date.now() >= deadline) {
+                return this.withWaitEvents(waitResult, events, afterEventSeq, "timeout");
+            }
+            const remainingMs = deadline - Date.now();
+            await sleep(Math.min(this.policy.waitForTurnPollMs, this.policy.waitForEventsPollMs, remainingMs));
+        }
+    }
     heartbeat(input) {
         const now = this.now();
         const timestamp = now.toISOString();
@@ -256,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
@@ -321,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");
@@ -436,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),
@@ -445,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
@@ -482,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) {
@@ -517,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);
@@ -572,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
@@ -595,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;
@@ -643,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 };
@@ -757,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,
@@ -767,6 +898,72 @@ export class TalkingStickService {
             claim_expires_at: room.claim_expires_at ?? undefined
         };
     }
+    waitForOwnerEventTurnOnce(input) {
+        const now = this.now();
+        const timestamp = now.toISOString();
+        const room = this.requireRoom(input.room_id);
+        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 };
+        }
+        if (room.owner === input.agent_id &&
+            room.lease_id &&
+            room.lease_expires_at &&
+            !this.hasExpired(room.lease_expires_at, now)) {
+            return {
+                status: "your_turn",
+                room_id: input.room_id,
+                turn_id: room.turn_id,
+                lease_id: room.lease_id,
+                handoff: null,
+                from_agent_id: null,
+                reason: "already_owner"
+            };
+        }
+        return {
+            status: "not_yet",
+            room_state: inspection.state,
+            turn_id: room.turn_id,
+            current_owner: room.owner ?? undefined,
+            reserved_for: room.reserved_for ?? undefined,
+            lease_expires_at: room.lease_expires_at ?? undefined,
+            claim_expires_at: room.claim_expires_at ?? undefined,
+            reason: "lost_turn"
+        };
+    }
+    isActiveOwner(roomId, agentId, now) {
+        const room = this.requireRoom(roomId);
+        return (room.owner === agentId &&
+            !!room.lease_id &&
+            !!room.lease_expires_at &&
+            !this.hasExpired(room.lease_expires_at, now));
+    }
+    isTurnWake(result, startedAsOwner = false) {
+        if (startedAsOwner &&
+            result.status === "your_turn" &&
+            result.reason === "already_owner") {
+            return false;
+        }
+        return (result.status === "your_turn" ||
+            result.status === "takeover_available" ||
+            // Park hints are turn wakes only because waitForTurnOnce throttles
+            // auto_claim_disabled per pending handoff; subsequent parked polls become
+            // plain not_yet and can timeout instead of tight-looping.
+            (result.status === "not_yet" &&
+                (result.reason === "auto_claim_disabled" ||
+                    result.reason === "lost_turn")));
+    }
+    withWaitEvents(result, events, afterEventSeq, wakeReason) {
+        return {
+            ...result,
+            events,
+            cursor_event_seq: events.length > 0
+                ? events[events.length - 1].event_seq
+                : afterEventSeq,
+            wake_reason: wakeReason
+        };
+    }
     grantTurn(room, agentId, now) {
         const timestamp = now.toISOString();
         const nextTurnId = room.turn_id + 1;
@@ -864,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
@@ -916,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)) {
@@ -1014,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
@@ -1035,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);
@@ -1136,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) {
@@ -1349,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") {
@@ -1544,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,
@@ -1708,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/plans/2026-05-20-wait-events-ambient-loop.md

@@ -0,0 +1,211 @@
+# wait-events ambient loop
+
+> **Status:** converged Codex + Claude design after operator pushback.
+>
+> **Problem trigger:** a holder still needs live messages while holding the
+> stick. A checkpoint-only wait loop lets agents fall out of receive exactly
+> when coordination matters.
+
+## Problem
+
+The current recommended workflow has two concepts:
+
+- `tt wait --json` grants ownership and starts or repairs the guardian.
+- `tt events --follow --json` is the ambient receiver for messages, passes,
+  releases, and assignments.
+
+That split is correct semantically, but it is too fragile operationally. Some
+harnesses cannot observe a long-running child process line-by-line and only see
+process completion. Others can start an ambient receiver but then stop paying
+attention after a release, timeout, or apparent task boundary. In practice, an
+agent can miss a late message or stop receiving while it owns the turn.
+
+The UX goal is one harness receive loop that remains active while waiting and
+while holding.
+
+## Decision
+
+Add an event-aware wait mode:
+
+```sh
+tt wait --events --after <event_seq> --json
+```
+
+This is the recommended ambient loop for harnesses. It runs in the background,
+returns on each wake, and is restarted with the returned `cursor_event_seq`.
+
+The normal ownership rule remains unchanged: only a `your_turn` wait result
+with a live guardian grants authority to mutate shared workspace state.
+Events returned by the command are observability, not permission.
+
+`tt events --follow` stays available for audit, debugging, and lower-level
+event inspection, but the bundled skill should stop teaching it as the primary
+harness loop once `wait --events` is dogfooded.
+
+## Output Shape
+
+`tt wait --events --after N --json` returns the existing wait result plus:
+
+```json
+{
+  "events": [],
+  "cursor_event_seq": 1234,
+  "wake_reason": "turn"
+}
+```
+
+`wake_reason` is one of:
+
+- `turn`: ownership state changed or an ownership-relevant branch is available.
+- `event`: self-targeted events arrived.
+- `timeout`: no relevant turn or event change arrived before timeout.
+- `closed`: the room closed. `status: "closed"` remains the canonical signal;
+  this reason only explains why the long-poll woke.
+
+If both a turn change and events are present, `wake_reason` is `turn`, and the
+harness still drains `events`.
+
+Events are returned on every result branch, including `your_turn`, `not_yet`,
+`takeover_available`, and `closed`. Terminal branches must not silently drop
+queued events.
+
+Holder timeout result shape is explicit: when the caller already owns the turn
+and no relevant events arrive before timeout, return `status: "your_turn"`,
+`reason: "already_owner"`, `events: []`, and `wake_reason: "timeout"`. The
+caller still owns the turn; the result is only a receive-loop checkpoint.
+
+## Wake Semantics
+
+When the caller is not the owner, wait-events wakes on:
+
+- a normal `your_turn` grant,
+- a reservation/pass to the caller,
+- room state entering a `takeover_available` branch the caller could exercise,
+- self-targeted event batches,
+- room closure,
+- timeout.
+
+When the caller already owns the turn, wait-events still long-polls. It wakes
+on:
+
+- self-targeted messages or broadcasts,
+- ownership loss or takeover,
+- room closure,
+- timeout.
+
+If the holder loses the turn, return `status: "not_yet"` with
+`reason: "lost_turn"` and any queued events. The former holder should not get an
+automatic re-grant path from that result.
+
+Holder-side wait-events must not release the turn, renew the lease, or change
+guardian state. The foreground work remains covered by the existing guardian
+process.
+
+## Park Mode
+
+`tt wait --park --events --after N --json` composes the same receive loop with
+park semantics.
+
+It wakes on self-targeted events, ownership-relevant state changes, closure, or
+timeout, but it never claims an idle room. In an idle room with a pending
+handoff, the result remains `status: "not_yet"` with
+`reason: "auto_claim_disabled"` plus the event fields. `wake_reason` reflects
+what woke the loop: usually `event`, `turn`, or `timeout`.
+
+## Targeting
+
+The default event target is `self`, matching the existing event filter:
+
+- direct messages to the caller,
+- broadcasts from other agents,
+- non-message events to or from the caller.
+
+`--target any` may exist for diagnostics, but the skill should not recommend it
+for normal harness loops.
+
+## Cursor Contract
+
+`--after` is required when `--events` is present. Omitting it is an explicit
+usage error. The harness owns the cursor and must pass the previous
+`cursor_event_seq` into the next invocation.
+
+`--after` without `--events` should also be an explicit usage error. Plain
+`tt wait` should not gain cursor semantics accidentally.
+
+Initial cursor choices:
+
+- use the room sequence from `tt join` / current state if available,
+- or use `--after 0` for a deliberate full replay.
+
+No implicit historical replay in the default path.
+
+## Heartbeat Contract
+
+Guardian remains the only owner lease heartbeat.
+
+Wait-events may refresh ordinary member presence as a read/check-in, but it
+must not update `lease_expires_at`, create a guardian, stop a guardian, or
+otherwise mutate owner lease state except when the wait-events path legitimately
+grants ownership. In that case, it is the normal wait path and must spawn or
+repair the guardian before returning `your_turn`.
+
+This is important for background use: if a backgrounded wait-events call grants
+`your_turn`, that same process must return a live `guardian_pid`. Requiring a
+follow-up foreground `tt wait` would create a race where the harness starts work
+before a guardian exists.
+
+## Skill Shape
+
+The harness guidance becomes:
+
+1. Join once.
+2. Start one background `tt wait --events --after <cursor> --json` loop.
+3. On each return, process `events`, update the cursor, and restart the loop.
+   Restart after `your_turn` too; ownership is not a reason to stop receiving.
+4. Treat `your_turn` plus guardian as write authority.
+5. Treat events on any non-owner result as messages/signals only.
+6. Release or park according to the existing active-work rules.
+
+This removes the separate "ambient receiver vs wait fallback" decision from
+normal harness behavior.
+
+## Implementation Order
+
+1. Extend wait CLI parsing with `--events`, `--after`, and optional `--target`.
+2. Add result fields for `events`, `cursor_event_seq`, and `wake_reason`.
+3. Implement service polling that checks both wait state and self-targeted
+   events without mutating owner lease state.
+4. Preserve existing `tt wait` behavior when `--events` is absent.
+5. Add tests for:
+   - waiting agent receives `your_turn` with events and a live guardian,
+   - holder receives a message while holding and gets `your_turn`,
+     `already_owner`, events, and no lease mutation,
+   - holder timeout returns `your_turn`, `already_owner`, empty events, and
+     `wake_reason: "timeout"`,
+   - holder is taken over and receives `not_yet`, `lost_turn`, and queued
+     events,
+   - event-only wake for a non-owner returns `not_yet` plus events,
+   - turn+event wake returns `wake_reason: "turn"` and still includes events,
+   - closed room still returns queued events,
+   - park plus events in an idle room returns `not_yet`,
+     `auto_claim_disabled`, and event fields,
+   - two concurrent wait-events calls on idle: one wins `your_turn`, the other
+     gets `not_yet` plus any queued events,
+   - `--events` without `--after` fails,
+   - `--after` without `--events` fails,
+   - wait-events alone does not preserve ownership if the guardian dies.
+6. Dogfood in a shared room with Codex and Claude before changing the bundled
+   skill recommendation.
+
+## Risks
+
+- The name `wait` now covers both ownership and receive-loop behavior. The
+  output must keep permission boundaries explicit.
+- A holder can still idle-hold if the harness misuses the loop as foreground
+  sleep. The skill must say the loop is background observability, not a reason
+  to keep the stick while inactive.
+- Wait-events alone must not preserve ownership. If the guardian dies or the
+  harness idles without active work, the lease expires normally and peers can
+  reach takeover availability.
+- Cursor misuse can replay or miss events. Requiring `--after` makes this
+  explicit instead of magical.

package/docs/releases/0.4.7.md

@@ -0,0 +1,17 @@
+# Talking Stick 0.4.7
+
+Date: 2026-05-20
+
+## Added
+- **`tt wait --events --after N`.** New flag turns `tt wait` into a unified background receive loop that long-polls for ownership changes *and* messages without a separate `tt events --follow` consumer. Holders can run the same command to receive directed and broadcast messages without renewing their lease; non-holders wake on ownership-relevant transitions (grant, reservation, takeover-available, room closure) or on self-targeted events. Result shape gains `events`, `cursor_event_seq`, and `wake_reason` (`turn` | `event` | `timeout` | `closed`). The cursor is required and explicit so a harness keeps the receive loop precise across restarts. `--target self|any|<agent_id>` (default `self`) selects which events the loop surfaces; release-to-room broadcasts are excluded by `self` but still wake the loop via the ownership-check half. `tt try --events --after N` composes the same shape for one-shot checks, and `--park --events` composes with the existing park-hint throttle so a parked receiver wakes once on a fresh pending handoff and then times out cleanly.
+
+## 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.8.md

@@ -0,0 +1,17 @@
+# Talking Stick 0.4.8
+
+Date: 2026-05-21
+
+## Added
+- **`coordination_prompt` in coordination command JSON.** Object-shaped JSON results from the common coordination commands (`join`, `state`, `events`, `wait`, `try`, `take`, `takeover`, `release`, `pass`, `assign`, `msg send`) now carry a short `coordination_prompt` reminder: keep `tt wait`/`tt events` active until all goals are met, and re-read the Talking Stick skill if context slips. The field is added only to plain JSON objects — event-stream arrays and instruction output are left untouched — and is never duplicated if a result already includes it. This keeps the stay-in-the-loop guidance in front of a harness even when the skill has scrolled out of context.
+
+## 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.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.6",
+  "version": "0.4.9",
   "description": "CLI coordination tool for path-scoped agent handoffs.",
   "type": "module",
   "bin": {