talking-stick 0.4.2 → 0.4.3

package/README.md

@@ -93,6 +93,7 @@ tt list            — which rooms exist under a path
 tt join            — join the room for this workspace
 tt leave           — explicitly leave a room; deletes it when no active members remain
 tt wait            — block until the stick is available, with takeover signals
+tt wait --park     — stay coordinated without auto-claiming idle rooms
 tt release         — normal handoff to the next fair waiter, with structured Handoff
 tt assign          — explicit handoff to a named agent
 tt take            — deliberate claim when the prior holder is gone/stuck
@@ -182,8 +183,8 @@ tt whoami [--explain]                                      # show the resolved C
 tt list [path]                                            # list rooms
 tt join [path] [--force-new]                              # join the room for path
 tt leave [path]                                           # leave the room for path
-tt wait [path] [--timeout 110s]                           # block until your turn
-tt try [path]                                             # non-blocking claim attempt
+tt wait [path] [--timeout 110s] [--park]                  # block until your turn; --park disables idle auto-claim
+tt try [path] [--park]                                    # non-blocking claim attempt
 tt state [path]                                           # full room state
 tt events [path] [--after N] [--limit N] [--wait|--follow] [--event TYPE[,TYPE]] [--target self|any|agent]  # room event log; --wait/--follow long-polls
 tt msg send <recipient|room> <body...> [--interrupt] [--stdin] [--path DIR]  # send an OOB message

package/dist/cli/output.js

@@ -60,6 +60,9 @@ export function formatWaitResult(result) {
                     : "";
                 return `Not your turn — turn ${result.turn_id ?? "?"} is reserved for ${result.reserved_for}${deadline}.`;
             }
+            if (result.reason === "auto_claim_disabled") {
+                return "Parked — auto-claim disabled; idle room left untouched.";
+            }
             return "Not your turn yet.";
         }
         case "closed":
@@ -123,8 +126,8 @@ Commands:
   tt join [path] [--force-new]
   tt leave [path]
   tt kick <agent_id> [path] [--reason TEXT] [--force]
-  tt wait [path] [--timeout 110s]
-  tt try [path]
+  tt wait [path] [--timeout 110s] [--park]
+  tt try [path] [--park]
   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]",
+        usage: "tt wait [path] [--timeout 110s] [--park]",
         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]",
+        usage: "tt try [path] [--park]",
         description: "Check turn availability without waiting.",
         handler: ({ runtime, parsed, cliEntryUrl }) => handleWaitCommand(requireRuntime(runtime), parsed, true, cliEntryUrl)
     },

package/dist/cli/turn-commands.js

