patchcord 0.6.29 → 0.6.31

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.29",
+  "version": "0.6.31",
   "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,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]
@@ -721,6 +741,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,
@@ -730,6 +758,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);
@@ -747,6 +776,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);
 }
 
@@ -1246,42 +1283,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 });
@@ -1344,7 +1373,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") {
@@ -1388,10 +1418,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.
@@ -1411,7 +1465,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);
@@ -1500,7 +1554,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
@@ -1537,7 +1591,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
@@ -1660,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") {
@@ -1674,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}`);
@@ -1744,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.29",
+  "version": "0.6.31",
   "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

@@ -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/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.