agent-coord-mcp 0.26.21 → 0.26.23

package/src/tools/registry.ts

@@ -1,11 +1,12 @@
 import { detachAgentTool } from "./transport.js";
-import { isLocallyProbeable, isRemoteTmuxKind, targetOf } from "../transports/index.js";
+import { isLocallyProbeable, isRemoteTmuxKind, targetOf, HERDR, HerdrTransport, activeTransport } from "../transports/index.js";
 import { readAway, secondCoordinatorRefusal } from "./away.js";
 import { randomUUID } from "node:crypto";
-import { existsSync, openSync, watch } from "node:fs";
+import { existsSync, openSync, statSync, watch } from "node:fs";
 import { promises as fsp } from "node:fs";
 import { spawn, spawnSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
+import { detectSpread, installedBuild } from "../server-spread.js";
 import { z } from "zod";
 import path from "node:path";
 import {
@@ -53,7 +54,8 @@ import {
   type RoomRegistry,
   type SessionBinding,
 } from "../store.js";
-import { recordAuthorityFor, resolveRole, CANONICAL_ROLE_IDS, roleInputSchema, type RoleArg } from "../roles.js";
+import { recordAuthorityFor, resolveRole, CANONICAL_ROLE_IDS, roleInputSchema, isHuman, type RoleArg } from "../roles.js";
+import { readHumans, recordHuman } from "../store.js";
 import {
   type AgentEntry,
   type AgentRegistry,
@@ -180,6 +182,10 @@ export async function registerTool(args: {
     return current;
   });
   const entry = reg[args.agentId];
+  // ⟨q-178878aa⟩ — a HUMAN registration is recorded durably: the registry entry itself is
+  // evicted after EVICT_MS (no heartbeat, no transport), and the send path's exemption
+  // must still see the human after that.
+  if (isHuman(entry)) await recordHuman(args.agentId, { displayName: entry.role, by: `register:${args.agentId}` });
   // Echo the record types this role may and may not emit. Record authority is
   // otherwise invisible until the first typed send is refused mid-work — this
   // is how an agent whose role owns `go`/`scope`/`verdict` finds out at
@@ -287,6 +293,23 @@ export async function heartbeatTool(args: { agentId: string }) {
       return current;
     }
     current[args.agentId].lastHeartbeat = Date.now();
+    /*
+     * ⛔ STAMP THE ANSWERING PROCESS — `⟨q-cec42e20⟩`. This runs INSIDE the server that
+     * is answering, which is the only place these two facts exist: `capabilities`
+     * reports them solely to its own caller, and no seat can query another seat's
+     * server at all. Publishing them here is what makes a cross-seat comparison
+     * possible without every seat having to volunteer it in prose.
+     *
+     * `startedAt` is derived from uptime rather than read from a file: an mtime tracks
+     * writes (a reinstall of identical bytes moves it) while uptime is a fact about
+     * THIS process.
+     */
+    current[args.agentId].serverPid = process.pid;
+    current[args.agentId].serverStartedAt = Date.now() - Math.round(process.uptime() * 1000);
+    // ⛔ WHAT this process is executing, not what it is labelled. Resolved from this
+    // module's own URL, so a server running a dev `dist/` says so instead of inheriting
+    // the installed path — the case that made a 3-build fleet read AGREED.
+    current[args.agentId].serverModule = installedBuild(import.meta.url, statSync)?.module;
     return current;
   });
   if (missing) return { ok: false, error: `agent '${args.agentId}' not registered` };
@@ -331,6 +354,8 @@ export async function listAgentsTool() {
       // heartbeat. This stamp only ever overwrote a true value with a
       // simultaneous one.
       if (liveTransports.has(id)) continue;
+      // A human has no heartbeat to go stale; evicting one is how the exemption went blind.
+      if (isHuman(entry)) continue;
       if (now - entry.lastHeartbeat > EVICT_MS) {
         evicted.push(id);
         delete current[id];
@@ -417,7 +442,33 @@ export async function listAgentsTool() {
       "granted to the SENDER and paid by every READER: their multi-line messages cannot be slimmed. " +
       "A rising share means the rule is decaying.",
   };
-  return { agents, evicted, proseOnly };
+  /*
+   * ⛔⛆ AND WHETHER THOSE SEATS AGREE ABOUT WHAT THEY ARE RUNNING — `⟨q-cec42e20⟩`.
+   *
+   * Reported HERE because this is the verb that already answers "who is live", and the
+   * spread is a property of that same population: a reader asking who is on the bus is
+   * exactly the reader who needs to know their servers are not the same build.
+   *
+   * ⚠ IT NEVER REPORTS AGREEMENT IT DID NOT ESTABLISH. A seat that has not stamped its
+   * identity is UNCOMPARABLE and poisons the verdict to CANNOT_COMPARE rather than being
+   * dropped from the population — because "every seat I could read agrees" and "the
+   * fleet agrees" are different claims, and only the second is what a reader will act on.
+   */
+  const spread = detectSpread(
+    Object.values(reg)
+      .filter((a) => liveTransports.has(a.agentId) || now - a.lastHeartbeat < STALE_MS)
+      .map((a) => ({
+        agentId: a.agentId,
+        serverPid: a.serverPid,
+        serverStartedAt: a.serverStartedAt,
+        serverModule: a.serverModule,
+      })),
+    installedBuild(import.meta.url, statSync),
+  );
+
+  // ⟨q-178878aa⟩ — the humans the bus knows: visible here, read at send time, never evicted.
+  const humans = Object.entries(await readHumans()).map(([id, h]) => ({ id, ...h }));
+  return { agents, evicted, proseOnly, humans, serverSpread: spread };
 }
 
 /**
@@ -474,6 +525,19 @@ export function isMarkerLive(marker: TransportMarker, reg: AgentRegistry, now: n
     const entry = reg[marker.agentId];
     return !!entry && now - entry.lastHeartbeat < STALE_MS;
   }
+  // Phase 5.4 Task 4 — a herdr marker has no pid (0): liveness is the PANE, asked of
+  // herdr itself. "Could not ask" keeps the marker (unknown is not dead); only herdr
+  // saying pane_not_found lets the registry drop it.
+  if (marker.transport === HERDR) {
+    const t = targetOf(marker);
+    if (!t) return false;
+    // Ask through the WIRED herdr transport (its runner is what tests inject and what the
+    // fleet configured). A server with no herdr transport wired cannot ask, and "cannot
+    // ask" keeps the marker: the herdr-configured server reaps its own dead panes.
+    const active = activeTransport();
+    const exists = active?.kind === HERDR && active instanceof HerdrTransport ? active.paneExists(t) : null;
+    return exists !== false;
+  }
   return isPidAlive(marker.pid);
 }
 

package/src/tools/seat-build.ts

@@ -0,0 +1,201 @@
+/*
+ * ⟨q-8a3f1c05⟩ — A HALF-RESTARTED SEAT IS A STATEMENT, NOT AN INFERENCE.
+ *
+ * Each seat runs TWO long-lived processes from the installed tree: the MCP server
+ * (answers `capabilities`) and the tmux pusher (`hooks/tmux-pusher.mjs --agent <id>`,
+ * pastes into the pane). A restart cycles the server and leaves the pusher, so a seat
+ * comes back running new server code behind an old pusher — fully responsive, `online:
+ * true`, and invisible to every instrument that reads the server. Measured 2026-09-14
+ * during the staged restart: stage 1's pusher was three days older than its server and
+ * was found only because that seat happened to look; a stale pusher still delivers.
+ *
+ * THE INSTRUMENT ALREADY EXISTED AND NOBODY CALLED IT: pushers self-identify on the
+ * command line (`--agent <id>`), so `ps` + `--agent` + the installed HOOK's mtime is a
+ * per-seat pusher-staleness probe. This module states it, per seat, beside the server
+ * half — in words, not a pair of timestamps a reader has to subtract.
+ *
+ * THE HOOK'S OWN MTIME, NEVER A SIBLING'S: `hooks/tmux-pusher.mjs` is the file the
+ * pusher loads. `package.json`, `dist/…` and the hook all carry the same instant under
+ * a whole-tree install, but an install that rewrites some files and not others breaks
+ * that, and nothing checks it. So the pusher half reads the hook file directly.
+ *
+ * THE LIMIT THIS CARRIES RATHER THAN SOLVES: servers carry no `--agent`, so the server
+ * side cannot be keyed to a seat from `ps`. Only the ANSWERING process knows its own
+ * start time (`answeredBy.pid`). For every other seat the server half is reported as
+ * UNOBSERVABLE from here — said, not inferred from the marker's attach-time stamp.
+ */
+import { execFileSync } from "node:child_process";
+import { statSync } from "node:fs";
+import path from "node:path";
+import type { TransportMarker } from "../transports/types.js";
+
+export type ProcessFacts = { pid: number; startedAt: number | null; command: string | null; alive: boolean };
+export type PsReader = (pid: number) => ProcessFacts;
+export type StatReader = (p: string) => { mtimeMs: number };
+export type Installed = { module: string; hookPath: string; hookMtime: number | null; buildMtime: number | null };
+export type ServerFacts = { pid: number; startedAt: number; buildMtime: number | null } | null;
+
+export type SeatBuild = {
+  agentId: string;
+  verdict: "current" | "half-restarted" | "stale" | "unknown";
+  statement: string;
+  server: { observable: boolean; pid: number | null; startedAt: string | null; buildMtime: string | null; current: boolean | null; note: string };
+  pusher: {
+    pid: number | null;
+    alive: boolean | null;
+    keyedByAgentArg: boolean | null;
+    startedAt: string | null;
+    /** The hook file THIS pusher loads, read off its own command line — never a sibling, never the server's tree. */
+    hookPath: string | null;
+    hookMtime: string | null;
+    /** false when the pusher runs from a different tree than the answering server (a dev checkout vs the global install, or two installs). */
+    sameTreeAsServer: boolean | null;
+    current: boolean | null;
+    note: string;
+  };
+};
+
+const iso = (ms: number | null | undefined) => (typeof ms === "number" && Number.isFinite(ms) ? new Date(ms).toISOString() : null);
+
+/** `ps` for one pid: start time and command line. `lstart` is portable across macOS and Linux. */
+export const psReader: PsReader = (pid) => {
+  try {
+    const out = execFileSync("ps", ["-o", "lstart=,command=", "-p", String(pid)], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
+    if (!out) return { pid, startedAt: null, command: null, alive: false };
+    // lstart is 24 chars ("Mon Sep 14 14:38:24 2026"), then the command.
+    const m = /^(\w{3}\s+\w{3}\s+\d+\s+[\d:]+\s+\d{4})\s+(.*)$/.exec(out);
+    const startedAt = m ? Date.parse(m[1]) : NaN;
+    return { pid, startedAt: Number.isFinite(startedAt) ? startedAt : null, command: m ? m[2] : out, alive: true };
+  } catch {
+    return { pid, startedAt: null, command: null, alive: false };
+  }
+};
+
+/** The installed tree's hook and build stamps, read from the files themselves. */
+export function installedFrom(moduleRoot: string, stat: (p: string) => { mtimeMs: number } = statSync): Installed {
+  const hookPath = path.join(moduleRoot, "hooks", "tmux-pusher.mjs");
+  const read = (p: string) => {
+    try {
+      return stat(p).mtimeMs;
+    } catch {
+      return null;
+    }
+  };
+  return { module: moduleRoot, hookPath, hookMtime: read(hookPath), buildMtime: read(path.join(moduleRoot, "package.json")) };
+}
+
+const day = (ms: number) => new Date(ms).toISOString().slice(0, 10);
+
+/**
+ * One seat's build state: the pusher half from its marker's pid via `ps`, keyed by the
+ * `--agent` argument on that process's own command line; the server half from the
+ * answering process when the seat IS the answering process, else unobservable.
+ */
+/** The hook file a pusher loads, read off its own command line: `node <path>/hooks/tmux-pusher.mjs --agent <id>`. */
+export function hookPathOf(command: string): string | null {
+  const m = /(\S*\/hooks\/tmux-pusher\.mjs)(?=\s|$)/.exec(command);
+  return m ? m[1] : null;
+}
+
+export function seatBuildOf(input: { agentId: string; marker: TransportMarker | undefined; installed: Installed; ps: PsReader; server: ServerFacts; stat?: StatReader }): SeatBuild {
+  const { agentId, marker, installed, ps, server } = input;
+  const stat = input.stat ?? statSync;
+
+  // ---- pusher half
+  let pusher: SeatBuild["pusher"];
+  const empty = { pid: null, alive: null, keyedByAgentArg: null, startedAt: null, hookPath: null, hookMtime: null, sameTreeAsServer: null, current: null };
+  if (marker && marker.transport === "herdr") {
+    // Phase 5.4 Task 4 — a herdr seat has NO pusher: delivery is in-process by the server,
+    // so the seat's build is the server half alone, and this says so instead of reading pid 0.
+    pusher = { ...empty, note: `herdr socket transport (pane ${marker.target ?? marker.tmuxTarget ?? "?"}): no pusher process — delivery is in-process by the answering server, so the server half is the whole seat` };
+  } else if (!marker || typeof marker.pid !== "number") {
+    pusher = { ...empty, note: "no transport marker for this seat — no pusher pid to read" };
+  } else {
+    const facts = ps(marker.pid);
+    if (!facts.alive) {
+      pusher = { ...empty, pid: marker.pid, alive: false, note: `the marker names pid ${marker.pid} and no such process is running — the pusher is dead, not stale` };
+    } else {
+      const cmd = facts.command ?? "";
+      const keyed = /tmux-pusher\.mjs/.test(cmd) && new RegExp(`--agent\\s+${agentId.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}(\\s|$)`).test(cmd);
+      if (!keyed) {
+        pusher = { ...empty, pid: marker.pid, alive: true, keyedByAgentArg: false, startedAt: iso(facts.startedAt), note: `pid ${marker.pid} is alive but its command line does not say \`tmux-pusher.mjs --agent ${agentId}\` — the marker's pid is not this seat's pusher, so nothing is claimed about it` };
+      } else {
+        // THE VERY FILE THIS PUSHER LOADS. Its path is on the command line; the mtime is
+        // read from that path, not from the answering server's tree — a dev checkout
+        // answering for a fleet of global-install pushers would otherwise call every
+        // pusher stale against a file none of them ever loaded (measured while building
+        // this: 6 of 6 read stale against a worktree's hook, all 6 current against their own).
+        const hookPath = hookPathOf(cmd) ?? installed.hookPath;
+        const fromOwnCmd = hookPathOf(cmd) !== null;
+        let hookMtime: number | null = null;
+        try {
+          hookMtime = stat(hookPath).mtimeMs;
+        } catch {
+          hookMtime = null;
+        }
+        const sameTree = path.resolve(path.dirname(path.dirname(hookPath))) === path.resolve(installed.module);
+        if (facts.startedAt === null || hookMtime === null) {
+          pusher = { ...empty, pid: marker.pid, alive: true, keyedByAgentArg: true, startedAt: iso(facts.startedAt), hookPath, sameTreeAsServer: sameTree, note: facts.startedAt === null ? "ps gave no start time for the pusher" : `the hook ${hookPath} could not be read` };
+        } else {
+          const current = facts.startedAt >= hookMtime;
+          pusher = {
+            pid: marker.pid,
+            alive: true,
+            keyedByAgentArg: true,
+            startedAt: iso(facts.startedAt),
+            hookPath,
+            hookMtime: iso(hookMtime),
+            sameTreeAsServer: sameTree,
+            current,
+            note:
+              (current
+                ? `pusher started ${iso(facts.startedAt)}, after its hook ${hookPath} (${iso(hookMtime)}) — it loaded that installed code`
+                : `pusher started ${iso(facts.startedAt)}, BEFORE its hook ${hookPath} (${iso(hookMtime)}) — it runs the code it loaded then, and still delivers`) +
+              (fromOwnCmd ? "" : " (hook path not on the command line; the answering server's tree was used)") +
+              (sameTree ? "" : `; NOTE the pusher's tree differs from the answering server's (${installed.module})`),
+          };
+        }
+      }
+    }
+  }
+
+  // ---- server half
+  let srv: SeatBuild["server"];
+  if (!server) {
+    srv = { observable: false, pid: null, startedAt: null, buildMtime: iso(installed.buildMtime), current: null, note: "the server side cannot be keyed to a seat from ps (servers carry no --agent); only the answering process knows its own start time (answeredBy.pid). Ask this seat's own `capabilities`." };
+  } else if (server.buildMtime === null) {
+    srv = { observable: true, pid: server.pid, startedAt: iso(server.startedAt), buildMtime: null, current: null, note: "the installed package.json could not be read, so the server's build cannot be placed" };
+  } else {
+    const current = server.startedAt >= server.buildMtime;
+    srv = { observable: true, pid: server.pid, startedAt: iso(server.startedAt), buildMtime: iso(server.buildMtime), current, note: current ? `server started ${iso(server.startedAt)}, on the ${day(server.buildMtime)} install` : `server started ${iso(server.startedAt)}, BEFORE the ${day(server.buildMtime)} install` };
+  }
+
+  // ---- the statement
+  let verdict: SeatBuild["verdict"];
+  let statement: string;
+  const p = pusher.current;
+  const s = srv.current;
+  if (s === true && p === true) {
+    verdict = "current";
+    statement = `${agentId}: current — server and pusher both started after the ${day(server!.buildMtime!)} install.`;
+  } else if (s === false && p === false) {
+    verdict = "stale";
+    statement = `${agentId}: stale — server and pusher both predate the install; nothing on this seat runs the installed code.`;
+  } else if (s === true && p === false) {
+    verdict = "half-restarted";
+    statement = `${agentId}: HALF-RESTARTED — server on the ${day(server!.buildMtime!)} install, pusher started before it (${pusher.startedAt}). The seat sends through new code and receives through old; it looks healthy. Cycle the pusher: detach_agent, then attach_agent, from this seat.`;
+  } else if (s === false && p === true) {
+    verdict = "half-restarted";
+    statement = `${agentId}: HALF-RESTARTED the other way — pusher on the installed hook, server started before the ${day(server!.buildMtime!)} install. Reload the server (relaunch the MCP client for this seat).`;
+  } else if (marker?.transport === "herdr" && s !== null) {
+    verdict = s ? "current" : "stale";
+    statement = `${agentId}: ${s ? "current" : "stale"} — herdr socket transport, no pusher; the server ${s ? "started after" : "predates"} the ${day(server!.buildMtime!)} install and is the whole seat.`;
+  } else if (s === null && p !== null) {
+    verdict = "unknown";
+    statement = `${agentId}: pusher ${p ? "current" : "STALE — started before the installed hook"}; server UNOBSERVABLE from here (${srv.note}).`;
+  } else {
+    verdict = "unknown";
+    statement = `${agentId}: unknown — ${pusher.note}${srv.observable ? "" : `; ${srv.note}`}`;
+  }
+  return { agentId, verdict, statement, server: srv, pusher };
+}

package/src/tools/shared.ts

@@ -86,6 +86,28 @@ export type AgentEntry = {
   // OTHER agents' context on every multi-line send. That is why it is stamped,
   // counted, and reviewed rather than self-service.
   proseOnly?: { since: number; reason?: string };
+
+  /*
+   * ⛔⛆ THE ANSWERING PROCESS, PUBLISHED — `⟨q-cec42e20⟩`. ADDITIVE AND OPTIONAL:
+   * absent on every pre-existing entry, and no reader that ignores unknown keys changes
+   * behaviour.
+   *
+   * Two seats ran the same verb, got `153` and `138`, and both servers honestly reported
+   * `versionLabel 0.26.20`. Nothing detected it — each seat had to VOLUNTEER it.
+   *
+   * ⭐ WHY THESE TWO FIELDS AND NOT A VERSION: a server loads its code once, at spawn,
+   * so START TIME against the installed build is the axis that separates two processes
+   * running different code. A label cannot: it AGREED while the behaviour differed, and
+   * `serverBuildMtime` cannot either — it is stamped at ATTACH and read IDENTICAL across
+   * all six live transports while the spread was live.
+   *
+   * ⚠ AND IT IS THE SERVER, NEVER THE PUSHER. `transports/<agent>.json` already carries a
+   * pid and it is the pusher's — a different process, on different code, which is the
+   * distinction this fleet paid for twice on 2026-09-12.
+   */
+  serverPid?: number;
+  serverStartedAt?: number;
+  serverModule?: string;
 };
 
 /**