talking-stick 0.4.2 → 0.4.4

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
@@ -229,7 +230,7 @@ Use `tt whoami --explain` to see which identity path the CLI chose.
 - **Structured handoffs.** `release_stick` and `pass_stick` carry a typed `Handoff` with required `status` / `next_action` and optional `artifacts[]` pointing at specific files and line ranges.
 - **Fair handoff selection.** Normal release prefers a recent waiter that is new or has gone longest without holding the stick; if the best-known candidate is between wait polls, a short grace window prevents immediate recycling to a less-fair claimant.
 - **No immediate take-backs.** If release leaves a handoff idle, the prior owner waits through the short grace window before reclaiming while another member exists.
-- **Ephemeral rooms.** `leave_room`/`tt leave` removes membership, rooms with no active members are physically deleted, and long-idle rooms are purged opportunistically on later invocations.
+- **Ephemeral rooms.** `leave_room`/`tt leave` removes membership, rooms with no active members are physically deleted, and long-idle rooms with no recent activity or provably live member process are purged opportunistically on later invocations. The default idle retention is seven days.
 - **Fencing tokens.** `lease_id` + `turn_id` make stale writes impossible — an agent who lost their turn cannot commit anything under the room's name.
 - **Liveness-aware recovery.** Dead or crashed holders are detected with OS-level process checks; claim-timeout takeover skips the prior owner when another active member is waiting.
 - **Multi-process safe.** Shared SQLite with WAL mode, `BEGIN IMMEDIATE` writes, 250 ms polling for `wait_for_turn`. No daemon required.
@@ -257,6 +258,11 @@ npm run build
 
 See [`CHANGELOG.md`](CHANGELOG.md) for a per-version summary; full release notes live in [`docs/releases/`](docs/releases/).
 
