agent-coord-mcp 0.17.0 → 0.18.0

package/hooks/tier.mjs

@@ -1,6 +1,6 @@
-// Pure delivery-tier logic for the pusher. Dependency-free and
-// side-effect-free so it can be unit-tested directly and adds no I/O to the
-// delivery hot path.
+// Pure delivery-tier logic for the pusher. Side-effect-free, and its only
+// import (./roles.mjs) is equally pure — so it can be unit-tested directly and
+// adds no I/O to the delivery hot path.
 //
 // "urgent" = push now (wakes the target agent's model).
 // "routine" = queue silently; it rides along as a coalesced digest on the
@@ -9,6 +9,41 @@
 // All prefix checks are case-sensitive: the protocol prefixes are uppercase
 // by convention, and a lowercase lookalike is chatter, not a work order.
 
+import { isGateRunner } from "./roles.mjs";
+
+// Typed protocol record → tier (Phase 8). The prefix table below is the same
+// vocabulary parsed out of text; reading the field instead removes the parse
+// entirely, so a body that leads with a greeting no longer downgrades a
+// blocker to routine.
+//
+// TRUST: `record` is caller-supplied, exactly like `from`. A typed record may
+// therefore assert what a text prefix could already assert, and NOTHING more —
+// `scope` resolves the sender against trustedSenders and `done` depends on the
+// RECIPIENT being a gate runner, exactly as the prefix path does. `go` is
+// unconditionally urgent here because literal "GO:" is unconditionally urgent
+// in the prefix path too; do NOT "fix" that asymmetry by gating go, and do not
+// ungate scope to match go — each mirrors its v1 prefix, which is the whole
+// invariant. Typed is not authenticated: anything that would let a peer
+// self-declare urgency belongs in the server-set `urgent` flag, not here.
+function tierFromRecord(rec, m, opts) {
+  switch (rec.type) {
+    case "blocker":
+    case "decision":
+      return "urgent";
+    case "go":
+      return "urgent";
+    case "scope":
+      return opts.trustedSenders?.has?.(m.from) ? "urgent" : "routine";
+    case "done":
+      return opts.gateRunner ? "urgent" : "routine";
+    // risk / fyi / action / verdict: real semantics, but not a reason to
+    // interrupt someone else's turn. A risk that genuinely needs an immediate
+    // turn is a blocker — that judgement stays with the sender.
+    default:
+      return "routine";
+  }
+}
+
 export function classifyTier(m, opts = {}) {
   if (!m) return "routine";
   // Server-set push-now override (post-/clear reminder). send_message builds
@@ -18,7 +53,39 @@ export function classifyTier(m, opts = {}) {
   // wants it specifically, and DM volume is tiny next to room traffic. The
   // tiers exist to absorb broadcast noise, not point-to-point asks (the
   // liaison relaying a David question must not sit in a digest queue).
-  if (m.kind === "DM") return "urgent";
+  //
+  // `tag`, not `kind`: this is the pushers' synthetic channel tag ("DM" /
+  // "room #general"), set on their own copy of the message. It used to be
+  // called `kind`, which collided with the stored Message.kind (retention
+  // weight, "decision"/"status"/"chatter") — a room post tagged
+  // kind:"decision" overwrote the channel tag and rendered as `[decision …]`.
+  // The tag is process-local and never persisted, so it was the safe half of
+  // the collision to rename; Message.kind is on disk in every JSONL file.
+  // NOTE: this returns before the record is read, so a DM can never be
+  // downgraded by one. The floor rule below makes that moot, but the ordering
+  // is load-bearing if anyone reintroduces a record-first branch.
+  if (m.tag === "DM") return "urgent";
+  // The record is a FLOOR, not an override: it can raise the tier, never lower
+  // it. An earlier version let the record win outright, on the argument that
+  // Task 3 renders text from the record so the two agree by construction. That
+  // is false when BOTH are supplied — contract 3.3 makes the author's `text`
+  // win for rendering, so `{text:"BLOCKER: prod down", record:{type:"fyi"}}`
+  // displayed a BLOCKER in the pane and delivered it routine, with the reader
+  // unable to see why (`record` is never rendered). That is a REGRESSION IN A
+  // SAFETY PROPERTY: in v1, "BLOCKER:" at byte 0 always woke the pane. The
+  // trigger is ordinary relay, not malice — an aide forwarding a worker's body
+  // under its own `fyi` would silently bury that worker's blocker.
+  //
+  // max() is not the two-overridable-sources design this phase exists to
+  // delete: it is monotone, so there is nothing to disagree about, only a
+  // higher claim winning. It also fails safe on an UNKNOWN future record type,
+  // which hits the routine default — an old pusher meeting a new vocabulary
+  // must not bury a "BLOCKER:" body. The one legitimate downgrade, quoting a
+  // blocker mid-body, is already handled by the byte-0 rule.
+  // Found by ai-workflow-worker-1 gating 721882a.
+  if (m.record && typeof m.record.type === "string") {
+    if (tierFromRecord(m.record, m, opts) === "urgent") return "urgent";
+  }
   if (typeof m.text !== "string") return "routine";
   const text = m.text.trimStart();
   // Control/slash commands are injected raw and must fire immediately.
@@ -46,10 +113,16 @@ export function effectiveTier(m, opts = {}) {
 }
 
 // A gate runner is the agent that consumes DONE: reports (QA / coordinator).
-// Resolved from the registry role, with an env override in both directions
-// (AGENT_COORD_GATE_RUNNER=1|0).
+// Resolved from the registry role's frozen `roleId` (Phase 8 Task 4) rather
+// than by regex-matching display prose, so renaming the role does not change
+// who runs the gate. Registry entries with no declared roleId fall back to the
+// legacy word match — see roleMatches in roles.mjs. Env override in both
+// directions (AGENT_COORD_GATE_RUNNER=1|0) is applied by the caller.
+//
+// Accepts a plain string or a whole registry entry ({role, roleId}); pass the
+// entry when you have it, or the id is lost.
 export function isGateRunnerRole(role) {
-  return /\b(qa|quality|coordinator|gate)\b/i.test(role ?? "");
+  return isGateRunner(role);
 }
 
 // In-memory routine queue with the push decision. Ingest classified messages;
@@ -96,15 +169,35 @@ export class TierQueue {
 // The per-message PARSE CONTRACT line. Agent harnesses read from/room/text
 // back out of this, so its shape is load-bearing and MUST stay byte-identical
 // to coord-pusher.mjs's `injectLine`. Compact form (v0.14.0, salvaged from
-// v0.8.10): `  [<kind> <HH:MM> <from>] <text>` where kind drops the leading
+// v0.8.10): `  [<tag> <HH:MM> <from>] <text>` where tag drops the leading
 // "room " ("room #general" → "#general"), the timestamp is HH:MM UTC, and the
-// "from=" label is dropped (bare id). kind/time/from never contain spaces
+// "from=" label is dropped (bare id). tag/time/from never contain spaces
 // (ids are sanitized), so a parser splits on the first "] " unambiguously.
 export function injectLine(m) {
-  const tag = String(m.kind ?? "").replace(/^room /, "");
+  const tag = String(m.tag ?? "").replace(/^room /, "");
   const d = new Date(m.ts ?? 0);
   const hhmm = `${String(d.getUTCHours()).padStart(2, "0")}:${String(d.getUTCMinutes()).padStart(2, "0")}`;
-  return `  [${tag} ${hhmm} ${m.from}] ${m.text ?? ""}`;
+  let text = m.text ?? "";
+  // Phase 8 Task 6: a TYPED record whose rendering spans lines is delivered as
+  // ONE attributed line — first line, a count of what was withheld, and the
+  // message id as the retrieval handle. Continuation lines used to arrive bare,
+  // with no `[tag HH:MM from]` header, so a parser could not attribute them.
+  //
+  // The handle is the message id, NOT a stashed copy: the full record is
+  // already persisted in rooms/<chan>.jsonl or inbox/<id>.jsonl, and
+  // retrieve_message reads it back by id (falling through to the append-only
+  // archive if compaction moved it). A cache would have had a TTL and lost the
+  // record permanently on expiry.
+  //
+  // Gated on `m.record`: a record-LESS multi-line message is untouched and
+  // still arrives unattributed past line 1, exactly as today. Task 6 does not
+  // fix hand-typed multi-line messages, and must not change their bytes.
+  const nl = text.indexOf("\n");
+  if (nl !== -1 && m.record && typeof m.record.type === "string" && m.id) {
+    const held = text.split("\n").length - 1;
+    text = `${text.slice(0, nl)} [+${held} lines · record:${m.record.type} · retrieve_message id=${m.id}]`;
+  }
+  return `  [${tag} ${hhmm} ${m.from}] ${text}`;
 }
 
 // Render one delivery: urgent verbatim under the banner, then at most ONE

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.0",
+  "version": "0.18.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,42 @@
+#!/usr/bin/env node
+// Guards against a recurring defect (see docs/QUEUE.md P1): this package's
+// own name has twice been reintroduced into its own dependency graph —
+// once manually, once by an `npm audit fix` run (commit de4e1ee added
+// "agent-coord-mcp": "^0.8.0" back into dependencies while patching
+// fast-uri/hono/ip-address/qs). A self-dependency makes `npm install`
+// resolve against an old published copy of this package instead of the
+// local source, silently breaking dev installs. Run on every `npm install`
+// (via the "prepare" script) so a reintroduction fails loudly and
+// immediately instead of sitting unnoticed until the next audit.
+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 has recurred before — a prior "npm audit fix" run reintroduced it (see docs/QUEUE.md P1). ` +
+      `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 = 218;
+
+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.`);
+});