patchcord 0.6.28 → 0.6.30

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.28",
+  "version": "0.6.30",
   "author": {
     "name": "ppravdin"
   },

package/bin/patchcord.mjs

@@ -12,6 +12,7 @@ const HOME = homedir();
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const pluginRoot = join(__dirname, "..");
 import { resolveProjectBearer, harnessContext } from "../scripts/lib/resolve-project-bearer.mjs";
+import { detectClaudeLocalMcpOverride } from "../scripts/lib/claude-local-mcp.mjs";
 const cmd = process.argv[2];
 
 /** Write a file then chmod 0600 (token-bearing configs must not be group/world readable). */
@@ -167,7 +168,7 @@ account:
   patchcord login                           authenticate the CLI (your account)
 
 orchestrator:
-  patchcord orchestrator [--namespace <ns>] [--tool <harness>] [--project <name>]
+  patchcord orchestrator --tool <harness> [--namespace <ns>] [--project <name>]
                                              provision the orchestrator here (always
                                              a lead); launch it to adopt this project
                                              or build a new team
@@ -180,6 +181,12 @@ team (run from the project root):
                                              place an existing agent into a folder
                                              (same identity; supersedes prior token —
                                              only ONE live credential per identity)
+
+  --tool is REQUIRED on provision / pull / orchestrator. It names which harness
+  config to write, and therefore WHICH AGENT. A folder may hold one patchcord
+  config per harness (.mcp.json for claude_code, .cursor/mcp.json for cursor, …)
+  and those can be different identities. Only the named harness is written —
+  sibling harness configs are never touched.
   patchcord provision revoke <agent> --namespace <ns>
                                              revoke a worker agent
   patchcord team list [--namespace <ns>] [--json]
@@ -189,6 +196,16 @@ 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)
+  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]
+                                             take ownership (exit 3 = lost the race)
+  patchcord team deployment complete --job <uid> --status <healthy|degraded|cancelled>
+                                             [--result <json> | --result-file <path>] [--json]
+  patchcord team deployment get --namespace <ns> (--job <uid> | --active) [--json]
+                                             one job, or the namespace's active job
   patchcord team status                     reconcile folder ↔ identity ↔ tmux ↔ token
   patchcord team launch                     launch each worker in mux
 
@@ -711,6 +728,14 @@ if (cmd === "whoami") {
     console.error(`✗ HTTP ${status}: ${(json && json.error) || body}`);
     process.exit(1);
   }
+  // Claude Code's local MCP cache can shadow .mcp.json with a stale bearer,
+  // which is exactly the state in which an agent reaches for whoami: the CLI
+  // works, the MCP tools 401, and the error blames the token. Read-only; see
+  // scripts/lib/claude-local-mcp.mjs.
+  const warnings = [];
+  const localOverride = detectClaudeLocalMcpOverride({ cwd: process.cwd(), diskToken: token });
+  if (localOverride) warnings.push(localOverride);
+
   if (wantJson) {
     const out = {
       agent: json.agent,
@@ -720,6 +745,7 @@ if (cmd === "whoami") {
       tool: found.tool || null,
       config_file: found.configFile || null,
       scope: found.scope || null,
+      warnings,
     };
     process.stdout.write(JSON.stringify(out) + "\n");
     process.exit(0);
@@ -737,6 +763,14 @@ if (cmd === "whoami") {
   }
   console.log();
   console.log(`tip: \`patchcord agents\` returns whoami for all peers.`);
+  for (const w of warnings) {
+    // stderr, matching the global-scope warning above. The line is addressed
+    // to the AGENT and says to relay it, because the human has no reason to
+    // know this command exists and will only ever see the 401.
+    console.error();
+    console.error(`\x1b[33m⚠ ${w.code}`);
+    console.error(`  TELL THE HUMAN: ${w.tell_human}\x1b[0m`);
+  }
   process.exit(0);
 }
 
@@ -1236,42 +1270,34 @@ if (cmd === "login" || cmd === "orchestrator" || cmd === "teamlead" || cmd === "
     return { ...r, m };
   };
 
-  /** After reminting into one harness file, update OTHER existing project
-   *  patchcord configs in the same dir so subscribe/hooks don't keep a
-   *  superseded pct- (dead .mcp.json next to live .cursor/mcp.json). */
-  const syncSiblingPatchcordTokens = (dir, baseUrl, token, hostname, primaryTool) => {
-    const hdr = { Authorization: `Bearer ${token}`, "X-Patchcord-Machine": hostname };
-    const touchJson = (path, mutate) => {
-      if (!existsSync(path)) return;
-      try {
-        let obj = {};
-        try { obj = JSON.parse(readFileSync(path, "utf-8")); } catch { return; }
-        // Only rewrite if a patchcord entry already exists — never invent configs.
-        const before = JSON.stringify(obj);
-        mutate(obj);
-        if (JSON.stringify(obj) === before) return;
-        writeSecureFile(path, JSON.stringify(obj, null, 2) + "\n");
-      } catch {}
-    };
-    // Claude Code project config
-    if (primaryTool !== "claude_code") {
-      touchJson(join(dir, ".mcp.json"), (o) => {
-        if (!o.mcpServers?.patchcord) return;
-        o.mcpServers.patchcord = {
-          ...(o.mcpServers.patchcord.type ? { type: o.mcpServers.patchcord.type } : { type: "http" }),
-          url: `${baseUrl}/mcp/bearer`,
-          headers: hdr,
-        };
-      });
-    }
-    // Cursor project config
-    if (primaryTool !== "cursor") {
-      touchJson(join(dir, ".cursor", "mcp.json"), (o) => {
-        if (!o.mcpServers?.patchcord) return;
-        o.mcpServers.patchcord = { url: `${baseUrl}/mcp/bearer`, headers: hdr };
-      });
-    }
-  };
+  // ── ONE HARNESS PER COMMAND — no sibling writes, ever ──
+  //
+  // This file used to run `syncSiblingPatchcordTokens` after every write:
+  // remint into the harness named by --tool, then stamp that same bearer into
+  // every OTHER patchcord config in the directory. The stated reason was to
+  // avoid leaving a superseded pct- beside a live one, and that reason only
+  // holds if the sibling files are copies of ONE identity.
+  //
+  // They routinely are not. The product rule is: at most one patchcord config
+  // PER HARNESS in a folder, and a folder MAY hold several harnesses at once —
+  // and those may be DIFFERENT agents:
+  //
+  //     .mcp.json         -> lead@mux-v2       (claude_code)
+  //     .cursor/mcp.json  -> mux-cursor@mux    (cursor)
+  //
+  // There is no "one directory, one shared token" rule and there never was. So
+  // `patchcord pull mux-cursor --tool cursor` was silently overwriting another
+  // agent's live credential — an identity never named on the command line —
+  // and breaking Claude's MCP when only Cursor had been asked for. It burned a
+  // production team.
+  //
+  // The rule now, with no exception and no opt-in flag: WRITE ONLY THE CONFIG
+  // FOR THE HARNESS NAMED BY --tool. A same-identity sync would still have to
+  // prove the sibling is the same agent, and the case it most wants to fix —
+  // a sibling whose token is already dead — is exactly the case that cannot be
+  // attributed: "my own stale copy" and "another agent's stale copy" look
+  // identical from here. Re-pull that harness by name instead; it is
+  // unambiguous, and it names the identity being changed.
 
   const writeWorkerConfig = (tool, dir, baseUrl, token, hostname) => {
     mkdirSync(dir, { recursive: true });
@@ -1334,7 +1360,8 @@ if (cmd === "login" || cmd === "orchestrator" || cmd === "teamlead" || cmd === "
           headers: hdr,
         };
       });
