agent-coord-mcp 0.17.1 → 0.19.0

package/hooks/tmux-pusher.mjs

@@ -39,11 +39,24 @@
  * while this daemon runs — both consume the same cursor and would race.
  *
  * Caveats:
- *   - Pasting types into whatever pane state exists. If you're mid-typing in
- *     the same pane, your buffer gets corrupted. Run the receiving agent in a
- *     dedicated pane you don't normally edit in.
- *   - The pusher can't tell if the agent is idle, mid-tool, or showing a
- *     permission prompt. send-keys is unconditional.
+ *   - PEER MESSAGES paste into whatever pane state exists. If you're mid-typing
+ *     in the same pane, your buffer gets corrupted. Run the receiving agent in
+ *     a dedicated pane you don't normally edit in.
+ *   - CONTROL COMMANDS (/clear, /compact) are the exception: since they paste
+ *     RAW, a pane that is busy or holds an unsent draft would either queue them
+ *     behind a running turn or append them to the draft and ship the result to
+ *     the model as ordinary text — both observed live, both reporting
+ *     delivery:"confirmed". So control submission is CONDITIONAL: it waits
+ *     (bounded) for a busy pane to go idle, refuses to paste onto a draft, and
+ *     verifies via capture-pane that the command left the input. An unverified
+ *     submission reports delivery:"pending" with a reason, never "confirmed".
+ *     See hooks/submit.mjs, shared with scripts/coord-pusher.mjs.
+ *   - CLEANUP: never `pkill -f tmux-pusher.mjs` — the pattern matches EVERY
+ *     pusher on the bus, and one agent's test-rig cleanup doing exactly that
+ *     silently detached all four live agents (2026-07-28). attach_agent puts
+ *     `--agent <id>` in argv so a pattern kill can be scoped to one agent
+ *     (`pkill -f "tmux-pusher.mjs --agent <id>"`); better still, use
+ *     detach_agent or the pid file — both target the exact pid.
  */
 
 import {
@@ -56,10 +69,14 @@ import {
   unlinkSync,
   watch,
 } from "node:fs";
+import { readdirSync, statSync } from "node:fs";
 import { homedir } from "node:os";
+import { fileURLToPath } from "node:url";
 import path from "node:path";
 import { spawn, spawnSync } from "node:child_process";
 import { effectiveTier, isGateRunnerRole, TierQueue, formatBatch } from "./tier.mjs";
+import { mergeTransportMarker } from "./marker.mjs";
+import { pasteAndSubmit as sharedPasteAndSubmit, submitControl as sharedSubmitControl } from "./submit.mjs";
 
 const AGENT_ID = process.env.AGENT_COORD_ID;
 const TMUX_TARGET = process.env.AGENT_COORD_TMUX_TARGET;
@@ -103,7 +120,9 @@ function refreshTierCtx() {
   try {
     const reg = JSON.parse(readFileSync(path.join(ROOT, "agents.json"), "utf8"));
     for (const [id, entry] of Object.entries(reg ?? {})) {
-      if (isGateRunnerRole(entry?.role)) trusted.add(id);
+      // Pass the whole entry: the frozen roleId lives beside `role`, and
+      // reading only the display string would throw the identity away.
+      if (isGateRunnerRole(entry)) trusted.add(id);
     }
     gateRunner = trusted.has(AGENT_ID);
   } catch {
@@ -129,6 +148,30 @@ const TRANSPORT_FILE = path.join(ROOT, "transports", `${SAFE_ID}.json`);
 // entering any agent's context. Mirrors RECEIPTS_DIR in src/store.ts.
 const RECEIPTS_FILE = path.join(ROOT, "receipts", `${SAFE_ID}.jsonl`);
 const BUFFER_NAME = `coord-${SAFE_ID}`;
+// Newest mtime across this script AND its sibling hooks modules, sampled once
+// at startup — an upgrade to any of them afterwards leaves this value behind,
+// which is exactly what doctor's stale-pusher-script check compares against.
+// The entry file alone is not enough: control submission lives in submit.mjs
+// and tiering in tier.mjs/roles.mjs, so a fix touching only an import would
+// leave a single-file stamp unchanged and a still-running pusher on the old
+// code would read as fresh. Scanning the whole dir over-covers (a hooks file
+// we never import can flag us stale) — that is the safe direction: a spurious
+// re-attach is loud and cheap, a false green silently invalidates the rollout
+// verification of every pusher-side fix.
+const SCRIPT_MTIME = (() => {
+  try {
+    const dir = path.dirname(fileURLToPath(import.meta.url));
+    let newest;
+    for (const f of readdirSync(dir)) {
+      if (!f.endsWith(".mjs")) continue;
+      const m = statSync(path.join(dir, f)).mtimeMs;
+      if (newest === undefined || m > newest) newest = m;
+    }
+    return newest;
+  } catch {
+    return undefined;
+  }
+})();
 
 mkdirSync(path.dirname(CURSOR_FILE), { recursive: true });
 mkdirSync(path.dirname(TRANSPORT_FILE), { recursive: true });
@@ -234,7 +277,15 @@ function collectSource(label, file, cursorKey, cur, staged) {
   if (fresh.length === 0) return;
   for (const m of fresh) {
     if (shouldInject(m)) {
-      const tagged = { kind: label, ...m };
+      // The channel tag lives in `tag`, not `kind`. A stored Message carries
+      // its own `kind` ("decision"/"status"/"chatter" — retention weight);
+      // sharing the name meant a room post tagged kind:"decision" (what the
+      // README recommends for GOs and verdicts) overwrote the channel tag and
+      // rendered as `[decision …]` instead of `[#general …]`, breaking
+      // injectLine's parse contract. Distinct names remove the collision at
+      // the source; assignment still follows the spread so a sender cannot
+      // smuggle a `tag` in either.
+      const tagged = { ...m, tag: label };
       // Assigned after the spread so a sender can't smuggle a tier field in.
       tagged.tier = effectiveTier(tagged, tierCtx);
       staged.msgs.push(tagged);
@@ -259,7 +310,7 @@ function collectRoomChannel(chan, cur, staged) {
   if (fresh.length === 0) return;
   for (const m of fresh) {
     if (shouldInject(m)) {
-      const tagged = { kind: `room #${c}`, ...m };
+      const tagged = { ...m, tag: `room #${c}` }; // see channel-tag note above
       tagged.tier = effectiveTier(tagged, tierCtx);
       staged.msgs.push(tagged);
     }
@@ -378,8 +429,11 @@ async function injectViaTmux(batch) {
   for (const m of batch) {
     if (isControl(m)) {
       await flushRun();
-      await pasteAndSubmit(m.text.trim(), false); // validated control: raw slash command
-      writeReceipts([m]);
+      // Control commands are VERIFIED: capture-pane confirms the command
+      // actually left the input. A receipt that says "typed" was being read
+      // as "ran" — see writeReceipts.
+      const outcome = await submitControlCommand(m.text.trim());
+      writeReceipts([m], outcome);
     } else {
       run.push(m);
     }
@@ -391,7 +445,12 @@ async function injectViaTmux(batch) {
 // pane. Receipts are out-of-band proof for the sender (it polls this file),
 // never injected into any agent's context — so verification costs zero tokens.
 // Best-effort: a failed receipt write must not break delivery, so we swallow.
-function writeReceipts(msgs) {
+// `outcome` (control commands only) carries what verification actually saw.
+// WITHOUT it a receipt proved the pusher TYPED the command, and send_command
+// reported that as delivery:"confirmed" — proof of typing sold as proof of
+// execution. `submitted` is the honest field: false means it is still sitting
+// in the input, and the sender is told so instead of being reassured.
+function writeReceipts(msgs, outcome) {
   const lines = [];
   for (const m of msgs) {
     if (!m || !m.id) continue;
@@ -402,6 +461,13 @@ function writeReceipts(msgs) {
         ts: Date.now(),
         from: m.from,
         control: m.control === true,
+        ...(outcome
+          ? {
+              submitted: outcome.submitted === true,
+              verified: outcome.verified === true,
+              ...(outcome.reason ? { reason: outcome.reason } : {}),
+            }
+          : {}),
       }),
     );
   }
@@ -417,45 +483,29 @@ function writeReceipts(msgs) {
 // a compliant TUI treats the payload as inert data — embedded newlines can't
 // submit lines or smuggle a "/command". Control commands (/clear, /compact) must
 // paste RAW (bracketed=false) so the TUI still runs them as slash commands.
+//
+// The pipeline itself lives in ./submit.mjs, shared with scripts/coord-pusher.mjs
+// so the two cannot drift again. This wrapper only supplies tmux.
+const tmuxDeps = {
+  target: TMUX_TARGET,
+  buffer: BUFFER_NAME,
+  run: (args) => spawnSync("tmux", args, { encoding: "utf8" }),
+  runStdin: (args, payload) =>
+    new Promise((resolve, reject) => {
+      const load = spawn("tmux", args);
+      load.on("error", reject);
+      load.on("exit", (code) => (code === 0 ? resolve() : reject(new Error(`tmux ${args[0]} exit ${code}`))));
+      load.stdin.end(payload);
+    }),
+};
+
 function pasteAndSubmit(payload, bracketed = false) {
-  return new Promise((resolve, reject) => {
-    const load = spawn("tmux", ["load-buffer", "-b", BUFFER_NAME, "-"]);
-    load.on("error", reject);
-    load.on("exit", (code) => {
-      if (code !== 0) return reject(new Error(`tmux load-buffer exit ${code}`));
-      const paste = spawnSync("tmux", [
-        "paste-buffer",
-        ...(bracketed ? ["-p"] : []),
-        "-b",
-        BUFFER_NAME,
-        "-t",
-        TMUX_TARGET,
-        "-d",
-      ]);
-      if (paste.status !== 0) {
-        return reject(new Error(`tmux paste-buffer: ${(paste.stderr ?? "").toString().trim()}`));
-      }
-      // Multi-line paste + Enter is racy: long buffers can still be flushing
-      // to the target app's input when Enter arrives, and many TUIs (Claude
-      // Code in particular) treat that first Enter as "still drafting,
-      // add newline" rather than "submit." Wait briefly so paste settles,
-      // then send Enter. Some apps additionally need a second Enter to
-      // exit paste-mode + submit; sending two Enters with a small gap is
-      // safe (worst case: harmless empty submit ignored by the app). For a
-      // slash command this also dismisses the autocomplete menu and submits.
-      setTimeout(() => {
-        const e1 = spawnSync("tmux", ["send-keys", "-t", TMUX_TARGET, "Enter"]);
-        if (e1.status !== 0) {
-          return reject(new Error(`tmux send-keys: ${(e1.stderr ?? "").toString().trim()}`));
-        }
-        setTimeout(() => {
-          spawnSync("tmux", ["send-keys", "-t", TMUX_TARGET, "Enter"]);
-          resolve();
-        }, 50);
-      }, 100);
-    });
-    load.stdin.end(payload);
-  });
+  return sharedPasteAndSubmit(tmuxDeps, payload, { bracketed });
+}
+
+// Control commands go through the preflight + verify path, never the plain one.
+function submitControlCommand(payload) {
+  return sharedSubmitControl(tmuxDeps, payload);
 }
 
 // Publish transport marker so list_agents can show this agent is push-capable.
@@ -470,24 +520,60 @@ const cleanupMarker = () => {
     // already gone
   }
 };
+// Log BEFORE cleaning up. A silent exit that also removes its own marker is
+// indistinguishable from "never attached" — on 2026-07-28 all four pushers on
+// the bus vanished at once and the cause could not be determined afterwards,
+// because every other exit path logs and this one did not. Ruled out at the
+// time: dead-pane self-exit (logs), die() (logs), SIGKILL/OOM (the marker
+// would have survived), a normal exit (the poll intervals are not unref'd),
+// doctor's reaper (has-session returned 0 for every live pane), tests (all
+// isolate AGENT_COORD_DIR), coord-chat (not running), stop-agent.sh (would
+// have killed the session too) and a parent process-group signal (the pusher
+// has its own PGID and SID). That left a signal from outside the repo, with
+// nothing recorded to identify it.
+function logSignal(sig) {
+  process.stderr.write(
+    `[tmux-pusher] received ${sig} — cleaning up marker for '${AGENT_ID}' (pane ${TMUX_TARGET}, pid ${process.pid}) and exiting\n`,
+  );
+}
+
 process.on("SIGINT", () => {
+  logSignal("SIGINT");
   cleanupMarker();
   process.exit(0);
 });
 process.on("SIGTERM", () => {
+  logSignal("SIGTERM");
   cleanupMarker();
   process.exit(0);
 });
 process.on("exit", cleanupMarker);
 
 function writeTransportMarker() {
-  const marker = {
+  // Merge over the existing marker, never rebuild from scratch: attach_agent
+  // wrote it first and owns fields only the server can know (its
+  // serverBuildMtime provenance stamp, and whatever comes next). A
+  // from-scratch rewrite here once dropped scriptMtime and silently disabled
+  // doctor's stale-pusher-script check — see hooks/marker.mjs.
+  let existing;
+  try {
+    existing = JSON.parse(readFileSync(TRANSPORT_FILE, "utf8"));
+  } catch {
+    existing = undefined; // first writer, or unreadable — our own fields stand alone
+  }
+  const marker = mergeTransportMarker(existing, {
     agentId: AGENT_ID,
     transport: "tmux-push",
     pid: process.pid,
     tmuxTarget: TMUX_TARGET,
     since: Date.now(),
-  };
+    // MUST be included: attach_agent stamps this too, but this write happens
+    // afterwards and would otherwise clobber it — and doctor SKIPS markers
+    // without it (pre-v0.8.2 shape), so dropping it silently disabled the
+    // stale-pusher-script check for every local pusher. Our own stamp is the
+    // more truthful value anyway: it reflects the code THIS process loaded.
+    scriptMtime: SCRIPT_MTIME,
+  });
   const tmp = TRANSPORT_FILE + ".tmp";
   writeFileSync(tmp, JSON.stringify(marker));
   renameSync(tmp, TRANSPORT_FILE);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-coord-mcp",
-  "version": "0.17.1",
+  "version": "0.19.0",
   "description": "File-backed MCP server for coordinating multiple AI coding agents (Claude Code, Cursor, Cline, etc.). Local stdio or networked over Streamable HTTP.",
   "type": "module",
   "bin": {
@@ -10,11 +10,12 @@
   },
   "scripts": {
     "build": "tsc",
-    "prepare": "tsc",
+    "prepare": "node scripts/check-self-dependency.mjs && tsc",
     "start": "node dist/server.js",
     "dev": "tsx src/server.ts",
-    "pretest": "tsc",
-    "test": "node --test \"test/*.test.mjs\""
+    "pretest": "node scripts/check-self-dependency.mjs && tsc",
+    "test": "node scripts/check-test-count.mjs",
+    "test:raw": "node --test \"test/*.test.mjs\""
   },
   "files": [
     "dist",

package/scripts/check-self-dependency.mjs

@@ -0,0 +1,54 @@
+#!/usr/bin/env node
+// Guards against this package's own name appearing in its own dependency
+// graph. A self-dependency makes `npm install` resolve against an old
+// published copy instead of the local source, silently breaking dev installs.
+//
+// It has happened ONCE, not repeatedly — verified 2026-07-29 by `git log -S`
+// over the whole history under both the current name and the pre-rename
+// `claude-coord-mcp`: commit de4e1ee (2026-06-06) added
+// "agent-coord-mcp": "^0.8.0" to dependencies, and 3bce3ce removed it six
+// days later. An earlier version of this comment claimed two reintroductions,
+// one of them manual; that second one is not in the history.
+//
+// What made the one occurrence dangerous is worth keeping, because it
+// generalises: de4e1ee is titled `chore: npm audit fix` and its body says
+// "Lockfile-only dependency bumps, non-breaking" — while also rewriting a
+// dependency block. It passed review BECAUSE the message said the manifest
+// was untouched; a reviewer reads the claim, not the diff. This guard is
+// cheap insurance against that class, not evidence of a recurring bug.
+//
+// Runs on `prepare` (every install), `pretest`, and `prepublishOnly`.
+import { readFileSync } from "node:fs";
+
+const pkg = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
+const DEP_FIELDS = ["dependencies", "devDependencies", "optionalDependencies", "peerDependencies"];
+
+function selfDepFields(manifest) {
+  return DEP_FIELDS.filter(
+    (field) => manifest[field] && Object.prototype.hasOwnProperty.call(manifest[field], pkg.name),
+  );
+}
+
+const offenders = selfDepFields(pkg);
+
+let lockOffender = false;
+try {
+  const lock = JSON.parse(readFileSync(new URL("../package-lock.json", import.meta.url), "utf8"));
+  const rootPkg = lock.packages?.[""];
+  if (rootPkg && selfDepFields(rootPkg).length) lockOffender = true;
+} catch {
+  /* no lockfile yet (fresh checkout pre-install) — nothing to check */
+}
+
+if (offenders.length || lockOffender) {
+  console.error(
+    `[check-self-dependency] "${pkg.name}" depends on itself` +
+      (offenders.length ? ` in package.json's ${offenders.join(", ")}` : "") +
+      (lockOffender ? `${offenders.length ? " and" : " in"} package-lock.json's root package` : "") +
+      `.\nThis happened once before, added by an "npm audit fix" whose commit message said it was ` +
+      `lockfile-only (de4e1ee, removed in 3bce3ce — see docs/DONE.md). If you just ran an audit or ` +
+      `dependency update, check what else it changed in package.json. ` +
+      `Remove the self-reference from both files and re-run "npm install".`,
+  );
+  process.exit(1);
+}

package/scripts/check-test-count.mjs

@@ -0,0 +1,83 @@
+#!/usr/bin/env node
+// Run the suite and assert it ran the number of tests we expect.
+//
+// WHY: `npm test` was twice observed reporting FOUR fewer tests with zero
+// failures (119→115, 145→141), never reproducible on a re-run. A suite whose
+// count silently varies cannot be used as a gate signal — "all green" and "a
+// file failed to load" look identical. This is the same silent-undercount
+// class as a QUEUE parser returning zero items while passing every test.
+//
+// So the count is an assertion, not a statistic. A short run fails loudly.
+//
+// It compares PASS, not `# tests`. The first version compared `# tests`, and
+// the sighting that followed showed why that was the wrong number: the runner
+// reported `# tests 186 / # pass 182 / # fail 0` — its own totals not adding
+// up, four results landing in no bucket at all. `# tests` read the full 186, so
+// the guard would have passed a run in which four results were lost. The
+// anomaly is a reporter gap, not a short run, and only the pass count sees it.
+//
+// When you add or remove tests, update EXPECTED_TESTS in the same commit —
+// that is the point, not an inconvenience. `AGENT_COORD_EXPECTED_TESTS=n`
+// overrides for a one-off (bisecting, a partial run); `=0` disables the check.
+
+import { spawn } from "node:child_process";
+
+const EXPECTED_TESTS = 226;
+
+const expected = Number(process.env.AGENT_COORD_EXPECTED_TESTS ?? EXPECTED_TESTS);
+// Same glob the suite always used — `--test test/` would recurse differently
+// on some node versions, and a runner that selects a different set of files
+// is exactly the failure this script exists to catch.
+const child = spawn(process.execPath, ["--test", "test/*.test.mjs"], {
+  stdio: ["inherit", "pipe", "inherit"],
+  shell: false,
+});
+
+let out = "";
+child.stdout.on("data", (chunk) => {
+  out += chunk;
+  process.stdout.write(chunk);
+});
+
+child.on("exit", (code, signal) => {
+  if (signal) process.exit(1);
+  // The TAP summary lines the runner prints once, at the end.
+  const num = (label) => {
+    const m = out.match(new RegExp(`^# ${label} (\\d+)$`, "m"));
+    return m ? Number(m[1]) : null;
+  };
+  const tests = num("tests");
+  const pass = num("pass");
+  const fail = num("fail");
+
+  if (code !== 0 || (fail ?? 0) > 0) process.exit(code || 1);
+
+  if (expected === 0) {
+    console.log(`[check-test-count] count assertion disabled (ran ${tests ?? "?"} tests)`);
+    process.exit(0);
+  }
+  if (pass === null) {
+    console.error("[check-test-count] FAIL — no '# pass' summary line in the runner output");
+    process.exit(1);
+  }
+  // The runner's own totals disagreeing is its own finding — report it as such
+  // rather than as a count mismatch, so nobody chases a missing test file.
+  if (tests !== null && tests !== pass + (fail ?? 0)) {
+    console.error(
+      `\n[check-test-count] FAIL — the runner's totals do not add up: ${tests} tests, ${pass} pass, ${fail ?? 0} fail.\n` +
+        `  ${tests - pass - (fail ?? 0)} result(s) landed in no bucket. This is a reporter gap, not a missing test file.\n`,
+    );
+    process.exit(1);
+  }
+  if (pass !== expected) {
+    console.error(
+      `\n[check-test-count] FAIL — ${pass} tests passed, expected ${expected}.\n` +
+        (pass < expected
+          ? `  ${expected - pass} result(s) missing. Zero failures does NOT mean green here: a file that fails to load reports nothing.\n` +
+            `  Re-run; if the count is stable, a test file is missing or erroring at import.\n`
+          : `  ${pass - expected} test(s) were added. Update EXPECTED_TESTS in scripts/check-test-count.mjs in the same commit.\n`),
+    );
+    process.exit(1);
+  }
+  console.log(`[check-test-count] ${pass} tests passed, as expected.`);
+});