agent-coord-mcp 0.26.36 → 0.26.40

package/src/tools/away.ts

@@ -112,8 +112,26 @@ export function coverageAgeOf(coverage: { at: string }, now = Date.now()): { age
   const stale = ageMs > COVERAGE_STALE_MINUTES * 60_000;
   return { ageMs, stale, label: `measured ${fmtAge(ageMs)} ago${stale ? ` — STALE (older than ${COVERAGE_STALE_MINUTES}m; re-arm or run stall_check for a current reading)` : ""}` };
 }
-/** Met when nothing scored is unseen — an empty board (0 of 0) is idle, not blind, and needs no special case. */
-export const meetsCoverageThreshold = (c: { checked: number; measurable: number }): boolean => c.measurable >= c.checked;
+/*
+ * ⛔⛆ ⟨q-b0d4e45a⟩ THE DENOMINATOR IS THE IN-FLIGHT POPULATION, NOT THE SCORED SUBSET. This armed a
+ * fleet on `checked: 0, measurable: 0, blind: []` while its own population said `rows: 4, inFlight: 2`:
+ * both in-flight lanes carried a PROSE cell, so each one hit `deliberate` and `continue`d out of the
+ * scoring loop before `scored.push`, and `checked` counted only what survived that filter. `0 >= 0` armed.
+ *
+ * ⛔ SO THE GUARD INVERTED AT ITS OWN LIMIT: `2 of 5` REFUSED while `0 of 2` ARMED SILENTLY — the
+ * partially blind fleet was stopped and the totally blind one waved through. An EMPTY blind-list and a
+ * blind-list THAT WAS NEVER POPULATED are indistinguishable, and this read the second as the first.
+ *
+ * ⭐ `deliberate` STAYS a category — a deliberately unwatched lane is real. The bug was that it was
+ * subtracted from the POPULATION rather than reported within it: a classification is a REASON a lane is
+ * unscored, never an exemption from being counted.
+ *
+ * ⚠ `inFlight === 0` is the ONE case that still arms, and it is a different sentence: nothing is in
+ * flight, so there is nothing to see — idle, not blind. That distinction is why the old `checked > 0`
+ * reasoning existed; it was right about idle and wrong about what `checked` measured.
+ */
+export const meetsCoverageThreshold = (c: { measurable: number; inFlight: number }): boolean =>
+  c.inFlight === 0 ? true : c.measurable >= c.inFlight;
 
 /**
  * ⟨q-1c95f7d4⟩ Task 5.4 — WHAT THE EXTERNAL TICK CONTRIBUTES TO THE AWAY PRECONDITION.
@@ -139,8 +157,19 @@ export type AwayCoverage = {
   tick?: AwayTick;
   /** ⟨q-5d1c8e04⟩ — standing seats on the board: present, not scored, and therefore not blind. */
   roles?: number;
-  /** Lanes that declare no per-agent branch: out of the population by their own statement. */
+  /**
+   * ⛔ ⟨q-b0d4e45a⟩ THE IN-FLIGHT POPULATION — the denominator. `checked` is the SCORED SUBSET and is
+   * reported beside it, never as the divisor: a lane filtered out before scoring still has to be counted,
+   * or the reading congratulates itself for the rows it dropped.
+   */
+  inFlight: number;
+  /**
+   * Lanes in flight that declare no per-agent branch. COUNTED IN `inFlight`, unscored, and named with the
+   * offending cell — a reason, not an exemption ⟨q-b0d4e45a⟩.
+   */
   deliberate?: number;
+  /** The `deliberate` lanes themselves, so a refusal can name the ROW and the CELL rather than a count. */
+  deliberateRows?: { agentId: string; stream: string; cell: string }[];
   /** ⟨q-3d82f1a9⟩ — the board could not be read: rows present vs parsed, as stall_check stated it. */
   unreadable?: { rowsPresent: number; rowsParsed: number; why: string };
   at: string;
@@ -245,11 +274,20 @@ export const coordAwaySchema = {
   agentId: z.string().optional(),
 };
 