-      syncSiblingPatchcordTokens(dir, baseUrl, token, hostname, tool);
+      // No sibling writes. `--tool cursor` touches cursor's config and nothing
+      // else; .mcp.json in this directory may be a different agent entirely.
       return written;
     }
     if (tool === "antigravity" || tool === "agy") {
@@ -1378,10 +1405,34 @@ if (cmd === "login" || cmd === "orchestrator" || cmd === "teamlead" || cmd === "
       o.mcpServers = o.mcpServers || {};
       o.mcpServers.patchcord = { type: "http", url: `${baseUrl}/mcp`, headers: hdr };
     });
-    syncSiblingPatchcordTokens(dir, baseUrl, token, hostname, tool);
+    // No sibling writes. .cursor/mcp.json in this directory may hold a
+    // different agent's live credential.
     return primary;
   };
 
+  /** --tool is REQUIRED on anything that writes a patchcord MCP config.
+   *
+   *  It used to default to claude_code, and that default was a guess about
+   *  WHICH AGENT to overwrite. In a folder holding one config per harness —
+   *  each possibly a different identity — silently choosing claude_code means
+   *  `patchcord pull <agent>` rewrites `.mcp.json` and whatever identity lived
+   *  there, without that identity appearing anywhere on the command line.
+   *  Refusing costs one flag; guessing costs someone's live credential. */
+  const requireToolFlag = (usage) => {
+    const raw = (flagVal("tool", "") || "").trim();
+    if (raw) return raw;
+    console.error(`patchcord: --tool is required.`);
+    console.error(`  It names which harness config to write — and therefore which agent.`);
+    console.error(`  One folder may hold one patchcord config per harness, and they can be`);
+    console.error(`  DIFFERENT identities:`);
+    console.error(`      .mcp.json         → claude_code`);
+    console.error(`      .cursor/mcp.json  → cursor`);
+    console.error(`  Defaulting would overwrite an agent you did not name, so there is no default.`);
+    console.error(`  One of: claude_code, codex, cursor, kimi, opencode, antigravity, grok, hermes`);
+    console.error(`  ${usage}`);
+    process.exit(1);
+  };
+
   if (cmd === "login") {
     // Explicit CLI login. Other commands log in on demand via requireAuth(),
     // so this is only needed to authenticate ahead of time or switch accounts.
@@ -1401,7 +1452,7 @@ if (cmd === "login" || cmd === "orchestrator" || cmd === "teamlead" || cmd === "
       console.log(`✓ revoked ${ns}:${ra} (${json.count} token(s))`);
       process.exit(0);
     }
-    const tool = flagVal("tool", "claude_code");
+    const tool = requireToolFlag("patchcord provision <agent> --tool X --role Y --namespace ns [--dir sub/] [--project name] [--lead]");
     const role = flagVal("role", "");
     const ns = flagVal("namespace");
     const subdir = flagVal("dir", arg);
@@ -1420,7 +1471,7 @@ if (cmd === "login" || cmd === "orchestrator" || cmd === "teamlead" || cmd === "
     if (lead) provisionBody.is_lead = true;
     const { status, json, m } = await accountCall("POST", "/api/provision", provisionBody);
     if (status !== "200" || !json?.token) { console.error(`provision failed (HTTP ${status}): ${json?.error || ""}`); process.exit(1); }
-    const base = String(json.url || `${m.baseUrl}/mcp`).replace(/\/mcp$/, "");
+    const base = String(json.url || `${m.baseUrl}/mcp`).replace(/\/mcp(\/bearer)?$/, "");
     const dir = join(process.cwd(), subdir);
     const hostname = run("hostname -s") || run("hostname") || "unknown";
     writeWorkerConfig(tool, dir, base, json.token, hostname);
@@ -1490,7 +1541,7 @@ if (cmd === "login" || cmd === "orchestrator" || cmd === "teamlead" || cmd === "
     // symmetry only; server is source of truth.
     const arg = process.argv[3];
     if (!arg || arg.startsWith("-")) { console.error("Usage: patchcord pull <agent> --namespace ns --tool X [--dir sub/] [--lead]"); process.exit(1); }
-    const tool = flagVal("tool", "claude_code");
+    const tool = requireToolFlag("patchcord pull <agent> --tool X --namespace ns [--dir sub/] [--lead]");
     const ns = flagVal("namespace");
     const subdir = flagVal("dir", arg);
     const lead = process.argv.includes("--lead"); // typed symmetry; server ignores escalate-on-pull
@@ -1500,7 +1551,7 @@ if (cmd === "login" || cmd === "orchestrator" || cmd === "teamlead" || cmd === "
     const { status, json, m } = await accountCall("POST", "/api/provision", pullBody);
     if (status === "404") { console.error(`no agent ${M.green}${ns}:${arg}${M.rst} to pull — create it with: patchcord provision ${arg} --tool ${tool} --namespace ${ns}`); process.exit(1); }
     if (status !== "200" || !json?.token) { console.error(`pull failed (HTTP ${status}): ${json?.error || ""}`); process.exit(1); }
-    const base = String(json.url || `${m.baseUrl}/mcp`).replace(/\/mcp$/, "");
+    const base = String(json.url || `${m.baseUrl}/mcp`).replace(/\/mcp(\/bearer)?$/, "");
     const dir = join(process.cwd(), subdir);
     const hostname = run("hostname -s") || run("hostname") || "unknown";
     writeWorkerConfig(tool, dir, base, json.token, hostname);
@@ -1527,7 +1578,7 @@ if (cmd === "login" || cmd === "orchestrator" || cmd === "teamlead" || cmd === "
     // (`teamlead` is kept as a back-compat alias for the command name.)
     const root = process.cwd();
     const ns = (flagVal("namespace", basename(root)) || "team").replace(/[^a-z0-9-]/gi, "-").toLowerCase();
-    const tool = flagVal("tool", "claude_code");
+    const tool = requireToolFlag("patchcord orchestrator --tool X [--namespace ns] [--project name]");
     const project = flagVal("project", "");
     const hostname = run("hostname -s") || run("hostname") || "unknown";
     // is_lead: true always — the orchestrator IS the one identity per namespace
@@ -1537,7 +1588,7 @@ if (cmd === "login" || cmd === "orchestrator" || cmd === "teamlead" || cmd === "
     // until both leads explicitly consent).
     const { status, json, m } = await accountCall("POST", "/api/provision", { namespace_id: ns, agent_id: "orchestrator", tool, role: "orchestrator", label: "orchestrator:self", is_lead: true });
     if (status !== "200" || !json?.token) { console.error(`could not set up orchestrator (HTTP ${status}): ${json?.error || ""}`); process.exit(1); }
-    const base = String(json.url || `${m.baseUrl}/mcp`).replace(/\/mcp$/, "");
+    const base = String(json.url || `${m.baseUrl}/mcp`).replace(/\/mcp(\/bearer)?$/, "");
     writeWorkerConfig(tool, root, base, json.token, hostname);
     if (project) {
       const { status: pStatus, json: pJson } = await accountCall("POST", "/api/namespace/set-project", { namespace_id: ns, project });
@@ -1674,6 +1725,138 @@ you design the team, provision its agents, launch them, and manage them.
       console.error("Usage: patchcord team blueprint <current|push> --namespace <ns> [--json]");
       process.exit(1);
     }
+    if (sub === "deployment" || sub === "deployments") {
+      // Deploy = apply a saved revision to live panes. Deliberately NOT part of
+      // a save: `blueprint push` writes an immutable revision, this asks the
+      // owning Mux installation to enact one. Mux shells out to these; its
+      // poller treats an unknown subcommand as an empty pending list, so an
+      // older CLI degrades to "nothing to do" rather than crashing a host.
+      const dsub = process.argv[4];
+      const wantJson = process.argv.includes("--json");
+      const fail = (label, status, json, body) => {
+        const detail = (json && (json.error || json.code || JSON.stringify(json.detail))) || body || "";
+        console.error(`deployment ${label} failed (HTTP ${status}): ${detail}`);
+        process.exit(1);
+      };
+      const emit = (json) => {
+        if (wantJson) { process.stdout.write(JSON.stringify(json) + "\n"); process.exit(0); }
+      };
+      const printJob = (j) => {
+        console.log(`job_uid: ${j.job_uid}`);
+        console.log(`namespace: ${j.namespace}`);
+        console.log(`status: ${j.status}`);
+        console.log(`revision_uid: ${j.revision_uid}`);
+        console.log(`sha256: ${j.sha256}`);
+        if (j.claimed_by) console.log(`claimed_by: ${j.claimed_by}`);
+        if (j.result && Object.keys(j.result).length) console.log(`result: ${JSON.stringify(j.result)}`);
+      };
+
+      if (dsub === "request") {
+        const ns = flagVal("namespace");
+        const rev = flagVal("revision");
+        if (!ns) { console.error("Usage: patchcord team deployment request --namespace <ns> [--revision <uid>] [--json]"); process.exit(1); }
+        const payload = rev ? { revision_uid: rev } : {};
+        const { status, json, body } = await accountCall("POST", `/api/team/${encodeURIComponent(ns)}/deployments`, payload);
+        // 409 is not an error to the caller: a deploy is already in flight and
+        // the response carries it, so emit that job rather than failing. The
+        // exit code still distinguishes the two.
+        if (status === "409" && json && json.job) {
+          if (wantJson) { process.stdout.write(JSON.stringify({ ...json.job, already_active: true }) + "\n"); process.exit(3); }
+          console.log(`already active (${json.code})`);
+          printJob(json.job);
+          process.exit(3);
+        }
+        if (status !== "200" && status !== "201") fail("request", status, json, body);
+        emit(json);
+        printJob(json);
+        process.exit(0);
+      }
+
+      if (dsub === "pending") {
+        const { status, json, body } = await accountCall("GET", "/api/deployments/pending");
+        if (status !== "200") fail("pending", status, json, body);
+        emit(json);
+        const jobs = (json && json.jobs) || [];
+        if (!jobs.length) { console.log("(no pending deployments)"); process.exit(0); }
+        for (const j of jobs) console.log(`  ${j.job_uid}  ${j.namespace}  ${j.sha256.slice(0, 12)}  ${j.status}`);
+        process.exit(0);
+      }
+
+      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); }
+        const { status, json, body } = await accountCall(
+          "POST", `/api/deployments/${encodeURIComponent(job)}/claim`,
+          installation ? { installation } : {},
+        );
+        // 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.
+        if (status === "409") {
+          if (wantJson) { process.stdout.write(JSON.stringify(json) + "\n"); process.exit(3); }
+          console.log(`not claimable (${(json && json.code) || "conflict"})`);
+          process.exit(3);
+        }
+        if (status !== "200") fail("claim", status, json, body);
+        emit(json);
+        printJob(json);
+        process.exit(0);
+      }
+
+      if (dsub === "complete") {
+        const job = flagVal("job");
+        const st = flagVal("status");
+        const resultRaw = flagVal("result");
+        const resultFile = flagVal("result-file");
+        if (!job || !st) {
+          console.error("Usage: patchcord team deployment complete --job <uid> --status <healthy|degraded|cancelled> [--result <json> | --result-file <path>] [--json]");
+          process.exit(1);
+        }
+        let result = {};
+        try {
+          if (resultFile) result = JSON.parse(readFileSync(resultFile, "utf-8"));
+          else if (resultRaw) result = JSON.parse(resultRaw);
+        } catch (e) { console.error(`cannot parse result JSON: ${e.message}`); process.exit(1); }
+        const { status, json, body } = await accountCall(
+          "POST", `/api/deployments/${encodeURIComponent(job)}/complete`,
+          { status: st, result },
+        );
+        if (status === "409") {
+          // The lease lapsed and the job was requeued or failed while this host
+          // was applying. Reporting into it would overwrite a fresher attempt.
+          if (wantJson) { process.stdout.write(JSON.stringify(json) + "\n"); process.exit(3); }
+          console.log(`not running (${(json && json.code) || "conflict"}) — lease likely lapsed`);
+          process.exit(3);
+        }
+        if (status !== "200") fail("complete", status, json, body);
+        emit(json);
+        printJob(json);
+        process.exit(0);
+      }
+
+      if (dsub === "get") {
+        const ns = flagVal("namespace");
+        const job = flagVal("job");
+        const active = process.argv.includes("--active");
+        if (!ns || (!job && !active)) {
+          console.error("Usage: patchcord team deployment get --namespace <ns> (--job <uid> | --active) [--json]");
+          process.exit(1);
+        }
+        const path = active
+          ? `/api/team/${encodeURIComponent(ns)}/deployments?active=1`
+          : `/api/team/${encodeURIComponent(ns)}/deployments/${encodeURIComponent(job)}`;
+        const { status, json, body } = await accountCall("GET", path);
+        if (status !== "200") fail("get", status, json, body);
+        emit(json);
+        const j = active ? (json && json.job) : json;
+        if (!j) { console.log("(no active deployment)"); process.exit(0); }
+        printJob(j);
+        process.exit(0);
+      }
+
+      console.error("Usage: patchcord team deployment <request|pending|claim|complete|get> [--json]");
+      process.exit(1);
+    }
     if (sub === "status") {
       // Reconciler: folder ↔ patchcord identity ↔ tmux session ↔ token-active.
       // Truth = .patchcord/team.json. For each agent we resolve the token from
@@ -1810,7 +1993,7 @@ you design the team, provision its agents, launch them, and manage them.
       }
       process.exit(0);
     }
-    console.error("Usage: patchcord team <list|blueprint|launch|status>");
+    console.error("Usage: patchcord team <list|blueprint|deployment|launch|status>");
     process.exit(1);
   }
 
@@ -2192,6 +2375,40 @@ if (!cmd || cmd === "install" || cmd === "agent" || cmd?.startsWith("--")) {
       if (_approveCursorProjectMcp(process.cwd())) {
         globalChanges.push("Cursor MCP approved for this project");
       }
+
+      // Stop hook — a SECOND wake path, independent of the subscribe listener.
+      // The listener's notify_on_output wakes a seat both busy and idle
+      // (verified live), so an armed listener needs no help. This covers the
+      // case where no listener is running at all: never armed, armed without
+      // notify_on_output, or the process died. The `stop` hook fires on the
+      // harness's own event and needs no long-lived process, so it survives
+      // exactly the failure that silences subscribe.
+      // NOTE: cursor-agent loads ~/.cursor/hooks.json at STARTUP only — a
+      // session already running when this is written will not fire it.
+      const cursorHookSrc = join(pluginRoot, "scripts", "cursor-stop-hook.sh");
+      if (existsSync(cursorHookSrc)) {
+        const cursorHookDest = join(HOME, ".cursor", "patchcord-stop-hook.sh");
+        const hookExisted = existsSync(cursorHookDest);
+        mkdirSync(join(HOME, ".cursor"), { recursive: true });
+        cpSync(cursorHookSrc, cursorHookDest);
+        chmodSync(cursorHookDest, 0o755);
+
+        const cursorHooksPath = join(HOME, ".cursor", "hooks.json");
+        const hooksOk = updateJsonConfig(cursorHooksPath, (obj) => {
+          if (obj.version === undefined) obj.version = 1;
+          if (!obj.hooks || typeof obj.hooks !== "object" || Array.isArray(obj.hooks)) obj.hooks = {};
+          const existing = Array.isArray(obj.hooks.stop) ? obj.hooks.stop : [];
+          // Drop any prior patchcord entry (path may have moved) and re-add.
+          const kept = existing.filter((e) => !JSON.stringify(e).includes("patchcord-stop-hook"));
+          kept.push({ command: cursorHookDest });
+          obj.hooks.stop = kept;
+        });
+        if (!hooksOk) {
+          globalChanges.push("✗ Cursor stop hook error");
+        } else {
+          globalChanges.push(`Cursor stop hook ${hookExisted ? "updated" : "installed"}`);
+        }
+      }
     }
   }
 
