@henryqw/pi-session-recall 2.1.1 → 4.0.2

package/README.md

@@ -1,10 +1,6 @@
 # `@henryqw/pi-session-recall`
 
-Find decisions and context in past Pi sessions through a local FTS5 index.
-
-Saved transcripts are not injected on every turn. The active tool registration still adds standing prompt cost through its schema, descriptions, and guideline. Returned content enters active model context.
-
-The bundled `pi-session-pattern-miner` skill prepares one bounded sample. The model then finds repeated work that may deserve automation.
+Search past Pi sessions locally to find prior decisions and context without injecting saved transcripts on every turn. The active tool registration still adds standing prompt cost through its schema, descriptions, and guideline. Returned content enters active model context.
 
 ## Install
 
@@ -12,74 +8,76 @@ The bundled `pi-session-pattern-miner` skill prepares one bounded sample. The mo
 pi install npm:@henryqw/pi-session-recall
 ```
 
+Requires Node.js 22.19.0 or later.
+
 ## Use
 
-Start discovery with a distinctive query:
+Ask the agent to search with distinctive keywords, for example:
 
 ```json
 { "query": "database migration rollback" }
 ```
 
-`session_search` returns ranked sessions. The top result includes nearby messages and session bookends.
+Discovery returns ranked metadata and snippets. Use a result's `path` and `matchMessageId` to scroll to the relevant messages.
 
-Prepare a repository-scoped pattern-mining sample with one call:
+| Surface | Type | Purpose |
+| --- | --- | --- |
+| `session_search` | tool | Agent tool to browse, search, read, scroll, or prepare a bounded pattern-mining corpus. |
+| `/skill:pi-session-pattern-miner` | skill | Agent workflow, invoked by a user, to find repeated work and choose the smallest useful automation. |
 
-```json
-{
-  "operation": "prepare-pattern-miner",
-  "scope": "repository",
-  "limit": 10
-}
-```
+The tool supports these modes. Agents use `session_search`; users can invoke the skill with `/skill:pi-session-pattern-miner`.
 
-Use `scope:"all"` for cross-repository work. It still returns the corpus when repository inventory is unavailable.
+| Mode | Call | Result |
+| --- | --- | --- |
+| Pattern preparation | `operation:"prepare-pattern-miner"` + `scope:"repository"` or `scope:"all"` | Up to ten recent lineage-unique sessions plus repository inventory. `limit` defaults to 10 and is clamped to [1,10]. Repository scope includes exact and descendant `cwd` values, filters before the limit, and excludes the current session file. |
+| Discovery | `query` | BM25-ranked metadata and snippets. Each result includes `path` and `matchMessageId` for a follow-up scroll. Start with keywords, then narrow the query before scrolling. `limit` defaults to 3 and is clamped to [1,10]. |
+| Scroll | `sessionId` + `aroundMessageId` | Raw message roles, including tool results, within ±`window` ([1,20], default 5) of the anchor on the selected branch. Re-anchor on the last or first message ID to scroll. Across forks, pass the previous response's `branchTip`; `aroundMessageId` must lie on that branch. |
+| Read | `sessionId` | Raw message roles, including tool results, from the session. Large sessions return head 20 + tail 10. Oversized content is bounded to 50k characters and marked with `contentTruncated`. |
+| Browse | no args | Recent sessions with path, name, cwd, started date, and preview. `limit` defaults to 3 and is clamped to [1,10]. |
 
-Use IDs from a discovery result to ask for more context:
+BM25 is a text-ranking method. Discovery returns index metadata; READ and SCROLL retrieve messages from saved session files.
+
+To scroll directly to a discovery hit, pass its `path` and `matchMessageId`:
 
 ```json
 {
-  "sessionId": "<returned sessionId>",
-  "aroundMessageId": "<returned message entryId>",
+  "sessionId": "<result path>",
+  "aroundMessageId": "<result matchMessageId>",
   "window": 10
 }
 ```
 
-The follow-up returns up to ten messages before and after that anchor on the selected branch.
+This returns up to ten messages before and after the anchor on the selected branch.
 
-| Surface | Type | Purpose |
-| --- | --- | --- |
-| `session_search` | tool | Search, inspect, or prepare a bounded mining corpus from past sessions. |
-| `pi-session-pattern-miner` | skill | Find repeated work and choose the smallest useful automation. |
+Start pattern mining with one preparation call:
 
-BM25 is a text-ranking method. Hydrated results include messages read from saved session files.
+```json
+{
+  "operation": "prepare-pattern-miner",
+  "scope": "repository",
+  "limit": 10
+}
+```
 
-| Mode | Call | Result |
-| --- | --- | --- |
-| Pattern preparation | `operation:"prepare-pattern-miner"` + `scope:"repository"` or `scope:"all"` | Up to ten recent lineage-unique sessions plus repository inventory. The default limit is 10. Repository scope includes exact and descendant `cwd` values, filters before the limit, and excludes the current session file. |
-| Discovery | `query` | BM25-ranked top sessions. Adaptive retrieval uses user and assistant text for windows, bookends, anchors, and counts. It omits tool-result messages and sets `toolResultsOmitted:true` when it removes one. Lower hits still include their indexed anchor. Use `detail:"full"` to hydrate every hit with tool-result messages included. |
-| Scroll | `sessionId` + `aroundMessageId` | Raw message roles, including tool results, within ±`window` ([1,20]) of the anchor. Re-anchor on the last or first message ID to scroll. Across forks, pass the previous response's `branchTip`; `aroundMessageId` only centers the window and must lie on that branch. |
-| Read | `sessionId` | Raw message roles, including tool results, from the session. Large sessions return head 20 + tail 10. Oversized content is bounded to 50k characters and marked with `contentTruncated`. |
-| Browse | no args | Recent sessions with path, name, cwd, started date, and preview. |
+Use `scope:"all"` for cross-repository work. It still returns the corpus when repository inventory is unavailable.
 
 In the interactive TUI, the collapsed tool block shows the last five visual lines and the earlier-line count. Press `Ctrl+O` to expand the full bounded response. The model always receives the complete tool result.
 
-### Skills
+### Pattern-miner skill
 
-Run `/skill:pi-session-pattern-miner` to find repeated workflows in past sessions. The skill makes one preparation call before interpretation.
+Invoke `/skill:pi-session-pattern-miner` to find repeated workflows in past sessions. The skill makes exactly one preparation call before interpretation.
 
-It treats one lineage as one source. It requires two independent examples before recommending automation. A requested topic gets a focused confirmation search even when the prepared sample does not contain it.
+It treats one lineage as one source and requires two independent examples before recommending automation. A requested topic gets a focused confirmation search even when the prepared sample does not contain it.
 
 After clustering, the skill always checks current candidate-relevant package manifests, scripts, skills, and instructions. It abstains if it cannot check them safely.
 
 ### Repository inventory
 
-Repository inventory contains discovery hints. It is never proof that a file owns a workflow. It does not verify the current worktree.
+Repository inventory contains discovery hints. It is never proof that a file owns a workflow and does not verify the current worktree.
 
 Package scripts, executable paths, and instruction paths come from stage-0 entries in the Git index. Package content comes from indexed blobs. Git reads the objects locally in one check batch and one content batch. Lazy object fetching and replacement refs are disabled. Inventory never opens working-tree package paths.
 
-Executables need index mode `100755`. Instructions need a recognized name and a regular-file index mode.
-
-Skills come from Pi's effective command registry. Their canonical source paths must stay inside the repository.
+Executables need index mode `100755`. Instructions need a recognized name and a regular-file index mode. Skills come from Pi's effective command registry, and their canonical source paths must stay inside the repository.
 
 Available inventory includes this provenance:
 
@@ -92,13 +90,11 @@ Available inventory includes this provenance:
 }
 ```
 
