patchcord 0.6.43 → 0.6.44

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

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

@@ -1,6 +1,6 @@
 {
   "name": "patchcord",
-  "version": "0.6.40",
+  "version": "0.6.43",
   "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.43",
+  "version": "0.6.44",
   "description": "Cross-machine agent messaging for Claude Code and Codex",
   "author": {
     "name": "ppravdin",

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

@@ -30,6 +30,48 @@ User invoked /patchcord:subscribe — do NOT substitute `wait_for_message()`. Sp
 
 3. **Tell the user one line:** *"Patchcord listener active — I'll pick up new messages as they arrive."*
 
+# IF YOUR HARNESS HAS NO `Monitor` TOOL — READ THIS BEFORE STEP 2
+
+`Monitor` is a Claude Code tool. Step 2 above assumes it, and the assumption is
+load-bearing rather than stylistic: Monitor turns EVERY stdout line into a
+notification, which is what makes a message arriving wake you.
+
+Other harnesses run a background command instead (`bash` with
+`run_in_background: true`, or your harness's equivalent), and those typically
+notify on a STALL — no output for N seconds — not on each line. On such a
+harness, following step 2 verbatim produces a listener that WORKS and NEVER
+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`:
+
+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.
+
+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".
+
+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.
+
 # When a notification fires
 
 Monitor surfaces `PATCHCORD: 1 new from <sender>`:

package/bin/patchcord.mjs

@@ -13,6 +13,7 @@ const __dirname = dirname(fileURLToPath(import.meta.url));
 const pluginRoot = join(__dirname, "..");
 import { resolveProjectBearer, harnessContext } from "../scripts/lib/resolve-project-bearer.mjs";
 import { detectClaudeLocalMcpOverride } from "../scripts/lib/claude-local-mcp.mjs";
+import { resolveHermesConfigPath, resolveHermesSkillsDest } from "../scripts/lib/hermes-home.mjs";
 const cmd = process.argv[2];
 
 /** Write a file then chmod 0600 (token-bearing configs must not be group/world readable). */
@@ -643,7 +644,7 @@ async function _resolveBearer(options = {}) {
     () => readJsonAt(join(HOME, ".gemini", "settings.json"), ["mcpServers", "patchcord"], "gemini"),
     () => readJsonAt(zedPath, ["context_servers", "patchcord"], "zed"),
     () => readJsonAt(join(HOME, ".openclaw", "openclaw.json"), ["mcp", "servers", "patchcord"], "openclaw"),
-    () => readHermesShape(join(HOME, ".hermes", "config.yaml")),
+    () => readHermesShape(resolveHermesConfigPath()),
     ...clinePaths.map((p) => () => readJsonAt(p, ["mcpServers", "patchcord"], "cline")),
   ];
   const globalCandidates = defaultGlobalCandidates;
@@ -1556,7 +1557,7 @@ if (cmd === "login" || cmd === "orchestrator" || cmd === "teamlead" || cmd === "
       // prints. NOT VERIFIED END TO END from here: no jcode on this machine,
       // and proving it needs a live token against the real endpoint.
       const jdir = join(dir, ".jcode"); mkdirSync(jdir, { recursive: true });
-      return writeJson(join(jdir, "mcp.json"), (o) => {
+      const jcodeWritten = writeJson(join(jdir, "mcp.json"), (o) => {
         o.mcpServers = o.mcpServers || {};
         // No `type` key at all. jcode infers stdio from the presence of
         // `command`, and writing "type": "stdio" is one more string to get
@@ -1573,16 +1574,54 @@ if (cmd === "login" || cmd === "orchestrator" || cmd === "teamlead" || cmd === "
           ],
         };
       });
+      // THE SKILL IS A GUARD, NOT DOCUMENTATION, AND THIS IS THE HARNESS THAT
+      // PROVED WHY. jcode inherits Claude Code's plugin skills today, which
+      // say "spawn the listener under Monitor" — jcode has no Monitor, so
+      // that instruction produces a listener that connects, receives, and
+      // never wakes the agent. Observed in production: two messages sat
+      // unread behind a healthy-looking listener. Without jcode's own
+      // subscribe skill telling it to use `--stall-signal` + a bash
+      // background task instead, every jcode agent silently inherits the
+      // wrong instructions for its own harness.
+      //
+      // GLOBAL, NOT per-project (Pavel's ruling: "we dont need per project
+      // skills, only per project MCP settings needed") — mirrors the hermes
+      // branch above, not the antigravity one. `.jcode/mcp.json` stays
+      // per-project (every project = one namespace = one agent identity);
+      // skills are per machine, installed once, and MUST NOT contain
+      // anything project-specific as a result — no namespace, no agent name,
+      // no path baked in below.
+      //
+      // Destination is FLAT under ~/.jcode/skills/<name>/, not nested under
+      // an "integrations" folder like hermes — jcode's own loader
+      // (crates/jcode-app-core/src/tool/skill.rs) reads
+      // ~/.jcode/skills/<skill-name>/SKILL.md directly, verified from source,
+      // not the hermes shape.
+      try {
+        const jcodeSkillsSrc = join(pluginRoot, "per-project-skills", "jcode");
+        if (existsSync(jcodeSkillsSrc)) {
+          const jcodeSkillsDest = join(HOME, ".jcode", "skills");
+          for (const name of ["inbox", "subscribe", "wait"]) {
+            const from = join(jcodeSkillsSrc, name, "SKILL.md");
+            if (!existsSync(from)) continue;
+            const to = join(jcodeSkillsDest, name);
+            mkdirSync(to, { recursive: true });
+            cpSync(from, join(to, "SKILL.md"));
+          }
+        }
+      } catch {}
+      return jcodeWritten;
     }
     if (tool === "hermes") {
-      // Hermes reads MCP servers ONLY from its GLOBAL ~/.hermes/config.yaml
-      // (mcp_servers key) — it ignores a project-local .mcp.json. So unlike the
-      // other tools we cannot write into `dir`; we upsert the global config,
-      // mirroring the `npx patchcord` installer's Hermes path. NOTE: global =
-      // one patchcord identity per machine, so provisioning a second hermes
-      // worker in another namespace overwrites the first's token. Single-hermes
-      // teams only until Hermes gains project-scoped MCP config.
-      const hermesPath = join(HOME, ".hermes", "config.yaml");
+      // Hermes reads MCP servers ONLY from its GLOBAL config.yaml (mcp_servers
+      // key) — it ignores a project-local .mcp.json. So unlike the other tools
+      // we cannot write into `dir`; we upsert the global config, mirroring the
+      // `npx patchcord` installer's Hermes path. NOTE: "global" here means one
+      // patchcord identity per Hermes HOME, so provisioning a second hermes
+      // worker under the SAME home overwrites the first's token. Isolated by
+      // HERMES_HOME (see resolveHermesConfigPath) or by -p profile — either
+      // gives a separate home, and therefore a separate identity.
+      const hermesPath = resolveHermesConfigPath();
       mkdirSync(dirname(hermesPath), { recursive: true });
       let existingYaml = "";
       try { existingYaml = existsSync(hermesPath) ? readFileSync(hermesPath, "utf-8") : ""; } catch {}
@@ -1592,7 +1631,7 @@ if (cmd === "login" || cmd === "orchestrator" || cmd === "teamlead" || cmd === "
       try {
         const hermesSkillsSrc = join(pluginRoot, "per-project-skills", "hermes");
         if (existsSync(hermesSkillsSrc)) {
-          const hermesSkillsDest = join(HOME, ".hermes", "skills", "integrations");
+          const hermesSkillsDest = resolveHermesSkillsDest();
           mkdirSync(hermesSkillsDest, { recursive: true });
           cpSync(hermesSkillsSrc, hermesSkillsDest, { recursive: true });
         }
@@ -2989,11 +3028,14 @@ if (!cmd || cmd === "install" || cmd === "agent" || cmd?.startsWith("--")) {
 
   // Hermes — refresh patchcord skills to the current version on every run, so
   // skill fixes land via `patchcord update` (the interactive choice 13 only
-  // installs them once). ~/.hermes/skills is Hermes-only, so no leak risk; only
-  // refresh when the integrations dir already exists (Hermes was set up before).
+  // installs them once). Hermes's own skills dir is not shared with any
+  // other tool's config, so no leak risk; only refresh when the integrations
+  // dir already exists (Hermes was set up before) — resolved through the
+  // SAME home as config.yaml, so this refresh touches the seat's own skills
+  // under HERMES_HOME, not the operator's global ones.
   {
     const hermesSkillsSrc = join(pluginRoot, "per-project-skills", "hermes");
-    const hermesSkillsDest = join(HOME, ".hermes", "skills", "integrations");
+    const hermesSkillsDest = resolveHermesSkillsDest();
     if (existsSync(hermesSkillsDest) && existsSync(hermesSkillsSrc)) {
       let hermesChanged = false;
       for (const name of readdirSync(hermesSkillsSrc)) {
@@ -3762,9 +3804,34 @@ if (!cmd || cmd === "install" || cmd === "agent" || cmd?.startsWith("--")) {
     } catch (e) {
       console.log(`\n  ${yellow}⚠ Failed to write ${jcodePath}: ${e.message}${r}`);
     }
+    // Install jcode skills to ~/.jcode/skills/<name>/ — GLOBAL, once per
+    // machine, not per project (Pavel's ruling: "we dont need per project
+    // skills, only per project MCP settings needed"). See the
+    // writeWorkerConfig branch above for the full guard-not-documentation
+    // reasoning and why the destination is flat, not nested under
+    // "integrations" the way hermes's is.
+    try {
+      const jcodeSkillsSrc = join(pluginRoot, "per-project-skills", "jcode");
+      if (existsSync(jcodeSkillsSrc)) {
+        const jcodeSkillsDest = join(HOME, ".jcode", "skills");
+        for (const name of ["inbox", "subscribe", "wait"]) {
+          const from = join(jcodeSkillsSrc, name, "SKILL.md");
+          if (!existsSync(from)) continue;
+          const to = join(jcodeSkillsDest, name);
+          mkdirSync(to, { recursive: true });
+          cpSync(from, join(to, "SKILL.md"));
+        }
+        console.log(`  ${green}✓${r} jcode skills installed: ${dim}${jcodeSkillsDest}${r}`);
+      }
+    } catch {}
   } else if (isHermes) {
-    // Hermes: global only (~/.hermes/config.yaml, YAML, mcp_servers key)
-    const hermesPath = join(HOME, ".hermes", "config.yaml");
+    // Hermes: global-per-home only (config.yaml, YAML, mcp_servers key). Same
+    // HERMES_HOME / `hermes config path` / ~/.hermes resolution as the
+    // writeWorkerConfig branch above — see resolveHermesConfigPath. Both
+    // write sites and the bearer-resolution read site must agree, or a seat
+    // provisioned here writes to one file while `patchcord whoami` verifies
+    // against another.
+    const hermesPath = resolveHermesConfigPath();
     mkdirSync(dirname(hermesPath), { recursive: true });
     let existingYaml = "";
     try { existingYaml = existsSync(hermesPath) ? readFileSync(hermesPath, "utf-8") : ""; } catch {}
@@ -3775,11 +3842,12 @@ if (!cmd || cmd === "install" || cmd === "agent" || cmd?.startsWith("--")) {
     } catch (e) {
       console.log(`\n  ${yellow}⚠ Failed to write ${hermesPath}: ${e.message}${r}`);
     }
-    // Install Hermes skills to ~/.hermes/skills/integrations/
+    // Install Hermes skills under the resolved home's skills/integrations/
+    // (same home as config.yaml — see resolveHermesSkillsDest).
     try {
       const hermesSkillsSrc = join(pluginRoot, "per-project-skills", "hermes");
       if (existsSync(hermesSkillsSrc)) {
-        const hermesSkillsDest = join(HOME, ".hermes", "skills", "integrations");
+        const hermesSkillsDest = resolveHermesSkillsDest();
         mkdirSync(hermesSkillsDest, { recursive: true });
         cpSync(hermesSkillsSrc, hermesSkillsDest, { recursive: true });
         console.log(`  ${green}✓${r} Hermes skills installed: ${dim}${hermesSkillsDest}${r}`);

package/harnesses.json

@@ -129,10 +129,10 @@
       "aliases": [],
       "cli": "hermes",
       "kind": "terminal",
-      "installer_scope": "global",
-      "installer_config": "~/.hermes/config.yaml",
-      "harness_scope": "per-profile",
-      "installer_defect": "The path is hardcoded to ~/.hermes/config.yaml. The installer never calls `hermes config path` and does not know profiles exist, so installing while a non-default profile is active writes the DEFAULT profile's config — the wrong file, silently. Not fixed as of 0.6.41.",
+      "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",
+      "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.",
       "listener": {
         "wake": "realtime",
         "mechanism": "webhook-bridge",
@@ -227,12 +227,12 @@
       "installer_config": ".jcode/mcp.json",
       "harness_scope": "project",
       "listener": {
-        "wake": "none",
-        "mechanism": null,
-        "self_arm": false,
+        "wake": "stall",
+        "mechanism": "subscribe-skill-stall-signal",
+        "self_arm": true,
         "survives_wake": null,
         "evidence": "declared",
-        "note": "STDIO ONLY, WHICH IS WHY THIS ROW IS NOT LIKE THE OTHERS. jcode reads .jcode/mcp.json, .mcp.json and .claude/mcp.json, so it ALREADY finds the Claude Code entry we write - and drops it, because jcode supports stdio servers only and skips type http/sse at load time with a log line (crates/jcode-base/src/mcp/protocol.rs, retain on is_stdio). So our installer writes a stdio bridge entry instead of the http entry every other harness gets. Two consequences a reader must not undo: the server is named patchcord-jcode, NOT patchcord, because jcode merges those three files with later ones overriding by NAME - a shared name means the day jcode gains http transport, the .mcp.json entry becomes runnable and silently overrides, and jcode starts authenticating as claude_code's agent. And no wake: no subscribe path exists for jcode in this package."
+        "note": "STDIO ONLY FOR MCP; SKILLS ARE GLOBAL, NOT PROJECT. jcode reads .jcode/mcp.json, .mcp.json and .claude/mcp.json for MCP config (per-project, unchanged by this note), so it ALREADY finds the Claude Code entry we write - and drops it, because jcode supports stdio servers only and skips type http/sse at load time with a log line (crates/jcode-base/src/mcp/protocol.rs, retain on is_stdio). Server named patchcord-jcode, NOT patchcord, for the same reason codex uses patchcord-codex: a shared name would let a later file's entry silently override by NAME the day jcode gains http transport. jcode's own skills, separately, install ONCE GLOBALLY to ~/.jcode/skills/<name>/SKILL.md (verified from crates/jcode-app-core/src/tool/skill.rs's own loader paths) - not per project. WAKE IS \"stall\", NOT \"realtime\" OR \"none\": jcode has no Monitor, so a background task wakes it only when stdout goes quiet for stall_wake_seconds - and subscribe.mjs's only stdout writer is a real-message line, so by default the pipe is ALREADY silent while idle, making an unmodified stall wake fire on a timer regardless of whether anything arrived. `patchcord subscribe --stall-signal` (scripts/lib/stall-signal.mjs) inverts that for jcode specifically: writes a HEARTBEAT keepalive while idle so the pipe is never silently quiet by accident, and suppresses it on purpose after a real message so the stall condition elapses close to when the message actually arrived. This only works if stall_wake_seconds equals --stall-signal's own quiet window (15s by default) - a mismatch silently breaks the wake in one direction or the other, which is why the subscribe skill states the number explicitly rather than leaving it to be inferred. NOT VERIFIED END TO END: no jcode install on this machine to watch it actually fire."
       }
     }
   ],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "patchcord",
-  "version": "0.6.43",
+  "version": "0.6.44",
   "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/inbox/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: patchcord-inbox
+description: Read Patchcord inbox and reply to messages
+---
+
+## Applies only when Patchcord MCP tools are loaded
+
+If the `inbox` MCP tool is not available in this session, this skill does not
+apply. Do nothing: do not run the Patchcord CLI, read a token from a config
+file, or call the HTTP API. A missing project MCP config is a normal state.
+
+Call the `inbox` MCP tool now. In its response, the first header line is YOUR
+own identity (the recipient); the real sender of each message is on a
+`From X` line — never confuse the two.
+
+For each pending message, classify it and act:
+
+- **ACK** — short signals like thanks, noted, works, great, ok, 👍 with no
+  task → close it silently: `reply(message_id, resolve=true)` with NO
+  content. Never send a text reply to an ack (it creates infinite ack
+  chains).
+- **BLOCKED** — you cannot do the work right now (busy, missing credentials,
+  ambiguous target) → `reply(message_id, "<reason>", defer=true)` so it stays
+  in your inbox as a reminder. Never silently skip a message.
+- **ACTIONABLE** — do the work the message asks for FIRST (edit the file,
+  run the command, write the code), THEN
+  `reply(message_id, "<concrete summary of what you did, with file paths and
+  line numbers>")`. Never reply "will do" / "understood" before doing the
+  work.
+
+If the patchcord-subscribe listener is already running in the background,
+you do not need to restart it after handling messages — unlike a
+poll-and-exit script, it keeps running across wakes. Only restart it if you
+have reason to believe it died (see the patchcord-subscribe skill).

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

@@ -0,0 +1,109 @@
+---
+name: patchcord-subscribe
+description: >
+  Start the Patchcord background listener so new messages wake this agent.
+  Run this when the user asks to start Patchcord push delivery.
+---
+
+jcode has no Monitor tool. A background task here wakes the agent on a
+STALL — no new output for N seconds — not per line the way Claude Code's
+Monitor does. Following Claude Code's own subscribe instructions verbatim on
+jcode produces a listener that connects, receives, and never wakes you: the
+pipe fills with messages you are never told about.
+
+This skill exists to run correctly on jcode specifically, using
+`patchcord subscribe --stall-signal`, a mode built for exactly this gap:
+while idle it writes a `HEARTBEAT:` line often enough that the pipe never
+looks silent, and on a real message it goes quiet on purpose for long enough
+that jcode's own stall detector fires. This is this repo's global skill
+directory (`~/.jcode/skills/`), shared by every jcode project on this
+machine — nothing below may name a specific namespace, agent, or project
+path.
+
+# Start
+
+1. **Drain the inbox first.** Call the Patchcord `inbox` MCP tool. Process
+   every pending message (see the patchcord-inbox skill) before starting the
+   listener — a backlog can accumulate while no listener was running, and
+   the listener does not replay what happened before it started.
+
+2. **Spawn the listener with bash, in the background, with a stall wake:**
+
+   ```
+   Bash(
+     command: "patchcord subscribe --stall-signal | grep --line-buffered '^PATCHCORD:'; exit ${PIPESTATUS[0]}",
+     run_in_background: true,
+     stall_wake_seconds: 15
+   )
+   ```
+
+   `stall_wake_seconds: 15` is not a placeholder — it MUST match
+   `--stall-signal`'s own default quiet window (15000ms). If you ever pass
+   `--stall-signal` a custom triple (`keepaliveMs:quietMs:stallMs`),
+   `stall_wake_seconds` must equal the `stallMs` you passed, or the two
+   numbers disagree and the wake either fires on nothing (too short) or
+   never fires on a real message (too long). Do not use 30 here — that
+   number predates `--stall-signal` and is shorter than nothing: it is
+   simply the wrong number for this mechanism, not a safer one.
+
+   The grep keeps only `PATCHCORD:` lines in the visible output; `HEARTBEAT:`
+   lines never match that pattern, so they never need special handling on
+   your end. `${PIPESTATUS[0]}` preserves subscribe's own exit code through
+   the pipe.
+
+3. **Tell the user one line:** "Patchcord listener active — I'll check
+   regularly for new messages." Do not say "as messages arrive" — the
+   mechanism approximates that, it does not guarantee it, and promising more
+   than jcode can deliver is worse than being accurate.
+
+# When the background task wakes you
+
+A wake means the pipe went quiet for `stall_wake_seconds` — with
+`--stall-signal` running, that quiet is now DESIGNED to correlate with a real
+message, but two other things also produce exactly the same silence, and you
+cannot tell which one happened from the wake alone:
+
+1. **Check the inbox every time.** Call the Patchcord `inbox` MCP tool. If it
+   has pending messages, handle them (see the patchcord-inbox skill). If it
+   is empty, say nothing to the user and do not report the wake as an event —
+   an empty check is not news.
+2. **If the inbox is empty, check whether the listener is still running**
+   before assuming this was a harmless false positive. A dead listener also
+   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.
+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
+   `PATCHCORD:` line without a corresponding inbox check is not confirmation
+   of anything.
+
+# Stopping
+
+Tell the user one of:
+
+- End this session.
+- Kill the listener: `kill $(cat /tmp/patchcord_subscribe_<namespace>_<agent>.pid)`
+  (the exact path is printed by `patchcord subscribe` on start; do not guess
+  the namespace/agent — this is a global skill and cannot know them).
+
+# If the background task ends on its own
+
+Read its output. Scan for one of:
+
+- `no patchcord config found` — not run from a project with `.jcode/mcp.json`
+  (or a parent project directory).
+- `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.
+- `subscribe: fatal: ...` — report the fatal line verbatim.
+
+If none of those appear, it likely ended with the session or because its
+output consumer closed. Restart it only when the user asks to resume Patchcord
+push delivery.
+
+**Forbidden on failure:** no hand-rolled polling loop in place of this
+mechanism, no pidfile editing, no re-arm loop after every wake — the
+background task under `run_in_background` keeps running across wakes; you
+are only checking in, not restarting it, unless step 2 above found it dead.

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

@@ -0,0 +1,26 @@
+---
+name: patchcord-wait
+description: Wait for one incoming Patchcord message
+---
+
+## Applies only when Patchcord MCP tools are loaded
+
+If the `wait_for_message` MCP tool is not available in this session, this
+skill does not apply. Do nothing: do not run the Patchcord CLI, read a token
+from a config file, or call the HTTP API. A missing project MCP config is a
+normal state.
+
+Call the `wait_for_message` MCP tool now to block until a message arrives or
+~5 minutes elapse.
+
+When a message arrives, classify it and act:
+
+- **ACK** (thanks, noted, works, ok, 👍, no task) →
+  `reply(message_id, resolve=true)` with NO content. Never text-reply an ack.
+- **BLOCKED** (cannot do the work right now) →
+  `reply(message_id, "<reason>", defer=true)`.
+- **ACTIONABLE** → do the work FIRST, then
+  `reply(message_id, "<concrete summary of what you did>")`.
+
+Use this skill for a single blocking wait, not as a substitute for the
+persistent background listener — see the patchcord-subscribe skill for that.

package/scripts/lib/hermes-home.mjs

@@ -0,0 +1,120 @@
+// Resolve where Hermes's HOME actually is, honouring HERMES_HOME — and
+// derive both config.yaml's path and the skills install destination from
+// that ONE resolved home, never from separate hardcoded joins.
+//
+// WHY THIS EXISTS
+//
+// bin/patchcord.mjs hardcoded join(HOME, ".hermes", "config.yaml") in two
+// places — the write site (writeWorkerConfig, provisioning a seat) and the
+// read site (bearer resolution, what `patchcord whoami` verifies against).
+// Neither read HERMES_HOME. mux sets HERMES_HOME=<seat workdir>/.hermes to
+// isolate one Hermes identity per seat; without this, every seat installs
+// into and reads from the SAME operator-global ~/.hermes/config.yaml.
+//
+// FIXING ONLY ONE SITE IS WORSE THAN FIXING NEITHER. `patchcord whoami` is
+// mux's second independent witness that a seat holds the identity just
+// minted for it. If the write moves to the seat's own HERMES_HOME but the
+// read keeps resolving the operator's global config, whoami silently
+// verifies the wrong file against itself — a check that always "passes"
+// because it was never actually looking where the write went.
+//
+// SKILLS FOLLOW THE HOME TOO, same reasoning one level up: they are a
+// GUARD, not documentation — carrying, among other rules, "do not run the
+// patchcord CLI when MCP is loaded". A seat isolated by HERMES_HOME that
+// still reads its skills from the operator's global
+// ~/.hermes/skills/integrations/ is running under another context's guard,
+// which is not isolation, just a config file that happens to be separate.
+// bin/patchcord.mjs previously joined ~/.hermes/skills/integrations
+// directly in three places, none aware of HERMES_HOME — the same defect
+// class as the config.yaml sites, one directory over.
+//
+// RESOLUTION ORDER, identical everywhere a Hermes path is needed:
+//   1. HERMES_HOME from the environment — this IS the home; nothing to
+//      derive.
+//   2. `hermes config path`, if the binary resolves — the harness's OWN
+//      answer for where its config lives, not our model of it. This command
+//      itself honours HERMES_HOME, which is exactly why a caller that shells
+//      it must NOT strip the environment: execSync inherits process.env by
+//      default, and that default is load-bearing here — an explicit `env`
+//      override that omits HERMES_HOME would make this probe silently
+//      answer for the OPERATOR's home instead of the seat's, which looks
+//      identical to "the env var is being ignored" from the outside. The
+//      home is taken as dirname() of the printed config file path, on the
+//      same "config path" == ".../config.yaml" assumption documented below.
+//   3. ~/.hermes — today's fallback, unchanged, so nothing existing breaks
+//      for an operator who never set HERMES_HOME.
+//
+// config.yaml's path and the skills destination are both joined onto this
+// 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.
+//
+// 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.
+
+import { execSync } from "node:child_process";
+import { join, dirname } from "node:path";
+import { homedir } from "node:os";
+
+/** Shell `hermes config path`, inheriting the parent environment (the
+ *  execSync default — do not pass an `env` override here). Returns the
+ *  trimmed stdout, or null if the binary is absent, exits non-zero, or
+ *  prints nothing. Exported so a test can substitute a fake without a real
+ *  `hermes` on PATH. */
+export function shellHermesConfigPath() {
+  try {
+    const out = execSync("hermes config path", {
+      stdio: ["ignore", "pipe", "ignore"],
+    }).toString("utf-8").trim();
+    return out || null;
+  } catch {
+    return null;
+  }
+}
+
+/** Resolve Hermes's home DIRECTORY per the order documented above.
+ *  `home` and `shell` are injectable for tests; production callers use the
+ *  defaults (real homedir(), real shellHermesConfigPath()). Every other
+ *  Hermes path in this module is joined onto this one value. */
+export function resolveHermesHome({ home = homedir(), shell = shellHermesConfigPath } = {}) {
+  const envHome = process.env.HERMES_HOME;
+  if (envHome) {
+    return envHome;
+  }
+  const shelledConfigPath = shell();
+  if (shelledConfigPath) {
+    return dirname(shelledConfigPath);
+  }
+  return join(home, ".hermes");
+}
+
+/** Resolve the Hermes config.yaml path. */
+export function resolveHermesConfigPath(opts) {
+  return join(resolveHermesHome(opts), "config.yaml");
+}
+
+/** Resolve where Hermes skills install — same home as config.yaml, so a
+ *  seat's skills and its identity can never point at different machines'
+ *  worth of Hermes. */
+export function resolveHermesSkillsDest(opts) {
+  return join(resolveHermesHome(opts), "skills", "integrations");
+}

package/scripts/lib/stall-signal.mjs

@@ -0,0 +1,104 @@
+// Pure parsing + validation for `patchcord subscribe --stall-signal[=<opts>]`.
+//
+// WHY THIS MODE EXISTS
+//
+// subscribe.mjs's only stdout writer is notify() — it writes a "PATCHCORD: ..."
+// line on a real message and nothing else. There is no periodic heartbeat line;
+// the WebSocket-level ping (HEARTBEAT_INTERVAL_MS in subscribe.mjs) never
+// touches stdout. So on a harness that wakes the agent on a STALL (no stdout
+// for N seconds) instead of per-line like Claude Code's Monitor, the pipe is
+// ALREADY silent while idle — a stall fires whether or not a message arrived,
+// which is a wake-on-silence mechanism, not wake-on-message.
+//
+// --stall-signal inverts that: while idle it writes a keepalive line often
+// enough that the pipe never looks silent, and on a real message it goes
+// quiet on purpose for long enough that the harness's stall detector fires.
+// The result approximates wake-on-message using only a wake-on-silence
+// primitive.
+//
+// KEPT SEPARATE FROM subscribe.mjs so the arithmetic can be unit tested
+// without opening a WebSocket, resolving a project config, or touching a
+// pidfile — all things subscribe.mjs does as soon as it runs.
+//
+// THE KEEPALIVE LINE ITSELF (written by subscribe.mjs, not here) starts with
+// "HEARTBEAT:", which does not match `^PATCHCORD:` — the grep filter every
+// subscribe skill uses already drops it for free.
+
+export const STALL_SIGNAL_DEFAULTS = Object.freeze({
+  // Written to stdout on this interval while idle. Must stay well under
+  // stallMs or the pipe can look idle for a full stall window even though
+  // nothing is wrong — see validateStallSignalOpts.
+  keepaliveMs: 5000,
+  // Keepalives are suppressed for this long after a real notification, so
+  // the pipe goes quiet on purpose. Must be >= stallMs or the harness's
+  // stall condition never actually triggers and the message is missed.
+  quietMs: 15000,
+  // What the CALLER promises the harness's own stall/wake threshold is set
+  // to (e.g. jcode's `stall_wake_seconds`, in ms here). subscribe.mjs cannot
+  // observe that value — the harness owns it — so this is supplied by
+  // whoever launches --stall-signal and used only to validate the other two
+  // against it before this process does anything live.
+  stallMs: 15000,
+});
+
+/** Parse `--stall-signal` out of an argv array. Returns null if the flag is
+ *  absent (mode disabled, nothing else in this module runs) or a resolved
+ *  options object. Throws on a malformed or nonsensical inline value —
+ *  the caller decides how to report that (subscribe.mjs calls its own
+ *  die()). Absence of the flag is untouched by this function: it returns
+ *  null and every default in the rest of subscribe.mjs is unaffected. */
+export function parseStallSignalArg(argv) {
+  if (!argv.includes("--stall-signal")) return null;
+  const i = argv.indexOf("--stall-signal");
+  const inline = i >= 0 && argv[i + 1] && !argv[i + 1].startsWith("-") ? argv[i + 1] : null;
+  return resolveStallSignalOpts(inline);
+}
+
+/** `inline` is `keepaliveMs:quietMs:stallMs`, any suffix omitted to take the
+ *  default (so `--stall-signal` alone, `--stall-signal 8000`, and
+ *  `--stall-signal 8000:20000:20000` are all legal). Throws on a
+ *  non-positive/non-numeric field or a combination validateStallSignalOpts
+ *  rejects. */
+export function resolveStallSignalOpts(inline) {
+  const d = STALL_SIGNAL_DEFAULTS;
+  if (!inline) {
+    const opts = { ...d };
+    validateStallSignalOpts(opts);
+    return opts;
+  }
+  const parts = inline.split(":");
+  const pick = (raw, fallback, label) => {
+    if (raw === undefined || raw === "") return fallback;
+    const n = Number(raw);
+    if (!Number.isFinite(n) || n <= 0) {
+      throw new Error(`--stall-signal: ${label} must be a positive number of milliseconds, got "${raw}"`);
+    }
+    return n;
+  };
+  const opts = {
+    keepaliveMs: pick(parts[0], d.keepaliveMs, "keepaliveMs"),
+    quietMs: pick(parts[1], d.quietMs, "quietMs"),
+    stallMs: pick(parts[2], d.stallMs, "stallMs"),
+  };
+  validateStallSignalOpts(opts);
+  return opts;
+}
+
+/** Refuse a nonsensical pair rather than run silently wrong. Both directions
+ *  matter: a keepalive too close to stallMs risks a false stall while idle,
+ *  and a quiet window shorter than stallMs means the harness's stall NEVER
+ *  fires on a real message — the exact failure this mode exists to prevent. */
+export function validateStallSignalOpts(opts) {
+  if (opts.keepaliveMs >= opts.stallMs) {
+    throw new Error(
+      `--stall-signal: keepaliveMs (${opts.keepaliveMs}) must be less than stallMs (${opts.stallMs}) — ` +
+      `otherwise the pipe can go quiet for a full stall window while idle and nothing is wrong`
+    );
+  }
+  if (opts.quietMs < opts.stallMs) {
+    throw new Error(
+      `--stall-signal: quietMs (${opts.quietMs}) must be at least stallMs (${opts.stallMs}) — ` +
+      `otherwise the harness's stall window never elapses during the quiet period and a real message is missed`
+    );
+  }
+}

package/scripts/subscribe.mjs

@@ -14,6 +14,7 @@ import { URL } from "node:url";
 import { dirname } from "node:path";
 import { connect as wsConnect } from "./lib/ws.mjs";
 import { resolveProjectBearer, listProjectBearers } from "./lib/resolve-project-bearer.mjs";
+import { parseStallSignalArg } from "./lib/stall-signal.mjs";
 
 // --- Hermes webhook bridge mode -------------------------------------------
 // Default mode writes "PATCHCORD: ..." lines to stdout for Claude Code's
@@ -30,6 +31,36 @@ const HERMES_WEBHOOK = (() => {
   return process.env.PATCHCORD_HERMES_WEBHOOK || inline || null;
 })();
 
+// --- Stall-signal mode ------------------------------------------------------
+// Default mode's only stdout writer is notify() — nothing else touches
+// stdout, so a harness with no Monitor that wakes on a STALL (no output for
+// N seconds) instead of per-line wakes on a timer, not on a message: the pipe
+// is silent whether or not anything arrived. See scripts/lib/stall-signal.mjs
+// for the inversion this mode performs (keepalive while idle, deliberate
+// quiet on a real message) and why the two windows must relate the way they
+// do. `--stall-signal` alone uses every default; `--stall-signal
+// keepaliveMs:quietMs:stallMs` overrides any prefix of the three. A malformed
+// or self-contradictory value is a startup error, not a silently-wrong run.
+let STALL_SIGNAL_OPTS = null;
+try {
+  STALL_SIGNAL_OPTS = parseStallSignalArg(process.argv);
+} catch (e) {
+  die(e.message);
+}
+const STALL_SIGNAL_MODE = STALL_SIGNAL_OPTS !== null;
+if (STALL_SIGNAL_MODE && HERMES_MODE) {
+  die("--stall-signal and --hermes are mutually exclusive — each is its own wake mechanism, pick one");
+}
+// The keepalive line's own prefix, chosen so it can never collide with a
+// real notification: every subscribe skill's grep is `^PATCHCORD:`, and
+// "HEARTBEAT:" does not start with "PATCHCORD" at all, so nothing else needs
+// to change for a consumer that already filters on that pattern.
+const STALL_SIGNAL_KEEPALIVE_PREFIX = "HEARTBEAT:";
+// Suppress keepalives until this timestamp (ms since epoch). 0 = never
+// suppressed. Set by notify() on every real message.
+let stallSignalQuietUntil = 0;
+let stallSignalTimer = null;
+
 const JWT_REFRESH_SAFETY_MARGIN_SEC = 120;
 const HEARTBEAT_INTERVAL_MS = 25_000;
 const RECONNECT_BACKOFF_MS = [1000, 2000, 4000, 8000, 15_000, 30_000];
@@ -171,6 +202,11 @@ function httpJson(urlStr, { method = "GET", headers = {}, body = null } = {}) {
 async function notify(line, meta = {}) {
   if (!HERMES_MODE) {
     process.stdout.write(line + "\n");
+    // Go quiet on purpose: suppress keepalives long enough that the
+    // harness's own stall detector actually elapses during this window.
+    if (STALL_SIGNAL_MODE) {
+      stallSignalQuietUntil = Date.now() + STALL_SIGNAL_OPTS.quietMs;
+    }
     return;
   }
   if (!HERMES_WEBHOOK) return;
@@ -330,7 +366,10 @@ async function run() {
   const pidfile = `/tmp/patchcord_subscribe_${ticket.namespace_ids[0]}_${ticket.agent_id}.pid`;
   writePidfile(pidfile);
 
-  const cleanup = () => removePidfile(pidfile);
+  const cleanup = () => {
+    removePidfile(pidfile);
+    if (stallSignalTimer) clearInterval(stallSignalTimer);
+  };
   process.on("exit", cleanup);
   process.on("SIGINT", () => {
     cleanup();
@@ -366,6 +405,23 @@ async function run() {
 
   logErr(`subscribe: agent=${ticket.agent_id} namespaces=${ticket.namespace_ids.join(",")}`);
 
+  // Runs for the process's whole life, independent of WS connect/reconnect
+  // state — a reconnect backoff is a normal transient state, not something
+  // that should look like a stall to the harness. Suppressed for quietMs
+  // after a real notification (notify() sets stallSignalQuietUntil); resumes
+  // once that window elapses.
+  if (STALL_SIGNAL_MODE) {
+    logErr(
+      `subscribe: stall-signal keepalive=${STALL_SIGNAL_OPTS.keepaliveMs}ms ` +
+      `quiet=${STALL_SIGNAL_OPTS.quietMs}ms stall=${STALL_SIGNAL_OPTS.stallMs}ms`
+    );
+    stallSignalTimer = setInterval(() => {
+      if (Date.now() >= stallSignalQuietUntil) {
+        process.stdout.write(`${STALL_SIGNAL_KEEPALIVE_PREFIX} ${new Date().toISOString()}\n`);
+      }
+    }, STALL_SIGNAL_OPTS.keepaliveMs);
+  }
+
   let backoffIdx = 0;
 
   const refreshAuth = async () => {

package/skills/subscribe/SKILL.md

@@ -30,6 +30,48 @@ User invoked /patchcord:subscribe — do NOT substitute `wait_for_message()`. Sp
 
 3. **Tell the user one line:** *"Patchcord listener active — I'll pick up new messages as they arrive."*
 
+# IF YOUR HARNESS HAS NO `Monitor` TOOL — READ THIS BEFORE STEP 2
+
+`Monitor` is a Claude Code tool. Step 2 above assumes it, and the assumption is
+load-bearing rather than stylistic: Monitor turns EVERY stdout line into a
+notification, which is what makes a message arriving wake you.
+
+Other harnesses run a background command instead (`bash` with
+`run_in_background: true`, or your harness's equivalent), and those typically
+notify on a STALL — no output for N seconds — not on each line. On such a
+harness, following step 2 verbatim produces a listener that WORKS and NEVER
+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`:
+
+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.
+
+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".
+
+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.
+
 # When a notification fires
 
 Monitor surfaces `PATCHCORD: 1 new from <sender>`: