patchcord 0.6.26 → 0.6.28

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

package/bin/patchcord.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 
-import { existsSync, mkdirSync, cpSync, readdirSync, readFileSync, writeFileSync, unlinkSync, rmSync } from "fs";
+import { existsSync, mkdirSync, cpSync, readdirSync, readFileSync, writeFileSync, unlinkSync, rmSync, chmodSync } from "fs";
 import { join, dirname, basename } from "path";
 import { fileURLToPath } from "url";
 import { execSync } from "child_process";
@@ -14,6 +14,15 @@ const pluginRoot = join(__dirname, "..");
 import { resolveProjectBearer, harnessContext } from "../scripts/lib/resolve-project-bearer.mjs";
 const cmd = process.argv[2];
 
+/** Write a file then chmod 0600 (token-bearing configs must not be group/world readable). */
+function writeSecureFile(path, contents) {
+  // mode applies at creation (no umask window for fresh files); the explicit
+  // chmod also repairs pre-existing files that were created too permissive.
+  writeFileSync(path, contents, { mode: 0o600 });
+  try { chmodSync(path, 0o600); } catch {}
+  return path;
+}
+
 if (cmd === "--version" || cmd === "-v") {
   const { readFileSync: _rf } = await import("fs");
   const { version } = JSON.parse(_rf(join(__dirname, "..", "package.json"), "utf-8"));
@@ -147,7 +156,8 @@ setup:
   patchcord --rename <name> [--agent-type <t>]   rename this agent
 
 agent:
-  patchcord whoami                          this agent's identity + project
+  patchcord whoami [--tool <harness>] [--json]
+                                             this agent's identity + project
   patchcord whoami --propose "<text>"       set self-description (two-shot confirm)
   patchcord agents [name]                   list agents in your namespace, or show one
   patchcord subscribe [interval] [--kimi]   realtime listener (Kimi: poll + exit)
@@ -166,12 +176,19 @@ team (run from the project root):
   patchcord provision <agent> --tool <X> --role <Y> --namespace <ns>
         [--dir <sub/>] [--project <name>] [--lead]
                                              create a worker agent (identity + config)
-  patchcord pull <agent> --tool <X> --namespace <ns> [--dir <sub/>]
-                                             move an existing agent into a folder
-                                             (same identity, new token)
+  patchcord pull <agent> --tool <X> --namespace <ns> [--dir <sub/>] [--lead]
+                                             place an existing agent into a folder
+                                             (same identity; supersedes prior token —
+                                             only ONE live credential per identity)
   patchcord provision revoke <agent> --namespace <ns>
                                              revoke a worker agent
-  patchcord team list [--namespace <ns>]    provisioned agents (server view)
+  patchcord team list [--namespace <ns>] [--json]
+                                             provisioned agents (server view)
+  patchcord team blueprint current --namespace <ns> [--json]
+                                             fetch current team blueprint revision
+  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 status                     reconcile folder ↔ identity ↔ tmux ↔ token
   patchcord team launch                     launch each worker in mux
 
@@ -612,12 +629,31 @@ async function _httpJSON(method, url, token, body) {
 // ── whoami ────────────────────────────────────────────────────
 if (cmd === "whoami") {
   const args = process.argv.slice(3);
-  const found = await _resolveBearer();
+  const wantJson = args.includes("--json");
+  const toolIdx = args.indexOf("--tool");
+  const toolFlag = toolIdx !== -1 ? (args[toolIdx + 1] || "").trim() : "";
+  // Canonical harness aliases → installer tool slug for config resolution.
+  const CANON_TOOL = {
+    claude: "claude_code", claude_code: "claude_code",
+    codex: "codex", kimi: "kimi", "kimi-code": "kimi",
+    opencode: "opencode", agy: "antigravity", antigravity: "antigravity",
+    cursor: "cursor", grok: "grok", hermes: "hermes",
+  };
+  const resolveOpts = {};
+  if (toolFlag) {
+    const mapped = CANON_TOOL[toolFlag.toLowerCase()];
+    if (!mapped) {
+      console.error(`Unknown --tool '${toolFlag}'. Expected one of: ${Object.keys(CANON_TOOL).filter((k, i, a) => a.indexOf(k) === i).join(", ")}`);
+      process.exit(1);
+    }
+    resolveOpts.forceTool = mapped;
+  }
+  const found = await _resolveBearer(resolveOpts);
   if (!found) {
     console.error("No patchcord config found in current directory or any parent. Run `npx patchcord@latest` from a project directory first.");
     process.exit(1);
   }
-  if (found.scope === "global") {
+  if (found.scope === "global" && !wantJson) {
     console.error(`\x1b[33m⚠ No project patchcord config in ${process.cwd()} or any parent.`);
     console.error(`  Falling back to a GLOBAL config: ${found.configFile} (tool: ${found.tool}).`);
     console.error(`  If this isn't the agent you expected, you're in a directory without its own .mcp.json —`);
@@ -669,19 +705,35 @@ if (cmd === "whoami") {
     process.exit(1);
   }
 
-  // plain whoami (no flags)
+  // plain whoami (no propose)
   const { status, json, body } = await _httpJSON("GET", `${baseUrl}/api/agent/whoami`, token);
   if (status !== "200") {
     console.error(`✗ HTTP ${status}: ${(json && json.error) || body}`);
     process.exit(1);
   }
+  if (wantJson) {
+    const out = {
+      agent: json.agent,
+      namespace: json.namespace,
+      project_summary: json.project_summary ?? null,
+      whoami: json.whoami ?? null,
+      tool: found.tool || null,
+      config_file: found.configFile || null,
+      scope: found.scope || null,
+    };
+    process.stdout.write(JSON.stringify(out) + "\n");
+    process.exit(0);
+  }
   console.log(`agent: ${json.agent}`);
   console.log(`namespace: ${json.namespace}`);
   if (json.project_summary) console.log(`project: ${json.project_summary}`);
   if (json.whoami) {
     console.log(`self: ${json.whoami}`);
   } else {
-    console.log(`self: (empty — propose with: patchcord whoami --propose "<text>")`);
+    // Empty self-description is a NORMAL state for a healthy identity — a
+    // fresh mux-v2 seat once fail-closed reading "(empty …)" as "not
+    // provisioned". Say explicitly that identity is fine.
+    console.log(`self-description: (not set — optional; your identity ${json.agent}@${json.namespace} is fully provisioned. Set one with: patchcord whoami --propose "<text>")`);
   }
   console.log();
   console.log(`tip: \`patchcord agents\` returns whoami for all peers.`);
@@ -1135,7 +1187,7 @@ if (cmd === "login" || cmd === "orchestrator" || cmd === "teamlead" || cmd === "
     });
     if (!token) { console.error("\n  Login timed out or failed."); process.exit(1); }
     mkdirSync(dirname(AUTH_CONFIG), { recursive: true });
-    writeFileSync(AUTH_CONFIG, JSON.stringify({ token, baseUrl: DEFAULT_API }, null, 2) + "\n");
+    writeSecureFile(AUTH_CONFIG, JSON.stringify({ token, baseUrl: DEFAULT_API }, null, 2) + "\n");
     console.log(`  ${M.green}✓${M.rst} Logged in ${M.dim}(${AUTH_CONFIG})${M.rst}\n`);
     return { token, baseUrl: DEFAULT_API };
   };
@@ -1183,14 +1235,54 @@ 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 };
+      });
+    }
+  };
+
   const writeWorkerConfig = (tool, dir, baseUrl, token, hostname) => {
     mkdirSync(dir, { recursive: true });
     const hdr = { Authorization: `Bearer ${token}`, "X-Patchcord-Machine": hostname };
+    // Centralized token-bearing config write: always chmod 0600 after write
+    // (authoritative supersession — one live credential per identity).
     const writeJson = (p, mutate) => {
       let obj = {};
       try { obj = JSON.parse(readFileSync(p, "utf-8")); } catch {}
       mutate(obj);
-      writeFileSync(p, JSON.stringify(obj, null, 2) + "\n");
+      writeSecureFile(p, JSON.stringify(obj, null, 2) + "\n");
       return p;
     };
     if (tool === "codex") {
@@ -1199,7 +1291,7 @@ if (cmd === "login" || cmd === "orchestrator" || cmd === "teamlead" || cmd === "
       let ex = existsSync(p) ? readFileSync(p, "utf-8") : "";
       ex = ex.replace(/\[mcp_servers\.patchcord[\w.-]*\][^\[]*/g, "").replace(/\n{3,}/g, "\n\n").trim();
       ex = (ex ? ex + "\n\n" : "") + `[mcp_servers.patchcord-codex]\nurl = "${baseUrl}/mcp"\nhttp_headers = { "Authorization" = "Bearer ${token}", "X-Patchcord-Machine" = "${hostname}" }\ntool_timeout_sec = 300\n`;
-      writeFileSync(p, ex);
+      writeSecureFile(p, ex);
       return p;
     }
     if (tool === "grok") {
@@ -1208,7 +1300,7 @@ if (cmd === "login" || cmd === "orchestrator" || cmd === "teamlead" || cmd === "
       let ex = existsSync(p) ? readFileSync(p, "utf-8") : "";
       ex = ex.replace(/\[mcp_servers\.patchcord(?:[-\w]*)?\][\s\S]*?(?=\n\[(?!mcp_servers\.patchcord(?:\.|[-\w]*\]))|$)/g, "").replace(/\n{3,}/g, "\n\n").trim();
       ex = (ex ? ex + "\n\n" : "") + `[mcp_servers.patchcord]\nurl = "${baseUrl}/mcp"\nenabled = true\n\n[mcp_servers.patchcord.headers]\nAuthorization = "Bearer ${token}"\nX-Patchcord-Machine = "${hostname}"\n`;
-      writeFileSync(p, ex);
+      writeSecureFile(p, ex);
       return p;
     }
     if (tool === "kimi" || tool === "kimi-code") {
@@ -1229,7 +1321,7 @@ if (cmd === "login" || cmd === "orchestrator" || cmd === "teamlead" || cmd === "
       // Cursor IDE + Cursor CLI (cursor-agent) share the same project config —
       // same file, same schema (see patchcord.dev/console/connect writer).
       const cdir = join(dir, ".cursor"); mkdirSync(cdir, { recursive: true });
-      return writeJson(join(cdir, "mcp.json"), (o) => {
+      const written = writeJson(join(cdir, "mcp.json"), (o) => {
         o.mcpServers = o.mcpServers || {};
         // NO "type" field — cursor-agent silently drops the entire server entry
         // when "type" is set to any value here (verified: tools simply never
@@ -1242,6 +1334,8 @@ if (cmd === "login" || cmd === "orchestrator" || cmd === "teamlead" || cmd === "
           headers: hdr,
         };
       });
+      syncSiblingPatchcordTokens(dir, baseUrl, token, hostname, tool);
+      return written;
     }
     if (tool === "antigravity" || tool === "agy") {
       // Antigravity CLI: PROJECT-scoped config at .agents/mcp_config.json (one
@@ -1264,7 +1358,7 @@ if (cmd === "login" || cmd === "orchestrator" || cmd === "teamlead" || cmd === "
       mkdirSync(dirname(hermesPath), { recursive: true });
       let existingYaml = "";
       try { existingYaml = existsSync(hermesPath) ? readFileSync(hermesPath, "utf-8") : ""; } catch {}
-      writeFileSync(hermesPath, upsertHermesConfig(existingYaml, `${baseUrl}/mcp`, token));
+      writeSecureFile(hermesPath, upsertHermesConfig(existingYaml, `${baseUrl}/mcp`, token));
       // Install the Hermes patchcord skills (inbox/subscribe/wait) so the worker
       // knows the messaging flow, same as the installer does.
       try {
@@ -1280,10 +1374,12 @@ if (cmd === "login" || cmd === "orchestrator" || cmd === "teamlead" || cmd === "
     // default: claude_code. type:"http" is REQUIRED — without it Claude Code
     // defaults to stdio transport and rejects the entry ("command: expected
     // string, received undefined").
-    return writeJson(join(dir, ".mcp.json"), (o) => {
+    const primary = writeJson(join(dir, ".mcp.json"), (o) => {
       o.mcpServers = o.mcpServers || {};
       o.mcpServers.patchcord = { type: "http", url: `${baseUrl}/mcp`, headers: hdr };
     });
+    syncSiblingPatchcordTokens(dir, baseUrl, token, hostname, tool);
+    return primary;
   };
 
   if (cmd === "login") {
@@ -1388,17 +1484,20 @@ if (cmd === "login" || cmd === "orchestrator" || cmd === "teamlead" || cmd === "
 
   if (cmd === "pull") {
     // Inverse of provision: place an EXISTING agent identity into a folder.
-    // Mints another token bound to the same agent_id@namespace (its original
-    // token is hashed server-side and unrecoverable, so we can't return the
-    // literal one — but the identity is the same). Nothing is overwritten; the
-    // agent can now run from this folder too.
+    // Server supersedes the prior active token for this identity (exactly ONE
+    // live credential) and PRESERVES is_lead from that active token — request
+    // body --lead / role cannot escalate a worker. CLI --lead is typed
+    // 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/]"); process.exit(1); }
+    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 ns = flagVal("namespace");
     const subdir = flagVal("dir", arg);
+    const lead = process.argv.includes("--lead"); // typed symmetry; server ignores escalate-on-pull
     if (!ns) { console.error("--namespace <project-namespace> required"); process.exit(1); }
-    const { status, json, m } = await accountCall("POST", "/api/provision", { namespace_id: ns, agent_id: arg, tool, require_existing: true, label: `pull:${tool}` });
+    const pullBody = { namespace_id: ns, agent_id: arg, tool, require_existing: true, label: `pull:${tool}` };
+    if (lead) pullBody.is_lead = true; // server will still preserve, not escalate
+    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$/, "");
@@ -1489,24 +1588,92 @@ you design the team, provision its agents, launch them, and manage them.
   if (cmd === "team") {
     const sub = process.argv[3];
     if (sub === "list") {
+      const wantJson = process.argv.includes("--json");
       const { status, json } = await accountCall("GET", "/api/provision/list");
       if (status !== "200") { console.error(`list failed (HTTP ${status})`); process.exit(1); }
       // Dedup by namespace:agent — the server returns one row per token, so a
       // re-provisioned agent shows up many times. Optional --namespace filter.
       const filterNs = flagVal("namespace");
       const seen = new Set();
-      let n = 0;
+      const rows = [];
       for (const a of (json?.agents || [])) {
         if (filterNs && a.namespace_id !== filterNs) continue;
         const key = `${a.namespace_id}:${a.agent_id}`;
         if (seen.has(key)) continue;
         seen.add(key);
-        console.log(`  ${key}  ${M.dim}${a.label || ""}${M.rst}`);
-        n++;
+        rows.push({
+          namespace_id: a.namespace_id,
+          agent_id: a.agent_id,
+          is_lead: Boolean(a.is_lead),
+          tool: a.tool ?? null,
+          harness: a.harness ?? a.tool ?? null,
+          active: a.active !== false,
+          label: a.label || null,
+        });
+      }
+      if (wantJson) {
+        process.stdout.write(JSON.stringify({ agents: rows }) + "\n");
+        process.exit(0);
       }
-      if (!n) console.log("  (no agents)");
+      for (const a of rows) {
+        const leadTag = a.is_lead ? " lead" : "";
+        const toolTag = a.tool ? ` ${a.tool}` : "";
+        console.log(`  ${a.namespace_id}:${a.agent_id}  ${M.dim}${a.label || ""}${toolTag}${leadTag}${M.rst}`);
+      }
+      if (!rows.length) console.log("  (no agents)");
       process.exit(0);
     }
+    if (sub === "blueprint") {
+      const bsub = process.argv[4];
+      if (bsub === "current") {
+        const ns = flagVal("namespace");
+        const wantJson = process.argv.includes("--json");
+        if (!ns) { console.error("Usage: patchcord team blueprint current --namespace <ns> [--json]"); process.exit(1); }
+        // pcm accountCall — cold fetch of GET /api/team/{ns}/blueprint/current
+        const { status, json, body } = await accountCall("GET", `/api/team/${encodeURIComponent(ns)}/blueprint/current`);
+        if (status !== "200") {
+          console.error(`blueprint current failed (HTTP ${status}): ${(json && (json.error || json.detail)) || body || ""}`);
+          process.exit(1);
+        }
+        if (wantJson) {
+          // JSON-only stdout when --json (stable machine contract).
+          process.stdout.write(JSON.stringify(json) + "\n");
+          process.exit(0);
+        }
+        console.log(`revision_uid: ${json.revision_uid}`);
+        console.log(`sha256: ${json.sha256}`);
+        console.log(`canonical_json: ${JSON.stringify(json.canonical_json)}`);
+        process.exit(0);
+      }
+      if (bsub === "push") {
+        const ns = flagVal("namespace");
+        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); }
+        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 (idem) payload.idempotency_key = idem;
+        const { status, json, body } = await accountCall("POST", `/api/team/${encodeURIComponent(ns)}/blueprint/revisions`, payload);
+        if (status !== "201" && status !== "200") {
+          console.error(`blueprint push failed (HTTP ${status}): ${(json && (json.error || JSON.stringify(json.detail))) || body || ""}`);
+          process.exit(1);
+        }
+        if (wantJson) {
+          process.stdout.write(JSON.stringify({ ...json, created: status === "201" }) + "\n");
+          process.exit(0);
+        }
+        console.log(`${status === "201" ? "created" : "unchanged (dedup)"} revision_uid: ${json.revision_uid}`);
+        console.log(`sha256: ${json.sha256}`);
+        process.exit(0);
+      }
+      console.error("Usage: patchcord team blueprint <current|push> --namespace <ns> [--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
@@ -1643,7 +1810,7 @@ you design the team, provision its agents, launch them, and manage them.
       }
       process.exit(0);
     }
-    console.error("Usage: patchcord team <list|launch|status>");
+    console.error("Usage: patchcord team <list|blueprint|launch|status>");
     process.exit(1);
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "patchcord",
-  "version": "0.6.26",
+  "version": "0.6.28",
   "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/resolve-project-bearer.mjs

@@ -131,7 +131,12 @@ const kimiCodeReader = (cwd) => readJsonAt(join(cwd, ".kimi-code", "mcp.json"),
 
 /** Detect which harness launched this process (env + explicit overrides). */
 export function harnessContext(env = process.env, options = {}) {
-  const forceTool = (env.PATCHCORD_FORCE_TOOL || env.PATCHCORD_TOOL || "").toLowerCase();
+  const forceTool = (
+    options.forceTool
+    || env.PATCHCORD_FORCE_TOOL
+    || env.PATCHCORD_TOOL
+    || ""
+  ).toLowerCase();
   const preferKimi =
     options.preferKimi === true
     || forceTool === "kimi"
@@ -148,6 +153,17 @@ export function harnessContext(env = process.env, options = {}) {
 
 /** Ordered per-project readers for the active harness. */
 export function projectReadersForContext(ctx) {
+  const byTool = {
+    claude_code: claudeReader,
+    cursor: cursorReader,
+    vscode: vscodeReader,
+    opencode: opencodeReader,
+    antigravity: antigravityReader,
+    agy: antigravityReader,
+    grok: grokReader,
+    codex: codexReader,
+    kimi: kimiCodeReader,
+  };
   const defaultReaders = [
     claudeReader,
     cursorReader,
@@ -159,6 +175,17 @@ export function projectReadersForContext(ctx) {
   ];
   const kimiReaders = [kimiReader, kimiCodeReader];
 
+  // Explicit --tool / forceTool: prefer that harness's config first.
+  if (ctx.forceTool && byTool[ctx.forceTool]) {
+    const forced = byTool[ctx.forceTool];
+    const rest = [...defaultReaders, ...kimiReaders].filter((r) => r !== forced);
+    // kimi has two readers — prefer both when forcing kimi
+    if (ctx.forceTool === "kimi") {
+      return [...kimiReaders, ...defaultReaders];
+    }
+    return [forced, ...rest];
+  }
+
   if (ctx.preferKimi) {
     return [...kimiReaders, ...defaultReaders];
   }
@@ -179,22 +206,34 @@ export function projectReadersForContext(ctx) {
   return [...defaultReaders, ...kimiReaders];
 }
 
-/** Walk up from startDir; return first matching project bearer or null. */
-export function resolveProjectBearer(startDir, options = {}) {
+/**
+ * All project bearers found at startDir (and ancestors), in harness preference
+ * order, de-duplicated by token. Used by subscribe to skip superseded configs
+ * (e.g. dead .mcp.json next to a live .cursor/mcp.json after a Cursor remint).
+ */
+export function listProjectBearers(startDir, options = {}) {
   const ctx = harnessContext(process.env, options);
   const readers = projectReadersForContext(ctx);
+  const out = [];
+  const seen = new Set();
   let dir = startDir;
   while (dir && dir !== "/") {
     for (const r of readers) {
       const found = r(dir);
-      if (found) {
-        found.scope = "project";
-        return found;
-      }
+      if (!found?.token || seen.has(found.token)) continue;
+      seen.add(found.token);
+      found.scope = "project";
+      out.push(found);
     }
     const parent = dirname(dir);
     if (parent === dir) break;
     dir = parent;
   }
-  return null;
+  return out;
+}
+
+/** Walk up from startDir; return first matching project bearer or null. */
+export function resolveProjectBearer(startDir, options = {}) {
+  const listed = listProjectBearers(startDir, options);
+  return listed[0] || null;
 }

package/scripts/subscribe.mjs

@@ -13,7 +13,7 @@ import { request as httpRequest } from "node:http";
 import { URL } from "node:url";
 import { dirname } from "node:path";
 import { connect as wsConnect } from "./lib/ws.mjs";
-import { resolveProjectBearer } from "./lib/resolve-project-bearer.mjs";
+import { resolveProjectBearer, listProjectBearers } from "./lib/resolve-project-bearer.mjs";
 
 // --- Hermes webhook bridge mode -------------------------------------------
 // Default mode writes "PATCHCORD: ..." lines to stdout for Claude Code's
@@ -69,17 +69,76 @@ function die(msg, code = 1) {
   process.exit(code);
 }
 
+function errDetail(e) {
+  // Prefer message; fall back to code / String so "pending heartbeat failed: "
+  // with an empty message is never silent again (socket hang up / 522 / etc.).
+  if (!e) return "unknown";
+  const msg = e.message || e.code || "";
+  const extra = e.code && e.message && e.code !== e.message ? ` code=${e.code}` : "";
+  return `${msg || String(e)}${extra}`;
+}
+
 function readMcpConfig(cwd) {
   // Prefer env vars injected by patchcord.mjs, which already ran _resolveBearer()
   // and supports all tool configs with harness-aware ordering.
   if (process.env.PATCHCORD_BASE_URL && process.env.PATCHCORD_BEARER_TOKEN) {
-    return { baseUrl: process.env.PATCHCORD_BASE_URL, token: process.env.PATCHCORD_BEARER_TOKEN };
+    return { baseUrl: process.env.PATCHCORD_BASE_URL, token: process.env.PATCHCORD_BEARER_TOKEN, source: "env" };
   }
   const found = resolveProjectBearer(cwd);
   if (!found) {
     die(`no patchcord config found — run from a project directory or use 'patchcord subscribe'`);
   }
-  return { baseUrl: found.baseUrl, token: found.token };
+  return { baseUrl: found.baseUrl, token: found.token, source: found.configFile || "project" };
+}
+
+/** Try every on-disk project bearer until /api/realtime/ticket returns 200.
+ *  Skips superseded tokens left behind when one harness reminted and another
+ *  config file still holds the old pct- (classic: dead .mcp.json + live .cursor). */
+async function resolveLiveConfig(cwd) {
+  if (process.env.PATCHCORD_BASE_URL && process.env.PATCHCORD_BEARER_TOKEN) {
+    const cfg = {
+      baseUrl: process.env.PATCHCORD_BASE_URL,
+      token: process.env.PATCHCORD_BEARER_TOKEN,
+      source: "env",
+    };
+    // Still validate — env can go stale after a remint too.
+    const res = await httpJson(`${cfg.baseUrl}/api/realtime/ticket`, {
+      headers: { Authorization: `Bearer ${cfg.token}`, "x-patchcord-install-path": cwd },
+    });
+    if (res.status === 200) return cfg;
+    if (res.status !== 401 && res.status !== 403) {
+      throw new Error(`ticket HTTP ${res.status}: ${res.body.slice(0, 200)}`);
+    }
+    logErr(`subscribe: env token rejected (HTTP ${res.status}); scanning project configs`);
+  }
+  const candidates = listProjectBearers(cwd);
+  if (!candidates.length) {
+    die(`no patchcord config found — run from a project directory or use 'patchcord subscribe'`);
+  }
+  const rejected = [];
+  for (const c of candidates) {
+    const res = await httpJson(`${c.baseUrl}/api/realtime/ticket`, {
+      headers: { Authorization: `Bearer ${c.token}`, "x-patchcord-install-path": cwd },
+    });
+    if (res.status === 200) {
+      if (rejected.length) {
+        logErr(`subscribe: using live token from ${c.configFile} (skipped ${rejected.length} superseded)`);
+      }
+      return { baseUrl: c.baseUrl, token: c.token, source: c.configFile || "project" };
+    }
+    if (res.status === 401 || res.status === 403) {
+      rejected.push(`${c.configFile || c.tool}:${res.status}`);
+      continue;
+    }
+    if (res.status === 501) {
+      die("ticket: server not configured for realtime (self-hosted without Supabase?)");
+    }
+    if (res.status === 404) {
+      die("ticket: namespace not owned — regenerate your token");
+    }
+    throw new Error(`ticket HTTP ${res.status}: ${res.body.slice(0, 200)}`);
+  }
+  die(`ticket: all project tokens rejected (${rejected.join(", ") || "none"}) — remint with patchcord pull/provision`);
 }
 
 function httpJson(urlStr, { method = "GET", headers = {}, body = null } = {}) {
@@ -133,7 +192,7 @@ async function notify(line, meta = {}) {
   }
 }
 
-async function fetchTicket(baseUrl, token) {
+async function fetchTicket(baseUrl, token, { fatalAuth = true } = {}) {
   const res = await httpJson(`${baseUrl}/api/realtime/ticket`, {
     headers: {
       Authorization: `Bearer ${token}`,
@@ -141,7 +200,12 @@ async function fetchTicket(baseUrl, token) {
     },
   });
   if (res.status === 401 || res.status === 403) {
-    die(`ticket: token rejected (HTTP ${res.status}) — check .mcp.json`);
+    if (fatalAuth) {
+      die(`ticket: token rejected (HTTP ${res.status}) — check .mcp.json / .cursor/mcp.json`);
+    }
+    const err = new Error(`ticket HTTP ${res.status}`);
+    err.status = res.status;
+    throw err;
   }
   if (res.status === 501) {
     die("ticket: server not configured for realtime (self-hosted without Supabase?)");
@@ -165,22 +229,49 @@ async function fetchTicket(baseUrl, token) {
 // inbox() manually. Emit a stdout line when there's a pending queue so
 // Monitor wakes the agent the same way a real arrival does.
 async function drainQueueOnce(baseUrl, token) {
-  const res = await httpJson(`${baseUrl}/api/inbox?count_only=1&limit=100`, {
-    headers: {
-      Authorization: `Bearer ${token}`,
-      "x-patchcord-install-path": process.cwd(),
-    },
-  });
-  if (res.status !== 200) {
-    throw new Error(`inbox HTTP ${res.status}`);
-  }
-  let count = 0;
-  try {
-    count = JSON.parse(res.body).pending_count ?? 0;
-  } catch (_) {}
-  if (count > 0) {
-    await notify(`PATCHCORD: ${count} waiting in inbox`, { count, kind: "pending" });
+  const maxAttempts = 3;
+  let lastErr;
+  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+    try {
+      const res = await httpJson(`${baseUrl}/api/inbox?count_only=1&limit=100`, {
+        headers: {
+          Authorization: `Bearer ${token}`,
+          "x-patchcord-install-path": process.cwd(),
+        },
+      });
+      if (res.status === 401 || res.status === 403) {
+        const err = new Error(`inbox HTTP ${res.status}`);
+        err.status = res.status;
+        throw err;
+      }
+      if (res.status !== 200) {
+        // 522/502/503 from Cloudflare when origin blips — retry.
+        if (res.status >= 500 && attempt < maxAttempts) {
+          await new Promise((r) => setTimeout(r, 500 * attempt));
+          continue;
+        }
+        throw new Error(`inbox HTTP ${res.status}`);
+      }
+      let count = 0;
+      try {
+        count = JSON.parse(res.body).pending_count ?? 0;
+      } catch (_) {}
+      if (count > 0) {
+        await notify(`PATCHCORD: ${count} waiting in inbox`, { count, kind: "pending" });
+      }
+      return;
+    } catch (e) {
+      lastErr = e;
+      if (e?.status === 401 || e?.status === 403) throw e;
+      const retryable = !e?.status || e.status >= 500 || e.code === "ECONNRESET" || e.code === "ETIMEDOUT" || /socket hang up/i.test(e?.message || "");
+      if (retryable && attempt < maxAttempts) {
+        await new Promise((r) => setTimeout(r, 500 * attempt));
+        continue;
+      }
+      throw e;
+    }
   }
+  throw lastErr;
 }
 
 function writePidfile(path) {
@@ -225,8 +316,8 @@ function removePidfile(path) {
 
 async function run() {
   const cwd = process.cwd();
-  const { baseUrl, token } = readMcpConfig(cwd);
-  logErr(`subscribe: cwd=${cwd} server=${baseUrl}`);
+  let { baseUrl, token, source } = await resolveLiveConfig(cwd);
+  logErr(`subscribe: cwd=${cwd} server=${baseUrl} auth=${source}`);
 
   if (HERMES_MODE) {
     if (!HERMES_WEBHOOK) {
@@ -277,25 +368,41 @@ async function run() {
 
   let backoffIdx = 0;
 
+  const refreshAuth = async () => {
+    try {
+      return await fetchTicket(baseUrl, token, { fatalAuth: false });
+    } catch (e) {
+      if (e?.status === 401 || e?.status === 403) {
+        // Bearer was superseded mid-flight (remint into another harness file).
+        // Re-scan disk for a live token before giving up.
+        logErr(`subscribe: bearer rejected on refresh — re-scanning configs`);
+        const live = await resolveLiveConfig(cwd);
+        baseUrl = live.baseUrl;
+        token = live.token;
+        source = live.source;
+        logErr(`subscribe: switched auth to ${source}`);
+        return await fetchTicket(baseUrl, token, { fatalAuth: false });
+      }
+      throw e;
+    }
+  };
+
   const loop = async () => {
     while (true) {
       try {
-        await runOnce(ticket, baseUrl, token, async () => {
-          ticket = await fetchTicket(baseUrl, token);
-          return ticket;
-        });
+        await runOnce(ticket, baseUrl, () => token, refreshAuth);
         backoffIdx = 0; // clean disconnect resets backoff
       } catch (e) {
-        logErr(`subscribe: ${e.message}`);
+        logErr(`subscribe: ${errDetail(e)}`);
       }
       const delay = RECONNECT_BACKOFF_MS[Math.min(backoffIdx, RECONNECT_BACKOFF_MS.length - 1)];
       backoffIdx++;
       logErr(`subscribe: reconnecting in ${delay}ms`);
       await new Promise((r) => setTimeout(r, delay));
       try {
-        ticket = await fetchTicket(baseUrl, token);
+        ticket = await refreshAuth();
       } catch (e) {
-        logErr(`subscribe: ticket refresh failed: ${e.message}`);
+        logErr(`subscribe: ticket refresh failed: ${errDetail(e)}`);
       }
     }
   };
@@ -303,7 +410,7 @@ async function run() {
   await loop();
 }
 
-function runOnce(ticket, baseUrl, token, refreshTicket) {
+function runOnce(ticket, baseUrl, getToken, refreshTicket) {
   return new Promise((resolve, reject) => {
     const allowedNs = new Set(ticket.namespace_ids);
     const wsUrl = `${ticket.realtime_url}?apikey=${encodeURIComponent(ticket.apikey)}&vsn=1.0.0`;
@@ -354,8 +461,8 @@ function runOnce(ticket, baseUrl, token, refreshTicket) {
       // otherwise wake the agent. Fire-and-forget: a transient HTTP
       // failure here just means we miss queued messages this round;
       // the next reconnect retries.
-      drainQueueOnce(baseUrl, token).catch((e) => {
-        logErr(`subscribe: queue check failed: ${e.message}`);
+      drainQueueOnce(baseUrl, getToken()).catch((e) => {
+        logErr(`subscribe: queue check failed: ${errDetail(e)}`);
       });
       heartbeatTimer = setInterval(() => {
         try {
@@ -392,8 +499,8 @@ function runOnce(ticket, baseUrl, token, refreshTicket) {
       // inbox is non-empty so a later idle tick has another chance to
       // wake the agent. drainQueueOnce stays silent if pending_count == 0.
       pendingHeartbeatTimer = setInterval(() => {
-        drainQueueOnce(baseUrl, token).catch((e) => {
-          logErr(`subscribe: pending heartbeat failed: ${e.message}`);
+        drainQueueOnce(baseUrl, getToken()).catch((e) => {
+          logErr(`subscribe: pending heartbeat failed: ${errDetail(e)}`);
         });
       }, PENDING_HEARTBEAT_MS);
 
@@ -438,7 +545,7 @@ function runOnce(ticket, baseUrl, token, refreshTicket) {
           // Transient network/server error — do NOT close the live
           // connection. The current JWT is still valid for ~2 more min
           // (JWT_REFRESH_SAFETY_MARGIN_SEC). Retry sooner.
-          logErr(`subscribe: token refresh failed, retrying in 30s: ${e.message}`);
+          logErr(`subscribe: token refresh failed, retrying in 30s: ${errDetail(e)}`);
           refreshTimer = setTimeout(doRefresh, 30_000);
         }
       };