patchcord 0.6.44 → 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.44",
+  "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.44",
+  "version": "0.6.46",
   "description": "Cross-machine agent messaging for Claude Code and Codex",
   "author": {
     "name": "ppravdin",

package/harnesses.json

@@ -25,7 +25,9 @@
   "harnesses": [
     {
       "id": "claude_code",
-      "aliases": ["claude"],
+      "aliases": [
+        "claude"
+      ],
       "cli": "claude",
       "kind": "terminal",
       "installer_scope": "project",
@@ -75,7 +77,10 @@
     },
     {
       "id": "grok",
-      "aliases": ["grok_cli", "grok_build"],
+      "aliases": [
+        "grok_cli",
+        "grok_build"
+      ],
       "cli": "grok",
       "kind": "terminal",
       "installer_scope": "project",
@@ -130,9 +135,9 @@
       "cli": "hermes",
       "kind": "terminal",
       "installer_scope": "env-directed",
-      "installer_config": "$HERMES_HOME/config.yaml if set, else the output of `hermes config path` if the binary resolves, else ~/.hermes/config.yaml",
+      "installer_config": "$HERMES_HOME/config.yaml if set, else the output of `hermes config path` if the binary resolves (which reflects the ambient profile), else ~/.hermes/config.yaml",
       "harness_scope": "per-profile-or-per-home",
-      "installer_defect": "WAS: the path was hardcoded to ~/.hermes/config.yaml. The installer never called `hermes config path` and did not know profiles exist, so installing while a non-default profile was active wrote the DEFAULT profile's config — the wrong file, silently. FIXED (scripts/lib/hermes-home.mjs, resolveHermesHome/resolveHermesConfigPath/resolveHermesSkillsDest, all three deriving from the same resolved home): HERMES_HOME from the environment, else a shelled `hermes config path` (which itself honours HERMES_HOME — the child inherits the environment), else the unchanged ~/.hermes fallback. Applies to config.yaml AND to where Hermes skills install (~/.hermes/skills/integrations was hardcoded in three more places, unaware of HERMES_HOME — a seat isolated by home for identity but not for skills is not isolated: skills are a guard, not documentation). mux measured two independent isolation mechanisms this way — HERMES_HOME and -p/--profile, both real, both giving a separate mcp_servers AND a separate .env — which is why harness_scope reads per-profile-or-per-home rather than per-profile alone. installer_scope changed from 'global' to 'env-directed' for the same reason: our installer's write target is no longer a fixed machine-wide path, it is wherever HERMES_HOME points when mux sets it, falling back to global only when nothing directs it. PROFILE SUPPORT DELIBERATELY NOT BUILT: -p/--profile is a second, separate isolation axis this installer does not resolve, understand, or accept a flag for. Whether `hermes config path`'s output already reflects an ambient active profile (e.g. via an env var hermes itself reads) is unknown without reading Hermes's own source or an install to test against — neither available here. If a user runs Hermes under a non-default profile without ALSO setting HERMES_HOME to match, this installer's write may land in a config that profile-launched Hermes never reads — the same silent-wrong-file failure this whole fix exists to close, just on the axis we chose not to resolve. Not yet released or observed end to end; version not bumped.",
+      "installer_defect": "WAS: the path was hardcoded to ~/.hermes/config.yaml. The installer never called `hermes config path` and did not know profiles exist, so installing while a non-default profile was active wrote the DEFAULT profile's config — the wrong file, silently. FIXED (scripts/lib/hermes-home.mjs, resolveHermesHome/resolveHermesConfigPath/resolveHermesSkillsDest, all three deriving from the same resolved home): HERMES_HOME from the environment, else a shelled `hermes config path` (which itself honours HERMES_HOME — the child inherits the environment), else the unchanged ~/.hermes fallback. Applies to config.yaml AND to where Hermes skills install (~/.hermes/skills/integrations was hardcoded in three more places, unaware of HERMES_HOME — a seat isolated by home for identity but not for skills is not isolated: skills are a guard, not documentation). mux measured two independent isolation mechanisms this way — HERMES_HOME and -p/--profile, both real, both giving a separate mcp_servers AND a separate .env — which is why harness_scope reads per-profile-or-per-home rather than per-profile alone. installer_scope changed from 'global' to 'env-directed' for the same reason: our installer's write target is no longer a fixed machine-wide path, it is wherever HERMES_HOME points when mux sets it, falling back to global only when nothing directs it. PROFILE AXIS: COVERED, AND MEASURED RATHER THAN CLAIMED. This entry previously said profile support was deliberately not built, and that a user on a non-default -p/--profile without a matching HERMES_HOME would still get the silent-wrong-file failure. That was WRONG and lead@mux-v2 disproved it on a real Hermes install (boca, 2026-08-20): `hermes profile use sticky1` then `hermes config path` answers $HERMES_HOME/profiles/sticky1/config.yaml. The shelled resolver therefore honours the ambient profile by construction, because Hermes resolves it, not us. The same measurement confirmed the output is a FILE path, so dirname() in resolveHermesHome is correct. Resolution order in full: HERMES_HOME set (a mux seat) uses it directly and the profile is correctly ignored; HERMES_HOME unset with a profile active gets the profile's config; no hermes binary falls back to ~/.hermes, and a host with no hermes has no hermes seat. Under a sticky profile skills land at .../profiles/<name>/skills/integrations - profile-local skills beside profile-local config, which is the intent. Shipped in 0.6.44.",
       "listener": {
         "wake": "realtime",
         "mechanism": "webhook-bridge",
@@ -146,7 +151,9 @@
     },
     {
       "id": "antigravity",
-      "aliases": ["agy"],
+      "aliases": [
+        "agy"
+      ],
       "cli": "antigravity",
       "kind": "terminal",
       "installer_scope": "project",
@@ -186,7 +193,13 @@
       "installer_scope": "global",
       "installer_config": "~/.codeium/windsurf/mcp_config.json",
       "harness_scope": "unknown",
-      "listener": { "wake": "none", "mechanism": null, "self_arm": false, "survives_wake": null, "evidence": "declared" }
+      "listener": {
+        "wake": "none",
+        "mechanism": null,
+        "self_arm": false,
+        "survives_wake": null,
+        "evidence": "declared"
+      }
     },
     {
       "id": "vscode",
@@ -196,7 +209,13 @@
       "installer_scope": "project",
       "installer_config": ".vscode/mcp.json",
       "harness_scope": "unknown",
-      "listener": { "wake": "none", "mechanism": null, "self_arm": false, "survives_wake": null, "evidence": "declared" }
+      "listener": {
+        "wake": "none",
+        "mechanism": null,
+        "self_arm": false,
+        "survives_wake": null,
+        "evidence": "declared"
+      }
     },
     {
       "id": "zed",
@@ -206,7 +225,13 @@
       "installer_scope": "global",
       "installer_config": "~/.config/zed/settings.json",
       "harness_scope": "unknown",
-      "listener": { "wake": "none", "mechanism": null, "self_arm": false, "survives_wake": null, "evidence": "declared" }
+      "listener": {
+        "wake": "none",
+        "mechanism": null,
+        "self_arm": false,
+        "survives_wake": null,
+        "evidence": "declared"
+      }
     },
     {
       "id": "cline",
@@ -216,7 +241,13 @@
       "installer_scope": "global",
       "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" }
+      "listener": {
+        "wake": "none",
+        "mechanism": null,
+        "self_arm": false,
+        "survives_wake": null,
+        "evidence": "declared"
+      }
     },
     {
       "id": "jcode",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "patchcord",
-  "version": "0.6.44",
+  "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/hermes-home.mjs

@@ -48,28 +48,36 @@
 // SAME resolved home (resolveHermesHome), never computed independently —
 // the two must never be able to disagree about which home they mean.
 //
-// NOT VERIFIED END TO END: no Hermes install on this machine to observe
-// `hermes config path`'s actual output shape. Assumed to print the config
-// FILE path directly (its name is "config path", not "profile path" or
-// "home"), so step 2 takes dirname() of it as the home rather than
-// assuming a directory was printed. If that assumption is wrong, the whole
-// chain (config.yaml AND skills) is wrong together under step 2 rather
-// than disagreeing with each other — a shared, nameable failure mode
-// instead of a silent split.
+// VERIFIED, ON A REAL INSTALL. lead@mux-v2 measured both open questions on
+// boca (hermes installed, 2026-08-20) and answered them:
 //
-// PROFILES (-p/--profile) ARE DELIBERATELY NOT SUPPORTED HERE. mux measured
-// that Hermes parses -p/--profile even though --help does not list it, and
-// that each profile gets its own config.yaml AND its own .env — a second,
-// separate isolation mechanism from HERMES_HOME. This module resolves
-// HERMES_HOME only. No --hermes-profile flag exists, and none is planned
-// without first reading Hermes's own source or testing against a real
-// install to learn whether `hermes config path`'s output already reflects
-// an ambient active profile — neither is available here, so the honest
-// choice was not to guess. CONSEQUENCE A USER MUST KNOW: running Hermes
-// under a non-default profile without ALSO setting HERMES_HOME to match
-// means this installer's write may land in a config that profile-launched
-// Hermes never reads — the exact silent-wrong-file failure the rest of this
-// module exists to close, just on the axis this module does not resolve.
+//   $ hermes config path
+//   /home/p/.hermes/config.yaml           <- a FILE path, so dirname() is right
+//
+//   $ hermes profile use sticky1          <- sets the ambient sticky profile
+//   $ hermes config path
+//   $HERMES_HOME/profiles/sticky1/config.yaml   <- the PROFILE is honoured
+//
+// PROFILES (-p/--profile) ARE COVERED, BY CONSTRUCTION RATHER THAN BY CODE.
+// This comment previously said the opposite: that profiles were a second
+// isolation axis this module does not resolve, and that a user on a
+// non-default profile without a matching HERMES_HOME would still get the
+// silent-wrong-file failure. That was wrong. Hermes resolves the ambient
+// profile itself, and step 2 shells Hermes, so the answer arrives already
+// correct. The decision NOT to model Hermes's resolution and to ask the
+// binary instead is what covers an axis nobody wrote code for.
+//
+// Resolution order, in full:
+//   HERMES_HOME set (a mux seat)   -> used directly; the profile is correctly
+//                                     ignored, because the seat's home wins
+//   HERMES_HOME unset, profile on  -> `hermes config path` answers with the
+//                                     profile's own config
+//   no hermes binary               -> ~/.hermes, and a host without hermes
+//                                     has no hermes seat to get wrong
+//
+// One consequence to keep rather than fix: under a sticky profile, dirname()
+// puts skills at .../profiles/<name>/skills/integrations. Profile-local
+// skills beside profile-local config is coherent, and it is what we want.
 
 import { execSync } from "node:child_process";
 import { join, dirname } from "node:path";

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 {