patchcord 0.6.42 → 0.6.43

package/.claude-plugin/marketplace.json

@@ -8,6 +8,11 @@
       "name": "patchcord",
       "source": "./",
       "description": "Cross-machine agent messaging — connect Claude Code, Codex, Cursor, ChatGPT, and other agents across projects and machines."
+    },
+    {
+      "name": "patchcord-ap",
+      "source": "./agent-plugin",
+      "description": "EXPERIMENTAL. The same patchcord skills and MCP server packaged to the Agent Plugins 1.0.0 open standard. Installs alongside `patchcord` and replaces nothing — install this only to test standard-format loading."
     }
   ]
 }

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

package/agent-plugin/.codex-plugin/plugin.json

@@ -0,0 +1,22 @@
+{
+  "name": "patchcord",
+  "version": "0.6.40",
+  "description": "Cross-machine agent messaging for Claude Code and Codex",
+  "author": {
+    "name": "ppravdin",
+    "url": "https://patchcord.dev"
+  },
+  "homepage": "https://patchcord.dev",
+  "repository": "https://github.com/ppravdin/patchcord",
+  "license": "MIT",
+  "keywords": [
+    "claude-code",
+    "codex",
+    "mcp",
+    "agent",
+    "messaging",
+    "plugin"
+  ],
+  "skills": "./skills/",
+  "mcpServers": "./.mcp.json"
+}

package/agent-plugin/.mcp.json

@@ -0,0 +1,9 @@
+{
+  "mcpServers": {
+    "patchcord": {
+      "type": "http",
+      "url": "https://mcp.patchcord.dev/mcp",
+      "bearer_token_env_var": "PATCHCORD_TOKEN"
+    }
+  }
+}

package/agent-plugin/README.md

@@ -0,0 +1,61 @@
+# patchcord — Agent Plugins 1.0.0 packaging
+
+**Generated. Do not edit by hand** — run `node scripts/build-agent-plugin.mjs`.
+This whole directory is deleted and rewritten on every build.
+
+This is an EXPERIMENTAL second packaging of the same skills and the same MCP
+server. It replaces nothing. `npx patchcord` and every per-harness config the
+installer writes are untouched and keep working exactly as before.
+
+## What is in here
+
+| File | Read by | Purpose |
+|---|---|---|
+| `plugin.json` | Agent Plugins clients | The open-standard manifest. Required: `$schema`, `name`. |
+| `mcp.json` | Agent Plugins clients | Standard MCP declaration. **Carries no credential — see below.** |
+| `.codex-plugin/plugin.json` | Codex | Codex uses pointer fields (`skills`, `mcpServers`) instead of the spec's fixed locations. |
+| `.mcp.json` | Codex | Codex MCP config, with the token read from an env var. |
+| `skills/*/SKILL.md` | both | Copied from `../skills/`, with `name:` rewritten to the directory name. |
+
+## The credential, and why `mcp.json` looks incomplete
+
+Agent Plugins 1.0.0 expands `${PLUGIN_ROOT}` and `${PLUGIN_DATA}` only, and
+only inside `args`, `env`, and `cwd`. `headers` is not in that list and there
+is no host-environment passthrough anywhere in the spec.
+
+So **the standard has no way to express "use this user's bearer token"**, and
+patchcord is nothing but a per-project bearer token. Writing
+`"Authorization": "Bearer ${PATCHCORD_TOKEN}"` into `mcp.json` would send that
+literal string to the server. The file therefore names the endpoint and the
+transport and stops, rather than looking complete and failing at runtime.
+
+Clients close the gap with their own extensions, which is where the token
+actually comes from:
+
+- **Codex** — `bearer_token_env_var` in `.mcp.json`, pointing at
+  `$PATCHCORD_TOKEN`.
+- **VS Code** — `envFile` / `headers`, neither of which is in the core schema.
+
+This is the one finding worth taking upstream: the portable core can carry the
+server's identity everywhere, but not its credential.
+
+## Trying it in Codex
+
+The marketplace is already registered, so:
+
+```bash
+export PATCHCORD_TOKEN=<an agent bearer for the namespace you want>
+codex plugin add patchcord-ap@patchcord-marketplace
+```
+
+Remove it with `codex plugin remove patchcord-ap@patchcord-marketplace`. The
+existing `patchcord@patchcord-marketplace` entry is unaffected either way.
+
+## Known limitation: one token per environment
+
+`$PATCHCORD_TOKEN` is a single value per shell, while patchcord's model is one
+namespace per project. A plugin installed this way is therefore **one identity
+per environment**, not one per project — the same constraint that already
+applies to Hermes, and the reason the current per-project installer writes
+per-directory config instead. Do not use this packaging for multi-seat work
+until the standard grows a per-project secret mechanism.

package/agent-plugin/mcp.json

@@ -0,0 +1,9 @@
+{
+  "$schema": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json",
+  "mcpServers": {
+    "patchcord": {
+      "type": "streamable-http",
+      "url": "https://mcp.patchcord.dev/mcp"
+    }
+  }
+}

package/agent-plugin/plugin.json

@@ -0,0 +1,21 @@
+{
+  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
+  "name": "patchcord",
+  "version": "0.6.43",
+  "description": "Cross-machine agent messaging for Claude Code and Codex",
+  "author": {
+    "name": "ppravdin",
+    "url": "https://patchcord.dev"
+  },
+  "homepage": "https://patchcord.dev",
+  "repository": "https://github.com/ppravdin/patchcord",
+  "license": "MIT",
+  "keywords": [
+    "claude-code",
+    "codex",
+    "mcp",
+    "agent",
+    "messaging",
+    "plugin"
+  ]
+}

package/agent-plugin/skills/inbox/SKILL.md