+When cutting a release, add entries under `CHANGELOG.md`'s `Unreleased` section,
+then run `npm version <new-version>`. The version lifecycle script moves those
+entries into the new version section, writes `docs/releases/<version>.md`, and
+adds the GitHub release link before npm commits and tags the version.
+
 ## Read next
 
 - [`docs/talking-stick-plan.md`](docs/talking-stick-plan.md) — full protocol, state transitions, persistence model, design rationale, and open questions.

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",
@@ -1194,7 +1207,7 @@ export class TalkingStickService {
                 if (this.latestRoomActivityMs(room, members) > cutoffMs) {
                     continue;
                 }
-                if (members.some((member) => this.isMemberActive(member, now))) {
+                if (members.some((member) => this.shouldRetainIdleRoom(member, now))) {
                     continue;
                 }
                 this.deleteRoom(room.room_id);
@@ -1226,6 +1239,16 @@ export class TalkingStickService {
         }
         return this.hasRecentPresence(member, now);
     }
+    shouldRetainIdleRoom(member, now) {
+        const liveness = this.getMemberProcessLiveness(member);
+        if (liveness === "alive") {
+            return true;
+        }
+        if (liveness === "gone") {
+            return false;
+        }
+        return this.hasRecentPresence(member, now);
+    }
     hasRecentPresence(member, now) {
         return (now.getTime() - Date.parse(member.last_seen_at) <=
             this.policy.presenceTtlMs);

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/docs/releases/0.4.4.md

@@ -0,0 +1,23 @@
+# Talking Stick 0.4.4
+
+Date: 2026-05-12
+
+## Added
+- **Automatic release prep.** `npm version <new-version>` now runs `scripts/prepare-release.mjs`, moving `CHANGELOG.md`'s `Unreleased` entries into the new version section, creating `docs/releases/<version>.md`, and adding the GitHub release link before npm creates the version commit/tag.
+
+## Changed
+- **Ambient receiver guidance.** The shipped skill now says to run exactly one streaming ambient receiver per session, and warns that exit-notify background commands silently swallow `tt events --follow` output instead of surfacing mid-task events.
+
+## Fixed
+- **Idle-room retention.** Opportunistic cleanup still deletes long-idle rooms after the seven-day default retention, but it now preserves a room when any recorded member process is provably still alive. Once no member is recently active or live, the same cleanup path removes the room and its member, event, and note rows.
+
+## 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

@@ -747,6 +747,7 @@ wait_for_turn_poll_ms      = 250;                  // transport polling cadence
 wait_for_events_max_wait_ms = 110 * 1000;          // 110 seconds
 presence_ttl_ms            =  4 * 60 * 60 * 1000;  // 4 hours
 waiter_grace_ms            = 10 * 1000;            // 10 seconds
+idle_room_ttl_ms           =  7 * 24 * 60 * 60 * 1000; // 7 days
 ```
 
 Timeout meanings:
@@ -757,6 +758,7 @@ Timeout meanings:
 - `owner_lease_ttl` is how long an owner may remain silent before takeover becomes possible.
 - `presence_ttl` determines whether a member is active for sequence selection and takeover eligibility.
 - `waiter_grace_ms` is the short window used to identify recent waiters and to avoid immediately recycling the turn while a fairer known member is between wait polls.
+- `idle_room_ttl` is the retention window for dormant coordination history. Opportunistic cleanup only purges a long-idle room when no member has recent presence and no recorded member process is provably still alive.
 
 Rationale for these defaults: a real agent turn often runs 20-30 minutes (plan-and-edit, build-and-verify, review-and-respond), and a human collaborator walking through a few rooms may easily be idle for an hour without being "gone." Earlier drafts inherited chat-scale defaults (5-minute lease, 10-minute presence) which would silently open takeover windows mid-turn. The selected values accept a slower takeover response in exchange for not interrupting legitimate long work; operators who want faster response can shorten them via per-room policy once that ships.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "talking-stick",
-  "version": "0.4.2",
+  "version": "0.4.4",
   "description": "CLI coordination tool for path-scoped agent handoffs.",
   "type": "module",
   "bin": {
@@ -21,6 +21,7 @@
     "postinstall": "node scripts/postinstall-mcp-cleanup.cjs",
     "prepare": "tsc -p tsconfig.build.json && chmod +x dist/cli.js",
     "test": "vitest run",
+    "version": "node scripts/prepare-release.mjs --from-package",
     "typecheck": "tsc -p tsconfig.json --noEmit"
   },
   "dependencies": {

package/scripts/prepare-release.mjs

@@ -0,0 +1,261 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import path from "node:path";
+import process from "node:process";
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+const CHANGELOG_PATH = "CHANGELOG.md";
+const RELEASES_DIR = path.join("docs", "releases");
+const PACKAGE_PATH = "package.json";
+const RELEASE_URL_PREFIX =
+  "https://github.com/mostlydev/talking-stick/releases/tag/v";
+
+function main() {
+  const options = parseArgs(process.argv.slice(2));
+  const version = options.fromPackage
+    ? readPackageVersion()
+    : options.version;
+  if (!version) {
+    throw new Error("Usage: prepare-release --from-package | --version VERSION");
+  }
+  assertVersion(version);
+
+  const date = options.date ?? new Date().toISOString().slice(0, 10);
+  const changelog = readText(CHANGELOG_PATH);
+  const { nextChangelog, releaseBody } = prepareChangelog({
+    changelog,
+    version,
+    date
+  });
+
+  const releasePath = path.join(RELEASES_DIR, `${version}.md`);
+  if (fs.existsSync(releasePath)) {
+    throw new Error(`${releasePath} already exists.`);
+  }
+
+  fs.mkdirSync(RELEASES_DIR, { recursive: true });
+  writeText(CHANGELOG_PATH, nextChangelog);
+  writeText(releasePath, renderReleaseNotes(version, date, releaseBody));
+  stageGeneratedFiles([CHANGELOG_PATH, releasePath]);
+
+  console.log(`Prepared release notes for ${version}.`);
+}
+
+function parseArgs(args) {
+  const options = {
+    fromPackage: false,
+    version: undefined,
+    date: undefined
+  };
+
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === "--from-package") {
+      options.fromPackage = true;
+      continue;
+    }
+    if (arg === "--version") {
+      options.version = requireValue(args, (index += 1), "--version");
+      continue;
+    }
+    if (arg === "--date") {
+      options.date = requireValue(args, (index += 1), "--date");
+      continue;
+    }
+    throw new Error(`Unknown option: ${arg}`);
+  }
+
+  if (options.fromPackage && options.version) {
+    throw new Error("Use either --from-package or --version, not both.");
+  }
+
+  return options;
+}
+
+function requireValue(args, index, name) {
+  const value = args[index];
+  if (!value || value.startsWith("--")) {
+    throw new Error(`${name} requires a value.`);
+  }
+  return value;
+}
+
+function readPackageVersion() {
+  const parsed = JSON.parse(readText(PACKAGE_PATH));
+  if (typeof parsed.version !== "string") {
+    throw new Error("package.json does not contain a string version.");
+  }
+  return parsed.version;
+}
+
+function assertVersion(version) {
+  if (!/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/.test(version)) {
+    throw new Error(`Invalid release version: ${version}`);
+  }
+}
+
+export function prepareChangelog({ changelog, version, date }) {
+  const lines = changelog.replace(/\r\n/g, "\n").split("\n");
+  const unreleasedIndex = lines.findIndex((line) => line === "## Unreleased");
+  if (unreleasedIndex === -1) {
+    throw new Error("CHANGELOG.md must contain a '## Unreleased' section.");
+  }
+
+  const duplicateIndex = lines.findIndex(
+    (line) => line === `## [${version}] — ${date}` || line.startsWith(`## [${version}] `)
+  );
+  if (duplicateIndex !== -1) {
+    throw new Error(`CHANGELOG.md already contains a ${version} section.`);
+  }
+
+  const nextSectionIndex = findNextVersionHeading(lines, unreleasedIndex + 1);
+  const unreleasedBody = trimBlankLines(
+    lines.slice(unreleasedIndex + 1, nextSectionIndex)
+  );
+
+  if (unreleasedBody.length === 0) {
+    throw new Error("CHANGELOG.md Unreleased section is empty.");
+  }
+
+  const releaseSection = [
+    "## Unreleased",
+    "",
+    `## [${version}] — ${date}`,
+    "",
+    `Full notes: [\`docs/releases/${version}.md\`](docs/releases/${version}.md).`,
+    "",
+    ...unreleasedBody,
+    ""
+  ];
+
+  const nextLines = [
+    ...lines.slice(0, unreleasedIndex),
+    ...releaseSection,
+    ...lines.slice(nextSectionIndex)
+  ];
+
+  const nextChangelog = ensureReleaseLink(
+    `${nextLines.join("\n").replace(/\n*$/, "")}\n`,
+    version
+  );
+
+  return {
+    nextChangelog,
+    releaseBody: unreleasedBody.join("\n")
+  };
+}
+
+function findNextVersionHeading(lines, startIndex) {
+  const nextIndex = lines.findIndex(
+    (line, index) => index >= startIndex && /^##\s+/.test(line)
+  );
+  return nextIndex === -1 ? lines.length : nextIndex;
+}
+
+function trimBlankLines(lines) {
+  let start = 0;
+  let end = lines.length;
+  while (start < end && lines[start].trim() === "") {
+    start += 1;
+  }
+  while (end > start && lines[end - 1].trim() === "") {
+    end -= 1;
+  }
+  return lines.slice(start, end);
+}
+
+function ensureReleaseLink(changelog, version) {
+  const reference = `[${version}]: ${RELEASE_URL_PREFIX}${version}`;
+  const lines = changelog.replace(/\r\n/g, "\n").split("\n");
+
+  if (lines.some((line) => line.startsWith(`[${version}]:`))) {
+    return changelog;
+  }
+
+  const firstReferenceIndex = lines.findIndex((line) =>
+    /^\[[^\]]+\]:\s+/.test(line)
+  );
+  if (firstReferenceIndex === -1) {
+    return `${changelog.replace(/\n*$/, "")}\n\n${reference}\n`;
+  }
+
+  lines.splice(firstReferenceIndex, 0, reference);
+  return `${lines.join("\n").replace(/\n*$/, "")}\n`;
+}
+
+function renderReleaseNotes(version, date, changelogBody) {
+  return `# Talking Stick ${version}
+
+Date: ${date}
+
+${renderReleaseBody(changelogBody)}
+
+## Verification
+
+\`\`\`bash
+npm run typecheck
+npm test
+npm run build
+node dist/cli.js --help
+git diff --check
+npm pack --dry-run
+\`\`\`
+`;
+}
+
+function renderReleaseBody(changelogBody) {
+  return changelogBody
+    .split("\n")
+    .map((line) => {
+      const heading = /^(#{3,})\s+(.+)$/.exec(line);
+      if (!heading) {
+        return line;
+      }
+      return `${heading[1].slice(1)} ${heading[2]}`;
+    })
+    .join("\n");
+}
+
+function readText(filePath) {
+  return fs.readFileSync(filePath, "utf8");
+}
+
+function writeText(filePath, content) {
+  fs.writeFileSync(filePath, content, "utf8");
+}
+
+function stageGeneratedFiles(filePaths) {
+  if (
+    process.env.npm_lifecycle_event !== "version" ||
+    process.env.npm_config_git_tag_version === "false"
+  ) {
+    return;
+  }
+
+  const insideWorkTree = spawnSync("git", ["rev-parse", "--is-inside-work-tree"], {
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "ignore"]
+  });
+  if (
+    insideWorkTree.status !== 0 ||
+    insideWorkTree.stdout.trim() !== "true"
+  ) {
+    return;
+  }
+
+  const add = spawnSync("git", ["add", ...filePaths], {
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "pipe"]
+  });
+  if (add.status !== 0) {
+    throw new Error(add.stderr.trim() || "Failed to stage release files.");
+  }
+}
+
+if (
+  process.argv[1] &&
+  path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)
+) {
+  main();
+}

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
@@ -68,13 +71,17 @@ tt instructions show --json
 
 If that command fails, continue with this bundled skill. Editable instructions can add local preferences, but they do not override the safety rules in this skill.
 
