patchcord 0.6.34 → 0.6.36

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

package/bin/patchcord.mjs

@@ -222,14 +222,29 @@ team (run from the project root):
   patchcord team status                     reconcile folder ↔ identity ↔ tmux ↔ token
   patchcord team launch                     launch each worker in mux
 
-projects (cloud-only — a free-text label grouping your own namespaces):
-  patchcord namespace set-project <namespace> <project>   assign a project label
-  patchcord namespace set-project <namespace>              clear it
+projects (cloud-only — groups your own namespaces into one initiative.
+  NOT just a label: the LEADS of Teams in one project can message each other
+  with no handshake. Any NON-lead still needs an approved link, below.):
+  patchcord project list                                  projects + their Teams
+  patchcord project create <name>                         explicit; nothing else creates one
+  patchcord project rename <project-id> <new-name>        label only; reach unchanged
+  patchcord project rm <project-id>                       Teams survive, un-grouped
+  patchcord namespace set-project <ns> <project>          assign (project must exist)
+  patchcord namespace set-project <ns> <project> --create  create it, then assign
+  patchcord namespace set-project <ns>                     un-group it
+  patchcord provision ... --project <name> [--create-project]
+  patchcord orchestrator ... --project <name> [--create-project]
+
+  A namespace in NO project has no cross-team peers at all — that is the
+  default and it is deliberate. Assignment never invents a project: an
+  unknown name is an error, because silently creating one on a typo made
+  mistyped projects invisible and unmanageable.
 
 cross-namespace links (cloud-only, no CLI — agent-to-agent via MCP:
   request_namespace_link(ns, agent) / respond_namespace_link(ns, agent, approve)
-  / list_my_namespace_links. Any agent, no lead role — but each link is to ONE
-  named agent, never the whole namespace; opt-in, not project-based.)
+  / list_my_namespace_links. Any agent, no lead role — each link is to ONE
+  named agent, never the whole namespace. This is the ONLY way to reach a
+  non-lead in another namespace, project or no project.)
 
 schedules:
   patchcord schedule create <name> --namespace <ns> --to <agent> --content "..."
@@ -1169,7 +1184,7 @@ if (cmd === "subscribe") {
 // account token (user-level, tied to NO agent) lives at ~/.patchcord/auth.json
 // (legacy: main.json / master.json) or $PATCHCORD_TOKEN (legacy: *_MAIN/MASTER).
 // `patchcord login` authenticates; everything else logs in on demand.
-if (cmd === "login" || cmd === "orchestrator" || cmd === "teamlead" || cmd === "provision" || cmd === "pull" || cmd === "team" || cmd === "schedule" || cmd === "namespace") {
+if (cmd === "login" || cmd === "orchestrator" || cmd === "teamlead" || cmd === "provision" || cmd === "pull" || cmd === "team" || cmd === "schedule" || cmd === "namespace" || cmd === "project" || cmd === "projects") {
   const M = { cyan: "\x1b[36m", green: "\x1b[32m", dim: "\x1b[2m", rst: "\x1b[0m" };
   const AUTH_CONFIG = join(HOME, ".patchcord", "auth.json");
   const LEGACY_CONFIGS = [join(HOME, ".patchcord", "main.json"), join(HOME, ".patchcord", "master.json")];
@@ -1195,6 +1210,42 @@ if (cmd === "login" || cmd === "orchestrator" || cmd === "teamlead" || cmd === "
   const forgetAuth = () => {
     for (const p of [AUTH_CONFIG, ...LEGACY_CONFIGS]) { try { unlinkSync(p); } catch {} }
   };
+  // Assign a namespace to a project, shared by `provision --project` and
+  // `orchestrator --project`.
+  //
+  // Assignment RESOLVES an existing project and NEVER creates one. The server
+  // used to create a project for any name it did not recognise, so a typo
+  // silently produced a new, invisible project — the defect that got an earlier
+  // version of this feature abandoned. `--create-project` makes creation an
+  // explicit act rather than a side effect of misspelling.
+  //
+  // warnOnly: a failure here must not fail the whole command. The agent
+  // identity is already provisioned and the credential is already on disk;
+  // exiting non-zero would make a working identity look like a failed one.
+  const assignProject = async (ns, project, { warnOnly = false, label = "done" } = {}) => {
+    if (process.argv.includes("--create-project")) {
+      const { status: cStatus, json: cJson } = await accountCall("POST", "/api/projects", { name: project });
+      if (cStatus === "201") console.log(`  ${M.dim}created project "${project}"${M.rst}`);
+      else if (cStatus !== "409") {
+        console.error(`  ${M.dim}warning: could not create project "${project}" (HTTP ${cStatus}): ${cJson?.error || ""}${M.rst}`);
+      }
+    }
+    const { status, json } = await accountCall("POST", "/api/namespace/set-project", { namespace_id: ns, project });
+    if (status === "200") {
+      console.log(`  ${M.dim}namespace ${ns} assigned to project "${project}" — its lead can now reach other leads in that project${M.rst}`);
+      return true;
+    }
+    if (status === "404") {
+      console.error(`  ${M.dim}warning: ${label}, but there is no project named "${project}".${M.rst}`);
+      console.error(`  ${M.dim}  create it:  patchcord project create ${project}${M.rst}`);
+      console.error(`  ${M.dim}  or re-run with --create-project${M.rst}`);
+    } else {
+      const retry = json?.retryable ? " (transient — retry shortly, your login is fine)" : "";
+      console.error(`  ${M.dim}warning: ${label}, but --project failed (HTTP ${status}): ${json?.error || ""}${retry}${M.rst}`);
+    }
+    if (!warnOnly) process.exit(1);
+    return false;
+  };
   const flagVal = (name, def = "") => {
     const eq = process.argv.find((a) => a.startsWith(`--${name}=`));
     if (eq) return eq.split("=").slice(1).join("=");
@@ -1504,69 +1555,248 @@ if (cmd === "login" || cmd === "orchestrator" || cmd === "teamlead" || cmd === "
         writeFileSync(tj, JSON.stringify(man, null, 2) + "\n");
       }
     } catch {}
-    // --project assigns this namespace to a project — an organizational label
-    // ONLY, does not affect cross-namespace messaging (that's namespace_links,
-    // agent-to-agent, no CLI). Separate call: provisioning creates the agent
-    // identity, project assignment groups the NAMESPACE — safe to retry
-    // independently, and a namespace already in a project just gets reassigned
-    // (last call wins, server-side upsert).
+    // --project assigns this namespace to a project: a grouping entity above
+    // the namespace. It DOES affect cross-namespace messaging — Teams in one
+    // project get a standing LEAD-TO-LEAD channel with no handshake. Reaching a
+    // NON-lead elsewhere still needs an approved namespace_links pair.
+    //
+    // Separate call: provisioning creates the agent identity, project assignment
+    // groups the NAMESPACE — safe to retry independently. Assignment RESOLVES an
+    // existing project and never creates one, so an unknown name is a 404, not a
+    // new project; pass --create-project to create it first, deliberately.
     if (project) {
-      const { status: pStatus, json: pJson } = await accountCall("POST", "/api/namespace/set-project", { namespace_id: ns, project });
-      if (pStatus !== "200") {
-        console.error(`  ${M.dim}warning: provisioned OK, but --project failed (HTTP ${pStatus}): ${pJson?.error || ""}${M.rst}`);
-      } else {
-        console.log(`  ${M.dim}namespace ${ns} assigned to project "${project}"${M.rst}`);
-      }
+      await assignProject(ns, project, { warnOnly: true, label: "provisioned OK" });
     }
     console.log(`✓ provisioned ${M.green}${ns}:${arg}${M.rst} [${tool}${role ? "/" + role : ""}${lead ? "/lead" : ""}] → ${dir}`);
     process.exit(0);
   }
 
   if (cmd === "namespace") {
-    // Cloud-only: group namespaces into a "project" — a free-text organizational
-    // label only. Does NOT gate cross-namespace lead chat — that's decided by
-    // per-pair namespace_links, approved lead-to-lead via the MCP tools
-    // request_namespace_link / respond_namespace_link (no CLI for that; see
-    // --help's CROSS-NAMESPACE LINKS section).
+    // Cloud-only: group namespaces into a PROJECT — a grouping entity above the
+    // namespace. It is NOT merely a label: Teams in one project get a standing
+    // LEAD-TO-LEAD message channel with no per-pair handshake. Reaching any
+    // NON-lead in another namespace still requires an approved namespace_links
+    // pair, agent-to-agent via the MCP tools request_namespace_link /
+    // respond_namespace_link (no CLI for that; see --help's CROSS-NAMESPACE
+    // LINKS section).
     const sub = process.argv[3];
     if (sub === "set-project") {
       const ns = process.argv[4];
-      const project = process.argv[5];
-      if (!ns) { console.error("Usage: patchcord namespace set-project <namespace> [project-name]\n  Omit project-name to clear the label."); process.exit(1); }
+      const project = (process.argv[5] || "").startsWith("-") ? "" : (process.argv[5] || "");
+      const doCreate = process.argv.includes("--create");
+      if (!ns) { console.error("Usage: patchcord namespace set-project <namespace> [project-name] [--create]\n  Omit project-name to un-group the namespace."); process.exit(1); }
+      if (doCreate && !project) { console.error("--create needs a project name."); process.exit(1); }
+      // Assignment RESOLVES an existing project and never creates one. The
+      // server used to create a project for any unrecognised name, which turned
+      // every typo into a new invisible project; --create makes creation an
+      // explicit act instead of a side effect of misspelling.
+      if (doCreate) {
+        const { status: cStatus, json: cJson } = await accountCall("POST", "/api/projects", { name: project });
+        if (cStatus === "201") console.log(`  ${M.dim}created project "${project}"${M.rst}`);
+        else if (cStatus === "409") console.log(`  ${M.dim}project "${project}" already exists — assigning to it${M.rst}`);
+        else { console.error(`could not create project (HTTP ${cStatus}): ${cJson?.error || ""}`); process.exit(1); }
+      }
       const { status, json } = await accountCall("POST", "/api/namespace/set-project", { namespace_id: ns, project: project || "" });
-      if (status !== "200") { console.error(`set-project failed (HTTP ${status}): ${json?.error || ""}`); process.exit(1); }
+      if (status === "404") {
+        console.error(`No project named "${project}".`);
+        console.error(`  Create it first:  patchcord project create ${project}`);
+        console.error(`  Or in one step:   patchcord namespace set-project ${ns} ${project} --create`);
+        process.exit(1);
+      }
+      if (status !== "200") { console.error(`set-project failed (HTTP ${status}): ${json?.error || ""}${json?.retryable ? " (transient — retry)" : ""}`); process.exit(1); }
       if (json.status === "cleared") {
-        console.log(`✓ ${ns} un-grouped — no project label`);
+        console.log(`✓ ${ns} un-grouped — belongs to no project, and its lead has no cross-team peers`);
       } else {
-        console.log(`✓ ${ns} assigned to project "${json.project}" (label only — does not affect cross-namespace messaging)`);
+        console.log(`✓ ${ns} assigned to project "${json.project}"`);
+        console.log(`  ${M.dim}its LEAD can now message the leads of other Teams in this project;${M.rst}`);
+        console.log(`  ${M.dim}other agents still need an approved link (request_namespace_link)${M.rst}`);
       }
       process.exit(0);
     }
-    console.error("Usage: patchcord namespace set-project <namespace> [project-name]");
+    console.error("Usage: patchcord namespace set-project <namespace> [project-name] [--create]");
+    process.exit(1);
+  }
+
+  // ── projects: the grouping entity above namespaces ──────────────────
+  // Exists because the server deliberately does NOT create a project as a side
+  // effect of assignment. Without a create/list path here, the only way to make
+  // one was a raw API call — and without a LIST path, a mistyped project was
+  // invisible, which is the exact defect that got an earlier version of this
+  // feature abandoned.
+  if (cmd === "project" || cmd === "projects") {
+    const sub = process.argv[3] || "list";
+    const fail = (status, json, what) => {
+      const retry = json?.retryable ? " (transient — retry shortly, your login is fine)" : "";
+      console.error(`${what} failed (HTTP ${status}): ${json?.error || ""}${retry}`);
+      process.exit(1);
+    };
+
+    if (sub === "list" || sub === "ls") {
+      const { status, json } = await accountCall("GET", "/api/projects");
+      if (status !== "200") fail(status, json, "project list");
+      const projects = json?.projects || [];
+      if (!projects.length) {
+        console.log("No projects yet.");
+        console.log(`  ${M.dim}patchcord project create <name>${M.rst}`);
+        process.exit(0);
+      }
+      for (const p of projects) {
+        const members = (p.namespaces || []);
+        console.log(`${M.green}${p.name}${M.rst}  ${M.dim}${p.id}${M.rst}`);
+        if (members.length) for (const ns of members) console.log(`  · ${ns}`);
+        else console.log(`  ${M.dim}(no Teams assigned)${M.rst}`);
+      }
+      process.exit(0);
+    }
+
+    if (sub === "create" || sub === "add") {
+      const name = process.argv[4];
+      if (!name) { console.error("Usage: patchcord project create <name>"); process.exit(1); }
+      const { status, json } = await accountCall("POST", "/api/projects", { name });
+      if (status === "409") { console.error(`A project named "${name}" already exists.`); process.exit(1); }
+      if (status !== "201") fail(status, json, "project create");
+      console.log(`✓ created project "${json.name}"  ${M.dim}${json.id}${M.rst}`);
+      console.log(`  ${M.dim}patchcord namespace set-project <namespace> ${json.name}${M.rst}`);
+      process.exit(0);
+    }
+
+    if (sub === "rename" || sub === "mv") {
+      const id = process.argv[4];
+      const name = process.argv[5];
+      if (!id || !name) { console.error("Usage: patchcord project rename <project-id> <new-name>\n  Get the id from `patchcord project list`."); process.exit(1); }
+      const { status, json } = await accountCall("PATCH", `/api/projects/${encodeURIComponent(id)}`, { name });
+      if (status === "404") { console.error(`No project with id ${id}.`); process.exit(1); }
+      if (status === "409") { console.error(`A project named "${name}" already exists.`); process.exit(1); }
+      if (status !== "200") fail(status, json, "project rename");
+      console.log(`✓ renamed to "${json.name}"  ${M.dim}(membership and reach unchanged — this is only the label)${M.rst}`);
+      process.exit(0);
+    }
+
+    if (sub === "rm" || sub === "delete") {
+      const id = process.argv[4];
+      if (!id) { console.error("Usage: patchcord project rm <project-id>\n  Get the id from `patchcord project list`."); process.exit(1); }
+      const { status, json } = await accountCall("DELETE", `/api/projects/${encodeURIComponent(id)}`);
+      if (status === "404") { console.error(`No project with id ${id}.`); process.exit(1); }
+      if (status !== "200") fail(status, json, "project rm");
+      const ungrouped = json?.ungrouped_namespaces || [];
+      console.log(`✓ deleted project ${M.dim}${id}${M.rst}`);
+      if (ungrouped.length) {
+        // Deleting a project withdraws the lead-to-lead channel between exactly
+        // these Teams. Fail-closed — reach is only ever removed here, never
+        // widened — but it must be stated rather than discovered.
+        console.log(`  ${ungrouped.length} Team(s) un-grouped; their leads no longer reach each other:`);
+        for (const ns of ungrouped) console.log(`  · ${ns}`);
+      } else {
+        console.log(`  ${M.dim}no Teams were assigned to it${M.rst}`);
+      }
+      process.exit(0);
+    }
+
+    console.error("Usage: patchcord project <list|create|rename|rm>");
     process.exit(1);
   }
 
   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;
+      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);
+          if (probe.status !== "200") continue;         // dead or superseded — skip
+          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) {
+        // Reuse is an optimisation over the old behaviour; if it cannot run we
+        // fall through and mint, exactly as before.
+        console.error(`  ${M.dim}(could not check for a reusable credential: ${e?.message || e})${M.rst}`);
+      }
+      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 {
@@ -1595,21 +1825,17 @@ if (cmd === "login" || cmd === "orchestrator" || cmd === "teamlead" || cmd === "
     const project = flagVal("project", "");
     const hostname = run("hostname -s") || run("hostname") || "unknown";
     // is_lead: true always — the orchestrator IS the one identity per namespace
-    // meant to coordinate across teams. Harmless by itself: a lead only reaches
-    // another namespace's lead after an approved namespace_links pair (agent-to-
-    // agent via request_namespace_link/respond_namespace_link — fails closed
-    // until both leads explicitly consent).
+    // meant to coordinate across teams. Not harmless by itself any more: a lead
+    // reaches another namespace's lead EITHER after an approved namespace_links
+    // pair (agent-to-agent via request_namespace_link/respond_namespace_link) OR
+    // when both namespaces sit in the same PROJECT, which needs no handshake.
+    // So --project below is a reachability decision, not just a label.
     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(\/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 });
-      if (pStatus !== "200") {
-        console.error(`  ${M.dim}warning: orchestrator set up OK, but --project failed (HTTP ${pStatus}): ${pJson?.error || ""}${M.rst}`);
-      } else {
-        console.log(`  ${M.dim}namespace ${ns} assigned to project "${project}"${M.rst}`);
-      }
+      await assignProject(ns, project, { warnOnly: true, label: "orchestrator set up OK" });
     }
     mkdirSync(join(root, ".patchcord"), { recursive: true });
     const tj = join(root, ".patchcord", "team.json");
@@ -4034,5 +4260,5 @@ if (cmd === "skill") {
   process.exit(0);
 }
 
-console.error(`Unknown command: ${cmd}. Available: install, whoami, agents, upload, subscribe, update, login, provision, pull, orchestrator, team, schedule, --rename, --token, --agent-type, --version, --help`);
+console.error(`Unknown command: ${cmd}. Available: install, whoami, agents, upload, subscribe, update, login, provision, pull, orchestrator, team, project, namespace, schedule, --rename, --token, --agent-type, --version, --help`);
 process.exit(1);

package/package.json

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