patchcord 0.6.35 → 0.6.37

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

package/bin/patchcord.mjs

@@ -1698,25 +1698,139 @@ if (cmd === "login" || cmd === "orchestrator" || cmd === "teamlead" || cmd === "
 
   if (cmd === "pull") {
     // Inverse of provision: place an EXISTING agent identity into a folder.
-    // 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.
+    //
+    // REUSE FIRST, MINT ONLY AS A LAST RESORT. This command is named `pull` and
+    // its whole purpose is "use the identity that already exists", but it used
+    // to go straight to POST /api/provision — which MINTS a new token and, via
+    // insert_bearer_token's supersede, deactivates every prior token for that
+    // identity. So a `pull` silently killed the credential held in memory by any
+    // LIVE session of the same agent.
+    //
+    // That is not a theoretical concern: `mux new <seat>` calls this on every
+    // relaunch whenever the identity already exists, so relaunching one seat
+    // revoked the running session's token. Nobody typed `patchcord pull`, no
+    // deploy ran, and no revoke was requested — yet agents lost patchcord
+    // mid-session with no visible cause. Worse, the documented recovery for a
+    // dead token was to re-run pull/provision, which armed the next one.
+    //
+    // The server cannot hand back an existing token: only the HASH is stored
+    // (plaintext was deliberately dropped). So reuse has to happen HERE, from a
+    // config already on this machine, and be proven live before it is trusted.
     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); }
+    if (!arg || arg.startsWith("-")) { console.error("Usage: patchcord pull <agent> --namespace ns --tool X [--dir sub/] [--lead] [--force-remint]"); process.exit(1); }
     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
+    const forceRemint = process.argv.includes("--force-remint");
     if (!ns) { console.error("--namespace <project-namespace> required"); process.exit(1); }
