agent-coord-mcp 0.26.34 → 0.26.39

package/src/tools/events.ts

@@ -23,11 +23,31 @@ const subsFile = () => path.join(ROOT, "subscriptions.json");
 // only if the enum cannot be widened without an emitter.
 export { EVENT_KINDS, EVENT_KIND_IDS };
 export type { RecordEvent, SubKind };
+/**
+ * ⟨q-8e00b367⟩(a) — HOW WIDELY A SUBSCRIPTION IS ASKING, as an EXPLICIT FIELD.
+ *
+ * ⛔ THE ALTERNATIVE WAS AN IN-BAND SENTINEL AND IT IS FORBIDDEN BY DESIGN. `target: "*"` would make
+ * one string mean two things — a literal target that happens to be an asterisk, and "everything" —
+ * and nothing in the wire shape would say which was meant. A separate field cannot be ambiguous.
+ *
+ * ⚠ `prefix` IS A PREFIX OF WHATEVER `target` HOLDS FOR THAT KIND, which differs per kind and is not
+ * guessable from the name: `pr` → the full ref (`owner/repo#402`), `item` → the queue id, `task` →
+ * the KEY (its `ref` is the ticked LINE, so a prefix here is NOT a prefix of the line), `phase` →
+ * the phase. Measured from the emitters in record-events.ts, not from documentation.
+ */
+export const SUB_SCOPES = ["exact", "kind", "prefix"] as const;
+export type SubScope = (typeof SUB_SCOPES)[number];
+
 export type Subscription = {
   id: string;
   agentId: string;
   kind: SubKind;
   target: string;
+  /**
+   * Absent ⇒ `"exact"`, which is what every subscription stored before this field meant. The
+   * widening is ADDITIVE: no migration, and no stored registration changes meaning.
+   */
+  scope?: SubScope;
   createdAt: number;
   /**
    * null until an event OF THIS KIND was evaluated against this subscription.
@@ -195,9 +215,33 @@ export function eventIsDerived(recordText: string, ev: RecordEvent): { ok: true
   return { ok: true };
 }
 
-/** Subscriptions matching an event. Exact target match; no wildcards yet. */
+/**
+ * Subscriptions matching an event, by the scope each one asked for.
+ *
+ * ⛔ THE GAP THIS CLOSES IS A DELIVERY OF NOTHING REPORTED AS A DELIVERY. With exact-only matching,
+ * "tell me when a new PR arrives" is inexpressible — a `pr` event's `target` IS its ref, so you would
+ * have to name `owner/repo#402` at subscribe time, and the entire point is that you do not know it
+ * yet. A poller could then scan correctly, emit a well-formed event, and match ZERO subscriptions
+ * while every instrument reported success: the tick exits 0, the scan finds a change, the emit
+ * succeeds, `list_subscriptions` shows healthy watches. Nothing anywhere reads as wrong.
+ *
+ * ⚠ `exact` REMAINS THE DEFAULT, so a widened match is always something a subscriber opted into.
+ */
 export const matching = (subs: Subscription[], ev: RecordEvent): Subscription[] =>
-  subs.filter((s) => s.kind === ev.kind && s.target === ev.target);
+  subs.filter((s) => {
+    if (s.kind !== ev.kind) return false;
+    switch (s.scope ?? "exact") {
+      case "kind":
+        return true;
+      // `startsWith` on a non-empty prefix only: an EMPTY prefix matches every target, which is the
+      // `"*"` sentinel this design rejected, arriving through the field that replaced it. `subscribe`
+      // refuses to create one; this guard means a hand-edited store cannot smuggle one in either.
+      case "prefix":
+        return s.target !== "" && ev.target.startsWith(s.target);
+      default:
+        return s.target === ev.target;
+    }
+  });
 
 export type Delivery = { subscriptionId: string; agentId: string; key: string; status: "delivered" | "duplicate-suppressed" };
 
@@ -244,18 +288,59 @@ export function evaluate(subs: Subscription[], ev: RecordEvent, now: number): {
 export const subscribeSchema = {
   agentId: z.string().min(1),
   kind: z.enum(EVENT_KIND_IDS),
+  // ⚠ STILL REQUIRED AND STILL `min(1)`. `scope:"kind"` does not relax it — it REFUSES it (below), so
+  // there is no shape where an empty or absent target is accepted. Relaxing the schema instead would
+  // have made `target:""` representable, which is the wildcard this design exists to keep out.
   target: z.string().min(1),
+  // A CLOSED SET, never a free string. The registry generates the kind enum so that a subscription
+  // which no emitter can satisfy cannot be registered; a free-form scope would reopen exactly that
+  // hole one field over — an unsatisfiable scope is an unsatisfiable subscription.
+  scope: z.enum(SUB_SCOPES).optional(),
 };
 
-export async function subscribeTool(args: { agentId: string; kind: SubKind; target: string }) {
+export async function subscribeTool(args: { agentId: string; kind: SubKind; target: string; scope?: SubScope }) {
+  const scope: SubScope = args.scope ?? "exact";
+
+  // ⛔ `kind` + A TARGET IS REFUSED, NOT IGNORED. An accepted-and-ignored target leaves a
+  // subscription that READS NARROWER THAN IT BEHAVES: an inspector sees one specific target and
+  // concludes the watch is narrow, while it fires on everything of that kind.
+  //
+  // ⭐ AND THE ASYMMETRY IS WHAT DECIDES IT RATHER THAN TASTE: refusing is relaxable later, whereas
+  // silently-ignoring is NOT tightenable later — the moment such subscriptions exist on disk,
+  // tightening changes what an already-stored registration means.
+  if (args.scope === "kind" && args.target)
+    return {
+      ok: false as const,
+      error:
+        `scope "kind" watches EVERY ${args.kind} event, so the target '${args.target}' would be ignored — refusing rather than ` +
+        `accepting a subscription that reads narrower than it behaves. Omit the target for kind-wide, ` +
+        `or use scope "prefix" with '${args.target}' to watch the ${args.kind} events whose target starts with it.`,
+    };
+
+  // ⛔ AN EMPTY PREFIX IS THE `"*"` WILDCARD WEARING THE FIELD THAT REPLACED IT. `"".startsWith()` is
+  // true of every string, so `scope:"prefix"` with an empty target subscribes to everything of the
+  // kind while LOOKING like a narrow, targeted watch — the same back door as `target:"*"`, one layer
+  // down and through an approved field. `kind` is how you ask for everything, and it says so.
+  if (scope === "prefix" && args.target.trim() === "")
+    return {
+      ok: false as const,
+      error:
+        `scope "prefix" with an empty target matches EVERY ${args.kind} event — that is the wildcard this ` +
+        `field exists to avoid spelling in-band. Use scope "kind" to watch all of them explicitly, or ` +
+        `give a non-empty prefix (e.g. 'davidbalzan/groundwork-kit#' for one repo's PRs).`,
+    };
+
   const subs = readSubs();
-  const dupe = subs.find((s) => s.agentId === args.agentId && s.kind === args.kind && s.target === args.target);
+  // Identity includes the SCOPE: `exact` on 'q-1' and `prefix` on 'q-1' are different watches, and
+  // collapsing them would silently hand back the narrower one.
+  const dupe = subs.find((s) => s.agentId === args.agentId && s.kind === args.kind && s.target === args.target && (s.scope ?? "exact") === scope);
   if (dupe) return { ok: true as const, subscription: dupe, note: "already subscribed — returning the existing registration rather than a second one" };
   const sub: Subscription = {
     id: randomUUID(),
     agentId: args.agentId,
     kind: args.kind,
     target: args.target,
+    scope,
     createdAt: Date.now(),
     // EXPLICIT null, never left absent. `null` means "we know no scan has run
     // for this"; `undefined` means "this record predates the field and we

package/src/tools/herdr-delivery.ts

@@ -23,8 +23,8 @@
 import { mkdirSync, statSync } from "node:fs";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
-import { activeTransport, HERDR, type TransportMarker } from "../transports/index.js";
-import { ROOT, inboxFile, roomFile } from "../store.js";
+import { activeTransport, HERDR, targetOf, type TransportMarker } from "../transports/index.js";
+import { ROOT, inboxFile, roomFile, withDeliveryLock } from "../store.js";
 import { loadLiveTransports } from "./registry.js";
 import { newMessagesIn } from "./jsonl-offsets.js";
 import type { Message } from "./shared.js";
@@ -46,6 +46,8 @@ const safeId = (id: string) => id.replace(/[^A-Za-z0-9._-]/g, "_");
 
 
 export type Where = { kind: "dm" } | { kind: "room"; chan: string };
+/** The (seat, source) key the delivery lock is taken on — ONE spelling, shared by the send-time path and the tail. */
+export const sourceKey = (where: Where) => (where.kind === "dm" ? "dm" : `room:${where.chan}`);
 
 /**
  * ⭐ ONE RENDERER AND ONE CURSOR RULE, SHARED BY BOTH PATHS. The send-time path
@@ -102,9 +104,15 @@ export async function readPushCursorFor(agentId: string): Promise<Record<string,
 }
 
 export type HerdrDeliveryOutcome = { agentId: string; delivered: boolean; enters?: number; error?: string; cursorAdvanced: boolean; deferred?: string };
+/** Every push, whichever path made it, is logged NAMING THE PATH — so a duplicate is separable from a retried write without transcript archaeology (⟨q-524305dd⟩). */
+export const pushLogLine = (path: "send-time" | "tail", id: unknown, target: string | undefined, outcome: string, error?: string) =>
+  `[herdr-${path === "tail" ? "tail" : "delivery"}] push id=${String(id ?? "?")} target=${target ?? "?"} outcome=${outcome}` +
+  (error ? ` reason=${JSON.stringify(error)}` : "") +
+  ` path=${path}`;
 
 /** Deliver one just-appended message to every herdr-attached recipient among `recipients`. */
-export async function deliverToHerdrSeats(msg: Message, recipients: string[], where: { kind: "dm" } | { kind: "room"; chan: string }): Promise<HerdrDeliveryOutcome[]> {
+export async function deliverToHerdrSeats(msg: Message, recipients: string[], where: { kind: "dm" } | { kind: "room"; chan: string }, opts: { log?: (line: string) => void } = {}): Promise<HerdrDeliveryOutcome[]> {
+  const log = opts.log ?? ((l: string) => console.error(l));
   const t = activeTransport();
   if (!t || t.kind !== HERDR) return [];
   let markers: Map<string, TransportMarker>;
@@ -122,34 +130,41 @@ export async function deliverToHerdrSeats(msg: Message, recipients: string[], wh
     // The coordinator's gate named the old call as "still advances the cursor to EOF"; measured,
     // it did exactly that. So: find THIS message after the persisted cursor; if any earlier
     // message to someone else precedes it, defer to the recipient's tail, which delivers in order.
-    const file = where.kind === "dm" ? inboxFile(agentId) : roomFile(where.chan);
-    const c = await readPushCursorFor(agentId);
-    const from = where.kind === "dm" ? Number(c.inboxOffset ?? 0) : Number(((c.roomOffsets as Record<string, number> | undefined) ?? {})[where.chan] ?? 0);
-    const after = newMessagesIn(file, from);
-    const at = after.findIndex((m) => m.msg.id === msg.id);
-    const owed = at === -1 ? [] : after.slice(0, at).filter((m) => m.msg.from !== agentId);
-    if (at === -1 || owed.length > 0) {
-      out.push({
-        agentId,
-        delivered: false,
-        cursorAdvanced: false,
-        deferred: at === -1
-          ? "this message is not after the push cursor (already delivered, or the file moved) — left to the recipient's tail"
-          : `${owed.length} earlier message(s) to this seat are still owed — left to the recipient's own tail, which delivers in order`,
-      });
-      continue;
-    }
-    const rendered = await renderForPane(msg, agentId, where);
-    // A control never comes through here: send_command hands a herdr seat's control to the
-    // transport's sendControl directly (a raw-vs-rendered branch here was dead and its
-    // mutation survived, so it is gone). Everything delivered here is a rendered message.
-    let r: { delivered: boolean; error?: string; enters?: number; verified?: boolean };
-    try { r = await t.push(marker, rendered); } catch (e) { r = { delivered: false, error: (e as Error).message }; }
-    // ⟨q-15d763dc⟩ Only a VERIFIED delivery moves the cursor; anything less leaves the message owed.
-    const verified = r.delivered && r.verified === true;
-    // Exactly past THIS message's line — never to the end of the file, which may already hold a later one.
-    const cursorAdvanced = verified ? await advancePushCursor(agentId, where, after[at]!.end) : false;
-    out.push({ agentId, delivered: verified, enters: r.enters, error: r.error ?? (r.delivered ? "delivered but not verified — cursor held (q-15d763dc)" : undefined), cursorAdvanced });
+    // ⛔ ⟨q-524305dd⟩ read → type → verify → advance as the ONLY deliverer to this seat's source, across
+    // processes: the seat's own tail takes the same lock, so it cannot read this cursor mid-verify and
+    // type the message a second time. WAIT, never skip: the seat may have no tail at all (⟨q-cdb5b007⟩).
+    const locked = await withDeliveryLock(agentId, sourceKey(where), async () => {
+      const file = where.kind === "dm" ? inboxFile(agentId) : roomFile(where.chan);
+      const c = await readPushCursorFor(agentId);
+      const from = where.kind === "dm" ? Number(c.inboxOffset ?? 0) : Number(((c.roomOffsets as Record<string, number> | undefined) ?? {})[where.chan] ?? 0);
+      const after = newMessagesIn(file, from);
+      const at = after.findIndex((m) => m.msg.id === msg.id);
+      const owed = at === -1 ? [] : after.slice(0, at).filter((m) => m.msg.from !== agentId);
+      if (at === -1 || owed.length > 0) {
+        out.push({
+          agentId,
+          delivered: false,
+          cursorAdvanced: false,
+          deferred: at === -1
+            ? "this message is not after the push cursor (already delivered, or the file moved) — left to the recipient's tail"
+            : `${owed.length} earlier message(s) to this seat are still owed — left to the recipient's own tail, which delivers in order`,
+        });
+        return;
+      }
+      const rendered = await renderForPane(msg, agentId, where);
+      // A control never comes through here: send_command hands a herdr seat's control to the
+      // transport's sendControl directly (a raw-vs-rendered branch here was dead and its
+      // mutation survived, so it is gone). Everything delivered here is a rendered message.
+      let r: { delivered: boolean; error?: string; enters?: number; verified?: boolean };
+      try { r = await t.push(marker, rendered); } catch (e) { r = { delivered: false, error: (e as Error).message }; }
+      // ⟨q-15d763dc⟩ Only a VERIFIED delivery moves the cursor; anything less leaves the message owed.
+      const verified = r.delivered && r.verified === true;
+      log(pushLogLine("send-time", msg.id, targetOf(marker), verified ? "delivered" : r.delivered ? "typed-unconfirmed" : "not-delivered", r.error));
+      // Exactly past THIS message's line — never to the end of the file, which may already hold a later one.
+      const cursorAdvanced = verified ? await advancePushCursor(agentId, where, after[at]!.end) : false;
+      out.push({ agentId, delivered: verified, enters: r.enters, error: r.error ?? (r.delivered ? "delivered but not verified — cursor held (q-15d763dc)" : undefined), cursorAdvanced });
+    }, { wait: true, log });
+    if (!locked.ran) out.push({ agentId, delivered: false, cursorAdvanced: false, deferred: `${locked.why} — left to that deliverer, which types in order` });
   }
   return out;
 }

package/src/tools/herdr-tail.ts

@@ -38,10 +38,10 @@
  * `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 { inboxFile, roomFile, getRooms, transportFile, withDeliveryLock } from "../store.js";
 import { activeTransport, HERDR, targetOf, type Transport, type TransportMarker } from "../transports/index.js";
-import { renderForPane, advancePushCursor, readPushCursorFor, type Message } from "./herdr-delivery.js";
-import { newMessagesIn } from "./jsonl-offsets.js";
+import { renderForPane, advancePushCursor, readPushCursorFor, pushLogLine, sourceKey, type Message } from "./herdr-delivery.js";
+import { newMessagesIn, idEndingAt, endOfId } 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. */
@@ -61,6 +61,12 @@ export type TailContext = {
   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>;
+  /**
+   * The id of the message each `hw` mark was set just past (null: set with no message, e.g. an EOF
+   * seed of a file whose last line has no id). A byte mark means something only while THAT message
+   * still ends there — see the rewrite check in tailOnce.
+   */
+  hwId: Map<string, string | null>;
   /** Last seen size per source: a source that has not grown costs one stat. */
   sizes: Map<string, number>;
   /**
@@ -73,10 +79,18 @@ export type TailContext = {
   seedEof: boolean;
   /** Sources already seeded — a room discovered on a later refresh is seeded on ITS first sight, not skipped. */
   seeded: Set<string>;
+  /** Sources whose persisted cursor is past EOF right now — logged once on entry, not on every tick. */
+  pastEof: Set<string>;
 };
-export const newContext = (seedEof = false): TailContext => ({ tick: 0, marker: null, rooms: [], hw: new Map(), sizes: new Map(), seedEof, seeded: new Set() });
+export const newContext = (seedEof = false): TailContext => ({ tick: 0, marker: null, rooms: [], hw: new Map(), hwId: new Map(), sizes: new Map(), seedEof, seeded: new Set(), pastEof: new Set() });
 
-const keyOf = (s: { kind: string; chan?: string }) => (s.kind === "dm" ? "dm" : `room:${s.chan}`);
+/** ONE spelling with the send-time path: the delivery lock is taken on this key by both (⟨q-524305dd⟩). */
+const keyOf = (s: { kind: string; chan?: string }) => sourceKey(s.kind === "dm" ? { kind: "dm" } : { kind: "room", chan: s.chan! });
+/** Set the in-process mark just past `msg`, remembering which message it follows. */
+const mark = (ctx: TailContext, key: string, end: number, msg: Record<string, unknown>) => {
+  ctx.hw.set(key, end);
+  ctx.hwId.set(key, msg.id === undefined || msg.id === null ? null : String(msg.id));
+};
 const sizeOf = (file: string): number => {
   try { return statSync(file).size; } catch { return 0; }
 };
@@ -169,58 +183,100 @@ export async function tailOnce(
     if (ctx.seedEof && !ctx.seeded.has(key)) {
       ctx.seeded.add(key);
       ctx.hw.set(key, size);
+      ctx.hwId.set(key, idEndingAt(src.file, size));
       log(`[herdr-tail] seeded ${key} at EOF (${size} bytes) for ${agentId} — first sight this process, nothing predating the tail will be typed`);
       continue;
     }
-    const from = await offsetOf(agentId, src, ctx);
-    // ⭐ NEGATIVE CONTROL FOR THE CLASS THIS ROW IS ABOUT: nothing is logged here when
-    // `size === from` — a source with nothing owed must stay silent, or every idle room on
-    // every tick becomes a line and the log that is supposed to make a real stall visible
-    // drowns in ones that are not.
-    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 }; }
-      // ⟨q-1ce5bc97⟩ step 1(b) — EVERY push outcome, logged, before any branch decides what to do
-      // with it. Not just the ones that end up `held`: a `delivered` needs a line too, or the
-      // log can never distinguish "nothing was owed" from "something was pushed and it worked".
-      log(
-        `[herdr-tail] push id=${String(msg.id ?? "?")} target=${targetOf(marker) ?? "?"} outcome=${r.outcome ?? (r.delivered ? "delivered" : "unknown")}` +
-          (r.error ? ` reason=${JSON.stringify(r.error)}` : ""),
-      );
-      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;
+    // ⛔ A BYTE MARK IS ONLY VALID WHILE THE SAME MESSAGE STILL ENDS THERE (⟨q-f44f17a7⟩). Any sender's
+    // server compacts a room on send, and every byte after the cut then means something else. A mark
+    // left PAST the new EOF made the seat deaf until the room regrew past it (the 40-minute blind
+    // stretch of 2026-09-24); a mark left INSIDE the new file resumes mid-stream and skips whatever
+    // now sits below it. So the mark is checked against the message it was set after: moved to where
+    // that message now ends, or — if it was archived — dropped, and the PERSISTED cursor, which the
+    // compactor rebased exactly (adjustCursors → rebaseBytes), is the position again.
+    // ⛔ ⟨q-524305dd⟩ THE SAME LOCK THE SENDER'S SEND-TIME PUSH TAKES. Without it, this tick read the push
+    // cursor while a sender's server was mid-verify on the same message and typed it a second time. A
+    // tick never waits for it: whoever holds it is delivering, and the next tick re-reads the cursor.
+    const locked = await withDeliveryLock(agentId, key, async () => {
+      const held = ctx.hw.get(key);
+      if (held !== undefined && idEndingAt(src.file, held) !== (ctx.hwId.get(key) ?? null)) {
+        const id = ctx.hwId.get(key);
+        const moved = id ? endOfId(src.file, id) : null;
+        log(`[herdr-tail] ${key} for ${agentId} was rewritten beneath the in-process mark (byte ${held}, after ${id ?? "no id"}) — ${moved !== null ? `moved to byte ${moved}, where that message now ends` : "that message is gone; resuming from the rebased push cursor"}`);
+        if (moved !== null) ctx.hw.set(key, moved);
+        else { ctx.hw.delete(key); ctx.hwId.delete(key); }
       }
-      // ⛔ 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;
+      const from = await offsetOf(agentId, src, ctx);
+      // …and if the PERSISTED cursor is past EOF too, the compactor has not rebased it yet (it rewrites
+      // the file first, then the cursors) or a server without this fix compacted. `size <= from` below
+      // skips it either way; this only makes the state VISIBLE, once per entry — on 2026-09-24 the only
+      // measurements of this defect came from a seat reading the room file by hand.
+      if (from > size) {
+        if (!ctx.pastEof.has(key)) log(`[herdr-tail] ${key} push cursor for ${agentId} is past EOF (${from} > ${size} bytes) — nothing can be typed from there until it is rebased or the file regrows past it (q-f44f17a7)`);
+        ctx.pastEof.add(key);
+      } else ctx.pastEof.delete(key);
+      // ⭐ NEGATIVE CONTROL FOR THE CLASS THIS ROW IS ABOUT: nothing is logged here when
+      // `size === from` — a source with nothing owed must stay silent, or every idle room on
+      // every tick becomes a line and the log that is supposed to make a real stall visible
+      // drowns in ones that are not.
+      if (size <= from) return;
+
+      for (const { msg, end } of newMessagesIn(src.file, from)) {
+        if (msg.from === agentId) { mark(ctx, key, end, msg); 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 }; }
+        // ⟨q-1ce5bc97⟩ step 1(b) — EVERY push outcome, logged, before any branch decides what to do
+        // with it. Not just the ones that end up `held`: a `delivered` needs a line too, or the
+        // log can never distinguish "nothing was owed" from "something was pushed and it worked".
+        log(pushLogLine("tail", msg.id, targetOf(marker), r.outcome ?? (r.delivered ? "delivered" : "unknown"), r.error));
+        // ⛔⛆ A `pending` IS RE-PUSHED, AND THAT IS THE CURE — NOT AN EXCLUSION. `pending` means the payload
+        // was typed and Enter pressed and it did NOT submit, so the composer now holds that text.
+        // ⚠ THE FIRST FIX HERE WAS TO SKIP THE RE-PUSH, and it was wrong: it stops the retype loop but the
+        // dirty composer then HOLDS every later message to that pane while the seat reads QUIET instead of
+        // WEDGED. Curing the loop is not curing the symptom.
+        // ⭐ What re-pushing now does depends on which transport this server loaded, and BOTH are correct:
+        //   • NEW (this build): the transport recognises a payload IT left un-submitted and PRESSES ENTER
+        //     rather than retyping — the message goes out on the next tick with no human involved.
+        //   • OLD (0.26.36, what the fleet is still running): the push refuses on the draft, which is
+        //     today's behaviour exactly, so this is no regression while the servers wait on a restart.
+        // ⛔ Either way it lands in `out.held` BELOW, so the state is VISIBLE every tick with the pane named
+        // and the human action spelled out. A silent park is the one outcome ruled out.
+        // ⛔ AND THE ENTER CANNOT LIVE HERE: a consumer cannot press a key, only ask the transport to push.
+        // Restarting the servers that would load it is David's call, not this slice's ⟨q-1ce5bc97⟩.
+        if (!r.delivered && r.safeToRetry === true) {
+          // NO VERIFIED DELIVERY and the transport says a retry could work: either nothing was typed (no
+          // ready input box, a foreign draft, a dialog, an unreadable pane) or the payload is sitting
+          // un-submitted in the box. Stop this source either way, so no later message is typed past one
+          // that did not land, and re-read next tick.
+          out.held.push({ kind: src.kind, chan: src.chan, id: String(msg.id ?? ""), why: r.error ?? (r.outcome === "pending" ? "pending — typed but not submitted" : "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) {
+          mark(ctx, key, end, msg);
+          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.
+        mark(ctx, key, end, msg);
+        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;
+        }
       }
-    }
+    }, { wait: false, log });
+    if (!locked.ran) ctx.sizes.delete(key); // another deliverer holds this source: re-read on the next tick
   }
   return out;
 }

package/src/tools/jsonl-offsets.ts

@@ -27,3 +27,26 @@ export function newMessagesIn(file: string, from: number): OffsetMessage[] {
   }
   return out;
 }
+
+/**
+ * The id of the message whose line ends EXACTLY at byte `end`, or null (no such line, past EOF, not
+ * JSON, no id). What makes a byte offset checkable: a position is only still valid while the SAME
+ * message ends there — a compaction rewrites the file and every byte after the cut then means
+ * something else (⟨q-f44f17a7⟩).
+ */
+export function idEndingAt(file: string, end: number): string | null {
+  let buf: Buffer;
+  try { buf = readFileSync(file); } catch { return null; }
+  if (end <= 0 || end > buf.length || buf[end - 1] !== 0x0a) return null;
+  const start = end >= 2 ? buf.lastIndexOf(0x0a, end - 2) + 1 : 0;
+  try {
+    const id = (JSON.parse(buf.subarray(start, end - 1).toString("utf8")) as { id?: unknown }).id;
+    return id === undefined || id === null ? null : String(id);
+  } catch { return null; }
+}
+
+/** The byte just past the line of the message with this id, or null if the file no longer holds it. */
+export function endOfId(file: string, id: string): number | null {
+  for (const { msg, end } of newMessagesIn(file, 0)) if (String(msg.id ?? "") === id) return end;
+  return null;
+}

package/src/tools/messaging.ts

@@ -549,7 +549,7 @@ async function maybeCompactRoom(chan: string): Promise<void> {
     archiveRoomFile(chan),
     (e) => e.ts >= boundaryTs || (isDecision(e) && e.ts > decisionCutoff)
   );
-  if (r.removed > 0) await adjustCursors({ roomRemovedByChan: { [chan]: r.removed } });
+  if (r.removed > 0) await adjustCursors({ roomByChan: { [chan]: r } });
 }
 
 async function maybeCompactStatus(): Promise<void> {
@@ -562,7 +562,7 @@ async function maybeCompactStatus(): Promise<void> {
     ARCHIVE_STATUS_FILE,
     (e) => e.ts >= boundaryTs
   );
-  if (r.removed > 0) await adjustCursors({ statusRemoved: r.removed });
+  if (r.removed > 0) await adjustCursors({ status: r });
 }
 
 // ---------- read_messages ----------

package/src/tools/registry.ts

@@ -660,9 +660,61 @@ export async function liveClaimEvidence(agentId: string, now: number): Promise<C
     // for the fleet that runs on herdr: every seat was refused by its own leftover marker (6 of 6 on
     // 2026-09-23). The pane comes from THIS process's environment, never from the caller's argument.
     const ownPane = ownPaneTarget(marker.transport);
-    if (targetOf(marker) && ownPane && targetOf(marker) === ownPane) {
-      samePane = true;
-      reasons.push(`the marker names THIS process's own pane (${ownPane})`);
+    const markerPane = targetOf(marker);
+    if (markerPane && ownPane) {
+      // ⟨q-f995c3c7⟩ NEXT LAYER — COMPARE PANE IDENTITIES, NOT SPELLINGS. `===` on the two strings was
+      // the whole remaining defect: one pane has more than one name, and this seat's env said
+      // `wA5:p1` while its own marker said `wA3:p4` for the SAME pane. Every herdr seat had to be
+      // hand-staged to its env spelling before a restart, and the standdown manifest grew an
+      // `attachWith` field to carry the workaround. herdr already answers the canonical id for
+      // either name, so the fix is to ask it.
+      const resolver = activeTransport();
+      const canAsk = marker.transport === HERDR && resolver?.kind === HERDR && resolver instanceof HerdrTransport;
+      const mine = canAsk ? resolver.resolvePaneId(ownPane) : null;
+      const theirs = canAsk ? resolver.resolvePaneId(markerPane) : null;
+
+      if (mine && theirs) {
+        // Both spellings resolved: identity is the answer, and a spelling mismatch is no longer one.
+        if (mine === theirs) {
+          samePane = true;
+          reasons.push(
+            markerPane === ownPane
+              ? `the marker names THIS process's own pane (${ownPane})`
+              : `the marker names THIS process's own pane — '${markerPane}' and '${ownPane}' both resolve to ${mine}`,
+          );
+        }
+      } else if (markerPane === ownPane) {
+        // ⛔ THE FALLBACK, AND IT IS DELIBERATELY THE NARROW ONE. When herdr cannot be asked — a tmux
+        // seat, no herdr binary, a pane that no longer answers — the only thing still knowable is
+        // whether the two spellings are literally equal, which is exactly the pre-fix behaviour. It
+        // is kept so this change cannot REMOVE a reclaim that used to work.
+        //
+        // ⛔⛆ AND IT NEVER WIDENS: "could not ask" must not silently become "matches". Unequal
+        // spellings that could not be resolved stay UNMATCHED — the seat is refused and has to be
+        // looked at, which is the outcome this row exists to make rare, not the outcome it exists to
+        // hide. A fallback that guessed `true` here would convert a diagnosable refusal into a seat
+        // silently claiming a pane that may belong to someone else.
+        samePane = true;
+        reasons.push(
+          canAsk
+            ? `the marker names THIS process's own pane (${ownPane}) — spellings are equal; herdr could not resolve either to a pane id, so identity was NOT confirmed`
+            : `the marker names THIS process's own pane (${ownPane})`,
+        );
+      } else {
+        // ⛔ STATED RATHER THAN SILENT, AND IT DISTINGUISHES THE TWO WAYS OF NOT KNOWING. A refusal
+        // whose reason is "I could not ask" is diagnosable in one read; one that prints nothing is the
+        // 26-hour kind. The first version of this branch was `else if (canAsk)`, which left the
+        // no-resolver case saying NOTHING — the same invisible-fallback shape the row is about, one
+        // level down, and the tests caught it.
+        const why = !canAsk
+          ? marker.transport === HERDR
+            ? "no herdr transport is wired in this process (initTransportFromConfig has not run), so no pane id could be asked for"
+            : `the ${marker.transport} transport has no pane-identity resolver, so only the spellings could be compared`
+          : `herdr could not resolve ${mine ? `'${markerPane}'` : theirs ? `'${ownPane}'` : "either spelling"} to a pane id`;
+        reasons.push(
+          `the marker names pane '${markerPane}' and this process is in '${ownPane}'; ${why}, so they are NOT treated as the same pane`,
+        );
+      }
     }
   }