patchcord 0.6.2 → 0.6.5

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

package/bin/patchcord.mjs

@@ -93,7 +93,7 @@ agent:
   patchcord whoami                          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]            start the realtime listener
+  patchcord subscribe [interval] [--kimi]   realtime listener (Kimi: poll + exit)
   patchcord upload <file> [--mime <t>] [--as <name>]   share a file as an attachment
 
 account:
@@ -122,9 +122,10 @@ 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
 
-cross-namespace links (cloud-only, no CLI — leads request/approve via MCP:
-  request_namespace_link / respond_namespace_link / list_my_namespace_links.
-  Both namespaces need a --lead agent; links are opt-in, not project-based.)
+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.)
 
 schedules:
   patchcord schedule create <name> --namespace <ns> --to <agent> --content "..."
@@ -166,6 +167,45 @@ function _kimiContextRequested(options = {}) {
     || Boolean(process.env.KIMI_MCP_CONFIG_FILE);
 }
 
+// Strip legacy Python kimi-cli per-project artifacts. Kimi Code (Node) uses
+// .kimi-code/mcp.json only — a leftover .kimi/mcp.json makes subscribe and
+// docs lie about which identity is active.
+function _purgeLegacyKimiProjectConfig(dir) {
+  const legacyMcp = join(dir, ".kimi", "mcp.json");
+  if (existsSync(legacyMcp)) {
+    try {
+      const obj = JSON.parse(readFileSync(legacyMcp, "utf-8"));
+      if (obj?.mcpServers?.patchcord) {
+        delete obj.mcpServers.patchcord;
+        if (Object.keys(obj.mcpServers).length === 0) delete obj.mcpServers;
+      }
+      if (!obj.mcpServers || Object.keys(obj).length === 0) {
+        rmSync(legacyMcp, { force: true });
+      } else {
+        writeFileSync(legacyMcp, JSON.stringify(obj, null, 2) + "\n");
+      }
+    } catch {
+      try { rmSync(legacyMcp, { force: true }); } catch {}
+    }
+  }
+  const legacySkills = join(dir, ".kimi", "skills");
+  if (existsSync(legacySkills)) {
+    for (const stale of ["patchcord", "patchcord-inbox", "patchcord-wait", "patchcord-subscribe", "patchcord:inbox", "patchcord:wait", "patchcord:subscribe"]) {
+      const d = join(legacySkills, stale);
+      if (existsSync(d)) { try { rmSync(d, { recursive: true, force: true }); } catch {} }
+    }
+    try {
+      if (readdirSync(legacySkills).length === 0) rmSync(legacySkills, { recursive: true, force: true });
+    } catch {}
+  }
+  try {
+    const legacyKimi = join(dir, ".kimi");
+    if (existsSync(legacyKimi) && readdirSync(legacyKimi).length === 0) {
+      rmSync(legacyKimi, { recursive: true, force: true });
+    }
+  } catch {}
+}
+
 // Insert-or-update mcp_servers.patchcord in a Hermes ~/.hermes/config.yaml,
 // preserving the rest of the user's YAML. Block-style only (what Hermes writes).
 function upsertHermesConfig(existing, url, token) {
@@ -667,9 +707,14 @@ if (cmd === "subscribe") {
       process.exit(1);
     }
     const { spawnSync } = await import("child_process");
+    const spawnEnv = {
+      ...process.env,
+      PATH: process.env.PATH || "/usr/local/bin:/usr/bin:/bin",
+    };
+    if (forceKimi) spawnEnv.PATCHCORD_KIMI_REQUIRED = "1";
     const result = spawnSync("bash", [kimiSubScript, intervalArg], {
       stdio: "inherit",
-      env: { ...process.env, PATH: process.env.PATH || "/usr/local/bin:/usr/bin:/bin" },
+      env: spawnEnv,
     });
     process.exit(result.status ?? (result.signal ? 1 : 0));
   }
