talking-stick 0.4.0 → 0.4.2

package/README.md

@@ -2,7 +2,7 @@
 
 A CLI coordination tool that lets multiple AI coding agents share a single workspace without stepping on each other. One agent holds the stick at a time; handoffs carry structured context so the next agent doesn't have to re-derive it.
 
-**Version:** 0.4.0. Multi-process-safe (SQLite WAL), liveness-aware, no daemon. Supports Claude Code, Codex CLI, Gemini CLI, and OpenCode out of the box. Two agents in the same room can also chat out-of-band — without passing the stick — via `tt msg send/recv`.
+**Version:** 0.4.1. Multi-process-safe (SQLite WAL), liveness-aware, no daemon. Supports Claude Code, Codex CLI, Gemini CLI, and OpenCode out of the box. Two agents in the same room can also chat out-of-band — without passing the stick — via `tt msg send/recv`.
 
 ## Quickstart
 
@@ -46,7 +46,7 @@ That's the whole workflow. They negotiate turns automatically, hand off structur
 
 | Method | Command | Notes |
 |---|---|---|
-| **From npm** | `npm i -g talking-stick` | Published as `0.4.0`. Requires Node ≥ 22. |
+| **From npm** | `npm i -g talking-stick` | Published as `0.4.1`. Requires Node ≥ 22. |
 | **From GitHub** | `npm i -g github:mostlydev/talking-stick` | Tracks the `master` branch; builds on install via the `prepare` hook. |
 | **From source** | `git clone … && npm install && npm link` | For contributors. |
 
@@ -106,7 +106,7 @@ 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.
 
-The global skill tells the model when to join, wait, verify its guardian, take over, leave notes, send messages, and hand off.
+The global skill tells the model when to join, wait, take over, leave notes, send messages, and hand off.
 
 ## Editable collaboration instructions
 
@@ -146,7 +146,7 @@ tt events --wait|--follow [--event TYPE[,TYPE]] [--target self|any|agent]
 - `tt msg recv --wait` exits on the next matching batch — ideal for harnesses that can launch a background command and notice when it completes; restart with `--after <last_event_seq>` to resume.
 - `tt events --wait` and `tt events --follow` default to `--target self`; pass `--target any` only for audit/debug views.
 - `wait_for_events` is observer-safe: it never mutates room state, so non-holders can use it freely without disturbing turn-fairness bookkeeping.
-- Event receive does not grant the stick. Agents must still use `tt wait` for ownership and verify the returned guardian before editing shared files.
+- Event receive does not grant the stick. Agents must still use `tt wait` for ownership before editing shared files.
 
 **When to message vs note vs handoff.**
 

package/dist/cli/turn-commands.js

