agent-coord-mcp 0.26.24 → 0.26.26

package/src/tools/herdr-tail.ts

@@ -0,0 +1,276 @@
+/**
+ * ⛔ A HERDR SEAT WAS DEAF TO EVERY TMUX SEAT, AND THE REASON IS A SINGLETON.
+ *
+ * `deliverToHerdrSeats` runs at SEND time and returns early unless `activeTransport().kind` is
+ * HERDR. `activeTransport()` returns a module-level singleton wired once at startup from the
+ * SENDER's own config — so that early return can only ever see the SENDER's transport, and a tmux
+ * seat's server could never type into a herdr pane. Measured both ways: `herdr → herdr` typed and
+ * woke the seat; `tmux → herdr` reached the inbox file and was never typed.
+ *
+ * ⚠ THE EASIER FIX IS THE WRONG ONE: letting the SENDER drive herdr per recipient passes on a
+ * one-machine fleet and fails silently and asymmetrically on two, because every sender would need
+ * the `herdr` binary on its own host. So the duty goes to the seat that needs waking — the only
+ * party guaranteed to be where it is.
+ *
+ * ⛔⛆ AND THE FIRST VERSION OF THIS FILE WAS INERT ON EVERY SEAT, INCLUDING ITS AUTHOR'S.
+ * `8363968` started the tail only when `AGENT_COORD_BOUND_AGENT` was set at startup. No seat on
+ * this fleet sets it — identity binds at `join` — so the coordinator measured "herdr tail NOT
+ * started" on the PR's own server and qa read the variable unset on all six live seat servers.
+ * Its eleven tests injected the agent id and so could not see it. The tail now starts from the
+ * IDENTITY BINDING (`startTailOnBind`), idempotently, one per agent per process.
+ *
+ * ⛔ AND IT MUST NOT RUN THE REAPER. That version called `loadLiveTransports()` on every tick —
+ * the loader that DELETES markers it judges dead, named an hour earlier as the vanishing-marker
+ * mechanism. A reaper in a once-a-second loop on every seat is not shippable on the argument that
+ * the current build usually keeps the marker. This file reads its own seat's marker FILE directly,
+ * read-only, and never asks about anyone else's.
+ *
+ * THE CURSOR RULE IS THE PUSHER'S (⟨q-7be94b5e⟩): advance the PUSH cursor only past what was
+ * VERIFIABLY typed. Two corrections from qa's read of `8363968`, both now driven by tests:
+ *   · the cursor advances to the byte AFTER THE DELIVERED LINE, never to the file's size — sizing
+ *     it skipped a later message in the same tick whose paste then failed;
+ *   · a cursor write that FAILS is held, and an in-process high-water mark stops the same message
+ *     being re-typed on the next tick — the directory fix closed one cause of a paste loop, this
+ *     closes the class.
+ *
+ * IDLE COST, COUNTED BY TESTS RATHER THAN ASSERTED HERE: when no tailed file has grown, a tick is
+ * one `stat()` per tailed file and nothing else. The marker and room membership are re-read every
+ * `REFRESH_TICKS` ticks, and no herdr subprocess runs until there is something to type.
+ */
+import { readFileSync, statSync } from "node:fs";
+import { inboxFile, roomFile, getRooms, transportFile } from "../store.js";
+import { activeTransport, HERDR, type Transport, type TransportMarker } from "../transports/index.js";
+import { renderForPane, advancePushCursor, readPushCursorFor, type Message } from "./herdr-delivery.js";
+import { newMessagesIn } from "./jsonl-offsets.js";
+
+export const DEFAULT_POLL_MS = 1000;
+/** Marker and room membership are re-read this often. A room joined mid-session is picked up within this many ticks. */
+export const REFRESH_TICKS = 30;
+
+type Source = { kind: "dm" | "room"; chan?: string; file: string };
+export type TailOutcome = {
+  delivered: { kind: "dm" | "room"; chan?: string; id: string }[];
+  held: { kind: "dm" | "room"; chan?: string; id: string; why: string }[];
+  idle?: string;
+};
+
+/** Per-agent memory that survives between ticks — what makes the idle path cheap and the paste loop impossible. */
+export type TailContext = {
+  tick: number;
+  marker: TransportMarker | null;
+  rooms: string[];
+  /** In-process high-water mark per source: never re-type below this, even if the persistent cursor could not be written. */
+  hw: Map<string, number>;
+  /** Last seen size per source: a source that has not grown costs one stat. */
+  sizes: Map<string, number>;
+  /**
+   * ⛔ START AT EOF, NEVER AT WHATEVER THE CURSOR FILE HAPPENS TO SAY. A tail is a LIVE push
+   * mechanism, not a mail reader: nothing that predates its start belongs on the pane. Measured
+   * 2026-09-17 — a daemon restart reset every push cursor to ~0, so a tail starting from disk
+   * state would have typed a 3.4MB inbox into one seat's pane. `read_messages` still serves that
+   * history on demand; that is the verb for it.
+   */
+  seedEof: boolean;
+  /** Sources already seeded — a room discovered on a later refresh is seeded on ITS first sight, not skipped. */
+  seeded: Set<string>;
+};
+export const newContext = (seedEof = false): TailContext => ({ tick: 0, marker: null, rooms: [], hw: new Map(), sizes: new Map(), seedEof, seeded: new Set() });
+
+const keyOf = (s: { kind: string; chan?: string }) => (s.kind === "dm" ? "dm" : `room:${s.chan}`);
+const sizeOf = (file: string): number => {
+  try { return statSync(file).size; } catch { return 0; }
+};
+
+/** Read THIS seat's own marker, read-only. Never the reaping loader. */
+export function readOwnMarker(agentId: string): TransportMarker | null {
+  try { return JSON.parse(readFileSync(transportFile(agentId), "utf8")) as TransportMarker; } catch { return null; }
+}
+
+/** The shared line reader — re-exported so callers of this module keep one import. */
+export { newMessagesIn } from "./jsonl-offsets.js";
+
+async function offsetOf(agentId: string, src: Source, ctx: TailContext): Promise<number> {
+  const c = await readPushCursorFor(agentId);
+  const persisted = src.kind === "dm" ? Number(c.inboxOffset ?? 0) : Number(((c.roomOffsets as Record<string, number> | undefined) ?? {})[src.chan!] ?? 0);
+  return Math.max(persisted, ctx.hw.get(keyOf(src)) ?? 0);
+}
+
+/** One pass. Everything that talks to the outside world is injectable, and nothing here schedules itself. */
+export async function tailOnce(
+  agentId: string,
+  opts: {
+    transport?: Transport;
+    ctx?: TailContext;
+    markerOf?: (agentId: string) => TransportMarker | null;
+    roomsOf?: () => Promise<Record<string, { members?: string[] }>>;
+  } = {},
+): Promise<TailOutcome> {
+  const out: TailOutcome = { delivered: [], held: [] };
+  const t = opts.transport ?? activeTransport();
+  if (!t || t.kind !== HERDR) return { ...out, idle: "this server's transport is not herdr — the tail is for a herdr seat's own inbox" };
+  const ctx = opts.ctx ?? newContext();
+  const refresh = ctx.tick % REFRESH_TICKS === 0;
+  ctx.tick += 1;
+
+  // A seat with NO marker re-reads it only on the refresh cadence too. The coordinator's gate found
+  // `|| !ctx.marker` here, which made a markerless seat — the exact state a vanished marker leaves —
+  // read its marker file on every tick while the stated idle cost said otherwise.
+  if (refresh) {
+    ctx.marker = (opts.markerOf ?? readOwnMarker)(agentId);
+    if (ctx.marker && ctx.marker.transport === HERDR && ctx.marker.rooms !== false) {
+      try {
+        const all = await (opts.roomsOf ?? getRooms)();
+        ctx.rooms = Object.entries(all ?? {}).filter(([, r]) => (r?.members ?? []).includes(agentId)).map(([chan]) => chan);
+      } catch { ctx.rooms = []; }
+    } else {
+      ctx.rooms = [];
+    }
+  }
+  const marker = ctx.marker;
+  if (!marker || marker.transport !== HERDR) return { ...out, idle: `${agentId} has no herdr marker on this bus — nothing to type into (re-checked every ${REFRESH_TICKS} ticks)` };
+
+  const sources: Source[] = [{ kind: "dm", file: inboxFile(agentId) }, ...ctx.rooms.map((chan) => ({ kind: "room" as const, chan, file: roomFile(chan) }))];
+
+  for (const src of sources) {
+    const size = sizeOf(src.file);
+    const key = keyOf(src);
+    // ⭐ THE IDLE PATH: a source that has not grown since the last tick costs this one stat.
+    if (ctx.sizes.get(key) === size) continue;
+    ctx.sizes.set(key, size);
+    // ⛔ FIRST SIGHT OF A SOURCE UNDER seedEof: adopt EOF and type NOTHING. This is the only place
+    // the starting offset is decided, and it is decided EXPLICITLY rather than inherited from a
+    // cursor file that a restart may have reset. Per source, so a room joined later seeds on its
+    // own first sight instead of replaying its history.
+    if (ctx.seedEof && !ctx.seeded.has(key)) {
+      ctx.seeded.add(key);
+      ctx.hw.set(key, size);
+      continue;
+    }
+    const from = await offsetOf(agentId, src, ctx);
+    if (size <= from) continue;
+
+    for (const { msg, end } of newMessagesIn(src.file, from)) {
+      if (msg.from === agentId) { ctx.hw.set(key, end); continue; }
+      const where = src.kind === "dm" ? ({ kind: "dm" } as const) : ({ kind: "room", chan: src.chan! } as const);
+      const rendered = await renderForPane(msg as unknown as Message, agentId, where);
+      let r: { delivered: boolean; error?: string; verified?: boolean; safeToRetry?: boolean; outcome?: string };
+      try { r = await t.push(marker, rendered); } catch (e) { r = { delivered: false, safeToRetry: false, error: (e as Error).message }; }
+      if (!r.delivered && r.safeToRetry === true) {
+        // HELD: the transport sent NO key (no ready input box, a draft, a dialog, an unreadable pane).
+        // Nothing moves and the message is retried next tick, which costs only a screen read. Stop
+        // this source so no later message is typed past one that did not land.
+        out.held.push({ kind: src.kind, chan: src.chan, id: String(msg.id ?? ""), why: r.error ?? "held — nothing was typed" });
+        ctx.sizes.delete(key); // force a re-read next tick
+        break;
+      }
+      // ⛔ ANYTHING SHORT OF A VERIFIED DELIVERY DOES NOT MOVE THE PERSISTENT CURSOR (⟨q-15d763dc⟩).
+      // Keys may have reached the pane (text typed, an Enter pressed) without the screen proving the
+      // message was submitted, so it stays owed on disk: read_messages still serves it and a restart
+      // re-offers it. The in-process high-water mark alone stops it being re-typed every tick, since
+      // re-typing a message that may already be sitting in the box is the paste loop in another coat.
+      // A throw lands here too: nothing says whether a key went out before it.
+      if (!r.delivered || r.verified !== true) {
+        ctx.hw.set(key, end);
+        out.held.push({ kind: src.kind, chan: src.chan, id: String(msg.id ?? ""), why: `${r.outcome ?? (r.delivered ? "unverified" : "not delivered")} — ${r.error ?? "not verified"}; the persistent cursor was not moved (q-15d763dc)` });
+        break;
+      }
+      // It landed and was verified. Record that in-process FIRST, so a cursor write that fails
+      // cannot turn one delivery into a paste loop, then persist exactly past this line.
+      ctx.hw.set(key, end);
+      const persisted = await advancePushCursor(agentId, where, end);
+      out.delivered.push({ kind: src.kind, chan: src.chan, id: String(msg.id ?? "") });
+      if (!persisted) {
+        out.held.push({ kind: src.kind, chan: src.chan, id: String(msg.id ?? ""), why: "delivered, but the push cursor could not be written — held in memory so it is not re-typed; a restart before the next successful write may type it once more" });
+        break;
+      }
+    }
+  }
+  return out;
+}
+
+// ─── the per-process registry of running tails ─────────────────────────────
+
+type TailRecord = {
+  agentId: string;
+  startedAt: string;
+  ticks: number;
+  delivered: number;
+  held: number;
+  lastTickAt: string | null;
+  lastWhy: string | null;
+  stop: () => void;
+};
+const running = new Map<string, TailRecord>();
+
+/** What `capabilities` reports: the tails THIS PROCESS is actually running, not the ones it could run. */
+export function herdrTailState(): { agentId: string; running: true; startedAt: string; ticks: number; delivered: number; held: number; lastTickAt: string | null; lastWhy: string | null }[] {
+  return [...running.values()].map(({ stop: _stop, ...r }) => ({ ...r, running: true as const }));
+}
+
+export function stopHerdrTail(agentId: string): boolean {
+  const r = running.get(agentId);
+  if (!r) return false;
+  r.stop();
+  running.delete(agentId);
+  return true;
+}
+export function stopAllHerdrTails(): void {
+  for (const id of [...running.keys()]) stopHerdrTail(id);
+}
+
+/**
+ * Start the tail for `agentId` if this server's transport is herdr. IDEMPOTENT: a second bind of
+ * the same agent in the same process returns `running: true, started: false`.
+ *
+ * ⛔ NEVER OVERLAPS ITSELF: a tick still typing when the timer fires would interleave two pastes
+ * into one pane; the guard is one in-flight flag, because the next tick re-reads the cursor.
+ */
+export function ensureHerdrTail(
+  agentId: string,
+  opts: { transport?: Transport; pollMs?: number; seedEof?: boolean; tail?: (id: string, ctx: TailContext) => Promise<TailOutcome> } = {},
+): { started: boolean; running: boolean; why: string } {
+  const t = opts.transport ?? activeTransport();
+  if (!t || t.kind !== HERDR) return { started: false, running: false, why: `transport is ${t?.kind ?? "unwired"}, not herdr — a tmux seat is woken by its pusher` };
+  if (running.has(agentId)) return { started: false, running: true, why: "already tailing this agent in this process" };
+  const ctx = newContext(opts.seedEof === true);
+  const run = opts.tail ?? ((id: string, c: TailContext) => tailOnce(id, { transport: t, ctx: c }));
+  const rec: TailRecord = { agentId, startedAt: new Date().toISOString(), ticks: 0, delivered: 0, held: 0, lastTickAt: null, lastWhy: null, stop: () => {} };
+  let inFlight = false;
+  const timer = setInterval(() => {
+    if (inFlight) return;
+    inFlight = true;
+    void run(agentId, ctx)
+      .then((o) => {
+        rec.ticks += 1;
+        rec.lastTickAt = new Date().toISOString();
+        rec.delivered += o.delivered.length;
+        rec.held += o.held.length;
+        rec.lastWhy = o.held.at(-1)?.why ?? o.idle ?? null;
+      })
+      .catch((e) => { rec.lastWhy = `tick threw: ${(e as Error).message}`; })
+      .finally(() => { inFlight = false; });
+  }, opts.pollMs ?? DEFAULT_POLL_MS);
+  timer.unref?.(); // optional-call: `unref` is absent on some host timer shims, and a server that cannot unref its tail must still start it
+  rec.stop = () => clearInterval(timer);
+  running.set(agentId, rec);
+  return { started: true, running: true, why: `tailing ${agentId}'s inbox and rooms every ${opts.pollMs ?? DEFAULT_POLL_MS}ms` };
+}
+
+/**
+ * The hook the server calls at EVERY identity binding — `join`, a gated first claim, the env var,
+ * or (HTTP) an authenticated request from a PRE-BOUND identity.
+ *
+ * ⛔ THE BINDING TRANSITION IS NOT REACHABLE UNDER HTTP, WHICH IS WHY THIS ALSO HANGS OFF AUTH.
+ * The `bound === undefined` sites below only fire when a session CLAIMS an id. A token-authenticated
+ * daemon resolves identity per request and reports `pre-bound (N agents)`, so `bound` is never
+ * undefined and NO tail ever started — measured 2026-09-17 as `herdrTail: []` on a freshly
+ * restarted daemon whose seats had re-joined after it. With the send-time path deferring owed
+ * messages to "the recipient's own tail", a tail that never exists makes that deferral a permanent
+ * silent drop: one message behind and the seat is deaf for good (⟨q-cdb5b007⟩).
+ *
+ * Idempotent, so the per-request call costs one Map lookup once the tail is up.
+ */
+export function startTailOnBind(agentId: string, log: (line: string) => void = (l) => console.error(l)): void {
+  const r = ensureHerdrTail(agentId, { seedEof: true });
+  if (r.started) log(`[agent-coord-mcp] herdr tail: ${r.why}`);
+}

package/src/tools/jsonl-offsets.ts

@@ -0,0 +1,29 @@
+/**
+ * Messages appended to a JSONL bus file after byte `from`, each with the absolute byte offset just
+ * past its own line. Shared by the send-time herdr path and the seat's own tail, so both agree on
+ * exactly which bytes a delivery covers — a second reader would be a second truth about where a
+ * seat's cursor may move.
+ *
+ * A partial trailing line is left for the next read rather than guessed at, and a line that is not
+ * JSON is skipped with the offset moving past it.
+ */
+import { readFileSync } from "node:fs";
+
+export type OffsetMessage = { msg: Record<string, unknown>; end: number };
+
+export function newMessagesIn(file: string, from: number): OffsetMessage[] {
+  let buf: Buffer;
+  try { buf = readFileSync(file); } catch { return []; }
+  const out: OffsetMessage[] = [];
+  let pos = Math.min(Math.max(0, from), buf.length);
+  while (pos < buf.length) {
+    const nl = buf.indexOf(0x0a, pos);
+    if (nl === -1) break;
+    const line = buf.subarray(pos, nl).toString("utf8");
+    const end = nl + 1;
+    pos = end;
+    if (!line.trim()) continue;
+    try { out.push({ msg: JSON.parse(line), end }); } catch { /* not a message; the offset moves past it */ }
+  }
+  return out;
+}

