talking-stick 0.4.1 → 0.4.2

package/README.md

@@ -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/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.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.1",
+  "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: