patchcord 0.6.0 → 0.6.2

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

package/bin/patchcord.mjs

@@ -1796,28 +1796,24 @@ if (!cmd || cmd === "install" || cmd === "agent" || cmd?.startsWith("--")) {
   const hasCursorAgent = run("which cursor-agent");
   if (hasCursorAgent || existsSync(cursorSkillsRoot)) {
     mkdirSync(cursorSkillsRoot, { recursive: true });
-    const cursorSkillDir = join(cursorSkillsRoot, "patchcord");
+    const cursorInboxDir = join(cursorSkillsRoot, "patchcord-inbox");
     const cursorWaitDir = join(cursorSkillsRoot, "patchcord-wait");
     const cursorSubscribeDir = join(cursorSkillsRoot, "patchcord-subscribe");
+    const staleCursorSkillDir = join(cursorSkillsRoot, "patchcord");
     let cursorChanged = false;
-    if (!existsSync(cursorSkillDir)) {
-      mkdirSync(cursorSkillDir, { recursive: true });
-      cpSync(join(pluginRoot, "skills", "inbox", "SKILL.md"), join(cursorSkillDir, "SKILL.md"));
-      cursorChanged = true;
-    }
-    if (!existsSync(cursorWaitDir)) {
-      mkdirSync(cursorWaitDir, { recursive: true });
-      cpSync(join(pluginRoot, "skills", "wait", "SKILL.md"), join(cursorWaitDir, "SKILL.md"));
-      cursorChanged = true;
-    }
-    if (!existsSync(cursorSubscribeDir)) {
-      mkdirSync(cursorSubscribeDir, { recursive: true });
-      cpSync(
-        join(pluginRoot, "per-project-skills", "cursor", "subscribe", "SKILL.md"),
-        join(cursorSubscribeDir, "SKILL.md")
-      );
-      cursorChanged = true;
-    }
+    if (existsSync(staleCursorSkillDir)) {
+      try { rmSync(staleCursorSkillDir, { recursive: true, force: true }); cursorChanged = true; } catch {}
+    }
+    mkdirSync(cursorInboxDir, { recursive: true });
+    cpSync(join(pluginRoot, "per-project-skills", "cursor", "inbox", "SKILL.md"), join(cursorInboxDir, "SKILL.md"));
+    cursorChanged = true;
+    mkdirSync(cursorWaitDir, { recursive: true });
+    cpSync(join(pluginRoot, "per-project-skills", "cursor", "wait", "SKILL.md"), join(cursorWaitDir, "SKILL.md"));
+    mkdirSync(cursorSubscribeDir, { recursive: true });
+    cpSync(
+      join(pluginRoot, "per-project-skills", "cursor", "subscribe", "SKILL.md"),
+      join(cursorSubscribeDir, "SKILL.md")
+    );
     if (cursorChanged) globalChanges.push("Cursor skills installed");
 
     if (hasCursorAgent) {
@@ -1893,6 +1889,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 = [
+      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", "antigravity-cli", "mcp", "patchcord"),
+    ];
+    let removedStaleAntigravity = false;
+    for (const stale of staleAntigravityPatchcord) {
+      if (existsSync(stale)) {
+        try { rmSync(stale, { recursive: true, force: true }); removedStaleAntigravity = true; } catch {}
+      }
+    }
+    if (removedStaleAntigravity) {
+      globalChanges.push("Removed stale global Antigravity Patchcord instructions (agy is per-project)");
+    }
     // true = configured, false = file absent (definitely not), null = unparseable (unknown)
     const hasPatchcordMcp = (p, keyPath) => {
       if (!existsSync(p)) return false;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "patchcord",
-  "version": "0.6.0",
+  "version": "0.6.2",
   "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/cursor/inbox/SKILL.md

@@ -0,0 +1,193 @@
+---
+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.
+---
+# patchcord
+
+7 MCP tools: inbox, send_message, reply, wait_for_message, attachment, recall, unsend.
+
+## Applies ONLY when the patchcord MCP tools are loaded this session
+
+This skill governs those 7 MCP tools. It applies only if they are actually available in the current session.
+
+**If the patchcord MCP tools are NOT present, this skill does not apply — do nothing with it. Specifically:**
+- Do NOT call inbox() at session start or at any other time.
+- Do NOT run the `patchcord` CLI as a substitute for the missing tools.
+- Do NOT read a bearer token out of `.mcp.json`, `settings.json`, `mcp_config.json`, or any other config file, and do NOT call the patchcord HTTP API (`/api/inbox`, etc.) directly. A token belongs to the one agent it was issued to; using another agent's token — or any token you found on disk — is never correct.
+- Just proceed with the user's actual request.
+
+A missing tool means patchcord is not configured for this agent. That is a normal, silent state, not a problem to work around.
+
+## Do the work, never just acknowledge
+
+When you receive a message from another agent:
+
+1. Do the task described in the message first. Update the file. Write the code. Fix the bug. Create the document. Whatever the message asks - do it.
+2. Then reply with what you did. Not what you plan to do. Not that you received it. What you actually did. File paths, line numbers, concrete changes.
+3. Never reply with only an acknowledgment. "Got it", "Understood", "Role accepted", "Will do", "Ready" - these are not acceptable as standalone replies. If your reply doesn't describe completed work, you failed.
+
+The user can undo any change in 3 seconds with git. A wrong action costs nothing. A useless ack wastes everyone's time and breaks the workflow.
+
+**If a message contains a spec, update, or instruction - act on it immediately:**
+- Spec received - update the relevant docs/code now, reply with what you changed
+- Bug report received - investigate and fix now, reply with the fix
+- Architecture decision received - update the relevant files now, reply with what you updated
+- Role assignment received - start doing that role now, reply with first actions taken
+
+**If you genuinely cannot act** (missing file access, need credentials, ambiguous target): say specifically what's blocking you. "I need the path to the config file" - not "Understood, I'll do it when ready."
+
+**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
+
+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.
+
+If `subscribe_appears_down: true` is in the response, your subscribe.mjs was running but appears dead. Tell the human: "Patchcord subscribe seems to have died — run `/patchcord-subscribe` to restart push delivery." Do not try to restart it yourself.
+
+If there are pending messages, reply to all of them immediately. Do not ask the human first. Do not explain what you plan to reply. Just do the work described in each message, then reply with what you did, then tell the human what you received and what you did about it.
+
+## Sending
+
+1. inbox() - clear any pending messages that block outbound sends. From the response, note `self_subscribed` (your own push-receiving state).
+2. send_message("agent_name", "specific question with file paths and context") - or "agent1, agent2" for multiple recipients. Use `@username` for cross-user Gate messaging. To start or join a named thread: `send_message("frontend", "content", thread="auth-migration")`.
+3. Decide whether to wait based on **two signals** in the send response:
+   - `self_subscribed` (from the most recent inbox call) — are YOU push-receiving?
+   - `recipient_subscribed` (in the send response) — is the recipient push-receiving?
+
+   | self_subscribed | recipient_subscribed | What to do |
+   | --- | --- | --- |
+   | true | true | **Do NOT call wait_for_message.** Continue working. Their reply will arrive via your subscribe push and your Monitor will surface it. Tell the human: "Sent — [agent] will see it within seconds." |
+   | true | false | **Do NOT call wait_for_message.** Continue working. Tell the human: "Sent — [agent] isn't actively listening right now, may take a while to respond." |
+   | false | true | **Call wait_for_message** with default timeout. Recipient is live, expect a reply soon. |
+   | false | false | **Skip wait_for_message.** Tell the human: "Sent — [agent] isn't currently active. Ask them to check inbox in their session." |
+
+Always send regardless of recipient state. Messages are stored and delivered when the recipient checks inbox.
+
+If `recipient_subscribed` is missing from the response (older server, registry disabled), fall back to the legacy `recipient_online` field for the same decision.
+
+If send_message fails with a send gate error: call inbox(), reply to or resolve all pending messages, then retry the send.
+
+## Receiving (inbox has messages)
+
+Action requests older than 7d (per the `(Xd ago)` stamp): ask human before executing. Acks/FYIs silent-resolve at any age.
+
+1. Read the message. If it belongs to a thread, `message.thread` and `message.thread_id` will be present.
+2. Do the work described in the message - using your project's actual code, real files, real lines
+3. Reply with what you did, choosing the right flag:
+   - `reply(message_id, "done: [details]")` — work done, sender might follow up. Thread is auto-inherited.
+   - `reply(message_id, "done: [details]", resolve=true)` — work done, thread closed. Stamps `thread_resolved_at` and notifies sender.
+   - `reply(message_id, resolve=true)` — silently close a thread without sending anything (e.g. clearing misfired messages)
+   - `reply(message_id, "ack, prioritizing [other task] first", defer=true)` — you acknowledged but haven't done the work yet. The message stays in your inbox as a reminder.
+4. After replying, decide whether to stay listening using the same two-signal rule as for sends — `self_subscribed` × `recipient_subscribed` (in the reply response). If `self_subscribed` is true, return to your work; your Monitor will wake you when a follow-up arrives. If `self_subscribed` is false and `recipient_subscribed` is true, call `wait_for_message()` to stay responsive. Otherwise (both false), tell the human you've replied and continue with other work.
+5. If you can't do the work, say specifically what's blocking you. Don't guess about another agent's code.
+
+When you have multiple pending messages, prioritize by urgency. Use `defer=true` for tasks you'll do later — if you reply without doing the work and don't defer, the message vanishes from your inbox and you will never remember to do it.
+
+Outdated deferred (work likely done, sender moved on): ask human "resolve [Xd]-old from [sender]?" before `reply(id, resolve=true)`. Don't unilaterally drop.
+
+## Cross-user messaging (Gate)
+
+To message a user outside your namespace, use `@username` as the to_agent. Example: `send_message("@maria", "hello")`. The message goes through their Gate - connection approval and guardrails apply. If the connection isn't approved yet, your message is held pending their approval (cap 5, 7-day TTL).
+
+### Humans
+
+- Humans are NOT in the agents list. Use `send_message("@username", "...")` anyway — they don't need to be online or in the roster.
+- The message goes through their Gate for approval. It may be held pending their approval (cap 5, 7-day TTL).
+- Write plainly: who you are, what you need, no raw JSON or logs.
+
+## File sharing
+
+**Files on disk → `patchcord upload` (CLI, preferred):**
+```
+patchcord upload /path/to/report.md --mime text/markdown
+```
+Prints the storage path. Pass that path to `send_message`. No curl, no base64 in chat, no presigned URLs. 25MB cap.
+
+**Public URLs → `attachment(relay=true, ...)`:**
+```
+attachment(relay=true, path_or_url="https://example.com/file.md", filename="file.md")
+```
+Server fetches the URL and stores it. Use when the file already lives at a public URL.
+
+**Web agents (no shell) → inline base64 last resort:**
+```
+attachment(upload=true, filename="notes.txt", file_data="<base64>")
+```
+Only for agents that cannot run shell commands. Wastes context tokens. Never use if you can run `patchcord upload`.
+
+**Downloading:**
+```
+attachment(path_or_url="namespace/agent/timestamp_file.md")
+```
+Pass the storage path from the sender's message.
+
+Always send the storage path (not the file content) to the other agent.
+
+## Identity (`patchcord whoami` / `patchcord agents`)
+
+`whoami` and `agents` are CLI commands, not MCP tools. Run them only when the patchcord MCP tools are present (see the gate at the top of this skill). They read the bearer token from the **current project's own** `.mcp.json` automatically — same namespace scope, no extra setup. Never go hunting for a token in another project's config or another agent's file, and never pass a token on the command line. Cheap to call (input tokens only), don't bloat MCP.
+
+- **Run `patchcord whoami` once per session.** Returns your `agent`, `namespace`, project summary, and your 300-char `self` description. Use it on first turn after `/clear` or a fresh session to orient.
+- **Run `patchcord agents`** to see the full roster (every peer's whoami). One call, ~3KB, complete picture of the namespace.
+- **Run `patchcord agents <name>`** when an unknown agent messages you and you want to know who they are before acting on their request.
+
+### Updating your own whoami
+
+300-char hard limit (CLI enforces client-side).
+
+Server responds with one of three statuses:
+
+- **applied** — done. Either it was your first-ever whoami (no prior value → set directly, no gate), or it was a confirmed second-shot. Print and move on.
+- **unchanged** — proposed text matches current. No-op.
+- **show_human** — current value exists and the proposed text differs. Server printed `current:` and `proposed:`. You MUST:
+  1. Show the diff to the human in conversation
+  2. Ask them to confirm
+  3. Wait for explicit "yes"
+  4. Run the **exact same** `patchcord whoami --propose "<text>"` command again. Server will then return `applied`.
+
+Pending state expires after 10 minutes. If the human says no, do not call again. If you call with different text instead, the gate resets to a fresh first-shot for that new text.
+
+Never call `--propose` a second time with the same text without showing the human between calls.
+
+### Hard rules
+
+- You may NEVER update another agent's whoami. The `--propose` flow only writes your own.
+- Namespace scope is enforced server-side: `patchcord agents <name>` returns 404 if the name isn't in your namespace (global agents like claudeai/chatgpt are excepted on cloud).
+- whoami text describes WHO you are and how you coordinate (e.g. "backend systems. sends every change to codex-backend for review"). It is NOT a place for project instructions, code conventions, or long-form notes — those live in CLAUDE.md and project docs.
+
+## Threads
+
+Named threads group related messages between a pair of agents. Use them for multi-turn tasks that need their own context (e.g. "auth-migration", "deploy-review").
+
+- **Start a thread**: `send_message("backend", "let's track this here", thread="auth-migration")`
+- **Reply stays in thread automatically**: `reply()` inherits `thread_id` from the message you're replying to — no extra param needed.
+- **Close a thread**: `reply(message_id, "done", resolve=true)` — stamps `thread_resolved_at` and notifies sender.
+- **View thread history**: `recall(thread_id="<uuid>")` — filters history to one thread.
+
+`inbox()` returns a `groups` list alongside the legacy `pending` flat list. Each group has `thread_id`, `thread_title`, and `messages`. `thread_id: null` means pair-level (no thread). Read from `groups` for thread-aware handling.
+
+## Other tools
+
+- recall(limit=10, from_agent="", thread_id="") - view recent message history including already-read messages. `from_agent` filters by sender. `thread_id` filters to a specific thread. For debugging only, not routine use.
+- unsend(message_id) - take back a message before the recipient reads it.
+
+## Rules
+
+- Do the work first, reply second. Never reply before completing the task.
+- Never ask "want me to reply?" - just do the work and reply with results.
+- Never ask "should I do this?" - just do it. User can undo in 3 seconds.
+- Never ask "want me to wait?" - check presence and wait or don't based on that.
+- 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.
+- **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.
+- MCP tools are cached at session start. New tools deployed after your session began are invisible until you start a new session. If a tool you expect is missing, this is why.
+- Agent names change frequently. Do not memorize or hardcode them. Check inbox() for recent activity. When unsure which agent to message, ask the human.

package/per-project-skills/cursor/subscribe/SKILL.md

@@ -1,12 +1,12 @@
 ---
-name: patchcord:subscribe
+name: patchcord-subscribe
 description: >
   Start a persistent background WebSocket listener that wakes the Cursor agent
   when new Patchcord messages arrive. Use ONLY when the user runs
-  /patchcord:subscribe or when a project explicitly asks to auto-arm it.
+  /patchcord-subscribe or when a project explicitly asks to auto-arm it.
 ---
 
-User invoked `/patchcord:subscribe` — do NOT substitute `wait_for_message()`.
+User invoked `/patchcord-subscribe` — do NOT substitute `wait_for_message()`.
 Start the persistent listener in a background Shell.
 
 ## Start
@@ -69,7 +69,7 @@ Read the background Shell terminal output and surface the exact cause:
 
 If the stream ends without one of these errors, it likely ended with the Cursor
 session or because its stdout consumer closed. Start it again only when the
-user invokes `/patchcord:subscribe` again.
+user invokes `/patchcord-subscribe` again.
 
 **Forbidden on failure:** no hand-rolled `nohup ... &`, no pidfile editing, no
 `curl`-to-MCP workarounds, and no re-arm loop after each inbox notification.

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

@@ -0,0 +1,31 @@
+---
+name: patchcord-wait
+description: >
+  Block this turn for up to 5 minutes waiting for one incoming Patchcord
+  message via the wait_for_message MCP tool. Single blocking call, no
+  background process. Use ONLY when the user explicitly runs
+  /patchcord-wait.
+---
+# patchcord-wait
+
+Applies ONLY when the patchcord MCP tools are loaded this session. If `wait_for_message` is not available, this skill does not apply — do nothing, do not substitute the CLI or direct HTTP calls, and never read a bearer token out of a config file. Proceed with the user's request.
+
+User invoked /patchcord-wait — do NOT substitute /patchcord-subscribe or spawn any background listener. Use `wait_for_message()` only.
+
+Call `wait_for_message()` to block until a message arrives (up to 5 minutes).
+
+When a message arrives:
+
+1. Read it — the tool returns from, content, and message_id. If it belongs to a thread, `thread` and `thread_id` will be set.
+2. Do the work described in the message first. Update the file, write the code, fix the bug - whatever it asks.
+3. Reply with what you did: `reply(message_id, "here's what I changed: [concrete details]")`. Thread is auto-inherited. Use `resolve=true` to close the thread when the task is fully done.
+4. Tell the human who wrote and what you did about it
+5. Call `wait_for_message()` again to keep listening
+
+Loop until timeout or the human interrupts.
+
+If `wait_for_message()` errors, fall back to polling `inbox()` every 10-15 seconds instead of stopping the loop.
+
+Do not ask the human for permission to reply - just do the work, reply with results, then report.
+
+**No ack chains.** If the arriving message is a clear ack ("Noted", "Got it", "Thanks", "Keep running") — close it silently with `reply(id, resolve=true)`, no content, and keep listening. Never text-reply to an ack. Never send "Noted" + resolve=true — that creates a new pending message the other side will feel compelled to answer.

package/per-project-skills/kimi/inbox/SKILL.md

@@ -5,6 +5,12 @@ description: Read Patchcord inbox and reply to messages
 
 Run this with `/skill:patchcord-inbox`. (Kimi Code has no `/flow:` — `/skill:` injects this as a prompt and you act on it.)
 
+## 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.
+
 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:

package/per-project-skills/kimi/subscribe/SKILL.md

@@ -5,6 +5,12 @@ description: Start the Patchcord background polling listener
 
 Run this with `/skill:patchcord-subscribe`. (Kimi Code has no `/flow:` — `/skill:` injects this as a prompt and you act on it.)
 
+## 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.
+
 First, call the `inbox` MCP tool and DRAIN every pending message before starting the listener (the listener exits immediately if messages are already waiting). In the inbox response, the first header line is YOUR identity (recipient); the real sender is on each `From X` line. For each message:
 - **ACK** (thanks, noted, works, ok, 👍) → `reply(message_id, resolve=true)`, no content.
 - **BLOCKED** → `reply(message_id, "<reason>", defer=true)`.

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

@@ -5,6 +5,12 @@ description: Wait for one incoming Patchcord message
 
 Run this with `/skill:patchcord-wait`. (Kimi Code has no `/flow:` — `/skill:` injects this as a prompt and you act on it.)
 
+## 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.
+
 Call the `wait_for_message` MCP tool now to block until a message arrives or ~5 minutes elapse.
 
 When a message arrives, classify it and act:

package/skills/subscribe/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: patchcord:subscribe
 description: >
-  Start a persistent background WebSocket listener (Supabase Realtime) that
+  Start a persistent background WebSocket listener that
   wakes Claude when new Patchcord messages arrive. Survives across turns
   until the user kills it or closes the session. Use ONLY when the user
   explicitly runs /patchcord:subscribe.
@@ -50,7 +50,7 @@ Read the output file. Scan the last ~15 lines for one of:
 
 - `no .mcp.json in <cwd>` — session is not in a patchcord project dir
 - `ticket: token rejected (HTTP 401|403)` — bad bearer; user regenerates from dashboard
-- `ticket: server not configured for realtime` — self-hosted without Supabase
+- `ticket: server not configured for realtime` — self-hosted without realtime configured
 - `ticket: namespace not owned` — token lost its owner; regenerate
 - `already running (pid N)` (exit 2) — another listener is active; report and stop
 - `subscribe: fatal: ...` — surface the line verbatim