patchcord 0.6.47 → 0.6.48

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

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

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

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

@@ -48,7 +48,7 @@ So, if you have no `Monitor`, **use `--stall-signal`. It was built for exactly
 this and it is not optional here:**
 
 ```
-patchcord subscribe --stall-signal | grep --line-buffered '^PATCHCORD:'; exit ${PIPESTATUS[0]}
+patchcord subscribe --stall-signal
 ```
 
 run as a background command with your harness's stall wake set to **15
@@ -61,8 +61,14 @@ seconds** (jcode: `stall_wake_seconds: 15`).
    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.
+   **Run it raw. Do not pipe it through `grep`.** Step 2's command filters
+   stdout down to `^PATCHCORD:` lines, and that filter removes the keepalives
+   this mode depends on. Your harness measures the stall on the OUTPUT of the
+   pipeline, so a filtered stream is silent all the time: the wake fires on
+   nothing every 15 s, and the deliberate quiet after a real message looks
+   exactly like idle. Filtering here does not merely add noise, it deletes the
+   signal. Ignore the `HEARTBEAT:` lines when you read the output; they exist
+   for the stall detector, not for you.
 
 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "patchcord",
-  "version": "0.6.47",
+  "version": "0.6.48",
   "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

@@ -31,7 +31,7 @@ path.
 
    ```
    Bash(
-     command: "patchcord subscribe --stall-signal | grep --line-buffered '^PATCHCORD:'; exit ${PIPESTATUS[0]}",
+     command: "patchcord subscribe --stall-signal",
      run_in_background: true,
      stall_wake_seconds: 15
    )
@@ -46,10 +46,19 @@ path.
    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.
+   **DO NOT PIPE THIS THROUGH `grep`.** Every other subscribe command in this
+   plugin filters stdout down to `^PATCHCORD:` lines, and doing that here
+   breaks the entire mechanism: your harness measures the stall on what comes
+   OUT of the pipeline, and `grep` removes exactly the `HEARTBEAT:` keepalives
+   that are supposed to keep the pipe looking alive. Filtered, the stream is
+   silent all the time, so the wake fires on nothing every 15 s and the quiet
+   window after a real message is indistinguishable from idle. That is the
+   noisy, useless wake loop `--stall-signal` exists to replace.
+
+   So the raw stream is what the background task must see. It carries
+   `HEARTBEAT: <timestamp>` every 5 s and `PATCHCORD: ...` on a real message.
+   Ignore the heartbeats when you read the output; they are for the stall
+   detector, not for you.
 
 3. **Tell the user one line:** "Patchcord listener active — I'll check
    regularly for new messages." Do not say "as messages arrive" — the
@@ -83,7 +92,7 @@ cannot tell which one happened from the wake alone:
 
    ```
    Bash(
-     command: "patchcord subscribe --replace --stall-signal | grep --line-buffered '^PATCHCORD:'; exit ${PIPESTATUS[0]}",
+     command: "patchcord subscribe --replace --stall-signal",
      run_in_background: true,
      stall_wake_seconds: 15
    )

package/scripts/lib/stall-signal.mjs

@@ -21,8 +21,21 @@
 // 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.
+// "HEARTBEAT:", which does not match `^PATCHCORD:`.
+//
+// THAT USED TO BE DESCRIBED HERE AS A CONVENIENCE — the grep every other
+// subscribe skill uses "drops it for free". It is the opposite, and the
+// mistake cost a working listener in production: the harness measures the
+// stall on what comes OUT of the pipeline, so a `| grep '^PATCHCORD:'` in
+// front of a --stall-signal listener deletes every keepalive before anything
+// can see it. The stream is then silent all the time, the wake fires on
+// nothing every stall window, and the deliberate quiet after a real message
+// is indistinguishable from idle. Filtering does not add noise here, it
+// removes the signal.
+//
+// So the keepalive prefix exists to be IGNORED BY A READER, not removed by a
+// filter. --stall-signal must be run raw. Every skill that documents it is
+// pinned to that by tests in tests/test-stall-signal.mjs.
 
 export const STALL_SIGNAL_DEFAULTS = Object.freeze({
   // Written to stdout on this interval while idle. Must stay well under

package/scripts/subscribe.mjs

@@ -53,10 +53,12 @@ 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.
+// The keepalive line's own prefix, chosen so it can never collide with a real
+// notification. It must be IGNORED by whoever reads the output, and never
+// FILTERED OUT of it: a `| grep '^PATCHCORD:'` in front of a --stall-signal
+// listener removes exactly the lines that keep the pipe from looking idle,
+// which turns wake-on-message back into wake-on-silence. See the header of
+// scripts/lib/stall-signal.mjs.
 const STALL_SIGNAL_KEEPALIVE_PREFIX = "HEARTBEAT:";
 // Suppress keepalives until this timestamp (ms since epoch). 0 = never
 // suppressed. Set by notify() on every real message.
@@ -502,6 +504,13 @@ async function run() {
       `subscribe: stall-signal keepalive=${STALL_SIGNAL_OPTS.keepaliveMs}ms ` +
       `quiet=${STALL_SIGNAL_OPTS.quietMs}ms stall=${STALL_SIGNAL_OPTS.stallMs}ms`
     );
+    // Said out loud on every start, because the mistake is invisible once
+    // made: a filtered stream looks like a working listener that simply never
+    // wakes anyone, which is exactly what was reported from production.
+    logErr(
+      "subscribe: stall-signal writes HEARTBEAT: lines to stdout — do NOT pipe " +
+      "this through `grep '^PATCHCORD:'`, it deletes them and the wake stops working"
+    );
     stallSignalTimer = setInterval(() => {
       if (Date.now() >= stallSignalQuietUntil) {
         process.stdout.write(`${STALL_SIGNAL_KEEPALIVE_PREFIX} ${new Date().toISOString()}\n`);

package/skills/subscribe/SKILL.md

@@ -48,7 +48,7 @@ So, if you have no `Monitor`, **use `--stall-signal`. It was built for exactly
 this and it is not optional here:**
 
 ```
-patchcord subscribe --stall-signal | grep --line-buffered '^PATCHCORD:'; exit ${PIPESTATUS[0]}
+patchcord subscribe --stall-signal
 ```
 
 run as a background command with your harness's stall wake set to **15
@@ -61,8 +61,14 @@ seconds** (jcode: `stall_wake_seconds: 15`).
    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.
+   **Run it raw. Do not pipe it through `grep`.** Step 2's command filters
+   stdout down to `^PATCHCORD:` lines, and that filter removes the keepalives
+   this mode depends on. Your harness measures the stall on the OUTPUT of the
+   pipeline, so a filtered stream is silent all the time: the wake fires on
+   nothing every 15 s, and the deliberate quiet after a real message looks
+   exactly like idle. Filtering here does not merely add noise, it deletes the
+   signal. Ignore the `HEARTBEAT:` lines when you read the output; they exist
+   for the stall detector, not for you.
 
 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