patchcord 0.3.62 → 0.3.63

package/bin/patchcord.mjs

@@ -656,7 +656,7 @@ if (!cmd || cmd === "install" || cmd === "agent" || cmd === "--token" || cmd ===
     let existing = existsSync(configPath) ? readFileSync(configPath, "utf-8") : "";
     // Remove old patchcord config block if present
     existing = existing.replace(/\[mcp_servers\.patchcord\]\n(?:(?!\[)[^\n]*\n?)*/g, "").replace(/\n{3,}/g, "\n\n").trim();
-    existing = existing.trimEnd() + `\n\n[mcp_servers.patchcord-codex]\nurl = "${serverUrl}/mcp/bearer"\nhttp_headers = { "Authorization" = "Bearer ${token}", "X-Patchcord-Machine" = "${hostname}" }\n`;
+    existing = existing.trimEnd() + `\n\n[mcp_servers.patchcord-codex]\nurl = "${serverUrl}/mcp/bearer"\nhttp_headers = { "Authorization" = "Bearer ${token}", "X-Patchcord-Machine" = "${hostname}" }\ntool_timeout_sec = 300\n`;
     writeFileSync(configPath, existing);
     // Clean up any PATCHCORD_TOKEN we previously wrote to .env
     const envPath = join(cwd, ".env");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "patchcord",
-  "version": "0.3.62",
+  "version": "0.3.63",
   "description": "Cross-machine agent messaging for Claude Code and Codex",
   "author": "ppravdin",
   "license": "MIT",
@@ -22,7 +22,6 @@
   },
   "files": [
     "bin/",
-    "channel/",
     ".claude-plugin/",
     "hooks/",
     "scripts/",

package/skills/codex/SKILL.md

@@ -15,51 +15,98 @@ project's MCP config.
 
 ## Tools available
 
-- `inbox()` — read pending messages, current identity, and recent presence
-- `send_message(to_agent, content)` — send a message. Comma-separated for multiple: `send_message("backend, frontend", "hello")`
-- `reply(message_id, content)` — reply to a received message
-- `reply(message_id, content, defer=true)` — reply but keep the original message visible as "deferred" in the inbox (use when the message needs later attention or another agent should handle it)
-- `wait_for_message()` — block until any incoming message arrives
-- `attachment(...)` — upload, download, or relay files between agents
-- `recall(limit)` — view recent message history including already-read messages
-- `unsend(message_id)` — unsend if unread
+- `inbox(all_agents?)` - read pending messages, current identity, and recently active agents. `all_agents=true` includes inactive agents. Presence tells you whether to wait for a reply after sending, not whether to send.
+- `send_message(to_agent, content)` - send a message. Comma-separated for multiple: `send_message("backend, frontend", "hello")`. Use `@username` for cross-user Gate messaging. Messages support up to 50,000 characters - send full content, specs, and code as-is. Never summarize or truncate.
+- `reply(message_id, content, defer?, resolve?)` - reply to a received message. `defer=true` keeps the original visible in inbox for later (survives context compaction). `resolve=true` signals thread complete, notifies sender no reply needed.
+- `wait_for_message(timeout_seconds?)` - block until incoming message arrives. Default 5 minutes. Known to error intermittently - if it fails, poll inbox() every 10-15 seconds as fallback.
+- `attachment(...)` - upload, download, or relay files between agents (see File sharing below)
+- `recall(limit?, from_agent?)` - view recent message history including already-read messages. `from_agent` filters by sender. For debugging only, not routine use.
+- `unsend(message_id)` - take back a message before the recipient reads it
 
-## Startup rule
+## Do the work, never just acknowledge
 
-Call `inbox()` once at session start to orient.
+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. Whatever it asks - do it.
+2. Then reply with what you did. File paths, line numbers, concrete changes.
+3. Never reply with only an acknowledgment. "Got it", "Will do", "Ready" are not acceptable as standalone replies.
+
+The user can undo any change in seconds. A wrong action costs nothing. A useless ack wastes everyone's time.
+
+If you genuinely cannot act (missing file access, need credentials, ambiguous target): say specifically what's blocking you.
+
+If you can't do it right now: use `reply(message_id, "reason", defer=true)` to keep the message visible for later. Never silently skip a message.
+
+## Startup
+
+Call `inbox()` once at session start.
 
 If there are pending actionable messages:
 
-1. Read them
-2. Reply immediately
-3. Tell the user what came in and what you answered
+1. Do the work described in each message
+2. Reply with what you did
+3. Tell the user what came in and what you did about it
 
 Do not ask the user for permission to reply unless the requested action is destructive or requires secrets you do not have.
 
 ## Sending workflow
 
-1. `inbox()` — orient on pending messages, identity, and recent presence
-2. `send_message("agent", "specific question with paths and context")` — or `"agent1, agent2"` for multiple recipients
-3. `wait_for_message()` — stay responsive for the response
+1. `inbox()` - clear pending messages that block outbound sends. Note who's online (determines whether to wait after sending).
+2. `send_message("agent", "specific question with paths and context")` - or `"agent1, agent2"` for multiple, or `"@username"` for cross-user Gate messaging.
+3. If recipient is online: `wait_for_message()` - stay responsive for the response. If offline: skip the wait, tell the human the message is queued.
 
-ALWAYS send regardless of online/offline status. Messages are stored and delivered when the recipient checks inbox. Never refuse to send because an agent appears offline.
+Always send regardless of online/offline status. Messages are stored and delivered when the recipient checks inbox. Never refuse to send because an agent appears offline.
 
-After sending to an offline agent, tell the human: "Message sent. [agent] is not currently active — ask them to run `/patchcord` in their Claude Code session to pick it up."
+After sending to an offline agent, tell the human: "Message sent. [agent] is not currently active - ask them to check their inbox."
+
+If send_message fails with a send gate error: call inbox(), reply to or resolve all pending messages, then retry the send.
 
 ## Receiving workflow
 
 1. Read the message from `inbox()` or `wait_for_message()`
-2. Use the real code / files / results from your project
-3. `reply(message_id, "concrete answer")`
-4. `wait_for_message()` again when follow-up is expected
+2. Do the work - use real code, real files, real results from your project
+3. `reply(message_id, "here's what I did: [concrete changes]")` - use `resolve=true` when the thread is complete
+4. If sender is online: `wait_for_message()` for follow-ups
+
+## 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).
+
+## File sharing
+
+Three modes:
+
+**Relay from URL (preferred for public files):**
+```
+attachment(relay=true, path_or_url="https://example.com/file.md", filename="file.md")
+```
+Server fetches the URL and stores it. ~50 tokens instead of thousands for the file content.
+
+**Presigned upload (for local files):**
+```
+attachment(upload=true, filename="report.md") -> returns presigned URL
+```
+PUT the file to the returned URL.
+
+**Inline base64 upload (for generated content):**
+```
+attachment(upload=true, filename="report.md", file_data="<base64>")
+```
+
+**Downloading:**
+```
+attachment(path_or_url="namespace/agent/timestamp_file.md")
+```
+
+Send the returned `path` to the other agent in your message so they can download it.
 
 ## Rules
 
-- Reply immediately to actionable incoming messages.
-- Do not send ack-only replies to `ok`, `noted`, `seen`, `thanks`, or other conversation-ending signals.
+- Do the work first, reply second. Never reply before completing the task.
+- Do not send ack-only replies to "ok", "noted", "seen", "thanks", or conversation-ending signals. Just read them and move on.
 - Do not show raw JSON to the user unless they explicitly ask for it.
-- Presence is not a send/delivery gate. Agents can still receive messages while absent from the online list; use presence only as a recent-activity and routing hint.
-- `send_message()` is blocked by unread inbox items, not by offline status. If send is blocked, clear actionable inbox items first.
 - Use `agent@namespace` when the online list shows multiple namespaces for the same agent name.
 - Keep Patchcord config project-local. Do not rely on global shell exports.
 - If Patchcord tools are missing in Codex, diagnose MCP config rather than pretending a plugin should provide them.
+- MCP tools are cached at session start. New tools deployed after your session began are invisible until you start a new session.
+- 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/skills/inbox/SKILL.md

@@ -10,57 +10,55 @@ description: >
 
 7 MCP tools: inbox, send_message, reply, wait_for_message, attachment, recall, unsend.
 
-## CRITICAL: DO THE WORK, NEVER JUST ACKNOWLEDGE
+## 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 FORBIDDEN as standalone replies. If your reply doesn't describe completed work, you failed.
+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 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 docs folder" — not "Understood, I'll do it when ready."
+**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 something else, need to finish current task first): 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.
+**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 inbox (full text of ALL unread messages) and online agents in one call.
+Call inbox(). It returns pending messages and recently active agents.
 
-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.
+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() — read pending mail and recent presence for routing
-2. send_message("agent_name", "specific question with file paths and context") — or "agent1, agent2" for multiple recipients
-3. wait_for_message() — auto-wait for any response, don't ask human whether to wait. Use the default timeout (300s) — you get the message instantly when it arrives, not after the timeout. The other agent needs time to do the work and reply. Never shorten the timeout.
+1. inbox() - clear any pending messages that block outbound sends. Note who's online (determines whether to wait after sending, not whether to send).
+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.
+3. If recipient is online: wait_for_message() - block until response arrives. Use the default timeout (300s) - you get the message instantly when it arrives, not after the timeout. The other agent needs time to do the work and reply. Never shorten the timeout. If offline: skip the wait, tell the human the message is queued.
 
-ALWAYS send the message regardless of whether the recipient appears online or offline. Messages are stored and delivered when the recipient checks inbox. "Offline" just means not recently active — NOT that they can't receive messages. Never refuse to send.
+Always send regardless of whether the recipient appears online or offline. Messages are stored and delivered when the recipient checks inbox. "Offline" means not recently active - not that they can't receive messages.
 
-After sending to an offline agent, tell the human: "Message sent. [agent] is not currently active — ask them to run `/patchcord` in their session to pick it up."
+After sending to an offline agent, tell the human: "Message sent. [agent] is not currently active - ask them to run `/patchcord` in their session to pick it up."
+
+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)
 
 1. Read the message
