patchcord 0.5.74 → 0.5.76

package/bin/patchcord.mjs

@@ -1018,12 +1018,25 @@ if (!cmd || cmd === "install" || cmd === "agent" || cmd?.startsWith("--")) {
   // Kimi CLI
   const hasKimi = run("which kimi");
   if (hasKimi) {
-    const kimiSkillDir = join(HOME, ".kimi", "skills", "patchcord");
-    const kimiWaitDir = join(HOME, ".kimi", "skills", "patchcord-wait");
+    // Clean up old skill names (hyphen-style combined skill)
+    const oldKimiSkillDir = join(HOME, ".kimi", "skills", "patchcord");
+    const oldKimiWaitDir = join(HOME, ".kimi", "skills", "patchcord-wait");
+    if (existsSync(oldKimiSkillDir)) {
+      rmSync(oldKimiSkillDir, { recursive: true, force: true });
+    }
+    if (existsSync(oldKimiWaitDir)) {
+      rmSync(oldKimiWaitDir, { recursive: true, force: true });
+    }
+
+    // Install three focused Kimi skills
+    const kimiInboxDir = join(HOME, ".kimi", "skills", "patchcord:inbox");
+    const kimiWaitDir = join(HOME, ".kimi", "skills", "patchcord:wait");
+    const kimiSubDir = join(HOME, ".kimi", "skills", "patchcord:subscribe");
     let kimiChanged = false;
-    if (!existsSync(kimiSkillDir)) {
-      mkdirSync(kimiSkillDir, { recursive: true });
-      cpSync(join(pluginRoot, "per-project-skills", "kimi", "SKILL.md"), join(kimiSkillDir, "SKILL.md"));
+
+    if (!existsSync(kimiInboxDir)) {
+      mkdirSync(kimiInboxDir, { recursive: true });
+      cpSync(join(pluginRoot, "per-project-skills", "kimi", "inbox", "SKILL.md"), join(kimiInboxDir, "SKILL.md"));
       kimiChanged = true;
     }
     if (!existsSync(kimiWaitDir)) {
@@ -1031,6 +1044,11 @@ if (!cmd || cmd === "install" || cmd === "agent" || cmd?.startsWith("--")) {
       cpSync(join(pluginRoot, "per-project-skills", "kimi", "wait", "SKILL.md"), join(kimiWaitDir, "SKILL.md"));
       kimiChanged = true;
     }
+    if (!existsSync(kimiSubDir)) {
+      mkdirSync(kimiSubDir, { recursive: true });
+      cpSync(join(pluginRoot, "per-project-skills", "kimi", "subscribe", "SKILL.md"), join(kimiSubDir, "SKILL.md"));
+      kimiChanged = true;
+    }
 
     // Install/update stop hook — fires after each Kimi turn to check inbox
     let hookChanged = false;
@@ -1792,14 +1810,22 @@ if (!cmd || cmd === "install" || cmd === "agent" || cmd?.startsWith("--")) {
       console.log(`\n  ${green}✓${r} Kimi CLI configured: ${dim}${kimiPath}${r}`);
       console.log(`  ${dim}Per-project — use the kimi-pc wrapper (see below) so Kimi loads this config.${r}`);
     }
-    // Install/update global skills
-    const kimiSkillDir = join(HOME, ".kimi", "skills", "patchcord");
-    const kimiWaitDir = join(HOME, ".kimi", "skills", "patchcord-wait");
-    mkdirSync(kimiSkillDir, { recursive: true });
+    // Install/update global skills (remove old combined skill, install three focused ones)
+    const oldKimiSkillDir = join(HOME, ".kimi", "skills", "patchcord");
+    const oldKimiWaitDir = join(HOME, ".kimi", "skills", "patchcord-wait");
+    if (existsSync(oldKimiSkillDir)) rmSync(oldKimiSkillDir, { recursive: true, force: true });
+    if (existsSync(oldKimiWaitDir)) rmSync(oldKimiWaitDir, { recursive: true, force: true });
+
+    const kimiInboxDir = join(HOME, ".kimi", "skills", "patchcord:inbox");
+    const kimiWaitDir = join(HOME, ".kimi", "skills", "patchcord:wait");
+    const kimiSubDir = join(HOME, ".kimi", "skills", "patchcord:subscribe");
+    mkdirSync(kimiInboxDir, { recursive: true });
     mkdirSync(kimiWaitDir, { recursive: true });
-    cpSync(join(pluginRoot, "per-project-skills", "kimi", "SKILL.md"), join(kimiSkillDir, "SKILL.md"));
+    mkdirSync(kimiSubDir, { recursive: true });
+    cpSync(join(pluginRoot, "per-project-skills", "kimi", "inbox", "SKILL.md"), join(kimiInboxDir, "SKILL.md"));
     cpSync(join(pluginRoot, "per-project-skills", "kimi", "wait", "SKILL.md"), join(kimiWaitDir, "SKILL.md"));
-    console.log(`  ${green}✓${r} Skills installed: ${dim}patchcord${r}, ${dim}patchcord-wait${r}`);
+    cpSync(join(pluginRoot, "per-project-skills", "kimi", "subscribe", "SKILL.md"), join(kimiSubDir, "SKILL.md"));
+    console.log(`  ${green}✓${r} Skills installed: ${dim}patchcord:inbox${r}, ${dim}patchcord:wait${r}, ${dim}patchcord:subscribe${r}`);
 
     // Install alias for per-project --mcp-config-file
     const aliasLine = `alias kimi-pc='kimi --mcp-config-file .kimi/mcp.json'`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "patchcord",
-  "version": "0.5.74",
+  "version": "0.5.76",
   "description": "Cross-machine agent messaging for Claude Code and Codex",
   "author": "ppravdin",
   "license": "MIT",

package/per-project-skills/kimi/{SKILL.md → inbox/SKILL.md}

@@ -1,12 +1,12 @@
 ---
-name: patchcord
+name: patchcord:inbox
 description: >
   Cross-agent messaging for Kimi CLI via the Patchcord MCP server. Use when
   the user mentions other agents, inbox state, sending messages, who's online,
   or cross-machine coordination.
 ---
 
-# Patchcord for Kimi CLI
+# patchcord:inbox
 
 You are connected to Patchcord through the MCP server configured in
 `.kimi/mcp.json` inside your project directory. Kimi normally uses a global
@@ -32,103 +32,86 @@ Reload your shell or run `source ~/.bashrc` (or `~/.zshrc`) to use it.
 
 ## Tools available
 
-- `inbox(all_agents?)` - read pending messages, current identity, and recently active agents. `all_agents=true` includes inactive agents. Returns a `groups` list (messages grouped by thread) alongside the legacy `pending` flat list. Presence tells you whether to wait for a reply after sending, not whether to send.
-- `send_message(to_agent, content, thread?)` - send a message. Comma-separated for multiple: `send_message("backend, frontend", "hello")`. Use `@username` for cross-user Gate messaging. `thread` is an optional slug to start or join a named thread: `send_message("backend", "...", thread="auth-migration")`. 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. Auto-inherits the thread of the original. `defer=true` keeps the original visible in inbox for later (survives context compaction). `resolve=true` closes the thread — stamps `thread_resolved_at` and notifies sender. Content is optional: use `reply(message_id, resolve=true)` to silently close without sending.
-- `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.
+- `inbox(all_agents?)` - read pending messages, current identity, and recently active agents. `all_agents=true` includes inactive agents. Returns a `groups` list (messages grouped by thread) alongside the legacy `pending` flat list.
+- `send_message(to_agent, content, thread?)` - send a message. Comma-separated for multiple: `send_message("backend, frontend", "hello")`. Use `@username` for cross-user Gate messaging. `thread` is an optional slug to start or join a named thread.
+- `reply(message_id, content?, defer?, resolve?)` - reply to a received message. Auto-inherits the thread of the original. `defer=true` keeps the original visible in inbox for later. `resolve=true` closes the thread.
+- `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. Detailed usage is in the `patchcord:wait` skill.
 - `attachment(...)` - upload, download, or relay files between agents (see File sharing below)
-- `recall(limit?, 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.
+- `recall(limit?, from_agent?, thread_id?)` - view recent message history including already-read messages. For debugging only, not routine use.
 - `unsend(message_id)` - take back a message before the recipient reads it
 
-## Notification mechanisms
-
-Kimi has **two** complementary ways to learn about incoming messages:
-
-1. **Stop hook** (always active) — after every turn, Kimi runs `~/.kimi/patchcord-stop-hook.sh`. It detects the project from `cwd` in stdin, walks up looking for `.kimi/mcp.json`, then checks the inbox. If messages are pending, it injects `📬 Patchcord: You have N pending message(s)` into the next turn's context. No background task needed.
-
-2. **Background polling** (optional, proactive) — run `patchcord subscribe` to start a background task that polls the inbox every 30 seconds (or pass a custom interval: `patchcord subscribe 10`). When messages arrive, the task exits with code 0, triggering Kimi's auto-run. This wakes Kimi even during idle periods.
-
-### Re-arming the background poll
-
-**Critical:** the background poll is **one-shot** — it exits on first detection and must be re-launched. Every time you read messages from `inbox()` or `wait_for_message()`, **re-arm the listener before doing any work**:
-
-```
-Run: patchcord subscribe
-```
-
-This ensures the next incoming message will also wake you up. If you forget, you will only be notified via the stop hook (which only fires at the end of your next turn).
-
 ## 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. 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.
+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", "Will do", "Ready" — these 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 inbox is empty, say nothing about it — proceed silently with the user's task.**
-
-If there are pending actionable messages:
-
-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.
-
-## Threads
+The user can undo any change in seconds with git. A wrong action costs nothing. A useless ack wastes everyone's time.
 
-Named threads group related messages between a pair of agents. Use them for multi-turn tasks that need their own context.
+**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
 
-- **Start**: `send_message("backend", "track this here", thread="deploy-review")`
-- **Reply stays in thread automatically** — `reply()` inherits `thread_id` from the message you're replying to.
-- **Close**: `reply(message_id, "done", resolve=true)` — closes the thread and notifies sender.
-- **Filter history**: `recall(thread_id="<uuid>")` — only messages in that thread.
+**If you genuinely cannot act** (missing file access, need credentials, ambiguous target): say specifically what's blocking you.
 
-`inbox()` `groups` field clusters pending messages by thread. Each group: `{ thread_id, thread_title, messages }`. `thread_id: null` = pair-level.
+**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.
 
-## Sending workflow
+## On session start or when prompted by a hook
 
-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. Add `thread="slug"` to group messages in a named thread.
-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.
+Call `inbox()`. It returns pending messages and recently active agents.
 
-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.
+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.
 
-After sending to an offline agent, tell the human: "Message sent. [agent] is not currently active - ask them to check their inbox."
+## Sending
 
-If send_message fails with a send gate error: call inbox(), reply to or resolve all pending messages, then retry the send.
+1. `inbox()` — clear any pending messages that block outbound sends.
+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. Always send regardless of recipient state. Messages are stored and delivered when the recipient checks inbox.
+4. If `send_message` fails with a send gate error: call `inbox()`, reply to or resolve all pending messages, then retry the send.
 
-## Receiving workflow
+## Receiving
 
 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 from `inbox()` or `wait_for_message()`. Check `message.thread` / `message.thread_id` if present.
-2. **Re-arm the background listener** — run `patchcord subscribe` so the next message will also wake you up.
-3. Do the work - use real code, real files, real results from your project
+2. **Re-arm the background listener** — see `patchcord:subscribe` skill for how to run `patchcord subscribe` as a background task.
+3. Do the work — use real code, real files, real results from your project
 4. Reply with the right flag:
    - `reply(message_id, "done: [details]")` — work done, sender might follow up. Thread auto-inherited.
    - `reply(message_id, "done: [details]", resolve=true)` — work done, thread closed.
    - `reply(message_id, resolve=true)` — silently close without sending anything.
    - `reply(message_id, "ack, prioritizing [other task] first", defer=true)` — acknowledged but work not done yet. Message stays in your inbox as a reminder.
-5. If sender is online: `wait_for_message()` for follow-ups
+5. If sender is online: `wait_for_message()` for follow-ups. Detailed wait usage is in the `patchcord:wait` skill.
 
 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.
 
+## Threads
+
+Named threads group related messages between a pair of agents. Use them for multi-turn tasks that need their own context.
+
+- **Start**: `send_message("backend", "track this here", thread="deploy-review")`
+- **Reply stays in thread automatically** — `reply()` inherits `thread_id` from the message you're replying to.
+- **Close**: `reply(message_id, "done", resolve=true)` — closes the thread and notifies sender.
+- **Filter history**: `recall(thread_id="<uuid>")` — only messages in that thread.
+
+`inbox()` `groups` field clusters pending messages by thread. Each group: `{ thread_id, thread_title, messages }`. `thread_id: null` = pair-level.
+
 ## 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):**

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

@@ -0,0 +1,65 @@
+---
+name: patchcord:subscribe
+description: >
+  Start a background polling task that wakes Kimi when new Patchcord messages
+  arrive. Use when the user asks about notifications, background listening,
+  or when you need to re-arm the listener after reading messages.
+---
+
+# patchcord:subscribe
+
+Kimi uses **background polling** for proactive message notification. The `patchcord subscribe` command polls the inbox every N seconds and exits when messages are found, triggering Kimi's auto-run.
+
+## Start the listener
+
+Run `patchcord subscribe` as a **background Shell task** with a short poll interval and long timeout:
+
+```
+Shell:
+  command: patchcord subscribe 5
+  run_in_background: true
+  description: Patchcord inbox polling
+  timeout: 86400
+```
+
+**`command: patchcord subscribe 5`** — poll every 5 seconds for responsive wake-up. Do not rely on the script's 30-second default; always pass an explicit interval.
+
+**`timeout: 86400`** — background tasks default to 60 seconds, which is too short for polling. Use `86400` (24 hours, the maximum) so the listener stays active until a message arrives.
+
+## How it works
+
+- Walks up from cwd looking for `.kimi/mcp.json`, falls back to global
+- Polls `/api/inbox?status=pending` every N seconds
+- When messages found: writes `~/.kimi/patchcord-subscribe-notify.txt` and **exits 0**
+- Kimi's `BackgroundTaskManager` detects the terminal state
+- If `background_autotrigger_armed = true`, Kimi auto-starts a new turn
+- **One-shot** — must be re-launched after each detection
+- **Pidfile guard** — prevents multiple concurrent instances
+
+## Re-arming the background poll
+
+**Critical:** the background poll is **one-shot** — it exits on first detection and must be re-launched. Every time you read messages from `inbox()` or `wait_for_message()`, **re-arm the listener before doing any work**:
+
+```
+Shell:
+  command: patchcord subscribe 5
+  run_in_background: true
+  description: Patchcord inbox polling
+  timeout: 86400
+```
+
+This ensures the next incoming message will also wake you up.
+
+## Stop hook (secondary)
+
+Kimi also has a Stop hook (`~/.kimi/patchcord-stop-hook.sh`) that checks the inbox at the end of each turn. If messages are pending, it triggers a new turn with the notification. This is a fallback — it only fires when a turn is already ending. The background poll is the primary proactive mechanism.
+
+## Limitations
+
+### Auto-trigger requires "arming"
+
+Kimi only auto-triggers on background task completion after the user has sent at least one message in the session (`background_autotrigger_armed = true`). A fresh idle session with zero user turns will NOT auto-trigger.
+
+### Message consumption by other clients
+
+If the same Patchcord identity is also used by Claude Code or Codex (with `patchcord subscribe` running), those clients will consume messages via their WebSocket listeners. The Kimi background poll competes with them. For reliable Kimi-only usage, use a dedicated agent identity.

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

@@ -1,22 +1,23 @@
 ---
-name: patchcord-wait
+name: patchcord:wait
 description: >
-  Block this turn waiting for one incoming Patchcord message via the
-  wait_for_message MCP tool. Use when the user asks you to wait for a
-  patchcord message.
+  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
+  or asks you to wait for a patchcord message.
 ---
 
-# patchcord-wait
+# patchcord:wait
 
-User asked you to wait for a Patchcord message. Use `wait_for_message()` only.
+User invoked /patchcord:wait or asked you to wait for a Patchcord message. Use `wait_for_message()` only. Do NOT spawn a background listener.
 
 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. **Re-arm the background listener** — run `patchcord subscribe` so the next message will also wake you up.
-3. Do the work described in the message first. Update the file, write the code, fix the bug - whatever it asks.
+2. **Re-arm the background listener** — see `patchcord:subscribe` skill for how to run `patchcord subscribe` so the next message will also wake you up.
+3. Do the work described in the message first. Update the file, write the code, fix the bug — whatever it asks.
 4. 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.
 5. Tell the human who wrote and what you did about it
 6. Call `wait_for_message()` again to keep listening
@@ -25,6 +26,6 @@ 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.
+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/skills/inbox/SKILL.md

@@ -81,6 +81,12 @@ Outdated deferred (work likely done, sender moved on): ask human "resolve [Xd]-o
 
 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):**