patchcord 0.6.27 → 0.6.29

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

package/bin/patchcord.mjs

@@ -16,7 +16,9 @@ const cmd = process.argv[2];
 
 /** Write a file then chmod 0600 (token-bearing configs must not be group/world readable). */
 function writeSecureFile(path, contents) {
-  writeFileSync(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;
 }
@@ -184,6 +186,19 @@ team (run from the project root):
                                              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 deployment request --namespace <ns> [--revision <uid>] [--json]
+                                             enqueue an apply of a saved revision
+                                             (exit 3 = one is already in flight)
+  patchcord team deployment pending [--json] jobs waiting for this host to claim
+  patchcord team deployment claim --job <uid> [--installation <name>] [--json]
+                                             take ownership (exit 3 = lost the race)
+  patchcord team deployment complete --job <uid> --status <healthy|degraded|cancelled>
+                                             [--result <json> | --result-file <path>] [--json]
+  patchcord team deployment get --namespace <ns> (--job <uid> | --active) [--json]
+                                             one job, or the namespace's active job
   patchcord team status                     reconcile folder ↔ identity ↔ tmux ↔ token
   patchcord team launch                     launch each worker in mux
 
@@ -725,7 +740,10 @@ if (cmd === "whoami") {
   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.`);
@@ -1412,7 +1430,7 @@ if (cmd === "login" || cmd === "orchestrator" || cmd === "teamlead" || cmd === "
     if (lead) provisionBody.is_lead = true;
     const { status, json, m } = await accountCall("POST", "/api/provision", provisionBody);
     if (status !== "200" || !json?.token) { console.error(`provision failed (HTTP ${status}): ${json?.error || ""}`); process.exit(1); }
-    const base = String(json.url || `${m.baseUrl}/mcp`).replace(/\/mcp$/, "");
+    const base = String(json.url || `${m.baseUrl}/mcp`).replace(/\/mcp(\/bearer)?$/, "");
     const dir = join(process.cwd(), subdir);
     const hostname = run("hostname -s") || run("hostname") || "unknown";
     writeWorkerConfig(tool, dir, base, json.token, hostname);
@@ -1492,7 +1510,7 @@ if (cmd === "login" || cmd === "orchestrator" || cmd === "teamlead" || cmd === "
     const { status, json, m } = await accountCall("POST", "/api/provision", pullBody);
     if (status === "404") { console.error(`no agent ${M.green}${ns}:${arg}${M.rst} to pull — create it with: patchcord provision ${arg} --tool ${tool} --namespace ${ns}`); process.exit(1); }
     if (status !== "200" || !json?.token) { console.error(`pull failed (HTTP ${status}): ${json?.error || ""}`); process.exit(1); }
-    const base = String(json.url || `${m.baseUrl}/mcp`).replace(/\/mcp$/, "");
+    const base = String(json.url || `${m.baseUrl}/mcp`).replace(/\/mcp(\/bearer)?$/, "");
     const dir = join(process.cwd(), subdir);
     const hostname = run("hostname -s") || run("hostname") || "unknown";
     writeWorkerConfig(tool, dir, base, json.token, hostname);
@@ -1529,7 +1547,7 @@ if (cmd === "login" || cmd === "orchestrator" || cmd === "teamlead" || cmd === "
     // until both leads explicitly consent).
     const { status, json, m } = await accountCall("POST", "/api/provision", { namespace_id: ns, agent_id: "orchestrator", tool, role: "orchestrator", label: "orchestrator:self", is_lead: true });
     if (status !== "200" || !json?.token) { console.error(`could not set up orchestrator (HTTP ${status}): ${json?.error || ""}`); process.exit(1); }
-    const base = String(json.url || `${m.baseUrl}/mcp`).replace(/\/mcp$/, "");
+    const base = String(json.url || `${m.baseUrl}/mcp`).replace(/\/mcp(\/bearer)?$/, "");
     writeWorkerConfig(tool, root, base, json.token, hostname);
     if (project) {
       const { status: pStatus, json: pJson } = await accountCall("POST", "/api/namespace/set-project", { namespace_id: ns, project });
@@ -1637,7 +1655,165 @@ you design the team, provision its agents, launch them, and manage them.
         console.log(`canonical_json: ${JSON.stringify(json.canonical_json)}`);
         process.exit(0);
       }
-      console.error("Usage: patchcord team blueprint current --namespace <ns> [--json]");
+      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 === "deployment" || sub === "deployments") {
+      // Deploy = apply a saved revision to live panes. Deliberately NOT part of
+      // a save: `blueprint push` writes an immutable revision, this asks the
+      // owning Mux installation to enact one. Mux shells out to these; its
+      // poller treats an unknown subcommand as an empty pending list, so an
+      // older CLI degrades to "nothing to do" rather than crashing a host.
+      const dsub = process.argv[4];
+      const wantJson = process.argv.includes("--json");
+      const fail = (label, status, json, body) => {
+        const detail = (json && (json.error || json.code || JSON.stringify(json.detail))) || body || "";
+        console.error(`deployment ${label} failed (HTTP ${status}): ${detail}`);
+        process.exit(1);
+      };
+      const emit = (json) => {
+        if (wantJson) { process.stdout.write(JSON.stringify(json) + "\n"); process.exit(0); }
+      };
+      const printJob = (j) => {
+        console.log(`job_uid: ${j.job_uid}`);
+        console.log(`namespace: ${j.namespace}`);
+        console.log(`status: ${j.status}`);
+        console.log(`revision_uid: ${j.revision_uid}`);
+        console.log(`sha256: ${j.sha256}`);
+        if (j.claimed_by) console.log(`claimed_by: ${j.claimed_by}`);
+        if (j.result && Object.keys(j.result).length) console.log(`result: ${JSON.stringify(j.result)}`);
+      };
+
+      if (dsub === "request") {
+        const ns = flagVal("namespace");
+        const rev = flagVal("revision");
+        if (!ns) { console.error("Usage: patchcord team deployment request --namespace <ns> [--revision <uid>] [--json]"); process.exit(1); }
+        const payload = rev ? { revision_uid: rev } : {};
+        const { status, json, body } = await accountCall("POST", `/api/team/${encodeURIComponent(ns)}/deployments`, payload);
+        // 409 is not an error to the caller: a deploy is already in flight and
+        // the response carries it, so emit that job rather than failing. The
+        // exit code still distinguishes the two.
+        if (status === "409" && json && json.job) {
+          if (wantJson) { process.stdout.write(JSON.stringify({ ...json.job, already_active: true }) + "\n"); process.exit(3); }
+          console.log(`already active (${json.code})`);
+          printJob(json.job);
+          process.exit(3);
+        }
+        if (status !== "200" && status !== "201") fail("request", status, json, body);
+        emit(json);
+        printJob(json);
+        process.exit(0);
+      }
+
+      if (dsub === "pending") {
+        const { status, json, body } = await accountCall("GET", "/api/deployments/pending");
+        if (status !== "200") fail("pending", status, json, body);
+        emit(json);
+        const jobs = (json && json.jobs) || [];
+        if (!jobs.length) { console.log("(no pending deployments)"); process.exit(0); }
+        for (const j of jobs) console.log(`  ${j.job_uid}  ${j.namespace}  ${j.sha256.slice(0, 12)}  ${j.status}`);
+        process.exit(0);
+      }
+
+      if (dsub === "claim") {
+        const job = flagVal("job");
+        const installation = flagVal("installation");
+        if (!job) { console.error("Usage: patchcord team deployment claim --job <uid> [--installation <name>] [--json]"); process.exit(1); }
+        const { status, json, body } = await accountCall(
+          "POST", `/api/deployments/${encodeURIComponent(job)}/claim`,
+          installation ? { installation } : {},
+        );
+        // Losing a claim race is normal in a multi-host account, not a failure:
+        // exit 3 so a poller can skip to the next job without parsing stderr.
+        if (status === "409") {
+          if (wantJson) { process.stdout.write(JSON.stringify(json) + "\n"); process.exit(3); }
+          console.log(`not claimable (${(json && json.code) || "conflict"})`);
+          process.exit(3);
+        }
+        if (status !== "200") fail("claim", status, json, body);
+        emit(json);
+        printJob(json);
+        process.exit(0);
+      }
+
+      if (dsub === "complete") {
+        const job = flagVal("job");
+        const st = flagVal("status");
+        const resultRaw = flagVal("result");
+        const resultFile = flagVal("result-file");
+        if (!job || !st) {
+          console.error("Usage: patchcord team deployment complete --job <uid> --status <healthy|degraded|cancelled> [--result <json> | --result-file <path>] [--json]");
+          process.exit(1);
+        }
+        let result = {};
+        try {
+          if (resultFile) result = JSON.parse(readFileSync(resultFile, "utf-8"));
+          else if (resultRaw) result = JSON.parse(resultRaw);
+        } catch (e) { console.error(`cannot parse result JSON: ${e.message}`); process.exit(1); }
+        const { status, json, body } = await accountCall(
+          "POST", `/api/deployments/${encodeURIComponent(job)}/complete`,
+          { status: st, result },
+        );
+        if (status === "409") {
+          // The lease lapsed and the job was requeued or failed while this host
+          // was applying. Reporting into it would overwrite a fresher attempt.
+          if (wantJson) { process.stdout.write(JSON.stringify(json) + "\n"); process.exit(3); }
+          console.log(`not running (${(json && json.code) || "conflict"}) — lease likely lapsed`);
+          process.exit(3);
+        }
+        if (status !== "200") fail("complete", status, json, body);
+        emit(json);
+        printJob(json);
+        process.exit(0);
+      }
+
+      if (dsub === "get") {
+        const ns = flagVal("namespace");
+        const job = flagVal("job");
+        const active = process.argv.includes("--active");
+        if (!ns || (!job && !active)) {
+          console.error("Usage: patchcord team deployment get --namespace <ns> (--job <uid> | --active) [--json]");
+          process.exit(1);
+        }
+        const path = active
+          ? `/api/team/${encodeURIComponent(ns)}/deployments?active=1`
+          : `/api/team/${encodeURIComponent(ns)}/deployments/${encodeURIComponent(job)}`;
+        const { status, json, body } = await accountCall("GET", path);
+        if (status !== "200") fail("get", status, json, body);
+        emit(json);
+        const j = active ? (json && json.job) : json;
+        if (!j) { console.log("(no active deployment)"); process.exit(0); }
+        printJob(j);
+        process.exit(0);
+      }
+
+      console.error("Usage: patchcord team deployment <request|pending|claim|complete|get> [--json]");
       process.exit(1);
     }
     if (sub === "status") {
@@ -1776,7 +1952,7 @@ you design the team, provision its agents, launch them, and manage them.
       }
       process.exit(0);
     }
-    console.error("Usage: patchcord team <list|blueprint|launch|status>");
+    console.error("Usage: patchcord team <list|blueprint|deployment|launch|status>");
     process.exit(1);
   }
 
@@ -2158,6 +2334,40 @@ if (!cmd || cmd === "install" || cmd === "agent" || cmd?.startsWith("--")) {
       if (_approveCursorProjectMcp(process.cwd())) {
         globalChanges.push("Cursor MCP approved for this project");
       }
+
+      // Stop hook — a SECOND wake path, independent of the subscribe listener.
+      // The listener's notify_on_output wakes a seat both busy and idle
+      // (verified live), so an armed listener needs no help. This covers the
+      // case where no listener is running at all: never armed, armed without
+      // notify_on_output, or the process died. The `stop` hook fires on the
+      // harness's own event and needs no long-lived process, so it survives
+      // exactly the failure that silences subscribe.
+      // NOTE: cursor-agent loads ~/.cursor/hooks.json at STARTUP only — a
+      // session already running when this is written will not fire it.
+      const cursorHookSrc = join(pluginRoot, "scripts", "cursor-stop-hook.sh");
+      if (existsSync(cursorHookSrc)) {
+        const cursorHookDest = join(HOME, ".cursor", "patchcord-stop-hook.sh");
+        const hookExisted = existsSync(cursorHookDest);
+        mkdirSync(join(HOME, ".cursor"), { recursive: true });
+        cpSync(cursorHookSrc, cursorHookDest);
+        chmodSync(cursorHookDest, 0o755);
+
+        const cursorHooksPath = join(HOME, ".cursor", "hooks.json");
+        const hooksOk = updateJsonConfig(cursorHooksPath, (obj) => {
+          if (obj.version === undefined) obj.version = 1;
+          if (!obj.hooks || typeof obj.hooks !== "object" || Array.isArray(obj.hooks)) obj.hooks = {};
+          const existing = Array.isArray(obj.hooks.stop) ? obj.hooks.stop : [];
+          // Drop any prior patchcord entry (path may have moved) and re-add.
+          const kept = existing.filter((e) => !JSON.stringify(e).includes("patchcord-stop-hook"));
+          kept.push({ command: cursorHookDest });
+          obj.hooks.stop = kept;
+        });
+        if (!hooksOk) {
+          globalChanges.push("✗ Cursor stop hook error");
+        } else {
+          globalChanges.push(`Cursor stop hook ${hookExisted ? "updated" : "installed"}`);
+        }
+      }
     }
   }
 
@@ -2486,6 +2696,15 @@ if (!cmd || cmd === "install" || cmd === "agent" || cmd?.startsWith("--")) {
       copyFileSync(hookScriptSrc, hookScriptDest);
       chmodSync(hookScriptDest, 0o755);
 
+      // The hook sources this for the identity hint + loop brake. It lives in
+      // scripts/lib/ in the repo, but the hook runs from ~/.codex, so ship a
+      // copy beside it — otherwise the hook silently falls back to the older,
+      // loop-prone wording.
+      const guardSrc = join(pluginRoot, "scripts", "lib", "inbox-guard.sh");
+      if (existsSync(guardSrc)) {
+        copyFileSync(guardSrc, join(HOME, ".codex", "patchcord-inbox-guard.sh"));
+      }
+
       // Enable the `hooks` feature flag exactly once. Older installs / Codex
       // versions may leave `codex_hooks = true`, `hooks=true` (no spaces), a
       // `hooks = false`, or even a duplicate `hooks = true` — any of which makes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "patchcord",
-  "version": "0.6.27",
+  "version": "0.6.29",
   "description": "Cross-machine agent messaging for Claude Code and Codex",
   "scripts": {
     "version": "node scripts/sync-plugin-version.mjs && git add .claude-plugin/plugin.json"

package/scripts/check-inbox.sh

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

package/scripts/codex-stop-hook.sh

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

package/scripts/cursor-stop-hook.sh

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

package/scripts/lib/inbox-guard.sh

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