-It also sets `worktreeVerified:false`. Staged adds, changes, and deletes affect the snapshot. Unstaged changes, deletions, mode changes, symlinks, and untracked files do not.
-
-Inspect the current candidate files before assigning ownership. Abstain if targeted current-file checks cannot be done safely.
+It also sets `worktreeVerified:false`. Staged adds, changes, and deletes affect the snapshot. Unstaged changes, deletions, mode changes, symlinks, and untracked files do not. Inspect current candidate files before assigning ownership; abstain if targeted current-file checks cannot be done safely.
 
 ## Flow
 
-![Flowchart showing session_search routing: preparation, discovery, and browse use the index; scroll and read retrieve saved transcripts directly.](./docs/session-search-routing.svg)
+![Flowchart showing progressive keyword discovery returning path and matchMessageId for direct transcript scroll.](./docs/session-search-routing.svg)
 
 Search makes no model calls.
 
@@ -112,38 +108,24 @@ Search makes no model calls.
 
 ### Context and sync
 
-Hits inside the current session's live context are suppressed. Compacted-away or inactive-branch history stays discoverable. Forked sessions collapse into their parent when both match.
+Discovery excludes the current session file when its path is available. Forked sessions collapse into their parent when both match.
 
-Before browse, discovery, or pattern preparation, the extension lazily syncs the index from the session tree.
-
-Pattern preparation reports `sync.walkComplete`, `sync.backlogRemaining`, and `sync.complete`. `sync.complete` is true only after a complete walk with no backlog.
+Before browse, discovery, or pattern preparation, the extension lazily syncs the index from the session tree. Pattern preparation reports `sync.walkComplete`, `sync.backlogRemaining`, and `sync.complete`; `sync.complete` is true only after a complete walk with no backlog.
 
 ### Retrieval safety
 
-Adaptive discovery leaves tool-result messages out of returned context. Use `detail:"full"`, READ, or SCROLL when you explicitly need them.
+Discovery returns short snippets from indexed user and assistant transcript text. Use a result's `path` and `matchMessageId` with SCROLL for targeted context; READ and SCROLL retrieve raw messages, including tool-result messages when present.
 
-Pattern preparation returns only non-empty user and assistant text. It never returns thinking blocks or tool-result content. Each session keeps citation and lineage metadata even when its hydration fails.
+Pattern preparation returns only non-empty user and assistant text. It never returns thinking blocks or tool-result content, and preserves citation and lineage metadata when a source cannot be read.
 
 Historical tool output may contain secrets or other sensitive data. Raw retrieval places that output in active model context.
 
 ## State and storage
 
