talking-stick 0.4.3 → 0.4.4

package/README.md

@@ -230,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.
@@ -258,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/service.js

@@ -1207,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);
@@ -1239,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/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.3",
+  "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

@@ -71,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.