patchcord 0.5.32 → 0.5.34

package/bin/patchcord.mjs

@@ -68,6 +68,7 @@ Usage:
   npx patchcord@latest --token <token> --server <url>     Self-hosted with custom server
   npx patchcord@latest --full                             Same + full statusline
   npx patchcord@latest --rename <new-name> [--tool <slug>] Rename this agent (paste from dashboard)
+  npx patchcord@latest subscribe                          Start the realtime listener (used by /patchcord:subscribe)
   npx patchcord@latest skill apply                        Fetch custom skill from web console`);
   process.exit(0);
 }
@@ -77,6 +78,26 @@ if (cmd === "plugin-path") {
   process.exit(0);
 }
 
+// ── subscribe ─────────────────────────────────────────────────
+// Thin wrapper around scripts/subscribe.mjs so users see a clean
+// "npx patchcord subscribe" in their Claude Code tool log instead
+// of a wall of bash. subscribe.mjs handles its own pidfile guard
+// (exits with code 2 + "already running" if another listener is up),
+// so this command needs zero pre-checks.
+if (cmd === "subscribe") {
+  const subscribeScript = join(pluginRoot, "scripts", "subscribe.mjs");
+  if (!existsSync(subscribeScript)) {
+    console.error(`subscribe.mjs not found at ${subscribeScript}`);
+    process.exit(1);
+  }
+  const { spawnSync } = await import("child_process");
+  const result = spawnSync(process.execPath, [subscribeScript], {
+    stdio: "inherit",
+    env: process.env,
+  });
+  process.exit(result.status ?? (result.signal ? 1 : 0));
+}
+
 // ── --rename <new> [--tool <slug>] [--expect-token <prefix>] ────
 // Renames the agent's bearer in its tool's per-project config. Supported
 // tools: claude_code, codex, cursor, vscode, opencode. Dashboard generates

package/package.json

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

package/scripts/subscribe.mjs

@@ -23,19 +23,27 @@ const RECONNECT_BACKOFF_MS = [1000, 2000, 4000, 8000, 15_000, 30_000];
 const FRESHNESS_CHECK_INTERVAL_MS = 30_000;
 const FRESHNESS_STALE_MS = 90_000;
 
+// Short HH:MM:SS prefix so the Monitor output can be scanned at a glance.
+// Local time — Monitor's reader is always a human looking at one machine.
+function logErr(msg) {
+  const d = new Date();
+  const ts = `${String(d.getHours()).padStart(2, "0")}:${String(d.getMinutes()).padStart(2, "0")}:${String(d.getSeconds()).padStart(2, "0")}`;
+  process.stderr.write(`[${ts}] ${msg}\n`);
+}
+
 // Guarantee a terminal stderr line on any unhandled failure so the agent
 // reading Monitor's output file always sees WHY the process died.
 process.on("uncaughtException", (err) => {
-  process.stderr.write(`subscribe: fatal: uncaught: ${err?.stack || err?.message || err}\n`);
+  logErr(`subscribe: fatal: uncaught: ${err?.stack || err?.message || err}`);
   process.exit(1);
 });
 process.on("unhandledRejection", (err) => {
-  process.stderr.write(`subscribe: fatal: unhandled rejection: ${err?.stack || err?.message || err}\n`);
+  logErr(`subscribe: fatal: unhandled rejection: ${err?.stack || err?.message || err}`);
   process.exit(1);
 });
 
 function die(msg, code = 1) {
-  process.stderr.write(msg + "\n");
+  logErr(msg);
   process.exit(code);
 }
 
@@ -178,7 +186,7 @@ function removePidfile(path) {
 async function run() {
   const cwd = process.cwd();
   const { baseUrl, token } = readMcpConfig(cwd);
-  process.stderr.write(`subscribe: cwd=${cwd} server=${baseUrl}\n`);
+  logErr(`subscribe: cwd=${cwd} server=${baseUrl}`);
 
   let ticket = await fetchTicket(baseUrl, token);
   const pidfile = `/tmp/patchcord_subscribe_${ticket.namespace_ids[0]}_${ticket.agent_id}.pid`;
@@ -195,9 +203,7 @@ async function run() {
     process.exit(0);
   });
 
-  process.stderr.write(
-    `subscribe: agent=${ticket.agent_id} namespaces=${ticket.namespace_ids.join(",")}\n`
-  );
+  logErr(`subscribe: agent=${ticket.agent_id} namespaces=${ticket.namespace_ids.join(",")}`);
 
   let backoffIdx = 0;
 
@@ -210,16 +216,16 @@ async function run() {
         });
         backoffIdx = 0; // clean disconnect resets backoff
       } catch (e) {
-        process.stderr.write(`subscribe: ${e.message}\n`);
+        logErr(`subscribe: ${e.message}`);
       }
       const delay = RECONNECT_BACKOFF_MS[Math.min(backoffIdx, RECONNECT_BACKOFF_MS.length - 1)];
       backoffIdx++;
-      process.stderr.write(`subscribe: reconnecting in ${delay}ms\n`);
+      logErr(`subscribe: reconnecting in ${delay}ms`);
       await new Promise((r) => setTimeout(r, delay));
       try {
         ticket = await fetchTicket(baseUrl, token);
       } catch (e) {
-        process.stderr.write(`subscribe: ticket refresh failed: ${e.message}\n`);
+        logErr(`subscribe: ticket refresh failed: ${e.message}`);
       }
     }
   };
@@ -255,7 +261,7 @@ function runOnce(ticket, baseUrl, token, refreshTicket) {
     };
 
     ws.on("open", () => {
-      process.stderr.write("subscribe: connected\n");
+      logErr("subscribe: connected");
       for (const topic of ticket.topics) {
         ws.send(
           JSON.stringify({
@@ -277,7 +283,7 @@ function runOnce(ticket, baseUrl, token, refreshTicket) {
       // failure here just means we miss queued messages this round;
       // the next reconnect retries.
       drainQueueOnce(baseUrl, token).catch((e) => {
-        process.stderr.write(`subscribe: queue check failed: ${e.message}\n`);
+        logErr(`subscribe: queue check failed: ${e.message}`);
       });
       heartbeatTimer = setInterval(() => {
         try {
@@ -300,9 +306,7 @@ function runOnce(ticket, baseUrl, token, refreshTicket) {
       freshnessTimer = setInterval(() => {
         const stale = Date.now() - lastEventAt;
         if (stale > FRESHNESS_STALE_MS) {
-          process.stderr.write(
-            `subscribe: ws stale ${Math.round(stale / 1000)}s, forcing reconnect\n`
-          );
+          logErr(`subscribe: ws stale ${Math.round(stale / 1000)}s, forcing reconnect`);
           done(new Error(`ws stale ${Math.round(stale / 1000)}s`));
         }
       }, FRESHNESS_CHECK_INTERVAL_MS);
@@ -340,13 +344,16 @@ function runOnce(ticket, baseUrl, token, refreshTicket) {
               })
             );
           }
-          process.stderr.write("subscribe: token refreshed\n");
+          // Routine refresh success — don't log. Over days this fills the
+          // Monitor output with ~250 identical lines and buries the rare
+          // interesting events (connects, errors). Refresh failures DO log,
+          // because those are the ones worth scanning for.
           scheduleRefresh(fresh.jwt_expires_in);
         } catch (e) {
           // Transient network/server error — do NOT close the live
           // connection. The current JWT is still valid for ~2 more min
           // (JWT_REFRESH_SAFETY_MARGIN_SEC). Retry sooner.
-          process.stderr.write(`subscribe: token refresh failed, retrying in 30s: ${e.message}\n`);
+          logErr(`subscribe: token refresh failed, retrying in 30s: ${e.message}`);
           refreshTimer = setTimeout(doRefresh, 30_000);
         }
       };
@@ -384,20 +391,20 @@ function runOnce(ticket, baseUrl, token, refreshTicket) {
     });
 
     ws.on("error", (err) => {
-      process.stderr.write(`subscribe: ws error: ${err.message}\n`);
+      logErr(`subscribe: ws error: ${err.message}`);
       done(err);
     });
 
     ws.on("close", (info) => {
       const codeStr = info?.code != null ? `code=${info.code}` : "code=none";
       const reasonStr = info?.reason ? ` reason=${JSON.stringify(info.reason)}` : "";
-      process.stderr.write(`subscribe: ws closed (${codeStr}${reasonStr})\n`);
+      logErr(`subscribe: ws closed (${codeStr}${reasonStr})`);
       done();
     });
   });
 }
 
 run().catch((e) => {
-  process.stderr.write(`subscribe: fatal: ${e.message}\n`);
+  logErr(`subscribe: fatal: ${e.message}`);
   process.exit(1);
 });

package/skills/subscribe/SKILL.md

@@ -3,145 +3,54 @@ name: patchcord:subscribe
 description: >
   Start a background listener that wakes Claude the moment a new Patchcord
   message arrives for this agent. Uses Supabase Realtime over WebSocket —
-  zero polling, zero idle cost. Use when the user says "subscribe",
-  "listen for patchcord messages", "wake me when messages arrive", or runs
-  /patchcord:subscribe.
+  zero polling. Use when the user says "subscribe", "listen for patchcord
+  messages", "wake me when messages arrive", or runs /patchcord:subscribe.
 ---
 
-# What this does
-
-Spawns `scripts/subscribe.mjs` in the background. The script holds a
-WebSocket to Supabase Realtime and prints one line to stdout per new
-`agent_messages` INSERT for this agent. Claude Code's `Monitor` tool
-picks up each line as a notification; Claude wakes up and calls
-`inbox()`.
-
-No polling, no tokens burned while idle. The process stays alive until
-the user kills it or closes the Claude Code session.
-
-# How to find the script path (read carefully — this is the one thing that trips agents up)
-
-At the top of the skill invocation message, Claude Code shows a header:
-`Base directory for this skill: <ABSOLUTE_PATH>/skills/subscribe`
-
-Take that path, strip `/skills/subscribe` from the end — you now have the
-plugin root. The script is at `<PLUGIN_ROOT>/scripts/subscribe.mjs`.
-
-**Do not rely on `$CLAUDE_PLUGIN_ROOT`** — it is often unset inside
-the Bash shell even when the skill is running. Always derive the path
-from the "Base directory for this skill" header you were given.
-
-Example: if the header says
-`Base directory for this skill: /home/user/.npm/_npx/abc123/node_modules/patchcord/skills/subscribe`
-then the script is at
-`/home/user/.npm/_npx/abc123/node_modules/patchcord/scripts/subscribe.mjs`.
-
-# Starting (step by step)
-
-1. **Know your identity.** If you don't already have `namespace_id` and
-   `agent_id` from this session, call `mcp__patchcord__inbox` once — the
-   response starts with `<agent>@<namespace> | N pending` and you can
-   read both off that line.
-
-2. **Compute the pidfile path:**
-   `/tmp/patchcord_subscribe_<namespace_id>_<agent_id>.pid`
-
-3. **Check for an existing listener.** One Bash call:
-   ```bash
-   PF=/tmp/patchcord_subscribe_<ns>_<agent>.pid
-   if [ -f "$PF" ] && kill -0 "$(cat "$PF")" 2>/dev/null; then
-     echo "ALREADY_RUNNING pid=$(cat "$PF")"
-   else
-     echo "OK_TO_SPAWN"
-   fi
-   ```
-   If output is `ALREADY_RUNNING`, tell the user "Patchcord listener
-   already active (pid N)" and STOP. Do not spawn another one.
-
-4. **Resolve the script path** using the recipe above.
-
-5. **Spawn under Monitor** — not Bash with `run_in_background`. Monitor
-   is the right tool because every stdout line becomes a notification.
-   Example call shape:
-   ```
-   Monitor(
-     description: "patchcord realtime listener (<agent>@<ns>)",
-     persistent: true,
-     timeout_ms: 3600000,
-     command: "exec node \"<absolute-path-to-subscribe.mjs>\""
-   )
-   ```
-   No `2>&1`, no grep filter. By construction the script only writes
-   `PATCHCORD: ...` lines to stdout. Everything else — `connected`,
-   `token refreshed`, startup diagnostics, errors — goes to stderr,
-   which Monitor captures into its output file but does NOT fire as
-   notifications. So there's nothing to filter and no way to get the
-   filter wrong.
-
-   Crash detection is handled automatically by Monitor itself: when the
-   process exits, Monitor emits a built-in "stream ended" task
-   notification with the output file path and exit code.
-
-6. **Tell the user one short line:**
-   "Patchcord listener active — I'll pick up new messages as they arrive."
+# Start
+
+Spawn 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: "exec npx patchcord subscribe"
+)
+```
+
+`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.
+
+Then one line to the user: *"Patchcord listener active — I'll pick up new messages as they arrive."*
 
 # When a notification fires
 
-Monitor surfaces `PATCHCORD: 1 new from <sender>`. Do this:
+Monitor surfaces `PATCHCORD: 1 new from <sender>`:
 
-1. Say one brief line: "Got a Patchcord ping from <sender> — checking inbox."
+1. Say: *"Got a Patchcord ping from <sender> — checking inbox."*
 2. Call `mcp__patchcord__inbox`.
-3. For each pending message, do the work first (follow the
-   patchcord:inbox skill), then reply with what you did.
-4. Return to listening — Monitor keeps running.
+3. Do the work per the patchcord:inbox skill, reply with what you did.
 
 # Stopping
 
-There is no `/patchcord:unsubscribe` command. Tell the user either:
-
-- Close this Claude Code session, OR
-- Run `kill $(cat /tmp/patchcord_subscribe_<namespace>_<agent>.pid)` in
-  a terminal.
-
-# If the Monitor stream ends — STRICT PROTOCOL
-
-The stream-end task notification includes the path to Monitor's output
-file. Do exactly this, in this order:
-
-1. Read that output file using the Read tool.
-2. Look at the last ~15 lines for a line matching one of the known
-   failure strings below. There will always be at least one terminal
-   error line — the script's error handlers guarantee it.
-3. Report the specific cause to the user in one short sentence.
-4. STOP.
-
-**Forbidden on failure — do not do any of these:**
-- Do NOT run `pgrep`, `ps`, `kill`, `pkill`, `killall`, or any command
-  that targets PIDs or process names.
-- Do NOT modify, delete, or write to the pidfile yourself. The script
-  manages it; it's already cleaned up by the time Monitor emits the
-  stream-end event.
-- Do NOT spawn another Monitor or another `node subscribe.mjs`. One
-  failure means something is wrong with the config or environment;
-  respawning will not fix it and will make things worse.
-- Do NOT search for orphaned processes or try to "clean up" state.
-
-Concrete failure strings you may see and what they mean:
-
-- `no .mcp.json in <cwd>` — session is not in a patchcord project dir.
-  Tell the user which directory to `cd` into.
-- `ticket: token rejected (HTTP 401|403)` — bearer in `.mcp.json` is
-  bad; regenerate from the dashboard.
-- `ticket: server not configured for realtime` — the patchcord server
-  hasn't had `SUPABASE_JWT_SECRET` / `SUPABASE_ANON_KEY` set. This is
-  a cloud-only feature.
-- `ticket: namespace not owned — regenerate your token` — the token's
-  namespace lost its owner row; regenerate from the dashboard.
-- `already running (pid N)` (exit code 2) — pidfile guard tripped,
-  another listener is active. Report and stop. Do NOT kill the other
-  listener to make room.
-- `subscribe: fatal: ...` — unhandled error. Show the user the line
-  verbatim, stop.
-
-If the process exited cleanly (exit 0) with no error line, the user
-closed the session or killed the process. Nothing to do.
+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 Supabase
+- `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.
+
+**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.
+
+Clean exit (code 0) with no error line = the user closed the session or killed the process. Nothing to do.