@@ -2520,6 +2737,15 @@ if (!cmd || cmd === "install" || cmd === "agent" || cmd?.startsWith("--")) {
       copyFileSync(hookScriptSrc, hookScriptDest);
       chmodSync(hookScriptDest, 0o755);
 
+      // The hook sources this for the identity hint + loop brake. It lives in
+      // scripts/lib/ in the repo, but the hook runs from ~/.codex, so ship a
+      // copy beside it — otherwise the hook silently falls back to the older,
+      // loop-prone wording.
+      const guardSrc = join(pluginRoot, "scripts", "lib", "inbox-guard.sh");
+      if (existsSync(guardSrc)) {
+        copyFileSync(guardSrc, join(HOME, ".codex", "patchcord-inbox-guard.sh"));
+      }
+
       // Enable the `hooks` feature flag exactly once. Older installs / Codex
       // versions may leave `codex_hooks = true`, `hooks=true` (no spaces), a
       // `hooks = false`, or even a duplicate `hooks = true` — any of which makes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "patchcord",
-  "version": "0.6.28",
+  "version": "0.6.30",
   "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/check-inbox.sh

@@ -4,6 +4,18 @@ set -euo pipefail
 # jq is required — skip silently if not installed (fresh macOS)
 command -v jq >/dev/null 2>&1 || exit 0
 
+HOOK_DIR="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd -P)"
+if [ -f "$HOOK_DIR/lib/inbox-guard.sh" ]; then
+  # shellcheck source=lib/inbox-guard.sh
+  . "$HOOK_DIR/lib/inbox-guard.sh"
+else
+  # Degrade to the pre-guard behaviour rather than dying: a partial install
+  # must still nudge, just without the identity hint or the loop breaker.
+  pc_inbox_reason() { printf '%s patchcord message(s) waiting. Call inbox() and reply to all immediately.' "$1"; }
+  pc_streak_ok() { return 0; }
+  pc_state_path() { printf ''; }
+fi
+
 INPUT=$(cat)
 
 # Validate input is parseable JSON before proceeding — Claude Code may include
@@ -118,22 +130,36 @@ fi
 
 # ── Inbox notification (deduplicated across Stop + Notification hooks) ──
 COUNT=$(echo "$RESPONSE" | jq -r '.count // .pending_count // 0' 2>/dev/null || echo "0")
+case "$COUNT" in
+  ''|*[!0-9]*) COUNT=0 ;;
+esac
 