+
+    const dir = join(process.cwd(), subdir);
+    const hostname = run("hostname -s") || run("hostname") || "unknown";
+
+    // ── Phase 1: is a healthy credential for this exact identity already here?
+    // Verified against the server rather than assumed from the file: a token on
+    // disk may itself already be superseded, and writing a dead credential
+    // forward would be worse than reminting. whoami is a read — it cannot
+    // supersede anything.
+    if (!forceRemint) {
+      let reusable = null;
+      let undetermined = null;   // a candidate we could NOT judge — see below
+      try {
+        const { listProjectBearers } = await import(
+          new URL("../scripts/lib/resolve-project-bearer.mjs", import.meta.url).href
+        );
+        const seen = new Set();
+        // The target folder first (the common case: relaunching a seat whose
+        // config is already correct), then upward through the project.
+        for (const cand of [...listProjectBearers(dir), ...listProjectBearers(process.cwd())]) {
+          if (!cand?.token || seen.has(cand.token)) continue;
+          seen.add(cand.token);
+          const baseUrl = String(cand.url || "").replace(/\/mcp(\/bearer)?$/, "") || DEFAULT_API;
+          const probe = await _httpJSON("GET", `${baseUrl}/api/agent/whoami`, cand.token);
+          const code = String(probe.status ?? "");
+
+          // THREE outcomes, not two. Collapsing them is the whole bug class this
+          // command exists to stop causing:
+          //
+          //   401/403  the credential is genuinely dead (revoked in the web
+          //            console, or superseded). Skip it; minting is CORRECT.
+          //   200      alive — check whose it is below.
+          //   anything else (000 from a failed connection, null when curl itself
+          //            died, any 5xx) we DO NOT KNOW. Treating "could not ask"
+          //            as "dead" would skip a HEALTHY token and mint, which
+          //            destroys the live session this command exists to protect
+          //            — and it would do that exactly when the backend is
+          //            already unwell. Absent, dead and unavailable are three
+          //            different answers.
+          if (code === "401" || code === "403") continue;
+          if (code !== "200") {
+            undetermined = { token: cand.token, base: baseUrl, code: code || "no response" };
+            continue;
+          }
+
+          const who = probe.json || {};
+          const gotNs = who.namespace_id || who.namespace || (who.self && who.self.namespace_id);
+          const gotAgent = who.agent_id || who.agent || (who.self && who.self.agent_id);
+          // Must be the SAME identity. A live token for a DIFFERENT agent is not
+          // a substitute — writing it here would hand this folder another
+          // agent's identity, which is how seats end up impersonating peers.
+          if (String(gotNs) === ns && String(gotAgent) === arg) {
+            reusable = { token: cand.token, base: baseUrl };
+            break;
+          }
+        }
+      } catch (e) {
+        // A crash in the reuse scan is itself "undetermined", not "dead". Same
+        // reasoning: never let a local failure authorise a destructive remint.
+        undetermined = undetermined || { code: `scan failed: ${e?.message || e}` };
+      }
+
+      // Could not determine, and found nothing provably alive: STOP. Do not
+      // mint. Minting is the irreversible half of this command — it kills a
+      // credential a running session may be holding — and an unreachable server
+      // is not evidence that anything needs replacing. Retrying is free; a
+      // revoked live session is not.
+      if (!reusable && undetermined) {
+        console.error(`✗ cannot verify the existing credential for ${M.green}${ns}:${arg}${M.rst} (${undetermined.code}).`);
+        console.error(`  Refusing to mint a replacement: that would revoke the token any`);
+        console.error(`  running session for this agent is currently using.`);
+        console.error(`  ${M.dim}Retry when the server is reachable, or force it deliberately with --force-remint.${M.rst}`);
+        process.exit(1);
+      }
+      if (reusable) {
+        writeWorkerConfig(tool, dir, reusable.base, reusable.token, hostname);
+        try {
+          const tj = join(process.cwd(), ".patchcord", "team.json");
+          if (existsSync(tj)) {
+            const man = JSON.parse(readFileSync(tj, "utf-8"));
+            man.agents = (man.agents || []).filter((a) => a.agent !== arg);
+            man.agents.push({ agent: arg, tool, dir: subdir, namespace: ns });
+            writeFileSync(tj, JSON.stringify(man, null, 2) + "\n");
+          }
+        } catch {}
+        console.log(`✓ pulled ${M.green}${ns}:${arg}${M.rst} [${tool}] → ${dir}`);
+        console.log(`  ${M.dim}reused the existing live credential — nothing was superseded,${M.rst}`);
+        console.log(`  ${M.dim}so any running session for this agent keeps working.${M.rst}`);
+        process.exit(0);
+      }
+    }
+
+    // ── Phase 2: no healthy local credential. Minting is the only option left,
+    // and it WILL supersede. Say so, loudly, before doing it — this is the step
+    // that kills live sessions and it must never again be silent.
+    console.error(`  ${M.dim}no healthy local credential for ${ns}:${arg} — minting a new one.${M.rst}`);
+    console.error(`  ${M.dim}This SUPERSEDES any token this identity is currently using:${M.rst}`);
+    console.error(`  ${M.dim}a live session holding the old one will start failing and must reconnect its MCP client.${M.rst}`);
     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(\/bearer)?$/, "");
-    const dir = join(process.cwd(), subdir);
-    const hostname = run("hostname -s") || run("hostname") || "unknown";
+    if (typeof json.superseded === "number" && json.superseded > 0) {
+      console.error(`  ${M.dim}superseded ${json.superseded} previously-active token(s) for ${ns}:${arg}.${M.rst}`);
+    }
     writeWorkerConfig(tool, dir, base, json.token, hostname);
     // Record in the local team manifest so `team launch` / `team status` see it.
     try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "patchcord",
-  "version": "0.6.35",
+  "version": "0.6.37",
   "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

@@ -14,6 +14,7 @@ else
   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 ''; }
+  pc_streak_n() { printf '1'; }
 fi
 
 INPUT=$(cat)
@@ -161,5 +162,9 @@ if [ -n "$STREAK_STATE" ] \
 fi
 
 touch "$NOTIFY_LOCK"
-REASON=$(pc_inbox_reason "$COUNT" "$NAMESPACE" "$AGENT_ID" "inbox()" "restart this Claude Code session")
+# Read the streak AFTER pc_streak_ok has incremented it, so the text can
+# escalate on evidence: quiet on the first nudge, and only explaining the
+# stale-token condition once a repeat proves inbox() did not clear it.
+NUDGE_STREAK=$(pc_streak_n "$STREAK_STATE" 2>/dev/null || echo 1)
+REASON=$(pc_inbox_reason "$COUNT" "$NAMESPACE" "$AGENT_ID" "inbox()" "restart this Claude Code session" "$NUDGE_STREAK")
 jq -n --arg reason "$REASON" '{"decision": "block", "reason": $reason}'

package/scripts/codex-stop-hook.sh

