agent-coord-mcp 0.26.36 → 0.26.39

package/src/server.ts

@@ -15,10 +15,12 @@ import { rotateSchema, rotateTool, rotateReconcileSchema, rotateReconcileTool }
 import { subscribeSchema, subscribeTool, unsubscribeSchema, unsubscribeTool, listSubscriptionsSchema, listSubscriptionsTool } from "./tools/events.js";
 import { scanRecordEventsSchema, scanRecordEventsTool } from "./tools/record-events.js";
 import { capabilitiesSchema, capabilitiesTool } from "./capabilities.js";
+import { type AuthFault, logText, responseText, detailInResponse } from "./auth-faults.js";
 import {
   ensureDirs,
   getTokenMap,
   agentForBearer,
+  retiredBearerFor,
   tokenMapCensusLine,
   TOKENS_FILE,
   reloadTokenMapSync,
@@ -767,7 +769,7 @@ function buildServer(initialBound?: string, opts: { trackSession?: boolean } = {
 
   addTool(
     "subscribe",
-    "Register for a record event: `task` (a phase checkbox newly ticked), `phase` (the last open box in a phase ticked), `item` (a queue item closed), or `pr` (a PR recorded in DONE.md). Events are DERIVED from the record and refused if the ref is not in it, so the stream can never claim something the authoritative markdown does not \u2014 but the TRIGGER is the record's COMMITTED CHANGE (`scan_record_events`), not any one verb, so a hand-edited DONE.md fires exactly like `land` does. Every offered kind has an emitter: the wire enum is generated from the emitter registry, so an unsatisfiable subscription cannot be registered. Re-subscribing returns the existing registration rather than a duplicate.",
+    "Register for a record event: `task` (a phase checkbox newly ticked), `phase` (the last open box in a phase ticked), `item` (a queue item closed), or `pr` (a PR recorded in DONE.md). Events are DERIVED from the record and refused if the ref is not in it, so the stream can never claim something the authoritative markdown does not \u2014 but the TRIGGER is the record's COMMITTED CHANGE (`scan_record_events`), not any one verb, so a hand-edited DONE.md fires exactly like `land` does. Every offered kind has an emitter: the wire enum is generated from the emitter registry, so an unsatisfiable subscription cannot be registered. Re-subscribing returns the existing registration rather than a duplicate. SCOPE picks how widely you are asking and is an explicit field rather than a magic target: `exact` (the default, and what every subscription stored before this field meant) matches one target; `kind` matches every event of the kind and REFUSES a target, because a target that was accepted and ignored would read narrower than it behaves; `prefix` matches targets starting with yours — which is how you watch a class whose ids do not exist yet, e.g. `davidbalzan/groundwork-kit#` for one repo's PRs. A prefix is over whatever `target` holds FOR THAT KIND (`pr` the full ref, `item` the queue id, `task` the KEY rather than the ticked line, `phase` the phase), and an EMPTY prefix is refused because it would match everything — that is the wildcard this field exists to avoid spelling in-band; ask for `kind` and say so.",
     subscribeSchema,
     gate("agentId", subscribeTool as (a: Record<string, unknown>) => Promise<unknown>),
   );
@@ -854,6 +856,11 @@ function loadTokenMap(initial: boolean): void {
   }
 }
 
+/** The coord dir, for the bind-time log line that tells an operator where refusals are recorded. */
+function coordRootForLog(): string {
+  return process.env.AGENT_COORD_DIR ?? `${process.env.HOME ?? "~"}/agent-coord`;
+}
+
 async function main() {
   ensureDirs();
   loadTokenMap(true);
@@ -1117,8 +1124,12 @@ async function startHttp(port: number): Promise<void> {
   // Reverse-lookup: extract bearer from header, map → bound agent. Returns
   // undefined if no map is configured (advisory mode); throws-like return of
   // null if the bearer doesn't match any known agent (caller responds 401).
-  function resolveBoundAgent(authHeader: string | undefined): { ok: boolean; agent?: string } {
-    if (!authHeader || !authHeader.startsWith("Bearer ")) return { ok: false };
+  function resolveBoundAgent(authHeader: string | undefined): { ok: boolean; agent?: string; fault?: AuthFault } {
+    // ⟨q-a441f1e1⟩ The refusal now carries WHICH fault it was. The caller is told only about the
+    // SHAPE of its request; everything about a credential's validity is uniform to the caller and
+    // detailed in the daemon log — see src/auth-faults.ts for why that split is where it is.
+    if (!authHeader) return { ok: false, fault: { kind: "no-header" } };
+    if (!authHeader.startsWith("Bearer ")) return { ok: false, fault: { kind: "not-bearer" } };
     const bearer = authHeader.slice("Bearer ".length);
     // ⟨q-54adf191⟩ Pick up a tokens.json that changed while this daemon ran. Rate-limited, so the
     // steady state is one stat; the file is read only when its stamp moved. Every outcome that is
@@ -1143,10 +1154,16 @@ async function startHttp(port: number): Promise<void> {
       // actually connects gets a tail, so a 20-agent map does not spawn 20 timers for seats that
       // may not exist. Idempotent — steady state is one Map lookup per request.
       if (agent) startTailOnBind(agent);
-      return agent ? { ok: true, agent } : { ok: false };
+      if (agent) return { ok: true, agent };
+      if (bearer === "") return { ok: false, fault: { kind: "empty-bearer" } };
+      // Retired is asked only AFTER the forced re-read above: a bearer minted seconds ago must not
+      // be reported as retired because this process had not read the file yet.
+      const retired = retiredBearerFor(bearer);
+      return { ok: false, fault: retired ? { kind: "retired-bearer", retired } : { kind: "unknown-bearer" } };
     }
     // Advisory mode: only check the shared bearer matches.
-    return sharedExpected && authHeader === sharedExpected ? { ok: true } : { ok: false };
+    if (sharedExpected && authHeader === sharedExpected) return { ok: true };
+    return { ok: false, fault: { kind: "advisory-mismatch" } };
   }
 
   // ⛔ ONE HANDLER, N SERVERS. Node binds a single address per `http.Server`, so a list of
@@ -1171,8 +1188,13 @@ async function startHttp(port: number): Promise<void> {
       // observe traffic; TLS termination is the answer to that.
       const resolved = resolveBoundAgent(req.headers.authorization);
       if (!resolved.ok) {
+        // ⟨q-a441f1e1⟩ The LOG is where an operator diagnosing "my seat stopped working" looks, and
+        // it distinguishes every fault. The RESPONSE names only what the caller already knows about
+        // its own request. Neither ever contains any part of a bearer.
+        const fault = resolved.fault ?? { kind: "unknown-bearer" as const };
+        console.error(`[agent-coord-mcp] ${logText(fault)}`);
         res.writeHead(401, { "Content-Type": "text/plain", "WWW-Authenticate": "Bearer" });
-        res.end("unauthorized\n");
+        res.end(`${responseText(fault)}\n`);
         return;
       }
 
@@ -1217,6 +1239,25 @@ async function startHttp(port: number): Promise<void> {
   {
     const startupCensus = tokenMapCensusLine();
     if (startupCensus) console.error(startupCensus);
+    // ⛔ ⟨q-a441f1e1⟩ A BUS RUNNING WITH THE ORACLE ON SAYS SO, AT BIND. qa: the switch existed and
+    // NOTHING announced it — no startup line, no warning — so a daemon could distinguish validity
+    // faults to unauthenticated callers while neither its log nor its capabilities mentioned it.
+    // An operator must not have to read the environment of a running process to learn this.
+    // ⭐ ⟨q-a441f1e1⟩ WHERE THE WITHHELD REASONS GO, stated at bind so an operator has the exact
+    // destination without it ever appearing in a 401 body. The response points at "this bus's daemon
+    // log" by role; this line is what turns that role into a path for the person entitled to it.
+    console.error(
+      `[agent-coord-mcp] 401 reasons (unknown / retired / advisory-mismatch bearers) are written HERE, to this ` +
+        `process's stderr — pid ${process.pid}, agent-coord dir ${coordRootForLog()}. A refused caller is told to ` +
+        `look here and is told nothing else.`,
+    );
+    if (detailInResponse()) {
+      console.error(
+        `[agent-coord-mcp] ⛔ AGENT_COORD_401_DETAIL=response — this bus tells an UNAUTHENTICATED caller ` +
+          `whether a bearer was never minted, or was genuine and retired, and when. That confirms a real ` +
+          `credential to whoever just failed to authenticate. Unset it to keep the detail in this log only.`,
+      );
+    }
   }
   await Promise.all(
     bindAddrs.map(

package/src/store.ts

@@ -392,8 +392,30 @@ export type TokenMapRefresh = {
   count: number | null;
   /** Present only when the reload was REFUSED; the previous map still serves. */
   refused?: string;
+  /**
+   * ⟨q-a441f1e1⟩ Bearers that were in the map before this reload and are not in it after — the only
+   * moment the daemon can ever observe a retirement, because nothing on disk records one.
+   * Hashes, never secrets. Empty unless `changed` is true.
+   */
+  retired?: RetiredHash[];
 };
 
+/** A bearer hash that left the map, with the agent it belonged to. ⛔ A HASH, NEVER A BEARER. */
+export type RetiredHash = { hash: string; agentId: string };
+
+/**
+ * ⟨q-a441f1e1⟩ Which entries LEFT the map. Pure, and separate from the reload decision so it can be
+ * exercised on posed maps: a rotation (`coord-token add` on an existing agent) and a revoke
+ * (`coord-token revoke`) both present here as a hash that is gone, and they are told apart by
+ * whether the agent still holds some other key afterwards.
+ */
+export function retiredSince(before: Map<string, string> | null, after: Map<string, string> | null): RetiredHash[] {
+  if (!before || !after) return [];
+  const out: RetiredHash[] = [];
+  for (const [hash, agentId] of before) if (!after.has(hash)) out.push({ hash, agentId });
+  return out;
+}
+
 // The file identity we compare against: mtime, size AND inode.
 //
 // ⛔ THE INODE IS LOAD-BEARING, NOT BELT-AND-BRACES. `coord-token` rotates by writing a temp file and
@@ -463,7 +485,12 @@ export function decideTokenMapRefresh(
     }
     return {
       next: { map: next, stamp, checkedAt: now },
-      result: { changed: true, reason: state.stamp === null ? "appeared" : "changed", count: next.size },
+      result: {
+        changed: true,
+        reason: state.stamp === null ? "appeared" : "changed",
+        count: next.size,
+        retired: retiredSince(state.map, next),
+      },
     };
   } catch (e) {
     // The stamp is deliberately NOT advanced: a half-written file that is fixed in place, with no
@@ -472,6 +499,58 @@ export function decideTokenMapRefresh(
   }
 }
 
+/**
+ * ⟨q-a441f1e1⟩ — WHAT THIS PROCESS WATCHED LEAVE THE TOKEN MAP. Hash → who held it and when it went.
+ *
+ * ⛔ IN MEMORY, DELIBERATELY, AND IT FORGETS ON RESTART. Nothing on disk records a superseded token:
+ * `coord-token add` overwrites an agent's entry and `revoke` deletes it, so after either the old
+ * bearer is simply absent — byte-for-byte identical to one that never existed. The ONLY moment the
+ * difference is observable is the reload that removes it, which this process is already doing.
+ * Persisting it would mean a new file or a schema change (⟨q-4b9cdeab⟩'s `previous` is documented in
+ * a comment and written by NOTHING), and release A writes neither form of token. So:
+ *   · a bearer retired while this daemon was RUNNING is reported as retired;
+ *   · a bearer retired while it was DOWN reads as unknown, and that is the honest answer — this
+ *     process never saw it valid. A test asserts that limit rather than only the happy path.
+ * Hashes only: a retirement record is never a place a secret appears.
+ */
+const RETIRED_MAX = 512;
+const retiredBearers = new Map<string, RetiredBearerRecord>();
+export type RetiredBearerRecord = { agentId: string; at: number; cause: "replaced" | "revoked" };
+
+/** Record what a reload removed. `cause` is derived, not guessed: see `retirementCause`. */
+export function noteRetired(entries: RetiredHash[], after: Map<string, string> | null, now = Date.now()): void {
+  for (const { hash, agentId } of entries) {
+    retiredBearers.set(hash, { agentId, at: now, cause: retirementCause(agentId, after) });
+    // Bounded so a long-lived daemon rotating often cannot grow this without limit. Insertion order
+    // is iteration order for a Map, so the oldest record is the one that goes.
+    if (retiredBearers.size > RETIRED_MAX) {
+      const oldest = retiredBearers.keys().next();
+      if (!oldest.done) retiredBearers.delete(oldest.value);
+    }
+  }
+}
+
+/**
+ * Replaced or revoked? The agent still holding a key after the reload was ROTATED; an agent with no
+ * key left was REVOKED. Derived from the map itself rather than from which command an operator ran,
+ * because the daemon never sees the command.
+ */
+export function retirementCause(agentId: string, after: Map<string, string> | null): "replaced" | "revoked" {
+  if (!after) return "revoked";
+  for (const held of after.values()) if (held === agentId) return "replaced";
+  return "revoked";
+}
+
+/** What this process knows about a presented bearer that is no longer live, or undefined. */
+export function retiredBearerFor(bearer: string): RetiredBearerRecord | undefined {
+  return retiredBearers.get(bearerHash(bearer));
+}
+
+/** Test seam only: forget every retirement, so a case can pose an empty process memory. */
+export function clearRetiredBearers(): void {
+  retiredBearers.clear();
+}
+
 export function refreshTokenMapIfChanged(opts: { force?: boolean; now?: number } = {}): TokenMapRefresh {
   if (!tokenMapInitialized) getTokenMap();
   const { next, result } = decideTokenMapRefresh(
@@ -479,6 +558,8 @@ export function refreshTokenMapIfChanged(opts: { force?: boolean; now?: number }
     { stamp: stampOf, read: readTokenMapSync },
     opts,
   );
+  // Before the cache moves: everything the old map held and the new one does not is retired.
+  if (result.retired?.length) noteRetired(result.retired, next.map, opts.now);
   tokenMapCache = next.map;
   tokenMapStamp = next.stamp;
   tokenMapCheckedAt = next.checkedAt;
@@ -729,6 +810,70 @@ function sanitize(id: string): string {
   return id.replace(/[^a-zA-Z0-9._-]/g, "_");
 }
 
+/* ── ⟨q-524305dd⟩ ONE DELIVERER PER (SEAT, SOURCE) AT A TIME, ACROSS PROCESSES ─────────────────────
+   Two paths type a room message into a herdr pane: the SENDER's server at send time (herdr-delivery)
+   and the RECIPIENT's own tail (herdr-tail). Each read the push cursor, typed, waited seconds to
+   verify the screen, and only then advanced it; the other read the same not-yet-advanced cursor in
+   that window and typed the message again. Measured 2026-09-24: 6 of 39 room messages reached one
+   seat's pane twice, 2.7–3.5s apart. The only guard was a closure-local `inFlight` flag — per
+   PROCESS, against a race between processes.
+   So read → type → verify → advance runs under a lock BOTH paths can see: a directory lock
+   (proper-lockfile, the same one appendJsonl uses) per seat and source.
+   ⛔ A holder that DIES must not deafen the seat. The lock's mtime is refreshed while its owner's
+   event loop runs, and it is STALE after DELIVERY_LOCK_STALE_MS without a refresh, so a killed sender
+   costs a bounded stall, never a permanent one. It must outlast the slowest push: herdr's verify
+   sleeps by spinning, which blocks the refresh for the push's whole duration.
+   ⛔ A compromised lock is LOGGED, never thrown: the library's default throws asynchronously, which
+   would take the bus server down with it. */
+const envMs = (name: string, fallback: number, min: number) => { const n = Number(process.env[name]); return Number.isFinite(n) && n >= min ? Math.floor(n) : fallback; };
+export const DELIVERY_LOCK_STALE_MS = envMs("AGENT_COORD_DELIVERY_LOCK_STALE_MS", 60_000, 2_000);
+export const DELIVERY_LOCK_WAIT_MS = envMs("AGENT_COORD_DELIVERY_LOCK_WAIT_MS", 30_000, 0);
+export const DELIVERY_LOCK_DIR = path.join(ROOT, "delivery-locks");
+export const deliveryLockPath = (agentId: string, sourceKey: string) => path.join(DELIVERY_LOCK_DIR, `${sanitize(agentId)}--${sanitize(sourceKey)}`);
+export type DeliveryLockOutcome<T> = { ran: true; value: T } | { ran: false; why: string };
+
+/**
+ * Run `fn` as the only deliverer to `agentId`'s `sourceKey` ("dm" or "room:<chan>") on this bus.
+ * `wait: false` (a tail tick) answers `ran: false` at once when another deliverer holds it — the next
+ * tick re-reads the cursor. `wait: true` (the send-time push) waits up to DELIVERY_LOCK_WAIT_MS rather
+ * than skipping, because the seat may have NO tail (⟨q-cdb5b007⟩) and a skipped send-time push would
+ * then be a silent drop. The lock is released on every path out of `fn`, including a throw.
+ */
+export async function withDeliveryLock<T>(
+  agentId: string,
+  sourceKey: string,
+  fn: () => Promise<T>,
+  opts: { wait: boolean; log?: (line: string) => void },
+): Promise<DeliveryLockOutcome<T>> {
+  const target = deliveryLockPath(agentId, sourceKey);
+  // A compromise or a failed release is ALWAYS logged — to the caller's sink, or stderr when none is given.
+  // (Not an optional call: a lock event that is silently dropped is the invisible failure this lock exists to end.)
+  const log = opts.log ?? ((line: string) => console.error(line));
+  mkdirSync(DELIVERY_LOCK_DIR, { recursive: true });
+  const deadline = Date.now() + (opts.wait ? DELIVERY_LOCK_WAIT_MS : 0);
+  let release: () => Promise<void>;
+  for (;;) {
+    try {
+      release = await lockfile.lock(target, {
+        realpath: false,
+        stale: DELIVERY_LOCK_STALE_MS,
+        retries: 0,
+        onCompromised: (e: Error) => log(`[delivery-lock] ${sourceKey} for ${agentId} was COMPROMISED (${e.message}) — another deliverer may have taken it over; logged, not thrown`),
+      });
+      break;
+    } catch (e) {
+      if ((e as NodeJS.ErrnoException).code !== "ELOCKED") return { ran: false, why: `delivery lock unavailable: ${(e as Error).message}` };
+      if (Date.now() >= deadline) return { ran: false, why: `another deliverer holds ${sourceKey} for ${agentId}` };
+      await new Promise((r) => setTimeout(r, 40 + Math.floor(Math.random() * 60)));
+    }
+  }
+  try {
+    return { ran: true, value: await fn() };
+  } finally {
+    try { await release(); } catch (e) { log(`[delivery-lock] release of ${sourceKey} for ${agentId} failed: ${(e as Error).message}`); }
+  }
+}
+
 export async function rewriteJsonl<T>(
   file: string,
   filter: (entry: T) => boolean

package/src/test-count-key.ts

@@ -0,0 +1,21 @@
+// ⟨q-f2cf9e0f⟩ — HOW A PASSING TEST IS ATTRIBUTED TO A FILE, in src/ so a probe can CALL it.
+//
+// `check-test-count` compares per-file pass counts against a committed record, and both the record's
+// keys and the glob's selections are paths relative to the package. The attribution key has to be
+// the SAME thing or the comparison is between two different namespaces.
+//
+// ⛔ IT WAS `test/${basename(file)}`, WHICH FLATTENS. Every test file sat directly in `test/`, so the
+// flattened key and the real one were identical and the defect was invisible — until a suite moved to
+// `test/live/`, whose passes then landed on the phantom key `test/<name>` while the real entry read
+// zero. A per-file guard that mis-keys is worse than no guard: it reports drift that is not there and
+// hides drift that is.
+//
+// Lives in src/ rather than beside the script for the reason measured in ⟨q-0c5476ec⟩: a probe in
+// dist/ importing out of scripts/ breaks any install that ships dist without scripts.
+import path from "node:path";
+
+/** The record/glob key for a test file: its path relative to the package, POSIX-separated. */
+export function testCountKey(pkgRoot: string, file: string | undefined): string {
+  if (!file) return "(unattributed)";
+  return path.relative(pkgRoot, file).split(path.sep).join("/");
+}

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