patchcord 0.6.45 → 0.6.46

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.46",
   "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.46",
   "description": "Cross-machine agent messaging for Claude Code and Codex",
   "author": {
     "name": "ppravdin",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "patchcord",
-  "version": "0.6.45",
+  "version": "0.6.46",
   "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
@@ -310,6 +312,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 +373,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 {