-Right after joining, start a background ambient receiver so direct messages and turn passes/reservations surface as soon as they happen instead of waiting for the next time you poll:
+Right after joining, start exactly one background ambient receiver so direct messages and turn passes/reservations surface as soon as they happen instead of waiting for the next time you poll:
 
 ```sh
 tt events --follow --json
 ```
 
-For `tt events --wait` and `tt events --follow`, the default target is `self`; add `--target any` only for audit/debug views. If your harness can stream a child process's stdout into the model's context (Claude Code's Monitor, Codex `attach`-style), this is enough — each line becomes an event you see mid-task. If your harness can only notice that a backgrounded command exits, use the polling fallback in §4.5. Without an ambient receiver, neither messages nor turn handoffs reach you between deliberate `tt wait` / `tt events` calls.
+For `tt events --wait` and `tt events --follow`, the default target is `self`; add `--target any` only for audit/debug views.
+
+The receiver must stream stdout line-by-line into your model context (Claude Code's Monitor, Codex `attach`-style) so each event becomes a notification you see mid-task. A backgrounded shell that only notifies when the process exits is **not** an ambient receiver — it silently swallows every event until termination, then fires a single useless notification at the end. If your harness can only observe process-exit, use the polling fallbacks in §4.5 instead; do not dress an exit-notify background command up as a stream consumer.
+
+Run exactly one ambient receiver per session. A second `tt events --follow` does not add coverage — both instances compete for the same stream, and one of them is likely silently consuming events you will never see. If you need a different filter, stop the existing receiver first.
 
 The ambient receiver is not a turn claimant. It never grants the stick and never starts the lease guardian. Keep using `tt wait --json` for ownership.
 
@@ -226,6 +233,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.