agent-coord-mcp 0.26.34 → 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
@@ -767,6 +912,88 @@ export function archiveInboxFile(agentId: string): string {
   return path.join(ARCHIVE_INBOX_DIR, `${sanitize(agentId)}.jsonl`);
 }
 
+/**
+ * What one archive pass did to a stream, in BOTH units a cursor can be measured in.
+ *
+ * ⛔ `removed` IS A LINE COUNT. `rebaseBytes` IS THE ONLY CORRECT WAY TO MOVE A BYTE OFFSET.
+ * A read cursor counts entries; a push cursor (`<agent>.push.json`) is the byte just past the
+ * last line typed into the pane. `adjustCursors` once subtracted `removed` from both — a line
+ * count from a byte offset — so every compaction left each push cursor far past the new EOF,
+ * and `advancePushCursor`'s monotonic `Math.max` meant nothing brought it back: the seat went
+ * deaf until the room organically regrew past the stale value (⟨q-f44f17a7⟩, 2026-09-24).
+ */
+export type ArchiveResult = { kept: number; removed: number; archived: number; rebaseBytes: (offset: number) => number };
+
+/**
+ * The byte offset in the rewritten file that corresponds to `offset` in the original one: the
+ * bytes of every KEPT line that ended at or before it. Exact, not a subtraction — compaction keeps
+ * fresh decisions from before its boundary, so removed and kept lines interleave. An offset inside
+ * a line maps to that line's start (it is re-offered, never skipped); one past the old EOF — a
+ * cursor already corrupted by the old rule — maps to the new EOF.
+ */
+function byteRebase(keptOldEnd: number[], keptNewEnd: number[], oldSize: number): (offset: number) => number {
+  return (offset) => {
+    const x = Math.min(Math.max(0, offset), oldSize);
+    let lo = 0;
+    let hi = keptOldEnd.length; // first index whose old end is PAST x
+    while (lo < hi) {
+      const mid = (lo + hi) >> 1;
+      if (keptOldEnd[mid]! <= x) lo = mid + 1;
+      else hi = mid;
+    }
+    return lo === 0 ? 0 : keptNewEnd[lo - 1]!;
+  };
+}
+
+/**
+ * The pure half of an archive pass: which lines stay, which go, and the byte map between the old file
+ * and the rewritten one. No I/O, so the SAME rule is what `archiveJsonl` writes and what the
+ * `push-cursor-rebased-in-bytes` capability probe asks — not a copy of it.
+ */
+export function planArchive<T>(raw: string, filter: (entry: T) => boolean): { keep: string[]; archive: string[] } & Omit<ArchiveResult, "archived"> {
+  let kept = 0;
+  let removed = 0;
+  const keep: string[] = [];
+  const archive: string[] = [];
+  // Where each kept line ENDED in the old file and ends in the new one.
+  const keptOldEnd: number[] = [];
+  const keptNewEnd: number[] = [];
+  let oldPos = 0;
+  let newPos = 0;
+  const segments = raw.split("\n");
+  for (let i = 0; i < segments.length; i++) {
+    const line = segments[i]!;
+    oldPos += Buffer.byteLength(line, "utf8") + (i < segments.length - 1 ? 1 : 0);
+    if (!line.trim()) continue;
+    let keepIt = false;
+    try {
+      keepIt = filter(JSON.parse(line) as T);
+    } catch {
+      keepIt = false; // malformed lines are archived verbatim rather than parsed
+    }
+    if (keepIt) {
+      keep.push(line);
+      kept++;
+      newPos += Buffer.byteLength(line, "utf8") + 1;
+      keptOldEnd.push(oldPos);
+      keptNewEnd.push(newPos);
+    } else {
+      archive.push(line);
+      removed++;
+    }
+  }
+  return { keep, archive, kept, removed, rebaseBytes: byteRebase(keptOldEnd, keptNewEnd, oldPos) };
+}
+
+/**
+ * Where a cursor lands after a rewrite, in ITS OWN unit: a read cursor counts entries (shifted down by
+ * the entries removed, clamped at 0), a push cursor is a byte offset (mapped exactly). The one place
+ * the unit is chosen — by the cursor's kind, never by a caller.
+ */
+export function moveCursorOffset(kind: "read" | "push", offset: number, rw: Pick<ArchiveResult, "removed" | "rebaseBytes">): number {
+  return kind === "push" ? rw.rebaseBytes(offset) : Math.max(0, offset - rw.removed);
+}
+
 // Like rewriteJsonl, but entries failing the filter are appended to
 // archiveFile instead of discarded. The archive append happens under the
 // source-file lock and BEFORE the rewrite, so a crash mid-operation can at