@@ -1034,6 +1079,7 @@ if (cmd === "login" || cmd === "orchestrator" || cmd === "teamlead" || cmd === "
     }
     if (tool === "kimi" || tool === "kimi-code") {
       const kdir = join(dir, ".kimi-code"); mkdirSync(kdir, { recursive: true });
+      _purgeLegacyKimiProjectConfig(dir);
       return writeJson(join(kdir, "mcp.json"), (o) => {
         o.mcpServers = o.mcpServers || {};
         o.mcpServers.patchcord = { url: `${baseUrl}/mcp/bearer`, headers: hdr };
@@ -1856,20 +1902,11 @@ if (!cmd || cmd === "install" || cmd === "agent" || cmd?.startsWith("--")) {
     if (windsurfChanged) globalChanges.push("Windsurf skills installed");
   }
 
-  // Gemini CLI + Antigravity SHARE ~/.gemini/skills and ~/.gemini/commands, but
-  // their MCP config is NOT shared: Gemini CLI stores patchcord globally
-  // (~/.gemini/settings.json) while Antigravity is PER-PROJECT
-  // (<project>/.agents/mcp_config.json). So the shared global skill must be
-  // seeded ONLY off Gemini CLI's global config — never off an Antigravity config.
-  // A patchcord entry in the global ~/.gemini/antigravity(-cli)/mcp_config.json or
-  // ~/.gemini/config/mcp_config.json (Antigravity's post-migration global path —
-  // confirmed live via the sibling ~/.gemini/config/.migrated marker; the older
-  // two paths are its predecessors) is a leaked per-project token: it makes agy
-  // load the patchcord MCP (and its "check inbox first" instruction) in EVERY
-  // project, and it kept this skill seeded everywhere. We strip that leak below
-  // and gate the skill on Gemini only. Keep all three paths in sync — a prior
-  // fix (a36809c) covered only the first two and missed the migrated path,
-  // leaving leaks there uncleaned.
+  // Gemini CLI and Antigravity CLI SHARE ~/.gemini/skills/ — Antigravity reads it
+  // globally in EVERY project. NEVER seed patchcord skills there (v0.6.2 still did
+  // when Gemini had MCP configured, poisoning bare agy sessions). Gemini CLI uses
+  // ~/.gemini/commands/ slash commands only. Antigravity gets per-project skills
+  // at <project>/.agents/skills/ during provision (see isAntigravity below).
   if (existsSync(join(HOME, ".gemini"))) {
     // Remove any leaked patchcord server from Antigravity's GLOBAL configs so a
     // per-project token stops hijacking every agy session. Preserve other MCP
@@ -1889,27 +1926,28 @@ if (!cmd || cmd === "install" || cmd === "agent" || cmd?.startsWith("--")) {
         }
       } catch {}
     }
-    // Older installers seeded Antigravity-only skills globally, and the
-    // Antigravity CLI caches each MCP server's tools/instructions globally.
-    // Both survive removal of the global mcp_config entry and can make a bare
-    // agy session synthesize an unconditional Patchcord rule in every folder.
-    // Antigravity is project-scoped, so remove only Patchcord's stale global
-    // artifacts; other MCP servers and Antigravity state stay untouched.
-    const staleAntigravityPatchcord = [
+    // Unconditionally purge every global Patchcord skill/instruction path Antigravity
+    // reads. Older installers seeded ~/.gemini/skills/patchcord for Gemini; agy-cli
+    // inherits that shared dir and auto-loads it in unrelated projects.
+    const staleGlobalPatchcord = [
+      join(HOME, ".gemini", "skills", "patchcord"),
+      join(HOME, ".gemini", "skills", "patchcord-wait"),
       join(HOME, ".gemini", "antigravity", "skills", "patchcord"),
       join(HOME, ".gemini", "antigravity", "skills", "patchcord-wait"),
       join(HOME, ".gemini", "antigravity-cli", "skills", "patchcord"),
       join(HOME, ".gemini", "antigravity-cli", "skills", "patchcord-wait"),
+      join(HOME, ".gemini", "config", "skills", "patchcord"),
+      join(HOME, ".gemini", "config", "skills", "patchcord-wait"),
       join(HOME, ".gemini", "antigravity-cli", "mcp", "patchcord"),
     ];
-    let removedStaleAntigravity = false;
-    for (const stale of staleAntigravityPatchcord) {
+    let removedStaleGlobal = false;
+    for (const stale of staleGlobalPatchcord) {
       if (existsSync(stale)) {
-        try { rmSync(stale, { recursive: true, force: true }); removedStaleAntigravity = true; } catch {}
+        try { rmSync(stale, { recursive: true, force: true }); removedStaleGlobal = true; } catch {}
       }
     }
-    if (removedStaleAntigravity) {
-      globalChanges.push("Removed stale global Antigravity Patchcord instructions (agy is per-project)");
+    if (removedStaleGlobal) {
+      globalChanges.push("Removed global Patchcord skills/instructions (agy reads ~/.gemini/skills — per-project only)");
     }
     // true = configured, false = file absent (definitely not), null = unparseable (unknown)
     const hasPatchcordMcp = (p, keyPath) => {
@@ -1922,38 +1960,27 @@ if (!cmd || cmd === "install" || cmd === "agent" || cmd?.startsWith("--")) {
     ];
     const mcpConfigured = checks.some((c) => c === true);
     const mcpUnknown = checks.some((c) => c === null);
-    const geminiSkillDir = join(HOME, ".gemini", "skills", "patchcord");
-    const geminiWaitDir = join(HOME, ".gemini", "skills", "patchcord-wait");
     const geminiCmdDir = join(HOME, ".gemini", "commands");
     const geminiLegacyCmd = join(geminiCmdDir, "patchcord.toml"); // single-command file from older installs
     if (mcpConfigured) {
       let geminiChanged = false;
-      // Refresh to the CURRENT plugin version (overwrite, not create-if-absent)
-      // so skill/gate fixes reach machines that already have an older copy.
       const seedFile = (dest, src) => {
         mkdirSync(dirname(dest), { recursive: true });
         const want = readFileSync(src, "utf-8");
         let cur = ""; try { cur = readFileSync(dest, "utf-8"); } catch {}
         if (cur !== want) { writeFileSync(dest, want); geminiChanged = true; }
       };
-      seedFile(join(geminiSkillDir, "SKILL.md"), join(pluginRoot, "skills", "inbox", "SKILL.md"));
-      seedFile(join(geminiWaitDir, "SKILL.md"), join(pluginRoot, "skills", "wait", "SKILL.md"));
+      // Gemini CLI only — slash commands, NOT ~/.gemini/skills (shared with agy-cli).
       seedFile(join(geminiCmdDir, "inbox.toml"), join(pluginRoot, "commands", "inbox.toml"));
       seedFile(join(geminiCmdDir, "wait.toml"), join(pluginRoot, "commands", "wait.toml"));
       if (existsSync(geminiLegacyCmd)) { try { unlinkSync(geminiLegacyCmd); geminiChanged = true; } catch {} }
-      if (geminiChanged) globalChanges.push("Gemini/Antigravity patchcord skills + commands refreshed");
+      if (geminiChanged) globalChanges.push("Gemini CLI patchcord commands refreshed");
     } else if (!mcpUnknown) {
-      // Definitively no patchcord MCP under ~/.gemini → remove any previously
-      // seeded skill/commands so a bare Gemini/Antigravity session has nothing
-      // to act on (incl. the legacy patchcord.toml command).
       let removed = false;
-      for (const d of [geminiSkillDir, geminiWaitDir]) {
-        if (existsSync(d)) { try { rmSync(d, { recursive: true, force: true }); removed = true; } catch {} }
-      }
       for (const f of [join(geminiCmdDir, "inbox.toml"), join(geminiCmdDir, "wait.toml"), geminiLegacyCmd]) {
         if (existsSync(f)) { try { unlinkSync(f); removed = true; } catch {} }
       }
-      if (removed) globalChanges.push("Removed stale Gemini/Antigravity patchcord skills (no patchcord MCP configured there)");
+      if (removed) globalChanges.push("Removed stale Gemini CLI patchcord commands (no patchcord MCP configured there)");
     }
   }
 
@@ -2100,6 +2127,13 @@ if (!cmd || cmd === "install" || cmd === "agent" || cmd?.startsWith("--")) {
         const p = join(legacyKimiHome, f);
         if (existsSync(p)) { try { rmSync(p, { force: true }); } catch {} }
       }
+      const legacySkillsRoot = join(legacyKimiHome, "skills");
+      if (existsSync(legacySkillsRoot)) {
+        for (const stale of ["patchcord", "patchcord-inbox", "patchcord-wait", "patchcord-subscribe", "patchcord:inbox", "patchcord:wait", "patchcord:subscribe"]) {
+          const d = join(legacySkillsRoot, stale);
+          if (existsSync(d)) { try { rmSync(d, { recursive: true, force: true }); } catch {} }
+        }
+      }
       const legacyConfigPath = join(legacyKimiHome, "config.toml");
       if (existsSync(legacyConfigPath)) {
         try {
@@ -2843,9 +2877,8 @@ if (!cmd || cmd === "install" || cmd === "agent" || cmd?.startsWith("--")) {
     // Antigravity CLI: PROJECT-scoped config at <project>/.agents/mcp_config.json
     // (one project = one namespace = one agent identity — never global, which
     // would give one shared agent cross-project visibility). Remote HTTP uses
-    // the `serverUrl` key. Skills are NOT seeded globally here: a stray skill in
-    // the shared ~/.gemini/skills makes bare agy sessions improvise. The MCP
-    // server injects its own instructions once connected.
+    // the `serverUrl` key. Skills are per-project at .agents/skills/ only — never
+    // ~/.gemini/skills (agy-cli reads that globally in every folder).
     const agPath = join(cwd, ".agents", "mcp_config.json");
     const agOk = updateJsonConfig(agPath, (obj) => {
       obj.mcpServers = obj.mcpServers || {};
@@ -2857,8 +2890,15 @@ if (!cmd || cmd === "install" || cmd === "agent" || cmd?.startsWith("--")) {
         },
       };
     });
+    const agInboxDir = join(cwd, ".agents", "skills", "patchcord");
+    const agWaitDir = join(cwd, ".agents", "skills", "patchcord-wait");
+    mkdirSync(agInboxDir, { recursive: true });
+    mkdirSync(agWaitDir, { recursive: true });
+    cpSync(join(pluginRoot, "per-project-skills", "antigravity", "inbox", "SKILL.md"), join(agInboxDir, "SKILL.md"));
+    cpSync(join(pluginRoot, "per-project-skills", "antigravity", "wait", "SKILL.md"), join(agWaitDir, "SKILL.md"));
     if (agOk) {
       console.log(`\n  ${green}✓${r} Antigravity CLI configured: ${dim}${agPath}${r}`);
+      console.log(`  ${green}✓${r} Skills installed: ${dim}.agents/skills/patchcord${r}, ${dim}patchcord-wait${r}`);
       console.log(`  ${yellow}Project config — this agent is scoped to ${cwd}.${r}`);
       console.log(`  ${dim}Verify in agy with the /mcp slash command.${r}`);
     }
@@ -2937,6 +2977,7 @@ if (!cmd || cmd === "install" || cmd === "agent" || cmd?.startsWith("--")) {
       };
     });
     if (kcOk) {
+      _purgeLegacyKimiProjectConfig(cwd);
       console.log(`\n  ${green}✓${r} Kimi Code configured: ${dim}${kcPath}${r}`);
       console.log(`  ${dim}Kimi Code auto-loads project-local .kimi-code/mcp.json — just run ${r}${bold}kimi${r}${dim} in this project (no wrapper needed).${r}`);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "patchcord",
-  "version": "0.6.2",
+  "version": "0.6.5",
   "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/per-project-skills/antigravity/inbox/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: patchcord-inbox
+description: Patchcord MCP inbox workflow for this project's Antigravity agent
+---
+
+## Applies only when Patchcord MCP tools are loaded
+
+If the `inbox` MCP tool is not available in this session, this skill does not
+apply. Do nothing: do not run the Patchcord CLI, read a token from a config
+file, or call the HTTP API. A missing project MCP config is a normal state.
+
+Invoke with `/patchcord-inbox` when Patchcord MCP is connected in this project.
+
+Call the `inbox` MCP tool now. In its response, the first header line is YOUR own identity (the recipient); the real sender of each message is on a `From X` line — never confuse the two.
+
+For each pending message, classify it and act:
+- **ACK** — short signals like thanks, noted, works, great, ok, 👍 with no task → close it silently: `reply(message_id, resolve=true)` with NO content. Never send a text reply to an ack (it creates infinite ack chains).
+- **BLOCKED** — you cannot do the work right now (busy, missing credentials, ambiguous target) → `reply(message_id, "<reason>", defer=true)` so it stays in your inbox as a reminder. Never silently skip a message.
+- **ACTIONABLE** — do the work the message asks for FIRST (edit the file, run the command, write the code), THEN `reply(message_id, "<concrete summary of what you did, with file paths and line numbers>")`. Never reply "will do" / "understood" before doing the work.
+
+After handling every message, tell the human who wrote, what they asked, and what you did.

package/per-project-skills/antigravity/wait/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: patchcord-wait
+description: Block until one Patchcord message arrives (this project's Antigravity agent)
+---
+
+## Applies only when Patchcord MCP tools are loaded
+
+If the `wait_for_message` MCP tool is not available in this session, this skill
+does not apply. Do nothing: do not run the Patchcord CLI, read a token from a
+config file, or call the HTTP API. A missing project MCP config is a normal state.
+
+Invoke with `/patchcord-wait` when Patchcord MCP is connected in this project.
+
+Call `wait_for_message()` to block until a message arrives (up to 5 minutes).
+
+When a message arrives:
+1. Do the work described in the message first.
+2. `reply(message_id, "<concrete summary of what you did>")`.
+3. Tell the human who wrote and what you did.
+4. Call `wait_for_message()` again to keep listening.
+
+If `wait_for_message()` errors, poll `inbox()` every 10–15 seconds instead.

package/scripts/kimi-subscribe.sh

@@ -15,13 +15,11 @@ set -euo pipefail
 command -v jq >/dev/null 2>&1 || { echo "jq required" >&2; exit 1; }
 
 # Resolve MCP config: PROJECT-scoped ONLY (walk up from cwd for .kimi-code/mcp.json).
-# Kimi Code (the current product) uses .kimi-code/ — the legacy .kimi/ path is
-# deprecated and MUST NOT be used; it also mismatched where `patchcord provision`
-# writes the config (.kimi-code/mcp.json), so the listener never found it.
+# Legacy .kimi/mcp.json (Python kimi-cli) is NOT read — reinstall/provision removes it.
 # NO global fallback: auto-launched by the (global) SessionStart hook on EVERY
 # Kimi session, so a global fallback would start a listener for some leftover
-# identity in every folder. No project config in the cwd tree => no patchcord
-# agent here => exit quietly (0, not 1: must not spam stderr in non-patchcord dirs).
+# identity in every folder. No project config in the cwd tree => exit quietly
+# (0) unless PATCHCORD_KIMI_REQUIRED=1 (explicit `patchcord subscribe --kimi`).
 KIMI_MCP=""
 dir="$PWD"
 while [ "$dir" != "/" ]; do
@@ -33,6 +31,11 @@ while [ "$dir" != "/" ]; do
 done
 
 if [ -z "$KIMI_MCP" ] || [ ! -f "$KIMI_MCP" ]; then
+  if [ "${PATCHCORD_KIMI_REQUIRED:-}" = "1" ]; then
+    echo "No Kimi Code Patchcord config in this project tree (.kimi-code/mcp.json)." >&2
+    echo "Run patchcord provision <agent> --tool kimi --namespace <ns> from the project root." >&2
+    exit 1
+  fi
   exit 0
 fi
 
@@ -46,10 +49,16 @@ fi
 
 BASE_URL=$(echo "$URL" | sed 's|/mcp$||; s|/mcp/bearer$||')
 
-# Derive agent identity for pidfile
+# Poll loop: count_only + no registry write — same cost model as subscribe.mjs
+# drainQueueOnce (id SELECT only). Kimi cannot hold a WebSocket/Realtime
+# listener (no Monitor; task must exit to wake), so polling is the transport;
+# the bug was fetching full message bodies every tick.
+INBOX_POLL_QS="status=pending&limit=5&count_only=1&touch_presence=0"
+
+# Derive agent identity for pidfile (count_only, no registry write)
 IDENTITY_RESP=$(curl -s --max-time 5 \
   -H "Authorization: Bearer ${TOKEN}" \
-  "${BASE_URL}/api/inbox?limit=0" 2>/dev/null || echo "{}")
+  "${BASE_URL}/api/inbox?limit=0&count_only=1&touch_presence=0" 2>/dev/null || echo "{}")
 NAMESPACE_ID=$(echo "$IDENTITY_RESP" | jq -r '.namespace_id // empty' 2>/dev/null || true)
 AGENT_ID=$(echo "$IDENTITY_RESP" | jq -r '.agent_id // empty' 2>/dev/null || true)
 
@@ -59,7 +68,7 @@ if [ -z "$NAMESPACE_ID" ] || [ -z "$AGENT_ID" ]; then
 fi
 
 PIDFILE="/tmp/patchcord_subscribe_${NAMESPACE_ID}_${AGENT_ID}.pid"
-NOTIFY_FILE="${HOME}/.kimi/patchcord-subscribe-notify.txt"
+NOTIFY_FILE="${KIMI_CODE_HOME:-${HOME}/.kimi-code}/patchcord-subscribe-notify.txt"
 
 # Always replace any existing listener for this project. Otherwise the agent
 # sees an instant exit ("already running") and narrates it as "listener failed
@@ -96,7 +105,7 @@ echo "PATCHCORD: subscribe started (poll ${INTERVAL}s) for ${AGENT_ID}@${NAMESPA
 while true; do
   RESP=$(curl -s --max-time 10 \
     -H "Authorization: Bearer ${TOKEN}" \
-    "${BASE_URL}/api/inbox?status=pending&limit=5" 2>/dev/null || echo "{}")
+    "${BASE_URL}/api/inbox?${INBOX_POLL_QS}" 2>/dev/null || echo "{}")
 
   COUNT=$(echo "$RESP" | jq -r '.pending_count // 0' 2>/dev/null || echo "0")
 

package/skills/inbox/SKILL.md

@@ -1,10 +1,9 @@
 ---
 name: patchcord:inbox
 description: >
-  Cross-agent messaging across MCP-connected agents. Use when user mentions
-  other agents, patchcord, check inbox, send message, who's online, agent
-  coordination, or when you receive additionalContext about pending patchcord
-  messages.
+  MCP tool workflow for Patchcord cross-agent messaging. Active ONLY when
+  mcp_patchcord_* tools are loaded in this session — ignore this skill
+  otherwise.
 ---
 # patchcord
 
@@ -42,7 +41,9 @@ The user can undo any change in 3 seconds with git. A wrong action costs nothing
 
 **If you can't do it right now** (busy with current task): use `reply(message_id, "reason why deferred", defer=true)`. This keeps the message visible in your inbox so you will come back to it. Never silently skip a message - you will forget it. If you don't act and don't defer, the message is lost forever.
 
-## On session start or when prompted by a hook
+## When MCP tools are loaded: session start or hook
+
+The following applies only when the patchcord MCP tools are present in this session (see the gate above). If they are absent, skip this entire section.
 
 Call inbox(). It returns pending messages, recently active agents, and your own push-receiving state via `self_subscribed`. Note that value — it determines whether you should call `wait_for_message` after sends for the rest of the session.
 
@@ -184,8 +185,8 @@ Named threads group related messages between a pair of agents. Use them for mult
 - Never show raw JSON to the human - summarize naturally.
 - **Cross-namespace addressing (`agent@namespace`)**: the syntax always exists in `send_message`/`reply`, but what it actually reaches depends on who you are:
   - **Ordinary agents (the default):** `agent@namespace` only ever works for YOUR OWN namespace — same as a bare name. Targeting any other namespace is rejected. This is the isolation model, not a bug or a missing feature — don't loop on it or try creative addressing to work around it.
-  - **Lead agents (cloud only — a small number of specially-provisioned identities per namespace, usually the orchestrator):** may reach a peer lead in a DIFFERENT namespace, but only after that specific pair of namespaces has an `approved` `namespace_links` row. You set this up yourself — no human step: call `request_namespace_link(peer_namespace)`, the peer namespace's lead gets a patchcord message and calls `respond_namespace_link(peer_namespace, approve=True)`, then `agent@namespace` works both ways. Check `list_my_namespace_links()` to see pending/approved/denied status. If you don't know whether you're a lead, you're not one — this isn't discoverable by trial and error; ask the human. (Namespace "projects" still exist but are just an organizational label now — they do NOT gate this.)
-  - A rejection here is almost always correct behavior, not a server error — don't retry with variations of the name.
+  - **Any agent (cloud only, no lead role required)** may reach ONE SPECIFIC agent in a DIFFERENT namespace, but only after an `approved` link between exactly that agent pair — never a whole-namespace grant. Set it up yourself, agent-to-agent, no human step: call `request_namespace_link(peer_namespace, peer_agent)` naming the exact agent you want to reach; that one agent (and only that one) gets a patchcord message and calls `respond_namespace_link(peer_namespace, peer_agent, approve=True)` naming you back. Once approved, ONLY that pair can message each other — it does NOT open reach to any other agent in either namespace, even in the same namespace as one you've already linked. Want to reach a second agent? Request a separate link for that specific pair. Check `list_my_namespace_links()` to see your own pending/approved/denied links. (Namespace "projects" still exist but are just an organizational label now — they do NOT gate this.)
+  - A rejection here is almost always correct behavior, not a server error — don't retry with variations of the name. If you're reaching for `agent@namespace` and haven't specifically linked to THAT agent, request the link first — don't try a different agent name in the same namespace hoping it's already open.
 - **Do not reply to acks.** "ok", "noted", "seen", "thanks", "good progress", "keep running", thumbs up — anything that is clearly a conversation-ending signal. Just read them and move on. If you must close the thread, use `reply(id, resolve=true)` with NO content. Never send a text reply to an ack.
 - **resolve=true with ack-only content is an anti-pattern.** `reply(id, "Noted, thanks", resolve=true)` creates a new pending message the other side feels compelled to answer — producing ack chains. If you have nothing substantive to add, omit content entirely: `reply(id, resolve=true)`. Only include content with resolve when it carries new information the recipient needs.
 - **When you receive an ack**, close it silently: `reply(id, resolve=true)`. No content. This stops the chain.