-The extension maintains the derived SQLite search index at `~/.pi/agent/config/pi-session-recall/index.db`.
-
-This is derived state. Delete it and it rebuilds from your session files.
+The extension maintains its derived SQLite search index at `~/.pi/agent/config/pi-session-recall/index.db`. Delete this derived state to rebuild it from your session files; no migration or recovery machinery is needed.
 
 The index and transcript reads stay local. Transcripts are read in place. Returned content follows the data path of your configured model provider.
 
-## Roll back
-
-Pin the previous release:
-
-```bash
-pi install npm:@henryqw/pi-session-recall@2.0.0
-```
-
-No index migration or cleanup is needed.
-
 ## Limits and recovery
 
 Lazy index sync can fail while walking the session tree. Results still come from the current index and can be partly updated or stale. Files found before failure may have new content, while rows for files the walk did not reach stay stale.
@@ -154,17 +136,13 @@ Lazy index sync can fail while walking the session tree. Results still come from
 
 Session directories whose encoded path starts with `--tmp-` or `--private-tmp-` are never indexed. These sessions run from `/tmp` or `/private/tmp`.
 
-Session files over 32 MiB are excluded from indexing and hydration. Discovery cannot newly find them.
-
-READ and SCROLL return an explicit size error. A stale discovery hit from before a file grew returns metadata with empty messages and that error.
+Session files over 32 MiB are excluded from indexing and hydration, so discovery cannot newly find them. READ and SCROLL return an explicit size error. Discovery returns indexed metadata even when a source file changes afterward.
 
 Pattern preparation runs one sync pass. A positive backlog or incomplete walk limits the sample and sets `sync.complete:false`. A total sync or required repository-inventory failure returns an explicit tool error.
 
-Repository scope fails outside Git or when repository inventory fails. All scope still returns its corpus in both cases.
-
-Outside Git, all scope sets `inventory.available:false` with `reason:"not-a-git-repository"`. On a repository inventory error, it uses `reason:"inventory-failed"`. Cancellation always aborts the call instead of returning unavailable inventory.
+Repository scope fails outside Git or when repository inventory fails. All scope still returns its corpus in both cases. Outside Git, all scope sets `inventory.available:false` with `reason:"not-a-git-repository"`. On a repository inventory error, it uses `reason:"inventory-failed"`. Cancellation always aborts the call instead of returning unavailable inventory.
 
-Preparation rejects `query`, session cursors, `window`, or `detail` in the same call. It also rejects `scope` without the operation.
+Preparation rejects `query`, session cursors, or `window` in the same call. It also rejects `scope` without the operation.
 
 Preparation output stays within 50,000 serialized characters. Inventory uses at most 10,000 characters. Its `omittedCounts` report only omitted collection entries, and `inventory.truncated` reports those omissions.
 
@@ -173,3 +151,13 @@ Inventory fails if the Git root output exceeds 4 KiB or the raw index listing ex
 Inventory accepts at most 512 package manifests. Each indexed manifest can be at most 1 MiB, and their declared sizes can total at most 16 MiB. One bounded batch checks all blob sizes before one bounded batch reads their content. Blob order, type, size, UTF-8, and exact output framing are checked before manifest data is parsed.
 
 Session and top-level `contentTruncated` report transcript budget trimming only. Session `truncated` reports omitted middle messages.
+
+### Rollback
+
+To return to the older 2.1.1 behavior, pin that release:
+
+```bash
+pi install npm:@henryqw/pi-session-recall@2.1.1
+```
+
+No index migration or cleanup is needed.

package/docs/session-search-routing.html

@@ -15,8 +15,8 @@
 <body>
   <figure>
     <svg width="1280" height="720" viewBox="0 0 1280 720" xmlns="http://www.w3.org/2000/svg" role="img" aria-labelledby="session-search-routing-title session-search-routing-desc">