@@ -776,36 +1003,16 @@ export async function archiveJsonl<T>(
   file: string,
   archiveFile: string,
   filter: (entry: T) => boolean
-): Promise<{ kept: number; removed: number; archived: number }> {
-  if (!existsSync(file)) return { kept: 0, removed: 0, archived: 0 };
+): Promise<ArchiveResult> {
+  if (!existsSync(file)) return { kept: 0, removed: 0, archived: 0, rebaseBytes: () => 0 };
   return withLock(file, async () => {
-    const raw = await fs.readFile(file, "utf8");
-    let kept = 0;
-    let removed = 0;
-    const keep: string[] = [];
-    const archive: string[] = [];
-    for (const line of raw.split("\n")) {
-      if (!line.trim()) continue;
-      try {
-        const entry = JSON.parse(line) as T;
-        if (filter(entry)) {
-          keep.push(line);
-          kept++;
-        } else {
-          archive.push(line);
-          removed++;
-        }
-      } catch {
-        archive.push(line);
-        removed++;
-      }
-    }
+    const { keep, archive, kept, removed, rebaseBytes } = planArchive(await fs.readFile(file, "utf8"), filter);
     if (archive.length) {
       await fs.mkdir(path.dirname(archiveFile), { recursive: true });
       await fs.appendFile(archiveFile, archive.join("\n") + "\n", "utf8");
     }
     await fs.writeFile(file, keep.length ? keep.join("\n") + "\n" : "", "utf8");
-    return { kept, removed, archived: archive.length };
+    return { kept, removed, archived: archive.length, rebaseBytes };
   });
 }
 

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/admin.ts

