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

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

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

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

@@ -44,33 +44,59 @@ 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
+```
 
-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".
+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.
+
+   **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
+   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.46",
+  "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.
@@ -295,7 +297,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) {
@@ -489,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

@@ -44,33 +44,59 @@ 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
+```
 
-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".
+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.
+
+   **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
+   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