patchcord 0.6.30 → 0.6.32

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "patchcord",
   "description": "Cross-machine agent messaging. Messages from other agents land in the inbox and wake the agent to reply.",
-  "version": "0.6.30",
+  "version": "0.6.32",
   "author": {
     "name": "ppravdin"
   },

package/bin/patchcord.mjs

@@ -196,11 +196,24 @@ team (run from the project root):
   patchcord team blueprint push --namespace <ns> --file <blueprint.json> [--json]
                                              create/update a team blueprint (first push
                                              to a new namespace claims it — first-provision)
+                                             PROMOTES BY DEFAULT — the pushed document
+                                             goes live immediately
+  patchcord team blueprint push ... --no-promote      (alias --dry-run)
+                                             validate + store WITHOUT going live. Use this
+                                             when any deployer may not yet understand a
+                                             value in the document.
   patchcord team deployment request --namespace <ns> [--revision <uid>] [--json]
                                              enqueue an apply of a saved revision
                                              (exit 3 = one is already in flight)
   patchcord team deployment pending [--json] jobs waiting for this host to claim
-  patchcord team deployment claim --job <uid> [--installation <name>] [--json]
+  patchcord team deployment claim --job <uid> [--installation <name>]
+        [--installation-uuid <uuid>] [--json]
+                                             --installation is the host LABEL
+                                             (becomes claimed_by).
+                                             --installation-uuid is the identity
+                                             selector; must match the enrolment
+                                             body or identity-key membership is
+                                             never recorded. Optional.
                                              take ownership (exit 3 = lost the race)
   patchcord team deployment complete --job <uid> --status <healthy|degraded|cancelled>
                                              [--result <json> | --result-file <path>] [--json]
@@ -1701,13 +1714,27 @@ you design the team, provision its agents, launch them, and manage them.
         const file = flagVal("file");
         const idem = flagVal("idempotency-key");
         const wantJson = process.argv.includes("--json");
-        if (!ns || !file) { console.error("Usage: patchcord team blueprint push --namespace <ns> --file <blueprint.json> [--idempotency-key k] [--json]"); process.exit(1); }
+        // --no-promote / --dry-run: store the revision and run strict server
+        // validation WITHOUT moving the live pointer.
+        //
+        // This exists because push promotes by default, so a hand-written
+        // document goes live the instant it validates. That is fine when the
+        // document is one every consumer understands, and it is how a Team gets
+        // bricked when it is not: the server can accept a value that deployers
+        // do not yet handle, and promoting it makes the Team undeployable AND
+        // unrestorable from one command. The rule the team arrived at is
+        // "consumers accept before producers emit", and until now the only way
+        // to honour it here was to remember to. This is the safe path existing
+        // rather than being agreed.
+        const noPromote = process.argv.includes("--no-promote") || process.argv.includes("--dry-run");
+        if (!ns || !file) { console.error("Usage: patchcord team blueprint push --namespace <ns> --file <blueprint.json> [--no-promote|--dry-run] [--idempotency-key k] [--json]"); process.exit(1); }
         let doc;
         try { doc = JSON.parse(readFileSync(file, "utf-8")); }
         catch (e) { console.error(`cannot read blueprint file: ${e.message}`); process.exit(1); }
         // First POST for an unowned namespace IS first-provision (server claims
         // the namespace atomically when PATCHCORD_BLUEPRINT_ATOMIC_CREATE is on).
         const payload = { canonical_json: doc };
+        if (noPromote) payload.promote = false;
         if (idem) payload.idempotency_key = idem;
         const { status, json, body } = await accountCall("POST", `/api/team/${encodeURIComponent(ns)}/blueprint/revisions`, payload);
         if (status !== "201" && status !== "200") {
@@ -1715,7 +1742,7 @@ you design the team, provision its agents, launch them, and manage them.
           process.exit(1);
         }
         if (wantJson) {
-          process.stdout.write(JSON.stringify({ ...json, created: status === "201" }) + "\n");
+          process.stdout.write(JSON.stringify({ ...json, created: status === "201", promoted: json.promoted !== false && !noPromote }) + "\n");
           process.exit(0);
         }
         console.log(`${status === "201" ? "created" : "unchanged (dedup)"} revision_uid: ${json.revision_uid}`);