-if [ "$COUNT" -gt 0 ]; then
-  NOTIFY_LOCK="/tmp/patchcord_notify_lock"
-  LOCK_AGE=5
-  if [ -f "$NOTIFY_LOCK" ]; then
-    LOCK_MTIME=$(stat -c %Y "$NOTIFY_LOCK" 2>/dev/null || stat -f %m "$NOTIFY_LOCK" 2>/dev/null || echo "0")
-    NOW=$(date +%s)
-    if [ $(( NOW - LOCK_MTIME )) -lt $LOCK_AGE ]; then
-      exit 0  # Already notified within 5s
-    fi
+STREAK_STATE=$(pc_state_path "patchcord_inbox_streak" "$NAMESPACE" "$AGENT_ID" 2>/dev/null || echo "")
+
+if [ "$COUNT" -eq 0 ]; then
+  [ -n "$STREAK_STATE" ] && rm -f "$STREAK_STATE"
+  exit 0
+fi
+
+NOTIFY_LOCK="/tmp/patchcord_notify_lock"
+LOCK_AGE=5
+if [ -f "$NOTIFY_LOCK" ]; then
+  LOCK_MTIME=$(stat -c %Y "$NOTIFY_LOCK" 2>/dev/null || stat -f %m "$NOTIFY_LOCK" 2>/dev/null || echo "0")
+  NOW=$(date +%s)
+  if [ $(( NOW - LOCK_MTIME )) -lt $LOCK_AGE ]; then
+    exit 0  # Already notified within 5s
   fi
