rovecode 0.3.2

package/src/memory/blocks.ts

@@ -0,0 +1,278 @@
+/** Bounded markdown memory blocks (hermes pattern): MEMORY.md + USER.md with hard char caps.
+ *  The snapshot is frozen at boot (constructor) so the system prompt stays cache-stable and
+ *  byte-identical across the turns of a run; tools mutate live state + disk only — an edit is in the
+ *  prompt from the NEXT run. A threat-scan neutralizes injection lines in the rendered view — raw text
+ *  on disk is never rewritten by the scan.
+ *
+ *  Scoping (2026-09-07): the two blocks may live in DIFFERENT directories (`BlockDirs` — MEMORY under
+ *  the project's .rovecode, USER under the user home; memory/scope.ts resolves them), because a USER
+ *  block written inside a repository is the wrong file in the wrong place. A plain string keeps both in
+ *  one dir. Directories are created lazily by the first commit (the ledger's write), so constructing a
+ *  store over the user scope never touches the home directory.
+ *
+ *  A block file is REPO DATA — `<cwd>/.rovecode/memory/MEMORY.md` is committable — so the boot read is
+ *  bounded twice: at most READ_CAP_BYTES are read from disk (a longer file marks the block read-cut and
+ *  every commit/rollback is refused — the store never rewrites a file it could not read whole), and the
+ *  PROMPT view is cut at the block's char cap (line boundary) behind a visible `[truncated: …]` marker,
+ *  so the prompt cannot balloon whatever the file holds; the live text (/memory, the tools) is what was
+ *  read. A block may also be WITHHELD (`BlockStoreOptions.withhold`): read as usual, kept out of the
+ *  prompt — memory/scope.ts withholds a project MEMORY block this machine has not approved. */
+
+import { closeSync, existsSync, openSync, readSync } from "node:fs";
+import { join } from "node:path";
+import { TRUST_HINT } from "../core/trust.ts";
+import { VersionLedger } from "../skills/versioned.ts";
+
+export type BlockName = "memory" | "user";
+
+/** the directory each block's file (+ its `.versions.jsonl` ledger sidecar) lives in */
+export type BlockDirs = Record<BlockName, string>;
+
+/** the block file names — the ONE place that spells them (memory/scope.ts copies them by these names) */
+export const BLOCK_FILES: Readonly<Record<BlockName, string>> = { memory: "MEMORY.md", user: "USER.md" };
+
+export interface BlockCaps { memory: number; user: number }
+
+export const defaultCaps: BlockCaps = { memory: 2_200, user: 1_375 };
+
+/** the most a block file is read at boot (bytes); past it the block is read-cut: shown cut, never rewritten */
+export const READ_CAP_BYTES = 64 * 1024;
+
+export interface BlockStoreOptions {
+  /** blocks read from disk but KEPT OUT of the prompt (a project MEMORY block this machine has not
+   *  approved); live text and /memory see them as usual, and every WRITE to them is refused — appending
+   *  our own note to a stranger's file would launder its content into the next prompt */
+  withhold?: readonly BlockName[];
+  /** called after a write THIS store performed landed on disk (commit or rollback), with the block and its
+   *  file. memory/scope.ts uses it to keep the project block's trust digest current: the narrow self-trust —
+   *  a file we just wrote, never "the file looks close enough". Never called for a refused write. */
+  onCommit?: (block: BlockName, file: string) => void;
+}
+
+export interface BlockEditResult {
+  ok: boolean;
+  reason?: string;
+  /** present on cap failures: current chars / cap */
+  current?: number;
+  limit?: number;
+  /** present on version conflicts: ledger numbers for logs/data surfaces only —
+   *  the model-facing `reason` stays generic (ouroboros: no ledger internals). */
+  conflict?: { baseVersion: number; currentVersion: number };
+}
+
+/** Model-facing conflict reason — deliberately free of ledger internals. */
+export const CONFLICT_REASON = "memory changed since it was read — re-read and retry";
+
+const THREAT = /(?:ignore previous|disregard above|system prompt)/i;
+
+function scan(text: string): string {
+  return text.split("\n").map((l) => (THREAT.test(l) ? "[BLOCKED]" : l)).join("\n");
+}
+
+/** `text` cut to at most `cap` chars at a line boundary (a hard cut when the last newline sits in the first half) */
+export function cutAtCap(text: string, cap: number): string {
+  if (text.length <= cap) return text;
+  let cut = text.lastIndexOf("\n", cap);
+  if (cut < cap / 2) cut = cap;
+  return text.slice(0, cut);
+}
+
+/** at most `cap + 1` bytes of `p` (existence checked by the caller): the text and whether the file went on past the cap */
+function readBounded(p: string, cap: number): { text: string; cut: boolean } {
+  const fd = openSync(p, "r");
+  try {
+    const buf = Buffer.alloc(cap + 1);
+    let n = 0;
+    while (n < buf.length) { const got = readSync(fd, buf, n, buf.length - n, n); if (got <= 0) break; n += got; }
+    return { text: buf.subarray(0, Math.min(n, cap)).toString("utf8"), cut: n > cap };
+  } finally { closeSync(fd); }
+}
+
+function occurrences(haystack: string, needle: string): number {
+  if (!needle) return 0;
+  let n = 0;
+  let i = 0;
+  while ((i = haystack.indexOf(needle, i)) !== -1) { n++; i += needle.length; }
+  return n;
+}
+
+export class BlockStore {
+  private live: Record<BlockName, string> = { memory: "", user: "" };
+  private readonly frozen: Record<BlockName, string>;
+  /** port #16: versioned edits — every commit lands through a sidecar ledger
+   *  (<file>.versions.jsonl), enabling one-call rollback + drift detection. */
+  private readonly ledgers: Record<BlockName, VersionLedger>;
+  /** Optimistic-concurrency baseline (prime baselineState, refinement.ts:735-749):
+   *  the version THIS store last saw. Passing ledger.version() to commit would
+   *  compare the guard to itself and silently drop a concurrent store's edit. */
+  private readonly baseVersions: Record<BlockName, number>;
+
+  private readonly dirs: BlockDirs;
+  /** the block's file went on past READ_CAP_BYTES at boot — shown cut, never rewritten */
+  private readonly readCut: Record<BlockName, boolean> = { memory: false, user: false };
+  private readonly withheld: ReadonlySet<BlockName>;
+  private readonly onCommit: ((block: BlockName, file: string) => void) | undefined;
+
+  /** `dir`: one directory for both blocks, or a per-block map (the scoped layout). Nothing is created here. */
+  constructor(
+    dir: string | BlockDirs,
+    private readonly caps: BlockCaps = defaultCaps,
+    opts: BlockStoreOptions = {},
+  ) {
+    // no mkdir here: reads tolerate a missing directory and the ledger creates it on the first commit
+    // (skills/versioned.ts). Creating `<session>/memory` at construction was what made every session
+    // directory non-empty before anyone had said anything (core/session.ts materialize()).
+    this.dirs = typeof dir === "string" ? { memory: dir, user: dir } : { memory: dir.memory, user: dir.user };
+    this.withheld = new Set(opts.withhold ?? []);
+    this.onCommit = opts.onCommit;
+    this.live.memory = this.read("memory");
+    this.live.user = this.read("user");
+    // snapshot is the threat-scanned view of what boot loaded
+    this.frozen = { memory: scan(this.live.memory), user: scan(this.live.user) };
+    this.ledgers = {
+      memory: new VersionLedger(this.file("memory")),
+      user: new VersionLedger(this.file("user")),
+    };
+    this.baseVersions = { memory: this.ledgers.memory.version(), user: this.ledgers.user.version() };
+  }
+
+  /** the bounded boot read (header): at most READ_CAP_BYTES; a longer file marks the block read-cut */
+  private read(block: BlockName): string {
+    const p = this.file(block);
+    if (!existsSync(p)) return "";
+    const r = readBounded(p, READ_CAP_BYTES);
+    this.readCut[block] = r.cut;
+    return r.text;
+  }
+
+  private file(block: BlockName): string {
+    return join(this.dirs[block], BLOCK_FILES[block]);
+  }
+
+  /** the block's file path (where edits land) — for notes, /memory and tests. */
+  path(block: BlockName): string { return this.file(block); }
+
+  add(block: BlockName, text: string): BlockEditResult {
+    const t = text.trim();
+    if (!t) return { ok: false, reason: "empty text" };
+    const next = this.live[block] ? this.live[block] + "\n" + t : t;
+    return this.commit(block, next);
+  }
+
+  replace(block: BlockName, oldText: string, newText: string): BlockEditResult {
+    const found = this.locate(block, oldText);
+    if (!found.ok) return found;
+    const t = newText.trim();
+    const next = t ? this.live[block].replace(oldText, t) : this.live[block].replace(oldText, "");
+    return this.commit(block, next.trim());
+  }
+
+  remove(block: BlockName, oldText: string): BlockEditResult {
+    const found = this.locate(block, oldText);
+    if (!found.ok) return found;
+    const next = this.live[block].replace(oldText, "").replace(/\n{3,}/g, "\n\n").trim();
+    return this.commit(block, next);
+  }
+
+  /** oldText must match exactly once: 0 → not found, >1 → ambiguous. */
+  private locate(block: BlockName, oldText: string): BlockEditResult {
+    if (!oldText) return { ok: false, reason: "oldText required" };
+    const n = occurrences(this.live[block], oldText);
+    if (n === 0) return { ok: false, reason: "oldText not found" };
+    if (n > 1) return { ok: false, reason: `oldText matches ${n} times; must match exactly once` };
+    return { ok: true };
+  }
+
+  /** Char-cap guard shared by commit() and rollback(); runs BEFORE any ledger write. A read-cut block
+   *  (header) refuses every write: the store never rewrites a file it could not read whole. */
+  private capCheck(block: BlockName, next: string): BlockEditResult | null {
+    const limit = this.caps[block];
+    if (this.withheld.has(block)) {
+      return { ok: false, reason: `${BLOCK_FILES[block]} came with this repository and is not approved on this machine — it is not in the prompt and cannot be written to (${TRUST_HINT})`, current: this.live[block].length, limit };
+    }
+    if (this.readCut[block]) {
+      return { ok: false, reason: `${BLOCK_FILES[block]} on disk is longer than the ${READ_CAP_BYTES}-byte read cap — trim it by hand before editing`, current: this.live[block].length, limit };
+    }
+    if (next.length <= limit) return null;
+    return {
+      ok: false, reason: `block would exceed cap (${next.length} > ${limit} chars)`,
+      current: this.live[block].length, limit,
+    };
+  }
+
+  private commit(block: BlockName, next: string): BlockEditResult {
+    const capped = this.capCheck(block, next);
+    if (capped) return capped;
+    // ledger-first write (port #16): version record appended, then the target
+    // is written atomically by the ledger — never writeFileSync directly. The
+    // baseline is what THIS store last saw, so a concurrent store's commit is
+    // caught here instead of being silently overwritten.
+    const r = this.ledgers[block].commit(next, "memory_edit", this.baseVersions[block]);
+    if (!r.ok) {
+      // conflict: another store/process advanced the block. Re-read reality so
+      // the next edit builds on the merged state; the reason stays generic —
+      // ledger numbers ride the structured field only.
+      this.live[block] = this.ledgers[block].read();
+      this.baseVersions[block] = r.currentVersion;
+      return {
+        ok: false, reason: CONFLICT_REASON,
+        conflict: { baseVersion: r.baseVersion, currentVersion: r.currentVersion },
+      };
+    }
+    this.baseVersions[block] = r.edit.version;
+    this.live[block] = next;
+    this.onCommit?.(block, this.file(block)); // the write landed and it was ours (memory/scope.ts self-trust)
+    return { ok: true, current: next.length, limit: this.caps[block] };
+  }
+
+  /** port #16: one-call rollback of a block to any retained version.
+   *  Restored content re-enters through the same cap guard as commits. */
+  rollback(block: BlockName, toVersion: number): BlockEditResult {
+    const restored = this.ledgers[block].contentAt(toVersion);
+    const capped = restored !== undefined ? this.capCheck(block, restored) : null;
+    if (capped) return capped;
+    const r = this.ledgers[block].rollback(toVersion, "memory_rollback");
+    if (!r.ok) return { ok: false, reason: r.message };
+    this.baseVersions[block] = r.edit.version;
+    this.live[block] = this.ledgers[block].read();
+    this.onCommit?.(block, this.file(block)); // a rollback rewrites the file too — same self-trust
+    return { ok: true, current: this.live[block].length, limit: this.caps[block] };
+  }
+
+  /** port #16: version history access for status/debug surfaces. */
+  ledger(block: BlockName): VersionLedger { return this.ledgers[block]; }
+
+  /** the prompt text of one block: the boot snapshot, cut at the block's cap (header) behind a visible marker */
+  private promptView(block: BlockName): string {
+    const text = this.frozen[block], cap = this.caps[block];
+    if (text.length <= cap && !this.readCut[block]) return text;
+    const size = this.readCut[block] ? `more than ${READ_CAP_BYTES} bytes` : `${this.live[block].length} chars`;
+    return `${cutAtCap(text, cap)}\n[truncated: ${BLOCK_FILES[block]} holds ${size}; the first ${cap} chars are shown — trim the file]`;
+  }
+
+  /** Boot snapshot (threat-scanned, cut at the cap; withheld blocks absent). Tool writes never change it. */
+  renderForPrompt(): string {
+    const parts: string[] = [];
+    if (this.frozen.memory && !this.withheld.has("memory")) parts.push(`# Memory\n${this.promptView("memory")}`);
+    if (this.frozen.user && !this.withheld.has("user")) parts.push(`# User\n${this.promptView("user")}`);
+    return parts.join("\n\n");
+  }
+
+  /** Live (post-snapshot) raw text — for reads/debug, not for the prompt. */
+  liveText(block: BlockName): string { return this.live[block]; }
+
+  /** true when the block's live text no longer matches the boot snapshot the prompt shows
+   *  (an edit this run — the prompt picks it up on the next run). */
+  edited(block: BlockName): boolean { return scan(this.live[block]) !== this.frozen[block]; }
+
+  cap(block: BlockName): number { return this.caps[block]; }
+
+  /** the block's boot read against its cap — null when it fits; `readCut` = the file went past READ_CAP_BYTES */
+  overCap(block: BlockName): { chars: number; cap: number; readCut: boolean } | null {
+    if (this.live[block].length <= this.caps[block] && !this.readCut[block]) return null;
+    return { chars: this.live[block].length, cap: this.caps[block], readCut: this.readCut[block] };
+  }
+
+  /** true when the block is read (live, /memory, memory_edit) but kept out of the prompt (an unapproved project file) */
+  isWithheld(block: BlockName): boolean { return this.withheld.has(block); }
+}