-      <title id="session-search-routing-title">session_search routing</title>
-      <desc id="session-search-routing-desc">Flowchart routing session_search requests between indexed preparation, discovery, and browse calls and direct transcript scroll and read calls.</desc>
+      <title id="session-search-routing-title">session_search progressive search and scroll</title>
+      <desc id="session-search-routing-desc">Flowchart routing progressive keyword discovery to metadata results, then using each result path and matchMessageId for direct transcript scroll.</desc>
       <defs>
         <style>
           .eyebrow { fill: #6a7282; font: 500 8px 'Geist Mono', monospace; letter-spacing: .16em; }
@@ -107,9 +107,9 @@
 
       <rect x="576" y="400" width="200" height="96" rx="20" fill="#f0eee9" stroke="#101828" stroke-width="1"/>
       <text class="node-name" x="676" y="428">Discovery</text>
-      <text class="node-sub" x="676" y="452">query · lazy sync + FTS5</text>
-      <text class="node-sub" x="676" y="468">adaptive output omits tool results</text>
-      <text class="node-sub" x="676" y="484">detail:&quot;full&quot; includes tool results</text>
+      <text class="node-sub" x="676" y="452">keyword query · lazy sync + FTS5</text>
+      <text class="node-sub" x="676" y="468">metadata + snippets only</text>
+      <text class="node-sub" x="676" y="484">path + matchMessageId → SCROLL</text>
 
       <rect x="328" y="544" width="192" height="96" rx="20" fill="#f0eee9" stroke="#101828" stroke-width="1"/>
       <text class="node-name" x="424" y="572">Browse</text>

package/docs/session-search-routing.svg

@@ -1,7 +1,7 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <svg width="1280" height="720" viewBox="0 0 1280 720" xmlns="http://www.w3.org/2000/svg" role="img" aria-labelledby="session-search-routing-title session-search-routing-desc">
-      <title id="session-search-routing-title">session_search routing</title>
-      <desc id="session-search-routing-desc">Flowchart routing session_search requests between indexed preparation, discovery, and browse calls and direct transcript scroll and read calls.</desc>
+      <title id="session-search-routing-title">session_search progressive search and scroll</title>
+      <desc id="session-search-routing-desc">Flowchart routing progressive keyword discovery to metadata results, then using each result path and matchMessageId for direct transcript scroll.</desc>
       <defs>
         <style>@import url('https://fonts.googleapis.com/css2?family=Instrument+Serif:ital@0;1&amp;family=Geist:wght@400;500;600&amp;family=Geist+Mono:wght@400;500;600&amp;display=swap');</style>
         <style>
@@ -93,9 +93,9 @@
 
       <rect x="576" y="400" width="200" height="96" rx="20" fill="#f0eee9" stroke="#101828" stroke-width="1"/>
       <text class="node-name" x="676" y="428">Discovery</text>
-      <text class="node-sub" x="676" y="452">query · lazy sync + FTS5</text>
-      <text class="node-sub" x="676" y="468">adaptive output omits tool results</text>
-      <text class="node-sub" x="676" y="484">detail:&quot;full&quot; includes tool results</text>
+      <text class="node-sub" x="676" y="452">keyword query · lazy sync + FTS5</text>
+      <text class="node-sub" x="676" y="468">metadata + snippets only</text>
+      <text class="node-sub" x="676" y="484">path + matchMessageId → SCROLL</text>
 
       <rect x="328" y="544" width="192" height="96" rx="20" fill="#f0eee9" stroke="#101828" stroke-width="1"/>
       <text class="node-name" x="424" y="572">Browse</text>

package/extensions/hydrate.ts

@@ -1,6 +1,6 @@
 /**
  * Hydration: direct JSONL parsing of Pi session files (never SessionManager.open —
- * it rewrites legacy files), branch-aware windows/bookends, READ head/tail.
+ * it rewrites legacy files), branch-aware windows, READ head/tail.
  * Pure functions over file paths; no SQLite access.
  */
 /// <reference types="node" />
@@ -9,13 +9,8 @@ import type { WindowMessage } from "./types.ts";
 
 export interface WindowResult {
 	messages: WindowMessage[];
-	/** Every message on the resolved branch, root→tip chronological. Callers
- *  derive bookends from this instead of re-parsing the transcript. */
-	branchMessages: WindowMessage[];
 	messagesBefore: number;
 	messagesAfter: number;
-	/** Present only when discovery filtering removed at least one tool result. */
-	toolResultsOmitted?: true;
 	/** Tip of the branch the window was resolved on — pass back as branchTip to
 	 *  keep scrolling on this branch across forks. May be a non-message entry id. */
 	branchTip: string;
@@ -139,11 +134,7 @@ function branch(entriesById: Map<string, Entry>, entryId: string): Entry[] {
 }
 
 /** Deepest entry in file order whose ancestry contains tipId (tipId itself if none). */
-function deepestDescendant(
-	entriesById: Map<string, Entry>,
-	entries: Entry[],
-	anchorId: string,
-): string {
+function deepestDescendant(entries: Entry[], anchorId: string): string {
 	const onBranch = new Set([anchorId]);
 	let tip = anchorId;
 	for (const e of entries) {
@@ -207,7 +198,7 @@ export function getWindow(
 	sessionPath: string,
 	anchorEntryId: string,
 	windowN: number,
-	opts?: { branchTip?: string; userAssistantTextOnly?: boolean },
+	opts?: { branchTip?: string },
 ): WindowResult {
 	const n = Math.max(0, Math.min(50, windowN));
 	const entries = parseSessionEntries(sessionPath);
@@ -222,32 +213,24 @@ export function getWindow(
 		// Explicit branch selection: resolve the branch from its tip (deepest
 		// descendant), independent of where the window centers.
 		resolveMessageCursor(entriesById, opts.branchTip); // unknown tip → throw
-		tip = deepestDescendant(entriesById, entries, opts.branchTip);
+		tip = deepestDescendant(entries, opts.branchTip);
 		if (!branch(entriesById, tip).some((e) => e.id === messageAnchor.id)) {
 			throw new Error(`anchor entry ${anchorEntryId} is not on branch ${opts.branchTip}`);
 		}
 	} else {
-		tip = deepestDescendant(entriesById, entries, anchorEntryId);
+		tip = deepestDescendant(entries, anchorEntryId);
 	}
-	const rawMessages = branchMessages(entriesById, tip);
-	const toolResultsOmitted = opts?.userAssistantTextOnly && rawMessages.some((m) => m.role === "toolResult")
-		? true
-		: undefined;
-	const msgs = opts?.userAssistantTextOnly
-		? rawMessages.filter((m) => (m.role === "user" || m.role === "assistant") && m.content.length > 0)
-		: rawMessages;
+	const msgs = branchMessages(entriesById, tip);
 	const idx = msgs.findIndex((m) => m.entryId === anchorEntryIdMsg);
-	if (idx < 0) throw new Error(`anchor entry ${anchorEntryId} is not a user/assistant text message`);
+	if (idx < 0) throw new Error(`anchor entry ${anchorEntryId} is not a message`);
 	const start = Math.max(0, idx - n);
 	const end = Math.min(msgs.length - 1, idx + n);
 	return {
-		branchMessages: msgs,
 		messages: msgs.slice(start, end + 1).map((m) =>
 			m.entryId === anchorEntryIdMsg ? { ...m, anchor: true } : m,
 		),
 		messagesBefore: idx,
 		messagesAfter: msgs.length - 1 - idx,
-		...(toolResultsOmitted ? { toolResultsOmitted } : {}),
 		branchTip: tip,
 	};
 }

package/extensions/search-core.ts

@@ -15,7 +15,7 @@ export const DEFAULT_SYNC_CAP = 50;
 const MAX_SYNC_CAP = DEFAULT_SYNC_CAP * 10;
 const MAX_TEXT_CHARS = 20000;
 const SCAN_LIMIT = 300;
-/** Best-ranked candidate retained per session after live-entry filtering. */
+/** Best-ranked candidate retained per session after SQL prefiltering. */
 const ROWS_PER_FILE = 1;
 
 const SCHEMA_SQL = `
@@ -519,19 +519,13 @@ function getBacklog(db: DatabaseSync): number {
 
 export interface SearchOptions {
 	limit?: number;
-	/** Entry ids on the current session's live branch — hits here are skipped. */
-	currentLiveEntryIds?: Set<string>;
-	/** Path of the current session file. */
+	/** Path of the current session file — the whole file is skipped. */
 	currentSessionPath?: string;
 }
 
-// Live-entry suppression happens INSIDE SQL (before ROW_NUMBER/caps) so
-// inactive matches on the current file compete only against each other, and
-// there is no pre-partition LIMIT: one verbose session cannot starve others.
-// live_filter is a per-connection TEMP table populated from SearchOptions.
-const LIVE_FILTER_SQL = `NOT EXISTS (
-  SELECT 1 FROM live_filter lf WHERE lf.path = m.path AND lf.entry_id = m.entry_id
-)`;
+// Current-session exclusion happens INSIDE SQL (before ROW_NUMBER/caps), so
+// the excluded file cannot consume the per-file rank, lineage, or scan limit.
+const CURRENT_SESSION_FILTER_SQL = "(? IS NULL OR m.path <> ?)";
 const LINEAGE_FILTER_SQL = `NOT EXISTS (
   SELECT 1 FROM ranked parent
   WHERE parent.path = r.parent_session
@@ -549,7 +543,7 @@ WITH matches AS (
          bm25(session_fts) AS score
   FROM session_fts JOIN messages m ON m.rowid = session_fts.rowid
   LEFT JOIN sessions s ON s.path = m.path
-  WHERE session_fts MATCH ? AND ${LIVE_FILTER_SQL}
+  WHERE session_fts MATCH ? AND ${CURRENT_SESSION_FILTER_SQL}
 ), ranked AS (
   SELECT *, ROW_NUMBER() OVER (PARTITION BY path ORDER BY score, rid) AS rn
   FROM matches
@@ -587,22 +581,7 @@ export function searchIndex(
 	const limit = opts?.limit ?? 3;
 	const db = openDb(dbPath);
 	try {
-		// Per-connection TEMP table of (path, entry_id) pairs to suppress —
-		// parameterized, immune to SQLite variable limits. Primary key indexes
-		// the correlated NOT EXISTS probe and dedupes inserts.
-		db.exec("CREATE TEMP TABLE IF NOT EXISTS live_filter (path TEXT NOT NULL, entry_id TEXT NOT NULL, PRIMARY KEY (path, entry_id))");
-		if (opts?.currentSessionPath && opts?.currentLiveEntryIds?.size) {
-			const ins = db.prepare("INSERT INTO live_filter(path, entry_id) VALUES (?, ?)");
-			db.exec("BEGIN");
-			try {
-				for (const id of opts.currentLiveEntryIds!) ins.run(opts.currentSessionPath!, id);
-				db.exec("COMMIT");
-			} catch (err) {
-				db.exec("ROLLBACK");
-				throw err;
-			}
-		}
-
+		const currentSessionPath = opts?.currentSessionPath ?? null;
 		const plan = buildFtsQueryPlan(query);
 		if (plan.ftsCandidates.length === 0 && !plan.forceLike) {
 			return { hits: [], backlogRemaining: getBacklog(db) };
@@ -628,7 +607,7 @@ export function searchIndex(
 			let parseFailed = false;
 			for (const cand of plan.ftsCandidates) {
 				try {
-					rows = db.prepare(BASE_SELECT).all(cand) as any;
+					rows = db.prepare(BASE_SELECT).all(cand, currentSessionPath, currentSessionPath) as any;
 					// First/raw success defines the result even with zero rows. After a
 					// parse error, an empty recovery candidate keeps trying later ones.
 					if (!parseFailed || rows.length > 0) {
@@ -652,21 +631,21 @@ export function searchIndex(
 			                   ROW_NUMBER() OVER (PARTITION BY m.path ORDER BY m.rowid DESC) AS rn,
 			                   COUNT(*) OVER (PARTITION BY m.path) AS matches
 			             FROM messages m LEFT JOIN sessions s ON s.path = m.path
-			             WHERE ${likePlan.where} AND ${LIVE_FILTER_SQL}
+			             WHERE ${likePlan.where} AND ${CURRENT_SESSION_FILTER_SQL}
 			            )
 			            SELECT path, entry_id, role, timestamp, head, tail, cwd, name, started_at
 			            FROM ranked r
 			            WHERE rn <= ${ROWS_PER_FILE}
 			              AND ${LINEAGE_FILTER_SQL}
 			            ORDER BY matches DESC, started_at DESC, path
-			            LIMIT ${SCAN_LIMIT}`).all(...likePlan.params) as any;
+			            LIMIT ${SCAN_LIMIT}`).all(...likePlan.params, currentSessionPath, currentSessionPath) as any;
 			// Snippets anchor on operand terms only — operator words like OR would
 			// otherwise match common substrings and hide the real match.
 			for (const r of rows as any[]) r.snip = likeSnippet((r as any).head ?? "", (r as any).tail ?? "", likePlan.terms);
 		}
 
-		// Live-entry and one-hop lineage suppression already happened in SQL,
-		// before the scan limit, so fork rows cannot starve unrelated matches.
+		// Current-file and one-hop lineage suppression already happened in SQL,
+		// before the scan limit, so excluded or fork rows cannot starve matches.
 		const seenFiles = new Set<string>();
 		const hits: SearchHit[] = [];
 		let rankCounter = 0;

package/extensions/session-recall.ts

@@ -266,16 +266,15 @@ interface ToolParams {
 	branchTip?: string;
 	window?: number;
 	limit?: number;
-	detail?: "adaptive" | "full";
 }
 
-const DESCRIPTION = `Search past Pi sessions locally with FTS5; returns stored messages.
+const DESCRIPTION = `Search past Pi sessions locally with FTS5; returns indexed metadata and snippets.
 
 - \`operation: "prepare-pattern-miner"\` + \`scope\`: prepare one bounded corpus and repository inventory.
 - \`query\`: discover matches. Prefer distinctive identifiers or uncommon terms; multi-word queries are AND. Use \`OR\`/\`NOT\` for Boolean queries and quotes only when exact wording is known.
 - \`sessionId\` + \`aroundMessageId\`: scroll ±\`window\`; retain \`branchTip\` across forks.
 - \`sessionId\` alone: read; no args: browse recent sessions.
-- Discovery is adaptive; use \`detail: "full"\` to hydrate every result.`;
+- Discovery returns metadata and snippets. Use a result's \`path\` and \`matchMessageId\` for a follow-up scroll.`;
 
 export default function (pi: ExtensionAPI): void {
 	// Best-effort sync at startup, deferred so the synchronous walk + SQLite
@@ -307,8 +306,7 @@ export default function (pi: ExtensionAPI): void {
 			branchTip: Type.Optional(Type.String({ description: "Branch tip entry id from a previous response — selects which branch of a forked session to scroll; aroundMessageId must lie on it." })),
 			window: Type.Optional(Type.Number({ description: "Scroll window radius, [1,20], default 5." })),
 			limit: Type.Optional(Type.Number({ description: "Max results, [1,10]. Defaults to 10 for preparation and 3 otherwise." })),
-			detail: Type.Optional(StringEnum(["adaptive", "full"] as const)),
-		}),
+		}, { additionalProperties: false }),
 		renderResult(result, { expanded }, theme) {
 			const output = result.content.find((part) => part.type === "text")?.text ?? "";
 			const styledOutput = theme.fg("toolOutput", output);
@@ -333,7 +331,7 @@ export default function (pi: ExtensionAPI): void {
 					throw new Error("scope requires operation: prepare-pattern-miner.");
 				}
 				if (rawParams.operation === "prepare-pattern-miner") {
-					const incompatible = (["query", "sessionId", "aroundMessageId", "branchTip", "window", "detail"] as const)
+					const incompatible = (["query", "sessionId", "aroundMessageId", "branchTip", "window"] as const)
 						.filter((key) => rawParams[key] !== undefined);
 					if (incompatible.length > 0) {
 						throw new Error(`prepare-pattern-miner does not accept: ${incompatible.join(", ")}.`);
@@ -365,7 +363,6 @@ export default function (pi: ExtensionAPI): void {
 					branchTip: rawParams.branchTip != null ? String(rawParams.branchTip) : undefined,
 					window: rawParams.window,
 					limit: rawParams.limit,
-					detail: rawParams.detail,
 				};
 				let sessionId = params.sessionId?.trim() || undefined;
 				const anchor = params.aroundMessageId?.trim() || undefined;
@@ -445,135 +442,40 @@ export default function (pi: ExtensionAPI): void {
 
 				// --- DISCOVERY ---
 				const limit = clamp(params.limit, 1, 10, 3);
-				const full = params.detail === "full";
 
-				// Current-session guard: suppress hits on the live branch.
-				let liveIds: Set<string> | undefined;
+				// Exclude the whole current file when the session manager provides it.
+				// A missing or failing manager leaves discovery usable without exclusion.
 				let currentSessionPath: string | undefined;
 				try {
-					currentSessionPath = ctx.sessionManager.getSessionFile();
-					liveIds = new Set(
-						ctx.sessionManager
-							.buildContextEntries()
-							.filter((e) => e.type === "message")
-							.map((e) => e.id),
-					);
+					currentSessionPath = ctx.sessionManager.getSessionFile() ?? undefined;
 				} catch {
-					// Guard unavailable → degrade gracefully, no suppression.
+					// Guard unavailable → continue without exclusion.
 				}
 
 				const { hits, backlogRemaining } = searchIndex(dbPath(), params.query, {
 					limit,
-					currentLiveEntryIds: liveIds,
 					currentSessionPath,
 				});
 
 				const resultQuery = params.query!.trim().slice(0, MAX_QUERY_CHARS);
-				// Reserve the complete response envelope and divide remaining space
-				// across hits so the first hydrated result cannot starve later metadata.
-				// The same warning-bearing envelope is reused for the final result so the
-				// reservation matches what is returned (and textResult's trimming keeps
-				// top-level non-array keys like syncWarning).
-				const envelope: Record<string, unknown> = {
+				const results = hits.map((hit) => ({
+					path: hit.path,
+					snippet: hit.snippet,
+					rank: hit.rank,
+					matchMessageId: hit.entryId,
+					role: hit.role,
+					timestamp: hit.timestamp,
+					cwd: hit.cwd,
+					name: hit.name,
+					startedAt: hit.startedAt,
+				}));
+				return textResult({
 					mode: "discovery",
 					query: resultQuery,
-					results: [],
+					results,
 					backlogRemaining,
 					...(syncWarning ? { syncWarning } : {}),
-				};
-				let used = JSON.stringify(envelope).length + Math.max(0, hits.length - 1);
-				const results = hits.map((hit, index) => {
-					const remaining = Math.floor((OUTPUT_CHAR_BUDGET - used) / (hits.length - index));
-					const meta = {
-						path: hit.path,
-						snippet: hit.snippet,
-						rank: hit.rank,
-						matchMessageId: hit.entryId,
-						role: hit.role,
-						timestamp: hit.timestamp,
-						cwd: hit.cwd,
-						name: hit.name,
-						startedAt: hit.startedAt,
-					};
-					const hydrateFull = full || hit.rank === 0;
-					// Every hit is sized against the cumulative remaining budget: keep
-					// as-is when it fits, else truncate to the largest uniform cap that
-					// fits across messages and bookends, else metadata-only.
-					// contentTruncated signals either case.
-					const fitOrTruncate = (
-						hitObj: Record<string, unknown>,
-						messages: WindowMessage[],
-						bookends?: { start: WindowMessage[]; end: WindowMessage[] },
-					): Record<string, unknown> => {
-						const out: Record<string, unknown> = { ...hitObj };
-						if (JSON.stringify(out).length > remaining) {
-							const pools = bookends ? [messages, bookends.start, bookends.end] : [messages];
-							const maxLen = Math.max(...pools.flatMap((a) => a.map((m) => m.content.length)), 0);
-							Object.assign(
-								out,
-								boundContent(
-									(cap) => ({
-										...hitObj,
-										messages: cap === null ? [] : truncateContent(messages, cap),
-										...(bookends && cap !== null
-											? { bookends: { start: truncateContent(bookends.start, cap), end: truncateContent(bookends.end, cap) } }
-											: bookends
-												? { bookends: { start: [], end: [] } }
-												: {}),
-										contentTruncated: true,
-									}),
-									maxLen,
-									remaining,
-								),
-							);
-						}
-						used += JSON.stringify(out).length;
-						return out;
-					};
-					const hydrationFallback = (error: unknown) =>
-						fitOrTruncate(
-							{ ...meta, detail: hydrateFull ? "full" : "compact", messages: [], bookends: { start: [], end: [] }, messagesBefore: 0, messagesAfter: 0, error: (error instanceof Error ? error.message : String(error)).slice(0, 512) },
-							[],
-						);
-					if (!hydrateFull) {
-						// Compact hits still carry the matched anchor message.
-						try {
-							const win = getWindow(hit.path, hit.entryId, 0, { userAssistantTextOnly: true });
-							// Mark when the fixed compact cap already removed content, so a
-							// hit that still fits the budget isn't mistaken for complete.
-							const overCompactCap = win.messages.some((m) => m.content.length > 2000);
-							return fitOrTruncate({ ...meta, detail: "compact", ...(overCompactCap ? { contentTruncated: true } : {}), ...(win.toolResultsOmitted ? { toolResultsOmitted: true } : {}), messages: truncateContent(win.messages, 2000), bookends: { start: [], end: [] }, messagesBefore: win.messagesBefore, messagesAfter: win.messagesAfter }, win.messages);
-						} catch (error) {
-							return hydrationFallback(error);
-						}
-					}
-					try {
-						// One bounded snapshot feeds both window and branch bookends.
-						const win = getWindow(hit.path, hit.entryId, 5, full ? undefined : { userAssistantTextOnly: true });
-						// Same branch as the anchor — following the file's final leaf
-						// would attach unrelated sibling messages.
-						const bookends = { start: win.branchMessages.slice(0, 3), end: win.branchMessages.slice(-3) };
-						return fitOrTruncate(
-							{
-								...meta,
-								detail: "full" as const,
-								...(win.toolResultsOmitted ? { toolResultsOmitted: true } : {}),
-								messages: win.messages,
-								bookends,
-								messagesBefore: win.messagesBefore,
-								messagesAfter: win.messagesAfter,
-							},
-							win.messages,
-							bookends,
-						);
-					} catch (error) {
-						// Session file unreadable/moved since indexing → anchor-only.
-						return hydrationFallback(error);
-					}
 				});
-
-				const result: Record<string, unknown> = { ...envelope, results };
-				return textResult(result);
 			} catch (error) {
 				const message = error instanceof Error ? error.message : String(error);
 				return textResult({ success: false, error: message });

package/extensions/types.ts

@@ -9,7 +9,7 @@ export interface WindowMessage {
 	role: string;
 	content: string;
 	timestamp: string;
-	/** True when this message is the anchor of a scroll/discovery window. */
+	/** True when this message is the anchor of a scroll window. */
 	anchor?: boolean;
 }
 
@@ -28,7 +28,7 @@ export interface PreparationSessionRow extends SessionRow {
 	lineageId: string;
 }
 
-/** One FTS discovery hit before hydration. */
+/** One metadata-only FTS discovery hit. */
 export interface SearchHit {
 	path: string;
 	entryId: string;

package/package.json

@@ -1,57 +1,62 @@
 {
-	"name": "@henryqw/pi-session-recall",
-	"version": "2.1.1",
-	"description": "Local FTS5 search over past Pi sessions plus a skill for turning recurring work into deterministic automation.",
-	"keywords": [
-		"pi-package",
-		"pi",
-		"session-recall",
-		"fts5",
-		"recall"
-	],
-	"type": "module",
-	"engines": {
-		"node": ">=22.19.0"
-	},
-	"license": "MIT",
-	"files": [
-		"LICENSE",
-		"extensions",
-		"skills",
-		"docs",
-		"README.md"
-	],
-	"scripts": {
-		"test": "node --test test/*.test.ts",
-		"typecheck": "tsc --noEmit --allowImportingTsExtensions --target ES2022 --module NodeNext --moduleResolution NodeNext --skipLibCheck extensions/*.ts test/*.test.ts",
-		"pack:check": "npm pack --dry-run"
-	},
-	"peerDependencies": {
-		"@earendil-works/pi-ai": "^0.85.1",
-		"@earendil-works/pi-coding-agent": "^0.85.1",
-		"@earendil-works/pi-tui": "^0.85.1",
-		"typebox": "^1.3.15"
-	},
-	"repository": {
-		"type": "git",
-		"url": "git+https://github.com/HenryQW/pi-harness.git",
-		"directory": "extensions/pi-session-recall"
-	},
-	"bugs": {
-		"url": "https://github.com/HenryQW/pi-harness/issues"
-	},
-	"publishConfig": {
-		"access": "public"
-	},
-	"pi": {
-		"extensions": [
-			"./extensions/session-recall.ts"
-		],
-		"skills": [
-			"./skills"
-		]
-	},
-	"dependencies": {
-		"@henryqw/pi-config-store": "^1.0.0"
-	}
+  "name": "@henryqw/pi-session-recall",
+  "version": "4.0.2",
+  "description": "Local FTS5 search over past Pi sessions plus a skill for turning recurring work into deterministic automation.",
+  "keywords": [
+    "pi-package",
+    "pi",
+    "session-recall",
+    "fts5",
+    "recall"
+  ],
+  "type": "module",
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "license": "MIT",
+  "files": [
+    "LICENSE",
+    "extensions",
+    "skills",
+    "docs",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "node --test test/*.test.ts",
+    "typecheck": "tsc --noEmit --allowImportingTsExtensions --target ES2022 --module NodeNext --moduleResolution NodeNext --skipLibCheck extensions/*.ts test/*.test.ts",
+    "pack:check": "npm pack --dry-run"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": ">=0.86.0 <0.88.0",
+    "@earendil-works/pi-coding-agent": ">=0.86.0 <0.88.0",
+    "@earendil-works/pi-tui": ">=0.86.0 <0.88.0",
+    "typebox": "^1.3.15"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/HenryQW/pi-harness.git",
+    "directory": "extensions/pi-session-recall"
+  },
+  "bugs": {
+    "url": "https://github.com/HenryQW/pi-harness/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "pi": {
+    "extensions": [
+      "./extensions/session-recall.ts"
+    ],
+    "skills": [
+      "./skills"
+    ]
+  },
+  "dependencies": {
+    "@henryqw/pi-config-store": "^2.0.0"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-ai": "0.87.0",
+    "@earendil-works/pi-coding-agent": "0.87.0",
+    "@earendil-works/pi-tui": "0.87.0"
+  }
 }