@staix/agent-mem 0.4.0 → 0.5.0

package/README.md

@@ -2,7 +2,7 @@
 
 Curated memory with append-only JSONL logs, a derived SQLite index, short- and long-term tiers, a typed graph, goals with leases, and git sync between machines. Extracted from [agent-hub](https://github.com/STAIxBWLB/agent-hub), with compatible storage and entry IDs.
 
-Version: 0.4.0. Requires Bun 1.4.2 or later; no runtime dependencies.
+Version: 0.5.0. Requires Bun 1.4.2 or later; no runtime dependencies.
 
 ## Install
 
@@ -135,7 +135,7 @@ The JSONL segments are authoritative. `index.db` is derived and can be rebuilt.
 
 From issue #13 (phase P1), the package carries a second, machine-local tier beside the curated store, born sharded (#15 T1): one capture shard per project key at `projects/<key-hash>/machine/<machine-id>/` under the memory home, with its own locks so two projects never contend. The capture tier records deterministic tool-event rows (project, agent, event, tool, paths, exit status and a bounded, secret-screened excerpt) in the shard's `capture.db`. It is never synced, never read as curated evidence, and never writes a curated log, so its maintenance can never evict notes, goals or work lists. Capture is bounded by a soft size cap and a retention window (defaults 512 MB per shard, 90 days), resolved at every invocation from the library options, then the shard's `config.json`, then the home default `capture-config.json`; eviction removes the oldest capture rows first in bounded batches. The 2026-10-17 owner decision keeps the P1 cap per shard; the machine-wide total is #15 T5. On lock contention a writer appends to an append-only spool and exits fast; the next uncontended writer replays the spool idempotently. The capture path makes no network or model call. The pre-T1 machine-wide `capture/` (an unreleased layout of this branch) is migrated per project on open and removed once empty.
 
-Project identity (#15 D2) keeps `memoryProjectKey`: a worktree, a submodule and the main checkout of one repository share its key; two unrelated same-named repositories without a remote get distinct path-hash keys, flagged `local` in the shard's `project.json` and the catalog. A no-remote key hashes the main working root (using the actual top-level for a separate git dir), so keys written from the repository root keep their pre-#15 value. Known limit: a linked worktree of a no-remote separate-git-dir repository gets its own key, because git does not record that repository's main working root (probe: `alpha` and `alpha/sub` share `alpha@<hash>`, `alpha-wt` gets `alpha-wt@<hash>`); the key stays as is for root-key compatibility, and a reviewed alias reconciles its capture. Keys written by older builds from a subdirectory or worktree still used that invocation's cwd hash; a person-reviewed alias maps such a key to its canonical one for capture, work lists and the CLI and MCP project binding. Curated rows written under the old key keep it and are not remapped, so the CLI and MCP stop showing that key's project-scoped notes, goals and candidates (the library still reads them by the raw key; shared rows stay visible). An alias can be retargeted but not removed, so add one only after checking the old key's private notes; curated row reconciliation is a later spec change. `amem alias add <from-key> <to-key>` appends an op to `aliases.jsonl` (latest wins, never chained, never automatic), `amem alias list` shows the ops. `catalog.db` in the memory home (#15 D3's storage part) is derived only from the shards and the alias log and rebuilds to the same rows; the D3 management commands are #15 T5 and not built.
+Project identity (#15 D2) keeps `memoryProjectKey`: a worktree, a submodule and the main checkout of one repository share its key; two unrelated same-named repositories without a remote get distinct path-hash keys, flagged `local` in the shard's `project.json` and the catalog. A no-remote key hashes the main working root (using the actual top-level for a separate git dir), so keys written from the repository root keep their pre-#15 value. Known limit: a linked worktree of a no-remote separate-git-dir repository gets its own key, because git does not record that repository's main working root (probe: `alpha` and `alpha/sub` share `alpha@<hash>`, `alpha-wt` gets `alpha-wt@<hash>`); the key stays as is for root-key compatibility, and a reviewed alias reconciles its capture. Keys written by older builds from a subdirectory or worktree still used that invocation's cwd hash; a person-reviewed alias maps such a key to its canonical one for capture, work lists and the CLI and MCP project binding. Curated rows written under the old key keep their key in the log (nothing is rewritten), and the CLI and MCP read them under the canonical project: the project filter of notes, goals, candidates, vault candidates and work lists covers the canonical key and every key aliased to it, and presents those rows under the canonical key (#27). The library `MemoryStore` still reads by the raw key unless a host passes `reconcile`, and shared rows stay visible as before. Writes still go to the key's own log and shard, and a settle or forget of an aliased row lands in the shard that holds it. `amem alias add <from-key> <to-key>` appends an op to `aliases.jsonl` (latest wins, never chained, never automatic), `amem alias remove <from-key>` appends a removal (the old key reads under itself again, the history stays), `amem alias list` shows the ops including removals. Both are person-only and need a terminal. An amem or hub older than this change ignores a removal and keeps the old binding until it is upgraded, so upgrade every host that shares the home first. A correction accepted on an aliased row lives under the canonical key, so after a removal the old key shows the superseded note again (see `docs/contracts.md`). `catalog.db` in the memory home (#15 D3's storage part) is derived only from the shards and the alias log and rebuilds to the same rows; the D3 management commands are #15 T5 and not built.
 
 `store.search(query, filter)` searches the curated tier and the current project's capture shard with SQLite FTS5 and BM25 plus tier/recency weighting: natural multi-word queries match partial term sets (the substring filter required every word), and a curated row outranks the same text in the capture tier. Prefix terms match inflections and Korean particles in either direction by retaining the original query term and adding a common-particle-stripped alternative. The FTS copy of the curated rows lives in its own derived `search.db` (`index.db`'s table set is a frozen contract and gains nothing); it is written from the same apply path as the index, and a prune, crash or rebuild is detected and resynced, so the incremental FTS copy equals a full resync. Where FTS5 is unavailable the engine falls back to the substring filter and reports `engine: "substring"`; capture recall needs FTS5 and is skipped in the fallback. The library entry exports `CaptureStore`, `captureSearch`, `readCaptureConfig`, `writeCaptureConfig`, `SearchIndex`, `fts5Available`, the shard helpers (`resolveAlias`, `appendAlias`, `listAliases`, `shardKeyHash`), the catalog (`rebuildCatalog`, `readCatalog`, `scanCatalog`) and the capacity advisor (`capacityReport`).
 
@@ -238,6 +238,8 @@ A native shard crash tail is left to its original writer's recovery. Migration c
 
 Run `amem mcp` as a stdio child of the agent CLI. It binds the working directory, canonical project key, exact memory home and selected profile once, accepts no project/home overrides in tool arguments, and closes all stores on stdin EOF. It has no listener, daemon, watcher or model call. Ordinary person commands retain their agent-marker refusal and mutation TTY checks; `mcp` is the sole agent entry point.
 
+MCP search, timeline and show remain available above 5,000 rows. Reads page exact-project candidates and screen them before result selection. Search ranks the newest 5,000 permitted matching candidates per tier; `since` narrows that window. Timeline can anchor an older row directly. Capture MCP indexing is lazy on queried reads, never hook construction or append. Index contention uses a call-pinned substring fallback; later searches retry. See [MCP candidate reads](docs/contracts.md#mcp-candidate-reads-13-task-209) for the bounded-window and fallback contract.
+
 The frozen nine-tool contract for dotfiles#255 and maru#458:
 
 | Tool | Purpose |
@@ -252,7 +254,7 @@ The frozen nine-tool contract for dotfiles#255 and maru#458:
 | `amem_vault_candidates` | Read-only screened durable curated notes |
 | `amem_capacity` | Numeric machine capacity proposal; no apply capability |
 
-Search/show/timeline label capture as recall with `evidence: false`; capture never enters the curated graph. Policy screens complete rows before selection, limits or graph construction. The standalone secret screen, private flags, PII patterns and deny paths compose with a host's stricter policy through `createMemoryMcp({cwd, base, policy})`. Screening errors fail closed. `base` is the exact memory root; historical library `home` options still name its parent. Scope and profile changes refuse further access instead of silently reopening another store. Reads refuse above 5,000 rows per curated/capture tier; work-list reads use the same 5,000-entry scan ceiling. Count-first admission refuses an oversized work-list corpus before loading or parsing its fields, rather than returning an incomplete screened result. These are operational ceilings, not exposed counts of unscreened data. Graphs cover curated-note relationships, not goal/suggestion tables.
+Search/show/timeline label capture as recall with `evidence: false`; capture never enters the curated graph. Policy screens complete rows before selection, limits or graph construction. The standalone secret screen, private flags, PII patterns and deny paths compose with a host's stricter policy through `createMemoryMcp({cwd, base, policy})`. Screening errors fail closed. `base` is the exact memory root; historical library `home` options still name its parent. Scope and profile changes refuse further access instead of silently reopening another store. Graph reads retain the 5,000-row curated ceiling; work-list reads stream the complete ordered history without an operation-count ceiling, applying policy before latest-value reduction. The working state scales with the current result, not historical payloads. These are operational ceilings, not exposed counts of unscreened data. Graphs cover curated-note relationships, not goal/suggestion tables.
 
 `WorkListStore` writes `projects/<key-hash>/work/` with its own append log, derived index and lock. Scalar fields reduce by latest value, null clears, list status `done` closes, and item status is `todo|doing|done|dropped`. Work lists are outside generation selection and capture eviction. `amem import claude-mem` additionally imports `work_state_entries` only through persisted person-reviewed D2 aliases, preserving source DB bytes and stable replay receipts; JSON keeps observation fields and adds `work` counts/cursor.
 
@@ -262,7 +264,7 @@ Do not record vault links on a home shared with a host using published agent-mem
 
 General memory candidates are separate from curated evidence. `amem review accept <id> --kind memory --policy-free` remains person-only and rechecks the current standalone privacy policy before the accepted note append. Machine capacity reports numeric aggregate use across shards, as R7 requires; it does not return foreign project names or text.
 
-`bun scripts/measure-mcp-budget.ts` exercises an actual stdio session with 200 curated notes, 2,000 capture rows and 2,000 work-list operations reduced into 100 items. It checks the R3 idle RSS limit of 100 MB, peak RSS limit of 200 MB across searches and work-list reads, and child reaping after EOF. CI runs the harness on macOS and Linux. All harness data is synthetic; live P6 measurements remain separate.
+`bun scripts/measure-mcp-budget.ts` exercises an actual stdio session with 5,001 curated notes, 5,001 capture rows and 10,001 work-list operations reduced into 100 items. It checks the R3 idle RSS limit of 100 MB, peak RSS limit of 200 MB across searches, latest/anchored timelines and work-list reads, and child reaping after EOF. CI runs the harness on macOS and Linux. All harness data is synthetic; live P6 measurements remain separate.
 
 ## Development
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@staix/agent-mem",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Curated, shared memory for coding agents: append-only logs, a derived index, tiers and a typed graph.",
   "license": "MIT",
   "type": "module",

package/src/cli.ts

@@ -9,7 +9,7 @@ import { MemoryStore, looksSecret, machineId, openShardStore, type StoreOptions
 import { rawMemoryCommand, rawGoalCommand } from "./memory/commands.ts";
 import { memoryProjectKey } from "./memory/project.ts";
 import { CandidateStore, type CandidateFilter } from "./memory/candidates.ts";
-import { appendAlias, listAliases, readShardedSelection, resolveAlias } from "./memory/shard.ts";
+import { aliasedKeys, appendAlias, appendUnalias, listAliases, readShardedSelection, resolveAlias } from "./memory/shard.ts";
 import { capacityReport, capacityText } from "./memory/capacity.ts";
 import { readCaptureConfigFile, writeCaptureConfigFile, type CaptureConfig } from "./memory/capture.ts";
 
@@ -70,12 +70,15 @@ function shardStatePresent(): boolean {
   catch (error) { if ((error as NodeJS.ErrnoException).code === "ENOENT") return false; throw error; }
 }
 
-function curatedStore(project: string, opts: StoreOptions): MemoryStore {
+/** `reconciled` (#27): the project filter also covers every key aliased to `project`; prune and other planners keep the exact key. */
+function curatedStore(project: string, opts: StoreOptions, reconciled = true): MemoryStore {
+  const aliases = reconciled ? aliasedKeys(memoryHome(), project) : [];
+  const withAliases: StoreOptions = aliases.length ? { ...opts, reconcile: { canonical: project, aliases } } : opts;
   if (shardStatePresent()) {
     readShardedSelection(memoryHome());
-    return openShardStore({ ...opts, project });
+    return openShardStore({ ...withAliases, project });
   }
-  return new MemoryStore(opts);
+  return new MemoryStore(withAliases);
 }
 
 export async function runCli(argv: readonly string[], context: CliContext = {}): Promise<string> {
@@ -136,7 +139,7 @@ export async function runCli(argv: readonly string[], context: CliContext = {}):
     }
     const store = options["--user"] === true
       ? openShardStore({ memoryDir: memoryHome(), user: true, deferPromotions: true })
-      : curatedStore(project, { deferPromotions: true });
+      : curatedStore(project, { deferPromotions: true }, false);
     try {
       const auth = { project, actor: "person" as const, authorize: () => true };
       return JSON.stringify(applying ? applyPrune(store.prunePort(), input, auth) : planPrune(store.prunePort(), { cutoff: String(options["--cutoff"]) }, auth), null, 2);
@@ -148,7 +151,7 @@ export async function runCli(argv: readonly string[], context: CliContext = {}):
     if (sub === "list" && options["--kind"] !== "memory" && resolveProfile(memoryHome()).kind === "generation") throw new Error("candidate review is not yet integrated with this generation; select --kind memory for the standalone memory candidate surface");
     const id = parsed.positionals[0];
     if (sub !== "list" && (!id || !/^[a-f0-9]{64}$/.test(id))) throw new Error("review accept/reject requires a full 64-character candidate id");
-    const project = boundProject(), candidates = new CandidateStore();
+    const project = boundProject(), aliases = aliasedKeys(memoryHome(), project), candidates = new CandidateStore(aliases.length ? { reconcile: { canonical: project, aliases } } : {});
     try {
       if (sub === "list") {
         const rows = candidates.list({ project, ...(options["--status"] ? { status: options["--status"] as CandidateFilter["status"] } : {}),
@@ -219,8 +222,15 @@ export async function runCli(argv: readonly string[], context: CliContext = {}):
       const op = appendAlias(memoryHome(), { alias: from, key: to, actor: "person", machine: machineId(memoryHome()).id });
       return options["--json"] ? JSON.stringify(op, null, 2) : `alias ${op.alias} -> ${op.key}`;
     }
+    if (parsed.path[1] === "remove") {
+      // #27 option 2: person only (ordinary CLI refusal of agent markers above, a TTY through `mutates`), append only, the latest op wins.
+      const [from] = parsed.positionals;
+      if (!from || parsed.positionals.length !== 1) throw new Error("usage: amem alias remove <alias-key>");
+      const op = appendUnalias(memoryHome(), { alias: from, actor: "person", machine: machineId(memoryHome()).id });
+      return options["--json"] ? JSON.stringify(op, null, 2) : `alias ${op.alias} removed`;
+    }
     const ops = listAliases(memoryHome());
-    return options["--json"] ? JSON.stringify(ops, null, 2) : ops.length ? ops.map((op) => `${op.at}  ${op.alias} -> ${op.key}  (${op.actor})`).join("\n") : "no aliases recorded";
+    return options["--json"] ? JSON.stringify(ops, null, 2) : ops.length ? ops.map((op) => op.op === "alias" ? `${op.at}  ${op.alias} -> ${op.key}  (${op.actor})` : `${op.at}  ${op.alias} removed  (${op.actor})`).join("\n") : "no aliases recorded";
   }
   // ponytail: board task links need the host's authenticated task boundary; add a host bridge before supporting them here.
   if (goal && sub === "link") throw new Error("goal link needs host integration; use ahub goal link");

package/src/commands-table.ts

@@ -75,6 +75,7 @@ export const COMMANDS: Record<string, CommandDefinition> = {
   alias: { description: "Person-reviewed project key aliases (#15 D2)", options: json, defaultCommand: "list", commands: {
     list: { description: "List alias ops" },
     add: { description: "Map one key onto its canonical key (append-only op)", args: [{ name: "from-key" }, { name: "to-key" }], mutates: true },
+    remove: { description: "Remove an alias so the key resolves to itself again (append-only op, the latest wins)", args: [{ name: "alias-key" }], mutates: true },
   } },
   completion: { description: "Print static shell completion", args: [{ name: "shell", values: ["zsh", "bash", "fish"] }] },
   help: { description: "Show help" }, version: { description: "Show version" },

package/src/mcp-memory.ts

@@ -10,14 +10,17 @@ import { canonicalPath, realPath } from "./memory/platform.ts";
 import { createStandalonePolicy, type StandalonePolicyOptions } from "./memory/policy.ts";
 import { memoryProjectKey } from "./memory/project.ts";
 import { registerReaderLease } from "./memory/reader-lease.ts";
-import { SearchIndex } from "./memory/search-fts.ts";
-import { readShardedSelection, resolveAlias } from "./memory/shard.ts";
+import { type ReadRef, type ReadWindow, SearchIndex } from "./memory/search-fts.ts";
+import { aliasedKeys, readShardedSelection, resolveAlias } from "./memory/shard.ts";
 import { MemoryStore, openShardStore, type Graph, type View } from "./memory/store.ts";
 import { vaultCandidates } from "./memory/vault.ts";
 import { WorkListStore, type WorkListFields } from "./memory/work-lists.ts";
 
-// ponytail: 5000 rows per tier per operation; above this ceiling refuse rather than select on an incomplete privacy-filtered corpus. Upgrade to screened streaming pagination.
+// Graph retains its complete-corpus ceiling; search/timeline/show page matching bodies instead.
 export const MCP_SCAN_LIMIT = 5000;
+// ponytail: rank the newest 5000 permitted matching candidates per tier; use since to narrow or upgrade to a policy-bound persistent index for global ranking.
+const SEARCH_CANDIDATES = 5000;
+const READ_PAGE = 256;
 export interface MemoryMcpOptions { cwd: string; base?: string; project?: string; policy?: StandalonePolicyOptions }
 export interface MemoryMcp { tools: McpHandlers; close(): void }
 const unavailable = (): never => { throw new Error("memory operation unavailable"); };
@@ -27,7 +30,7 @@ const textOf = (args: Record<string, unknown>, key: string, optional = false): s
   const value = args[key]; if (value === undefined && optional) return undefined;
   return typeof value === "string" && value.trim() && !value.includes("\0") ? value : unavailable();
 };
-const sinceOf = (args: Record<string, unknown>): string | undefined => { const since = textOf(args, "since", true); if (since !== undefined && !Number.isFinite(Date.parse(since))) unavailable(); return since; };
+const sinceOf = (args: Record<string, unknown>): string | undefined => { const since = textOf(args, "since", true); if (since !== undefined && !Number.isFinite(Date.parse(since))) unavailable(); return since === undefined ? undefined : new Date(since).toISOString(); };
 
 /** All identities are resolved once. Per-call arguments cannot change projects, homes, profiles or policy. */
 export function createMemoryMcp(options: MemoryMcpOptions): MemoryMcp {
@@ -40,15 +43,17 @@ export function createMemoryMcp(options: MemoryMcpOptions): MemoryMcp {
     const selection = readSelector(base).revision;
     const sharded = !!lstatSync(join(base, "shards.json"), { throwIfNoEntry: false });
     const shardSelection = sharded ? JSON.stringify(readShardedSelection(base)) : undefined;
-    const store = sharded ? openShardStore({ memoryDir: base, project, deferPromotions: true }) : new MemoryStore({ memoryDir: base, deferPromotions: true });
+    // #27: the project filter covers the canonical key and every key aliased to it; the keys are fixed with the project, so a later alias change fails the guard below.
+    const aliases = aliasedKeys(base, project), reconcile = aliases.length ? { canonical: project, aliases } : undefined;
+    const store = sharded ? openShardStore({ memoryDir: base, project, deferPromotions: true, ...(reconcile ? { reconcile } : {}) }) : new MemoryStore({ memoryDir: base, deferPromotions: true, ...(reconcile ? { reconcile } : {}) });
     closers.push(() => store.close());
     const capture = new CaptureStore({ memoryDir: base, project }); closers.push(() => capture.close());
-    const candidates = new CandidateStore({ memoryDir: base }); closers.push(() => candidates.close());
-    const work = new WorkListStore({ base, project, policy: async row => { const permitted = await policy.screen(row); guard(); return permitted; } }); closers.push(() => work.close());
+    const candidates = new CandidateStore({ memoryDir: base, ...(reconcile ? { reconcile } : {}) }); closers.push(() => candidates.close());
+    const work = new WorkListStore({ base, project, aliases, policy: async row => { const permitted = await policy.screen(row); guard(); return permitted; } }); closers.push(() => work.close());
     const guard = () => {
       if (closed) unavailable();
       release.verify();
-      if (resolveAlias(base, requested) !== project || readSelector(base).revision !== selection) unavailable();
+      if (resolveAlias(base, requested) !== project || aliasedKeys(base, project).join("\n") !== aliases.join("\n") || readSelector(base).revision !== selection) unavailable();
       const split = !!lstatSync(join(base, "shards.json"), { throwIfNoEntry: false });
       if (split !== sharded || split && JSON.stringify(readShardedSelection(base)) !== shardSelection) unavailable();
     };
@@ -63,46 +68,84 @@ export function createMemoryMcp(options: MemoryMcpOptions): MemoryMcp {
       if (rows.length > MCP_SCAN_LIMIT) unavailable();
       return screen(rows.filter(row => row.project === project));
     };
-    const captures = async () => screen(capture.rows({ project, limit: MCP_SCAN_LIMIT + 1 }));
-    const find = (rows: View[], id: string): View | null => { const found = rows.filter(row => row.id === id || row.id.startsWith(id.replace(/^mem:/, ""))); return found.length === 1 ? found[0]! : null; };
+    const readPermitted = async <T>(read: (window: ReadWindow) => { rows: T[]; next?: ReadRef; engine?: "fts5" | "substring" },
+      options: Omit<ReadWindow, "project" | "limit" | "after">, cap: number, matches: (row: T, engine?: "fts5" | "substring") => boolean = () => true): Promise<T[]> => {
+      const result: T[] = []; let after: ReadWindow["after"];
+      while (result.length < cap) {
+        guard();
+        const page = read({ ...options, project, limit: READ_PAGE, after });
+        for (const row of page.rows) if (await policy.screen(row) && matches(row, page.engine)) {
+          result.push(row); if (result.length === cap) break;
+        }
+        guard();
+        if (!page.next) break;
+        after = { position: page.next.position, id: page.next.id };
+      }
+      return result;
+    };
+    const anchorAt = async (id: string): Promise<string | undefined> => {
+      if (/^capture:[1-9][0-9]*$/.test(id)) {
+        return (await readPermitted(window => capture.readPage(window), { id: id.slice(8) }, 1))[0]?.at;
+      }
+      const rows = await readPermitted(window => store.readPage({ ...window, includeSuperseded: true }), { prefix: id.replace(/^mem:/, "") }, 2);
+      return rows.length === 1 ? rows[0]!.at : undefined;
+    };
     const tools: McpHandlers = {
       async amem_search(args) {
         bound(args, ["query", "limit", "since", "includeCapture"]); const query = textOf(args, "query")!, limit = limitOf(args), since = sinceOf(args);
         if (args.includeCapture !== undefined && typeof args.includeCapture !== "boolean") unavailable();
         if (!await policy.screen({ query })) unavailable();
-        const notes = await curated(), recalls = args.includeCapture === false ? [] : await captures();
-        const hits = [...notes.map(view => ({ source: "curated" as const, evidence: true, view, ref: view.id, at: view.at, tier: view.tier, body: `${view.title ?? ""}\n${view.text}\n${view.about.join(" ")}` })),
-          ...recalls.map(row => ({ source: "capture" as const, evidence: false, capture: row, ref: `capture:${row.id}`, at: row.at, tier: "capture", body: `${row.excerpt}\n${row.paths.join(" ")}\n${row.event}` }))].filter(hit => !since || Date.parse(hit.at) >= Date.parse(since));
         const index = new SearchIndex(":memory:");
         try {
-          index.resync(() => hits.map(hit => ({ id: hit.ref, at: hit.at, project, tier: hit.tier, scope: "project", body: hit.body })));
-          if (index.available && index.needsResync(hits.length)) unavailable();
-          const ranks = new Map(index.query(query, MCP_SCAN_LIMIT * 2, project).map(row => [row.ref, row.rank]));
           const words = query.toLowerCase().split(/\s+/).filter(Boolean);
+          const captureState: { engine?: "fts5" | "substring" } = {};
+          const recalls = args.includeCapture === false ? [] : await readPermitted(window => {
+            const page = capture.readPage({ ...window, query, ...(captureState.engine === "substring" ? { match: "substring" as const } : {}) });
+            captureState.engine ??= page.engine;
+            return page;
+          }, { since }, SEARCH_CANDIDATES,
+            (row, engine) => index.available && engine === "fts5" || words.every(word => `${row.excerpt}\n${row.paths.join(" ")}\n${row.event}`.toLowerCase().includes(word)));
+          const useFts = index.available && captureState.engine !== "substring";
+          const notes = await readPermitted(window => store.readPage({ ...window, ...(useFts ? { query } : {}) }), { since }, SEARCH_CANDIDATES,
+            view => useFts || words.every(word => `${view.title ?? ""}\n${view.text}\n${view.about.join(" ")}`.toLowerCase().includes(word)));
+          const hits = [...notes.map(view => ({ source: "curated" as const, evidence: true, view, ref: view.id, at: view.at, tier: view.tier, body: `${view.title ?? ""}\n${view.text}\n${view.about.join(" ")}` })),
+            ...recalls.map(row => ({ source: "capture" as const, evidence: false, capture: row, ref: `capture:${row.id}`, at: row.at, tier: "capture", body: `${row.excerpt}\n${row.paths.join(" ")}\n${row.event}` }))].filter(hit => !since || Date.parse(hit.at) >= Date.parse(since));
+          if (useFts) {
+            index.resync(() => hits.map(hit => ({ id: hit.ref, at: hit.at, project, tier: hit.tier, scope: "project", body: hit.body })));
+            if (index.needsResync(hits.length)) unavailable();
+          }
+          const ranks = new Map((useFts ? index.query(query, MCP_SCAN_LIMIT * 2, project) : []).map(row => [row.ref, row.rank]));
           const selected = hits.flatMap(hit => {
             const rank = ranks.get(hit.ref);
-            if (index.available ? rank === undefined : !words.every(word => hit.body.toLowerCase().includes(word))) return [];
+            if (useFts ? rank === undefined : !words.every(word => hit.body.toLowerCase().includes(word))) return [];
             const weight = hit.tier === "long" ? 1 : hit.tier === "capture" ? 0.5 : 0.9;
             const score = -(rank ?? -1) * weight / (1 + Math.max(0, Date.now() - Date.parse(hit.at)) / (30 * 86400_000));
             return [{ source: hit.source, evidence: hit.evidence, ...(hit.source === "curated" ? { view: hit.view } : { capture: hit.capture }), score }];
           }).sort((a, b) => b.score - a.score).slice(0, limit);
-          guard(); return { engine: index.available ? "fts5" : "substring", hits: selected };
+          guard(); return { engine: useFts ? "fts5" : "substring", hits: selected };
         } finally { index.close(); }
       },
       async amem_show(args) {
         bound(args, ["id"]); guard(); const id = textOf(args, "id")!;
-        if (/^capture:[1-9][0-9]*$/.test(id)) { const row = (await captures()).find(row => `capture:${row.id}` === id); guard(); return row ? { source: "capture", evidence: false, capture: row } : null; }
-        const result = find(await curated(true), id); guard(); return result;
+        if (/^capture:[1-9][0-9]*$/.test(id)) {
+          const row = (await readPermitted(window => capture.readPage(window), { id: id.slice(8) }, 1))[0];
+          guard(); return row ? { source: "capture", evidence: false, capture: row } : null;
+        }
+        const rows = await readPermitted(window => store.readPage({ ...window, includeSuperseded: true }), { prefix: id.replace(/^mem:/, "") }, 2);
+        guard(); return rows.length === 1 ? rows[0]! : null;
       },
       async amem_timeline(args) {
-        bound(args, ["id", "since", "limit"]); const rows = await curated(true), recalls = await captures(), id = textOf(args, "id", true), since = sinceOf(args), limit = limitOf(args);
-        const entries = [...rows.map(row => ({ at: row.at, value: row as unknown })), ...recalls.map(row => ({ at: row.at, value: { source: "capture", evidence: false, capture: row } as unknown }))];
-        let selected = entries.filter(row => !since || Date.parse(row.at) >= Date.parse(since));
-        if (id) {
-          const anchor = id.startsWith("capture:") ? recalls.find(row => `capture:${row.id}` === id) : find(rows, id);
-          if (!anchor) return []; selected = selected.sort((a, b) => Math.abs(Date.parse(a.at) - Date.parse(anchor.at)) - Math.abs(Date.parse(b.at) - Date.parse(anchor.at)));
-        } else selected.sort((a, b) => b.at.localeCompare(a.at));
-        guard(); return selected.slice(0, limit).map(row => row.value);
+        bound(args, ["id", "since", "limit"]);
+        const id = textOf(args, "id", true), since = sinceOf(args), limit = limitOf(args);
+        guard();
+        const anchor = id ? await anchorAt(id) : undefined;
+        if (id && !anchor) { guard(); return []; }
+        const rows = await readPermitted(window => store.readPage({ ...window, includeSuperseded: true }), { since, anchor }, limit);
+        const recalls = await readPermitted(window => capture.readPage(window), { since, anchor }, limit);
+        const entries = [...rows.map(row => ({ at: row.at, ref: row.id, value: row as unknown })),
+          ...recalls.map(row => ({ at: row.at, ref: `capture:${row.id}`, value: { source: "capture", evidence: false, capture: row } as unknown }))];
+        entries.sort((a, b) => (anchor ? Math.abs(Date.parse(a.at) - Date.parse(anchor)) - Math.abs(Date.parse(b.at) - Date.parse(anchor)) : Date.parse(b.at) - Date.parse(a.at)) || (a.ref < b.ref ? -1 : a.ref > b.ref ? 1 : 0));
+        guard(); return entries.slice(0, limit).map(row => row.value);
       },
       async amem_graph(args) {
         bound(args, ["start", "hops", "limit"]); const start = textOf(args, "start")!, cap = limitOf(args), hops = args.hops ?? 1;

package/src/memory/candidates.ts

@@ -76,7 +76,11 @@ export class CandidateStore {
   readonly path: string;
   private readonly db: Database;
   private readonly now: () => number;
-  constructor(options: { home?: string; memoryDir?: string; now?: () => number } = {}) {
+  /** #27: the keys aliased to the canonical project; its candidates read, accept and reject under the canonical key. Absent in the library default. */
+  private readonly reconcile?: { canonical: string; aliases: readonly string[] };
+  private scope(project: string): string { return JSON.stringify(this.reconcile && project === this.reconcile.canonical ? [project, ...this.reconcile.aliases] : [project]); }
+  constructor(options: { home?: string; memoryDir?: string; now?: () => number; reconcile?: { canonical: string; aliases: readonly string[] } } = {}) {
+    if (options.reconcile?.aliases.length) this.reconcile = { canonical: options.reconcile.canonical, aliases: [...options.reconcile.aliases] };
     if (options.memoryDir !== undefined && options.home !== undefined) throw new Error("choose a home or an exact memory directory");
     this.dir = options.memoryDir ?? (options.home === undefined ? memoryHome() : join(options.home, "memory"));
     this.now = options.now ?? Date.now;
@@ -112,7 +116,7 @@ export class CandidateStore {
   get(id: string, project: string): Candidate | undefined {
     if (!candidateId(id) || !text(project, 400)) throw new Error("invalid candidate identity");
     this.prune();
-    const row = this.db.query("SELECT * FROM candidates WHERE id = ? AND project = ?").get(id, project) as Parameters<CandidateStore["decode"]>[0] | null;
+    const row = this.db.query("SELECT * FROM candidates WHERE id = ? AND project IN (SELECT value FROM json_each(?))").get(id, this.scope(project)) as Parameters<CandidateStore["decode"]>[0] | null;
     return row ? this.decode(row) : undefined;
   }
   list(filter: CandidateFilter): Candidate[] {
@@ -120,7 +124,7 @@ export class CandidateStore {
     const limit = filter.limit ?? CANDIDATE_RETENTION.count;
     if (!Number.isSafeInteger(limit) || limit < 1 || limit > CANDIDATE_RETENTION.count) throw new Error("candidate limit must be 1..500");
     this.prune();
-    const where = ["project = ?"], bind: (string | number)[] = [filter.project];
+    const where = ["project IN (SELECT value FROM json_each(?))"], bind: (string | number)[] = [this.scope(filter.project)];
     if (filter.status === undefined) where.push("status IN ('pending', 'accepting')"); else if (filter.status !== "all") { where.push("status = ?"); bind.push(filter.status); }
     if (filter.kind) { where.push("kind = ?"); bind.push(filter.kind); }
     return (this.db.query(`SELECT * FROM candidates WHERE ${where.join(" AND ")} ORDER BY at DESC, rowid DESC LIMIT ?`).all(...bind, limit) as Parameters<CandidateStore["decode"]>[0][]).map(row => this.decode(row));
@@ -137,7 +141,7 @@ export class CandidateStore {
   counters(project: string, entry?: string): Counter[] {
     if (!text(project, 400) || entry !== undefined && !entryId(entry)) throw new Error("invalid counter filter");
     this.prune();
-    const rows = this.db.query("SELECT * FROM counters WHERE project = ? ORDER BY at DESC, rowid DESC").all(project) as { id: string; payload: string; at: number; rendered: number | null; delivered: number | null; cited: number | null }[];
+    const rows = this.db.query("SELECT * FROM counters WHERE project IN (SELECT value FROM json_each(?)) ORDER BY at DESC, rowid DESC").all(this.scope(project)) as { id: string; payload: string; at: number; rendered: number | null; delivered: number | null; cited: number | null }[];
     return rows.map(row => ({ id: row.id, key: JSON.parse(row.payload) as CounterKey, createdAt: new Date(row.at).toISOString(), rendered: row.rendered, delivered: row.delivered, cited: row.cited })).filter(row => !entry || row.key.entryId === entry);
   }
   reject(id: string, context: { project: string; actor: "person" | "agent"; verdict: CandidateVerdict }): void {
@@ -146,7 +150,7 @@ export class CandidateStore {
       const candidate = this.get(id, context.project);
       if (!candidate) throw new Error("candidate unavailable");
       if (candidate.status === "accepted" || candidate.status === "accepting") throw new Error("candidate acceptance already started; inspect its ordinary note before any further action");
-      this.db.query("UPDATE candidates SET status = 'rejected' WHERE id = ? AND project = ? AND status = 'pending'").run(id, context.project);
+      this.db.query("UPDATE candidates SET status = 'rejected' WHERE id = ? AND project IN (SELECT value FROM json_each(?)) AND status = 'pending'").run(id, this.scope(context.project));
     }).immediate();
   }
   accept(id: string, context: CandidateAcceptance): CandidateAcceptanceResult {
@@ -185,7 +189,7 @@ export class CandidateStore {
         if (!current) throw new Error("candidate unavailable");
         if (current.status === "accepted") return current.acceptedNoteId!;
         if (current.status !== "pending") throw new Error("candidate is rejected or acceptance was interrupted; no automatic replay");
-        this.db.query("UPDATE candidates SET status = 'accepting' WHERE id = ? AND project = ?").run(id, context.project);
+        this.db.query("UPDATE candidates SET status = 'accepting' WHERE id = ? AND project IN (SELECT value FROM json_each(?))").run(id, this.scope(context.project));
         return undefined;
       }).immediate();
       if (started) return { candidateId: id, noteId: started, alreadyAccepted: true };
@@ -193,7 +197,7 @@ export class CandidateStore {
       // automatic replay; add explicit person-audited recovery before offering background acceptance retries.
       const noteId = append();
       if (data.kind === "correction" && !context.store.supersede(target!.id, noteId, "person", context.project)) throw new Error("candidate replacement refused; inspect the accepted note before recovery");
-      this.db.query("UPDATE candidates SET status = 'accepted', note_id = ? WHERE id = ? AND project = ?").run(noteId, id, context.project);
+      this.db.query("UPDATE candidates SET status = 'accepted', note_id = ? WHERE id = ? AND project IN (SELECT value FROM json_each(?))").run(noteId, id, this.scope(context.project));
       return { candidateId: id, noteId, alreadyAccepted: false };
     });
   }

package/src/memory/capture.ts

@@ -1,13 +1,13 @@
 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, 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 { memoryBase } from "./home.ts";
 import { captureShardDir, ensureShardDescriptor, resolveAlias } from "./shard.ts";
 import { machineId } from "./store.ts";
-import { fts5Available } from "./search-fts.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 +25,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
@@ -50,6 +50,13 @@ 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;
@@ -182,7 +189,7 @@ 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();
@@ -239,7 +246,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 +267,29 @@ 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 (!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");
   }
@@ -306,35 +342,79 @@ export class CaptureStore {
   }
 
   private spool(row: NormalizedCapture): void {
-    appendFileSync(join(this.dir, SPOOL), JSON.stringify({ ...row, nonce: randomBytes(4).toString("hex") }) + "\n", { mode: 0o600 });
+    this.spoolRaw(JSON.stringify({ ...row, nonce: randomBytes(12).toString("hex") }));
   }
 
   /**
-   * 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;
+    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 +436,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 };
   }
@@ -424,6 +508,19 @@ export class CaptureStore {
     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" } {
+    const { columns, where, bind } = readWindowSql(window, "id");
+    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 } {
     let fileBytes = 0;
     try { fileBytes = statSync(join(this.dir, "capture.db")).size; } catch { /* not created yet */ }