@@ -2,17 +2,20 @@ import { clearCliSessionLease, createSystemProcessInspector, findCliSessionByRoo
 import { checkGuardianLiveness, spawnGuardian, stopGuardian } from "./guardian.js";
 import { resolveHandoff } from "./handoff.js";
 import { deriveCliIdentity, resolveTakeoverReason, shouldUseOperatorOverride } from "./identity.js";
-import { parseWaitTimeout } from "./parser.js";
+import { hasOption, normalizeBooleanFlag, parseWaitTimeout } from "./parser.js";
 import { formatWaitResult, printResult } from "./output.js";
 import { requireLeaseSession, upsertSessionFromJoin } from "./session.js";
 export async function handleWaitCommand(runtime, parsed, isTry, cliEntryUrl) {
+    normalizeBooleanFlag(parsed, "park");
+    const park = hasOption(parsed, "park");
     const contextPath = parsed.positionals[0] ?? process.cwd();
     const identity = deriveCliIdentity(parsed);
     const joined = runtime.commands.joinPath(identity, { context_path: contextPath });
     upsertSessionFromJoin(identity, joined);
     const waitResult = await runtime.commands.waitForTurn(identity, {
         room_id: joined.room_id,
-        max_wait_ms: isTry ? 0 : parseWaitTimeout(parsed)
+        max_wait_ms: isTry ? 0 : parseWaitTimeout(parsed),
+        auto_claim: park ? false : undefined
     });
     if (waitResult.status === "your_turn") {
         if (waitResult.reason === "already_owner") {

package/dist/commands.js

@@ -37,7 +37,8 @@ export class TalkingStickCommands {
         return this.service.waitForTurn({
             agent_id: identity.agent_id,
             room_id: input.room_id,
-            max_wait_ms: input.max_wait_ms
+            max_wait_ms: input.max_wait_ms,
+            auto_claim: input.auto_claim
         });
     }
     heartbeat(identity, input) {

package/dist/instructions.js

@@ -6,7 +6,9 @@ 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. If you are the only active member of the room, stop polling after a clear handoff rather than churning release/reclaim turns.
+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. If you have no expected work and are blocked on operator input or an external signal, use \`tt wait --park --json\` so you stay coordinated without auto-claiming idle turns.
+
+On freshly invoked multi-agent tasks, give peers a short window to join before deciding you are alone. Use a normal wait timeout or spend about a minute on read-only repo orientation while other harnesses appear.
 
 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

@@ -656,6 +656,19 @@ export class TalkingStickService {
             };
         }
         if (!room.owner && !room.reserved_for) {
+            const autoClaim = input.auto_claim ?? true;
+            if (!autoClaim) {
+                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: "auto_claim_disabled"
+                };
+            }
             if (this.shouldDeferIdleClaim(room, input.agent_id, now)) {
                 return {
                     status: "not_yet",

package/docs/plans/2026-05-10-wait-park-mode.md

@@ -0,0 +1,137 @@
+# Park mode for `tt wait`
+
+**Status:** Implemented in working tree (claude:b8175be6 + codex:0c293df7). Original checklist retained as design context.
+
+**Origin:** Coordination churn observed during the guardian-contract session on 2026-05-10. After a no-work release, the just-released agent's next `tt wait` auto-claimed the idle room because the existing `shouldDeferIdleClaim` cooldown is gated on `hasOtherActiveRoomMember`, which was false when the other agent went briefly inactive. Sequence: claim → release → claim → release with no work in between (turns 247–248 in this room; turns 1205–1291 earlier with claude:b2c853ee). Independently surfaced from both sides; design draft in room note `722adc99-1f1e-4e83-a950-5176dce3ae1c`.
+
+## Problem
+
+`tt wait` is overloaded as two operations:
+
+1. Wait for a turn that will be handed to me (reserved_for me, pass/assign to me, takeover).
+2. Claim the room if it is idle (auto-claim).
+
+The second operation is correct when the caller has work. When the caller has no work but is staying coordinated (waiting on operator input or other external signal), it produces the churn pattern. The existing `priorOwnerReleaseCooldownMs` heuristic helps but can't encode operator-wait intent — only the caller knows whether they have work.
+
+## Design
+
+Add a protocol-level opt-out for the idle auto-claim. The two operations split cleanly:
+
+- **`tt wait`** (current behavior, unchanged): caller is willing to take the stick now. Auto-claim is on.
+- **`tt wait --park`**: caller wants to stay coordinated but only act on explicit signals. Auto-claim is off. Already-owner, reserved-to-me, pass-to-me, and takeover-available still return `your_turn` / `takeover_available` normally.
+
+**Protocol field:** `WaitForTurnInput.auto_claim?: boolean` (default `true`). The CLI flag `--park` sets `auto_claim: false`. Naming separation is deliberate — `auto_claim` is the precise protocol invariant; `--park` is the UX vocabulary.
+
+**Filtered branches under `auto_claim: false`:**
+
+- `!room.owner && !room.reserved_for` → `grantTurn` (service.ts:1107) is the **only** auto-claim path. Park returns `not_yet` with reason `auto_claim_disabled` here.
+
+**Preserved branches:**
+
+- already_owner (service.ts:1090) — true signal, return your_turn.
+- reserved_for === caller (service.ts:1138) — explicit pass, return your_turn.
+- recipient_gone / owner_gone / stale_owner / claim_timeout (service.ts:1122, 1146, 1162, 1173) — return takeover_available. Park = no automatic ownership, not blind recovery.
+- closed (service.ts:1086) — unchanged.
+- default not_yet (service.ts:1184) — unchanged.
+
+**Fair routing:** parked agents stay eligible for `tt assign next`. Park opts out of automatic claim, not explicit routing.
+
+**Cooldown:** `shouldDeferIdleClaim` is unchanged. Park is the explicit-intent mechanism; the cooldown is a heuristic for the no-park case. Tightening the cooldown to fire when alone would be a silent semantic change for plain `tt wait` callers and is the wrong tool.
+
+## Implementation
+
+### `src/service.ts`
+
+Add `auto_claim?: boolean` to `WaitForTurnInput`. In `waitForTurnOnce` (line 1078), gate the idle branch:
+
+```ts
+if (!room.owner && !room.reserved_for) {
+  const autoClaim = input.auto_claim ?? true;
+  if (!autoClaim) {
+    return {
+      status: "not_yet",
+      room_state: inspection.state,
+      turn_id: room.turn_id,
+      reason: "auto_claim_disabled"
+    };
+  }
+  if (this.shouldDeferIdleClaim(room, input.agent_id, now)) {
+    return { status: "not_yet", /* existing fields */ };
+  }
+  return this.grantTurn(room, input.agent_id, now);
+}
+```
+
+Add `auto_claim_disabled` to the `not_yet` reason union.
+
+### MCP surface
+
+No MCP schema change is needed in the current CLI-only implementation. The older `src/mcp-server.ts` surface no longer exists; `src/commands.ts` carries the command-level `auto_claim` field through to the service.
+
+### `src/cli/parser.ts`
+
+Use `normalizeBooleanFlag(parsed, "park")` in the wait/try handler so `--park` can appear before or after the optional path. The generic parser still consumes the next non-`--` token by default; normalization restores that consumed token as a positional for this boolean flag.
+
+### `src/cli/turn-commands.ts`
+
+In `handleWaitCommand`:
+
+```ts
+normalizeBooleanFlag(parsed, "park");
+const park = hasOption(parsed, "park");
+const waitResult = await runtime.commands.waitForTurn(identity, {
+  room_id: joined.room_id,
+  max_wait_ms: isTry ? 0 : parseWaitTimeout(parsed),
+  auto_claim: park ? false : undefined
+});
+```
+
+Update `formatWaitResult` to print `Parked — auto-claim disabled; idle room left untouched.` when `status: "not_yet"` and `reason: "auto_claim_disabled"`.
+
+### `skills/talking-stick/SKILL.md`
+
+In §8 "After Release, Stay In The Loop", add after the "stop polling if only active member" rule:
+
+> If you have no expected work and are blocked on operator input or external signal, use `tt wait --park` instead of `tt wait` to stay coordinated without claiming idle turns. Park returns `your_turn` only for explicit signals (reserved-to-me, pass/assign to me, takeover-available); it never auto-claims an idle room. Switch back to plain `tt wait` once you have work to do.
+
+Add `tt wait --park` to the CLI list in §1.
+
+### `README.md`
+
+Add `--park` to the `tt wait` line in the CLI cheat sheet (~line 100). One-line description under it: "Stay coordinated without auto-claiming idle turns."
+
+### `CHANGELOG.md`
+
+Unreleased Added entry:
+
+```
+- **`tt wait --park`.** New flag opts out of idle-room auto-claim while keeping the agent coordinated for explicit passes, assignments, and takeover signals. Use when waiting on operator input without intent to take the next idle turn. Protocol-level field is `wait_for_turn.auto_claim` (default true).
+```
+
+## Tests
+
+Add to `tests/talking-stick.test.ts` and `tests/cli.test.ts`:
+
+- **service**: `waitForTurn with auto_claim=false on an idle room returns not_yet with reason auto_claim_disabled` (regression for this session's churn).
+- **service**: `waitForTurn with auto_claim=false when reserved_for == caller returns your_turn`.
+- **service**: `waitForTurn with auto_claim=false when caller is already owner returns your_turn`.
+- **service**: `waitForTurn with auto_claim=false surfaces takeover_available for stale owner` (and for claim_timeout, recipient_gone, owner_gone).
+- **service**: `waitForTurn with auto_claim=false returns not_yet when another agent owns the stick`.
+- **service**: plain `waitForTurn` (auto_claim default true) still claims idle rooms — pin no-regression.
+- **CLI**: `tt wait --park` against an idle room exits with not_yet, no guardian spawned, no claim event in the log.
+- **CLI**: `tt wait --park` against a reservation-to-me returns your_turn with a live guardian.
+
+## Out of scope
+
+- No change to `shouldDeferIdleClaim` (line 2066) or `priorOwnerReleaseCooldownMs`.
+- No new `tt park` verb. `--park` flag is the only surface in v1.
+- No change to how parked agents are heartbeat-tracked; they remain active members.
+- No change to fair-routing eligibility; parked agents stay in the `tt assign next` pool.
+
+## Verification
+
+`npm run typecheck && npm test && npm run build`. Manual smoke: in a two-agent room, agent A releases with no work, runs `tt wait --park --timeout 5s` — expect `not_yet, reason: auto_claim_disabled` and no claim event. Then agent B does `tt assign next` — agent A's next park wait should return `your_turn`. Then agent A releases and runs plain `tt wait --timeout 5s` — expect your_turn (auto-claim restored).
+
+## Commit message
+
+`Add tt wait --park for non-claiming coordination`

package/docs/releases/0.4.3.md

@@ -0,0 +1,48 @@
+# Talking Stick 0.4.3
+
+Date: 2026-05-11
+
+This patch adds a parked wait mode for agents that need to remain coordinated
+without taking an idle turn. It addresses release/reclaim churn during pauses
+for operator input while preserving the existing `tt wait` behavior for agents
+that are ready to work.
+
+## Added
+
+### `tt wait --park`
+
+`tt wait --park` and `tt try --park` now opt out of idle-room auto-claim. The
+underlying service/command field is `auto_claim`, which defaults to true for
+the existing behavior. When false, an idle room returns `not_yet` with
+`reason: "auto_claim_disabled"` and does not mint a claim event or start a
+guardian.
+
+Parked waits still return actionable signals:
+
+- already-owned turns remain `your_turn`
+- explicit passes or assignments to the caller still become `your_turn`
+- takeover availability is still surfaced
+
+Plain `tt wait` is unchanged and still auto-claims idle rooms.
+
+## Changed
+
+### Coordination guidance
+
+The bundled skill and default editable instructions now tell agents to use
+`tt wait --park --json` when they have no expected work and are blocked on
+operator input or an external signal. They also remind freshly invoked agents
+to give peers a short window to join before concluding they are alone, using
+normal waits or read-only repo orientation while other harnesses appear.
+
+## Verification
+
+```bash
+npm run typecheck
+npx vitest run tests/talking-stick.test.ts tests/cli.test.ts -t "auto_claim=false|tt wait --park|auto_claim default"
+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.2",
+  "version": "0.4.3",
   "description": "CLI coordination tool for path-scoped agent handoffs.",
   "type": "module",
   "bin": {

package/skills/talking-stick/SKILL.md

@@ -32,6 +32,7 @@ Useful commands:
 - `tt whoami --json`
 - `tt join --json`
 - `tt wait --json`
+- `tt wait --park --json`
 - `tt try --json`
 - `tt state --json`
 - `tt events --after N --target any --json`
@@ -60,6 +61,8 @@ tt join --json
 
 Keep the returned room id and canonical path in mind. The current working directory is the implicit path for normal commands; pass an explicit path only when coordinating a different directory or intentionally selecting a nested room.
 
+On freshly invoked multi-agent tasks, give peers a short window to join before deciding you are alone. Use a normal wait timeout or spend about a minute on read-only repo orientation while other harnesses appear.
+
 After joining, load editable collaboration instructions once:
 
 ```sh
@@ -226,6 +229,8 @@ Exit the wait loop only when one of these is true:
 
 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 you have no expected work and are blocked on operator input or an external signal, use `tt wait --park --json` instead of `tt wait --json` to stay coordinated without claiming idle turns. Park still surfaces explicit passes, assignments, and takeover availability; it never auto-claims an idle room. Switch back to plain `tt wait --json` once you have work to do.
+
 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.
 
 If the room state shows ghost members from past sessions whose processes are gone, run `tt kick <agent_id> --json` to evict them. Use `--force` only when the operator explicitly tells you to remove a still-active member.