@@ -18,12 +18,12 @@ export async function handleWaitCommand(runtime, parsed, isTry, cliEntryUrl) {
         if (waitResult.reason === "already_owner") {
             const sessionPath = resolveCliSessionPath();
             const existing = findCliSessionByRoom(sessionPath, identity.agent_id, joined.room_id);
-            const liveness = existing
+            const liveness = existing?.guardian_pid
                 ? checkGuardianLiveness({
                     pid: existing.guardian_pid,
                     process_started_at: existing.guardian_process_started_at
                 }, createSystemProcessInspector())
-                : "unknown";
+                : "gone";
             if (liveness === "gone") {
                 const replacement = await spawnGuardian({
                     agentId: identity.agent_id,
@@ -44,7 +44,12 @@ export async function handleWaitCommand(runtime, parsed, isTry, cliEntryUrl) {
                     guardian_process_started_at: replacement.process_started_at,
                     updated_at: new Date().toISOString()
                 });
-                printResult(parsed, { ...waitResult, guardian_pid: replacement.pid }, () => `Already holding the stick (turn ${waitResult.turn_id}). Prior guardian was gone; spawned replacement ${replacement.pid}.`);
+                printResult(parsed, { ...waitResult, guardian_pid: replacement.pid }, () => {
+                    const reason = existing?.guardian_pid
+                        ? "Prior guardian was gone"
+                        : "No guardian was recorded";
+                    return `Already holding the stick (turn ${waitResult.turn_id}). ${reason}; spawned replacement ${replacement.pid}.`;
+                });
                 return;
             }
             const guardianPid = existing?.guardian_pid;

package/dist/instructions.js

@@ -6,7 +6,7 @@ import { resolveContextPath } from "./path-resolution.js";
 export const DEFAULT_MAX_INSTRUCTION_FILE_BYTES = 256 * 1024;
 export const DEFAULT_INSTRUCTIONS_MARKDOWN = `# Talking Stick collaboration instructions
 
-Keep using Talking Stick until the shared task is done. After releasing or handing off, re-enter the wait loop by default. Prefer continued action unless the task is complete or the operator explicitly redirects or stops the room.
+Keep using Talking Stick until the shared task is done. After releasing or handing off, re-enter the wait loop by default. Prefer continued action unless the task is complete or the operator explicitly redirects or stops the room. If you are the only active member of the room, stop polling after a clear handoff rather than churning release/reclaim turns.
 
 Use phase names in handoffs when they clarify the work: draft, adversarial review, convergence, implementation, implementation review, test review, and release. These phases are vocabulary, not protocol state.
 

package/dist/service.js

@@ -1247,20 +1247,24 @@ export class TalkingStickService {
         if (!room.pending_handoff_event_seq) {
             return false;
         }
-        if (now.getTime() - Date.parse(room.updated_at) >= this.policy.waiterGraceMs) {
-            return false;
-        }
+        const handoffAgeMs = now.getTime() - Date.parse(room.updated_at);
         const pendingEvent = this.getEventBySeq(room.pending_handoff_event_seq);
         const priorOwner = pendingEvent?.from_agent_id ?? null;
         if (priorOwner === agentId &&
-            this.hasOtherRoomMember(room.room_id, agentId)) {
-            return true;
+            this.hasOtherActiveRoomMember(room.room_id, agentId, now)) {
+            return handoffAgeMs < this.priorOwnerReleaseCooldownMs();
+        }
+        if (handoffAgeMs >= this.policy.waiterGraceMs) {
+            return false;
         }
         const bestKnownMember = this.findBestFairKnownMember(room.room_id, priorOwner, now);
         return bestKnownMember !== null && bestKnownMember.agent_id !== agentId;
     }
-    hasOtherRoomMember(roomId, agentId) {
-        return this.getMembers(roomId).some((member) => member.agent_id !== agentId);
+    hasOtherActiveRoomMember(roomId, agentId, now) {
+        return this.getMembers(roomId).some((member) => member.agent_id !== agentId && this.isMemberActive(member, now));
+    }
+    priorOwnerReleaseCooldownMs() {
+        return Math.max(this.policy.waiterGraceMs * 6, 60_000);
     }
     inspectRoom(room, now) {
         const members = this.getMembers(room.room_id);

package/docs/receive-consumer-contract.md

@@ -26,7 +26,7 @@
 ## Consumer Responsibilities
 
 - Keep `wait_for_turn` / `tt wait` running separately. Receive processes do not claim or grant the stick, even when they return pass, release, or assignment events.
-- Treat an event wake as a prompt to read, reply, or retry `tt wait`. It is not permission to mutate shared files; only a `your_turn` wait result with a live guardian grants ownership.
+- Treat an event wake as a prompt to read, reply, or retry `tt wait`. It is not permission to mutate shared files; only a `your_turn` wait result grants ownership.
 - Decide how to surface `delivery_hint=interrupt`; the server only records the hint.
 - Dedupe on `event_id` if restart replay is possible.
 - Treat message bodies as room-visible text, not private data.

package/docs/releases/0.4.1.md

@@ -0,0 +1,38 @@
+# Talking Stick 0.4.1
+
+Date: 2026-05-10
+
+This patch fixes release/reclaim churn discovered while dogfooding the 0.4.0
+collaboration instructions. A holder could release with "no work", immediately
+re-enter `tt wait`, and reclaim the stick before another active harness had a
+real chance to claim.
+
+## Fixed
+
+### Prior-owner release cooldown
+
+When a room is idle after a release, the release's prior owner now waits through
+a bounded cooldown before reclaiming if another active member exists. The
+cooldown defaults to `max(6 * waiterGraceMs, 60_000)`, which is 60 seconds with
+the stock policy.
+
+Other members can still claim immediately, and the prior owner can continue
+immediately when he is genuinely alone. Stale members and audit-only
+`target=any` event reads do not force a cooldown.
+
+### Solo-polling guidance
+
+The bundled skill and default collaboration instructions now clarify the escape
+hatch for one-agent rooms: if you are the only active member, stop polling after
+a clear handoff instead of churning release/reclaim turns. Brief quiet periods
+from another active agent are not enough to declare yourself alone.
+
+## Verification
+
+```bash
+npm run typecheck
+npm run build
+npm test
+git diff --check
+npm pack --dry-run
+```

package/docs/releases/0.4.2.md

@@ -0,0 +1,41 @@
+# Talking Stick 0.4.2
+
+Date: 2026-05-10
+
+This patch moves guardian liveness back into the CLI contract. Agents should not
+manually inspect guardian PIDs after `tt wait`; a `your_turn` result means the
+CLI has confirmed or spawned the guardian it needs, and guardian setup failures
+surface as command failures.
+
+## Fixed
+
+### Guardian ownership contract
+
+`tt wait` now repairs an already-owned turn when the local CLI session has no
+recorded guardian PID. This can happen after local session-file loss or partial
+state cleanup: the room still knows the caller owns the turn, but the foreground
+CLI no longer has a guardian process recorded. Instead of returning
+`your_turn` with `guardian_pid: null`, the CLI now starts a replacement guardian,
+records it, and returns that PID.
+
+Known-uncertain liveness with an existing PID is still left alone. That avoids
+respawning guardians repeatedly on platforms or process-start formats where
+exact liveness cannot be proven.
+
+### Harness guidance
+
+The bundled skill, README, and receive-consumer contract now describe
+`tt wait`/`tt take` as the ownership gate. Event streams remain observer-only:
+an event wake can tell an agent to read, reply, or retry `tt wait`, but it does
+not grant workspace write authority.
+
+## Verification
+
+```bash
+npm run typecheck
+npx vitest run tests/cli.test.ts -t guardian
+npm test
+npm run build
+node dist/cli.js --help
+git diff --check
+```

package/package.json

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

package/skills/talking-stick/SKILL.md

@@ -95,7 +95,7 @@ Possible outcomes:
 - `takeover_available`: surface the reason and make takeover explicit
 - `closed`: stop and explain that the room is closed
 
-A successful `tt wait` or `tt take` starts an internal `tt guard` lease guardian and returns `guardian_pid` in JSON. Verify the field is present and the pid is alive before you start a long edit; the guardian is what keeps your lease from expiring after the foreground `tt wait` process exits. If `guardian_pid` is missing or the pid is gone, stop, run `tt wait` again to repair the guardian (it will detect the existing ownership and respawn the guardian), and only then continue. Do not kill that guardian.
+A successful `tt wait` or `tt take` starts an internal `tt guard` lease guardian and returns `guardian_pid` in JSON. Trust `tt wait`: a `your_turn` result means the CLI confirmed or spawned a guardian, and if it could not, the command would have failed. Do not kill that guardian.
 
 ### 4. While Waiting
 
@@ -103,7 +103,7 @@ Prefer to run `tt wait` in the background if your harness supports background co
 
 Prefer wait cycles over scheduled wakeups. A direct long-poll stays aligned with other agents and usually notices a released stick within the same cycle. Use scheduled wakeups only when your harness cannot keep a wait running in the background.
 
-Do not replace `tt wait` with an event receiver. `tt events --wait` is only a wake channel for messages and handoff/reservation events. If it exits with a pass, release, assignment, or message, process the event, then run or continue `tt wait --json`; do not touch shared files unless that wait returns `your_turn` and a live `guardian_pid`.
+Do not replace `tt wait` with an event receiver. `tt events --wait` is only a wake channel for messages and handoff/reservation events. If it exits with a pass, release, assignment, or message, process the event, then run or continue `tt wait --json`; do not touch shared files unless that wait returns `your_turn`.
 
 If you do not have the stick:
 
@@ -224,7 +224,7 @@ Exit the wait loop only when one of these is true:
 - the shared task is explicitly finished
 - the operator gives a direct redirect or stop
 
-In every other case, after `tt release` or `tt assign`, go straight back into `tt wait --json`. Other-harness inactivity is not an exit signal; keep waiting or take the next useful action until the task is done.
+In every other case, after `tt release` or `tt assign`, go straight back into `tt wait --json`. If you are the only active member of the room, stop polling after a clear handoff. Treat "only active" as no other member that `tt state --json` reports active or that has been seen in the last hour; if liveness is ambiguous, run one more normal wait cycle instead of churning. Other agents going briefly quiet is not enough to declare yourself alone.
 
 If the operator tells you to drop out of coordination, run `tt leave --json`. Rooms with no active members are deleted instead of kept as history, and long-idle rooms may be purged on later invocations.