agent-coord-mcp 0.26.33 → 0.26.36

package/src/store.ts

@@ -153,10 +153,86 @@ export function ensureDirs(): void {
   }
 }
 
-// Synchronous, deliberate. The result feeds the server's bearer→agent
-// reverse-lookup map; we want startup to fail loudly on a malformed file
-// rather than silently degrade to advisory mode. Returns null if the file
-// is absent (operator hasn't configured binding yet).
+// ⟨q-4b9cdeab⟩ RELEASE A — THE READER ACCEPTS BOTH FORMS AND WRITES NEITHER.
+//
+// `tokens.json` holds every seat's bearer in the clear, so one readable file is the whole fleet's
+// identity. The fix is that the file stores a HASH while the seat's config keeps the secret. Because
+// 13 live HTTP seats depend on this file's shape, the migration is two-form first (David's ruling,
+// 2026-09-23, docs/notes/Q_4B9CDEAB_HASHED_TOKENS_PLAN.md): this release READS both forms and writes
+// NEITHER. No migration command, no hashed file written, no cutover. `coord-token` keeps minting
+// plaintext.
+//
+//   v1 (today):  { "alice": "tk_<secret>" }
+//   v2 (hashed): { "alice": { "alg": "sha256", "hash": "<hex>", "createdAt": "…", "previous": {…} } }
+//
+// The two are told apart by the VALUE TYPE, so an untouched file keeps working with no version field.
+//
+// ⭐ ONE LOOKUP PATH FOR BOTH FORMS: a v1 entry is HASHED AT LOAD, so the in-process map is always
+// hash → agentId and `agentForBearer` hashes whatever is presented. There is no second comparison to
+// drift, and no branch where a plaintext file authenticates differently from a hashed one.
+//
+// ⛔ AN ENTRY THIS BUILD CANNOT EVALUATE REFUSES THE WHOLE FILE, BY NAME. An unknown `alg` is never
+// ignored (which would silently drop a seat) and never treated as plaintext (which would compare a
+// bearer against a hash and lock that seat out while looking fine). Same for a missing or malformed
+// hash. The refusal names the AGENT and the ALG — never any part of a bearer, and never the hash.
+//
+// ⚠ `previous` (the rotation grace window) is NOT honoured in release A: it is written by nothing in
+// this release, so accepting it would be accepting a shape no tool here produces. A bearer that
+// matches only `previous` does not authenticate, and that is asserted rather than left implicit.
+//
+// Synchronous, deliberate: startup fails loudly on a malformed file rather than silently degrading
+// to advisory mode. Returns null if the file is absent (binding not configured).
+/** The hash algorithms this build can evaluate. An entry naming anything else refuses the file. */
+export const TOKEN_HASH_ALGS = Object.freeze(["sha256"] as const);
+const HEX64 = /^[0-9a-f]{64}$/;
+/**
+ * ⛔ sha256 OF THE EMPTY STRING. v1 refused an empty token STRUCTURALLY (`value.length === 0`); the
+ * hashed form has no such shape, because this hex is as well-formed as any other. It is the exact
+ * artefact of an ordinary shell slip during the hand migration this release exists for —
+ * `printf '%s' "$TOK" | shasum -a 256` with `$TOK` unset or mistyped writes precisely this — and an
+ * entry holding it authenticates an `Authorization: Bearer ` header with nothing after it.
+ */
+const EMPTY_BEARER_HASH = "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855";
+
+/** sha256 hex of a bearer. Unsalted on purpose: a bearer is 24 CSPRNG bytes, so there is no
+ * dictionary to run, and a per-entry salt would force a linear scan of every entry on every
+ * request. See §2 of the plan for the condition that would make that choice wrong. */
+export function bearerHash(bearer: string): string {
+  return createHash("sha256").update(bearer, "utf8").digest("hex");
+}
+
+/** How many entries of each form the loaded map came from — what the census line reports. */
+export type TokenMapCensus = { total: number; hashed: number; plaintext: number };
+let tokenMapCensus: TokenMapCensus = { total: 0, hashed: 0, plaintext: 0 };
+export function getTokenMapCensus(): TokenMapCensus {
+  return { ...tokenMapCensus };
+}
+
+function refuse(detail: string): never {
+  throw new Error(`[agent-coord-mcp] ${TOKENS_FILE}: ${detail}`);
+}
+
+/**
+ * Insert a hash → agentId claim, REFUSING a hash two agents both claim.
+ *
+ * ⛔ LAST-WINS WOULD RE-ATTRIBUTE A LIVE BEARER. Under v1 a collision meant two identical plaintext
+ * strings, visible to anyone reading the file. With one side hashed it is invisible on inspection —
+ * a property this release removed, so the reader has to put it back. The invariant this keeps is
+ * `map.size === census.total`: every entry claims its own key or the file is refused.
+ */
+function claim(out: Map<string, string>, hash: string, agentId: string): void {
+  const held = out.get(hash);
+  if (held !== undefined) {
+    refuse(
+      `agents "${held}" and "${agentId}" both resolve to the SAME token hash. One bearer cannot ` +
+        `authenticate two identities: whichever entry loaded last would silently take the other's ` +
+        `traffic, and with one side hashed the clash is invisible in the file. Give each agent its own token.`,
+    );
+  }
+  out.set(hash, agentId);
+}
+
+/** Read the file into a hash → agentId map, accepting v1 and v2 entries. NEVER writes. */
 export function readTokenMapSync(): Map<string, string> | null {
   if (!existsSync(TOKENS_FILE)) return null;
   const raw = readFileSync(TOKENS_FILE, "utf8");
@@ -171,21 +247,89 @@ export function readTokenMapSync(): Map<string, string> | null {
   }
   if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
     throw new Error(
-      `[agent-coord-mcp] ${TOKENS_FILE} must be a JSON object mapping agentId → token.`,
+      `[agent-coord-mcp] ${TOKENS_FILE} must be a JSON object mapping agentId → token or hashed entry.`,
     );
   }
   const out = new Map<string, string>();