@@ -20,6 +20,7 @@ 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 ''; }
+  pc_streak_n() { printf '1'; }
 fi
 
 INPUT=$(cat)
@@ -104,5 +105,8 @@ if [ -n "$STREAK_STATE" ] \
 fi
 
 touch "$NOTIFY_LOCK"
-REASON=$(pc_inbox_reason "$COUNT" "$NAMESPACE" "$AGENT_ID" "inbox()" "restart this Codex session")
+# See check-inbox.sh: quiet on the first nudge, explain only once a repeat has
+# proved inbox() did not clear it.
+NUDGE_STREAK=$(pc_streak_n "$STREAK_STATE" 2>/dev/null || echo 1)
+REASON=$(pc_inbox_reason "$COUNT" "$NAMESPACE" "$AGENT_ID" "inbox()" "restart this Codex session" "$NUDGE_STREAK")
 jq -n --arg reason "$REASON" '{"decision":"block","reason":$reason}'

package/scripts/lib/inbox-guard.sh

@@ -20,15 +20,42 @@
 #   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>
+# pc_inbox_reason <count> <namespace> <agent> <inbox_call> <restart_hint> [streak]
 #
 # 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.
+# agent can recognise the mismatch.
+#
+# THE STALE-IDENTITY EXPLANATION IS ONLY EMITTED ONCE THE SYMPTOM HAS ACTUALLY
+# OCCURRED. It used to be appended to EVERY nudge, fleet-wide, which was wrong
+# for three reasons:
+#
+#   1. It is ~7 lines of failure analysis attached to "you have one message" —
+#      the overwhelmingly common case, where nothing is wrong at all.
+#   2. It made every agent read a paragraph about its own credential possibly
+#      being dead, on every single nudge. That is not neutral: an agent told
+#      often enough that its identity may be broken starts diagnosing that
+#      instead of doing the work. One harness did exactly this — it hit a normal
+#      empty inbox, concluded "the session token appears stale or replaced",
+#      refused to call inbox() again for the rest of the session, and asked the
+#      human to restart. Nothing was wrong with its token. The nudge taught it
+#      that conclusion.
+#   3. A warning that fires on every occasion carries no information on any
+#      occasion. It gets skimmed, and then it is not there when it matters.
+#
+# `streak` is the consecutive-identical-block count from pc_streak_ok. A streak
+# of 1 means "first time we are telling you" — short text, no theory. A streak of
+# 2+ means the agent has already been nudged for this exact identity and count
+# and it did NOT clear, which is the actual evidence of the stale-token
+# condition. That is when the explanation is worth its length.
+#
+# Omitted/unknown streak is treated as the first block, i.e. short. Callers that
+# do not pass it keep the quiet wording, which is the safe default.
 pc_inbox_reason() {
   local count="$1" ns="$2" agent="$3" call="${4:-inbox()}" hint="${5:-restart this session}"
+  local streak="${6:-1}"
   local noun="message(s)"
   [ "$count" = "1" ] && noun="message"
+  case "$streak" in ''|*[!0-9]*) streak=1 ;; esac
 
   if [ -z "$ns" ] || [ -z "$agent" ]; then
     printf '%s patchcord %s waiting. Call %s and reply to all immediately.' \
@@ -36,13 +63,34 @@ pc_inbox_reason() {
     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.' \
+  if [ "$streak" -lt 2 ]; then
+    printf '%s patchcord %s waiting for %s@%s. Call %s and reply to all immediately.' \
+      "$count" "$noun" "$agent" "$ns" "$call"
+    return
+  fi
+
+  printf 'STILL %s patchcord %s waiting for %s@%s after a previous nudge — %s did not clear it. Call %s once more. If it 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. In that case 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" \
+    "$agent" "$ns" \
     "$call" "$hint"
 }
 
+# pc_streak_n <state_file>
+#
+# The current consecutive-identical-block count, or 0. Read AFTER pc_streak_ok
+# has run, so it reflects this block. Exists so the nudge text can escalate on
+# evidence instead of warning unconditionally.
+pc_streak_n() {
+  local prev n
+  prev=$(cat "$1" 2>/dev/null || true)
+  [ -n "$prev" ] || { printf '0'; return; }
+  n="${prev##*|}"
+  case "$n" in ''|*[!0-9]*) n=0 ;; esac
+  printf '%s' "$n"
+}
+
 # pc_streak_ok <state_file> <key> <max>
 #
 # Consecutive-identical-block breaker. `key` should encode identity + count, so