agent-coord-mcp 0.17.0 → 0.18.0

package/scripts/coord-pusher.mjs

@@ -37,6 +37,7 @@
 
 import { hostname } from "node:os";
 import { spawn, spawnSync } from "node:child_process";
+import { pasteAndSubmit as sharedPasteAndSubmit, submitControl as sharedSubmitControl } from "../hooks/submit.mjs";
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
 
@@ -83,17 +84,36 @@ try {
 // Call a tool and JSON-parse the wrapped text content. The server's tool
 // handlers return { content: [{ type:"text", text: JSON.stringify(payload) }] }
 // (see jsonResult in src/server.ts), so we unwrap exactly once.
-async function call(name, args) {
+//
+// { strict: true } makes an MCP tool error (isError:true — e.g. an
+// identity-mismatch on register/report_transport) throw instead of being
+// silently returned as parsed data. Startup uses this so a failed
+// register/report_transport can't be mistaken for success.
+async function call(name, args, { strict = false } = {}) {
   // SDK zod schemas reject arguments:undefined; send {} for parameter-less tools.
   const r = await client.callTool({ name, arguments: args ?? {} });
   const text = r?.content?.[0]?.text;
-  if (typeof text !== "string") return r;
-  try { return JSON.parse(text); } catch { return text; }
+  const data = typeof text !== "string" ? r : parseOr(text, text);
+  if (strict && r?.isError) {
+    throw new Error(typeof data === "string" ? data : JSON.stringify(data));
+  }
+  return data;
+}
+
+function parseOr(text, fallback) {
+  try { return JSON.parse(text); } catch { return fallback; }
 }
 
 // Register (idempotent), then publish the transport marker so list_agents
-// shows us attached. Marker liveness is heartbeat-based server-side.
-await call("register", { agentId: AGENT_ID });
+// shows us attached. Marker liveness is heartbeat-based server-side. Both
+// calls are strict: a server-side isError (e.g. identity-mismatch on a
+// stale/reused token) must hard-fail the process rather than let us log
+// "attached" and heartbeat into the void while delivering nothing.
+try {
+  await call("register", { agentId: AGENT_ID }, { strict: true });
+} catch (e) {
+  die(`register failed: ${e?.message ?? e}`);
+}
 // Stamp the mtime of THIS process's loaded script so doctor() can spot a
 // stale remote pusher after a remote-side upgrade (see v0.8.2 stale-pusher
 // check — same hazard as the local tmux-pusher).
@@ -103,14 +123,22 @@ try {
   const { fileURLToPath } = await import("node:url");
   scriptMtime = statSync(fileURLToPath(import.meta.url)).mtimeMs;
 } catch { /* non-fatal */ }
-await call("report_transport", {
-  agentId: AGENT_ID,
-  transport: "tmux-push-remote",
-  host: hostname(),
-  tmuxTarget: TMUX_TARGET,
-  since: Date.now(),
-  ...(scriptMtime !== undefined ? { scriptMtime } : {}),
-});
+try {
+  await call(
+    "report_transport",
+    {
+      agentId: AGENT_ID,
+      transport: "tmux-push-remote",
+      host: hostname(),
+      tmuxTarget: TMUX_TARGET,
+      since: Date.now(),
+      ...(scriptMtime !== undefined ? { scriptMtime } : {}),
+    },
+    { strict: true },
+  );
+} catch (e) {
+  die(`report_transport failed: ${e?.message ?? e}`);
+}
 process.stderr.write(
   `[coord-pusher] attached agent='${AGENT_ID}' tmux=${TMUX_TARGET} server=${SERVER} (room=${INCLUDE_ROOM ? "on" : "off"})\n`,
 );
@@ -188,15 +216,35 @@ async function flush() {
 
 // The per-message PARSE CONTRACT line — MUST stay byte-identical to
 // hooks/tier.mjs's injectLine (agent harnesses parse from/room/text out of
-// it). Compact form (v0.14.0): `  [<kind> <HH:MM> <from>] <text>`, kind drops
+// it). Compact form (v0.14.0): `  [<tag> <HH:MM> <from>] <text>`, tag drops
 // the leading "room ", timestamp is HH:MM UTC, no "from=" label. This pusher
 // is standalone (may deploy without hooks/), so the helper is duplicated
 // rather than imported; test/tier.test.mjs locks both to the same shape.
 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}`;
 }
 
 function formatBatch(batch) {
@@ -226,12 +274,23 @@ async function injectViaTmux(batch) {
   const flushRun = async () => {
     if (run.length === 0) return;
     await pasteAndSubmit(formatBatch(run), true); // peer content: inert bracketed paste
+    await reportReceipts(run); // stamp only AFTER the paste+submit resolves
     run = [];
   };
   for (const m of batch) {
     if (isControl(m)) {
       await flushRun();
-      await pasteAndSubmit(m.text.trim(), false); // validated control: raw slash command
+      // Verified like the local path: the extra Enters and the capture-pane
+      // check are what make a control command actually run. The outcome is
+      // reported back over MCP (report_receipt) so send_command can return
+      // delivery:"confirmed" for a remote agent — before that wire tool
+      // existed this pusher could only log, and a remote control command was
+      // never confirmable no matter how well it went.
+      const outcome = await submitControlCommand(m.text.trim());
+      if (!outcome.submitted) {
+        process.stderr.write(`[coord-pusher] control command NOT submitted: ${outcome.reason}\n`);
+      }
+      await reportReceipts([m], outcome);
     } else {
       run.push(m);
     }
@@ -239,24 +298,76 @@ async function injectViaTmux(batch) {
   await flushRun();
 }
 
+// Wire counterpart to tmux-pusher's writeReceipts: this pusher cannot append
+// to receipts/<id>.jsonl on the server's filesystem, so it reports each
+// delivery over MCP and the server writes the same receipt line the local
+// path does. `outcome` (control commands only) carries what submit
+// verification actually observed — submitted/verified/reason are forwarded
+// verbatim and OMITTED entirely for ordinary peer batches, because an absent
+// `submitted` means "typed but unverified" and must never be upgraded to a
+// claim of execution this pusher did not make.
+//
+// Best-effort by design: a failed report must not break delivery or crash the
+// inject loop (the message IS in the pane by the time we get here). The
+// sender just times out to delivery:"pending" — the same honest answer an
+// unreported submission always produced. This also covers servers predating
+// the report_receipt tool: the unknown-tool error lands here and is logged.
+async function reportReceipts(msgs, outcome) {
+  for (const m of msgs) {
+    if (!m || !m.id) continue;
+    try {
+      await call(
+        "report_receipt",
+        {
+          agentId: AGENT_ID,
+          id: m.id,
+          ...(m.from !== undefined ? { from: m.from } : {}),
+          control: m.control === true,
+          ...(outcome
+            ? {
+                submitted: outcome.submitted === true,
+                verified: outcome.verified === true,
+                ...(outcome.reason ? { reason: outcome.reason } : {}),
+              }
+            : {}),
+        },
+        { strict: true },
+      );
+    } catch (e) {
+      process.stderr.write(`[coord-pusher] report_receipt for ${m.id} failed: ${e?.message ?? e}\n`);
+    }
+  }
+}
+
 // bracketed=true wraps the paste in bracketed-paste markers (paste-buffer -p) so
 // 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.
+//
+// Paste + submit. The pipeline is ./hooks/submit.mjs, shared with the local
+// pusher — this file used to carry its own copy, which had already drifted to a
+// SINGLE Enter with no settle delay at all, so a remote agent's control command
+// was even less likely to run than a local one. Only tmux is supplied here.
+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()}`));
-      const enter = spawnSync("tmux", ["send-keys", "-t", TMUX_TARGET, "Enter"]);
-      if (enter.status !== 0) return reject(new Error(`tmux send-keys: ${(enter.stderr ?? "").toString().trim()}`));
-      resolve();
-    });
-    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);
 }
 
 // ---------- per-source wait loops + subscription refresh ----------