package/src/memory/recall.ts

@@ -0,0 +1,355 @@
+/** Cross-session recall (port #17): tokenized full-text search over
+ *  `.rovecode/sessions/<id>/entries.jsonl` message text, exposed as a `recall` tool.
+ *
+ *  Ported from hermes-agent's session search (MIT), adapted from SQLite FTS5 to an
+ *  in-memory inverted index over the JSONL session tree:
+ *  - Index = tokenized message content, maintained incrementally; hermes keeps an
+ *    external-content FTS5 table in sync via insert triggers + high-water/progress
+ *    markers so only unindexed rows are (re)indexed (hermes_state_common.py:637-684,
+ *    hermes_state_search.py:280-346 fts_rebuild_step). Here the incremental unit is
+ *    the session FILE, keyed by mtime (+size guard): only changed files re-index.
+ *  - Ranking tiers = hermes's routing: exact tokenized FTS5 match is the primary
+ *    path, substring (trigram) matching is the fallback tier
+ *    (hermes_state_search.py:1467-1489 _describe_search_path, 1846-1885 routing);
+ *    within a tier hermes orders by BM25 `ORDER BY rank` with timestamp tiebreaks
+ *    (hermes_state_search.py:1791-1798). Here: exact-term count desc, then weighted
+ *    term frequency, then recency. Query terms are implicitly ANDed, matching FTS5
+ *    (tools/session_search_tool.py:807-809).
+ *  - Partial matches need terms >=3 chars, mirroring trigram eligibility
+ *    (hermes_state_search.py:1322-1337 _trigram_eligible_tokens).
+ *  - Hits are snippet + metadata only, never full content
+ *    (hermes_state_search.py:1694-1701, 1827-1844); preview = 120-char window
+ *    starting 40 before the first match, the LIKE-fallback snippet shape
+ *    (hermes_state_search.py:1585-1595).
+ *  - Result budget: limit clamped like hermes's max(1, min(limit, 10))
+ *    (tools/session_search_tool.py:1040-1046).
+ *  - NO LLM anywhere in the search path (tools/session_search_tool.py:25-33 — the
+ *    historical "summary mode" was removed upstream); summarization is an optional
+ *    injected fn here, off by default.
+ *  - Trust boundary: previews get the same per-line injection neutralization as
+ *    BlockStore (blocks.ts:24-27) — threat lines render as [BLOCKED]; disk is never
+ *    rewritten. The query echo in tool output is bounded to MAX_QUERY_CHARS.
+ */
+
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+import type { Tool, ToolContext, ToolOutput } from "../core/types.ts";
+
+/** Ranked hit — the bar's exact shape. Preview only; full text stays on disk. */
+export interface RecallHit { sessionId: string; entryId: string; preview: string; timestamp: number }
+
+/** Optional post-search summarizer (LLM or otherwise) — injected, never required. */
+export type SummarizeFn = (query: string, hits: RecallHit[]) => Promise<string> | string;
+
+export interface RefreshStats { scanned: number; indexed: number; removed: number }
+
+const MAX_RESULTS = 10;      // hermes limit ceiling (session_search_tool.py:1046)
+const DEFAULT_RESULTS = 5;
+const PREVIEW_WINDOW = 120;  // hermes LIKE-fallback snippet width (hermes_state_search.py:1587)
+const PREVIEW_LEAD = 40;     // window starts 40 chars before the match (same line)
+const MIN_PARTIAL_TERM = 3;  // trigram eligibility (hermes_state_search.py:1322-1337)
+const MAX_QUERY_CHARS = 512; // bounded adversarial input (hermes MAX_FTS5_QUERY_CHARS, hermes_state_search.py:1199-1201)
+const EXACT_WEIGHT = 2;
+const PARTIAL_WEIGHT = 1;
+
+/** unicode61-style tokenization (hermes's base FTS5 index): case-fold, split on
+ *  anything that is not a letter or digit. */
+export function tokenize(text: string): string[] {
+  return text.toLowerCase().split(/[^\p{L}\p{N}]+/u).filter((t) => t.length > 0);
+}
+
+interface Doc {
+  sessionId: string;
+  entryId: string;
+  text: string;
+  timestamp: number;
+  tokens: Map<string, number>; // token -> tf (kept for O(tokens) removal on re-index)
+}
+
+interface FileState { mtimeMs: number; size: number; docKeys: string[] }
+
+/** One session-entry line, already filtered to message text. */
+function parseLine(line: string): { entryId: string; text: string; timestamp: number } | null {
+  let raw: unknown;
+  try { raw = JSON.parse(line); } catch { return null; } // malformed lines: skip, never throw (session.ts reload pattern)
+  if (!raw || typeof raw !== "object") return null;
+  const w = raw as { id?: unknown; createdAt?: unknown; entry?: unknown };
+  if (typeof w.id !== "string") return null;
+  const e = w.entry;
+  // events (kind:"event") and non-message shapes are not "message text" — skip
+  if (!e || typeof e !== "object" || !("role" in e)) return null;
+  const parts = (e as { parts?: unknown }).parts;
+  if (!Array.isArray(parts)) return null;
+  const texts: string[] = [];
+  for (const p of parts) {
+    if (p && typeof p === "object"
+      && (p as { kind?: unknown }).kind === "text"
+      && typeof (p as { text?: unknown }).text === "string") {
+      texts.push((p as { text: string }).text);
+    }
+  }
+  const text = texts.join(" ").trim();
+  if (!text) return null; // tool_call/tool_result-only messages carry no text parts
+  return { entryId: w.id, text, timestamp: typeof w.createdAt === "number" ? w.createdAt : 0 };
+}
+
+/** Recalled transcript text sits at the SAME trust level as BlockStore markdown:
+ *  text a past model/user wrote, re-entering a live context. Local copy of the
+ *  blocks.ts:24-27 neutralization — any line matching the injection pattern
+ *  renders as [BLOCKED]; the raw text on disk is never rewritten. */
+const THREAT = /(?:ignore previous|disregard above|system prompt)/i;
+function neutralize(text: string): string {
+  return text.split("\n").map((l) => (THREAT.test(l) ? "[BLOCKED]" : l)).join("\n");
+}
+
+/** Slicing by UTF-16 unit can strand half of a surrogate pair at either cut —
+ *  drop a leading low / trailing high orphan so emitted text stays well-formed. */
+function trimOrphanSurrogates(s: string): string {
+  const head = s.charCodeAt(0); // NaN on empty: both range checks are false
+  if (head >= 0xdc00 && head <= 0xdfff) s = s.slice(1);
+  const tail = s.charCodeAt(s.length - 1);
+  if (tail >= 0xd800 && tail <= 0xdbff) s = s.slice(0, -1);
+  return s;
+}
+
+/** Single-line preview: 120-char window starting 40 before the first matched term
+ *  (hermes_state_search.py:1585-1595). Ellipses mark clipping. */
+function makePreview(text: string, terms: string[]): string {
+  const flat = text.replace(/\s+/g, " ").trim();
+  const lower = flat.toLowerCase();
+  let pos = -1;
+  for (const t of terms) {
+    const i = lower.indexOf(t);
+    if (i !== -1 && (pos === -1 || i < pos)) pos = i;
+  }
+  const start = pos === -1 ? 0 : Math.max(0, pos - PREVIEW_LEAD);
+  const clip = trimOrphanSurrogates(flat.slice(start, start + PREVIEW_WINDOW));
+  return (start > 0 ? "…" : "") + clip + (start + PREVIEW_WINDOW < flat.length ? "…" : "");
+}
+
+/** Inverted index over every session's entries.jsonl. Incremental: a file is
+ *  re-read only when its mtime (or size — appends always grow JSONL) changed;
+ *  deleted session dirs drop out. Session identity = the DIRECTORY name, matching
+ *  session.ts listSessions (a tampered meta.json must not redirect recall). */
+export class RecallIndex {
+  private docs = new Map<string, Doc>();                    // docKey -> doc
+  private postings = new Map<string, Map<string, number>>(); // token -> docKey -> tf
+  private files = new Map<string, FileState>();              // sessionId -> file state
+
+  constructor(private readonly root: string) {}
+
+  /** Stat every session file; (re)index changed/new ones, drop vanished ones. */
+  refresh(): RefreshStats {
+    const stats: RefreshStats = { scanned: 0, indexed: 0, removed: 0 };
+    let names: string[] = [];
+    try { names = readdirSync(this.root); } catch { /* missing root = empty index */ }
+    const live = new Set<string>();
+    for (const name of names) {
+      const file = join(this.root, name, "entries.jsonl");
+      let st: { mtimeMs: number; size: number };
+      try { const s = statSync(file); st = { mtimeMs: s.mtimeMs, size: s.size }; }
+      catch { continue; } // foreign dir / no entries yet: skip, never throw
+      live.add(name);
+      stats.scanned++;
+      const prev = this.files.get(name);
+      if (prev && prev.mtimeMs === st.mtimeMs && prev.size === st.size) continue; // unchanged: keyed by mtime
+      this.dropSession(name);
+      this.indexFile(name, file, st);
+      stats.indexed++;
+    }
+    for (const name of [...this.files.keys()]) {
+      if (!live.has(name)) { this.dropSession(name); stats.removed++; }
+    }
+    return stats;
+  }
+
+  private dropSession(sessionId: string): void {
+    const prev = this.files.get(sessionId);
+    if (!prev) return;
+    for (const key of prev.docKeys) {
+      const doc = this.docs.get(key);
+      if (doc) {
+        for (const token of doc.tokens.keys()) {
+          const posting = this.postings.get(token);
+          if (posting) { posting.delete(key); if (posting.size === 0) this.postings.delete(token); }
+        }
+      }
+      this.docs.delete(key);
+    }
+    this.files.delete(sessionId);
+  }
+
+  private indexFile(sessionId: string, file: string, st: { mtimeMs: number; size: number }): void {
+    const docKeys: string[] = [];
+    let content = "";
+    try { content = readFileSync(file, "utf8"); } catch { /* raced deletion: index as empty */ }
+    for (const line of content.split("\n")) {
+      if (!line.trim()) continue;
+      const parsed = parseLine(line);
+      if (!parsed) continue;
+      // length-prefixed doc key: immune to separator-content collisions — session
+      // "s" + entry "0000e1" and session "s0000" + entry "e1" must stay distinct.
+      // The previous separator was the literal 4-char string "0000" (bytes 0x30
+      // 0x30 0x30 0x30 — an intended U+0000 NUL escape written without the
+      // backslash-u), so exactly that pair collided and the second doc was
+      // silently dropped by the duplicate-key guard below.
+      const key = `${sessionId.length}:${sessionId}:${parsed.entryId}`;
+      if (this.docs.has(key)) continue; // duplicate-id guard (session.ts corruption class)
+      const tokens = new Map<string, number>();
+      for (const t of tokenize(parsed.text)) tokens.set(t, (tokens.get(t) ?? 0) + 1);
+      if (tokens.size === 0) continue;
+      this.docs.set(key, { sessionId, entryId: parsed.entryId, text: parsed.text, timestamp: parsed.timestamp, tokens });
+      docKeys.push(key);
+      for (const [token, tf] of tokens) {
+        let posting = this.postings.get(token);
+        if (!posting) { posting = new Map(); this.postings.set(token, posting); }
+        posting.set(key, tf);
+      }
+    }
+    this.files.set(sessionId, { mtimeMs: st.mtimeMs, size: st.size, docKeys });
+  }
+
+  /** Ranked search. Terms are ANDed (FTS5 implicit AND). Tiering: docs with more
+   *  exact-term matches ALWAYS outrank docs matching only partially (hermes's
+   *  exact-FTS5-before-trigram routing as a rank, not a fallback); within a tier,
+   *  weighted tf desc, then timestamp desc, then key for determinism. */
+  search(query: string, limit: number, excludeSession?: string): RecallHit[] {
+    this.refresh();
+    const terms = [...new Set(tokenize(query.slice(0, MAX_QUERY_CHARS)))];
+    if (terms.length === 0) return [];
+
+    let cands: Map<string, { exact: number; weighted: number }> | null = null;
+    for (const term of terms) {
+      const matched = new Map<string, { ex: number; part: number }>();
+      const exact = this.postings.get(term);
+      if (exact) for (const [key, tf] of exact) matched.set(key, { ex: tf, part: 0 });
+      if (term.length >= MIN_PARTIAL_TERM) { // substring tier, trigram-eligible terms only
+        for (const [token, posting] of this.postings) {
+          if (token === term || !token.includes(term)) continue;
+          for (const [key, tf] of posting) {
+            const m = matched.get(key) ?? { ex: 0, part: 0 };
+            m.part += tf;
+            matched.set(key, m);
+          }
+        }
+      }
+      const next = new Map<string, { exact: number; weighted: number }>();
+      for (const [key, m] of matched) {
+        const prev = cands === null ? { exact: 0, weighted: 0 } : cands.get(key);
+        if (prev === undefined) continue; // AND: term missing from doc drops it
+        next.set(key, {
+          exact: prev.exact + (m.ex > 0 ? 1 : 0),
+          weighted: prev.weighted + EXACT_WEIGHT * m.ex + PARTIAL_WEIGHT * m.part,
+        });
+      }
+      cands = next;
+      if (cands.size === 0) return [];
+    }
+
+    const ranked = [...(cands ?? new Map<string, { exact: number; weighted: number }>())]
+      .flatMap(([key, cand]) => {
+        const doc = this.docs.get(key);
+        // exclude the live session: recall is CROSS-session (hermes skips the
+        // current lineage, session_search_tool.py:852-860)
+        return doc && doc.sessionId !== excludeSession ? [{ key, cand, doc }] : [];
+      })
+      .sort((a, b) =>
+        b.cand.exact - a.cand.exact
+        || b.cand.weighted - a.cand.weighted
+        || b.doc.timestamp - a.doc.timestamp
+        || (a.key < b.key ? -1 : 1));
+
+    return ranked.slice(0, Math.max(0, limit)).map(({ doc }) => ({
+      sessionId: doc.sessionId,
+      entryId: doc.entryId,
+      // neutralized HERE so every consumer — tool output, data.hits, the injected
+      // summarizer — sees the scanned view, never the verbatim transcript line
+      preview: neutralize(makePreview(doc.text, terms)),
+      timestamp: doc.timestamp,
+    }));
+  }
+}
+
+export interface RecallToolOptions {
+  /** injected summarizer; absent = raw hits only (upstream removed its LLM summary mode) */
+  summarize?: SummarizeFn;
+  /** result-budget ceiling; defaults to hermes's 10 */
+  maxResults?: number;
+}
+
+/** Build the `recall` tool over a sessions root (one lazy index per tool instance).
+ *
+ *  kind "read", NOT "memory": recall only READS session files from disk — it never
+ *  mutates memory. core/tools.ts actionFor() maps "read" -> "file.read" but
+ *  "memory" -> "memory.write"; gating a pure read behind a write action would let
+ *  memory-write policies silently grant history reads AND lock recall out of
+ *  read-only rule sets. With no `path` arg, describeResource() falls back to the
+ *  tool name, so policy can target `file.read recall` precisely; deny-by-default
+ *  still applies when no rule matches (core/tools.ts evaluatePermissions). */
+export function recallTool(sessionsRoot: string, opts: RecallToolOptions = {}): Tool {
+  const index = new RecallIndex(sessionsRoot);
+  const ceiling = Math.max(1, opts.maxResults ?? MAX_RESULTS);
+  return {
+    schema: {
+      name: "recall",
+      description:
+        "Search past session transcripts (cross-session recall). Full-text over prior conversation " +
+        "message text — no LLM. Terms are ANDed; exact word matches rank above partial (substring) " +
+        `matches. Returns up to ${ceiling} hits: sessionId, entryId, timestamp, and a short preview. ` +
+        "Use for questions about past conversations: 'what did we decide about X', 'where did we leave Y'.",
+      args: {
+        type: "object",
+        properties: {
+          query: { type: "string", description: "words to find in past sessions" },
+          limit: { type: "integer", description: `max hits (default ${Math.min(DEFAULT_RESULTS, ceiling)}, max ${ceiling})` },
+        },
+        required: ["query"],
+      },
+    },
+    kind: "read",
+    sequential: false, // pure read: safe to run concurrently with sibling reads
+    async execute(args: unknown, ctx: ToolContext): Promise<ToolOutput> {
+      // Defense in depth: keep ONLY schema args (query, limit) — smuggled keys,
+      // notably `path`, must never influence behavior. core/tools.ts
+      // describeResource() prefers an args `path` over the tool-name fallback, so
+      // {query, path:"/x"} re-aims a `file.read recall` deny rule at "/x"; policy
+      // runs BEFORE execute, so this strip cannot repair that gate — the
+      // authoritative fix belongs in describeResource (validate against the tool
+      // schema). Residual gap documented in recall.test.ts. A fresh object (not
+      // deletes on `args`) because the registry reuses the caller's object for
+      // loop-guard identity and onToolResult after execute.
+      const raw = (args && typeof args === "object" ? args : {}) as Record<string, unknown>;
+      const a: { query?: unknown; limit?: unknown } = { query: raw.query, limit: raw.limit };
+      if (typeof a.query !== "string" || a.query.trim().length === 0) {
+        return { ok: false, output: "recall failed: query must be a non-empty string" };
+      }
+      // the echoed query is bounded like the searched one: a 200k-char query must
+      // not reflect 200k chars into tool output (truncation marked with an ellipsis)
+      const trimmed = a.query.trim();
+      const echo = trimmed.length > MAX_QUERY_CHARS
+        ? trimOrphanSurrogates(trimmed.slice(0, MAX_QUERY_CHARS)) + "…" : trimmed;
+      // hermes limit clamp: max(1, min(limit, ceiling)) (session_search_tool.py:1040-1046)
+      let limit = Math.min(DEFAULT_RESULTS, ceiling);
+      if (typeof a.limit === "number" && Number.isFinite(a.limit)) limit = Math.trunc(a.limit);
+      limit = Math.max(1, Math.min(limit, ceiling));
+
+      const hits = index.search(a.query, limit, ctx.sessionId);
+      if (hits.length === 0) {
+        // actionable empty message, hermes session_search_tool.py:806-810
+        return { ok: true, output: `recall: no matches for "${echo}" — terms are ANDed; try fewer or broader terms`, data: { hits } };
+      }
+      const lines = hits.map((h) =>
+        `- [${h.sessionId}] entry ${h.entryId} @ ${h.timestamp > 0 ? new Date(h.timestamp).toISOString() : "unknown time"}\n  ${h.preview}`);
+      let output = `recall: ${hits.length} hit(s) for "${echo}"\n` + lines.join("\n");
+      if (opts.summarize) {
+        try {
+          const summary = await opts.summarize(a.query, hits);
+          if (summary) output += `\n\nsummary: ${summary}`;
+        } catch (e) {
+          output += `\n\n(summarize step failed: ${e instanceof Error ? e.message : String(e)}; hits above are unaffected)`;
+        }
+      }
+      return { ok: true, output, data: { hits } };
+    },
+  };
+}