@@ -16,6 +16,7 @@ import {
   listCursorFiles,
   listInboxFiles,
   listReceiptFiles,
+  moveCursorOffset,
   normalizeRoom,
   pruneHistory,
   readJson,
@@ -23,6 +24,7 @@ import {
   rewriteJsonl,
   roomFile,
   updateJson,
+  type ArchiveResult,
   type RoomRegistry,
 } from "../store.js";
 import {
@@ -60,48 +62,59 @@ function keepEntry(
   return isDecision(e) ? e.ts > decisionCutoff : e.ts > cutoff;
 }
 
-// Shift every agent's cursor offsets down by the number of entries removed
-// ahead of them (append-only + oldest-first removal ⇒ plain subtraction,
-// clamped at 0). Shared by prune and live compaction — without this, an
-// offset past the new file length makes read_messages return [] forever.
-export async function adjustCursors(removals: {
-  roomRemovedByChan?: Record<string, number>;
-  statusRemoved?: number;
-  perAgentInboxRemoved?: Record<string, number>;
+/**
+ * Carry every agent's cursors across a rewrite of the streams they index. Shared by prune and
+ * live compaction — without this, an offset past the new file length makes read_messages return
+ * [] forever.
+ *
+ * ⛔ EACH CURSOR IS MOVED IN ITS OWN UNIT (⟨q-f44f17a7⟩). A READ cursor (`<agent>.json`) counts
+ * entries: it is shifted down by the entries removed (clamped at 0; at-least-once if kept
+ * decisions sat behind it). A PUSH cursor (`<agent>.push.json`) is a BYTE offset: it is mapped
+ * through the archive pass's `rebaseBytes`, exactly. This took three visits to one function:
+ * ⟨q-40449919⟩ fixed the push FILENAME and left the unit wrong, and ⟨q-c36a078f⟩ fixed the same
+ * confusion in push-cursor seeding. So the caller cannot pass a bare count any more — it passes the
+ * whole `ArchiveResult`, which carries both units, and the choice between them is made HERE by the
+ * cursor's own kind rather than trusted to every call site.
+ */
+export type StreamRewrite = Pick<ArchiveResult, "removed" | "rebaseBytes">;
+export async function adjustCursors(rewrites: {
+  roomByChan?: Record<string, StreamRewrite>;
+  status?: StreamRewrite;
+  inboxByAgent?: Record<string, StreamRewrite>;
 }): Promise<string[]> {
-  const roomRemovedByChan = removals.roomRemovedByChan ?? {};
-  const statusRemoved = removals.statusRemoved ?? 0;
-  const perAgentInboxRemoved = removals.perAgentInboxRemoved ?? {};
+  const roomByChan = rewrites.roomByChan ?? {};
+  const inboxByAgent = rewrites.inboxByAgent ?? {};
   const cursorsAdjusted: string[] = [];
   for (const cname of await listCursorFiles()) {
     // q-40449919: this was `cname.replace(/\.json$/, "")`, which strips only
     // the outer extension. A push cursor's `<agent>.push.json` then keyed
-    // `perAgentInboxRemoved` lookups below on `<agent>.push` — a key that
+    // `inboxByAgent` lookups below on `<agent>.push` — a key that
     // never matches — so a push cursor's inboxOffset was silently never
-    // decremented after a prune shrank the inbox, drifting it toward a
-    // false past-EOF the next time doctor ran.
-    const { id } = agentIdFromCursorFilename(cname);
+    // adjusted after a prune shrank the inbox.
+    const { id, kind } = agentIdFromCursorFilename(cname);
+    const move = (offset: number, rw: StreamRewrite) => moveCursorOffset(kind, offset, rw);
     const cursorPath = path.join(CURSOR_DIR, cname);
     let touched = false;
     await updateJson<Cursor>(cursorPath, {}, (current) => {
-      for (const [chan, removed] of Object.entries(roomRemovedByChan)) {
+      for (const [chan, rw] of Object.entries(roomByChan)) {
+        if (rw.removed <= 0) continue;
         if (chan === DEFAULT_ROOM) {
           if (current.roomOffset !== undefined) {
-            current.roomOffset = Math.max(0, current.roomOffset - removed);
+            current.roomOffset = move(current.roomOffset, rw);
             touched = true;
           }
         } else if (current.roomOffsets?.[chan] !== undefined) {
-          current.roomOffsets[chan] = Math.max(0, current.roomOffsets[chan] - removed);
+          current.roomOffsets[chan] = move(current.roomOffsets[chan], rw);
           touched = true;
         }
       }
-      if (current.statusOffset !== undefined && statusRemoved > 0) {
-        current.statusOffset = Math.max(0, current.statusOffset - statusRemoved);
+      if (current.statusOffset !== undefined && rewrites.status && rewrites.status.removed > 0) {
+        current.statusOffset = move(current.statusOffset, rewrites.status);
         touched = true;
       }
-      const myInboxRemoved = perAgentInboxRemoved[id] ?? 0;
-      if (current.inboxOffset !== undefined && myInboxRemoved > 0) {
-        current.inboxOffset = Math.max(0, current.inboxOffset - myInboxRemoved);
+      const myInbox = inboxByAgent[id];
+      if (current.inboxOffset !== undefined && myInbox && myInbox.removed > 0) {
+        current.inboxOffset = move(current.inboxOffset, myInbox);
         touched = true;
       }
       return current;
@@ -232,26 +245,26 @@ export async function pruneTool(args: {
   // Per-channel removed counts so we can shift the matching offset in each
   // cursor (default channel → roomOffset, others → roomOffsets[chan]).
   // Aged-out entries are archived to archive/rooms/<chan>.jsonl, never deleted.
-  const roomRemovedByChan: Record<string, number> = {};
+  const roomByChan: Record<string, StreamRewrite> = {};
   let roomRemovedTotal = 0;
   if (targets.has("rooms")) {
     for (const chan of channels) {
       const r = await archiveJsonl<Message>(roomFile(chan), archiveRoomFile(chan), keep);
       if (r.removed > 0) {
-        roomRemovedByChan[chan] = r.removed;
+        roomByChan[chan] = r;
         roomRemovedTotal += r.removed;
       }
     }
   }
   const statusResult = targets.has("status")
     ? await archiveJsonl<StatusEntry>(STATUS_FILE, ARCHIVE_STATUS_FILE, (e) => e.ts > cutoff)
-    : { kept: 0, removed: 0, archived: 0 };
+    : { kept: 0, removed: 0, archived: 0, rebaseBytes: () => 0 };
 
   let inboxRemoved = 0;
   const deletedOrphans: string[] = [];
-  // perAgentInboxRemoved: how many entries were stripped from each *kept* agent's
-  // inbox, so we can shift only that agent's inboxOffset cursor below.
-  const perAgentInboxRemoved: Record<string, number> = {};
+  // inboxByAgent: what was stripped from each *kept* agent's inbox (in both
+  // units), so we can shift only that agent's inboxOffset cursors below.
+  const inboxByAgent: Record<string, StreamRewrite> = {};
   if (targets.has("inbox")) {
     for (const fname of await listInboxFiles()) {
       const id = fname.replace(/\.jsonl$/, "");
@@ -266,14 +279,14 @@ export async function pruneTool(args: {
       }
       const r = await archiveJsonl<Message>(filePath, archiveInboxFile(id), (e) => e.ts > cutoff);
       inboxRemoved += r.removed;
-      perAgentInboxRemoved[id] = r.removed;
+      inboxByAgent[id] = r;
     }
   }
 
   const cursorsAdjusted = await adjustCursors({
-    roomRemovedByChan,
-    statusRemoved: statusResult.removed,
-    perAgentInboxRemoved,
+    roomByChan,
+    status: statusResult,
+    inboxByAgent,
   });
 
   // Membership sweep: drop orphans (not in registry) and stale members (no