-  touch "$NOTIFY_LOCK"
-  jq -n --arg count "$COUNT" '{
-    "decision": "block",
-    "reason": ($count + " patchcord message(s) waiting. Call inbox() and reply to all immediately.")
-  }'
-else
+fi
+
+# Give up after MAX identical blocks. Keyed on identity+count, so a genuinely
+# new message resets it and always gets through — but a hook that keeps
+# counting messages the session cannot see (stale on-disk token, see
+# lib/inbox-guard.sh) stops burning turns instead of looping forever.
+if [ -n "$STREAK_STATE" ] \
+   && ! pc_streak_ok "$STREAK_STATE" "${NAMESPACE}/${AGENT_ID}/${COUNT}" 3; then
   exit 0
 fi
+
+touch "$NOTIFY_LOCK"
+REASON=$(pc_inbox_reason "$COUNT" "$NAMESPACE" "$AGENT_ID" "inbox()" "restart this Claude Code session")
+jq -n --arg reason "$REASON" '{"decision": "block", "reason": $reason}'

package/scripts/codex-stop-hook.sh

@@ -6,6 +6,22 @@ set -euo pipefail
 
 command -v jq >/dev/null 2>&1 || exit 0
 
+# This script is COPIED to ~/.codex/patchcord-stop-hook.sh by the installer, so
+# the shared guard is looked for both in the repo layout (scripts/lib/) and
+# beside the installed copy, where `npx patchcord` drops it.
+HOOK_DIR="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd -P)"
+if [ -f "$HOOK_DIR/lib/inbox-guard.sh" ]; then
+  # shellcheck source=lib/inbox-guard.sh
+  . "$HOOK_DIR/lib/inbox-guard.sh"
+elif [ -f "$HOOK_DIR/patchcord-inbox-guard.sh" ]; then
+  # shellcheck source=lib/inbox-guard.sh
+  . "$HOOK_DIR/patchcord-inbox-guard.sh"
+else
+  pc_inbox_reason() { printf '%s patchcord message(s) waiting. Call inbox() and reply to all.' "$1"; }
+  pc_streak_ok() { return 0; }
+  pc_state_path() { printf ''; }
+fi
+
 INPUT=$(cat)
 
 PROJECT_CWD=$(echo "$INPUT" | jq -r '.cwd // empty' 2>/dev/null || true)
@@ -61,14 +77,32 @@ RESPONSE=$(cat /tmp/patchcord_codex_inbox.json 2>/dev/null || echo '{"count":0}'
 rm -f /tmp/patchcord_codex_inbox.json
 
 COUNT=$(echo "$RESPONSE" | jq -r '.count // .pending_count // 0' 2>/dev/null || echo "0")
+case "$COUNT" in
+  ''|*[!0-9]*) COUNT=0 ;;
+esac
+
+NAMESPACE=$(echo "$RESPONSE" | jq -r '.namespace_id // empty' 2>/dev/null || true)
+AGENT_ID=$(echo "$RESPONSE" | jq -r '.agent_id // empty' 2>/dev/null || true)
+STREAK_STATE=$(pc_state_path "patchcord_codex_streak" "$NAMESPACE" "$AGENT_ID" 2>/dev/null || echo "")
+
+if [ "$COUNT" -eq 0 ]; then
+  [ -n "$STREAK_STATE" ] && rm -f "$STREAK_STATE"
+  exit 0
+fi
 
-if [ "$COUNT" -gt 0 ]; then
-  NOTIFY_LOCK="/tmp/patchcord_codex_notify_lock"
-  if [ -f "$NOTIFY_LOCK" ]; then
-    LOCK_MTIME=$(stat -c %Y "$NOTIFY_LOCK" 2>/dev/null || stat -f %m "$NOTIFY_LOCK" 2>/dev/null || echo "0")
-    NOW=$(date +%s)
-    [ $(( NOW - LOCK_MTIME )) -lt 5 ] && exit 0
-  fi
-  touch "$NOTIFY_LOCK"
-  jq -n --arg count "$COUNT" '{"decision":"block","reason":($count + " patchcord message(s) waiting. Call inbox() and reply to all.")}'
+NOTIFY_LOCK="/tmp/patchcord_codex_notify_lock"
+if [ -f "$NOTIFY_LOCK" ]; then
+  LOCK_MTIME=$(stat -c %Y "$NOTIFY_LOCK" 2>/dev/null || stat -f %m "$NOTIFY_LOCK" 2>/dev/null || echo "0")
+  NOW=$(date +%s)
+  [ $(( NOW - LOCK_MTIME )) -lt 5 ] && exit 0
 fi
+
+# Same-count/same-identity blocks give up after 3 — see lib/inbox-guard.sh.
+if [ -n "$STREAK_STATE" ] \
+   && ! pc_streak_ok "$STREAK_STATE" "${NAMESPACE}/${AGENT_ID}/${COUNT}" 3; then
+  exit 0
+fi
+
+touch "$NOTIFY_LOCK"
+REASON=$(pc_inbox_reason "$COUNT" "$NAMESPACE" "$AGENT_ID" "inbox()" "restart this Codex session")
+jq -n --arg reason "$REASON" '{"decision":"block","reason":$reason}'

package/scripts/cursor-stop-hook.sh

