talking-stick 0.1.0-alpha.5 → 0.1.0

package/README.md

@@ -2,7 +2,7 @@
 
 An MCP coordination server 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.1.0-alpha.5. Multi-process-safe (SQLite WAL), liveness-aware, no daemon. Supports Claude Code, Codex CLI, Gemini CLI, and OpenCode out of the box.
+**Version:** 0.1.0. Multi-process-safe (SQLite WAL), liveness-aware, no daemon. Supports Claude Code, Codex CLI, Gemini CLI, and OpenCode out of the box.
 
 ## Quickstart
 
@@ -27,7 +27,7 @@ That's it. The next time two agents `cd` into the same repo, they see each other
 
 | Method | Command | Notes |
 |---|---|---|
-| **From npm** | `npm i -g talking-stick` | Published as `0.1.0-alpha.5`. Requires Node ≥ 22. |
+| **From npm** | `npm i -g talking-stick` | Published as `0.1.0`. 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. |
 

package/dist/cli/install-commands.js

@@ -143,9 +143,7 @@ function runInheritIo(command, args) {
 function reportInstallResults(results, mode) {
     let anyFailed = false;
     for (const result of results) {
-        if (result.skipped)
-            continue;
-        const status = result.ok ? "ok" : "FAIL";
+        const status = formatInstallStatus(result.status);
         process.stdout.write(`[${result.harness}] ${status}: ${result.message}\n`);
         if (!result.ok)
             anyFailed = true;
@@ -154,3 +152,6 @@ function reportInstallResults(results, mode) {
         throw new Error(`${mode} completed with failures.`);
     }
 }
+function formatInstallStatus(status) {
+    return status.replaceAll("_", "-");
+}

package/dist/install.js

@@ -130,7 +130,10 @@ export function planInstall(harness, options = {}) {
                 harness,
                 command: "claude",
                 args: ["mcp", "add", "-s", "user", resolved.serverName, "--", serverBin, ...serverArgs],
-                description: `claude mcp add -s user ${resolved.serverName} -- ${resolved.serverCommand.join(" ")}`
+                description: `claude mcp add -s user ${resolved.serverName} -- ${resolved.serverCommand.join(" ")}`,
+                operation: "install",
+                serverName: resolved.serverName,
+                serverCommand: resolved.serverCommand
             };
         case "codex":
             if (resolved.skipMissing && !resolved.hooks.which("codex")) {
@@ -141,7 +144,10 @@ export function planInstall(harness, options = {}) {
                 harness,
                 command: "codex",
                 args: ["mcp", "add", resolved.serverName, "--", serverBin, ...serverArgs],
-                description: `codex mcp add ${resolved.serverName} -- ${resolved.serverCommand.join(" ")}`
+                description: `codex mcp add ${resolved.serverName} -- ${resolved.serverCommand.join(" ")}`,
+                operation: "install",
+                serverName: resolved.serverName,
+                serverCommand: resolved.serverCommand
             };
         case "gemini":
             if (resolved.skipMissing && !resolved.hooks.which("gemini")) {
@@ -152,7 +158,10 @@ export function planInstall(harness, options = {}) {
                 harness,
                 command: "gemini",
                 args: ["mcp", "add", "-s", "user", "-t", "stdio", resolved.serverName, serverBin, ...serverArgs],
-                description: `gemini mcp add -s user -t stdio ${resolved.serverName} ${resolved.serverCommand.join(" ")}`
+                description: `gemini mcp add -s user -t stdio ${resolved.serverName} ${resolved.serverCommand.join(" ")}`,
+                operation: "install",
+                serverName: resolved.serverName,
+                serverCommand: resolved.serverCommand
             };
         case "opencode": {
             const filePath = resolveOpencodeConfigPath(options);
@@ -165,6 +174,9 @@ export function planInstall(harness, options = {}) {
                 harness,
                 filePath,
                 description: `merge mcp.${resolved.serverName} into ${filePath}`,
+                operation: "install",
+                serverName: resolved.serverName,
+                inspect: () => inspectOpencodeConfig(filePath, resolved),
                 apply: () => patchOpencodeConfig(filePath, resolved, "install")
             };
         }
@@ -184,7 +196,9 @@ export function planUninstall(harness, options = {}) {
                 harness,
                 command: "claude",
                 args: ["mcp", "remove", "-s", "user", resolved.serverName],
-                description: `claude mcp remove -s user ${resolved.serverName}`
+                description: `claude mcp remove -s user ${resolved.serverName}`,
+                operation: "uninstall",
+                serverName: resolved.serverName
             };
         case "codex":
             if (resolved.skipMissing && !resolved.hooks.which("codex")) {
@@ -195,7 +209,9 @@ export function planUninstall(harness, options = {}) {
                 harness,
                 command: "codex",
                 args: ["mcp", "remove", resolved.serverName],
-                description: `codex mcp remove ${resolved.serverName}`
+                description: `codex mcp remove ${resolved.serverName}`,
+                operation: "uninstall",
+                serverName: resolved.serverName
             };
         case "gemini":
             if (resolved.skipMissing && !resolved.hooks.which("gemini")) {
@@ -206,7 +222,9 @@ export function planUninstall(harness, options = {}) {
                 harness,
                 command: "gemini",
                 args: ["mcp", "remove", "-s", "user", resolved.serverName],
-                description: `gemini mcp remove -s user ${resolved.serverName}`
+                description: `gemini mcp remove -s user ${resolved.serverName}`,
+                operation: "uninstall",
+                serverName: resolved.serverName
             };
         case "opencode": {
             const filePath = resolveOpencodeConfigPath(options);
@@ -222,6 +240,9 @@ export function planUninstall(harness, options = {}) {
                 harness,
                 filePath,
                 description: `remove mcp.${resolved.serverName} from ${filePath}`,
+                operation: "uninstall",
+                serverName: resolved.serverName,
+                inspect: () => inspectOpencodeConfig(filePath, resolved),
                 apply: () => patchOpencodeConfig(filePath, resolved, "uninstall")
             };
         }
@@ -264,6 +285,47 @@ function patchOpencodeConfig(filePath, resolved, mode) {
     resolved.hooks.ensureDir(path.dirname(filePath));
     resolved.hooks.writeFile(filePath, JSON.stringify(config, null, 2) + "\n");
 }
+function inspectOpencodeConfig(filePath, resolved) {
+    const existing = resolved.hooks.readFile(filePath);
+    if (existing === null)
+        return "absent";
+    let config;
+    try {
+        config = parseJsonOrThrow(existing, filePath);
+    }
+    catch {
+        return "unknown";
+    }
+    const mcp = isPlainObject(config.mcp) ? config.mcp : {};
+    if (!(resolved.serverName in mcp))
+        return "absent";
+    const expected = {
+        type: "local",
+        command: [...resolved.serverCommand],
+        enabled: true
+    };
+    return valuesEqual(mcp[resolved.serverName], expected) ? "present" : "different";
+}
+function inspectGeminiSettings(action, resolved) {
+    const filePath = path.join(resolveHarnessConfigDirFromResolved("gemini", resolved), "settings.json");
+    const existing = resolved.hooks.readFile(filePath);
+    if (existing === null)
+        return "absent";
+    let config;
+    try {
+        config = parseJsonOrThrow(existing, filePath);
+    }
+    catch {
+        return "unknown";
+    }
+    const servers = isPlainObject(config.mcpServers) ? config.mcpServers : {};
+    const serverName = action.serverName ?? resolved.serverName;
+    if (!(serverName in servers))
+        return "absent";
+    const [command, ...args] = action.serverCommand ?? resolved.serverCommand;
+    const expected = { command, args };
+    return valuesEqual(servers[serverName], expected) ? "present" : "different";
+}
 function parseJsonOrThrow(raw, filePath) {
     try {
         const parsed = JSON.parse(raw);
@@ -279,6 +341,9 @@ function parseJsonOrThrow(raw, filePath) {
 function isPlainObject(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
+function valuesEqual(left, right) {
+    return JSON.stringify(left) === JSON.stringify(right);
+}
 export function detectHarness(harness, options = {}) {
     const resolved = resolveOptions(options);
     switch (harness) {
@@ -333,6 +398,7 @@ export async function runAction(action, options = {}) {
             harness: action.harness,
             ok: true,
             action,
+            status: "skipped",
             message: action.message,
             skipped: true
         };
@@ -344,6 +410,7 @@ export async function runAction(action, options = {}) {
                 harness: action.harness,
                 ok: resolved.skipMissing,
                 action,
+                status: resolved.skipMissing ? "skipped" : "failed",
                 message: `${action.command} not on PATH`,
                 skipped: resolved.skipMissing
             };
@@ -353,9 +420,29 @@ export async function runAction(action, options = {}) {
                 harness: action.harness,
                 ok: false,
                 action,
+                status: "failed",
                 message: invocation.error
             };
         }
+        const beforeState = await inspectExecAction(action, resolved);
+        if (action.operation === "install" && beforeState === "present") {
+            return {
+                harness: action.harness,
+                ok: true,
+                action,
+                status: "already_present",
+                message: formatMcpActionMessage(action, "already_present")
+            };
+        }
+        if (action.operation === "uninstall" && beforeState === "absent") {
+            return {
+                harness: action.harness,
+                ok: true,
+                action,
+                status: "already_absent",
+                message: formatMcpActionMessage(action, "already_absent")
+            };
+        }
         let result;
         try {
             result = await resolved.hooks.run(invocation.command, invocation.args, invocation.options);
@@ -365,31 +452,75 @@ export async function runAction(action, options = {}) {
                 harness: action.harness,
                 ok: false,
                 action,
+                status: "failed",
                 message: formatExecError(error)
             };
         }
         if (result.exitCode === 0) {
+            const status = successStatusForOperation(action.operation, beforeState);
+            return {
+                harness: action.harness,
+                ok: true,
+                action,
+                status,
+                message: formatMcpActionMessage(action, status, result.stdout.trim() || undefined)
+            };
+        }
+        const errorMessage = result.stderr.trim() || result.stdout.trim() || `${action.command} exited with code ${result.exitCode}`;
+        if (action.operation === "install" && isAlreadyPresentMessage(errorMessage)) {
+            return {
+                harness: action.harness,
+                ok: true,
+                action,
+                status: "already_present",
+                message: formatMcpActionMessage(action, "already_present")
+            };
+        }
+        if (action.operation === "uninstall" && isAlreadyAbsentMessage(errorMessage)) {
             return {
                 harness: action.harness,
                 ok: true,
                 action,
-                message: result.stdout.trim() || `${action.command} succeeded`
+                status: "already_absent",
+                message: formatMcpActionMessage(action, "already_absent")
             };
         }
         return {
             harness: action.harness,
             ok: false,
             action,
-            message: (result.stderr.trim() || result.stdout.trim() || `${action.command} exited with code ${result.exitCode}`)
+            status: "failed",
+            message: errorMessage
+        };
+    }
+    const beforeState = action.inspect?.() ?? "unknown";
+    if (action.operation === "install" && beforeState === "present") {
+        return {
+            harness: action.harness,
+            ok: true,
+            action,
+            status: "already_present",
+            message: formatMcpActionMessage(action, "already_present")
+        };
+    }
+    if (action.operation === "uninstall" && beforeState === "absent") {
+        return {
+            harness: action.harness,
+            ok: true,
+            action,
+            status: "already_absent",
+            message: formatMcpActionMessage(action, "already_absent")
         };
     }
     try {
         action.apply();
+        const status = successStatusForOperation(action.operation, beforeState);
         return {
             harness: action.harness,
             ok: true,
             action,
-            message: `Updated ${action.filePath}`
+            status,
+            message: formatMcpActionMessage(action, status, `Updated ${action.filePath}`)
         };
     }
     catch (error) {
@@ -398,6 +529,7 @@ export async function runAction(action, options = {}) {
                 harness: action.harness,
                 ok: true,
                 action,
+                status: "skipped",
                 message: error.message,
                 skipped: true
             };
@@ -406,10 +538,83 @@ export async function runAction(action, options = {}) {
             harness: action.harness,
             ok: false,
             action,
+            status: "failed",
             message: error.message
         };
     }
 }
+async function inspectExecAction(action, resolved) {
+    if (!action.operation || !action.serverName)
+        return "unknown";
+    if (action.harness === "gemini") {
+        return inspectGeminiSettings(action, resolved);
+    }
+    if (action.harness !== "claude-code" && action.harness !== "codex") {
+        return "unknown";
+    }
+    const invocation = resolveCommandInvocation(action.command, ["mcp", "get", action.serverName], resolved);
+    if (!invocation || "error" in invocation)
+        return "unknown";
+    try {
+        const result = await resolved.hooks.run(invocation.command, invocation.args, invocation.options);
+        return result.exitCode === 0 ? "present" : "absent";
+    }
+    catch {
+        return "unknown";
+    }
+}
+function successStatusForOperation(operation, beforeState) {
+    if (operation === "install") {
+        return beforeState === "different" ? "updated" : "added";
+    }
+    if (operation === "uninstall") {
+        return "removed";
+    }
+    return "ok";
+}
+function formatMcpActionMessage(action, status, fallback) {
+    if (!action.serverName || !action.operation) {
+        return fallback ?? "ok";
+    }
+    const target = `MCP server '${action.serverName}'`;
+    const location = mcpConfigLocation(action);
+    switch (status) {
+        case "added":
+            return `${target} registered in ${location}.`;
+        case "updated":
+            return `${target} updated in ${location}.`;
+        case "already_present":
+            return `${target} already registered in ${location}.`;
+        case "removed":
+            return `${target} removed from ${location}.`;
+        case "already_absent":
+            return `${target} is not registered in ${location}.`;
+        default:
+            return fallback ?? "ok";
+    }
+}
+function mcpConfigLocation(action) {
+    if (action.kind === "file-patch")
+        return action.filePath;
+    switch (action.harness) {
+        case "claude-code":
+            return "Claude Code user config";
+        case "codex":
+            return "Codex global config";
+        case "gemini":
+            return "Gemini user config";
+        case "opencode":
+            return "OpenCode config";
+        default:
+            return "harness config";
+    }
+}
+function isAlreadyPresentMessage(message) {
+    return /\balready\b.*\b(exists|configured|present|registered|installed)\b/i.test(message);
+}
+function isAlreadyAbsentMessage(message) {
+    return /\b(not found|does not exist|not configured|not registered|no mcp server)\b/i.test(message);
+}
 export function parseHarnessList(values) {
     const result = [];
     for (const value of values) {
@@ -422,15 +627,18 @@ export function parseHarnessList(values) {
     return result;
 }
 function resolveExecInvocation(action, resolved) {
-    const executable = resolved.hooks.which(action.command);
+    return resolveCommandInvocation(action.command, action.args, resolved);
+}
+function resolveCommandInvocation(command, args, resolved) {
+    const executable = resolved.hooks.which(command);
     if (!executable) {
         return null;
     }
     if (resolved.platform === "win32" && /\.(cmd|bat)$/i.test(executable)) {
-        const unsafeArg = action.args.find(containsWindowsCmdMetacharacter);
+        const unsafeArg = args.find(containsWindowsCmdMetacharacter);
         if (unsafeArg !== undefined) {
             return {
-                error: `Cannot safely launch ${action.command} through cmd.exe because ` +
+                error: `Cannot safely launch ${command} through cmd.exe because ` +
                     `an argument contains Windows command metacharacters (& | < > ^ % ").`
             };
         }
@@ -439,13 +647,13 @@ function resolveExecInvocation(action, resolved) {
             "cmd.exe";
         return {
             command: cmdExe,
-            args: ["/d", "/s", "/c", executable, ...action.args],
+            args: ["/d", "/s", "/c", executable, ...args],
             options: { windowsHide: true }
         };
     }
     return {
         command: executable,
-        args: action.args,
+        args,
         options: resolved.platform === "win32" ? { windowsHide: true } : undefined
     };
 }

package/dist/mcp-server.js

@@ -27,7 +27,7 @@ export function createMcpServer(service = new TalkingStickService()) {
     const resolveConnectionIdentity = createConnectionIdentityResolver();
     const server = new McpServer({
         name: "talking-stick",
-        version: "0.1.0-alpha"
+        version: "0.1.0"
     });
     server.registerTool("list_rooms", {
         title: "List Rooms",

package/docs/releases/0.1.0-alpha.6.md

@@ -0,0 +1,61 @@
+# Talking Stick 0.1.0-alpha.6
+
+Date: 2026-04-27
+
+Installer idempotency alpha. This release makes repeated `tt install --all`
+runs precise instead of noisy.
+
+## Changed
+
+### Precise install results
+
+`tt install` and `tt uninstall` now return and print explicit result statuses:
+
+- `added`
+- `already-present`
+- `updated`
+- `removed`
+- `already-absent`
+- `skipped`
+- `failed`
+
+The CLI reports the state Talking Stick observed instead of forwarding each
+harness's native wording directly. That keeps Claude Code, Codex, Gemini, and
+OpenCode output consistent.
+
+### Idempotent MCP install preflight
+
+Before running native MCP add/remove commands, Talking Stick now checks whether
+the named MCP server is already in the expected state:
+
+- Claude Code and Codex use their native `mcp get` command.
+- Gemini is inspected through its user `settings.json`.
+- OpenCode is inspected through its JSON config.
+
+If `talking-stick` is already registered, `tt install` reports
+`already-present` and does not call another native add command.
+
+## Fixed
+
+### Claude Code already-present installs
+
+Claude Code reports an existing MCP server as a native command failure. Talking
+Stick now recognizes that response as `already-present`, so a rerun of
+`tt install --all` no longer ends with "install completed with failures" just
+because Claude Code was already configured.
+
+### Codex duplicate-looking installs
+
+Codex already stores MCP servers by name, but rerunning `tt install --all`
+previously invoked `codex mcp add` again and printed Codex's native "Added"
+message. Talking Stick now reports `already-present` without invoking another
+add when the named server is already present.
+
+## Verification
+
+- `npm test -- tests/install.test.ts`
+- `npm run typecheck`
+- `npm run build`
+- `git diff --check`
+- `node dist/cli.js install --all`
+- `npx vitest run --reporter verbose` — 208 tests across 14 files

package/docs/releases/0.1.0.md

@@ -0,0 +1,37 @@
+# Talking Stick 0.1.0
+
+Date: 2026-04-27
+
+First non-alpha release. This promotes the current single-host coordination
+surface from alpha to the initial SemVer baseline.
+
+## What is in the baseline
+
+- MCP room coordination: `join_path`, `wait_for_turn`, `heartbeat`,
+  `release_stick`, `pass_stick`, `takeover_stick`, state reads, event reads,
+  and non-owner notes.
+- Human `tt` CLI flows for joining, waiting, releasing, passing, takeover,
+  notes, room inspection, installers, skill installers, and self-update.
+- SQLite WAL-backed persistence with multi-process safety, lease fencing,
+  liveness-aware recovery, fair release selection, and ephemeral room cleanup.
+- User-global MCP and skill install support for Claude Code, Codex CLI, Gemini
+  CLI, and OpenCode.
+
+## Changed
+
+### Non-alpha package version
+
+Package metadata, README version text, and the MCP server handshake now advertise
+`0.1.0`.
+
+### Long-poll skill guidance
+
+The bundled skill now uses `110000` ms as the default client-safe
+`wait_for_turn` long-poll budget.
+
+## Verification
+
+- `npm run typecheck`
+- `npm test` — 208 tests across 14 files
+- `git diff --check`
+- `npm pack --dry-run --ignore-scripts`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "talking-stick",
-  "version": "0.1.0-alpha.5",
+  "version": "0.1.0",
   "description": "MCP coordination server for path-scoped agent handoffs.",
   "type": "module",
   "bin": {

package/skills/talking-stick/SKILL.md

@@ -53,11 +53,11 @@ Keep the wait input minimal:
 ```json
 {
   "room_id": "<room_id from join_path>",
-  "max_wait_ms": 60000
+  "max_wait_ms": 110000
 }
 ```
 
-`max_wait_ms` is optional. Use the longest client-safe wait you can support: 60000 ms is a good MCP default when the harness can tolerate it; 120000 ms is fine only when the tool/client timeout is known to exceed that. If the call times out at the harness layer, fall back to a shorter value and call again. Do not send `cursor`, even if an old tool schema still exposes it; `wait_for_turn` is cursor-free, and resumable event replay belongs to `get_room_events`.
+`max_wait_ms` is optional. Use the longest client-safe wait you can support: 110000 ms is a good MCP default when the harness can tolerate it; 180000 ms is fine only when the tool/client timeout is known to exceed that. If the call times out at the harness layer, fall back to a shorter value and call again. Do not send `cursor`, even if an old tool schema still exposes it; `wait_for_turn` is cursor-free, and resumable event replay belongs to `get_room_events`.
 
 Possible outcomes: