patchcord 0.6.40 → 0.6.42

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

package/bin/patchcord.mjs

@@ -993,7 +993,27 @@ if (cmd === "subscribe") {
     spawnEnv.PATCHCORD_BEARER_TOKEN = bearerInfo.token;
   }
   const { spawnSync } = await import("child_process");
-  const result = spawnSync(process.execPath, [subscribeScript], {
+  // FORWARD argv. This used to spawn [subscribeScript] with no arguments, so
+  // every flag a user typed was silently thrown away between the wrapper and
+  // the script that reads it.
+  //
+  // What that broke: subscribe.mjs gates its Hermes webhook bridge on
+  // `process.argv.includes("--hermes")` — its OWN argv. Our Hermes skill tells
+  // the human to run `PATCHCORD_HERMES_WEBHOOK=<url> patchcord subscribe
+  // --hermes`. The env var arrived, the flag did not, and the flag is the gate.
+  // notify() then took the `!HERMES_MODE` branch and wrote to a stdout no
+  // Hermes gateway reads. The listener ran. Nothing was ever woken. No error.
+  // The `--hermes <url>` inline form was worse: it has no env fallback at all.
+  //
+  // Forward everything rather than allow-listing `--hermes`. An allow-list
+  // fixes today and leaves the trap armed: the next person adds a child-side
+  // flag, reads subscribe.mjs, sees it handled, and never looks at these eight
+  // lines. Same silent failure, new flag name. Reported by lead@mux-v2, who
+  // asked for the fix in this shape rather than the narrow one.
+  //
+  // `--kimi` never hit this because the kimi branch above parses it here in the
+  // parent and re-passes the interval explicitly. That was luck, not design.
+  const result = spawnSync(process.execPath, [subscribeScript, ...args], {
     stdio: "inherit",
     env: spawnEnv,
   });
@@ -4037,21 +4057,71 @@ if (!cmd || cmd === "install" || cmd === "agent" || cmd?.startsWith("--")) {
         console.log(`  ${green}✓${r} Cleaned PATCHCORD_TOKEN from .env`);
       }
     }
-    // Clean up old per-project slash commands (deprecated in Codex v0.117+)
-    for (const dir of [join(codexDir, "prompts"), join(homedir(), ".codex", "prompts")]) {
-      for (const f of ["patchcord.md", "patchcord-wait.md"]) {
-        const p = join(dir, f);
-        if (existsSync(p)) { unlinkSync(p); }
-      }
-    }
+    // We do NOT touch .codex/prompts/ — not the project one, not the home one.
+    //
+    // We used to write /patchcord and /patchcord-wait there, then a later commit
+    // deleted them on every install. Both halves were wrong to keep.
+    //
+    // Writing them is pointless: Codex stopped loading $CODEX_HOME/prompts
+    // entirely. Verified on 0.145 — a probe file at ~/.codex/prompts/pctest.md
+    // and at ./.codex/prompts/pcproj.md both give "no matches" in the slash
+    // menu, while /us still filters to /usage, so the menu itself works.
+    // OpenAI marks custom prompts deprecated and says "use skills instead";
+    // openai/codex#15941 reports the 0.117 break and was closed "not planned".
+    //
+    // Deleting them is worse than pointless. A user still on Codex < 0.117 has
+    // WORKING slash commands, and the delete loop took them away on the next
+    // install. It gave that user nothing back. `@patchcord` is the replacement
+    // and it is installed below via the skills path.
+    //
+    // If you are tempted to re-add either half, run the probe first. Do not
+    // trust this comment and do not trust the docs.
+
     // Clean up old per-project skill (now installed as global plugin)
     const oldSkillPath = join(cwd, ".agents", "skills", "patchcord", "SKILL.md");
     if (existsSync(oldSkillPath)) { unlinkSync(oldSkillPath); }
 
-    // Install Codex plugin at ~/.agents/plugins/patchcord/ (personal marketplace)
-    const pluginVersion = JSON.parse(readFileSync(join(pluginRoot, "package.json"), "utf-8")).version;
+    // Install the Codex plugin.
+    //
+    // TWO DIFFERENT DIRECTORIES, and putting them in one place is the bug this
+    // replaces. The marketplace FILE lives at ~/.agents/plugins/marketplace.json.
+    // The plugin BODY lives at ~/plugins/patchcord. A `source.path` in that file
+    // resolves against HOME — NOT against the directory holding the file.
+    //
+    // We previously wrote the body to ~/.agents/plugins/patchcord and pointed at
+    // "./patchcord". Codex read that as ~/patchcord, which never existed, so:
+    //
+    //   $ codex plugin list
+    //   patchcord@patchcord   not installed   /home/now/patchcord
+    //
+    // The plugin has never once installed. Only the ~/.agents/skills/ copy
+    // written further down kept @patchcord alive, which is why nobody noticed.
+    //
+    // The layout below is OpenAI's own, from the bundled plugin-creator skill
+    // (~/.codex/skills/.system/plugin-creator/): the scaffold writes bodies to
+    // ~/plugins/<name>, and its SKILL.md states "In either location, the
+    // generated source path remains ./plugins/<plugin-name>".
+    //
+    // Verify with `codex plugin list` after changing this. STATUS must not say
+    // "not installed", and PATH must be a directory that exists.
+    // Codex caches an installed plugin BY VERSION under ~/.codex/plugins/cache/.
+    // Re-running the installer on the same release therefore reinstalls nothing,
+    // and re-running it is the normal way people pick up a fix. So append the
+    // cachebuster suffix Codex defines for exactly this case — the format is
+    // `+codex.<token>`, per the bundled plugin-creator helper
+    // (~/.codex/skills/.system/plugin-creator/scripts/update_plugin_cachebuster.py).
+    const basePluginVersion = JSON.parse(readFileSync(join(pluginRoot, "package.json"), "utf-8")).version;
+    const pluginVersion = `${basePluginVersion}+codex.${new Date().toISOString().replace(/[-:T]/g, "").slice(0, 14)}`;
     const marketplaceDir = join(homedir(), ".agents", "plugins");
-    const pluginDir = join(marketplaceDir, "patchcord");
+    const pluginDir = join(homedir(), "plugins", "patchcord");
+
+    // Remove the body from the old, never-loadable location. Leaving it behind
+    // makes `plugin list` ambiguous and keeps a stale copy of the skills on disk.
+    const deadPluginDir = join(marketplaceDir, "patchcord");
+    if (existsSync(join(deadPluginDir, ".codex-plugin", "plugin.json"))) {
+      try { rmSync(deadPluginDir, { recursive: true, force: true }); } catch {}
+    }
+
     mkdirSync(join(pluginDir, ".codex-plugin"), { recursive: true });
     mkdirSync(join(pluginDir, "skills", "patchcord"), { recursive: true });
     mkdirSync(join(pluginDir, "skills", "patchcord-wait"), { recursive: true });
@@ -4081,7 +4151,7 @@ if (!cmd || cmd === "install" || cmd === "agent" || cmd?.startsWith("--")) {
     writeFileSync(join(pluginDir, "skills", "patchcord-wait", "SKILL.md"),
       readFileSync(join(pluginRoot, "skills", "wait", "SKILL.md"), "utf-8"));
 
-    // Personal marketplace entry (relative path from marketplace root)
+    // Personal marketplace entry. `path` is relative to HOME, not to this file.
     const marketplacePath = join(marketplaceDir, "marketplace.json");
     updateJsonConfig(marketplacePath, (obj) => {
       if (!obj.name) obj.name = "patchcord";
@@ -4089,24 +4159,71 @@ if (!cmd || cmd === "install" || cmd === "agent" || cmd?.startsWith("--")) {
       obj.plugins = (obj.plugins || []).filter(p => p.name !== "patchcord");
       obj.plugins.push({
         name: "patchcord",
-        source: { source: "local", path: "./patchcord" },
+        source: { source: "local", path: "./plugins/patchcord" },
         policy: { installation: "INSTALLED_BY_DEFAULT", authentication: "ON_INSTALL" },
         category: "Productivity",
       });
     });
 
-    // Also install global skills (working @patchcord — plugin/read broken in Codex v0.117)
+    // Writing the marketplace entry does NOT install the plugin. Codex leaves it
+    // at "not installed" until this runs, `INSTALLED_BY_DEFAULT` notwithstanding.
+    // We never ran it, which is the second half of why the plugin was dead.
+    // The command is `plugin add`, not `plugin install` — see
+    // ~/.codex/skills/.system/plugin-creator/references/installing-and-updating.md.
+    //
+    // Not run() — run() has no timeout, and this is the one call here that talks
+    // to another program's install path. The marketplace entry sets
+    // authentication ON_INSTALL, so a future Codex could decide to ask. An
+    // installer that hangs forever is worse than one that skips the plugin, and
+    // skipping is survivable: the ~/.agents/skills/ fallback below covers it.
+    let pluginAdded = false;
+    try {
+      execSync(`codex plugin add patchcord@patchcord`,
+        { stdio: "pipe", encoding: "utf-8", timeout: 30_000 });
+      pluginAdded = true;
+    } catch { pluginAdded = false; }
+
+    // ~/.agents/skills/ holds the SAME two skills as a fallback. Codex reads that
+    // tree directly, with no marketplace and no install step, so @patchcord works
+    // there even when the plugin does not load.
+    //
+    // EXACTLY ONE of the two may exist at a time. Codex reads both and shows both.
+    // With the plugin installed AND the fallback present, `@patchcord` lists:
+    //
+    //   Patchcord                   Cross-machine agent messaging          Plugin
+    //   patchcord                   Cross-agent messaging for Codex …      Skill
+    //   patchcord (patchcord)       Cross-agent messaging for Codex …      Skill
+    //   patchcord-wait              Block this turn for up to 5 minutes …  Skill
+    //   patchcord:wait (patchcord)  Block this turn for up to 5 minutes …  Skill
+    //
+    // Five entries for two skills. Observed, not predicted — an earlier version
+    // of this comment asserted they would not collide, and that was wrong.
     const globalSkillDir = join(homedir(), ".agents", "skills", "patchcord");
-    mkdirSync(globalSkillDir, { recursive: true });
-    writeFileSync(join(globalSkillDir, "SKILL.md"),
-      readFileSync(join(pluginRoot, "per-project-skills", "codex", "SKILL.md"), "utf-8"));
     const globalWaitDir = join(homedir(), ".agents", "skills", "patchcord-wait");
-    mkdirSync(globalWaitDir, { recursive: true });
-    writeFileSync(join(globalWaitDir, "SKILL.md"),
-      readFileSync(join(pluginRoot, "skills", "wait", "SKILL.md"), "utf-8"));
+    if (pluginAdded) {
+      for (const d of [globalSkillDir, globalWaitDir]) {
+        if (existsSync(d)) { try { rmSync(d, { recursive: true, force: true }); } catch {} }
+      }
+    } else {
+      mkdirSync(globalSkillDir, { recursive: true });
+      writeFileSync(join(globalSkillDir, "SKILL.md"),
+        readFileSync(join(pluginRoot, "per-project-skills", "codex", "SKILL.md"), "utf-8"));
+      mkdirSync(globalWaitDir, { recursive: true });
+      writeFileSync(join(globalWaitDir, "SKILL.md"),
+        readFileSync(join(pluginRoot, "skills", "wait", "SKILL.md"), "utf-8"));
+    }
 
     console.log(`\n  ${green}✓${r} Codex configured: ${dim}${configPath}${r}`);
-    console.log(`  ${green}✓${r} Plugin installed: ${dim}@patchcord${r}, ${dim}@patchcord-wait${r}`);
+    if (pluginAdded) {
+      console.log(`  ${green}✓${r} Plugin installed: ${dim}${pluginDir}${r}`);
+    } else {
+      // Say it plainly. A silent failure here still leaves @patchcord working
+      // through ~/.agents/skills/, so this is a downgrade, not a breakage.
+      console.log(`  ${yellow}!${r} Codex plugin did not install (${dim}codex plugin add patchcord@patchcord${r})`);
+      console.log(`  ${dim}Skills still work. Check with: codex plugin list${r}`);
+    }
+    console.log(`  ${green}✓${r} Type ${dim}@patchcord${r} or ${dim}@patchcord-wait${r} in Codex`);
+    console.log(`  ${dim}Codex dropped custom slash commands — @ is the picker now.${r}`);
   } else {
     // Claude Code: write .mcp.json
     const mcpPath = join(cwd, ".mcp.json");

package/harnesses.json

@@ -0,0 +1,228 @@
+{
+  "$comment": [
+    "Machine-readable harness capability registry. Consumed by mux (lead@mux-v2) to decide",
+    "whether a seat can hold a Patchcord listener and whether two seats may share a host.",
+    "",
+    "TWO SCOPE FIELDS ON PURPOSE. `installer_scope` is where OUR installer writes.",
+    "`harness_scope` is what the HARNESS itself supports. They are not the same question and",
+    "conflating them is what this file exists to prevent: in one thread I answered three",
+    "harness-capability questions with installer behaviour and was wrong all three times.",
+    "hermes is the worked example — our installer writes one global file, and hermes supports",
+    "many isolated profiles. 'Our installer writes X' never implies 'the harness only does X'.",
+    "",
+    "EVIDENCE IS EARNED, NOT TYPED. This file may only ever say \"declared\" or \"absent\".",
+    "\"tested\" is not a legal value here — it lives in tests/test-harness-registry.mjs, in a",
+    "list that names what was observed and by whom. A writer can type a confident guess into",
+    "a data file; a writer cannot type an observation into a test they did not run. If you",
+    "believe a row deserves \"tested\", add it there with the observation, not here.",
+    "",
+    "Any row whose listener.wake is not \"none\" MUST have a real subscribe path on disk, or",
+    "carry blocked_reason saying why not. hermes is why: it HAS a subscribe skill directory",
+    "and, until 0.6.41, could not actually be armed. Directory presence is necessary, never",
+    "sufficient."
+  ],
+  "version": 1,
+  "harnesses": [
+    {
+      "id": "claude_code",
+      "aliases": ["claude"],
+      "cli": "claude",
+      "kind": "terminal",
+      "installer_scope": "project",
+      "installer_config": ".mcp.json",
+      "harness_scope": "project",
+      "listener": {
+        "wake": "realtime",
+        "mechanism": "subscribe-skill-under-monitor",
+        "self_arm": true,
+        "survives_wake": true,
+        "evidence": "declared"
+      }
+    },
+    {
+      "id": "codex",
+      "aliases": [],
+      "cli": "codex",
+      "kind": "terminal",
+      "installer_scope": "project",
+      "installer_config": ".codex/config.toml",
+      "harness_scope": "project",
+      "listener": {
+        "wake": "none",
+        "mechanism": "stop-hook-nudge-only",
+        "self_arm": false,
+        "survives_wake": null,
+        "evidence": "declared",
+        "note": "A stop hook fires at the END of a turn. An idle codex seat hears nothing. No subscribe skill exists for codex in this package."
+      }
+    },
+    {
+      "id": "cursor",
+      "aliases": [],
+      "cli": "cursor-agent",
+      "kind": "terminal",
+      "installer_scope": "project",
+      "installer_config": ".cursor/mcp.json",
+      "harness_scope": "unknown",
+      "listener": {
+        "wake": "realtime",
+        "mechanism": "subscribe-skill-background-shell",
+        "self_arm": true,
+        "survives_wake": null,
+        "evidence": "declared",
+        "note": "The skill claims it wakes the agent. Nobody in this repo has watched it happen."
+      }
+    },
+    {
+      "id": "grok",
+      "aliases": ["grok_cli", "grok_build"],
+      "cli": "grok",
+      "kind": "terminal",
+      "installer_scope": "project",
+      "installer_config": ".grok/config.toml",
+      "harness_scope": "project",
+      "listener": {
+        "wake": "realtime",
+        "mechanism": "subscribe-skill",
+        "self_arm": true,
+        "survives_wake": null,
+        "evidence": "declared",
+        "note": "Grok resolves configs from cwd up to the git root, so per-seat identity works. Wake is claimed by the skill, not observed."
+      }
+    },
+    {
+      "id": "opencode",
+      "aliases": [],
+      "cli": "opencode",
+      "kind": "terminal",
+      "installer_scope": "project",
+      "installer_config": "opencode.json",
+      "harness_scope": "unknown",
+      "listener": {
+        "wake": "realtime",
+        "mechanism": "installed-plugin",
+        "self_arm": true,
+        "survives_wake": true,
+        "evidence": "declared",
+        "note": "The installer writes .opencode/plugins/patchcord.js, which spawns `patchcord subscribe` and calls client.session.prompt() on each message. It prompts on the realtime event rather than session.idle deliberately: session.idle re-prompting has a teardown race in headless `opencode run`."
+      }
+    },
+    {
+      "id": "kimi",
+      "aliases": [],
+      "cli": "kimi",
+      "kind": "terminal",
+      "installer_scope": "project",
+      "installer_config": ".kimi-code/mcp.json",
+      "harness_scope": "unknown",
+      "listener": {
+        "wake": "poll",
+        "mechanism": "poll-script",
+        "self_arm": true,
+        "survives_wake": false,
+        "evidence": "declared",
+        "note": "NOT realtime. patchcord-subscribe.sh polls /api/inbox and EXITS 0 on a pending count; Kimi starts a turn when a background task reaches a terminal state. So the listener dies on every delivery and the agent must re-arm it. Re-arm is the failure point: an agent that skips it is silently deaf from then on."
+      }
+    },
+    {
+      "id": "hermes",
+      "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.",
+      "listener": {
+        "wake": "realtime",
+        "mechanism": "webhook-bridge",
+        "self_arm": false,
+        "survives_wake": true,
+        "evidence": "declared",
+        "note": "`patchcord subscribe --hermes` POSTs to a Hermes gateway webhook per message; the gateway injects a prompt. No re-arm needed. self_arm is false: a human creates the route and starts the bridge once. A deploy that waits N seconds for a SEAT-started listener will fail hermes forever while hermes is fully push-capable.",
+        "blocked_until": "0.6.41",
+        "blocked_reason": "Before 0.6.41 the `patchcord subscribe` wrapper spawned subscribe.mjs with no arguments, so --hermes never reached the child that gates on it. The env var arrived, the flag did not, the flag is the gate. The bridge was unreachable by its own documented command and failed silently. Fixed; not yet observed end to end."
+      }
+    },
+    {
+      "id": "antigravity",
+      "aliases": ["agy"],
+      "cli": "antigravity",
+      "kind": "terminal",
+      "installer_scope": "project",
+      "installer_config": ".agents/mcp_config.json",
+      "harness_scope": "unknown",
+      "listener": {
+        "wake": "none",
+        "mechanism": null,
+        "self_arm": false,
+        "survives_wake": null,
+        "evidence": "declared",
+        "note": "No subscribe skill of any kind in this package."
+      }
+    },
+    {
+      "id": "openclaw",
+      "aliases": [],
+      "cli": "openclaw",
+      "kind": "terminal",
+      "installer_scope": "unknown",
+      "installer_config": "~/.openclaw/openclaw.json",
+      "harness_scope": "unknown",
+      "listener": {
+        "wake": "none",
+        "mechanism": null,
+        "self_arm": false,
+        "survives_wake": null,
+        "evidence": "absent",
+        "note": "installer_scope is unknown, not global. We PREFER `openclaw mcp set patchcord`, so openclaw decides where the entry lands; the ~/.openclaw path is only our fallback when that CLI is missing. Nobody here has openclaw installed. Do not refuse a second openclaw seat on the strength of this row — refuse on a test or not at all."
+      }
+    },
+    {
+      "id": "windsurf",
+      "aliases": [],
+      "cli": null,
+      "kind": "editor",
+      "installer_scope": "global",
+      "installer_config": "~/.codeium/windsurf/mcp_config.json",
+      "harness_scope": "unknown",
+      "listener": { "wake": "none", "mechanism": null, "self_arm": false, "survives_wake": null, "evidence": "declared" }
+    },
+    {
+      "id": "vscode",
+      "aliases": [],
+      "cli": null,
+      "kind": "editor",
+      "installer_scope": "project",
+      "installer_config": ".vscode/mcp.json",
+      "harness_scope": "unknown",
+      "listener": { "wake": "none", "mechanism": null, "self_arm": false, "survives_wake": null, "evidence": "declared" }
+    },
+    {
+      "id": "zed",
+      "aliases": [],
+      "cli": null,
+      "kind": "editor",
+      "installer_scope": "global",
+      "installer_config": "~/.config/zed/settings.json",
+      "harness_scope": "unknown",
+      "listener": { "wake": "none", "mechanism": null, "self_arm": false, "survives_wake": null, "evidence": "declared" }
+    },
+    {
+      "id": "cline",
+      "aliases": [],
+      "cli": null,
+      "kind": "editor",
+      "installer_scope": "global",
+      "installer_config": "cline_mcp_settings.json (VS Code globalStorage)",
+      "harness_scope": "unknown",
+      "listener": { "wake": "none", "mechanism": null, "self_arm": false, "survives_wake": null, "evidence": "declared" }
+    }
+  ],
+  "retired": [
+    {
+      "id": "gemini",
+      "reason": "Retired as an install target; Antigravity covers Google's agent. CLIENT_TYPE_MAP slot \"5\" is left UNASSIGNED rather than reused, so a stale connect page sending client_type=gemini falls through to no choice instead of silently configuring a different harness and writing someone's token to the wrong file. Do not mirror the gap as a bug and do not fill it."
+    }
+  ]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "patchcord",
-  "version": "0.6.40",
+  "version": "0.6.42",
   "description": "Cross-machine agent messaging for Claude Code and Codex",
   "scripts": {
     "version": "node scripts/sync-plugin-version.mjs && git add .claude-plugin/plugin.json"
@@ -32,6 +32,7 @@
     "per-project-skills/",
     "commands/",
     "README.md",
-    "plugins/"
+    "plugins/",
+    "harnesses.json"
   ]
 }