@@ -0,0 +1,167 @@
+#!/bin/bash
+set -euo pipefail
+
+# Cursor `stop` hook — checks the patchcord inbox at the end of every turn.
+# Installed automatically by `npx patchcord` when cursor-agent is detected.
+#
+# Why this exists: cursor-agent has no push-from-background-shell mechanism.
+# Its Shell tool exposes only the pull-shaped Await contract
+# (task_id / block_until_ms / regex), so a background `patchcord subscribe`
+# listener can print "PATCHCORD:" lines that nothing ever reads. Hooks are the
+# one inbound path Cursor actually offers, and `stop` is the one that fires
+# when the agent goes idle — exactly when an unread message would otherwise sit
+# until a human pokes the session.
+#
+# Contract — captured from a live cursor-agent 2026.07.23 stop event, not from
+# docs. The real stdin payload is:
+#   {conversation_id, generation_id, model, status, loop_count, input_tokens,
+#    output_tokens, cache_read_tokens, cache_write_tokens, session_id,
+#    hook_event_name, cursor_version, workspace_roots[], user_email,
+#    transcript_path}
+# Note `workspace_roots` — an ARRAY, and there is no `workspace_root_path` and
+# no `cwd`. Reading a scalar here silently falls back to $PWD (whatever cwd the
+# hook process inherited) and resolves the wrong project, or none.
+#
+#   stdout — JSON; a `followup_message` field starts a new turn carrying that
+#            text (StopRequestResponse.followupMessage). Verified live: it does
+#            start turns, and each new turn ends and fires this hook again — a
+#            bare canary looped 5 times in 14s before Cursor's own loop_count
+#            cap stopped it. That is why the streak brake below is not optional.
+# Never exit nonzero: a failing hook must not break the session.
+#
+# Hooks are loaded at STARTUP only. Dropping this file into ~/.cursor while a
+# session is running does nothing until that session restarts (verified: the
+# same canary was silent mid-session and fired immediately after a restart).
+
+command -v jq >/dev/null 2>&1 || exit 0
+command -v curl >/dev/null 2>&1 || exit 0
+
+INPUT=$(cat 2>/dev/null || echo '{}')
+
+# workspace_roots[0] is what cursor-agent actually sends. The scalar spellings
+# are accepted as fallbacks in case the payload shape changes again; $PWD is the
+# last resort and is deliberately last, since it points at the hook process's
+# inherited cwd rather than the agent's project.
+PROJECT_CWD=$(echo "$INPUT" | jq -r '(.workspace_roots[0]? // .workspace_root_path? // .cwd?) // empty' 2>/dev/null || true)
+if [ -z "$PROJECT_CWD" ] || [ "$PROJECT_CWD" = "null" ]; then
+  PROJECT_CWD="$PWD"
+fi
+
+CONVERSATION=$(echo "$INPUT" | jq -r '.conversation_id // empty' 2>/dev/null || true)
+[ -n "$CONVERSATION" ] || CONVERSATION="nocid"
+
+# ── Resolve project-scoped .cursor/mcp.json ──────────────────────────────────
+# PROJECT-scoped ONLY — walk up from the workspace root. A cursor-agent started
+# outside a patchcord project is not that agent and must not be nudged.
+CURSOR_MCP=""
+dir="$PROJECT_CWD"
+while [ "$dir" != "/" ] && [ -n "$dir" ]; do
+  if [ -f "$dir/.cursor/mcp.json" ]; then
+    CURSOR_MCP="$dir/.cursor/mcp.json"
+    break
+  fi
+  parent=$(dirname "$dir")
+  [ "$parent" = "$dir" ] && break
+  dir="$parent"
+done
+[ -n "$CURSOR_MCP" ] || exit 0
+
+TOKEN=$(jq -r '.mcpServers.patchcord.headers.Authorization // empty' "$CURSOR_MCP" 2>/dev/null | sed 's/^Bearer //i' || true)
+URL=$(jq -r '.mcpServers.patchcord.url // empty' "$CURSOR_MCP" 2>/dev/null || true)
+if [ -z "$TOKEN" ] || [ -z "$URL" ]; then
+  exit 0
+fi
+
+# Cursor uses the bearer endpoint; both spellings normalize to the same base.
+BASE_URL=$(echo "$URL" | sed 's|/mcp/bearer$||; s|/mcp$||')
+
+# ── Suppression state, keyed per project+conversation ────────────────────────
+# One file holding "<epoch> <consecutive_nudges>". Two jobs:
+#   * rate limit  — never nudge more than once per COOLDOWN seconds
+#   * loop brake  — if the agent is handed the same nudge MAX_CONSECUTIVE times
+#                   without the inbox draining, stop; something is wrong and an
+#                   endless followup chain would burn the session.
+# Both reset the moment the inbox reaches zero.
+#
+# Keyed on the RESOLVED project root (the directory owning .cursor/mcp.json),
+# never on the incoming workspace path: Cursor reports whatever cwd the turn ran
+# in, so keying on that would mint a fresh key per subdirectory and silently
+# defeat both the cooldown and the loop brake.
+COOLDOWN=30
+MAX_CONSECUTIVE=3
+PROJECT_ROOT=$(dirname "$(dirname "$CURSOR_MCP")")
+STATE_KEY=$(printf '%s|%s' "$PROJECT_ROOT" "$CONVERSATION" | cksum | cut -d' ' -f1)
+STATE_FILE="/tmp/patchcord_cursor_stop_${STATE_KEY}"
+
+# ── Pending count ────────────────────────────────────────────────────────────
+BODY_FILE=$(mktemp "/tmp/patchcord_cursor_inbox.XXXXXX" 2>/dev/null || echo "/tmp/patchcord_cursor_inbox.$$")
+HTTP_CODE=$(curl -s -o "$BODY_FILE" -w "%{http_code}" --max-time 5 \
+  -H "Authorization: Bearer ${TOKEN}" \
+  -H "x-patchcord-install-path: ${PROJECT_CWD}" \
+  "${BASE_URL}/api/inbox?status=pending&limit=5&count_only=1" 2>/dev/null || echo "000")
+
+RESPONSE=$(cat "$BODY_FILE" 2>/dev/null || echo '{}')
+rm -f "$BODY_FILE"
+
+if [ "$HTTP_CODE" = "401" ] || [ "$HTTP_CODE" = "403" ]; then
+  # Surface a dead token once per cooldown rather than silently going quiet.
+  NOW=$(date +%s)
+  LAST=0
+  [ -f "$STATE_FILE" ] && LAST=$(cut -d' ' -f1 "$STATE_FILE" 2>/dev/null || echo 0)
+  if [ $(( NOW - LAST )) -ge "$COOLDOWN" ]; then
+    echo "$NOW 0" > "$STATE_FILE"
+    jq -n --arg code "$HTTP_CODE" \
+      '{followup_message: ("Patchcord token rejected (HTTP " + $code + "). Tell the human to re-run `npx patchcord` in this project — do not edit .cursor/mcp.json by hand.")}'
+  fi
+  exit 0
+fi
+
+# Network blip / origin down — stay silent, try again next turn.
+[ "$HTTP_CODE" = "200" ] || exit 0
+
+COUNT=$(echo "$RESPONSE" | jq -r '.pending_count // .count // 0' 2>/dev/null || echo "0")
+case "$COUNT" in
+  ''|*[!0-9]*) COUNT=0 ;;
+esac
+
+if [ "$COUNT" -eq 0 ]; then
+  rm -f "$STATE_FILE"
+  exit 0
+fi
+
+NOW=$(date +%s)
+LAST=0
+STREAK=0
+if [ -f "$STATE_FILE" ]; then
+  LAST=$(cut -d' ' -f1 "$STATE_FILE" 2>/dev/null || echo 0)
+  STREAK=$(cut -d' ' -f2 "$STATE_FILE" 2>/dev/null || echo 0)
+  case "$LAST" in ''|*[!0-9]*) LAST=0 ;; esac
+  case "$STREAK" in ''|*[!0-9]*) STREAK=0 ;; esac
+fi
+
+[ $(( NOW - LAST )) -lt "$COOLDOWN" ] && exit 0
+[ "$STREAK" -ge "$MAX_CONSECUTIVE" ] && exit 0
+
+echo "$NOW $(( STREAK + 1 ))" > "$STATE_FILE"
+
+NAMESPACE=$(echo "$RESPONSE" | jq -r '.namespace_id // empty' 2>/dev/null || true)
+AGENT_ID=$(echo "$RESPONSE" | jq -r '.agent_id // empty' 2>/dev/null || true)
+
+if [ "$COUNT" -eq 1 ]; then
+  MSG="Patchcord: 1 pending message. Call the patchcord inbox tool now, do the work it asks for, then reply with what you did."
+else
+  MSG="Patchcord: ${COUNT} pending messages. Call the patchcord inbox tool now, do the work each one asks for, then reply to each with what you did."
+fi
+
+# Name the identity the count belongs to. This hook reads the token from
+# .cursor/mcp.json on disk; the agent's MCP connection holds whatever token it
+# was given at session start. Once anything rewrites that config the two drift
+# apart, the hook counts for the new identity and the inbox tool answers 0 for
+# the old one — a contradiction neither side can see alone. See
+# lib/inbox-guard.sh.
+if [ -n "$NAMESPACE" ] && [ -n "$AGENT_ID" ]; then
+  MSG="${MSG} These are addressed to ${AGENT_ID}@${NAMESPACE}. If the inbox tool reports a different identity, or reports 0 pending, this session is authenticated as another agent — the token on disk was replaced after it started. Do not keep retrying: say so and ask the user to restart the session."
+fi
+
+jq -n --arg msg "$MSG" '{followup_message: $msg}'
+exit 0

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

@@ -0,0 +1,131 @@
+// Detect Claude Code's LOCAL MCP config cache shadowing the project .mcp.json.
+//
+// Claude Code stores a per-project MCP config in ~/.claude.json under
+// projects[<abs project dir>].mcpServers. That is the "local" scope, and
+// Claude Code's precedence is:
+//
+//     enterprise  >  LOCAL  >  project (.mcp.json)  >  user
+//
+// So a stale bearer cached there BEATS the live one on disk. The failure is
+// nasty because the two halves disagree about who is right:
+//
+//     `patchcord whoami`  reads .mcp.json  -> works, identity looks healthy
+//     Claude's MCP client reads the cache  -> 401 "requires re-authorization"
+//
+// An agent hitting that 401 concludes its token expired, and it has not. The
+// credential is fine; only Claude's MCP client is poisoned. Nothing in the
+// error says so, and the human has no reason to know `whoami` exists — which
+// is why this check reports to the AGENT, whose job is then to tell them.
+//
+// THIS MODULE IS READ-ONLY AND MUST STAY THAT WAY. Patchcord does not edit
+// ~/.claude.json. That file holds a lot more than MCP config, rewriting it
+// races a running Claude Code, and clearing an override is a decision about
+// the human's editor, not about Patchcord. We diagnose; they act.
+
+import { existsSync, readFileSync, statSync } from "fs";
+import { createHash } from "crypto";
+import { homedir } from "os";
+import { join, parse as parsePath } from "path";
+
+// ~/.claude.json carries whole-session state and can get large. Cap the read
+// so `whoami` can never be slowed to a crawl by a pathological file.
+const MAX_BYTES = 32 * 1024 * 1024;
+
+const stripBearer = (v) => String(v || "").replace(/^Bearer\s+/i, "").trim();
+
+/** Short, non-reversible tag for a secret — lets a human match two values
+ *  without either of them ever being printed. */
+export function fingerprint(token) {
+  const t = stripBearer(token);
+  if (!t) return null;
+  return createHash("sha256").update(t).digest("hex").slice(0, 12);
+}
+
+/** Every directory from `dir` up to the filesystem root, nearest first. */
+function ancestors(dir) {
+  const out = [];
+  let cur = dir;
+  for (;;) {
+    out.push(cur);
+    const next = parsePath(cur).dir;
+    if (!next || next === cur) return out;
+    cur = next;
+  }
+}
+
+/**
+ * @returns {null | {
+ *   code: string, tell_human: string, project_dir: string,
+ *   local_bearer_fp: string|null, disk_bearer_fp: string|null,
+ *   claude_config: string,
+ * }}
+ *
+ * Returns null — never throws — when there is nothing to report OR when the
+ * check itself cannot run. A diagnostic that can break `whoami` is worse than
+ * no diagnostic: whoami is what an agent reaches for when everything else is
+ * already broken.
+ */
+export function detectClaudeLocalMcpOverride({
+  cwd = process.cwd(),
+  diskToken = null,
+  home = homedir(),
+  serverKey = "patchcord",
+} = {}) {
+  try {
+    const claudeConfig = join(home, ".claude.json");
+    if (!existsSync(claudeConfig)) return null;
+    if (statSync(claudeConfig).size > MAX_BYTES) return null;
+
+    const parsed = JSON.parse(readFileSync(claudeConfig, "utf-8"));
+    const projects = parsed?.projects;
+    if (!projects || typeof projects !== "object") return null;
+
+    // Claude keys by the ABSOLUTE directory it was launched in, which may be
+    // an ancestor of the cwd this command runs in (an agent working in a
+    // subdirectory, a worktree helper). Nearest match wins, mirroring how
+    // .mcp.json itself is resolved.
+    let projectDir = null;
+    let entry = null;
+    for (const dir of ancestors(cwd)) {
+      const candidate = projects?.[dir]?.mcpServers?.[serverKey];
+      if (candidate) { projectDir = dir; entry = candidate; break; }
+    }
+    if (!entry) return null;
+
+    const localToken = stripBearer(entry?.headers?.Authorization);
+    const disk = stripBearer(diskToken);
+
+    // Nothing on disk to compare against: the local entry is the only config,
+    // so it is not SHADOWING anything and this is not the bug.
+    if (!disk) return null;
+    // Present and identical is harmless today. It is a latent trap — it will
+    // silently go stale on the next rotation — but warning on it would fire
+    // for every Claude Code user on every whoami, and a warning that is
+    // usually noise stops being read before the day it matters.
+    if (localToken && localToken === disk) return null;
+
+    const localFp = fingerprint(localToken);
+    const diskFp = fingerprint(disk);
+    const detail = localToken
+      ? `The cached token (${localFp}) is not the one on disk (${diskFp}).`
+      : `The cached entry has no usable bearer token at all, while .mcp.json does.`;
+
+    return {
+      code: "claude_local_mcp_cache_override",
+      project_dir: projectDir,
+      claude_config: claudeConfig,
+      local_bearer_fp: localFp,
+      disk_bearer_fp: diskFp,
+      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.",
+    };
+  } catch {
+    return null;
+  }
+}

package/scripts/lib/inbox-guard.sh