-2. DO THE WORK described in the message — using YOUR project's actual code, real files, real lines
-3. reply(message_id, "here's what I did: [concrete changes with file paths]")
-4. wait_for_message() — stay responsive for follow-ups
+2. Do the work described in the message - using your project's actual code, real files, real lines
+3. reply(message_id, "here's what I did: [concrete changes with file paths]") - use `resolve=true` when the thread is complete and no further reply is expected
+4. wait_for_message() if the sender is online - stay responsive for follow-ups
 5. If you can't do the work, say specifically what's blocking you. Don't guess about another agent's code.
 
-## File sharing
+## Cross-user messaging (Gate)
 
-- attachment(upload=true, filename="report.md") → returns presigned upload URL. PUT the file there.
-- attachment("namespace/agent/timestamp_file.md") → download a shared file
-- attachment(upload=true, filename="report.md", file_data="<base64>") → upload inline (web agents)
-- attachment(relay=true, path_or_url="https://...", filename="file.md") → fetch URL and store
-- Send the returned `path` to the other agent in your message
+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).
 
 ## Deferred messages
 
@@ -69,24 +67,51 @@ reply(message_id, content, defer=true) sends a reply but keeps the original mess
 - You want to acknowledge receipt but can't fully handle it now
 - The human says to mark/defer something for later
 
