@staix/agent-mem 0.4.0 → 0.6.0

package/src/memory/capture.ts

@@ -1,13 +1,14 @@
 import { Database } from "bun:sqlite";
 import { createHash, randomBytes } from "node:crypto";
-import { appendFileSync, chmodSync, existsSync, linkSync, mkdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { chmodSync, closeSync, existsSync, lstatSync, mkdirSync, openSync, opendirSync, readFileSync, readSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { looksSecret } from "./screen.ts";
-import { isDenied } from "./platform.ts";
+import { normalizeCaptureFields, type CaptureFields } from "./capture-input.ts";
+export { CAPTURE_MAX_EXCERPT, CAPTURE_MAX_PATHS } from "./capture-input.ts";
 import { memoryBase } from "./home.ts";
-import { captureShardDir, ensureShardDescriptor, resolveAlias } from "./shard.ts";
-import { machineId } from "./store.ts";
-import { fts5Available } from "./search-fts.ts";
+import { captureShardDir, ensureShardDescriptor, readShardDescriptor, resolveAlias, shardKeyHash } from "./shard.ts";
+import { machineId } from "./machine.ts";
+import { readWindowSql, readRef, type ReadWindow, type ReadRef, ftsTerms, fts5Available } from "./search-fts.ts";
 
 /**
  * #13 design A, tier 2, born sharded (#15 T1): machine-local capture, one shard per project key. A shard lives at
@@ -25,10 +26,10 @@ import { fts5Available } from "./search-fts.ts";
  * ponytail: the cap counts row payload bytes, not the sqlite file's page slack or WAL; a VACUUM blocks writers and
  * stays out of the hook path, so file size can exceed the cap until pages are reused.
  *
- * R2 contention: a writer that cannot take its shard's lock within `busyTimeoutMs` appends the row to the
- * append-only `spool.jsonl` and exits instead of blocking the agent. The next uncontended writer (or an explicit
- * `drain()`) replays the spool; replay is idempotent per spooled line, so a crash between insert and truncation
- * never doubles a row.
+ * R2 contention: a writer that cannot take its shard's lock within `busyTimeoutMs` closes a private segment
+ * before publishing it atomically in `spool/`. The next uncontended writer (or explicit `drain()`) replays it
+ * under a unique claim name. Segments are immutable; a claim's byte offset advances only after the rows commit.
+ * Replay is idempotent per spooled line, so a crash between insert and acknowledgement never doubles a row.
  *
  * Migration: the pre-T1 machine-wide `capture/` (this branch never shipped) is drained per project on open —
  * each project key's rows move into its shard with their original timestamps, and the legacy store is removed
@@ -39,24 +40,23 @@ export const CAPTURE_DEFAULT_CAP_MB = 512;
 export const CAPTURE_DEFAULT_RETENTION_DAYS = 90;
 /** Well under the 150 ms R2 wall budget even with process startup: contention spools instead of waiting. */
 export const CAPTURE_BUSY_TIMEOUT_MS = 25;
-export const CAPTURE_MAX_EXCERPT = 2000;
-export const CAPTURE_MAX_PATHS = 32;
 /** Eviction and drain work per invocation, so a shrunk cap or a long outage is worked off over many hooks. */
 export const CAPTURE_EVICT_BATCH_ROWS = 256;
 export const CAPTURE_EVICT_MAX_BATCHES = 4;
 /** Wall-time bound for one invocation's eviction: with the batch bound, an append stays inside R2 after a cap shrink. */
 export const CAPTURE_EVICT_MAX_MS = 25;
 export const CAPTURE_DRAIN_MAX_LINES = 1000;
-const ROW_OVERHEAD_BYTES = 96;
 const SPOOL = "spool.jsonl";
 const DRAINING = "spool.jsonl.draining";
+const SPOOL_DIR = "spool";
+const SPOOL_MAX_FILES = 32;
+const SPOOL_MAX_BYTES = 256 * 1024;
+const SPOOL_MAX_MS = 25;
+const segmentName = /^spool-[0-9a-f-]+\.jsonl(?:\.offset-(\d+)(-skip)?)?(?:\.draining-[0-9a-f]+)?$/;
+let spoolSequence = 0;
+const spoolToken = () => `${Date.now().toString(16).padStart(13, "0")}-${process.pid.toString(16).padStart(8, "0")}-${(spoolSequence++).toString(16).padStart(8, "0")}-${randomBytes(12).toString("hex")}`;
 
-export interface CaptureInput {
-  project: string; agent: string; event: string;
-  tool?: string; paths?: string[]; status?: string; excerpt?: string;
-  /** Tests and the spool replay pin the time; hooks leave it to the store clock. */
-  at?: string;
-}
+export interface CaptureInput extends CaptureFields { project: string }
 export interface CaptureRow {
   id: number; at: string; project: string; agent: string; event: string;
   tool: string | null; paths: string[]; status: string | null; excerpt: string;
@@ -73,10 +73,20 @@ export interface CaptureOptions {
   /** Host-supplied R6 values win over the shard and home config files. */
   capMb?: number; retentionDays?: number;
   busyTimeoutMs?: number;
+  /** Host-only brief view: open existing capture only, without schema/index/replay writes. */
+  readOnly?: boolean;
+  /** Host-only row ceiling for the read-only snapshot; overflow is unavailable, never empty. */
+  maxReadRows?: number;
+  /** Host-only optional brief: retain the newest maxReadRows ids, with explicit partial coverage. */
+  recentReadRows?: boolean;
   /** Excerpt screen; defaults to the built-in secret screen. A host passes its stricter policy. */
   screen?: (text: string) => boolean;
 }
-export type CaptureAppend = { id: number } | { spooled: true };
+export interface CaptureAppendOptions {
+  /** Opaque stable source receipt for deterministic transcript replay. Requires an explicit source timestamp. */
+  receipt?: string;
+}
+export type CaptureAppend = { id: number; already?: true } | { spooled: true };
 
 /** One row after validation, deny-filtering, bounding and screening: what both the insert and the spool carry. */
 interface NormalizedCapture {
@@ -151,24 +161,77 @@ export class CaptureStore {
   private readonly retentionDays: number;
   /** Set when the schema setup itself met the lock: appends spool without touching the database again. */
   private contended = false;
+  private readonly readOnly: boolean;
+  private recentReadIds?: number[];
+  /** True when the optional recent snapshot excludes older capture rows. */
+  readonly recentReadTruncated: boolean = false;
 
   constructor(opts: CaptureOptions) {
     if (typeof opts.project !== "string" || !opts.project.trim()) throw new Error("capture shards need a project key");
     if (opts.memoryDir !== undefined && opts.home !== undefined) throw new Error("choose a home or an exact memory directory");
+    this.readOnly = opts.readOnly === true;
+    if (opts.readOnly !== undefined && typeof opts.readOnly !== "boolean") throw new Error("invalid capture read-only option");
+    if (opts.recentReadRows !== undefined && (typeof opts.recentReadRows !== "boolean" || !this.readOnly)) throw new Error("recent capture rows require a read-only store");
+    const maxReadRows = opts.maxReadRows ?? 128;
+    if (this.readOnly && (!Number.isSafeInteger(maxReadRows) || maxReadRows < 1 || maxReadRows >= Number.MAX_SAFE_INTEGER)) throw new Error("invalid capture read row bound");
     this.base = opts.memoryDir ?? memoryBase(opts.home);
-    const machine = opts.machine ?? machineId(this.base).id;
+    const machine = opts.machine ?? (this.readOnly ? this.existingMachine() : machineId(this.base).id);
+    if (this.readOnly && !/^[a-f0-9]{16}$/.test(machine)) throw new Error("capture machine identity unavailable");
     this.requestedKey = opts.project;
     this.key = resolveAlias(this.base, opts.project);
-    ensureShardDescriptor(this.base, this.key);
+    if (this.readOnly) {
+      const descriptor = lstatSync(join(this.base, "projects", shardKeyHash(this.key), "project.json"));
+      if (!descriptor.isFile() || descriptor.isSymbolicLink() || descriptor.size > 4096
+        || readShardDescriptor(this.base, shardKeyHash(this.key))?.key !== this.key) throw new Error("capture shard identity unavailable");
+    } else ensureShardDescriptor(this.base, this.key);
     this.dir = captureShardDir(this.base, opts.project, machine);
-    mkdirSync(this.dir, { recursive: true, mode: 0o700 });
-    chmodSync(this.dir, 0o700); // mkdir's mode applies only when it creates the directory
+    if (!this.readOnly) {
+      mkdirSync(this.dir, { recursive: true, mode: 0o700 });
+      chmodSync(this.dir, 0o700); // mkdir's mode applies only when it creates the directory
+    }
+    if (this.readOnly) for (const file of [join(this.dir, "config.json"), join(this.base, "capture-config.json")]) {
+      const stat = lstatSync(file, { throwIfNoEntry: false });
+      if (stat && (!stat.isFile() || stat.isSymbolicLink() || stat.size > 64 * 1024)) throw new Error("capture configuration unavailable");
+    }
     const config = readCaptureConfig(this.dir, this.base); // each invocation: a config change applies at the next hook
     this.capMb = opts.capMb ?? config.capMb;
     this.retentionDays = opts.retentionDays ?? config.retentionDays;
     this.now = opts.now ?? Date.now;
     this.screen = opts.screen ?? looksSecret;
     const file = join(this.dir, "capture.db");
+    if (this.readOnly) {
+      // Refuse absent/cold state without authoring machine, shard, schema, FTS or spool metadata.
+      for (const directory of [this.base, join(this.base, "projects"), join(this.base, "projects", shardKeyHash(this.key)),
+        join(this.base, "projects", shardKeyHash(this.key), "machine"), this.dir]) {
+        const stat = lstatSync(directory);
+        if (!stat.isDirectory() || stat.isSymbolicLink()) throw new Error("capture read path unavailable");
+      }
+      const stat = lstatSync(file);
+      if (!stat.isFile() || stat.isSymbolicLink()) throw new Error("capture database unavailable");
+      const timeout = opts.busyTimeoutMs ?? 0;
+      if (!Number.isSafeInteger(timeout) || timeout < 0 || timeout > 3000) throw new Error("invalid capture busy timeout");
+      const db = this.db = new Database(file, { readonly: true });
+      try {
+        db.run(`PRAGMA busy_timeout = ${timeout}`); db.run("PRAGMA cache_size = -2048"); db.run("PRAGMA mmap_size = 0");
+        db.run("BEGIN");
+        if (opts.recentReadRows) {
+          // The existing rows_at index supplies the reverse time/id walk; retain ids only.
+          // One sentinel records excluded history without counting or loading its bodies.
+          const sql = "SELECT id FROM rows INDEXED BY rows_at ORDER BY at DESC, id DESC LIMIT ?";
+          const plan = db.query(`EXPLAIN QUERY PLAN ${sql}`).all(maxReadRows + 1) as { detail: string }[];
+          if (plan.some(row => row.detail.includes("TEMP B-TREE"))) throw new Error("capture recent index unavailable");
+          const recent = db.query(sql).all(maxReadRows + 1) as { id: number }[];
+          this.recentReadIds = recent.slice(0, maxReadRows).map(row => row.id);
+          this.recentReadTruncated = recent.length > maxReadRows;
+        } else {
+          const count = (db.query("SELECT COUNT(*) AS n FROM (SELECT 1 FROM rows LIMIT ?)").get(maxReadRows + 1) as { n: number }).n;
+          if (count > maxReadRows) throw new Error("capture brief row bound exceeded");
+        }
+        if (resolveAlias(this.base, this.requestedKey) !== this.key) throw new Error("capture alias binding changed");
+      } catch (error) { db.close(); throw error; }
+      this.migrated = 0;
+      return;
+    }
     const db = new Database(file, { create: true });
     this.db = db;
     try { chmodSync(file, 0o600); } catch { /* best effort */ }
@@ -182,12 +245,26 @@ export class CaptureStore {
       db.run("CREATE TABLE IF NOT EXISTS meta (key TEXT PRIMARY KEY, value TEXT NOT NULL)");
       this.ensureFts();
     } catch (error) {
-      if (!lockError(error)) throw error;
+      if (!lockError(error)) { db.close(); throw error; }
       this.contended = true; // R2: the hook spools and exits instead of waiting out another writer
     }
     this.migrated = this.contended ? 0 : this.migrateLegacy();
   }
 
+  private existingMachine(): string {
+    const file = join(this.base, "machine.json"), stat = lstatSync(file);
+    if (!stat.isFile() || stat.isSymbolicLink() || stat.size > 4096) throw new Error("capture machine identity unavailable");
+    const value = JSON.parse(readFileSync(file, "utf8")) as { id?: unknown };
+    if (typeof value?.id !== "string" || !/^[a-f0-9]{16}$/.test(value.id)) throw new Error("capture machine identity unavailable");
+    return value.id;
+  }
+  private writable(): void {
+    if (this.readOnly) throw new Error("capture store is read-only");
+  }
+  private checkReadBinding(): void {
+    if (this.readOnly && resolveAlias(this.base, this.requestedKey) !== this.key) throw new Error("capture alias binding changed");
+  }
+
   /** The pre-T1 machine-wide store hands this project key's rows AND spool lines to the shard, once; an emptied legacy store goes away. */
   private migrateLegacy(): number {
     const legacyDir = join(this.base, "capture"); // the pre-T1 machine-wide location (this branch never shipped)
@@ -239,7 +316,13 @@ export class CaptureStore {
 
   /** A line moved from the legacy spool, byte for byte: the shard's drain normalizes whatever format it holds. */
   private spoolRaw(line: string): void {
-    appendFileSync(join(this.dir, SPOOL), line + "\n", { mode: 0o600 });
+    const directory = join(this.dir, SPOOL_DIR), writing = join(directory, ".writing");
+    mkdirSync(writing, { recursive: true, mode: 0o700 });
+    const name = `spool-${spoolToken()}.jsonl`, temporary = join(writing, name);
+    try {
+      writeFileSync(temporary, line + "\n", { mode: 0o600, flag: "wx" }); // closes before readers can see it
+      renameSync(temporary, join(directory, name));
+    } finally { rmSync(temporary, { force: true }); }
   }
 
   /** External-content FTS5 over the excerpts, kept in sync by triggers, so capture search needs no catch-up pass. */
@@ -254,6 +337,30 @@ export class CaptureStore {
     if (!had && (this.db.query("SELECT COUNT(*) AS n FROM rows").get() as { n: number }).n > 0) this.db.run("INSERT INTO fts (fts) VALUES ('rebuild')");
   }
 
+  private mcpReady = false;
+  /** One-time MCP read cost only: hooks neither create this derived index nor scan history to fill it. */
+  private ensureMcpFts(): boolean {
+    if (this.readOnly) return !!this.db.query("SELECT 1 FROM sqlite_master WHERE name = 'mcp_fts' AND type = 'table'").get();
+    if (!fts5Available()) return false;
+    if (this.mcpReady) return true;
+    try {
+      this.db.transaction(() => {
+        const hadMcp = !!this.db.query("SELECT 1 FROM sqlite_master WHERE name = 'mcp_fts' AND type = 'table'").get();
+        const body = (row: string) => `${row}.excerpt || char(10) || COALESCE((SELECT group_concat(value, ' ') FROM json_each(${row}.paths)), '') || char(10) || ${row}.event`;
+        this.db.run("CREATE VIRTUAL TABLE IF NOT EXISTS mcp_fts USING fts5(body)");
+        this.db.run(`CREATE TRIGGER IF NOT EXISTS rows_mcp_ai AFTER INSERT ON rows BEGIN INSERT INTO mcp_fts(rowid, body) VALUES (new.id, ${body("new")}); END`);
+        this.db.run("CREATE TRIGGER IF NOT EXISTS rows_mcp_ad AFTER DELETE ON rows BEGIN DELETE FROM mcp_fts WHERE rowid = old.id; END");
+        this.db.run(`CREATE TRIGGER IF NOT EXISTS rows_mcp_au AFTER UPDATE ON rows BEGIN DELETE FROM mcp_fts WHERE rowid = old.id; INSERT INTO mcp_fts(rowid, body) VALUES (new.id, ${body("new")}); END`);
+        if (!hadMcp) this.db.run(`INSERT INTO mcp_fts(rowid, body) SELECT rows.id, ${body("rows")} FROM rows`);
+      }).immediate();
+      this.mcpReady = true;
+      return true;
+    } catch {
+      // Missing/unavailable derived search is not a capture read failure. Retry on the next independent read.
+      return false;
+    }
+  }
+
   private bytes(): number {
     return Number((this.db.query("SELECT value FROM meta WHERE key = 'bytes'").get() as { value: string } | null)?.value ?? "0");
   }
@@ -267,74 +374,127 @@ export class CaptureStore {
    * and a later drainer — under any screen — inserts exactly that row. On lock contention the row goes to the spool
    * and the caller exits fast (R2); the next uncontended writer replays it with its original timestamp.
    */
-  append(input: CaptureInput): CaptureAppend {
+  append(input: CaptureInput, options: CaptureAppendOptions = {}): CaptureAppend {
+    this.writable();
     const str = (v: unknown, max: number) => typeof v === "string" && v.length > 0 && v.length <= max;
     if (!str(input.project, 400) || !str(input.agent, 64) || !str(input.event, 64)) throw new Error("capture rows need a project, an agent and an event");
     if (input.at !== undefined && (typeof input.at !== "string" || !Number.isFinite(Date.parse(input.at)))) throw new Error("capture row time must be a parseable time string");
+    const receipt = options.receipt;
+    if (receipt !== undefined && (typeof receipt !== "string" || !/^[a-f0-9]{64}$/.test(receipt) || input.at === undefined)) throw new Error("capture receipt needs a stable time and a 64-hex digest");
     const row = this.normalize(input);
+    // Reuse the immutable spool format and its existing unique index: a crash between capture and cursor
+    // advance replays exactly the same screened line, whether first written directly or under contention.
+    const spoolId = receipt === undefined ? null : createHash("sha256").update(this.spoolLine(row, receipt)).digest("hex");
     if (this.contended) {
-      this.spool(row);
+      this.spool(row, receipt);
       return { spooled: true };
     }
     try {
       this.drain(); // replay earlier spooled rows first, so row ids stay in hook order
       // The row and its running byte count commit or roll back together: a lock after the INSERT cannot spool a duplicate.
-      const id = this.db.transaction(() => this.insertRow(row, null)).immediate();
+      const result = this.db.transaction((): CaptureAppend => {
+        const id = this.insertRow(row, spoolId);
+        if (id !== undefined) return { id };
+        const prior = this.db.query("SELECT id FROM rows WHERE spool_id = ?").get(spoolId) as { id: number } | null;
+        if (!prior) throw new Error("capture receipt lookup failed");
+        return { id: prior.id, already: true };
+      }).immediate();
       try { this.evict(); } catch (error) {
         if (!lockError(error)) throw error; // the row is already committed; a locked eviction simply resumes on a later append
       }
-      return { id: id! };
+      return result;
     } catch (error) {
       if (!lockError(error)) throw error;
-      this.spool(row);
+      this.spool(row, receipt);
       return { spooled: true };
     }
   }
 
   /** The one place input becomes a row: caps fields, deny-filters paths, screens the excerpt, counts its bytes. */
   private normalize(input: CaptureInput): NormalizedCapture {
-    const str = (v: unknown, max: number) => typeof v === "string" && v.length > 0 && v.length <= max;
-    // Canonical UTC ISO text, so text order is time order for eviction (`at < cutoff`) and search (`at >= notBefore`).
-    const at = new Date(input.at === undefined ? this.now() : Date.parse(input.at)).toISOString();
-    const tool = str(input.tool, 64) ? input.tool! : null;
-    const status = str(input.status, 64) ? input.status! : null;
-    const paths = (input.paths ?? []).map(String).filter((p) => p && !isDenied(p)).slice(0, CAPTURE_MAX_PATHS).map((p) => p.slice(0, 400));
-    let excerpt = (input.excerpt ?? "").slice(0, CAPTURE_MAX_EXCERPT);
-    if (excerpt && this.screen(excerpt)) excerpt = "[secret-screened]";
-    return { at, project: input.project, agent: input.agent, event: input.event, tool, paths, status, excerpt,
-      bytes: Buffer.byteLength(excerpt) + Buffer.byteLength(JSON.stringify(paths)) + ROW_OVERHEAD_BYTES };
+    const { at, agent, event, tool, paths, status, excerpt, bytes } = normalizeCaptureFields(input, () => this.now(), text => this.screen(text));
+    return { at, project: input.project, agent, event, tool, paths, status, excerpt, bytes };
   }
 
-  private spool(row: NormalizedCapture): void {
-    appendFileSync(join(this.dir, SPOOL), JSON.stringify({ ...row, nonce: randomBytes(4).toString("hex") }) + "\n", { mode: 0o600 });
+  private spoolLine(row: NormalizedCapture, nonce = randomBytes(12).toString("hex")): string {
+    return JSON.stringify({ ...row, nonce });
+  }
+
+  private spool(row: NormalizedCapture, nonce?: string): void {
+    this.spoolRaw(this.spoolLine(row, nonce));
   }
 
   /**
-   * Replay the spool, finishing a leftover draining file from a crash first. Idempotent per spooled line and bounded
-   * per invocation; malformed or incomplete lines are skipped and counted instead of poisoning every later append.
-   * ponytail: the shared spool/draining names cannot fully close multi-process replacement and already-open-writer
-   * races. Per-writer spool files with unique drain names are the upgrade path if that hard guarantee is required.
+   * Immutable segments with unique claims: a stale drainer can remove only its own old name. Recovery may
+   * steal a live claim; both readers can replay it safely because row ids dedupe and neither mutates its inode.
+   * Offset acknowledgement is another rename, after commit, so a crash always leaves replayable evidence.
+   * ponytail: unpublished files left in .writing by a killed writer are not replayed (they may be partial).
+   * Quiescent maintenance may remove them; durable recovery of an interrupted append needs a journal/fsync.
+   * Legacy fixed names are accepted for upgrade, but old-version writers must stop before upgrading: their
+   * already-open shared inode cannot be made immutable by a newer reader.
    */
   drain(): { drained: number; skipped: number } {
-    let budget = CAPTURE_DRAIN_MAX_LINES, drained = 0, skipped = 0;
+    this.writable();
+    let budget = CAPTURE_DRAIN_MAX_LINES, byteBudget = SPOOL_MAX_BYTES, drained = 0, skipped = 0;
     if (this.contended) return { drained, skipped };
+    const started = performance.now();
+    const directory = join(this.dir, SPOOL_DIR);
+    mkdirSync(directory, { recursive: true, mode: 0o700 });
+    const candidates: { file: string; name: string; offset: number; skip: boolean }[] = [];
+    // Fixed-name imports are only compatibility inputs; all acknowledgements use unique names thereafter.
+    for (const name of [DRAINING, SPOOL]) {
+      if (existsSync(join(this.dir, name))) candidates.push({ file: join(this.dir, name), name: `spool-${spoolToken()}.jsonl`, offset: 0, skip: false });
+    }
+    const entries = opendirSync(directory);
+    try {
+      for (let scanned = 0; scanned < 256 && candidates.length < SPOOL_MAX_FILES; scanned++) {
+        const entry = entries.readSync();
+        if (!entry) break;
+        const match = segmentName.exec(entry.name);
+        if (entry.isFile() && match) candidates.push({ file: join(directory, entry.name), name: entry.name.split(".offset-")[0]!.split(".draining-")[0]!,
+          offset: Number(match[1] ?? 0), skip: !!match[2] });
+      }
+    } finally { entries.closeSync(); }
     const validRow = (row: Partial<NormalizedCapture>): row is NormalizedCapture =>
       typeof row.at === "string" && row.at.length > 0 && typeof row.project === "string" && row.project.length > 0
       && typeof row.agent === "string" && row.agent.length > 0 && typeof row.event === "string" && row.event.length > 0
       && (row.tool === null || typeof row.tool === "string") && Array.isArray(row.paths) && row.paths.every((p) => typeof p === "string")
       && (row.status === null || typeof row.status === "string") && typeof row.excerpt === "string"
       && typeof row.bytes === "number" && Number.isFinite(row.bytes) && row.bytes >= 0;
-    for (const renameFirst of [false, true]) {
-      const file = join(this.dir, DRAINING);
-      if (renameFirst && existsSync(join(this.dir, SPOOL))) {
-        if (budget <= 0) break;
-        // link+remove, not rename: a draining file another process owns is never clobbered at claim time.
-        try { linkSync(join(this.dir, SPOOL), file); rmSync(join(this.dir, SPOOL)); } catch { continue; }
+    candidates.sort((a, b) => a.name.localeCompare(b.name));
+    for (const source of candidates) {
+      if (budget <= 0 || byteBudget <= 0 || performance.now() - started >= SPOOL_MAX_MS) break;
+      const file = join(directory, `${source.name}.offset-${source.offset}${source.skip ? "-skip" : ""}.draining-${randomBytes(12).toString("hex")}`);
+      try { renameSync(source.file, file); } catch { continue; } // another drainer claimed this exact name
+      let bytes: Buffer, size: number;
+      try {
+        const fd = openSync(file, "r");
+        try {
+          size = statSync(file).size;
+          bytes = Buffer.alloc(Math.min(byteBudget, Math.max(0, size - source.offset)));
+          bytes = bytes.subarray(0, readSync(fd, bytes, 0, bytes.length, source.offset));
+        } finally { closeSync(fd); }
+      } catch { continue; } // a recovery reader may already have moved our unique claim
+      byteBudget -= bytes.length;
+      let consumed = 0, skipping = source.skip;
+      const batch: string[] = [];
+      while (consumed < bytes.length && batch.length < budget) {
+        const newline = bytes.indexOf(10, consumed);
+        if (newline < 0) {
+          if (source.offset + bytes.length < size) {
+            // A short window may only be the allowance left after another file, not an oversized row.
+            if (consumed === 0 && bytes.length === SPOOL_MAX_BYTES) { consumed = bytes.length; skipping = true; }
+            break;
+          }
+          if (!skipping) batch.push(bytes.subarray(consumed).toString("utf8"));
+          else skipped++;
+          consumed = bytes.length; skipping = false; break;
+        }
+        const line = bytes.subarray(consumed, newline).toString("utf8");
+        consumed = newline + 1;
+        if (skipping) { skipped++; skipping = false; }
+        else if (line) batch.push(line);
       }
-      if (!existsSync(file)) continue;
-      const lines = readFileSync(file, "utf8").split("\n").filter(Boolean);
-      if (!lines.length) { rmSync(file, { force: true }); continue; }
-      const batch = lines.slice(0, Math.max(0, budget));
       try {
         this.db.transaction(() => {
           for (const line of batch) {
@@ -356,8 +516,12 @@ export class CaptureStore {
         break; // still contended: the spool stays for the next invocation
       }
       budget -= batch.length;
-      if (batch.length === lines.length) rmSync(file, { force: true });
-      else { writeFileSync(file, lines.slice(batch.length).join("\n") + "\n", { mode: 0o600 }); break; }
+      const next = source.offset + consumed;
+      if (next >= size) rmSync(file, { force: true });
+      else {
+        // Never rewrite a shared inode. Only the owner of this exact claim can acknowledge its prefix.
+        try { renameSync(file, join(directory, `${source.name}.offset-${next}${skipping ? "-skip" : ""}`)); } catch { /* recovered elsewhere */ }
+      }
     }
     return { drained, skipped };
   }
@@ -385,6 +549,7 @@ export class CaptureStore {
    * deleted; the curated store is a different file this class never opens (AC5).
    */
   evict(): { expired: number; trimmed: number } {
+    this.writable();
     if (this.contended) return { expired: 0, trimmed: 0 };
     const start = performance.now();
     const expired = this.evictWhere("at < ?", [new Date(this.now() - this.retentionDays * 24 * 3600_000).toISOString()], start);
@@ -417,14 +582,35 @@ export class CaptureStore {
   }
 
   rows(f: { project?: string; sinceId?: number; limit?: number } = {}): CaptureRow[] {
+    this.checkReadBinding();
     const where: string[] = [], bind: (string | number)[] = [];
+    if (this.recentReadIds) { where.push("id IN (SELECT value FROM json_each(?))"); bind.push(JSON.stringify(this.recentReadIds)); }
     if (f.project) { where.push("project = ?"); bind.push(f.project); }
     if (f.sinceId !== undefined) { where.push("id > ?"); bind.push(f.sinceId); }
     const rows = this.db.query(`SELECT * FROM rows${where.length ? ` WHERE ${where.join(" AND ")}` : ""} ORDER BY id LIMIT ?`).all(...bind, f.limit ?? 1000) as RawRow[];
     return rows.map(toRow);
   }
 
+  /** Exact-project, bounded body pages; MCP screens before filling its public candidate window. */
+  readPage(window: ReadWindow & { query?: string; match?: "substring" }): { rows: CaptureRow[]; next?: ReadRef; engine?: "fts5" | "substring" } {
+    this.checkReadBinding();
+    const { columns, where, bind } = readWindowSql(window, "id");
+    if (this.recentReadIds) {
+      if (window.query !== undefined) throw new Error("recent capture brief does not support query indexes");
+      where.push("id IN (SELECT value FROM json_each(?))"); bind.push(JSON.stringify(this.recentReadIds));
+    }
+    const engine = window.query === undefined ? undefined : window.match !== "substring" && this.ensureMcpFts() ? "fts5" : "substring";
+    if (window.query !== undefined && engine === "fts5") {
+      const match = ftsTerms(window.query); if (!match) return { rows: [], engine };
+      where.push("id IN (SELECT rowid FROM mcp_fts WHERE mcp_fts MATCH ?)"); bind.push(match);
+    }
+    const rows = this.db.query(`SELECT *, ${columns} FROM rows WHERE ${where.join(" AND ")} ORDER BY candidate_position, candidate_id LIMIT ?`)
+      .all(...bind, window.limit) as (RawRow & { candidate_id: string; candidate_position: number })[];
+    return { rows: rows.map(toRow), ...(engine ? { engine } : {}), ...(rows.length ? { next: readRef(rows[rows.length - 1]!) } : {}) };
+  }
+
   stats(): { rows: number; bytes: number; capMb: number; retentionDays: number; fileBytes: number } {
+    this.checkReadBinding();
     let fileBytes = 0;
     try { fileBytes = statSync(join(this.dir, "capture.db")).size; } catch { /* not created yet */ }
     return { rows: (this.db.query("SELECT COUNT(*) AS n FROM rows").get() as { n: number }).n, bytes: this.bytes(), capMb: this.capMb, retentionDays: this.retentionDays, fileBytes };

package/src/memory/catalog.ts

@@ -2,7 +2,7 @@ import { Database } from "bun:sqlite";
 import { chmodSync, existsSync, readdirSync } from "node:fs";
 import { join } from "node:path";
 import { memoryBase } from "./home.ts";
-import { listAliases, readShardDescriptor, SHARDED_SCHEMA } from "./shard.ts";
+import { effectiveAliases, readShardDescriptor, SHARDED_SCHEMA } from "./shard.ts";
 import { readProfileJSON, validGeneration } from "./generation.ts";
 import { captureShardStats, readCaptureConfig } from "./capture.ts";
 import { openShardStore } from "./store.ts";
@@ -73,9 +73,8 @@ export function walkShards(base: string): { hash: string; key: string; local: bo
 /** What the shards and the alias log say, before anything is persisted. */
 export function scanCatalog(base: string): CatalogProject[] {
   const captured = capturedSelection(base);
-  // The latest op per alias: an alias lists only under the key it currently points at, never under a past target.
-  const latest = new Map<string, string>();
-  for (const op of listAliases(base)) latest.set(op.alias, op.key);
+  // The latest op per alias (a removal included): an alias lists only under the key it currently points at, never under a past target or after `alias remove`.
+  const latest = effectiveAliases(base);
   const out: CatalogProject[] = [];
   for (const shard of walkShards(base)) {
     let rows = 0, bytes = 0, lastAt: string | null = null;

package/src/memory/import.ts

@@ -5,7 +5,7 @@ import { realPath } from "./platform.ts";
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { KINDS, looksSecret, type Kind, type MemoryStore } from "./store.ts";
-import { listAliases, resolveAlias } from "./shard.ts";
+import { aliasedKeys, resolveAlias } from "./shard.ts";
 import { WorkListStore, type WorkListFields, type WorkListPolicy } from "./work-lists.ts";
 
 /** The claude-mem store is another program's: opened read-only, never written, its locks waited on briefly. */
@@ -27,8 +27,7 @@ export async function importClaudeMemWorkState(opts: { base: string; project: st
   const limit = opts.limit ?? 10_000;
   if (!Number.isSafeInteger(limit) || limit <= 0) throw new Error("--limit takes a positive integer");
   const project = resolveAlias(opts.base, opts.project);
-  const aliases = [...new Map(listAliases(opts.base).map(op => [op.alias, op.key]))]
-    .filter(([, key]) => key === project).map(([alias]) => alias).sort();
+  const aliases = aliasedKeys(opts.base, project);
   const result: WorkStateImportResult = { read: 0, added: 0, skipped: { invalid: 0, policy: 0 }, more: false, cursor: 0 };
   if (!aliases.length) return result;
   const db = new Database(file, { readonly: true });

package/src/memory/machine.ts

@@ -0,0 +1,31 @@
+import { randomBytes } from "node:crypto";
+import { linkSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+export interface Machine { id: string; label: string }
+/** Random per `~/.agenthub`, with a person-given label; created on first use. */
+export function machineId(dir: string): Machine {
+  const file = join(dir, "machine.json");
+  const read = (): Machine | undefined => {
+    try {
+      const m = JSON.parse(readFileSync(file, "utf8")) as Machine;
+      if (/^[0-9a-f]{16}$/.test(m?.id)) return { id: m.id, label: typeof m.label === "string" ? m.label : m.id };
+    } catch { /* none, or unreadable */ }
+    return undefined;
+  };
+  const found = read();
+  if (found) return found;
+  // Hubs of several projects can start at once on a fresh home: each writes its own temp file and links it into place,
+  // which fails if another got there first; then everyone reads the one identity that won.
+  const id = randomBytes(8).toString("hex");
+  mkdirSync(dir, { recursive: true, mode: 0o700 });
+  const tmp = `${file}.${process.pid}.${randomBytes(4).toString("hex")}.tmp`;
+  writeFileSync(tmp, JSON.stringify({ id, label: id }) + "\n", { mode: 0o600 });
+  try { linkSync(tmp, file); } catch { /* another process created it: its identity wins */ } finally { rmSync(tmp, { force: true }); }
+  // A file that is there but holds no valid id is never overwritten (another process may be reading it): the store
+  // fails to open, so the hub says hub memory is unavailable instead of filing notes under no machine.
+  const won = read();
+  if (!won) throw new Error(`${file} holds no valid machine id; remove it and a new one is made`);
+  return won;
+}
+

package/src/memory/metrics.ts

@@ -0,0 +1,63 @@
+import { closeSync, constants, fstatSync, openSync, readSync, appendFileSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+/** Rolling resource samples; importing this leaf never loads a memory store or capacity probe. */
+export interface MetricSample { at: string; kind: "hook" | "search"; wallMs?: number; rssMB?: number; rawRssMB?: number; idleMB?: number; captureDrops?: number; captureDropReason?: CaptureDropReason }
+const METRICS_MAX_BYTES = 64 * 1024, METRICS_KEEP = 200;
+
+export function metricsPath(base: string): string {
+  return join(base, "metrics.jsonl");
+}
+
+/** Append samples, trimming the rolling file when it outgrows its bound (newest samples win). */
+export function appendMetrics(base: string, samples: MetricSample[]): void {
+  mkdirSync(base, { recursive: true, mode: 0o700 });
+  const file = metricsPath(base);
+  appendFileSync(file, samples.map((s) => JSON.stringify(s)).join("\n") + "\n", { mode: 0o600 });
+  try {
+    if (statSync(file).size <= METRICS_MAX_BYTES) return;
+    const lines = readFileSync(file, "utf8").split("\n").filter(Boolean).slice(-METRICS_KEEP);
+    writeFileSync(file, lines.join("\n") + "\n", { mode: 0o600 });
+  } catch { /* a trim failure loses nothing: the file simply stays larger */ }
+}
+
+/** The newest samples first-preserved order (oldest to newest); malformed lines are skipped. */
+export function readMetrics(base: string, limit = METRICS_KEEP): MetricSample[] {
+  let lines: string[] = [];
+  try { lines = readFileSync(metricsPath(base), "utf8").split("\n").filter(Boolean); } catch { return []; }
+  const out: MetricSample[] = [];
+  for (const line of lines.slice(-limit)) {
+    try {
+      const s = JSON.parse(line) as MetricSample;
+      if ((s?.kind === "hook" || s?.kind === "search") && typeof s.at === "string") out.push(s);
+    } catch { /* a malformed line is skipped */ }
+  }
+  return out;
+}
+
+
+export type CaptureDropReason = "spool_full" | "cwd_removed" | "undrainable_expired" | "scope_unknown";
+const DROP_REASONS: readonly CaptureDropReason[] = ["spool_full", "cwd_removed", "undrainable_expired", "scope_unknown"];
+/** Numeric notice only, bounded to the rolling metric tail; never an all-time counter. */
+export function captureDropSummary(base: string): Partial<Record<CaptureDropReason, number>> {
+  const counts: Partial<Record<CaptureDropReason, number>> = {};
+  let fd: number | undefined;
+  try {
+    fd = openSync(metricsPath(base), constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+    const stat = fstatSync(fd); if (!stat.isFile()) return counts;
+    const start = Math.max(0, stat.size - METRICS_MAX_BYTES), bytes = Buffer.alloc(stat.size - start);
+    const length = readSync(fd, bytes, 0, bytes.length, start);
+    let text = new TextDecoder("utf-8", { fatal: true }).decode(bytes.subarray(0, length));
+    if (start) text = text.slice(text.indexOf("\n") + 1);
+    for (const line of text.split("\n").filter(Boolean).slice(-METRICS_KEEP)) {
+      try {
+        const sample = JSON.parse(line) as MetricSample;
+        if (sample.kind !== "hook" || !DROP_REASONS.includes(sample.captureDropReason!) || !Number.isSafeInteger(sample.captureDrops) || sample.captureDrops! <= 0) continue;
+        const reason = sample.captureDropReason!;
+        counts[reason] = (counts[reason] ?? 0) + sample.captureDrops!;
+      } catch { /* A malformed metric is never a notice. */ }
+    }
+  } catch { /* Metric availability never denies the native call. */ }
+  finally { if (fd !== undefined) closeSync(fd); }
+  return counts;
+}

package/src/memory/mutation.ts

@@ -6,10 +6,11 @@ export const MUTATION_BUSY_TIMEOUT_MS = 3000;
 // ponytail: older hubs (before consuming this agent-mem), raw/legacy log writers and any segment editor
 // that bypasses this lock are not serialized. Require every writer to take it, or make segment appends API-only.
 /** An empty, machine-local SQLite file used only for crash-safe writer exclusion, never for memory data. */
-export function mutationDatabase(dir: string): Database {
+export function mutationDatabase(dir: string, busyTimeoutMs = MUTATION_BUSY_TIMEOUT_MS): Database {
+  if (!Number.isSafeInteger(busyTimeoutMs) || busyTimeoutMs < 0 || busyTimeoutMs > MUTATION_BUSY_TIMEOUT_MS) throw new Error("invalid mutation busy timeout");
   const file = join(dir, "mutation-lock.db"), db = new Database(file, { create: true });
   chmodSync(file, 0o600);
-  db.run(`PRAGMA busy_timeout = ${MUTATION_BUSY_TIMEOUT_MS}`);
+  db.run(`PRAGMA busy_timeout = ${busyTimeoutMs}`);
   return db;
 }
 
@@ -22,13 +23,14 @@ export function acquireMutation(dir: string): (() => void) | undefined {
 }
 
 /** Short local admission fence, never held across sync/network or data mutations. */
-export function readerAdmissionDatabase(dir: string): Database {
+export function readerAdmissionDatabase(dir: string, busyTimeoutMs = MUTATION_BUSY_TIMEOUT_MS): Database {
+  if (!Number.isSafeInteger(busyTimeoutMs) || busyTimeoutMs < 0 || busyTimeoutMs > MUTATION_BUSY_TIMEOUT_MS) throw new Error("invalid reader admission busy timeout");
   const file = join(dir, "reader-admission.db");
   for (const suffix of ["", "-wal", "-shm", "-journal"]) {
     const stat = lstatSync(file + suffix, { throwIfNoEntry: false });
     if (stat && (stat.isSymbolicLink() || !stat.isFile())) throw new Error("reader admission fence is not a regular file");
   }
   const db = new Database(file, { create: true });
-  try { chmodSync(file, 0o600); db.run(`PRAGMA busy_timeout = ${MUTATION_BUSY_TIMEOUT_MS}`); return db; }
+  try { chmodSync(file, 0o600); db.run(`PRAGMA busy_timeout = ${busyTimeoutMs}`); return db; }
   catch (error) { db.close(); throw error; }
 }