@@ -0,0 +1,88 @@
+#!/bin/bash
+# Shared stop-hook guards for the pending-message nudge.
+#
+# Sourced by check-inbox.sh (Claude Code), codex-stop-hook.sh and
+# cursor-stop-hook.sh. Pure functions + a state file; no network, no jq
+# dependency of its own.
+#
+# Why this exists — the stale-identity loop:
+#   A stop hook reads the bearer token from the config file ON DISK. The agent's
+#   MCP connection holds the token it was given when the session STARTED. Those
+#   are the same token right up until something rewrites the config — a
+#   re-provision, a team restore, a seat handover. From that moment the hook
+#   counts messages for the NEW identity while inbox() still queries as the OLD
+#   one, so the hook says "2 waiting" and inbox() truthfully answers 0. The
+#   agent has no way to see the contradiction, so it calls inbox() again, gets 0
+#   again, and burns turns until a human kills it.
+#
+#   Neither side is wrong and neither can detect it alone. So the hook names the
+#   identity the count belongs to, which turns an invisible contradiction into
+#   something the agent can read and act on, and gives up after a few identical
+#   blocks instead of looping forever.
+
+# pc_inbox_reason <count> <namespace> <agent> <inbox_call> <restart_hint>
+#
+# The nudge text. Names the identity so a session authenticated as a different
+# agent can recognise the mismatch. Falls back to the plain wording when the
+# server did not return an identity.
+pc_inbox_reason() {
+  local count="$1" ns="$2" agent="$3" call="${4:-inbox()}" hint="${5:-restart this session}"
+  local noun="message(s)"
+  [ "$count" = "1" ] && noun="message"
+
+  if [ -z "$ns" ] || [ -z "$agent" ]; then
+    printf '%s patchcord %s waiting. Call %s and reply to all immediately.' \
+      "$count" "$noun" "$call"
+    return
+  fi
+
+  printf '%s patchcord %s waiting for %s@%s. Call %s and reply to all immediately. If %s reports a different identity than %s@%s, or reports 0 pending, then this session is authenticated as another agent: the token on disk was replaced after the session started. Do NOT keep calling %s — say so and ask the user to %s so it reloads the config.' \
+    "$count" "$noun" "$agent" "$ns" \
+    "$call" \
+    "$call" "$agent" "$ns" \
+    "$call" "$hint"
+}
+
+# pc_streak_ok <state_file> <key> <max>
+#
+# Consecutive-identical-block breaker. `key` should encode identity + count, so
+# the streak resets the moment either changes and a genuinely new message always
+# gets through. Returns 0 (block) while the streak is under `max`, 1 (stay
+# silent) once it is reached. Writes state best-effort; an unwritable /tmp
+# degrades to "always block", never to a hard failure.
+pc_streak_ok() {
+  local state="$1" key="$2" max="${3:-3}"
+  local prev="" prev_key="" prev_n=0
+
+  prev=$(cat "$state" 2>/dev/null || true)
+  if [ -n "$prev" ]; then
+    prev_key="${prev%|*}"
+    prev_n="${prev##*|}"
+    case "$prev_n" in ''|*[!0-9]*) prev_n=0 ;; esac
+  fi
+
+  if [ "$prev_key" = "$key" ]; then
+    if [ "$prev_n" -ge "$max" ]; then
+      return 1
+    fi
+    prev_n=$(( prev_n + 1 ))
+  else
+    prev_n=1
+  fi
+
+  # Braces so the REDIRECT's own failure is captured too — `printf > bad 2>/dev/null`
+  # still prints the redirect error, and kimi's hook treats stderr as the
+  # notification channel.
+  { printf '%s|%s' "$key" "$prev_n" > "$state"; } 2>/dev/null || true
+  return 0
+}
+
+# pc_state_path <prefix> <namespace> <agent>
+# A filesystem-safe state path. Identity is part of the name so two agents in
+# one project never share a streak counter.
+pc_state_path() {
+  local prefix="$1" ns="${2:-nons}" agent="${3:-noagent}"
+  local slug
+  slug=$(printf '%s_%s' "$ns" "$agent" | tr -c 'A-Za-z0-9_.-' '_')
+  printf '/tmp/%s_%s' "$prefix" "$slug"
+}

package/skills/subscribe/SKILL.md

@@ -57,6 +57,44 @@ Read the output file. Scan the last ~15 lines for one of:
 
 Report the cause in one sentence. STOP.
 
+# If the MCP tools 401 — check before you believe the error
+
+`mcp__patchcord__*` returning **401 / "requires re-authorization (token expired)"** does NOT establish that the token expired. Claude Code keeps a **local** MCP config cache in `~/.claude.json` under `projects[<project dir>].mcpServers`, and local scope **beats** the project's `.mcp.json`. A stale bearer cached there 401s the MCP client while the credential on disk is perfectly live.
+
+**Always run `patchcord whoami --json` before reporting an auth failure.** It reads the disk config, so it keeps working in exactly this state:
+
+```bash
+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.
+
+## If `whoami` is clean and the MCP tools STILL 401
+
+This is a **different failure with an identical symptom**, and it is the one that leaves you stuck if you stop at "identity is fine".
+
+The stale-cache bug above is **cache newer than disk**. This one is the mirror image — **disk newer than your process**:
+
+1. Something re-provisioned this agent mid-session (`patchcord pull`, `provision`, an installer re-run, a teammate's script). That **rewrites `.mcp.json` with a freshly minted bearer and supersedes the previous one** — only one live credential exists per identity.
+2. Your MCP client is still holding the bearer it read at session start. That token is now dead.
+3. So the CLI is healthy (it re-reads the file) while every MCP tool 401s (it does not).
+
+**The CLI cannot detect this**, which is why it is not a `warnings[]` entry: no external process can see your client's in-process token. Confirm it by hand instead:
+
+```bash
+stat -c '%y %n' .mcp.json     # was it modified after this session started?
+```
+
+A modification time later than your session start is the answer.
+
+**Then reconnect the MCP client** — that is the fix, and it is the step people miss. Do **not** conclude that the token is broken, and do not keep retrying `inbox()`: a superseded token will 401 forever, and repeating the call reports the same error indefinitely. If reconnecting is not something you can do yourself, **tell the human that the MCP client needs reconnecting and why**, naming the rewrite time.
+
+Reported by `lead@mux-v2`, who followed the procedure above, correctly concluded "not that bug", and then had nowhere to go for several hours.
+
+If `whoami` is clean, `.mcp.json` was not touched this session, and the tools still fail, the problem is neither of these — say so plainly rather than guessing at the token.
+
 **Forbidden on failure:** no `pgrep`/`ps`/`kill`/`pkill`/`killall`, no pidfile writes, no respawning. The script manages pidfile cleanup itself; respawning will not fix a config problem.
 
 No matching error pattern = the listener exited cleanly (session ended, user killed it, or EPIPE detected). Nothing to do.