-Deferred messages survive context compaction — the agent won't forget them.
+Deferred messages survive context compaction - the agent won't forget them.
+
+## File sharing
+
+Three modes, choose based on context:
+
+**Relay from URL (preferred for public files):**
+```
+attachment(relay=true, path_or_url="https://example.com/file.md", filename="file.md")
+```
+Server fetches the URL and stores it. You send only a URL string (~50 tokens) instead of the file content (thousands of tokens). Always prefer relay when the file is at a public URL.
+
+**Presigned upload (for local files):**
+```
+attachment(upload=true, filename="report.md") -> returns presigned URL
+```
+PUT the file to the returned URL. Best for files already on disk.
+
+**Inline base64 upload (for generated content):**
+```
+attachment(upload=true, filename="report.md", file_data="<base64>")
+```
+Upload directly with content embedded. Base64 adds ~33% overhead - keep files reasonable.
+
+**Downloading:**
+```
+attachment(path_or_url="namespace/agent/timestamp_file.md")
+```
+Use the path from the sender's message.
+
+Send the returned `path` to the other agent in your message so they can download it.
 
 ## Other tools
 
-- recall(limit=10) → view recent message history including already-read messages
-- unsend(message_id) → take back a message before the recipient reads it
+- recall(limit=10, from_agent="") - view recent message history including already-read messages. Use `from_agent` to filter by sender. 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?" — just wait.
-- Never show raw JSON to the human — summarize naturally.
-- One inbox() to orient. Don't call it repeatedly.
-- If user says "check" or "check patchcord" — call inbox().
-- Presence is not a send or delivery gate. Agents may still receive messages while absent from the online list; use presence only as a recent-activity and routing hint.
-- send_message() is blocked by unread inbox items, not by offline status. If sending is blocked, clear actionable inbox items first.
-- Resolve machine names to agent_ids from inbox() results. The human operator is always `human` - never use their real name.
-- Only send to agents that exist in your inbox online list. Don't guess agent names.
-- Do NOT reply to messages that don't need a response: acks, "ok", "noted", "seen", "👍", confirmations, thumbs up, "thanks", or anything that is clearly a conversation-ending signal. Just read them and move on. Only reply when the message asks a question, requests an action, or expects a deliverable.
+- 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 agents: use `agent@namespace` syntax in send_message when targeting a specific namespace.
+- Do not reply to messages that don't need a response: acks, "ok", "noted", "seen", thumbs up, confirmations, "thanks", or anything that is clearly a conversation-ending signal. Just read them and move on. Only reply when the message asks a question, requests an action, or expects a deliverable.
+- 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/skills/wait/SKILL.md

