agent-coord-mcp 0.26.23 → 0.26.25

package/src/tools/herdr-tail.ts

@@ -0,0 +1,244 @@
+/**
+ * ⛔ 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>;
+};
+export const newContext = (): TailContext => ({ tick: 0, marker: null, rooms: [], hw: new Map(), sizes: new Map() });
+
+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);
+    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; 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();
+  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, or the env var. */
+export function startTailOnBind(agentId: string, log: (line: string) => void = (l) => console.error(l)): void {
+  const r = ensureHerdrTail(agentId);
+  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/queue-write.ts

@@ -395,7 +395,10 @@ export async function queueWriteTool(args: {
               `item by hand once, or move the queue section last.`,
           );
         }
-        const w0 = writeDoc(repo, QUEUE_DOC, reparsed, original);
+        // `own` names the row this call authored. It is already recorded above, so this
+  // changes nothing today — it is stated so the guarantee survives a refactor that
+  // stops pre-stamping, rather than depending on line 361 staying where it is.
+  const w0 = writeDoc(repo, QUEUE_DOC, reparsed, original, [], [target.id]);
         return {
           ok: true,
           op: args.op,

package/src/tools/record-events.ts

@@ -120,6 +120,48 @@ const norm = (s: string) => String(s).toLowerCase().replace(/[`*_]/g, "").replac
  * against them by the caller (`eventIsDerived`), so a diff that has since been
  * reverted cannot produce an event that outlives the record.
  */
+/**
+ * ⟨q-…⟩ PHASE COMPLETENESS IS THE ABSENCE OF AN UNTICKED BOX, AND IT MUST NOT DEPEND ON WHAT
+ * A BOX IS CALLED.
+ *
+ * ⛔ MEASURED, NOT REASONED — a false "phase 5.4 complete" event was emitted and DELIVERED on
+ * 2026-09-16 at `579db9d`. The detector's box pattern required a label shaped `\d+\.\d+`, so
+ * against the real document it saw **31 of 36** checkboxes, every one of them ticked, and
+ * fired. The three it could not see were `3B.2`, `3B.3` and `3B.4` — labels with a LETTER
+ * inside the number — and `3B.3` is deliberately unticked and not recoverable.
+ *
+ * ⚠ SO THE CAUSE IS THE LABEL PATTERN, NOT THE POSITION OF THE LAST BOX. The event cited
+ * `- [x] 6.4`, the document's final line, which made it look like a last-line rule; the ref is
+ * only what it cites. Any doc whose remaining work carries an unanticipated label reported
+ * itself finished, wherever that work sat.
+ *
+ * ⭐ THE FIX IS A DIFFERENT QUESTION, not a wider regex for the same one: "is any checkbox in
+ * this document unticked" is asked over EVERY markdown checkbox, whatever follows it. A label
+ * shape nobody has invented yet cannot defeat it. The failure direction is deliberate — an
+ * unticked box anywhere blocks the event, so an unrecognised box costs a MISSED completion,
+ * never a FALSE one. This code's own comment already said which way to lean: *"A false
+ * completion is worse than a missing one: it closes a phase nobody finished."*
+ */
+export const ANY_BOX = /^[ \t]*[-*+][ \t]*\[([ xX])\][ \t]*(.*)$/;
+export const TICKED_BOX = /^[ \t]*[-*+][ \t]*\[[xX]\]/;
+
+export type PhaseBox = { ticked: boolean; label: string | null; line: string };
+
+/** Every markdown checkbox in a phase document, in file order, label-agnostic. */
+export function checkboxesIn(text: string): PhaseBox[] {
+  const out: PhaseBox[] = [];
+  for (const raw of String(text).split("\n")) {
+    const m = ANY_BOX.exec(raw);
+    if (!m) continue;
+    const rest = m[2] ?? "";
+    out.push({ ticked: m[1]!.toLowerCase() === "x", label: (/^\*{0,2}([A-Za-z0-9][A-Za-z0-9.]*)\b/.exec(rest) ?? [])[1] ?? null, line: raw.trim() });
+  }
+  return out;
+}
+
+/** The unticked boxes, for a caller that wants to say WHY it did not fire. */
+export const untickedIn = (text: string): PhaseBox[] => checkboxesIn(text).filter((b) => !b.ticked);
+
 export function eventsFromCommittedChange(
   diff: string,
   after: { done?: string; phases?: Record<string, string> } = {},
@@ -257,14 +299,14 @@ export function eventsFromCommittedChange(
   // finished.
   for (const [rel, text] of Object.entries(after.phases ?? {})) {
     if (!isPhaseDoc(rel)) continue;
-    const boxes = [...String(text).matchAll(/^\s*-\s*\[( |x)\]\s*\*{0,2}(\d+\.\d+[a-z]?)\b/gim)];
-    if (!boxes.length || boxes.some((m) => m[1] !== "x")) continue;
+    const boxes = checkboxesIn(String(text));
+    if (!boxes.length || boxes.some((b) => !b.ticked)) continue;
     // This commit must have ticked a box IN THIS FILE.
-    const closedHere = (byFile.get(rel)?.added ?? []).some((l) => /^\s*-\s*\[x\]\s*\*{0,2}\d+\.\d+/.test(l));
+    const closedHere = (byFile.get(rel)?.added ?? []).some((l) => TICKED_BOX.test(l));
     if (!closedHere) continue;
     const phase = /phase(\d+(?:\.\d+)?)/i.exec(rel)?.[1];
     if (!phase) continue;
-    events.push({ kind: "phase", target: phase, ref: boxes[boxes.length - 1]![0].trim(), summary: `phase ${phase} — every task box ticked` });
+    events.push({ kind: "phase", target: phase, ref: boxes[boxes.length - 1]!.line, summary: `phase ${phase} — every task box ticked` });
   }
 
   lastUnattributedItems = unattributedItems;

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";
@@ -149,8 +149,12 @@ export function writeDoc(
   doc: WorkDoc,
   original: string,
   alreadyWritten: string[] = [],
+  own: readonly string[] = [],
 ): { written: boolean; stamped: string[] } {
-  const { text, stamped } = renderWorkDocForWrite(doc);
+  // `own` = the rows THIS CALL authored. Everything else is stamped only if the
+  // document already speaks the recorded-id grammar — see `stampQueueIds`, which
+  // holds the rule so both writers cannot drift apart on it.
+  const { text, stamped } = renderWorkDocForWrite(doc, { own });
   if (text === original) return { written: false, stamped: [] };
   const p = path.join(repo, rel);
   const current = existsSync(p) ? readFileSync(p, "utf8") : "";
@@ -1195,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.
   //
@@ -1265,7 +1285,7 @@ export async function landTool(
   try {
   if (args.write) {
     if (queueChanged) {
-      const w = writeDoc(repo, QUEUE_DOC, q.doc, q.text, wrote);
+      const w = writeDoc(repo, QUEUE_DOC, q.doc, q.text, wrote, args.queueItemId ? [args.queueItemId] : []);
       if (w.written) wrote.push(QUEUE_DOC);
       // Rows stamped that this call did not ask to touch. `queueItemId` is the
       // one item the caller supplied, so anything else here is a row that

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;