patchcord 0.6.42 → 0.6.44

package/scripts/build-agent-plugin.mjs

@@ -0,0 +1,215 @@
+#!/usr/bin/env node
+/**
+ * Generate the Agent Plugins 1.0.0 distribution at ./agent-plugin/.
+ *
+ * PURELY ADDITIVE. This does not touch .claude-plugin/, skills/, hooks/,
+ * commands/, or anything the current installer writes. Every existing harness
+ * keeps working exactly as it does today; the generated directory is a second,
+ * parallel packaging of the same content for clients that load the open
+ * standard (Codex/ChatGPT, Cursor, GitHub Copilot, Kiro, VS Code).
+ *
+ * WHY GENERATED RATHER THAN HAND-WRITTEN
+ *
+ * The skills are the same skills. Copying them by hand would create two
+ * SKILL.md bodies that drift, and the drift would be silent — both files stay
+ * valid, they just stop agreeing. Deriving them means the source of truth
+ * remains ./skills/ and this script is the only thing that has to be re-run.
+ *
+ * THE ONE TRANSFORM APPLIED
+ *
+ * Our skills declare `name: patchcord:inbox`. The Agent Skills specification
+ * that Agent Plugins defers to requires the name to be lowercase alphanumeric
+ * plus hyphens ONLY (a colon is invalid) and to MATCH THE PARENT DIRECTORY.
+ * Every real Codex plugin on this machine follows that rule.
+ *
+ * So the generated copies get `name: <directory>`. The originals are left
+ * alone, because that string is what Claude Code surfaces as
+ * `/patchcord:inbox` and renaming it in place would change a user-facing
+ * command name to fix a spec violation nobody is currently enforcing. Two
+ * packagings, two conventions, one body.
+ */
+
+import { readFileSync, writeFileSync, mkdirSync, readdirSync, rmSync, existsSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const ROOT = join(dirname(fileURLToPath(import.meta.url)), "..");
+const OUT = join(ROOT, "agent-plugin");
+const SKILLS_SRC = join(ROOT, "skills");
+
+const pkg = JSON.parse(readFileSync(join(ROOT, "package.json"), "utf-8"));
+const VERSION = pkg.version;
+const BASE_URL = "https://mcp.patchcord.dev";
+
+// Regenerate from scratch so a skill deleted upstream does not linger here.
+if (existsSync(OUT)) rmSync(OUT, { recursive: true });
+mkdirSync(join(OUT, ".codex-plugin"), { recursive: true });
+
+/* ---------- skills: copied, with `name` rewritten to the directory ---------- */
+
+const skillNames = readdirSync(SKILLS_SRC, { withFileTypes: true })
+  .filter((d) => d.isDirectory() && existsSync(join(SKILLS_SRC, d.name, "SKILL.md")))
+  .map((d) => d.name);
+
+if (skillNames.length === 0) {
+  console.error("build-agent-plugin: no skills found under ./skills — refusing to emit an empty plugin");
+  process.exit(1);
+}
+
+for (const name of skillNames) {
+  const body = readFileSync(join(SKILLS_SRC, name, "SKILL.md"), "utf-8");
+  // Replace only the `name:` line inside the leading frontmatter block. Anchored
+  // to the start of the file so a later `name:` in prose cannot be hit.
+  const fm = body.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  if (!fm) {
+    console.error(`build-agent-plugin: ${name}/SKILL.md has no frontmatter — refusing to guess`);
+    process.exit(1);
+  }
+  const rewritten = body.replace(/^(---\r?\n[\s\S]*?)^name:[ \t]*.*$/m, `$1name: ${name}`);
+  if (rewritten === body && !new RegExp(`^name:[ \\t]*${name}\\s*$`, "m").test(fm[1])) {
+    console.error(`build-agent-plugin: could not rewrite name: in ${name}/SKILL.md`);
+    process.exit(1);
+  }
+  mkdirSync(join(OUT, "skills", name), { recursive: true });
+  writeFileSync(join(OUT, "skills", name, "SKILL.md"), rewritten);
+}
+
+/* ---------- Agent Plugins 1.0.0 core: plugin.json + mcp.json ---------- */
+
+// The AP manifest schema is CLOSED (additionalProperties: false). Only the
+// fields it names may appear — notably there is no `skills` pointer, because
+// the spec fixes that location at ./skills/ rather than letting a manifest
+// redirect it.
+writeFileSync(join(OUT, "plugin.json"), JSON.stringify({
+  $schema: "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
+  name: "patchcord",
+  version: VERSION,
+  description: pkg.description,
+  author: { name: "ppravdin", url: "https://patchcord.dev" },
+  homepage: "https://patchcord.dev",
+  repository: "https://github.com/ppravdin/patchcord",
+  license: pkg.license,
+  keywords: pkg.keywords,
+}, null, 2) + "\n");
+
+// NOTE THE MISSING CREDENTIAL, DELIBERATELY.
+//
+// Agent Plugins 1.0.0 defines placeholder expansion for ${PLUGIN_ROOT} and
+// ${PLUGIN_DATA} ONLY, and only in `args`, `env`, and `cwd`. `headers` is not
+// in that list, and the spec has no host-environment passthrough at all. So
+// there is no conformant way to say "put THIS user's bearer in the
+// Authorization header" in this file.
+//
+// Writing `"Authorization": "Bearer ${PATCHCORD_TOKEN}"` here would produce a
+// file that looks correct and sends the literal string `${PATCHCORD_TOKEN}` to
+// the server. That is worse than an obviously incomplete file, so this one is
+// obviously incomplete: it names the endpoint and the transport and stops.
+//
+// Clients supply the missing half through their own extensions — Codex via
+// `bearer_token_env_var` in .mcp.json (below), VS Code via `envFile`/`headers`.
+// See agent-plugin/README.md.
+writeFileSync(join(OUT, "mcp.json"), JSON.stringify({
+  $schema: "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json",
+  mcpServers: {
+    patchcord: { type: "streamable-http", url: `${BASE_URL}/mcp` },
+  },
+}, null, 2) + "\n");
+
+/* ---------- Codex client files ---------- */
+
+// Codex reads .codex-plugin/plugin.json with POINTER fields (skills, mcpServers)
+// rather than the spec's fixed locations, so it needs its own manifest. Both
+// live in one directory without colliding: different filenames, different paths.
+writeFileSync(join(OUT, ".codex-plugin", "plugin.json"), JSON.stringify({
+  name: "patchcord",
+  version: VERSION,
+  description: pkg.description,
+  author: { name: "ppravdin", url: "https://patchcord.dev" },
+  homepage: "https://patchcord.dev",
+  repository: "https://github.com/ppravdin/patchcord",
+  license: pkg.license,
+  keywords: pkg.keywords,
+  skills: "./skills/",
+  mcpServers: "./.mcp.json",
+}, null, 2) + "\n");
+
+// `bearer_token_env_var` is Codex's own field — it names an environment
+// variable to read the token FROM, so the credential never enters this file.
+// That is what makes the plugin publishable: it carries no secret and is
+// identical for every user.
+writeFileSync(join(OUT, ".mcp.json"), JSON.stringify({
+  mcpServers: {
+    patchcord: {
+      type: "http",
+      url: `${BASE_URL}/mcp`,
+      bearer_token_env_var: "PATCHCORD_TOKEN",
+    },
+  },
+}, null, 2) + "\n");
+
+/* ---------- README (emitted, because this directory is wiped each build) ---------- */
+
+writeFileSync(join(OUT, "README.md"), `# patchcord — Agent Plugins 1.0.0 packaging
+
+**Generated. Do not edit by hand** — run \`node scripts/build-agent-plugin.mjs\`.
+This whole directory is deleted and rewritten on every build.
+
+This is an EXPERIMENTAL second packaging of the same skills and the same MCP
+server. It replaces nothing. \`npx patchcord\` and every per-harness config the
+installer writes are untouched and keep working exactly as before.
+
+## What is in here
+
+| File | Read by | Purpose |
+|---|---|---|
+| \`plugin.json\` | Agent Plugins clients | The open-standard manifest. Required: \`$schema\`, \`name\`. |
+| \`mcp.json\` | Agent Plugins clients | Standard MCP declaration. **Carries no credential — see below.** |
+| \`.codex-plugin/plugin.json\` | Codex | Codex uses pointer fields (\`skills\`, \`mcpServers\`) instead of the spec's fixed locations. |
+| \`.mcp.json\` | Codex | Codex MCP config, with the token read from an env var. |
+| \`skills/*/SKILL.md\` | both | Copied from \`../skills/\`, with \`name:\` rewritten to the directory name. |
+
+## The credential, and why \`mcp.json\` looks incomplete
+
+Agent Plugins 1.0.0 expands \`\${PLUGIN_ROOT}\` and \`\${PLUGIN_DATA}\` only, and
+only inside \`args\`, \`env\`, and \`cwd\`. \`headers\` is not in that list and there
+is no host-environment passthrough anywhere in the spec.
+
+So **the standard has no way to express "use this user's bearer token"**, and
+patchcord is nothing but a per-project bearer token. Writing
+\`"Authorization": "Bearer \${PATCHCORD_TOKEN}"\` into \`mcp.json\` would send that
+literal string to the server. The file therefore names the endpoint and the
+transport and stops, rather than looking complete and failing at runtime.
+
+Clients close the gap with their own extensions, which is where the token
+actually comes from:
+
+- **Codex** — \`bearer_token_env_var\` in \`.mcp.json\`, pointing at
+  \`$PATCHCORD_TOKEN\`.
+- **VS Code** — \`envFile\` / \`headers\`, neither of which is in the core schema.
+
+This is the one finding worth taking upstream: the portable core can carry the
+server's identity everywhere, but not its credential.
+
+## Trying it in Codex
+
+The marketplace is already registered, so:
+
+\`\`\`bash
+export PATCHCORD_TOKEN=<an agent bearer for the namespace you want>
+codex plugin add patchcord-ap@patchcord-marketplace
+\`\`\`
+
+Remove it with \`codex plugin remove patchcord-ap@patchcord-marketplace\`. The
+existing \`patchcord@patchcord-marketplace\` entry is unaffected either way.
+
+## Known limitation: one token per environment
+
+\`$PATCHCORD_TOKEN\` is a single value per shell, while patchcord's model is one
+namespace per project. A plugin installed this way is therefore **one identity
+per environment**, not one per project — the same constraint that already
+applies to Hermes, and the reason the current per-project installer writes
+per-directory config instead. Do not use this packaging for multi-seat work
+until the standard grows a per-project secret mechanism.
+`);
+
+console.log(`build-agent-plugin: wrote agent-plugin/ (v${VERSION}, skills: ${skillNames.join(", ")})`);

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/resolve-project-bearer.mjs

@@ -126,6 +126,43 @@ const opencodeReader = (cwd) => readJsonAt(join(cwd, "opencode.json"), ["mcp", "
 const antigravityReader = (cwd) => readJsonAt(join(cwd, ".agents", "mcp_config.json"), ["mcpServers", "patchcord"], "antigravity");
 const grokReader = (cwd) => readGrokTomlShape(join(cwd, ".grok", "config.toml"));
 const codexReader = (cwd) => readCodexTomlShape(join(cwd, ".codex", "config.toml"));
+// jcode: STDIO entry, so the bearer is in `args`, not in `headers`. readJsonAt
+// cannot see it -- extractBearer requires headers.Authorization and a url, and
+// this entry has neither. jcode has no HTTP transport, so an entry shaped like
+// every other harness's would be dropped at load time, and a reader shaped like
+// every other harness's finds nothing.
+//
+// Keyed on `patchcord-jcode`, matching what the installer writes. The distinct
+// name exists so jcode's own merge (.jcode/mcp.json, then .mcp.json, then
+// .claude/mcp.json -- later overriding by NAME) can never make jcode adopt
+// claude_code's credential.
+function readJcodeStdioShape(path) {
+  if (!existsSync(path)) return null;
+  try {
+    const obj = parseJsonc(readFileSync(path, "utf-8"));
+    const entry = obj?.mcpServers?.["patchcord-jcode"];
+    const args = Array.isArray(entry?.args) ? entry.args : null;
+    if (!args) return null;
+    // `--header` `Authorization: Bearer <token>` as two adjacent argv items.
+    let token = null;
+    for (let i = 0; i < args.length; i++) {
+      const m = typeof args[i] === "string" && args[i].match(/^Authorization:\s*Bearer\s+(\S+)$/i);
+      if (m) { token = m[1]; break; }
+    }
+    const urlArg = args.find((a) => typeof a === "string" && /^https?:\/\//.test(a));
+    if (!token || !urlArg) return null;
+    return {
+      token,
+      baseUrl: urlArg.replace(/\/mcp(\/bearer)?$/, ""),
+      configFile: path,
+      tool: "jcode",
+    };
+  } catch {
+    return null;
+  }
+}
+
+const jcodeReader = (cwd) => readJcodeStdioShape(join(cwd, ".jcode", "mcp.json"));
 const kimiReader = (cwd) => readJsonAt(join(cwd, ".kimi", "mcp.json"), ["mcpServers", "patchcord"], "kimi");
 const kimiCodeReader = (cwd) => readJsonAt(join(cwd, ".kimi-code", "mcp.json"), ["mcpServers", "patchcord"], "kimi");
 
@@ -163,6 +200,7 @@ export function projectReadersForContext(ctx) {
     grok: grokReader,
     codex: codexReader,
     kimi: kimiCodeReader,
+    jcode: jcodeReader,
   };
   const defaultReaders = [
     claudeReader,
@@ -172,6 +210,7 @@ export function projectReadersForContext(ctx) {
     antigravityReader,
     grokReader,
     codexReader,
+    jcodeReader,
   ];
   const kimiReaders = [kimiReader, kimiCodeReader];
 
@@ -199,6 +238,7 @@ export function projectReadersForContext(ctx) {
       antigravityReader,
       grokReader,
       codexReader,
+      jcodeReader,
       claudeReader,
       ...kimiReaders,
     ];

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/scripts/sync-plugin-version.mjs

@@ -10,15 +10,30 @@ import { readFileSync, writeFileSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import { dirname, join } from "node:path";
 
+// EVERY manifest, not the one that existed when this was written. A second
+// packaged plugin (agent-plugin/) arrived later and this script did not know
+// about it, so a merge left it claiming 0.6.40 inside a 0.6.42 package — the
+// same drift the comment above describes, reappearing the moment a new manifest
+// was added. A list is what stops the next one being missed: add the path here
+// and the sync is automatic, rather than a step someone must remember.
 const root = join(dirname(fileURLToPath(import.meta.url)), "..");
 const pkg = JSON.parse(readFileSync(join(root, "package.json"), "utf8"));
-const manifestPath = join(root, ".claude-plugin", "plugin.json");
-const manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
+const MANIFESTS = [
+  join(root, ".claude-plugin", "plugin.json"),
+  join(root, "agent-plugin", "plugin.json"),
+];
 
-if (manifest.version === pkg.version) {
-  process.exit(0);
+for (const manifestPath of MANIFESTS) {
+  let manifest;
+  try {
+    manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
+  } catch {
+    // A manifest that is not present is not an error — agent-plugin/ is built
+    // in some trees and not others. A manifest that is present and STALE is.
+    continue;
+  }
+  if (manifest.version === pkg.version) continue;
+  manifest.version = pkg.version;
+  writeFileSync(manifestPath, JSON.stringify(manifest, null, 2) + "\n");
+  process.stderr.write(`synced ${manifestPath} version -> ${pkg.version}\n`);
 }
-
-manifest.version = pkg.version;
-writeFileSync(manifestPath, JSON.stringify(manifest, null, 2) + "\n");
-process.stderr.write(`synced plugin.json version -> ${pkg.version}\n`);

package/skills/inbox/SKILL.md

@@ -114,7 +114,7 @@ To message a user outside your namespace, use `@username` as the to_agent. Examp
 ```
 patchcord upload /path/to/report.md --mime text/markdown
 ```
-Prints the storage path. Pass that path to `send_message`. No curl, no base64 in chat, no presigned URLs. 25MB cap.
+Prints the storage path. Pass that path to `send_message`. No curl, no base64 in chat, no presigned URLs. The size limit is the server's, not a number to remember: it is 10 MiB by default and a self-hosted server can raise it. If a file is too large the command prints the server's own limit.
 
 **Public URLs → `attachment(relay=true, ...)`:**
 ```