-async function measureCoverage(repo?: string): Promise<AwayCoverage | null> {
+/**
+ * ⛔ THE SEAM EXISTS TO FEED THE GUARD BELOW, NOT TO BYPASS IT ⟨q-b0d4e45a⟩. `checkStall` replaces only
+ * the CLOCK'S REPLY; every line of the arithmetic and every refusal still runs on it. A seam that stood
+ * in for `measureCoverage` itself could not test the missing-population guard, because the guard is the
+ * thing under test — so the injection point is deliberately UPSTREAM of it.
+ */
+export type StallReplyForCoverage = { ok?: boolean; checked?: number; measurable?: number; blind?: string[]; roles?: unknown[]; deliberate?: unknown[]; population?: { rows?: number; inFlight?: number }; tick?: unknown; boardParse?: unknown };
+async function measureCoverage(repo?: string, checkStall: (a: { repo: string }) => Promise<unknown> = stallCheckTool): Promise<AwayCoverage | null> {
   if (!repo) return null;
   try {
-    const r = (await stallCheckTool({ repo })) as unknown as {
-      ok?: boolean; checked?: number; measurable?: number; blind?: string[]; roles?: unknown[]; deliberate?: unknown[];
+    const r = (await checkStall({ repo })) as unknown as {
+      ok?: boolean; checked?: number; measurable?: number; blind?: string[]; roles?: unknown[];
+      deliberate?: { agentId?: string; stream?: string; cell?: string }[];
+      population?: { rows?: number; inFlight?: number };
       tick?: { seats?: unknown[]; readable?: number; states?: Record<string, number>; note?: string };
       boardParse?: { readable: boolean; rowsPresent: number; rowsParsed: number; why: string };
     };
@@ -258,21 +296,42 @@ async function measureCoverage(repo?: string): Promise<AwayCoverage | null> {
     // promise a watched fleet over a table nobody can read.
     if (r?.boardParse && !r.boardParse.readable) {
       return {
-        checked: 0, measurable: 0, blind: [], roles: 0, deliberate: 0,
+        checked: 0, measurable: 0, inFlight: 0, blind: [], roles: 0, deliberate: 0,
         unreadable: { rowsPresent: r.boardParse.rowsPresent, rowsParsed: r.boardParse.rowsParsed, why: r.boardParse.why },
         at: new Date().toISOString(),
       };
     }
     if (!r?.ok) return null;
+    // ⛔⛆ ⟨q-b0d4e45a⟩ A MISSING POPULATION IS NOT A POPULATION OF ZERO, and `?? 0` here would rebuild the
+    // defect one layer up: `inFlight: 0` is the one value that passes the threshold unconditionally. If the
+    // clock cannot state its own denominator the fleet is UNMEASURED, and `null` sends it to the
+    // "cannot measure" refusal.
+    // ⭐ MEASURED, by removing this line in the COMPILED dist (tsc refuses the mutation, so the matrix runs
+    // against dist — qa's technique) — and it is worth stating exactly, because the danger is NOT uniform:
+    //   • plain call            → refuses, but INCOHERENTLY: "covers 0 of undefined … (NaN short)"
+    //   • acknowledgeBlindFleet → ⛔ ARMS, recording `coverage.inFlight: undefined` and announcing
+    //                             "Stall coverage 0/undefined — ACKNOWLEDGED BLIND"
+    // ⚠ So the acknowledged path is the one that actually goes away on an unmeasured fleet, and an earlier
+    // draft of this comment said "would ARM" without that split. Both outcomes are wrong; only one ships a
+    // fleet unwatched. The test covers BOTH, including that the flag cannot buy past it.
+    const inFlight = r.population?.inFlight;
+    if (typeof inFlight !== "number") return null;
+    const deliberateRows = (r.deliberate ?? []).map((d) => ({
+      agentId: String(d?.agentId ?? "-"),
+      stream: String(d?.stream ?? "-"),
+      cell: String(d?.cell ?? "").trim(),
+    }));
     return {
       checked: r.checked ?? 0,
       measurable: r.measurable ?? 0,
+      inFlight,
       blind: r.blind ?? [],
       tick: r.tick
         ? { seats: r.tick.seats?.length ?? 0, readable: r.tick.readable ?? 0, states: (r.tick.states ?? {}) as Record<string, number>, note: r.tick.note ?? "" }
         : undefined,
       roles: r.roles?.length ?? 0,
-      deliberate: r.deliberate?.length ?? 0,
+      deliberate: deliberateRows.length,
+      deliberateRows,
       at: new Date().toISOString(),
     };
   } catch {
@@ -280,16 +339,23 @@ async function measureCoverage(repo?: string): Promise<AwayCoverage | null> {
   }
 }
 
-export async function coordAwayTool(args: {
-  project: string;
-  on?: boolean;
-  leadId?: string;
-  decisionLog?: string;
-  until?: string;
-  repo?: string;
-  acknowledgeBlindFleet?: boolean;
-  agentId?: string;
-}) {
+export async function coordAwayTool(
+  args: {
+    project: string;
+    on?: boolean;
+    leadId?: string;
+    decisionLog?: string;
+    until?: string;
+    repo?: string;
+    acknowledgeBlindFleet?: boolean;
+    agentId?: string;
+  },
+  /**
+   * ⚠ A SECOND PARAMETER RATHER THAN A FIELD ON `args`, so nothing here can reach the MCP tool schema:
+   * a caller on the bus cannot supply its own clock. Tests only.
+   */
+  deps: { checkStall?: (a: { repo: string }) => Promise<unknown> } = {},
+) {
   const state = readAway();
   const prior = state[args.project];
 
@@ -320,7 +386,10 @@ export async function coordAwayTool(args: {
       summary:
         `'${args.project}' is ARMED — '${prior.leadId}' leads since ${prior.at}` +
         `${prior.until ? ` until ${prior.until}` : ""}. ` +
-        `Coverage ${prior.coverage.measurable}/${prior.coverage.checked} lane(s) ${coverageAgeOf(prior.coverage).label}` +
+        // ⚠ A RECORD WRITTEN BEFORE ⟨q-b0d4e45a⟩ HAS NO POPULATION, and a query must not invent one.
+        // Printing `/${checked}` for it would quote the scored subset as the denominator — the very
+        // reading this row fixed — so an unrecorded population says so in words.
+        `Coverage ${prior.coverage.measurable}/${typeof prior.coverage.inFlight === "number" ? prior.coverage.inFlight : `?? (population not recorded at arm time; ${prior.coverage.checked} scored)`} lane(s) ${coverageAgeOf(prior.coverage).label}` +
         `${prior.coverage.roles ? ` · ${prior.coverage.roles} role(s) present, not scored` : ""}` +
         `${prior.blindAcknowledged ? " (ACKNOWLEDGED BLIND)" : ""}. ` +
         `Decisions logged to ${prior.decisionLog}.`,
@@ -347,7 +416,7 @@ export async function coordAwayTool(args: {
     }
 
     // THE PRECONDITION: what could the clock actually SEE?
-    const coverage = await measureCoverage(args.repo);
+    const coverage = await measureCoverage(args.repo, deps.checkStall);
     if (!coverage) {
       return {
         ok: false as const,
@@ -370,18 +439,29 @@ export async function coordAwayTool(args: {
           `Away mode promises a watched fleet; a board the clock cannot read is not a quiet fleet, it is an unwatched one. Fix the row and re-arm.`,
       };
     }
-    // `checked > 0` MATTERS: an empty board is an IDLE fleet, not a blind one.
-    // Without it, arming while nothing is in flight refuses with "the clock
-    // covers 0 of 0" — a refusal that reads as a fleet nobody can see when in
-    // fact there is nothing to see, and the only way past it would be to
-    // acknowledge a blindness that does not exist.
     // ⟨q-5a71fc3b⟩ — below the threshold, not only at zero: "2 of 5" refuses.
+    // ⛔⛆ ⟨q-b0d4e45a⟩ — AND "0 of 2" REFUSES THE SAME WAY. The denominator is the in-flight
+    // population, so a lane filtered out of `checked` before scoring cannot buy silence. An empty
+    // board still arms, because `inFlight === 0` is idle rather than blind — the one thing the old
+    // `checked > 0` reasoning got right, now expressed against the population instead of against
+    // the scored subset it was mistaken for.
     if (!meetsCoverageThreshold(coverage) && !args.acknowledgeBlindFleet) {
+      // ⭐ NAME THE ROW AND THE CELL, not a count. "1 deliberate" tells a reader nothing they can act
+      // on; the stream and the offending cell text tell them which line to fix — or that the lane is
+      // legitimately unscoreable because nothing has been pushed yet.
+      const unscored = coverage.deliberateRows ?? [];
+      const unscoredSentence = unscored.length
+        ? ` UNSCORED BUT COUNTED — ${unscored.length} in-flight lane(s) declare no branch ref, and each is counted in the ${coverage.inFlight}: ` +
+          unscored.map((d) => `${d.agentId} (${d.stream}) cell reads ${JSON.stringify(d.cell)}`).join(" · ") +
+          `. A cell like this is a REASON a lane is unscored, never an exemption from being counted: if the lane has genuinely pushed nothing there is no ref to write, and that is UNSCOREABLE-AND-COUNTED, not covered.`
+        : "";
       return {
         ok: false as const,
         error:
-          `REFUSING: the stall clock covers ${coverage.measurable} of ${coverage.checked} in-flight row(s); the threshold is that ${COVERAGE_THRESHOLD} ` +
-          `(${coverage.checked - coverage.measurable} short)${coverage.blind.length ? ` — blind on: ${coverage.blind.join(", ")}` : ""}. ` +
+          `REFUSING: the stall clock covers ${coverage.measurable} of ${coverage.inFlight} in-flight row(s) ` +
+          `(${coverage.checked} scored); the threshold is that ${COVERAGE_THRESHOLD} ` +
+          `(${coverage.inFlight - coverage.measurable} short)${coverage.blind.length ? ` — blind on: ${coverage.blind.join(", ")}` : ""}.` +
+          unscoredSentence + " " +
           `${coverage.measurable === 0 ? "It would RUN and see nothing. " : "The seats it cannot see are exactly the ones an absence leaves unattended. "}` +
           `"The clock ran" and "the fleet is observed" are different facts, and this verb must not treat the first as the second. ` +
           `The usual cause is a board 'Branch · Worktree' cell holding a PATH rather than a branch ref: a path resolves for ` +
@@ -417,7 +497,12 @@ export async function coordAwayTool(args: {
         `Decides: planning · priority · curation · roadmap · canon · releases under standing authorisation. ` +
         `Never: merges, gates, or takes a code lane. Parks for David: ${PARKED_CATEGORIES.join(" · ")}. ` +
         `Decisions logged to ${args.decisionLog}. ` +
-        `Stall coverage ${coverage.measurable}/${coverage.checked}${!meetsCoverageThreshold(coverage) ? ` — ACKNOWLEDGED BLIND${coverage.measurable === 0 ? ": the clock runs and sees nothing" : ""}${coverage.blind.length ? ` on: ${coverage.blind.join(", ")}` : ""}` : ""}.` +
+        // ⭐ ⟨q-b0d4e45a⟩ TWO DIFFERENT SENTENCES, AND ONLY ONE OF THEM IS REASSURING. An idle fleet says
+        // "0 in flight"; it must never render as "0/0 covered", which reads as a measured fleet and is
+        // exactly how a never-populated reading passed for a clean one.
+        (coverage.inFlight === 0
+          ? `Stall coverage: 0 in flight — nothing to watch, so nothing was measured (idle, not blind; ${coverage.checked} scored).`
+          : `Stall coverage ${coverage.measurable}/${coverage.inFlight}${!meetsCoverageThreshold(coverage) ? ` — ACKNOWLEDGED BLIND${coverage.measurable === 0 ? ": the clock runs and sees nothing" : ""}${coverage.blind.length ? ` on: ${coverage.blind.join(", ")}` : ""}` : ""}.`) +
         tickSentence(coverage.tick),
     };
   }

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;
 }