patchcord 0.5.14 → 0.5.16

package/bin/patchcord.mjs

@@ -97,6 +97,43 @@ if (!cmd || cmd === "install" || cmd === "agent" || cmd?.startsWith("--")) {
     } catch { return null; }
   }
 
+  // Read+merge+write a JSON config file. If the file exists but its contents
+  // can't be parsed, REFUSE to write — silently overwriting would erase
+  // unrelated MCP servers, settings, or hand-edits the user has in there.
+  // Returns true on success, false when skipped due to a parse failure (so
+  // the caller can suppress its "configured" message).
+  function updateJsonConfig(filePath, mutate) {
+    let parsed = {};
+    if (existsSync(filePath)) {
+      const raw = readFileSync(filePath, "utf-8");
+      try {
+        // JSONC-tolerant: Zed/Gemini settings allow //, /* */, trailing commas.
+        const cleaned = raw
+          .replace(/\/\/.*$/gm, "")
+          .replace(/\/\*[\s\S]*?\*\//g, "")
+          .replace(/,\s*([}\]])/g, "$1");
+        const result = cleaned.trim() ? JSON.parse(cleaned) : {};
+        // null / arrays / primitives aren't config objects we can merge into;
+        // refuse rather than blow them away.
+        if (result === null || typeof result !== "object" || Array.isArray(result)) {
+          console.log(`\n  ${yellow}⚠${r}  Skipped ${filePath} — existing file is not a JSON object.`);
+          console.log(`     Replace it with a valid object ({...}) or remove it, then re-run.`);
+          return false;
+        }
+        parsed = result;
+      } catch {
+        console.log(`\n  ${yellow}⚠${r}  Skipped ${filePath} — could not parse existing JSON.`);
+        console.log(`     Fix the file by hand and re-run the installer. We will not`);
+        console.log(`     overwrite it: that would erase your other servers/settings.`);
+        return false;
+      }
+    }
+    mutate(parsed);
+    mkdirSync(dirname(filePath), { recursive: true });
+    writeFileSync(filePath, JSON.stringify(parsed, null, 2) + "\n");
+    return true;
+  }
+
   console.log(`
   ___  ____ ___ ____ _  _ ____ ____ ____ ___
   |__] |__|  |  |    |__| |    |  | |__/ |  \\
@@ -661,20 +698,14 @@ if (!cmd || cmd === "install" || cmd === "agent" || cmd?.startsWith("--")) {
       },
     };
 
-    if (existsSync(cursorPath)) {
-      try {
-        const existing = JSON.parse(readFileSync(cursorPath, "utf-8"));
-        existing.mcpServers = existing.mcpServers || {};
-        existing.mcpServers.patchcord = cursorConfig.mcpServers.patchcord;
-        writeFileSync(cursorPath, JSON.stringify(existing, null, 2) + "\n");
-      } catch {
-        writeFileSync(cursorPath, JSON.stringify(cursorConfig, null, 2) + "\n");
-      }
-    } else {
-      writeFileSync(cursorPath, JSON.stringify(cursorConfig, null, 2) + "\n");
+    const cursorOk = updateJsonConfig(cursorPath, (obj) => {
+      obj.mcpServers = obj.mcpServers || {};
+      obj.mcpServers.patchcord = cursorConfig.mcpServers.patchcord;
+    });
+    if (cursorOk) {
+      console.log(`\n  ${green}✓${r} Cursor configured: ${dim}${cursorPath}${r}`);
+      console.log(`  ${dim}Per-project only — other projects won't see this agent.${r}`);
     }
-    console.log(`\n  ${green}✓${r} Cursor configured: ${dim}${cursorPath}${r}`);
-    console.log(`  ${dim}Per-project only — other projects won't see this agent.${r}`);
   } else if (isWindsurf) {
     // Windsurf: global only (~/.codeium/windsurf/mcp_config.json)
     const wsPath = join(HOME, ".codeium", "windsurf", "mcp_config.json");
@@ -690,84 +721,72 @@ if (!cmd || cmd === "install" || cmd === "agent" || cmd?.startsWith("--")) {
       },
     };
 