package/src/tools/messaging.ts

@@ -20,6 +20,9 @@ import { readLog } from "./logwatch.js";
 // `dist/`, so this resolves the same in the built package as in source.
 // @ts-expect-error — untyped .mjs sibling, deliberately not duplicated in TS
 import { priorDeliveries, replayInfo } from "../../hooks/replay.mjs";
+// ⟨q-e5cb3538⟩ The pane-unsafe byte class is single-sourced there too, shared with the renderer.
+// @ts-expect-error — untyped .mjs sibling, deliberately not duplicated in TS
+import { findControlByte } from "../../hooks/control-bytes.mjs";
 import { renderRecord } from "./render.js";
 import path from "node:path";
 import {
@@ -344,6 +347,23 @@ export async function sendMessageTool(args: {
   const scribeCheck = checkVerdictScribe(args.from, args.record);
   if (!scribeCheck.ok) return { ok: false as const, error: scribeCheck.error };
 
+  // ⟨q-e5cb3538⟩ — INGRESS POLICY: REFUSE, don't rewrite. A control byte in content is a
+  // keystroke in every pane the message is typed into (CR submits, ESC interrupts, ETX is
+  // Ctrl-C). Refused rather than silently escaped because the stored message is what gets
+  // cited and replayed; a rewrite would make it differ from what the sender wrote, and the
+  // sender is the only party who can say what the byte was for. Line feed and tab pass.
+  // Render-time escaping (hooks/tier.mjs) still covers history stored before this check.
+  const control = findControlByte({ from: args.from, to: args.to, room: args.room, text: args.text, record: args.record, repo: args.repo });
+  if (control) {
+    return {
+      ok: false as const,
+      error:
+        `refused: '${control.path}' carries a control character (${control.escape}) at offset ${control.offset}. ` +
+        "Delivered to a pane it would be typed as a keystroke in the recipient's session. " +
+        "Remove it, or write it out visibly (e.g. \\r); quoted external text (PR bodies, commit messages) is the usual carrier. Nothing was written.",
+    };
+  }
+
   // A `done` must cite the work it claims. Presence and shape only — resolving
   // the ref against gh/git is a consumer's job, and the send path makes no
   // network calls. Rejected as a value, not a throw, mirroring the

package/src/tools/records.ts

@@ -45,7 +45,7 @@ import { verdictsFor, gatedBy, prVerdictsIn } from "../gated-head.js";
 import { boardRefFor, classifyBoardRef } from "./board-ref.js";
 import { haltState } from "./stall.js";
 import { readSubs, evaluate, commitEvaluation, eventIsDerived, type RecordEvent } from "./events.js";
-import { prRefsIn } from "./record-events.js";
+import { prRefsIn, leadingItemIdOf } from "./record-events.js";
 
 const QUEUE_DOC = "docs/QUEUE.md";
 const DONE_DOC = "docs/DONE.md";
@@ -1199,7 +1199,23 @@ export async function landTool(
     }
   }
 
-  const already = doneEntriesOf(d.doc).some((e) => new RegExp(`#${n}\\b`).test(String(e.ref ?? "")));
+  /*
+   * ⛔ ⟨q-552b9912⟩ "ALREADY LOGGED" IS A QUESTION ABOUT THE ITEM, NOT THE PR.
+   *
+   * It asked whether ANY DONE entry cited this PR, so the second item a PR closed found the first item's entry,
+   * reported `alreadyLogged: true`, and wrote nothing: the row left the queue and never reached the delivery record,
+   * so `scan_record_events` emitted no item event for it. Measured twice on 2026-09-16 — ⟨q-3b8e05af⟩ on #360 and
+   * ⟨q-144c97a8⟩ on #366, both hand-repaired (07338a1, 00c8315).
+   *
+   * Keyed per item BY POSITION ONLY: an entry is this item's when it LEADS with `⟨id⟩` (the form this verb writes). A
+   * by-mention fallback was tried and REMOVED (qa's FAIL on #370 @ fce3ae1): an id-less entry for this PR that merely
+   * MENTIONS the id — B never landed — read as logged and wrote nothing, the same defect narrowed. A mention is not a
+   * record. A land with no item keeps the PR key, since there is no item to key on.
+   */
+  const citesThisPr = (e: { ref?: string }) => new RegExp(`#${n}\\b`).test(String(e.ref ?? ""));
+  const already = target
+    ? doneEntriesOf(d.doc).some((e) => leadingItemIdOf(e.text) === target.id)
+    : doneEntriesOf(d.doc).some(citesThisPr);
 
   // A DONE LINE A HUMAN WOULD NOT HAVE WRITTEN IS NOT A DONE LINE.
   //

package/src/tools/registry.ts

@@ -6,7 +6,7 @@ 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 { detectSpread, installedBuild, pidRunning } from "../server-spread.js";
 import { z } from "zod";
 import path from "node:path";
 import {
@@ -161,6 +161,9 @@ export async function registerTool(args: {
       registeredAt: existing?.registeredAt ?? now,
       lastHeartbeat: now,
       capabilities: existing?.capabilities,
+      // ⟨q-18a719c5⟩ The entry is rebuilt here, so the stamp is rebuilt with it — from the
+      // server answering THIS register, which is the one serving the seat now.
+      ...answeringServerIdentity(),
       // Omitted → carried forward untouched. Only an explicit `false` revokes.
       ...(args.proseOnly === undefined
         ? existing?.proseOnly
@@ -285,6 +288,39 @@ export async function quitTool(args: { agentId: string }): Promise<never> {
 
 export const heartbeatSchema = { agentId: z.string().min(1) };
 
+/**
+ * ⟨q-18a719c5⟩ THE ANSWERING SERVER'S IDENTITY — what `serverSpread` places a seat by. It exists
+ * only inside the process that serves the seat, so every path on which a session binds an
+ * identity stamps it: `register` (which `join` calls), the first-claim binding in server.ts
+ * (a server that restarts and re-binds through any gated tool, `attach_agent` included),
+ * `rename_agent` (the renaming session serves the new id), and `heartbeat`. Before this,
+ * only `heartbeat` stamped, no code path called it, and `register` rebuilt the entry and
+ * dropped whatever it had written.
+ */
+export function answeringServerIdentity(): { serverPid: number; serverStartedAt: number; serverModule?: string } {
+  return {
+    serverPid: process.pid,
+    // 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.
+    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.
+    serverModule: installedBuild(import.meta.url, statSync)?.module,
+  };
+}
+
+/** Stamp an EXISTING registry entry with the answering server's identity. False when absent. */
+export async function stampServerIdentity(agentId: string): Promise<boolean> {
+  let stamped = false;
+  await updateJson<AgentRegistry>(AGENTS_FILE, {}, (current) => {
+    if (!current[agentId]) return current;
+    Object.assign(current[agentId], answeringServerIdentity());
+    stamped = true;
+    return current;
+  });
+  return stamped;
+}
+
 export async function heartbeatTool(args: { agentId: string }) {
   let missing = false;
   await updateJson<AgentRegistry>(AGENTS_FILE, {}, (current) => {
@@ -293,23 +329,8 @@ 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;
+    // ⛔ STAMP THE ANSWERING PROCESS — `⟨q-cec42e20⟩`; see `answeringServerIdentity`.
+    Object.assign(current[args.agentId], answeringServerIdentity());
     return current;
   });
   if (missing) return { ok: false, error: `agent '${args.agentId}' not registered` };
@@ -464,6 +485,8 @@ export async function listAgentsTool() {
         serverModule: a.serverModule,
       })),
     installedBuild(import.meta.url, statSync),
+    // ⟨q-18a719c5⟩ a stamp whose server is gone reads unknown: ask the kernel, here, in production.
+    { isRunning: pidRunning },
   );
 
   // ⟨q-178878aa⟩ — the humans the bus knows: visible here, read at send time, never evicted.
@@ -541,6 +564,18 @@ export function isMarkerLive(marker: TransportMarker, reg: AgentRegistry, now: n
   return isPidAlive(marker.pid);
 }
 
+/**
+ * ⟨q-abd88dd4⟩ Does this marker hold a LIVE LOCAL PROCESS — a pusher someone could signal, or
+ * wait on? A herdr marker never does: it has no pusher, and its `pid` is addressed to pre-herdr
+ * readers (pid 1, see `herdrMarkerPid`), so reading it as a process would make pid 1 look like a
+ * running pusher. Every pid-as-process decision about a marker goes through here; liveness of a
+ * herdr seat is `isMarkerLive`, which asks herdr for the pane.
+ */
+export function markerHoldsLiveProcess(marker: TransportMarker | null | undefined): boolean {
+  if (!marker || marker.transport === HERDR) return false;
+  return isPidAlive(marker.pid);
+}
+
 export function isPidAlive(pid: number): boolean {
   if (!pid || pid <= 0) return false;
   try {
@@ -682,7 +717,7 @@ export async function renameAgentTool(args: { agentId: string; newAgentId: strin
   // must re-attach under the new id (join/attach_agent) to restore push.
   const liveTransport = await readJson<TransportMarker | null>(transportFile(oldId), null);
   let detachedTransport = false;
-  if (liveTransport && isPidAlive(liveTransport.pid)) {
+  if (markerHoldsLiveProcess(liveTransport)) {
     await detachAgentTool({ agentId: oldId });
     detachedTransport = true;
   }
@@ -690,7 +725,8 @@ export async function renameAgentTool(args: { agentId: string; newAgentId: strin
   // Registry: move the entry under the new key.
   await updateJson<AgentRegistry>(AGENTS_FILE, {}, (current) => {
     if (current[oldId]) {
-      current[newId] = { ...current[oldId], agentId: newId };
+      // ⟨q-18a719c5⟩ The renaming session serves the new id, so the stamp is re-taken from it.
+      current[newId] = { ...current[oldId], agentId: newId, ...answeringServerIdentity() };
       delete current[oldId];
     }
     return current;