@@ -0,0 +1,202 @@
+---
+name: inbox
+description: >
+  MCP tool workflow for Patchcord cross-agent messaging. Active ONLY when
+  mcp_patchcord_* tools are loaded in this session — ignore this skill
+  otherwise.
+---
+# 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.
+
+## 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.
+
+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.
+
+## Name the other agent when you talk to the human
+
+When you tell a human that you sent, received, or replied to a message, always write the full address as `name@namespace` — never a bare role word like "the worker", "their lead", or "the team".
+
+The human cannot see your inbox. An unnamed recipient is a claim they cannot check. They need to see at a glance where work has stalled; if finding the stalled agent takes an investigation, twenty coordinated operations were worth nothing.
+
+`name` alone is not enough either once you are linked to more than one namespace — every team has a seat called `lead`, so two of them read identically.
+
+## 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. The size limit is the server's, not a number to remember: it is 10 MiB by default and a self-hosted server can raise it. If a file is too large the command prints the server's own limit.
+
+**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.
+  - **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.
+- 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/agent-plugin/skills/subscribe/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: subscribe
+description: >
+  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.
+---
+
+User invoked /patchcord:subscribe — do NOT substitute `wait_for_message()`. Spawn the listener.
+
+# Start
+
+1. **Drain the inbox first.** Call `mcp__patchcord__inbox`. If anything is pending, process it per the patchcord:inbox skill before continuing. Backlog can accumulate while no listener was up; subscribe must catch it.
+
+2. **Spawn the listener under Monitor** (not Bash with run_in_background — Monitor turns each stdout line into a notification):
+
+   ```
+   Monitor(
+     description: "patchcord realtime listener",
+     persistent: true,
+     timeout_ms: 3600000,
+     command: "patchcord subscribe | grep --line-buffered '^PATCHCORD:'; exit ${PIPESTATUS[0]}"
+   )
+   ```
+
+   The grep filter drops internal `HEARTBEAT` keepalive lines (written every 30 s to detect a dead pipe) — only `PATCHCORD:` lines fire notifications. `${PIPESTATUS[0]}` preserves subscribe's exit code through the pipe.
+
+   `subscribe.mjs` handles its own pidfile guard — if another listener is already active for this agent it exits with code 2 and stderr `already running (pid N)`. Monitor catches the stream-end event; read the output file and report.
+
+3. **Tell the user one line:** *"Patchcord listener active — I'll pick up new messages as they arrive."*
+
+# When a notification fires
+
+Monitor surfaces `PATCHCORD: 1 new from <sender>`:
+
+1. Say: *"Got a Patchcord ping from <sender> — checking inbox."*
+2. Call `mcp__patchcord__inbox`.
+3. Do the work per the patchcord:inbox skill, reply with what you did.
+
+# Stopping
+
+Tell the user one of:
+- Close this Claude Code session.
+- `kill $(cat /tmp/patchcord_subscribe_<namespace>_<agent>.pid)`
+
+# If the Monitor stream ends
+
+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 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
+
+Report the cause in one sentence. STOP.
+
+# If the MCP tools 401 — check before you believe the error
+
+`mcp__patchcord__*` returning **401 / "requires re-authorization (token expired)"** does NOT establish that the token expired. Claude Code keeps a **local** MCP config cache in `~/.claude.json` under `projects[<project dir>].mcpServers`, and local scope **beats** the project's `.mcp.json`. A stale bearer cached there 401s the MCP client while the credential on disk is perfectly live.
+
+**Always run `patchcord whoami --json` before reporting an auth failure.** It reads the disk config, so it keeps working in exactly this state:
+
+```bash
+patchcord whoami --json
+```
+
+If `warnings` contains `claude_local_mcp_cache_override`, **relay its `tell_human` text to the user verbatim.** They have no reason to know this command exists — all they saw was a tool failing.
+
+Then **offer to clear it**: *"Want me to remove the stale entry?"* Ask first — `~/.claude.json` is the user's global editor config, holds far more than MCP servers, and writing it races the running Claude Code process. But do not stop at diagnosing. Most users do not want to hand-edit JSON, and an accurate report they cannot act on leaves them exactly as stuck as no report.
+
+If they say yes:
+
+1. **Back it up first** — `cp ~/.claude.json ~/.claude.json.bak.$(date +%s)`.
+2. **Remove only** `projects["<dir>"].mcpServers["patchcord"]`. Not the whole `mcpServers` object, not the project entry, not the file. Parse, delete the one key, write atomically.
+3. **Then tell them to run `/mcp` and reconnect patchcord.**
+
+**Step 3 is the one that actually heals it, and it is the one that gets forgotten.** Clearing the entry changes a file the running MCP client already read; until it reloads, the tools keep 401-ing with the stale token and it looks like the fix failed. `/mcp` → reconnect reloads in place. Never tell them to restart Claude Code — if they are talking to you, they have already restarted, and it would not have helped anyway.
+
+You cannot run `/mcp` yourself; it is an interactive command in the user's client. Say the words and let them press it.
+
+Do not ask another agent to edit the file for you.
+
+## If `whoami` is clean and the MCP tools STILL 401
+
+This is a **different failure with an identical symptom**, and it is the one that leaves you stuck if you stop at "identity is fine".
+
+The stale-cache bug above is **cache newer than disk**. This one is the mirror image — **disk newer than your process**:
+
+1. Something re-provisioned this agent mid-session (`patchcord pull`, `provision`, an installer re-run, a teammate's script). That **rewrites `.mcp.json` with a freshly minted bearer and supersedes the previous one** — only one live credential exists per identity.
+2. Your MCP client is still holding the bearer it read at session start. That token is now dead.
+3. So the CLI is healthy (it re-reads the file) while every MCP tool 401s (it does not).
+
+**The CLI cannot detect this**, which is why it is not a `warnings[]` entry: no external process can see your client's in-process token. Confirm it by hand instead:
+
+```bash
+stat -c '%y %n' .mcp.json     # was it modified after this session started?
+```
+
+A modification time later than your session start is the answer.
+
+**Then reconnect the MCP client** — that is the fix, and it is the step people miss. Do **not** conclude that the token is broken, and do not keep retrying `inbox()`: a superseded token will 401 forever, and repeating the call reports the same error indefinitely. If reconnecting is not something you can do yourself, **tell the human that the MCP client needs reconnecting and why**, naming the rewrite time.
+
+Reported by `lead@mux-v2`, who followed the procedure above, correctly concluded "not that bug", and then had nowhere to go for several hours.
+
+If `whoami` is clean, `.mcp.json` was not touched this session, and the tools still fail, the problem is neither of these — say so plainly rather than guessing at the token.
+
+**Forbidden on failure:** no `pgrep`/`ps`/`kill`/`pkill`/`killall`, no pidfile writes, no respawning. The script manages pidfile cleanup itself; respawning will not fix a config problem.
+
+No matching error pattern = the listener exited cleanly (session ended, user killed it, or EPIPE detected). Nothing to do.

package/agent-plugin/skills/wait/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: 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/bin/patchcord.mjs

@@ -683,6 +683,7 @@ if (cmd === "whoami") {
     codex: "codex", kimi: "kimi", "kimi-code": "kimi",
     opencode: "opencode", agy: "antigravity", antigravity: "antigravity",
     cursor: "cursor", grok: "grok", hermes: "hermes",
+    jcode: "jcode",
   };
   const resolveOpts = {};
   if (toolFlag) {
@@ -907,8 +908,28 @@ if (cmd === "upload") {
     console.error(`file is empty: ${filePath}`);
     process.exit(1);
   }
-  if (stats.size > 25 * 1024 * 1024) {
-    console.error(`file is ${(stats.size / 1024 / 1024).toFixed(1)}MB; max is 25MB for inline upload.`);
+  // THIS IS NOT THE UPLOAD LIMIT AND MUST NOT BE DESCRIBED AS ONE.
+  //
+  // It used to say "max is 25MB", which was wrong in both directions. The
+  // server's limit is PATCHCORD_ATTACHMENT_MAX_BYTES, 10 MiB by default and
+  // raisable on a self-hosted install. So this client refused files a
+  // configured server would have accepted, and accepted files every default
+  // server rejects: a 15 MB file passed here, got base64'd to 20 MB, was
+  // uploaded in full, and came back 413. A guard set above the real limit does
+  // not guard; it only pays the upload first.
+  //
+  // The client must not hold a copy of a number the server owns. What is left
+  // is a memory guard for THIS process: the file, its base64 (4/3 the size),
+  // and the JSON body are all resident at once. The real limit comes back from
+  // the server, in max_bytes, and is printed below.
+  const MEMORY_GUARD_BYTES = 256 * 1024 * 1024;
+  if (stats.size > MEMORY_GUARD_BYTES) {
+    console.error(
+      `file is ${(stats.size / 1024 / 1024).toFixed(1)}MB. This client buffers the ` +
+      `file and its base64 copy in memory and refuses above ` +
+      `${MEMORY_GUARD_BYTES / 1024 / 1024}MB. This is a client memory guard, not ` +
+      `the server's size limit — the server's limit is lower.`
+    );
     process.exit(1);
   }
 
@@ -923,7 +944,18 @@ if (cmd === "upload") {
     "POST", `${baseUrl}/api/agent/attachment/upload`, token, body
   );
   if (status !== "200") {
-    console.error(`✗ HTTP ${status}: ${(json && json.error) || respBody}`);
+    // Print max_bytes/allowed when the server sends them. Without this the user
+    // reads "attachment exceeds maximum size" and is not told the maximum, so
+    // their next move is to guess — or to ask an agent, which will guess.
+    let detail = "";
+    if (json && typeof json.max_bytes === "number") {
+      detail = ` (server limit ${(json.max_bytes / 1024 / 1024).toFixed(1)}MiB` +
+        (typeof json.actual_bytes === "number"
+          ? `, this file ${(json.actual_bytes / 1024 / 1024).toFixed(1)}MiB)` : ")");
+    } else if (json && Array.isArray(json.allowed)) {
+      detail = ` (allowed: ${json.allowed.join(", ")})`;
+    }
+    console.error(`✗ HTTP ${status}: ${(json && json.error) || respBody}${detail}`);
     process.exit(1);
   }
   console.log(json.path);
@@ -1500,6 +1532,48 @@ if (cmd === "login" || cmd === "orchestrator" || cmd === "teamlead" || cmd === "
       } catch {}
       return agWritten;
     }
+    if (tool === "jcode") {
+      // jcode is the ONLY harness here that gets a STDIO entry, and the reason
+      // is not preference: jcode has no HTTP transport. Its loader keeps an
+      // entry only when `is_stdio()` holds and drops the rest at load time --
+      // "MCP: Skipping non-stdio server '<name>' (http); HTTP/SSE transports
+      // are not yet supported" (crates/jcode-base/src/mcp/protocol.rs). So the
+      // `type: "http"` entry every other harness receives is READ, RECOGNISED
+      // AND DISCARDED by jcode, with a log line and no error. A bridge process
+      // is the only shape it can run today.
+      //
+      // NAMED patchcord-jcode, NOT patchcord, AND THAT IS LOAD-BEARING.
+      // jcode merges .jcode/mcp.json, then .mcp.json, then .claude/mcp.json,
+      // with later files overriding same-named servers. A guard currently saves
+      // us -- a non-stdio entry never displaces a working stdio one (their
+      // issue #653) -- but that guard holds only while jcode CANNOT run http.
+      // The day it gains that transport, a shared name means .mcp.json wins,
+      // and jcode silently starts authenticating as claude_code's agent: two
+      // harnesses, one credential, no error anywhere. A distinct name cannot
+      // collide in the first place. Codex already does this (patchcord-codex).
+      //
+      // The bridge command mirrors the OpenClaw fallback this file already
+      // prints. NOT VERIFIED END TO END from here: no jcode on this machine,
+      // and proving it needs a live token against the real endpoint.
+      const jdir = join(dir, ".jcode"); mkdirSync(jdir, { recursive: true });
+      return writeJson(join(jdir, "mcp.json"), (o) => {
+        o.mcpServers = o.mcpServers || {};
+        // No `type` key at all. jcode infers stdio from the presence of
+        // `command`, and writing "type": "stdio" is one more string to get
+        // wrong for a default that is already correct.
+        o.mcpServers["patchcord-jcode"] = {
+          command: "npx",
+          args: [
+            "mcp-remote",
+            `${baseUrl}/mcp`,
+            "--header",
+            `Authorization: Bearer ${token}`,
+            "--header",
+            `X-Patchcord-Machine: ${hostname}`,
+          ],
+        };
+      });
+    }
     if (tool === "hermes") {
       // Hermes reads MCP servers ONLY from its GLOBAL ~/.hermes/config.yaml
       // (mcp_servers key) — it ignores a project-local .mcp.json. So unlike the
@@ -1555,7 +1629,7 @@ if (cmd === "login" || cmd === "orchestrator" || cmd === "teamlead" || cmd === "
     console.error(`      .mcp.json         → claude_code`);
     console.error(`      .cursor/mcp.json  → cursor`);
     console.error(`  Defaulting would overwrite an agent you did not name, so there is no default.`);
-    console.error(`  One of: claude_code, codex, cursor, kimi, opencode, antigravity, grok, hermes`);
+    console.error(`  One of: claude_code, codex, cursor, kimi, opencode, antigravity, grok, hermes, jcode`);
     console.error(`  ${usage}`);
     process.exit(1);
   };
@@ -3194,7 +3268,7 @@ if (!cmd || cmd === "install" || cmd === "agent" || cmd?.startsWith("--")) {
     // falls through to no choice instead of silently configuring a DIFFERENT
     // harness and writing someone's token to the wrong file.
     "vscode": "6", "zed": "7", "opencode": "8", "openclaw": "9", "antigravity": "10",
-    "cline": "11", "kimi": "12", "hermes": "13",
+    "cline": "11", "kimi": "12", "hermes": "13", "jcode": "15",
   };
 
 
@@ -3583,6 +3657,7 @@ if (!cmd || cmd === "install" || cmd === "agent" || cmd?.startsWith("--")) {
   const isCline = choice === "11";
   const isKimi = choice === "12";
   const isHermes = choice === "13";
+  const isJcode = choice === "15";
 
   // MoonshotAI ships TWO CLIs that both use the `kimi` command:
   //   • kimi-cli (Python): supports `--mcp-config-file`, config in .kimi/mcp.json
@@ -3657,6 +3732,36 @@ if (!cmd || cmd === "install" || cmd === "agent" || cmd?.startsWith("--")) {
     } catch (e) {
       console.log(`\n  ${yellow}⚠ Failed to write ${grokPath}: ${e.message}${r}`);
     }
+  } else if (isJcode) {
+    // jcode: project-local .jcode/mcp.json, and a STDIO entry rather than the
+    // http one every other harness gets. jcode has no HTTP transport -- it
+    // recognises `type: "http"` and drops the server at load time with a log
+    // line. See the writeWorkerConfig branch above for why the entry is named
+    // `patchcord-jcode` and not `patchcord`; the short version is that jcode
+    // merges .jcode/mcp.json, .mcp.json and .claude/mcp.json by server NAME,
+    // so a shared name lets claude_code's credential silently become jcode's
+    // the day jcode gains http support.
+    const jcodePath = join(cwd, ".jcode", "mcp.json");
+    try {
+      mkdirSync(dirname(jcodePath), { recursive: true });
+      let jobj = {};
+      try { jobj = JSON.parse(readFileSync(jcodePath, "utf-8")); } catch {}
+      jobj.mcpServers = jobj.mcpServers || {};
+      jobj.mcpServers["patchcord-jcode"] = {
+        command: "npx",
+        args: [
+          "mcp-remote",
+          `${serverUrl}/mcp`,
+          "--header",
+          `Authorization: Bearer ${token}`,
+        ],
+      };
+      writeSecureFile(jcodePath, JSON.stringify(jobj, null, 2) + "\n");
+      console.log(`\n  ${green}✓${r} jcode configured: ${dim}${jcodePath}${r}`);
+      console.log(`  ${dim}Bridged over stdio — jcode does not speak HTTP MCP yet.${r}`);
+    } catch (e) {
+      console.log(`\n  ${yellow}⚠ Failed to write ${jcodePath}: ${e.message}${r}`);
+    }
   } else if (isHermes) {
     // Hermes: global only (~/.hermes/config.yaml, YAML, mcp_servers key)
     const hermesPath = join(HOME, ".hermes", "config.yaml");
@@ -4324,10 +4429,11 @@ if (!cmd || cmd === "install" || cmd === "agent" || cmd?.startsWith("--")) {
   // Hermes is global config (~/.hermes/config.yaml) — no per-project file to ignore.
   if (!isWindsurf && !isGemini && !isZed && !isOpenClaw && !isCline && !isHermes) {
     const gitignorePath = join(cwd, ".gitignore");
-    const configFile = isKimiCode ? ".kimi-code/mcp.json" : isKimi ? ".kimi/mcp.json" : isCodex ? ".codex/config.toml" : isCursor ? ".cursor/mcp.json" : isGrok ? ".grok/config.toml" : isVSCode ? ".vscode/mcp.json" : isOpenCode ? "opencode.json" : isAntigravity ? ".agents/mcp_config.json" : ".mcp.json";
+    const configFile = isJcode ? ".jcode/mcp.json" : isKimiCode ? ".kimi-code/mcp.json" : isKimi ? ".kimi/mcp.json" : isCodex ? ".codex/config.toml" : isCursor ? ".cursor/mcp.json" : isGrok ? ".grok/config.toml" : isVSCode ? ".vscode/mcp.json" : isOpenCode ? "opencode.json" : isAntigravity ? ".agents/mcp_config.json" : ".mcp.json";
     // Forms that already cover this config (its file or its dir)
     const patterns = [configFile];
-    if (isKimiCode) patterns.push(".kimi-code/");
+    if (isJcode) patterns.push(".jcode/");
+    else if (isKimiCode) patterns.push(".kimi-code/");
     else if (isKimi) patterns.push(".kimi/");
     else if (isCodex) patterns.push(".codex/");
     else if (isCursor) patterns.push(".cursor/");
@@ -4352,7 +4458,7 @@ if (!cmd || cmd === "install" || cmd === "agent" || cmd?.startsWith("--")) {
     }
   }
 
-  const toolName = isHermes ? "Hermes" : isKimiCode ? "Kimi Code" : isKimi ? "Kimi Code" : isAntigravity ? "Antigravity CLI" : isCline ? "Cline" : isOpenClaw ? "OpenClaw" : isOpenCode ? "OpenCode" : isZed ? "Zed" : isVSCode ? "VS Code" : isGemini ? "Gemini CLI" : isWindsurf ? "Windsurf" : isGrok ? "Grok CLI" : isCursor ? "Cursor" : isCodex ? "Codex" : "Claude Code";
+  const toolName = isJcode ? "jcode" : isHermes ? "Hermes" : isKimiCode ? "Kimi Code" : isKimi ? "Kimi Code" : isAntigravity ? "Antigravity CLI" : isCline ? "Cline" : isOpenClaw ? "OpenClaw" : isOpenCode ? "OpenCode" : isZed ? "Zed" : isVSCode ? "VS Code" : isGemini ? "Gemini CLI" : isWindsurf ? "Windsurf" : isGrok ? "Grok CLI" : isCursor ? "Cursor" : isCodex ? "Codex" : "Claude Code";
 
   if (!isWindsurf && !isGemini && !isZed && !isOpenClaw && !isCline && !isKimi && !isHermes) {
     console.log(`\n  ${dim}To connect a second agent:${r}`);

package/harnesses.json

@@ -217,6 +217,23 @@
       "installer_config": "cline_mcp_settings.json (VS Code globalStorage)",
       "harness_scope": "unknown",
       "listener": { "wake": "none", "mechanism": null, "self_arm": false, "survives_wake": null, "evidence": "declared" }
+    },
+    {
+      "id": "jcode",
+      "aliases": [],
+      "cli": "jcode",
+      "kind": "terminal",
+      "installer_scope": "project",
+      "installer_config": ".jcode/mcp.json",
+      "harness_scope": "project",
+      "listener": {
+        "wake": "none",
+        "mechanism": null,
+        "self_arm": false,
+        "survives_wake": null,
+        "evidence": "declared",
+        "note": "STDIO ONLY, WHICH IS WHY THIS ROW IS NOT LIKE THE OTHERS. jcode reads .jcode/mcp.json, .mcp.json and .claude/mcp.json, so it ALREADY finds the Claude Code entry we write - and drops it, because jcode supports stdio servers only and skips type http/sse at load time with a log line (crates/jcode-base/src/mcp/protocol.rs, retain on is_stdio). So our installer writes a stdio bridge entry instead of the http entry every other harness gets. Two consequences a reader must not undo: the server is named patchcord-jcode, NOT patchcord, because jcode merges those three files with later ones overriding by NAME - a shared name means the day jcode gains http transport, the .mcp.json entry becomes runnable and silently overrides, and jcode starts authenticating as claude_code's agent. And no wake: no subscribe path exists for jcode in this package."
+      }
     }
   ],
   "retired": [

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "patchcord",
-  "version": "0.6.42",
+  "version": "0.6.43",
   "description": "Cross-machine agent messaging for Claude Code and Codex",
   "scripts": {
-    "version": "node scripts/sync-plugin-version.mjs && git add .claude-plugin/plugin.json"
+    "version": "node scripts/sync-plugin-version.mjs && git add .claude-plugin/plugin.json agent-plugin/plugin.json"
   },
   "author": "ppravdin",
   "license": "MIT",
@@ -33,6 +33,7 @@
     "commands/",
     "README.md",
     "plugins/",
+    "agent-plugin/",
     "harnesses.json"
   ]
 }

package/per-project-skills/codex/SKILL.md

@@ -99,7 +99,7 @@ To message a user outside your namespace, use `@username` as the to_agent. Examp
 ```
 patchcord upload /path/to/report.md --mime text/markdown
 ```
-Prints the storage path. Pass it to `send_message`. No curl, no base64 in chat. 25MB cap.
+Prints the storage path. Pass it to `send_message`. No curl, no base64 in chat. The size limit belongs to the server: 10 MiB by default, raisable on a self-hosted server. Too large prints the server's own limit.
 
 **Public URLs → `attachment(relay=true, ...)`:**
 ```

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

@@ -105,7 +105,7 @@ To message a user outside your namespace, use `@username` as the to_agent. Examp
 ```
 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.
+Prints the storage path. Pass that path to `send_message`. No curl, no base64 in chat, no presigned URLs. The size limit is the server's, not a number to remember: it is 10 MiB by default and a self-hosted server can raise it. If a file is too large the command prints the server's own limit.
 
 **Public URLs → `attachment(relay=true, ...)`:**
 ```

package/scripts/build-agent-plugin.mjs

@@ -0,0 +1,215 @@
+#!/usr/bin/env node
+/**
+ * Generate the Agent Plugins 1.0.0 distribution at ./agent-plugin/.
+ *
+ * PURELY ADDITIVE. This does not touch .claude-plugin/, skills/, hooks/,
+ * commands/, or anything the current installer writes. Every existing harness
+ * keeps working exactly as it does today; the generated directory is a second,
+ * parallel packaging of the same content for clients that load the open
+ * standard (Codex/ChatGPT, Cursor, GitHub Copilot, Kiro, VS Code).
+ *
+ * WHY GENERATED RATHER THAN HAND-WRITTEN
+ *
+ * The skills are the same skills. Copying them by hand would create two
+ * SKILL.md bodies that drift, and the drift would be silent — both files stay
+ * valid, they just stop agreeing. Deriving them means the source of truth
+ * remains ./skills/ and this script is the only thing that has to be re-run.
+ *
+ * THE ONE TRANSFORM APPLIED
+ *
+ * Our skills declare `name: patchcord:inbox`. The Agent Skills specification
+ * that Agent Plugins defers to requires the name to be lowercase alphanumeric
+ * plus hyphens ONLY (a colon is invalid) and to MATCH THE PARENT DIRECTORY.
+ * Every real Codex plugin on this machine follows that rule.
+ *
+ * So the generated copies get `name: <directory>`. The originals are left
+ * alone, because that string is what Claude Code surfaces as
+ * `/patchcord:inbox` and renaming it in place would change a user-facing
+ * command name to fix a spec violation nobody is currently enforcing. Two
+ * packagings, two conventions, one body.
+ */
+
+import { readFileSync, writeFileSync, mkdirSync, readdirSync, rmSync, existsSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const ROOT = join(dirname(fileURLToPath(import.meta.url)), "..");
+const OUT = join(ROOT, "agent-plugin");
+const SKILLS_SRC = join(ROOT, "skills");
+
+const pkg = JSON.parse(readFileSync(join(ROOT, "package.json"), "utf-8"));
+const VERSION = pkg.version;
+const BASE_URL = "https://mcp.patchcord.dev";
+
+// Regenerate from scratch so a skill deleted upstream does not linger here.
+if (existsSync(OUT)) rmSync(OUT, { recursive: true });
+mkdirSync(join(OUT, ".codex-plugin"), { recursive: true });
+
+/* ---------- skills: copied, with `name` rewritten to the directory ---------- */
+
+const skillNames = readdirSync(SKILLS_SRC, { withFileTypes: true })
+  .filter((d) => d.isDirectory() && existsSync(join(SKILLS_SRC, d.name, "SKILL.md")))
+  .map((d) => d.name);
+
+if (skillNames.length === 0) {
+  console.error("build-agent-plugin: no skills found under ./skills — refusing to emit an empty plugin");
+  process.exit(1);
+}
+
+for (const name of skillNames) {
+  const body = readFileSync(join(SKILLS_SRC, name, "SKILL.md"), "utf-8");
+  // Replace only the `name:` line inside the leading frontmatter block. Anchored
+  // to the start of the file so a later `name:` in prose cannot be hit.
+  const fm = body.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  if (!fm) {
+    console.error(`build-agent-plugin: ${name}/SKILL.md has no frontmatter — refusing to guess`);
+    process.exit(1);
+  }
+  const rewritten = body.replace(/^(---\r?\n[\s\S]*?)^name:[ \t]*.*$/m, `$1name: ${name}`);
+  if (rewritten === body && !new RegExp(`^name:[ \\t]*${name}\\s*$`, "m").test(fm[1])) {
+    console.error(`build-agent-plugin: could not rewrite name: in ${name}/SKILL.md`);
+    process.exit(1);
+  }
+  mkdirSync(join(OUT, "skills", name), { recursive: true });
+  writeFileSync(join(OUT, "skills", name, "SKILL.md"), rewritten);
+}
+
+/* ---------- Agent Plugins 1.0.0 core: plugin.json + mcp.json ---------- */
+
+// The AP manifest schema is CLOSED (additionalProperties: false). Only the
+// fields it names may appear — notably there is no `skills` pointer, because
+// the spec fixes that location at ./skills/ rather than letting a manifest
+// redirect it.
+writeFileSync(join(OUT, "plugin.json"), JSON.stringify({
+  $schema: "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
+  name: "patchcord",
+  version: VERSION,
+  description: pkg.description,
+  author: { name: "ppravdin", url: "https://patchcord.dev" },
+  homepage: "https://patchcord.dev",
+  repository: "https://github.com/ppravdin/patchcord",
+  license: pkg.license,
+  keywords: pkg.keywords,
+}, null, 2) + "\n");
+
+// NOTE THE MISSING CREDENTIAL, DELIBERATELY.
+//
+// Agent Plugins 1.0.0 defines placeholder expansion for ${PLUGIN_ROOT} and
+// ${PLUGIN_DATA} ONLY, and only in `args`, `env`, and `cwd`. `headers` is not
+// in that list, and the spec has no host-environment passthrough at all. So
+// there is no conformant way to say "put THIS user's bearer in the
+// Authorization header" in this file.
+//
+// Writing `"Authorization": "Bearer ${PATCHCORD_TOKEN}"` here would produce a
+// file that looks correct and sends the literal string `${PATCHCORD_TOKEN}` to
+// the server. That is worse than an obviously incomplete file, so this one is
+// obviously incomplete: it names the endpoint and the transport and stops.
+//
+// Clients supply the missing half through their own extensions — Codex via
+// `bearer_token_env_var` in .mcp.json (below), VS Code via `envFile`/`headers`.
+// See agent-plugin/README.md.
+writeFileSync(join(OUT, "mcp.json"), JSON.stringify({
+  $schema: "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json",
+  mcpServers: {
+    patchcord: { type: "streamable-http", url: `${BASE_URL}/mcp` },
+  },
+}, null, 2) + "\n");
+
+/* ---------- Codex client files ---------- */
+
+// Codex reads .codex-plugin/plugin.json with POINTER fields (skills, mcpServers)
+// rather than the spec's fixed locations, so it needs its own manifest. Both
+// live in one directory without colliding: different filenames, different paths.
+writeFileSync(join(OUT, ".codex-plugin", "plugin.json"), JSON.stringify({
+  name: "patchcord",
+  version: VERSION,
+  description: pkg.description,
+  author: { name: "ppravdin", url: "https://patchcord.dev" },
+  homepage: "https://patchcord.dev",
+  repository: "https://github.com/ppravdin/patchcord",
+  license: pkg.license,
+  keywords: pkg.keywords,
+  skills: "./skills/",
+  mcpServers: "./.mcp.json",
+}, null, 2) + "\n");
+
+// `bearer_token_env_var` is Codex's own field — it names an environment
+// variable to read the token FROM, so the credential never enters this file.
+// That is what makes the plugin publishable: it carries no secret and is
+// identical for every user.
+writeFileSync(join(OUT, ".mcp.json"), JSON.stringify({
+  mcpServers: {
+    patchcord: {
+      type: "http",
+      url: `${BASE_URL}/mcp`,
+      bearer_token_env_var: "PATCHCORD_TOKEN",
+    },
+  },
+}, null, 2) + "\n");
+
+/* ---------- README (emitted, because this directory is wiped each build) ---------- */
+
+writeFileSync(join(OUT, "README.md"), `# patchcord — Agent Plugins 1.0.0 packaging
+
+**Generated. Do not edit by hand** — run \`node scripts/build-agent-plugin.mjs\`.
+This whole directory is deleted and rewritten on every build.
+
+This is an EXPERIMENTAL second packaging of the same skills and the same MCP
+server. It replaces nothing. \`npx patchcord\` and every per-harness config the
+installer writes are untouched and keep working exactly as before.
+
+## What is in here
+
+| File | Read by | Purpose |
+|---|---|---|
+| \`plugin.json\` | Agent Plugins clients | The open-standard manifest. Required: \`$schema\`, \`name\`. |
+| \`mcp.json\` | Agent Plugins clients | Standard MCP declaration. **Carries no credential — see below.** |
+| \`.codex-plugin/plugin.json\` | Codex | Codex uses pointer fields (\`skills\`, \`mcpServers\`) instead of the spec's fixed locations. |
+| \`.mcp.json\` | Codex | Codex MCP config, with the token read from an env var. |
+| \`skills/*/SKILL.md\` | both | Copied from \`../skills/\`, with \`name:\` rewritten to the directory name. |
+
+## The credential, and why \`mcp.json\` looks incomplete
+
+Agent Plugins 1.0.0 expands \`\${PLUGIN_ROOT}\` and \`\${PLUGIN_DATA}\` only, and
+only inside \`args\`, \`env\`, and \`cwd\`. \`headers\` is not in that list and there
+is no host-environment passthrough anywhere in the spec.
+
+So **the standard has no way to express "use this user's bearer token"**, and
+patchcord is nothing but a per-project bearer token. Writing
+\`"Authorization": "Bearer \${PATCHCORD_TOKEN}"\` into \`mcp.json\` would send that
+literal string to the server. The file therefore names the endpoint and the
+transport and stops, rather than looking complete and failing at runtime.
+
+Clients close the gap with their own extensions, which is where the token
+actually comes from:
+
+- **Codex** — \`bearer_token_env_var\` in \`.mcp.json\`, pointing at
+  \`$PATCHCORD_TOKEN\`.
+- **VS Code** — \`envFile\` / \`headers\`, neither of which is in the core schema.
+
+This is the one finding worth taking upstream: the portable core can carry the
+server's identity everywhere, but not its credential.
+
+## Trying it in Codex
+
+The marketplace is already registered, so:
+
+\`\`\`bash
+export PATCHCORD_TOKEN=<an agent bearer for the namespace you want>
+codex plugin add patchcord-ap@patchcord-marketplace
+\`\`\`
+
+Remove it with \`codex plugin remove patchcord-ap@patchcord-marketplace\`. The
+existing \`patchcord@patchcord-marketplace\` entry is unaffected either way.
+
+## Known limitation: one token per environment
+
+\`$PATCHCORD_TOKEN\` is a single value per shell, while patchcord's model is one
+namespace per project. A plugin installed this way is therefore **one identity
+per environment**, not one per project — the same constraint that already
+applies to Hermes, and the reason the current per-project installer writes
+per-directory config instead. Do not use this packaging for multi-seat work
+until the standard grows a per-project secret mechanism.
+`);
+
+console.log(`build-agent-plugin: wrote agent-plugin/ (v${VERSION}, skills: ${skillNames.join(", ")})`);

package/scripts/lib/resolve-project-bearer.mjs

@@ -126,6 +126,43 @@ const opencodeReader = (cwd) => readJsonAt(join(cwd, "opencode.json"), ["mcp", "
 const antigravityReader = (cwd) => readJsonAt(join(cwd, ".agents", "mcp_config.json"), ["mcpServers", "patchcord"], "antigravity");
 const grokReader = (cwd) => readGrokTomlShape(join(cwd, ".grok", "config.toml"));
 const codexReader = (cwd) => readCodexTomlShape(join(cwd, ".codex", "config.toml"));
+// jcode: STDIO entry, so the bearer is in `args`, not in `headers`. readJsonAt
+// cannot see it -- extractBearer requires headers.Authorization and a url, and
+// this entry has neither. jcode has no HTTP transport, so an entry shaped like
+// every other harness's would be dropped at load time, and a reader shaped like
+// every other harness's finds nothing.
+//
+// Keyed on `patchcord-jcode`, matching what the installer writes. The distinct
+// name exists so jcode's own merge (.jcode/mcp.json, then .mcp.json, then
+// .claude/mcp.json -- later overriding by NAME) can never make jcode adopt
+// claude_code's credential.
+function readJcodeStdioShape(path) {
+  if (!existsSync(path)) return null;
+  try {
+    const obj = parseJsonc(readFileSync(path, "utf-8"));
+    const entry = obj?.mcpServers?.["patchcord-jcode"];
+    const args = Array.isArray(entry?.args) ? entry.args : null;
+    if (!args) return null;
+    // `--header` `Authorization: Bearer <token>` as two adjacent argv items.
+    let token = null;
+    for (let i = 0; i < args.length; i++) {
+      const m = typeof args[i] === "string" && args[i].match(/^Authorization:\s*Bearer\s+(\S+)$/i);
+      if (m) { token = m[1]; break; }
+    }
+    const urlArg = args.find((a) => typeof a === "string" && /^https?:\/\//.test(a));
+    if (!token || !urlArg) return null;
+    return {
+      token,
+      baseUrl: urlArg.replace(/\/mcp(\/bearer)?$/, ""),
+      configFile: path,
+      tool: "jcode",
+    };
+  } catch {
+    return null;
+  }
+}
+
+const jcodeReader = (cwd) => readJcodeStdioShape(join(cwd, ".jcode", "mcp.json"));
 const kimiReader = (cwd) => readJsonAt(join(cwd, ".kimi", "mcp.json"), ["mcpServers", "patchcord"], "kimi");
 const kimiCodeReader = (cwd) => readJsonAt(join(cwd, ".kimi-code", "mcp.json"), ["mcpServers", "patchcord"], "kimi");
 
@@ -163,6 +200,7 @@ export function projectReadersForContext(ctx) {
     grok: grokReader,
     codex: codexReader,
     kimi: kimiCodeReader,
+    jcode: jcodeReader,
   };
   const defaultReaders = [
     claudeReader,
@@ -172,6 +210,7 @@ export function projectReadersForContext(ctx) {
     antigravityReader,
     grokReader,
     codexReader,
+    jcodeReader,
   ];
   const kimiReaders = [kimiReader, kimiCodeReader];
 
@@ -199,6 +238,7 @@ export function projectReadersForContext(ctx) {
       antigravityReader,
       grokReader,
       codexReader,
+      jcodeReader,
       claudeReader,
       ...kimiReaders,
     ];

package/scripts/sync-plugin-version.mjs

@@ -10,15 +10,30 @@ import { readFileSync, writeFileSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import { dirname, join } from "node:path";
 
+// EVERY manifest, not the one that existed when this was written. A second
+// packaged plugin (agent-plugin/) arrived later and this script did not know
+// about it, so a merge left it claiming 0.6.40 inside a 0.6.42 package — the
+// same drift the comment above describes, reappearing the moment a new manifest
+// was added. A list is what stops the next one being missed: add the path here
+// and the sync is automatic, rather than a step someone must remember.
 const root = join(dirname(fileURLToPath(import.meta.url)), "..");
 const pkg = JSON.parse(readFileSync(join(root, "package.json"), "utf8"));
-const manifestPath = join(root, ".claude-plugin", "plugin.json");
-const manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
+const MANIFESTS = [
+  join(root, ".claude-plugin", "plugin.json"),
+  join(root, "agent-plugin", "plugin.json"),
+];
 
-if (manifest.version === pkg.version) {
-  process.exit(0);
+for (const manifestPath of MANIFESTS) {
+  let manifest;
+  try {
+    manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
+  } catch {
+    // A manifest that is not present is not an error — agent-plugin/ is built
+    // in some trees and not others. A manifest that is present and STALE is.
+    continue;
+  }
+  if (manifest.version === pkg.version) continue;
+  manifest.version = pkg.version;
+  writeFileSync(manifestPath, JSON.stringify(manifest, null, 2) + "\n");
+  process.stderr.write(`synced ${manifestPath} version -> ${pkg.version}\n`);
 }
-
-manifest.version = pkg.version;
-writeFileSync(manifestPath, JSON.stringify(manifest, null, 2) + "\n");
-process.stderr.write(`synced plugin.json version -> ${pkg.version}\n`);

package/skills/inbox/SKILL.md

@@ -114,7 +114,7 @@ To message a user outside your namespace, use `@username` as the to_agent. Examp
 ```
 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.
+Prints the storage path. Pass that path to `send_message`. No curl, no base64 in chat, no presigned URLs. The size limit is the server's, not a number to remember: it is 10 MiB by default and a self-hosted server can raise it. If a file is too large the command prints the server's own limit.
 
 **Public URLs → `attachment(relay=true, ...)`:**
 ```