patchcord 0.6.45 → 0.6.47

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

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

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

package/agent-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
   "name": "patchcord",
-  "version": "0.6.45",
+  "version": "0.6.47",
   "description": "Cross-machine agent messaging for Claude Code and Codex",
   "author": {
     "name": "ppravdin",

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

@@ -44,33 +44,53 @@ WAKES YOU: the pipe fills with messages you are never told about, and you
 discover them only when the user asks why you did not answer. That has happened
 in production, on jcode, and is the reason this section exists.
 
-So, if you have no `Monitor`:
+So, if you have no `Monitor`, **use `--stall-signal`. It was built for exactly
+this and it is not optional here:**
 
-1. **Set the stall wake.** Whatever your harness calls it — jcode uses
-   `stall_wake_seconds: 30` — you MUST set it. Without it the background task
-   is silent by construction and you get zero notifications, no error, and no
-   sign that anything is wrong.
+```
+patchcord subscribe --stall-signal | grep --line-buffered '^PATCHCORD:'; exit ${PIPESTATUS[0]}
+```
+
+run as a background command with your harness's stall wake set to **15
+seconds** (jcode: `stall_wake_seconds: 15`).
+
+1. **What `--stall-signal` does.** While idle it writes a `HEARTBEAT:` line
+   every 5 s, so the pipe never looks silent and the stall never fires on
+   nothing. When a real message arrives it writes the `PATCHCORD:` line and
+   then goes QUIET ON PURPOSE for 15 s, so your harness's stall detector fires
+   because a message came in. It turns wake-on-silence into wake-on-message
+   using only the primitive your harness has.
+
+   The `grep` drops the `HEARTBEAT:` lines from what you see; they still keep
+   the pipe alive, which is their whole job.
 
-2. **Understand what the wake means, and what it does not.** The stall fires
-   because the pipe went QUIET, not because a message arrived. The `grep` filter
-   in step 2 drops the 30 s heartbeats, which is exactly what makes the pipe
-   look idle — so you will be woken on a timer, whether or not anything came in.
-   Treat every wake as "go and check", never as "there is a message".
+2. **The two numbers must agree.** Your stall wake MUST equal `--stall-signal`'s
+   quiet window. Both default to 15 s, so setting `15` and passing no inline
+   value is correct. If you pass a custom triple
+   (`--stall-signal keepaliveMs:quietMs:stallMs`), your stall wake must equal
+   the `stallMs` you passed. Too short and it fires on nothing; too long and it
+   never fires on a real message. **Do not use 30** — that number predates this
+   mode and is simply wrong for it, not safer.
 
 3. **NEVER read the last `PATCHCORD:` line in the task output as news.** It is
-   scrollback. It may be the same line you already handled minutes ago. The
-   inbox is the source of truth: on each wake call `mcp__patchcord__inbox`, and
-   if it is empty, say nothing and go back to waiting. An agent that announces a
-   message because it re-read an old line is worse than one that misses it.
-
-4. **The noise is the cost of delivery, and it is the right trade.** A wake
-   every N seconds with nothing to report is cheap. A missed message is not.
-   Raise the interval if the user asks; do not remove it.
-
-This degrades push into a timed poll on those harnesses. That is honest and it
-works. Do not pretend otherwise to the user, and do not tell them you will be
-woken "as messages arrive" if your harness cannot do that — say you will check
-regularly.
+   scrollback and it may be a line you already handled. Two lines look almost
+   alike: a live arrival, and a `... waiting in inbox (snapshot at HH:MM:SS)`
+   written once when the listener connected and drained the queue. The
+   timestamp on the second is there so you can see it is old — check it. In a
+   real jcode session an agent re-announced that same drain line repeatedly and
+   missed five actual messages while doing so. On every wake call
+   `mcp__patchcord__inbox` and believe only that. If it is empty, say nothing
+   and go back to waiting.
+
+4. **If the inbox is empty, check the listener is still alive** before assuming
+   a harmless false wake. A dead listener produces the same silence. If a
+   restart is refused with `already running (pid N)`, the process outlived the
+   task that tracked it: restart with `--replace`, which is the only sanctioned
+   way to remove a running listener. Never `kill`/`pkill` by hand.
+
+**Only if your harness has no stall setting at all** does this degrade to a
+timed poll. Say so plainly to the user in that case — tell them you will check
+regularly, never that you will be woken "as messages arrive".
 
 # When a notification fires
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "patchcord",
-  "version": "0.6.45",
+  "version": "0.6.47",
   "description": "Cross-machine agent messaging for Claude Code and Codex",
   "scripts": {
     "version": "node scripts/sync-plugin-version.mjs && git add .claude-plugin/plugin.json agent-plugin/plugin.json"

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

@@ -72,6 +72,29 @@ cannot tell which one happened from the wake alone:
    produces silence — that is a feature (it is how you notice), but only if
    you actually look. If the background task has exited, restart it with the
    command in Start, step 2.
+
+   **If the restart is refused with `already running (pid N)`, add
+   `--replace`.** That message means a listener process is alive while your
+   background task is not tracking it — which is the worst state available
+   here, because it receives messages and can no longer wake you, and it
+   holds the pidfile that refuses the correct respawn. It happens when a
+   cancel is rejected as stale and the process outlives the task that owned
+   it.
+
+   ```
+   Bash(
+     command: "patchcord subscribe --replace --stall-signal | grep --line-buffered '^PATCHCORD:'; exit ${PIPESTATUS[0]}",
+     run_in_background: true,
+     stall_wake_seconds: 15
+   )
+   ```
+
+   `--replace` terminates the pidfile's holder and takes over. It signals only
+   a pid read from patchcord's own pidfile, and only after confirming that pid
+   is a patchcord listener — a reused pid belonging to something else is left
+   alone and the file is treated as stale. This is the ONLY sanctioned way to
+   remove a running listener. Do not reach for `kill`, `pkill`, or the pidfile
+   yourself.
 3. **Never read the last `PATCHCORD:` line in the task output as news.** It
    is scrollback — output already displayed. It may be the same line you
    already handled. The inbox call in step 1 is the source of truth; a
@@ -96,7 +119,8 @@ Read its output. Scan for one of:
 - `ticket: token rejected (HTTP 401|403)` — the bearer token is invalid or
   expired.
 - `already running (pid N)` (exit 2) — another listener is active for this
-  agent; report it, do not respawn.
+  agent. Do not respawn it unchanged, and do not kill it by hand: restart with
+  `--replace` as described above.
 - `subscribe: fatal: ...` — report the fatal line verbatim.
 
 If none of those appear, it likely ended with the session or because its

package/scripts/lib/pidfile.mjs

@@ -0,0 +1,63 @@
+// Pidfile takeover for `patchcord subscribe --replace`.
+//
+// WHY THIS EXISTS
+//
+// A running listener is not the problem; being UNABLE TO REPLACE IT is. On a
+// harness whose background-task tracking can be lost - jcode, where a restart
+// whose cancel is rejected as stale leaves the process alive but no longer
+// attached to a stall wake - the listener keeps receiving and can no longer
+// wake anybody. Because it still holds the pidfile, the correct respawn is
+// then refused with `already running`. The agent is stuck between a guard
+// doing its job and a skill that forbids reaching for kill.
+//
+// So the recovery is a flag rather than instructions a model may not follow.
+//
+// THE SAFETY BOUNDARY, which is the whole reason this is a separate module
+// with its own tests: this only ever signals a pid READ FROM OUR OWN PIDFILE
+// PATH, and only after confirming that pid is one of ours. PIDs are reused. A
+// file left behind by a crashed listener can name a process that now belongs
+// to somebody else, and killing it because a stale file pointed there would
+// be far worse than the stuck state this fixes. When identity cannot be
+// established the file is treated as stale and taken over WITHOUT signalling
+// anything.
+//
+// Kept out of subscribe.mjs so the decision can be unit tested without
+// opening a WebSocket, resolving a project config, or touching a real
+// pidfile - all things subscribe.mjs does as soon as it runs.
+
+import { readFileSync } from "node:fs";
+
+/** Is `pid` one of our own subscribe processes? Reads the kernel's own record
+ *  of the command line rather than trusting the pidfile's existence.
+ *
+ *  Returns false whenever that cannot be established - a process we cannot
+ *  read, a platform without /proc, a command line that does not look like
+ *  ours. False means "do not signal it", so every uncertain case is safe by
+ *  construction rather than by the caller remembering to check. */
+export function isOurSubscribeProcess(pid, deps = {}) {
+  const read = deps.readFile || ((p) => readFileSync(p, "utf8"));
+  try {
+    const cmdline = String(read(`/proc/${pid}/cmdline`)).replace(/\0/g, " ");
+    return /subscribe\.mjs/.test(cmdline) || /patchcord[^ ]* subscribe/.test(cmdline);
+  } catch (_) {
+    return false;
+  }
+}
+
+/** Decide what --replace should do about an existing pidfile holder.
+ *
+ *  Pure: takes facts, returns one of three verdicts, signals nothing itself.
+ *  The caller performs the action. This split is what lets the dangerous
+ *  case - "live pid that is not ours" - be tested without a real kill.
+ *
+ *    "start"      nothing is holding it; just start
+ *    "takeover"   the file is stale or names a foreign process; take the
+ *                 file, signal NOTHING
+ *    "terminate"  a live listener of ours; terminate it, then take the file
+ */
+export function decidePidfileAction({ existingPid, selfPid, isAlive, isOurs }) {
+  if (!existingPid || existingPid === selfPid) return "start";
+  if (!isAlive) return "takeover";
+  if (!isOurs) return "takeover";
+  return "terminate";
+}

package/scripts/subscribe.mjs

@@ -12,9 +12,11 @@ import { request as httpsRequest } from "node:https";
 import { request as httpRequest } from "node:http";
 import { URL } from "node:url";
 import { dirname } from "node:path";
+import { execSync } from "node:child_process";
 import { connect as wsConnect } from "./lib/ws.mjs";
 import { resolveProjectBearer, listProjectBearers } from "./lib/resolve-project-bearer.mjs";
 import { parseStallSignalArg } from "./lib/stall-signal.mjs";
+import { isOurSubscribeProcess, decidePidfileAction } from "./lib/pidfile.mjs";
 
 // --- Hermes webhook bridge mode -------------------------------------------
 // Default mode writes "PATCHCORD: ..." lines to stdout for Claude Code's
@@ -293,7 +295,20 @@ async function drainQueueOnce(baseUrl, token) {
         count = JSON.parse(res.body).pending_count ?? 0;
       } catch (_) {}
       if (count > 0) {
-        await notify(`PATCHCORD: ${count} waiting in inbox`, { count, kind: "pending" });
+        // SELF-DATING, DELIBERATELY. This line and a live-arrival line both
+        // start with "PATCHCORD:" and both stay in the task output forever.
+        // On a harness that wakes on a stall, the agent re-reads the tail of
+        // that output on every wake, and an undated snapshot from twenty
+        // minutes ago is indistinguishable from a message that just landed -
+        // reported in a jcode session where five real messages were missed
+        // while the same old line was announced repeatedly as news.
+        // The clock is what makes a re-read visibly stale.
+        const at = new Date().toTimeString().slice(0, 8);
+        await notify(`PATCHCORD: ${count} waiting in inbox (snapshot at ${at})`, {
+          count,
+          kind: "pending",
+          at,
+        });
       }
       return;
     } catch (e) {
@@ -310,6 +325,56 @@ async function drainQueueOnce(baseUrl, token) {
   throw lastErr;
 }
 
+// --replace: the running listener is not the problem, being UNABLE TO REPLACE
+// IT is. On a harness whose background-task tracking can be lost (jcode: a
+// restart whose cancel was rejected as stale leaves the process alive but no
+// longer attached to a stall wake), the listener keeps receiving and can no
+// longer wake anybody — and because it still holds the pidfile, the correct
+// respawn is refused with `already running`. The agent is then stuck between
+// a guard doing its job and a skill that forbids reaching for kill.
+//
+// So the recovery is a flag rather than instructions: `patchcord subscribe
+// --replace` terminates the pidfile's holder and takes over.
+//
+// IT ONLY EVER SIGNALS A PID READ FROM OUR OWN PIDFILE PATH, and only after
+// confirming that pid is one of ours. PIDs are reused: a file left by a
+// crashed listener can name a process that now belongs to somebody else, and
+// killing it because a stale file pointed there would be far worse than the
+// stuck state this fixes. When the identity cannot be confirmed the file is
+// treated as stale and taken over WITHOUT signalling anything.
+const REPLACE_MODE = process.argv.includes("--replace");
+
+/** SIGTERM, then SIGKILL if it is still there. Returns true once the pid is
+ *  gone. Bounded: it must not hang a listener start forever. */
+function terminateAndWait(pid, deadlineMs = 3000) {
+  const isGone = () => {
+    try {
+      process.kill(pid, 0);
+      return false;
+    } catch (_) {
+      return true;
+    }
+  };
+  try {
+    process.kill(pid, "SIGTERM");
+  } catch (_) {
+    return true;
+  }
+  const started = Date.now();
+  while (Date.now() - started < deadlineMs) {
+    if (isGone()) return true;
+    try {
+      // Busy-wait deliberately: this runs once, before the socket opens, and
+      // an async sleep here would let the rest of startup race the takeover.
+      execSync("sleep 0.1");
+    } catch (_) {}
+  }
+  try {
+    process.kill(pid, "SIGKILL");
+  } catch (_) {}
+  return isGone();
+}
+
 function writePidfile(path) {
   try {
     writeFileSync(path, String(process.pid), { flag: "wx" });
@@ -321,7 +386,29 @@ function writePidfile(path) {
         if (existingPid && existingPid !== process.pid) {
           try {
             process.kill(existingPid, 0);
-            die(`already running (pid ${existingPid})`, 2);
+            if (REPLACE_MODE) {
+              const action = decidePidfileAction({
+                existingPid,
+                selfPid: process.pid,
+                isAlive: true,
+                isOurs: isOurSubscribeProcess(existingPid),
+              });
+              if (action === "takeover") {
+                // A live pid that is NOT ours means the file is stale and the
+                // number was reused. Take the file; signal nothing.
+                logErr(`subscribe: --replace: pid ${existingPid} is not a patchcord listener — treating the pidfile as stale`);
+              } else if (terminateAndWait(existingPid)) {
+                logErr(`subscribe: --replace: terminated the previous listener (pid ${existingPid})`);
+              } else {
+                die(`--replace: could not terminate the previous listener (pid ${existingPid})`, 2);
+              }
+              try {
+                unlinkSync(path);
+              } catch (_) {}
+              writeFileSync(path, String(process.pid), { flag: "wx" });
+              return;
+            }
+            die(`already running (pid ${existingPid}) — use \`patchcord subscribe --replace\` to take over`, 2);
           } catch (_) {
             // stale
             try {

package/skills/subscribe/SKILL.md

@@ -44,33 +44,53 @@ WAKES YOU: the pipe fills with messages you are never told about, and you
 discover them only when the user asks why you did not answer. That has happened
 in production, on jcode, and is the reason this section exists.
 
-So, if you have no `Monitor`:
+So, if you have no `Monitor`, **use `--stall-signal`. It was built for exactly
+this and it is not optional here:**
 
-1. **Set the stall wake.** Whatever your harness calls it — jcode uses
-   `stall_wake_seconds: 30` — you MUST set it. Without it the background task
-   is silent by construction and you get zero notifications, no error, and no
-   sign that anything is wrong.
+```
+patchcord subscribe --stall-signal | grep --line-buffered '^PATCHCORD:'; exit ${PIPESTATUS[0]}
+```
+
+run as a background command with your harness's stall wake set to **15
+seconds** (jcode: `stall_wake_seconds: 15`).
+
+1. **What `--stall-signal` does.** While idle it writes a `HEARTBEAT:` line
+   every 5 s, so the pipe never looks silent and the stall never fires on
+   nothing. When a real message arrives it writes the `PATCHCORD:` line and
+   then goes QUIET ON PURPOSE for 15 s, so your harness's stall detector fires
+   because a message came in. It turns wake-on-silence into wake-on-message
+   using only the primitive your harness has.
+
+   The `grep` drops the `HEARTBEAT:` lines from what you see; they still keep
+   the pipe alive, which is their whole job.
 
-2. **Understand what the wake means, and what it does not.** The stall fires
-   because the pipe went QUIET, not because a message arrived. The `grep` filter
-   in step 2 drops the 30 s heartbeats, which is exactly what makes the pipe
-   look idle — so you will be woken on a timer, whether or not anything came in.
-   Treat every wake as "go and check", never as "there is a message".
+2. **The two numbers must agree.** Your stall wake MUST equal `--stall-signal`'s
+   quiet window. Both default to 15 s, so setting `15` and passing no inline
+   value is correct. If you pass a custom triple
+   (`--stall-signal keepaliveMs:quietMs:stallMs`), your stall wake must equal
+   the `stallMs` you passed. Too short and it fires on nothing; too long and it
+   never fires on a real message. **Do not use 30** — that number predates this
+   mode and is simply wrong for it, not safer.
 
 3. **NEVER read the last `PATCHCORD:` line in the task output as news.** It is
-   scrollback. It may be the same line you already handled minutes ago. The
-   inbox is the source of truth: on each wake call `mcp__patchcord__inbox`, and
-   if it is empty, say nothing and go back to waiting. An agent that announces a
-   message because it re-read an old line is worse than one that misses it.
-
-4. **The noise is the cost of delivery, and it is the right trade.** A wake
-   every N seconds with nothing to report is cheap. A missed message is not.
-   Raise the interval if the user asks; do not remove it.
-
-This degrades push into a timed poll on those harnesses. That is honest and it
-works. Do not pretend otherwise to the user, and do not tell them you will be
-woken "as messages arrive" if your harness cannot do that — say you will check
-regularly.
+   scrollback and it may be a line you already handled. Two lines look almost
+   alike: a live arrival, and a `... waiting in inbox (snapshot at HH:MM:SS)`
+   written once when the listener connected and drained the queue. The
+   timestamp on the second is there so you can see it is old — check it. In a
+   real jcode session an agent re-announced that same drain line repeatedly and
+   missed five actual messages while doing so. On every wake call
+   `mcp__patchcord__inbox` and believe only that. If it is empty, say nothing
+   and go back to waiting.
+
+4. **If the inbox is empty, check the listener is still alive** before assuming
+   a harmless false wake. A dead listener produces the same silence. If a
+   restart is refused with `already running (pid N)`, the process outlived the
+   task that tracked it: restart with `--replace`, which is the only sanctioned
+   way to remove a running listener. Never `kill`/`pkill` by hand.
+
+**Only if your harness has no stall setting at all** does this degrade to a
+timed poll. Say so plainly to the user in that case — tell them you will check
+regularly, never that you will be woken "as messages arrive".
 
 # When a notification fires