@@ -275,7 +386,9 @@ function startLoop(source, room) {
   if (loops.has(key)) return;
   const state = { cancelled: false };
   loops.set(key, state);
-  const tag = source === "inbox" ? "DM" : `room #${normalizeRoom(room)}`;
+  // Named `label` to match hooks/tmux-pusher.mjs, and to leave `tag` free as
+  // the field name it is assigned to below.
+  const label = source === "inbox" ? "DM" : `room #${normalizeRoom(room)}`;
   (async () => {
     while (!state.cancelled) {
       let r;
@@ -283,14 +396,18 @@ function startLoop(source, room) {
         r = await call("wait_for_message", { agentId: AGENT_ID, source, room, timeoutMs: 60_000 });
       } catch (e) {
         // Transport hiccup — back off briefly so we don't spin against a dead server.
-        process.stderr.write(`[coord-pusher] wait_for_message(${tag}) error: ${e?.message ?? e}\n`);
+        process.stderr.write(`[coord-pusher] wait_for_message(${label}) error: ${e?.message ?? e}\n`);
         await sleep(2_000);
         continue;
       }
       if (state.cancelled) break;
       const msgs = Array.isArray(r?.messages) ? r.messages : [];
       for (const m of msgs) {
-        if (shouldInject(m)) pending.push({ kind: tag, ...m });
+        // The channel tag lives in `tag` — a stored Message's own `kind`
+        // (retention weight) shared the name and overwrote what injectLine
+        // renders. Mirrors hooks/tmux-pusher.mjs; the two must stay
+        // byte-identical.
+        if (shouldInject(m)) pending.push({ ...m, tag: label });
       }
       if (pending.length > 0) scheduleFlush();
     }

package/src/build.ts

@@ -0,0 +1,111 @@
+// Build identity of the RUNNING server process.
+//
+// The principle is the #28 pusher-freshness fix carried one layer up: stamp
+// what you LOADED at init, compare against what's on disk NOW, and resolve the
+// measured artifact from the code that is actually executing
+// (import.meta.url), never from configuration — the thing that measures must
+// be the thing that ran. A server process outlives `npm run build`; without a
+// load-time sample there is nothing truthful to compare the on-disk build to,
+// and a server running pre-rebuild code stamps transport markers with logic
+// the rebuild replaced (observed live 2026-07-29: post-#28 attach spawned a
+// pusher with no `--agent` argv and a single-file freshness stamp, agreeing
+// with the new on-disk check only by coincidence).
+
+import { readdirSync, statSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+// Newest mtime (epoch ms) across every file under `dir` (recursive) whose
+// name ends with one of `exts`. Returns undefined when the dir is missing or
+// unreadable — callers skip their check rather than guess. Pure over its
+// arguments so tests exercise it on temp trees instead of touching real
+// sources (a utimes on a shared checkout flips every live pusher's freshness
+// while the suite runs files in parallel).
+export function newestMtimeUnder(dir: string, exts: string[]): number | undefined {
+  try {
+    let newest: number | undefined;
+    for (const rel of readdirSync(dir, { recursive: true }) as string[]) {
+      const name = String(rel);
+      if (!exts.some((e) => name.endsWith(e))) continue;
+      let m: number;
+      try {
+        m = statSync(path.join(dir, name)).mtimeMs;
+      } catch {
+        continue; // deleted mid-scan
+      }
+      if (newest === undefined || m > newest) newest = m;
+    }
+    return newest;
+  } catch {
+    return undefined;
+  }
+}
+
+// The dir this module was loaded FROM: dist/ in production, src/ under tsx.
+// Either way it is the code actually running, which is the point.
+export const BUILD_DIR = path.dirname(fileURLToPath(import.meta.url));
+
+// .js for the compiled build, .ts for dev-mode (tsx src/server.ts) — both
+// sides of every comparison use the same list, so the two modes are each
+// self-consistent and can never be compared across.
+const BUILD_EXTS = [".js", ".ts"];
+
+// Sampled ONCE at module load: the newest mtime across the build this server
+// process actually imported. A later `npm run build` rewrites dist/ under a
+// still-running server; this value stays behind, which is exactly what
+// doctor's server-build-drift check compares against.
+export const SERVER_BUILD_MTIME: number | undefined = newestMtimeUnder(BUILD_DIR, BUILD_EXTS);
+
+// The on-disk side of the comparison, statted fresh per call.
+// AGENT_COORD_DIST_DIR is a test seam only: it redirects what doctor
+// MEASURES so tests can stage a newer/older build in a temp dir — it never
+// changes what the server loads.
+export function onDiskBuildMtime(): number | undefined {
+  const dir = process.env.AGENT_COORD_DIST_DIR ?? BUILD_DIR;
+  return newestMtimeUnder(dir, BUILD_EXTS);
+}
+
+// The uncompiled side of the dist-behind-source comparison: newest mtime
+// across src/**/*.ts, resolved as BUILD_DIR's sibling. undefined on a
+// packaged install with no src/ (callers report "nothing to compare", never
+// warn). Under tsx dev-mode BUILD_DIR *is* src/, so the comparison degrades
+// to src-vs-src and reads ok — dev-mode has no build to fall behind.
+// AGENT_COORD_SRC_DIR is the same test seam as AGENT_COORD_DIST_DIR:
+// it redirects measurement only.
+export function onDiskSourceMtime(): number | undefined {
+  const dir = process.env.AGENT_COORD_SRC_DIR ?? path.resolve(BUILD_DIR, "..", "src");
+  return newestMtimeUnder(dir, [".ts"]);
+}
+
+// Best-effort checkout identity, report-only: lets doctor NAME the build
+// (`branch@sha` would be nicer, but HEAD's sha alone already makes
+// mutable-checkout drift visible, which is all this claims). undefined when
+// not a git checkout (npm install) — never an error.
+export const SERVER_BUILD_SHA: string | undefined = (() => {
+  try {
+    let gitDir = path.resolve(BUILD_DIR, "..", ".git");
+    const st = statSync(gitDir);
+    if (st.isFile()) {
+      // A worktree's .git is a pointer file: "gitdir: <real dir>".
+      const ptr = readFileSync(gitDir, "utf8").trim();
+      if (!ptr.startsWith("gitdir:")) return undefined;
+      gitDir = ptr.slice("gitdir:".length).trim();
+    }
+    const head = readFileSync(path.join(gitDir, "HEAD"), "utf8").trim();
+    if (!head.startsWith("ref:")) return head.slice(0, 12); // detached
+    const ref = head.slice(4).trim();
+    try {
+      return readFileSync(path.join(gitDir, ref), "utf8").trim().slice(0, 12);
+    } catch {
+      // Ref may be packed. commondir handling is deliberately out of scope —
+      // best-effort means undefined beats wrong.
+      const packed = readFileSync(path.join(gitDir, "packed-refs"), "utf8");
+      for (const line of packed.split("\n")) {
+        if (line.endsWith(` ${ref}`)) return line.slice(0, 12);
+      }
+      return undefined;
+    }
+  } catch {
+    return undefined;
+  }
+})();

package/src/roles.ts

@@ -0,0 +1,111 @@
+// Canonical role identity, server side (Phase 8 Task 4).
+//
+// MIRROR of hooks/roles.mjs — tsconfig's rootDir is `src`, so this cannot
+// import the hook copy, and the hook copy must stay build-free (the pusher
+// loads it from a bare checkout). test/roles.test.mjs asserts the two agree;
+// change one, change the other.
+//
+// See hooks/roles.mjs for the rationale behind `explicit` and the word-match
+// fallback.
+
+import { z } from "zod";
+
+export type ResolvedRole = {
+  roleId: string;
+  displayName: string;
+  // true when the id was DECLARED (frozen), false when DERIVED from display text.
+  explicit: boolean;
+};
+
+export type RoleInput =
+  | string
+  | { roleId?: string; displayName?: string; role?: string | null }
+  | null
+  | undefined;
+
+export function slugifyRole(role: unknown): string {
+  return String(role ?? "")
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+}
+
+export const GATE_RUNNER_ROLE_IDS = new Set(["qa", "quality", "coordinator", "gate"]);
+export const COORDINATOR_ROLE_IDS = new Set(["coordinator"]);
+
+export function resolveRole(role: RoleInput): ResolvedRole | undefined {
+  if (role === null || role === undefined) return undefined;
+  if (typeof role === "string") {
+    const roleId = slugifyRole(role);
+    return roleId ? { roleId, displayName: role, explicit: false } : undefined;
+  }
+  if (typeof role === "object") {
+    const declared = typeof role.roleId === "string" ? slugifyRole(role.roleId) : "";
+    const name =
+      typeof role.displayName === "string" && role.displayName
+        ? role.displayName
+        : typeof role.role === "string" && role.role
+          ? role.role
+          : undefined;
+    if (declared) return { roleId: declared, displayName: name ?? declared, explicit: true };
+    if (name) return resolveRole(name);
+  }
+  return undefined;
+}
+
+export function roleMatches(role: RoleInput, allowedIds: Set<string>): boolean {
+  const resolved = resolveRole(role);
+  if (!resolved) return false;
+  if (allowedIds.has(resolved.roleId)) return true;
+  if (resolved.explicit) return false;
+  return resolved.roleId.split("-").some((word) => allowedIds.has(word));
+}
+
+export function isGateRunner(role: RoleInput): boolean {
+  return roleMatches(role, GATE_RUNNER_ROLE_IDS);
+}
+
+export function isCoordinator(role: RoleInput): boolean {
+  return roleMatches(role, COORDINATOR_ROLE_IDS);
+}
+
+// Which roles may emit which record.type at the send path. Enforcement lives
+// in messaging.ts (checkRecordAuthority); the table lives here so register/join
+// can ECHO the consequence back at onboarding — a role that cannot emit `go`
+// should learn it when it registers, not when it sends its first work order.
+//
+// NOT A TRUST BOUNDARY — roles are self-declared. See checkRecordAuthority.
+export const RECORD_AUTHORITY: Record<string, { roles: Set<string>; label: string }> = {
+  verdict: { roles: GATE_RUNNER_ROLE_IDS, label: "gate-runner" },
+  go: { roles: COORDINATOR_ROLE_IDS, label: "coordinator" },
+  scope: { roles: COORDINATOR_ROLE_IDS, label: "coordinator" },
+};
+
+// Split the restricted record types into what this role may and may not emit.
+// Unrestricted types are omitted from both lists — they are nobody's business.
+export function recordAuthorityFor(role: RoleInput): { mayEmit: string[]; mayNotEmit: string[] } {
+  const mayEmit: string[] = [];
+  const mayNotEmit: string[] = [];
+  for (const [type, rule] of Object.entries(RECORD_AUTHORITY)) {
+    (roleMatches(role, rule.roles) ? mayEmit : mayNotEmit).push(type);
+  }
+  return { mayEmit, mayNotEmit };
+}
+
+// Wire shape for `role` on register/join. Either free text (v1: `role: "qa
+// lead"`) or a declared identity (`{roleId: "qa", displayName: "QA gate"}`).
+// Both are supported forever — the string form is not deprecated, it just
+// leaves the id derived rather than frozen.
+//
+// Lives here rather than in tools/ because registry.ts and transport.ts import
+// each other; a schema in either would be a temporal-dead-zone hazard.
+export const roleInputSchema = z.union([
+  z.string(),
+  z.object({
+    roleId: z.string().min(1).optional(),
+    displayName: z.string().min(1).optional(),
+  }),
+]);
+
+export type RoleArg = z.infer<typeof roleInputSchema>;