-    if (existsSync(wsPath)) {
-      try {
-        const content = readFileSync(wsPath, "utf-8").trim();
-        const existing = content ? JSON.parse(content) : {};
-        existing.mcpServers = existing.mcpServers || {};
-        existing.mcpServers.patchcord = wsConfig.mcpServers.patchcord;
-        writeFileSync(wsPath, JSON.stringify(existing, null, 2) + "\n");
-      } catch {
-        writeFileSync(wsPath, JSON.stringify(wsConfig, null, 2) + "\n");
-      }
-    } else {
-      mkdirSync(join(HOME, ".codeium", "windsurf"), { recursive: true });
-      writeFileSync(wsPath, JSON.stringify(wsConfig, null, 2) + "\n");
+    const wsOk = updateJsonConfig(wsPath, (obj) => {
+      obj.mcpServers = obj.mcpServers || {};
+      obj.mcpServers.patchcord = wsConfig.mcpServers.patchcord;
+    });
+    if (wsOk) {
+      console.log(`\n  ${green}✓${r} Windsurf configured: ${dim}${wsPath}${r}`);
+      console.log(`  ${yellow}Global config — all Windsurf projects share this agent.${r}`);
     }
-    console.log(`\n  ${green}✓${r} Windsurf configured: ${dim}${wsPath}${r}`);
-    console.log(`  ${yellow}Global config — all Windsurf projects share this agent.${r}`);
   } else if (isGemini) {
     // Gemini CLI: global only (~/.gemini/settings.json)
     const geminiPath = join(HOME, ".gemini", "settings.json");
-    let geminiSettings = (existsSync(geminiPath) && safeReadJson(geminiPath)) || {};
-    if (!geminiSettings.mcpServers) geminiSettings.mcpServers = {};
-    geminiSettings.mcpServers.patchcord = {
-      httpUrl: `${serverUrl}/mcp`,
-      headers: {
-        Authorization: `Bearer ${token}`,
-        "X-Patchcord-Machine": hostname,
-      },
-    };
-    // Clean up deprecated tools.allowed if present (removed in Gemini CLI 1.0)
-    if (geminiSettings.tools?.allowed) {
-      geminiSettings.tools.allowed = geminiSettings.tools.allowed.filter(t => !t.startsWith("mcp_patchcord_"));
-      if (geminiSettings.tools.allowed.length === 0) delete geminiSettings.tools;
+    const geminiOk = updateJsonConfig(geminiPath, (obj) => {
+      obj.mcpServers = obj.mcpServers || {};
+      obj.mcpServers.patchcord = {
+        httpUrl: `${serverUrl}/mcp`,
+        headers: {
+          Authorization: `Bearer ${token}`,
+          "X-Patchcord-Machine": hostname,
+        },
+      };
+      // Clean up deprecated tools.allowed if present (removed in Gemini CLI 1.0)
+      if (obj.tools?.allowed) {
+        obj.tools.allowed = obj.tools.allowed.filter(t => !t.startsWith("mcp_patchcord_"));
+        if (obj.tools.allowed.length === 0) delete obj.tools;
+      }
+    });
+    if (geminiOk) {
+      console.log(`\n  ${green}✓${r} Gemini CLI configured: ${dim}${geminiPath}${r}`);
+      console.log(`  ${yellow}Global config — all Gemini CLI projects share this agent.${r}`);
     }
-    mkdirSync(join(HOME, ".gemini"), { recursive: true });
-    writeFileSync(geminiPath, JSON.stringify(geminiSettings, null, 2) + "\n");
-    console.log(`\n  ${green}✓${r} Gemini CLI configured: ${dim}${geminiPath}${r}`);
-    console.log(`  ${yellow}Global config — all Gemini CLI projects share this agent.${r}`);
   } else if (isZed) {
     // Zed: global settings.json → context_servers
     const zedPath = process.platform === "darwin"
       ? join(HOME, "Library", "Application Support", "Zed", "settings.json")
       : join(HOME, ".config", "zed", "settings.json");
-    let zedSettings = (existsSync(zedPath) && safeReadJson(zedPath)) || {};
-    if (!zedSettings.context_servers) zedSettings.context_servers = {};
-    zedSettings.context_servers.patchcord = {
-      url: `${serverUrl}/mcp`,
-      headers: {
-        Authorization: `Bearer ${token}`,
-        "X-Patchcord-Machine": hostname,
-      },
-    };
-    const zedDir = process.platform === "darwin"
-      ? join(HOME, "Library", "Application Support", "Zed")
-      : join(HOME, ".config", "zed");
-    mkdirSync(zedDir, { recursive: true });
-    writeFileSync(zedPath, JSON.stringify(zedSettings, null, 2) + "\n");
-    console.log(`\n  ${green}✓${r} Zed configured: ${dim}${zedPath}${r}`);
-    console.log(`  ${yellow}Global config — all Zed projects share this agent.${r}`);
+    const zedOk = updateJsonConfig(zedPath, (obj) => {
+      obj.context_servers = obj.context_servers || {};
+      obj.context_servers.patchcord = {
+        url: `${serverUrl}/mcp`,
+        headers: {
+          Authorization: `Bearer ${token}`,
+          "X-Patchcord-Machine": hostname,
+        },
+      };
+    });
+    if (zedOk) {
+      console.log(`\n  ${green}✓${r} Zed configured: ${dim}${zedPath}${r}`);
+      console.log(`  ${yellow}Global config — all Zed projects share this agent.${r}`);
+    }
   } else if (isOpenCode) {
     // OpenCode: per-project opencode.json → mcp
     const ocPath = join(cwd, "opencode.json");
-    let ocConfig = {};
-    if (existsSync(ocPath)) {
-      try {
-        ocConfig = JSON.parse(readFileSync(ocPath, "utf-8"));
-      } catch {}
+    const ocOk = updateJsonConfig(ocPath, (obj) => {
+      obj.mcp = obj.mcp || {};
+      obj.mcp.patchcord = {
+        type: "remote",
+        url: `${serverUrl}/mcp`,
+        headers: {
+          Authorization: `Bearer ${token}`,
+          "X-Patchcord-Machine": hostname,
+        },
+      };
+    });
+    if (ocOk) {
+      console.log(`\n  ${green}✓${r} OpenCode configured: ${dim}${ocPath}${r}`);
     }
-    if (!ocConfig.mcp) ocConfig.mcp = {};
-    ocConfig.mcp.patchcord = {
-      type: "remote",
-      url: `${serverUrl}/mcp`,
-      headers: {
-        Authorization: `Bearer ${token}`,
-        "X-Patchcord-Machine": hostname,
-      },
-    };
-    writeFileSync(ocPath, JSON.stringify(ocConfig, null, 2) + "\n");
-    console.log(`\n  ${green}✓${r} OpenCode configured: ${dim}${ocPath}${r}`);
   } else if (isOpenClaw) {
     // OpenClaw: global ~/.openclaw/openclaw.json → mcp.servers
     // Try CLI first, fall back to direct file write
@@ -785,28 +804,23 @@ if (!cmd || cmd === "install" || cmd === "agent" || cmd?.startsWith("--")) {
       console.log(`\n  ${green}✓${r} OpenClaw configured via CLI: ${dim}openclaw mcp set${r}`);
     } else {
       // CLI not available — write config directly
-      const openclawDir = join(HOME, ".openclaw");
-      const openclawPath = join(openclawDir, "openclaw.json");
-      let openclawConfig = {};
-      if (existsSync(openclawPath)) {
-        try {
-          openclawConfig = JSON.parse(readFileSync(openclawPath, "utf-8"));
-        } catch {}
+      const openclawPath = join(HOME, ".openclaw", "openclaw.json");
+      const openclawOk = updateJsonConfig(openclawPath, (obj) => {
+        obj.mcp = obj.mcp || {};
+        obj.mcp.servers = obj.mcp.servers || {};
+        obj.mcp.servers.patchcord = {
+          url: `${serverUrl}/mcp`,
+          transport: "streamable-http",
+          headers: {
+            Authorization: `Bearer ${token}`,
+            "X-Patchcord-Machine": hostname,
+          },
+          connectionTimeoutMs: 300000,
+        };
+      });
+      if (openclawOk) {
+        console.log(`\n  ${green}✓${r} OpenClaw configured: ${dim}${openclawPath}${r}`);
       }
-      if (!openclawConfig.mcp) openclawConfig.mcp = {};
-      if (!openclawConfig.mcp.servers) openclawConfig.mcp.servers = {};
-      openclawConfig.mcp.servers.patchcord = {
-        url: `${serverUrl}/mcp`,
-        transport: "streamable-http",
-        headers: {
-          Authorization: `Bearer ${token}`,
-          "X-Patchcord-Machine": hostname,
-        },
-        connectionTimeoutMs: 300000,
-      };
-      mkdirSync(openclawDir, { recursive: true });
-      writeFileSync(openclawPath, JSON.stringify(openclawConfig, null, 2) + "\n");
-      console.log(`\n  ${green}✓${r} OpenClaw configured: ${dim}${openclawPath}${r}`);
     }
     console.log(`  ${yellow}Global config — all OpenClaw channels share this agent.${r}`);
     console.log(`  ${dim}Run: openclaw gateway restart${r}`);
@@ -818,32 +832,28 @@ if (!cmd || cmd === "install" || cmd === "agent" || cmd?.startsWith("--")) {
     // Antigravity: global ~/.gemini/antigravity/mcp_config.json → mcpServers
     const agDir = join(HOME, ".gemini", "antigravity");
     const agPath = join(agDir, "mcp_config.json");
-    let agConfig = {};
-    if (existsSync(agPath)) {
-      try {
-        agConfig = JSON.parse(readFileSync(agPath, "utf-8"));
-      } catch {}
+    const agOk = updateJsonConfig(agPath, (obj) => {
+      obj.mcpServers = obj.mcpServers || {};
+      obj.mcpServers.patchcord = {
+        serverUrl: `${serverUrl}/mcp`,
+        headers: {
+          Authorization: `Bearer ${token}`,
+          "X-Patchcord-Machine": hostname,
+        },
+      };
+    });
+    if (agOk) {
+      console.log(`\n  ${green}✓${r} Antigravity configured: ${dim}${agPath}${r}`);
+      // Install global skills
+      const agSkillDir = join(agDir, "skills", "patchcord");
+      const agWaitDir = join(agDir, "skills", "patchcord-wait");
+      mkdirSync(agSkillDir, { recursive: true });
+      mkdirSync(agWaitDir, { recursive: true });
+      cpSync(join(pluginRoot, "skills", "inbox", "SKILL.md"), join(agSkillDir, "SKILL.md"));
+      cpSync(join(pluginRoot, "skills", "wait", "SKILL.md"), join(agWaitDir, "SKILL.md"));
+      console.log(`  ${green}✓${r} Skills installed: ${dim}patchcord${r}, ${dim}patchcord-wait${r}`);
+      console.log(`  ${yellow}Global config — all Antigravity projects share this agent.${r}`);
     }
-    if (!agConfig.mcpServers) agConfig.mcpServers = {};
-    agConfig.mcpServers.patchcord = {
-      serverUrl: `${serverUrl}/mcp`,
-      headers: {
-        Authorization: `Bearer ${token}`,
-        "X-Patchcord-Machine": hostname,
-      },
-    };
-    mkdirSync(agDir, { recursive: true });
-    writeFileSync(agPath, JSON.stringify(agConfig, null, 2) + "\n");
-    console.log(`\n  ${green}✓${r} Antigravity configured: ${dim}${agPath}${r}`);
-    // Install global skills
-    const agSkillDir = join(agDir, "skills", "patchcord");
-    const agWaitDir = join(agDir, "skills", "patchcord-wait");
-    mkdirSync(agSkillDir, { recursive: true });
-    mkdirSync(agWaitDir, { recursive: true });
-    cpSync(join(pluginRoot, "skills", "inbox", "SKILL.md"), join(agSkillDir, "SKILL.md"));
-    cpSync(join(pluginRoot, "skills", "wait", "SKILL.md"), join(agWaitDir, "SKILL.md"));
-    console.log(`  ${green}✓${r} Skills installed: ${dim}patchcord${r}, ${dim}patchcord-wait${r}`);
-    console.log(`  ${yellow}Global config — all Antigravity projects share this agent.${r}`);
   } else if (isCline) {
     // Cline VS Code extension: global cline_mcp_settings.json
     // Config lives in VS Code's globalStorage for saoudrizwan.claude-dev
@@ -884,24 +894,22 @@ if (!cmd || cmd === "install" || cmd === "agent" || cmd?.startsWith("--")) {
     }
 
     const clinePath = join(clineSettingsDir, "cline_mcp_settings.json");
-    let clineConfig = {};
-    if (existsSync(clinePath)) {
-      try { clineConfig = JSON.parse(readFileSync(clinePath, "utf-8")); } catch {}
+    const clineOk = updateJsonConfig(clinePath, (obj) => {
+      obj.mcpServers = obj.mcpServers || {};
+      obj.mcpServers.patchcord = {
+        url: `${serverUrl}/mcp`,
+        headers: {
+          Authorization: `Bearer ${token}`,
+          "X-Patchcord-Machine": hostname,
+        },
+        disabled: false,
+        alwaysAllow: [],
+      };
+    });
+    if (clineOk) {
+      console.log(`\n  ${green}✓${r} Cline configured: ${dim}${clinePath}${r}`);
+      console.log(`  ${yellow}Global config — all Cline projects share this agent.${r}`);
     }
-    if (!clineConfig.mcpServers) clineConfig.mcpServers = {};
-    clineConfig.mcpServers.patchcord = {
-      url: `${serverUrl}/mcp`,
-      headers: {
-        Authorization: `Bearer ${token}`,
-        "X-Patchcord-Machine": hostname,
-      },
-      disabled: false,
-      alwaysAllow: [],
-    };
-    mkdirSync(clineSettingsDir, { recursive: true });
-    writeFileSync(clinePath, JSON.stringify(clineConfig, null, 2) + "\n");
-    console.log(`\n  ${green}✓${r} Cline configured: ${dim}${clinePath}${r}`);
-    console.log(`  ${yellow}Global config — all Cline projects share this agent.${r}`);
   } else if (isVSCode) {
     // VS Code: write .vscode/mcp.json (per-project)
     const vscodeDir = join(cwd, ".vscode");
@@ -920,20 +928,14 @@ if (!cmd || cmd === "install" || cmd === "agent" || cmd?.startsWith("--")) {
       },
     };
 
-    if (existsSync(vscodePath)) {
-      try {
-        const existing = JSON.parse(readFileSync(vscodePath, "utf-8"));
-        existing.servers = existing.servers || {};
-        existing.servers.patchcord = vscodeConfig.servers.patchcord;
-        writeFileSync(vscodePath, JSON.stringify(existing, null, 2) + "\n");
-      } catch {
-        writeFileSync(vscodePath, JSON.stringify(vscodeConfig, null, 2) + "\n");
-      }
-    } else {
-      writeFileSync(vscodePath, JSON.stringify(vscodeConfig, null, 2) + "\n");
+    const vscodeOk = updateJsonConfig(vscodePath, (obj) => {
+      obj.servers = obj.servers || {};
+      obj.servers.patchcord = vscodeConfig.servers.patchcord;
+    });
+    if (vscodeOk) {
+      console.log(`\n  ${green}✓${r} VS Code configured: ${dim}${vscodePath}${r}`);
+      console.log(`  ${dim}Requires GitHub Copilot extension with agent mode enabled.${r}`);
     }
-    console.log(`\n  ${green}✓${r} VS Code configured: ${dim}${vscodePath}${r}`);
-    console.log(`  ${dim}Requires GitHub Copilot extension with agent mode enabled.${r}`);
   } else if (isCodex) {
     // Codex: write MCP config + per-project skills + global plugin
     // Per-project skills (working @patchcord in Codex v0.117)
@@ -1010,19 +1012,17 @@ if (!cmd || cmd === "install" || cmd === "agent" || cmd?.startsWith("--")) {
 
     // Personal marketplace entry (relative path from marketplace root)
     const marketplacePath = join(marketplaceDir, "marketplace.json");
-    let marketplace = { name: "patchcord", interface: { displayName: "Patchcord" }, plugins: [] };
-    if (existsSync(marketplacePath)) {
-      try { marketplace = JSON.parse(readFileSync(marketplacePath, "utf-8")); } catch {}
-    }
-    if (!marketplace.plugins) marketplace.plugins = [];
-    marketplace.plugins = marketplace.plugins.filter(p => p.name !== "patchcord");
-    marketplace.plugins.push({
-      name: "patchcord",
-      source: { source: "local", path: "./patchcord" },
-      policy: { installation: "INSTALLED_BY_DEFAULT", authentication: "ON_INSTALL" },
-      category: "Productivity",
+    updateJsonConfig(marketplacePath, (obj) => {
+      if (!obj.name) obj.name = "patchcord";
+      if (!obj.interface) obj.interface = { displayName: "Patchcord" };
+      obj.plugins = (obj.plugins || []).filter(p => p.name !== "patchcord");
+      obj.plugins.push({
+        name: "patchcord",
+        source: { source: "local", path: "./patchcord" },
+        policy: { installation: "INSTALLED_BY_DEFAULT", authentication: "ON_INSTALL" },
+        category: "Productivity",
+      });
     });
-    writeFileSync(marketplacePath, JSON.stringify(marketplace, null, 2) + "\n");
 
     // Also install global skills (working @patchcord — plugin/read broken in Codex v0.117)
     const globalSkillDir = join(homedir(), ".agents", "skills", "patchcord");
@@ -1052,17 +1052,15 @@ if (!cmd || cmd === "install" || cmd === "agent" || cmd?.startsWith("--")) {
       },
     };
 
-    if (existsSync(mcpPath)) {
-      try {
-        const existing = JSON.parse(readFileSync(mcpPath, "utf-8"));
-        existing.mcpServers = existing.mcpServers || {};
-        existing.mcpServers.patchcord = mcpConfig.mcpServers.patchcord;
-        writeFileSync(mcpPath, JSON.stringify(existing, null, 2) + "\n");
-      } catch {
-        writeFileSync(mcpPath, JSON.stringify(mcpConfig, null, 2) + "\n");
-      }
-    } else {
-      writeFileSync(mcpPath, JSON.stringify(mcpConfig, null, 2) + "\n");
+    const mcpOk = updateJsonConfig(mcpPath, (obj) => {
+      obj.mcpServers = obj.mcpServers || {};
+      obj.mcpServers.patchcord = mcpConfig.mcpServers.patchcord;
+    });
+    if (!mcpOk) {
+      // Existing .mcp.json was malformed — helper already explained.
+      // Bail with non-zero so wrapper scripts notice; the user fixes
+      // their JSON and re-runs.
+      process.exit(1);
     }
     console.log(`\n  ${green}✓${r} Claude Code configured: ${dim}${mcpPath}${r}`);
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "patchcord",
-  "version": "0.5.14",
+  "version": "0.5.16",
   "description": "Cross-machine agent messaging for Claude Code and Codex",
   "author": "ppravdin",
   "license": "MIT",

package/scripts/subscribe.mjs

@@ -16,6 +16,12 @@ import { connect as wsConnect } from "./lib/ws.mjs";
 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];
+// Freshness watchdog: if we haven't received ANY frame from the server
+// (heartbeat replies, postgres_changes, system events) for this long, the
+// WS is silently dead — phx replies should arrive every ~25s, so a 90s
+// gap means three missed heartbeats. Force a reconnect via the outer loop.
+const FRESHNESS_CHECK_INTERVAL_MS = 30_000;
+const FRESHNESS_STALE_MS = 90_000;
 
 // Guarantee a terminal stderr line on any unhandled failure so the agent
 // reading Monitor's output file always sees WHY the process died.
@@ -230,6 +236,8 @@ function runOnce(ticket, baseUrl, token, refreshTicket) {
     let ref = 1;
     let heartbeatTimer = null;
     let refreshTimer = null;
+    let freshnessTimer = null;
+    let lastEventAt = Date.now();
     let currentJwt = ticket.jwt;
     let settled = false;
 
@@ -238,6 +246,7 @@ function runOnce(ticket, baseUrl, token, refreshTicket) {
       settled = true;
       if (heartbeatTimer) clearInterval(heartbeatTimer);
       if (refreshTimer) clearTimeout(refreshTimer);
+      if (freshnessTimer) clearInterval(freshnessTimer);
       try {
         ws.close();
       } catch (_) {}
@@ -283,6 +292,21 @@ function runOnce(ticket, baseUrl, token, refreshTicket) {
         } catch (_) {}
       }, HEARTBEAT_INTERVAL_MS);
 
+      // Freshness watchdog. Phoenix replies to every heartbeat with a
+      // phx_reply frame; if those stop arriving (silent network drop,
+      // backgrounded socket after laptop sleep, server-side eviction
+      // without close frame), the WS appears open but is dead. Force a
+      // reconnect via the outer loop — done(err) increments backoffIdx.
+      freshnessTimer = setInterval(() => {
+        const stale = Date.now() - lastEventAt;
+        if (stale > FRESHNESS_STALE_MS) {
+          process.stderr.write(
+            `subscribe: ws stale ${Math.round(stale / 1000)}s, forcing reconnect\n`
+          );
+          done(new Error(`ws stale ${Math.round(stale / 1000)}s`));
+        }
+      }, FRESHNESS_CHECK_INTERVAL_MS);
+
       const scheduleRefresh = (ttlSec) => {
         const refreshIn = Math.max((ttlSec - JWT_REFRESH_SAFETY_MARGIN_SEC) * 1000, 30_000);
         refreshTimer = setTimeout(doRefresh, refreshIn);
@@ -331,6 +355,10 @@ function runOnce(ticket, baseUrl, token, refreshTicket) {
     });
 
     ws.on("message", (raw) => {
+      // Any inbound frame counts as proof of life — phx_reply, system,
+      // presence_state, postgres_changes, etc. Reset BEFORE the parse
+      // attempt so even malformed frames count.
+      lastEventAt = Date.now();
       let frame;
       try {
         frame = JSON.parse(raw);

package/skills/inbox/SKILL.md

@@ -32,19 +32,30 @@ The user can undo any change in 3 seconds with git. A wrong action costs nothing
 
 ## On session start or when prompted by a hook
 
-Call inbox(). It returns pending messages and recently active agents.
+Call inbox(). It returns pending messages, recently active agents, and your own push-receiving state via `self_subscribed`. Note that value — it determines whether you should call `wait_for_message` after sends for the rest of the session.
+
+If `subscribe_appears_down: true` is in the response, your subscribe.mjs was running but appears dead. Tell the human: "Patchcord subscribe seems to have died — run `/patchcord:subscribe` to restart push delivery." Do not try to restart it yourself.
 
 If there are pending messages, reply to all of them immediately. Do not ask the human first. Do not explain what you plan to reply. Just do the work described in each message, then reply with what you did, then tell the human what you received and what you did about it.
 
 ## Sending
 
-1. inbox() - clear any pending messages that block outbound sends. Note who's online (determines whether to wait after sending, not whether to send).
+1. inbox() - clear any pending messages that block outbound sends. From the response, note `self_subscribed` (your own push-receiving state).
 2. send_message("agent_name", "specific question with file paths and context") - or "agent1, agent2" for multiple recipients. Use `@username` for cross-user Gate messaging. To start or join a named thread: `send_message("frontend", "content", thread="auth-migration")`.
-3. If recipient is online: wait_for_message() - block until response arrives. Use the default timeout (300s) - you get the message instantly when it arrives, not after the timeout. The other agent needs time to do the work and reply. Never shorten the timeout. If offline: skip the wait, tell the human the message is queued.
+3. Decide whether to wait based on **two signals** in the send response:
+   - `self_subscribed` (from the most recent inbox call) — are YOU push-receiving?
+   - `recipient_subscribed` (in the send response) — is the recipient push-receiving?
+
+   | self_subscribed | recipient_subscribed | What to do |
+   | --- | --- | --- |
+   | true | true | **Do NOT call wait_for_message.** Continue working. Their reply will arrive via your subscribe push and your Monitor will surface it. Tell the human: "Sent — [agent] will see it within seconds." |
+   | true | false | **Do NOT call wait_for_message.** Continue working. Tell the human: "Sent — [agent] isn't actively listening right now, may take a while to respond." |
+   | false | true | **Call wait_for_message** with default timeout. Recipient is live, expect a reply soon. |
+   | false | false | **Skip wait_for_message.** Tell the human: "Sent — [agent] isn't currently active. Ask them to check inbox in their session." |
 
-Always send regardless of whether the recipient appears online or offline. Messages are stored and delivered when the recipient checks inbox. "Offline" means not recently active - not that they can't receive messages.
+Always send regardless of recipient state. Messages are stored and delivered when the recipient checks inbox.
 
-After sending to an offline agent, tell the human: "Message sent. [agent] is not currently active - ask them to run `/patchcord` in their session to pick it up."
+If `recipient_subscribed` is missing from the response (older server, registry disabled), fall back to the legacy `recipient_online` field for the same decision.
 
 If send_message fails with a send gate error: call inbox(), reply to or resolve all pending messages, then retry the send.
 
@@ -57,7 +68,7 @@ If send_message fails with a send gate error: call inbox(), reply to or resolve
    - `reply(message_id, "done: [details]", resolve=true)` — work done, thread closed. Stamps `thread_resolved_at` and notifies sender.
    - `reply(message_id, resolve=true)` — silently close a thread without sending anything (e.g. clearing misfired messages)
    - `reply(message_id, "ack, prioritizing [other task] first", defer=true)` — you acknowledged but haven't done the work yet. The message stays in your inbox as a reminder.
-4. wait_for_message() if the sender is online - stay responsive for follow-ups
+4. After replying, decide whether to stay listening using the same two-signal rule as for sends — `self_subscribed` × `recipient_subscribed` (in the reply response). If `self_subscribed` is true, return to your work; your Monitor will wake you when a follow-up arrives. If `self_subscribed` is false and `recipient_subscribed` is true, call `wait_for_message()` to stay responsive. Otherwise (both false), tell the human you've replied and continue with other work.
 5. If you can't do the work, say specifically what's blocking you. Don't guess about another agent's code.
 
 When you have multiple pending messages, prioritize by urgency. Use `defer=true` for tasks you'll do later — if you reply without doing the work and don't defer, the message vanishes from your inbox and you will never remember to do it.