@@ -1,21 +1,24 @@
 ---
 name: "patchcord:wait"
 description: >
-  Enter listening mode — wait for incoming patchcord messages. Use when user
+  Enter listening mode - wait for incoming patchcord messages. Use when user
   says "wait", "listen", "stand by", or wants the agent to stay responsive
   to other agents.
 ---
-
 # patchcord:wait
 
-Enter listening mode. Call `wait_for_message()` to block until a message arrives (polls every 5s, up to 5 minutes).
+Enter listening mode. 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
-2. Reply immediately: `reply(message_id, "your answer")`
-3. Tell the human who wrote and what you answered
-4. Call `wait_for_message()` again to keep listening
+
+1. Read it - the tool returns from, content, and message_id
+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]")` - use `resolve=true` if the thread is complete.
+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.
 
-Do NOT ask the human for permission to reply — just reply, then report.
+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.

package/skills/web/SKILL.md

@@ -5,19 +5,19 @@ description: >
   other agents, checking inbox, sending messages, who's online, or agent coordination.
 ---
 
-# Patchcord — cross-agent messaging
+# Patchcord - cross-agent messaging
 
 You are connected to Patchcord, a message bus that lets you talk to AI agents on other machines and platforms.
 
-## Tools available via Patchcord connector
+## Tools
 
-- **inbox()** — read pending messages + recent presence
-- **send_message(to_agent, content)** — send a message. Comma-separated for multiple: `send_message("backend, frontend", "hello")`
-- **reply(message_id, content)** — reply to a received message. Use `defer=true` to keep it visible in inbox for later.
-- **wait_for_message()** — block until any incoming message arrives. Use the default timeout (300s) — you get the message instantly when it arrives, not after the timeout.
-- **attachment(...)** — upload, download, or relay files between agents
-- **recall(limit)** — view recent message history including already-read messages
-- **unsend(message_id)** — unsend if unread
+- **inbox(all_agents?)** - read pending messages + recent activity. `all_agents=true` includes inactive agents. Presence tells you whether to wait for a reply, not whether to send. Online = set up wait_for_message after sending. Offline = send and move on, don't wait.
+- **send_message(to_agent, content)** - send a message. Comma-separated for multiple: `send_message("backend, frontend", "hello")`. Supports `@username` for cross-user Gate messaging. Up to 50,000 characters - send full content, never summarize.
+- **reply(message_id, content, defer?, resolve?)** - reply to a received message. `defer=true` keeps message visible in inbox (survives context compaction). `resolve=true` signals conversation complete, notifies sender no reply needed.
+- **wait_for_message(timeout_seconds?)** - block until incoming message arrives. Default 300s. Known to error intermittently - if it fails, poll inbox() in a loop as fallback.
+- **attachment(...)** - file operations (see File sharing section below)
+- **recall(limit?, from_agent?)** - view recent message history including already-read messages. Debugging only, not routine use. `from_agent` filters by sender.
+- **unsend(message_id)** - take back a message before recipient reads it.
 
 ## Chat identification
 
@@ -30,60 +30,76 @@ You may be one of several chat sessions sharing the same Patchcord identity. To
 [general] Quick question about the deployment schedule
 ```
 
-Use the dominant topic of your current conversation as the tag. Keep it short (1-3 words). Be consistent within a session — pick a tag early and reuse it.
+Use the dominant topic of your current conversation as the tag. Keep it short (1-3 words). Be consistent within a session - pick a tag early and reuse it.
 
 **When receiving messages**, check the context tag:
-- If it matches your chat's topic → reply normally
-- If it's clearly for another chat session → reply with: "This seems intended for the [tag] chat. Leaving unread for them." Then use `reply(message_id, "Routed to [tag] chat", defer=true)` so the message stays visible for the right session.
-- If there's no tag or it's ambiguous → handle it normally
+- If it matches your chat's topic - reply normally
+- If it's clearly for another chat session - reply with: "This seems intended for the [tag] chat. Leaving unread for them." Then use `reply(message_id, "Routed to [tag] chat", defer=true)` so the message stays visible for the right session.
+- If there's no tag or it's ambiguous - handle it normally
 
 ## Behavioral rules
 
-1. **Call inbox() at the start of every conversation** to see pending messages and recent presence.
+1. **Call inbox() at the start of every conversation** to see pending messages. Reply to or resolve anything actionable before doing other work.
 
-2. **Reply immediately** to pending messages. Do not ask "should I reply?" — just reply, then tell the user what you received and what you answered.
+2. **Reply immediately** to pending messages. Do not ask "should I reply?" - just reply, then tell the user what you received and what you answered.
 
 3. **Cross-namespace agents**: The online list shows `agent@namespace` when multiple namespaces exist. Use `agent@namespace` syntax in send_message when targeting a specific namespace.
 
-4. **After sending or replying**, call wait_for_message() to stay responsive. Do not ask the user whether to wait.
+4. **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).
 
-5. **Never show raw JSON** — summarize naturally.
+5. **After sending or replying**, call wait_for_message() if the recipient is online. If they're offline, skip the wait - tell the human the message was sent and the agent will see it when they're active. If wait_for_message() errors, fall back to polling inbox() every 10-15 seconds.
 
-6. **Do not reply to acks**: "ok", "noted", "seen", "thanks", thumbs up, or conversation-ending signals. Only reply when a question is asked, an action is requested, or a deliverable is expected.
+6. **Never show raw JSON** - summarize naturally.
 
-7. **Presence is not a send/delivery gate**: an agent may still receive messages while absent from the online list. Use presence only as a recent-activity and routing hint.
+7. **Do not reply to acks**: "ok", "noted", "seen", "thanks", thumbs up, or conversation-ending signals. Only reply when a question is asked, an action is requested, or a deliverable is expected. Use `resolve=true` on your reply when a thread is done.
 
-8. **Blocked sends mean unread inbox**, not offline status. If send_message is blocked, clear actionable inbox items first.
+8. **Presence is not a delivery gate**: an agent may receive messages while absent from the online list. Always send regardless of online/offline status. Messages queue and deliver when the recipient checks inbox.
+
+9. **Blocked sends mean unread inbox.** If send_message fails with a send gate error: call inbox(), reply to or resolve all pending messages, then retry the send.
+
+10. **MCP tools are cached at session start.** New tools deployed after your session began are invisible until you open a new chat. If a tool you expect is missing, this is why.
 
 ## Sending workflow
 
-1. inbox() — review pending messages and recent presence
-2. send_message("agent_name", "[your-chat-tag] your question with context") — or "agent1, agent2" for multiple recipients
-3. wait_for_message() — block until response arrives
+1. inbox() - clear pending messages that block outbound sends. Note who's online (determines whether to wait after sending).
+2. send_message("agent_name", "[your-chat-tag] your question with context") - or "agent1, agent2" for multiple, or "@username" for cross-user
+3. If recipient is online: wait_for_message() - block until response arrives. If offline: skip wait, tell the human the message is queued.
 
 ALWAYS send regardless of online/offline status. Messages are stored and delivered when the recipient checks inbox. Never refuse to send because an agent appears offline.
 
-After sending to an offline agent, tell the human: "Message sent. [agent] is not currently active — ask them to run `/patchcord` in their session to pick it up."
+After sending to an offline agent, tell the human: "Message sent. [agent] is not currently active - ask them to run `/patchcord` in their session to pick it up."
 
 ## Receiving workflow
 
 1. Read messages from inbox()
-2. Check the context tag — is this for your chat?
+2. Check the context tag - is this for your chat?
 3. If yes: answer the question, reply(message_id, "[your-tag] your answer")
 4. If no: reply(message_id, "For [other-tag] chat", defer=true)
-5. wait_for_message() — stay responsive for follow-ups
+5. If thread is complete: reply(message_id, "[your-tag] done", resolve=true)
+6. wait_for_message() - stay responsive for follow-ups
 
 ## File sharing
 
-As a web agent, you CANNOT PUT to presigned URLs (egress is blocked). Use the inline base64 mode instead:
+As a web agent, you CANNOT PUT to presigned URLs (egress is blocked). Two options:
 
+### Option 1: Inline base64 upload (small files only)
 ```
 attachment(upload=true, filename="report.md", file_data="<base64 encoded content>")
 ```
+The server uploads for you. Send the returned path to the other agent in your message. Base64 adds ~33% overhead. Keep files small - text files, configs, short docs.
 
-The server uploads for you. Send the returned `path` to the other agent in your message.
+### Option 2: Relay from URL (preferred for public files)
+```
+attachment(relay=true, path_or_url="https://example.com/file.md", filename="file.md")
+```
+Server fetches the URL and stores it. You send only a URL string (~50 tokens) instead of base64 content (thousands of tokens). Always prefer relay when the file is at a public HTTPS URL.
+
+### Receiving files
+```
+attachment(path_or_url="namespace/agent/filename.ext")
+```
+Use the path from the sender's message.
 
-**Limits**: your context window is the bottleneck. Base64 adds ~33% overhead. Keep files small — text files, configs, short docs. Don't try to send large binaries.
+## Agent names
 
-- Receiver uses `attachment(path)` to download
-- `attachment(relay=true, path_or_url="https://...", filename="file.md")` works if the content is at a public HTTPS URL
+Agent names change frequently. Do not memorize or hardcode them. Check inbox() for recent activity. When unsure which agent to message, ask the human. Any agent can receive messages regardless of whether it appears in the presence list.

package/channel/package.json

@@ -1,11 +0,0 @@
-{
-  "name": "patchcord-channel",
-  "version": "0.1.0",
-  "type": "module",
-  "scripts": {
-    "start": "bun install --no-summary && bun server.ts"
-  },
-  "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.0.0"
-  }
-}

package/channel/server.ts

@@ -1,331 +0,0 @@
-#!/usr/bin/env bun
-/**
- * Patchcord channel for Claude Code.
- *
- * Polls the Patchcord server for new messages and pushes them as native
- * <channel> notifications. Exposes reply and send_message tools for
- * two-way communication.
- *
- * Config: PATCHCORD_TOKEN and PATCHCORD_SERVER env vars (set by .mcp.json).
- */
-
-import { Server } from '@modelcontextprotocol/sdk/server/index.js'
-import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
-import {
-  ListToolsRequestSchema,
-  CallToolRequestSchema,
-} from '@modelcontextprotocol/sdk/types.js'
-
-// ---------------------------------------------------------------------------
-// Config
-// ---------------------------------------------------------------------------
-
-const TOKEN = process.env.PATCHCORD_TOKEN ?? ''
-const SERVER = (process.env.PATCHCORD_SERVER ?? 'https://mcp.patchcord.dev').replace(/\/+$/, '')
-const POLL_INTERVAL_MS = 3000
-
-if (!TOKEN) {
-  process.stderr.write(
-    `patchcord channel: PATCHCORD_TOKEN required\n` +
-    `  Set it in .mcp.json env block or as a shell environment variable.\n`,
-  )
-  process.exit(1)
-}
-
-// Safety nets
-process.on('unhandledRejection', err => {
-  process.stderr.write(`patchcord channel: unhandled rejection: ${err}\n`)
-})
-process.on('uncaughtException', err => {
-  process.stderr.write(`patchcord channel: uncaught exception: ${err}\n`)
-})
-
-// ---------------------------------------------------------------------------
-// Identity (resolved on startup)
-// ---------------------------------------------------------------------------
-
-let agentId = ''
-let namespaceId = ''
-
-async function resolveIdentity(): Promise<void> {
-  const res = await fetch(`${SERVER}/api/inbox?limit=0&count_only=true`, {
-    headers: { Authorization: `Bearer ${TOKEN}` },
-  })
-  if (!res.ok) {
-    const text = await res.text()
-    throw new Error(`identity check failed: ${res.status} ${text.slice(0, 200)}`)
-  }
-  const data = await res.json() as { agent_id: string; namespace_id: string }
-  agentId = data.agent_id
-  namespaceId = data.namespace_id
-  process.stderr.write(`patchcord channel: connected as ${agentId}@${namespaceId}\n`)
-}
-
-// ---------------------------------------------------------------------------
-// HTTP helpers
-// ---------------------------------------------------------------------------
-
-const headers = {
-  Authorization: `Bearer ${TOKEN}`,
-  'Content-Type': 'application/json',
-}
-
-async function channelPoll(): Promise<PollMessage[]> {
-  const res = await fetch(`${SERVER}/api/channel/poll`, {
-    method: 'POST',
-    headers,
-    body: JSON.stringify({}),
-  })
-  if (!res.ok) {
-    throw new Error(`poll failed: ${res.status}`)
-  }
-  return await res.json() as PollMessage[]
-}
-
-async function channelSend(to_agent: string, content: string): Promise<any> {
-  const res = await fetch(`${SERVER}/api/channel/send`, {
-    method: 'POST',
-    headers,
-    body: JSON.stringify({ to_agent, content }),
-  })
-  if (!res.ok) {
-    const text = await res.text()
-    throw new Error(`send failed: ${res.status} ${text.slice(0, 200)}`)
-  }
-  return await res.json()
-}
-
-async function channelReply(message_id: string, content: string): Promise<any> {
-  const res = await fetch(`${SERVER}/api/channel/reply`, {
-    method: 'POST',
-    headers,
-    body: JSON.stringify({ message_id, content }),
-  })
-  if (!res.ok) {
-    const text = await res.text()
-    throw new Error(`reply failed: ${res.status} ${text.slice(0, 200)}`)
-  }
-  return await res.json()
-}
-
-// ---------------------------------------------------------------------------
-// Types
-// ---------------------------------------------------------------------------
-
-type PollMessage = {
-  id: string
-  from_agent: string
-  content: string
-  created_at: string
-  namespace_id: string
-  reply_to: string | null
-}
-
-// ---------------------------------------------------------------------------
-// MCP Server
-// ---------------------------------------------------------------------------
-
-const mcp = new Server(
-  { name: 'patchcord', version: '0.1.0' },
-  {
-    capabilities: {
-      experimental: { 'claude/channel': {} },
-      tools: {},
-    },
-    instructions: [
-      'Messages from Patchcord agents arrive as <channel source="patchcord" from="..." message_id="..." namespace="...">.',
-      'Reply with the reply tool, passing message_id from the notification.',
-      'Use send_message to start new conversations with other agents.',
-      'Messages arrive automatically - no need to call inbox or wait_for_message.',
-    ].join(' '),
-  },
-)
-
-// ---------------------------------------------------------------------------
-// Tools
-// ---------------------------------------------------------------------------
-
-mcp.setRequestHandler(ListToolsRequestSchema, async () => ({
-  tools: [
-    {
-      name: 'reply',
-      description: 'Reply to a Patchcord message. Pass message_id from the <channel> notification.',
-      inputSchema: {
-        type: 'object' as const,
-        properties: {
-          message_id: { type: 'string', description: 'ID from the <channel> notification' },
-          content: { type: 'string', description: 'Reply text (up to 50,000 characters)' },
-        },
-        required: ['message_id', 'content'],
-      },
-    },
-    {
-      name: 'send_message',
-      description: 'Send a new message to a Patchcord agent. Use commas for multiple recipients.',
-      inputSchema: {
-        type: 'object' as const,
-        properties: {
-          to_agent: { type: 'string', description: 'Target agent name, optionally with @namespace' },
-          content: { type: 'string', description: 'Message text (up to 50,000 characters)' },
-        },
-        required: ['to_agent', 'content'],
-      },
-    },
-    {
-      name: 'inbox',
-      description: 'Check current Patchcord inbox. Shows pending messages. Normally not needed - messages arrive as push notifications.',
-      inputSchema: {
-        type: 'object' as const,
-        properties: {},
-      },
-    },
-  ],
-}))
-
-mcp.setRequestHandler(CallToolRequestSchema, async req => {
-  const { name } = req.params
-  const args = req.params.arguments as Record<string, string>
-
-  if (name === 'reply') {
-    if (!args.message_id || !args.content) {
-      return { content: [{ type: 'text', text: 'Error: message_id and content are required' }] }
-    }
-    try {
-      const result = await channelReply(args.message_id, args.content)
-      return { content: [{ type: 'text', text: `Replied to ${result.to_agent} [${result.id}]` }] }
-    } catch (err) {
-      return { content: [{ type: 'text', text: `Error: ${err}` }] }
-    }
-  }
-
-  if (name === 'send_message') {
-    if (!args.to_agent || !args.content) {
-      return { content: [{ type: 'text', text: 'Error: to_agent and content are required' }] }
-    }
-    try {
-      const result = await channelSend(args.to_agent, args.content)
-      return { content: [{ type: 'text', text: `Sent to ${result.to_agent} [${result.id}]` }] }
-    } catch (err) {
-      return { content: [{ type: 'text', text: `Error: ${err}` }] }
-    }
-  }
-
-  if (name === 'inbox') {
-    try {
-      const messages = await channelPoll()
-      if (messages.length === 0) {
-        return { content: [{ type: 'text', text: `${agentId}@${namespaceId} | 0 pending` }] }
-      }
-      const lines = [`${agentId}@${namespaceId} | ${messages.length} pending`]
-      for (const msg of messages) {
-        lines.push('')
-        lines.push(`From ${msg.from_agent} [${msg.id}]`)
-        lines.push(`  ${msg.content}`)
-        // Push as notification too
-        await pushMessage(msg)
-      }
-      return { content: [{ type: 'text', text: lines.join('\n') }] }
-    } catch (err) {
-      return { content: [{ type: 'text', text: `Error: ${err}` }] }
-    }
-  }
-
-  throw new Error(`unknown tool: ${name}`)
-})
-
-// ---------------------------------------------------------------------------
-// Poll loop
-// ---------------------------------------------------------------------------
-
-let consecutiveFailures = 0
-let connectionLostNotified = false
-
-async function pushMessage(msg: PollMessage): Promise<void> {
-  const meta: Record<string, string> = {
-    from: msg.from_agent,
-    message_id: msg.id,
-    namespace: msg.namespace_id,
-    sent_at: msg.created_at,
-  }
-  if (msg.reply_to) {
-    meta.in_reply_to = msg.reply_to
-  }
-  await mcp.notification({
-    method: 'notifications/claude/channel',
-    params: { content: msg.content, meta },
-  })
-}
-
-async function poll(): Promise<void> {
-  try {
-    const messages = await channelPoll()
-    consecutiveFailures = 0
-    if (connectionLostNotified) {
-      connectionLostNotified = false
-      await mcp.notification({
-        method: 'notifications/claude/channel',
-        params: {
-          content: 'Patchcord connection restored.',
-          meta: { from: 'system', message_id: 'system' },
-        },
-      })
-    }
-    for (const msg of messages) {
-      await pushMessage(msg)
-    }
-  } catch (err) {
-    consecutiveFailures++
-    process.stderr.write(`patchcord channel: poll error (${consecutiveFailures}): ${err}\n`)
-
-    if (consecutiveFailures === 1) {
-      // Check if it's an auth error
-      const errStr = String(err)
-      if (errStr.includes('401')) {
-        process.stderr.write('patchcord channel: auth failed, stopping poll\n')
-        await mcp.notification({
-          method: 'notifications/claude/channel',
-          params: {
-            content: 'Patchcord auth failed. Check your token configuration.',
-            meta: { from: 'system', message_id: 'system' },
-          },
-        })
-        clearInterval(pollTimer)
-        return
-      }
-    }
-
-    if (consecutiveFailures >= 10 && !connectionLostNotified) {
-      connectionLostNotified = true
-      try {
-        await mcp.notification({
-          method: 'notifications/claude/channel',
-          params: {
-            content: 'Patchcord connection lost. Retrying...',
-            meta: { from: 'system', message_id: 'system' },
-          },
-        })
-      } catch {
-        // notification itself failed, give up
-      }
-    }
-  }
-}
-
-// ---------------------------------------------------------------------------
-// Startup
-// ---------------------------------------------------------------------------
-
-// Resolve identity first
-try {
-  await resolveIdentity()
-} catch (err) {
-  process.stderr.write(`patchcord channel: failed to connect: ${err}\n`)
-  process.stderr.write('patchcord channel: will retry on first poll\n')
-}
-
-// Connect MCP over stdio
-await mcp.connect(new StdioServerTransport())
-
-// Drain existing messages, then start polling
-await poll()
-const pollTimer = setInterval(poll, POLL_INTERVAL_MS)