@henryqw/pi-session-recall 4.0.1 → 4.0.3

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,29 +8,36 @@ 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 a progressive search with a distinctive keyword query:
+Ask the agent to search with distinctive keywords, for example:
 
 ```json
 { "query": "database migration rollback" }
 ```
 
-Discovery returns ranked metadata and snippets. Use a result's `path` and `matchMessageId` to scroll for the relevant messages.
+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]. |
+
+BM25 is a text-ranking method. Discovery returns index metadata; READ and SCROLL retrieve messages from saved session files.
 
-Use the discovery result's `path` and `matchMessageId` for a follow-up scroll:
+To scroll directly to a discovery hit, pass its `path` and `matchMessageId`:
 
 ```json
 {
@@ -44,42 +47,37 @@ Use the discovery result's `path` and `matchMessageId` for a follow-up scroll:
 }
 ```
 
-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. Discovery returns index metadata; READ and SCROLL retrieve messages 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 metadata and snippets. Each result includes `path` and `matchMessageId` for a follow-up SCROLL. Start with keywords, then narrow the query before scrolling. |
-| 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,9 +90,7 @@ 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 Git-index collections. Unstaged changes, deletions, mode changes, symlinks, and untracked files do not affect those collections. Skills come from Pi's effective registry and can include untracked files. Inspect current candidate files before assigning ownership; abstain if targeted current-file checks cannot be done safely.
 
 ## Flow
 
@@ -114,36 +110,22 @@ Search makes no model calls.
 
 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
 
 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. Preparation keeps citation and lineage metadata when a source cannot be read.
+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.1.1
-```
-
-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,15 +136,11 @@ 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. Discovery returns the indexed metadata even when a source file changes afterward.
+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 when Git-root lookup exits nonzero (`inventory.available:false`, `reason:"not-a-git-repository"`) or inventory fails after the root is resolved (`reason:"inventory-failed"`). If the working directory cannot be resolved, Git cannot start, root lookup overflows or produces invalid output or unexpected stderr, or the call is cancelled, preparation fails even with all scope; these failures do not return unavailable inventory.
 
 Preparation rejects `query`, session cursors, or `window` in the same call. It also rejects `scope` without the operation.
 
@@ -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/extensions/search-core.ts

@@ -315,10 +315,6 @@ function parseSessionFile(filePath: string, maxBytes: number): ParsedFile {
 	return parsed;
 }
 
-function isJunkEncodedDir(relSegments: string[]): boolean {
-	return relSegments.some((seg) => seg.startsWith("--tmp-") || seg.startsWith("--private-tmp-"));
-}
-
 /** Walk result. `complete: false` means the tree could not be fully read
  *  (missing root, readdir/stat failure) — callers must not treat unseen
  *  indexed paths as deleted. */
@@ -329,11 +325,10 @@ interface WalkResult {
 
 function walkJsonlFiles(sessionsDir: string): WalkResult {
 	const files = new Map<string, fs.Stats>();
-	if (!fs.existsSync(sessionsDir)) return { files, complete: false };
-	const stack: { dir: string; rel: string[] }[] = [{ dir: sessionsDir, rel: [] }];
+	const stack = [sessionsDir];
 	let complete = true;
 	while (stack.length > 0) {
-		const { dir, rel } = stack.pop()!;;
+		const dir = stack.pop()!;
 		let entries: fs.Dirent[];
 		try {
 			entries = fs.readdirSync(dir, { withFileTypes: true });
@@ -346,8 +341,8 @@ function walkJsonlFiles(sessionsDir: string): WalkResult {
 			if (ent.isDirectory()) {
 				// Junk dirs are pruned before descent so a large ignored tree never
 				// costs a walk + per-file stats on every sync pass.
-				if (isJunkEncodedDir([...rel, ent.name])) continue;
-				stack.push({ dir: full, rel: [...rel, ent.name] });
+				if (ent.name.startsWith("--tmp-") || ent.name.startsWith("--private-tmp-")) continue;
+				stack.push(full);
 			} else if (ent.isFile() && ent.name.endsWith(".jsonl")) {
 				try {
 					files.set(full, fs.statSync(full));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@henryqw/pi-session-recall",
-  "version": "4.0.1",
+  "version": "4.0.3",
   "description": "Local FTS5 search over past Pi sessions plus a skill for turning recurring work into deterministic automation.",
   "keywords": [
     "pi-package",