talking-stick 0.4.6 → 0.4.8

package/dist/cli/event-stream.js

@@ -116,7 +116,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/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/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") {

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,10 @@ 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
         });
     }
     heartbeat(identity, input) {

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();
@@ -767,6 +817,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);
+        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;

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/package.json

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