-  for (const [agentId, token] of Object.entries(parsed as Record<string, unknown>)) {
-    if (typeof token !== "string" || token.length === 0) {
-      throw new Error(
-        `[agent-coord-mcp] ${TOKENS_FILE}: agent "${agentId}" has a non-string/empty token.`,
+  const census: TokenMapCensus = { total: 0, hashed: 0, plaintext: 0 };
+  for (const [agentId, value] of Object.entries(parsed as Record<string, unknown>)) {
+    census.total += 1;
+    if (typeof value === "string") {
+      // v1: the secret itself is on disk. Hash it here so the map has ONE shape.
+      if (value.length === 0) refuse(`agent "${agentId}" has a non-string/empty token.`);
+      claim(out, bearerHash(value), agentId);
+      census.plaintext += 1;
+      continue;
+    }
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+      refuse(`agent "${agentId}" has a non-string/empty token.`);
+    }
+    const entry = value as { alg?: unknown; hash?: unknown };
+    const alg = entry.alg;
+    if (typeof alg !== "string" || !(TOKEN_HASH_ALGS as readonly string[]).includes(alg)) {
+      refuse(
+        `agent "${agentId}" uses hash alg ${JSON.stringify(alg ?? null)}, which this build cannot evaluate ` +
+          `(known: ${TOKEN_HASH_ALGS.join(", ")}). Refusing the whole file: ignoring the entry would drop that ` +
+          `seat silently, and treating it as a plaintext token would compare a bearer against a hash and lock ` +
+          `the seat out while every file on disk looked correct.`,
       );
     }
-    out.set(token, agentId);
+    if (typeof entry.hash !== "string" || !HEX64.test(entry.hash)) {
+      refuse(`agent "${agentId}" has a ${alg} entry whose hash is not 64 lowercase hex characters.`);
+    }
+    if (entry.hash === EMPTY_BEARER_HASH) {
+      refuse(
+        `agent "${agentId}" has a ${alg} entry whose hash is sha256 of the EMPTY STRING. An empty ` +
+          `Authorization bearer would authenticate as that agent. The plaintext form refused an empty ` +
+          `token by its shape; this hex is well-formed, so it is refused by name instead. It is what ` +
+          `hashing an unset or mistyped shell variable produces — re-hash the real token.`,
+      );
+    }
+    claim(out, entry.hash, agentId);
+    census.hashed += 1;
   }
+  tokenMapCensus = census;
   return out;
 }
 
+/** The agent a presented bearer belongs to, or undefined. The ONE place a bearer is compared. */
+export function agentForBearer(bearer: string): string | undefined {
+  // ⚠ NO SEPARATE EMPTY-BEARER GUARD HERE, DELIBERATELY. An empty `Authorization: Bearer ` slices to
+  // "" and hashes to sha256(""), and the reader REFUSES any entry carrying that hash — so the map can
+  // never hold the only key an empty bearer could match. A guard here would therefore be unkillable
+  // by any test: I added one, the mutation matrix showed removing it changed nothing, and a conjunct
+  // no test can fire belongs in a comment rather than in the code. The enforcement point is the
+  // reader's refusal, and it is tested.
+  //
+  // ⛔ WHAT THAT DELETION COSTS, NAMED BECAUSE NOTHING ASSERTS IT: the guarantee is no longer local to
+  // this function. It holds only while `readTokenMapSync` is the map's ONLY PRODUCER — true today at
+  // all three assignments to `tokenMapCache` (the lazy first load, `reloadTokenMapSync`, and the
+  // refresh, which reads through `readTokenMapSync`). TWO changes void it, and BOTH are silent because
+  // the guard that would have caught them was deleted for being unfireable:
+  //   1. LOOSENING THE REFUSAL — if an entry carrying sha256("") stops being refused;
+  //   2. ⛔ A SECOND PRODUCER — anything that populates or mutates the map outside `readTokenMapSync`.
+  //      This is the one release B actually SCHEDULES: `coord-token migrate` writes hashed entries, and
+  //      a migrate path that seeds or patches the in-process map rather than re-reading the file
+  //      reintroduces the empty-bearer key with nothing between it and the auth path.
+  // Either one is where the guard goes back — with a test that can fail. If you are here writing
+  // `coord-token migrate`, this paragraph is addressed to you.
+  return getTokenMap()?.get(bearerHash(bearer));
+}
+
+/** One line an operator can act on. Says nothing about any bearer, prefix or hash. */
+export function tokenMapCensusLine(): string | null {
+  const map = getTokenMap();
+  if (!map) return null;
+  const c = getTokenMapCensus();
+  const tail =
+    c.total === 0
+      ? " — no entries: every bearer will be refused"
+      : c.plaintext > 0
+        ? ` — ${c.plaintext} still plaintext, run coord-token migrate`
+        : " — all hashed";
+  return `[agent-coord-mcp] token map: ${c.total} entries (${c.hashed} hashed, ${c.plaintext} plaintext)${tail}`;
+}
+
 // In-process cache of the token map, shared by the HTTP identity-binding
 // layer (server.ts) and rotateAgentToken below. A module-level cache (rather
 // than each caller re-reading the file) is what lets a rename refresh the
@@ -623,6 +767,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
@@ -632,36 +858,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/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

package/src/tools/herdr-tail.ts

@@ -41,7 +41,7 @@ import { readFileSync, statSync } from "node:fs";
 import { inboxFile, roomFile, getRooms, transportFile } from "../store.js";
 import { activeTransport, HERDR, targetOf, type Transport, type TransportMarker } from "../transports/index.js";
 import { renderForPane, advancePushCursor, readPushCursorFor, type Message } from "./herdr-delivery.js";
-import { newMessagesIn } from "./jsonl-offsets.js";
+import { newMessagesIn, idEndingAt, endOfId } from "./jsonl-offsets.js";
 
 export const DEFAULT_POLL_MS = 1000;
 /** Marker and room membership are re-read this often. A room joined mid-session is picked up within this many ticks. */
@@ -61,6 +61,12 @@ export type TailContext = {
   rooms: string[];
   /** In-process high-water mark per source: never re-type below this, even if the persistent cursor could not be written. */
   hw: Map<string, number>;
+  /**
+   * The id of the message each `hw` mark was set just past (null: set with no message, e.g. an EOF
+   * seed of a file whose last line has no id). A byte mark means something only while THAT message
+   * still ends there — see the rewrite check in tailOnce.
+   */
+  hwId: Map<string, string | null>;
   /** Last seen size per source: a source that has not grown costs one stat. */
   sizes: Map<string, number>;
   /**
@@ -73,10 +79,17 @@ export type TailContext = {
   seedEof: boolean;
   /** Sources already seeded — a room discovered on a later refresh is seeded on ITS first sight, not skipped. */
   seeded: Set<string>;
+  /** Sources whose persisted cursor is past EOF right now — logged once on entry, not on every tick. */
+  pastEof: Set<string>;
 };
-export const newContext = (seedEof = false): TailContext => ({ tick: 0, marker: null, rooms: [], hw: new Map(), sizes: new Map(), seedEof, seeded: new Set() });
+export const newContext = (seedEof = false): TailContext => ({ tick: 0, marker: null, rooms: [], hw: new Map(), hwId: new Map(), sizes: new Map(), seedEof, seeded: new Set(), pastEof: new Set() });
 
 const keyOf = (s: { kind: string; chan?: string }) => (s.kind === "dm" ? "dm" : `room:${s.chan}`);
+/** Set the in-process mark just past `msg`, remembering which message it follows. */
+const mark = (ctx: TailContext, key: string, end: number, msg: Record<string, unknown>) => {
+  ctx.hw.set(key, end);
+  ctx.hwId.set(key, msg.id === undefined || msg.id === null ? null : String(msg.id));
+};
 const sizeOf = (file: string): number => {
   try { return statSync(file).size; } catch { return 0; }
 };
@@ -169,10 +182,34 @@ export async function tailOnce(
     if (ctx.seedEof && !ctx.seeded.has(key)) {
       ctx.seeded.add(key);
       ctx.hw.set(key, size);
+      ctx.hwId.set(key, idEndingAt(src.file, size));
       log(`[herdr-tail] seeded ${key} at EOF (${size} bytes) for ${agentId} — first sight this process, nothing predating the tail will be typed`);
       continue;
     }
+    // ⛔ A BYTE MARK IS ONLY VALID WHILE THE SAME MESSAGE STILL ENDS THERE (⟨q-f44f17a7⟩). Any sender's
+    // server compacts a room on send, and every byte after the cut then means something else. A mark
+    // left PAST the new EOF made the seat deaf until the room regrew past it (the 40-minute blind
+    // stretch of 2026-09-24); a mark left INSIDE the new file resumes mid-stream and skips whatever
+    // now sits below it. So the mark is checked against the message it was set after: moved to where
+    // that message now ends, or — if it was archived — dropped, and the PERSISTED cursor, which the
+    // compactor rebased exactly (adjustCursors → rebaseBytes), is the position again.
+    const held = ctx.hw.get(key);
+    if (held !== undefined && idEndingAt(src.file, held) !== (ctx.hwId.get(key) ?? null)) {
+      const id = ctx.hwId.get(key);
+      const moved = id ? endOfId(src.file, id) : null;
+      log(`[herdr-tail] ${key} for ${agentId} was rewritten beneath the in-process mark (byte ${held}, after ${id ?? "no id"}) — ${moved !== null ? `moved to byte ${moved}, where that message now ends` : "that message is gone; resuming from the rebased push cursor"}`);
+      if (moved !== null) ctx.hw.set(key, moved);
+      else { ctx.hw.delete(key); ctx.hwId.delete(key); }
+    }
     const from = await offsetOf(agentId, src, ctx);
+    // …and if the PERSISTED cursor is past EOF too, the compactor has not rebased it yet (it rewrites
+    // the file first, then the cursors) or a server without this fix compacted. `size <= from` below
+    // skips it either way; this only makes the state VISIBLE, once per entry — on 2026-09-24 the only
+    // measurements of this defect came from a seat reading the room file by hand.
+    if (from > size) {
+      if (!ctx.pastEof.has(key)) log(`[herdr-tail] ${key} push cursor for ${agentId} is past EOF (${from} > ${size} bytes) — nothing can be typed from there until it is rebased or the file regrows past it (q-f44f17a7)`);
+      ctx.pastEof.add(key);
+    } else ctx.pastEof.delete(key);
     // ⭐ NEGATIVE CONTROL FOR THE CLASS THIS ROW IS ABOUT: nothing is logged here when
     // `size === from` — a source with nothing owed must stay silent, or every idle room on
     // every tick becomes a line and the log that is supposed to make a real stall visible
@@ -180,7 +217,7 @@ export async function tailOnce(
     if (size <= from) continue;
 
     for (const { msg, end } of newMessagesIn(src.file, from)) {
-      if (msg.from === agentId) { ctx.hw.set(key, end); continue; }
+      if (msg.from === agentId) { mark(ctx, key, end, msg); continue; }
       const where = src.kind === "dm" ? ({ kind: "dm" } as const) : ({ kind: "room", chan: src.chan! } as const);
       const rendered = await renderForPane(msg as unknown as Message, agentId, where);
       let r: { delivered: boolean; error?: string; verified?: boolean; safeToRetry?: boolean; outcome?: string };
@@ -207,13 +244,13 @@ export async function tailOnce(
       // re-typing a message that may already be sitting in the box is the paste loop in another coat.
       // A throw lands here too: nothing says whether a key went out before it.
       if (!r.delivered || r.verified !== true) {
-        ctx.hw.set(key, end);
+        mark(ctx, key, end, msg);
         out.held.push({ kind: src.kind, chan: src.chan, id: String(msg.id ?? ""), why: `${r.outcome ?? (r.delivered ? "unverified" : "not delivered")} — ${r.error ?? "not verified"}; the persistent cursor was not moved (q-15d763dc)` });
         break;
       }
       // It landed and was verified. Record that in-process FIRST, so a cursor write that fails
       // cannot turn one delivery into a paste loop, then persist exactly past this line.
-      ctx.hw.set(key, end);
+      mark(ctx, key, end, msg);
       const persisted = await advancePushCursor(agentId, where, end);
       out.delivered.push({ kind: src.kind, chan: src.chan, id: String(msg.id ?? "") });
       if (!persisted) {

package/src/tools/jsonl-offsets.ts

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

package/src/tools/messaging.ts

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