@@ -1785,10 +1812,35 @@ you design the team, provision its agents, launch them, and manage them.
       if (dsub === "claim") {
         const job = flagVal("job");
         const installation = flagVal("installation");
-        if (!job) { console.error("Usage: patchcord team deployment claim --job <uid> [--installation <name>] [--json]"); process.exit(1); }
+        // SEPARATE FIELD, deliberately not a new meaning for --installation.
+        //
+        // --installation becomes claimed_by, which is the human-readable "which
+        // host took this job" an operator reads in the deploy list. Putting a
+        // UUID there would spend a label field on an identifier and leave
+        // nothing legible in its place.
+        //
+        // They are also different things by construction: --installation is
+        // <hostname>-<suffix>, live (macOS renames itself on a Bonjour
+        // collision) and MUX_HOST_ID-overridable — the exact selector we
+        // disqualified for the identity flow. --installation-uuid is minted
+        // beside the identity key itself so the key and its selector share one
+        // lifetime. It is what the server keys team membership on, so it must
+        // match the enrolment body's installation_uuid EXACTLY or membership is
+        // written against a string nothing else uses and the team-scoped read
+        // returns an empty set forever.
+        //
+        // Omitting it is legal and stays legal: an installation that has not
+        // upgraded keeps claiming exactly as before and simply records no
+        // identity-key membership. The server has accepted this field since
+        // bb553b2, so consumers accept before producers emit.
+        const installationUuid = flagVal("installation-uuid");
+        if (!job) { console.error("Usage: patchcord team deployment claim --job <uid> [--installation <name>] [--installation-uuid <uuid>] [--json]"); process.exit(1); }
+        const claimBody = {};
+        if (installation) claimBody.installation = installation;
+        if (installationUuid) claimBody.installation_uuid = installationUuid;
         const { status, json, body } = await accountCall(
           "POST", `/api/deployments/${encodeURIComponent(job)}/claim`,
-          installation ? { installation } : {},
+          claimBody,
         );
         // Losing a claim race is normal in a multi-host account, not a failure:
         // exit 3 so a poller can skip to the next job without parsing stderr.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "patchcord",
-  "version": "0.6.30",
+  "version": "0.6.32",
   "description": "Cross-machine agent messaging for Claude Code and Codex",
   "scripts": {
     "version": "node scripts/sync-plugin-version.mjs && git add .claude-plugin/plugin.json"

package/scripts/lib/claude-local-mcp.mjs

@@ -116,14 +116,18 @@ export function detectClaudeLocalMcpOverride({
       claude_config: claudeConfig,
       local_bearer_fp: localFp,
       disk_bearer_fp: diskFp,
+      // Kept SHORT and ending on the action that actually heals it. The old
+      // copy ran seven clauses and finished with "restart Claude Code", which
+      // is both heavier than needed and incomplete: clearing the entry does
+      // nothing until the MCP client reloads, and `/mcp` -> reconnect does that
+      // in place. A human who follows the old text to the letter clears the
+      // file, sees the tools still 401, and concludes the diagnosis was wrong.
       tell_human:
-        "Claude Code cached an old MCP token in ~/.claude.json that overrides this "
-        + "project's .mcp.json, and the cached copy wins. " + detail + " "
-        + `Clear projects["${projectDir}"].mcpServers (or just its "${serverKey}" entry) `
-        + "in ~/.claude.json, then restart Claude Code. "
-        + "Your Patchcord identity and token are fine — only Claude's MCP client is "
-        + "using the stale copy, which is why the CLI works while the MCP tools 401. "
-        + "Patchcord will not edit ~/.claude.json for you.",
+        `Claude Code cached an old MCP token in ~/.claude.json that overrides this project's .mcp.json. ${detail} `
+        + `Remove projects["${projectDir}"].mcpServers["${serverKey}"], then run /mcp and reconnect patchcord — `
+        + "clearing it alone will not fix it, the MCP client has to reload. "
+        + "Your token is fine; only Claude's MCP client holds the stale copy, "
+        + "which is why the CLI works while the MCP tools 401.",
     };
   } catch {
     return null;

package/skills/subscribe/SKILL.md

@@ -69,7 +69,19 @@ patchcord whoami --json
 
 If `warnings` contains `claude_local_mcp_cache_override`, **relay its `tell_human` text to the user verbatim.** They have no reason to know this command exists — all they saw was a tool failing.
 
-**Do NOT edit `~/.claude.json` yourself,** and do not ask another agent to. That file holds far more than MCP config, writing it races the running Claude Code process, and clearing an override is the user's call about their own editor. Patchcord diagnoses; the human acts.
+Then **offer to clear it**: *"Want me to remove the stale entry?"* Ask first — `~/.claude.json` is the user's global editor config, holds far more than MCP servers, and writing it races the running Claude Code process. But do not stop at diagnosing. Most users do not want to hand-edit JSON, and an accurate report they cannot act on leaves them exactly as stuck as no report.
+
+If they say yes:
+
+1. **Back it up first** — `cp ~/.claude.json ~/.claude.json.bak.$(date +%s)`.
+2. **Remove only** `projects["<dir>"].mcpServers["patchcord"]`. Not the whole `mcpServers` object, not the project entry, not the file. Parse, delete the one key, write atomically.
+3. **Then tell them to run `/mcp` and reconnect patchcord.**
+
+**Step 3 is the one that actually heals it, and it is the one that gets forgotten.** Clearing the entry changes a file the running MCP client already read; until it reloads, the tools keep 401-ing with the stale token and it looks like the fix failed. `/mcp` → reconnect reloads in place. Never tell them to restart Claude Code — if they are talking to you, they have already restarted, and it would not have helped anyway.
+
+You cannot run `/mcp` yourself; it is an interactive command in the user's client. Say the words and let them press it.
+
+Do not ask another agent to edit the file for you.
 
 ## If `whoami` is clean and the MCP tools STILL 401