pi-memoria 0.3.2 → 0.3.3

package/AGENTS.md

@@ -28,6 +28,7 @@ From this package directory; from the monorepo root, use `npm --prefix packages/
 - `index.ts`: Pi lifecycle hooks, tool schemas, guidance, and bounded tool results.
 - `src/config.ts`: global paths and session-root configuration.
 - `src/database.ts`: SQLite WAL, transactional FTS5 triggers, CRUD, retrieval, alias-expanded keyword queries, exact tag predicates, session-root registry.
+- `src/database-path.ts`, `src/database-schema.ts`: pre-mutation path/companion alias guards, private snapshot attestation, exact supported-schema signatures and legacy/current initialization.
 - `src/hot-memory.ts`: authoritative bullet file, stable IDs, priorities, duplicate-safe adds/edits, single-line validation, locking, atomic writes, cap enforcement.
 - `src/aliases.ts`: optional global `synonyms.json` loading/validation and bounded one-hop query expansion.
 - `src/errors.ts`: stable expected-error codes and SQLite failure classification.
@@ -61,10 +62,10 @@ Add meaningful regression tests for cap boundaries, races, durable retrieval, pa
 
 ## Releasing
 
-Follow the [monorepo release process](https://github.com/rcsaquino/pi-extensions/blob/main/RELEASING.md) only after explicit approval. Version 0.3.2 is the patch after the public 0.3.1 release; it is not published by editing this file.
+Follow the [monorepo release process](https://github.com/rcsaquino/pi-extensions/blob/main/RELEASING.md) only after explicit approval. Version 0.3.3 is the patch after the public 0.3.2 release; it is not published by editing this file.
 
 - Verify this package and the root suite, inspect `npm pack --dry-run --ignore-scripts --workspaces=false`, and check the chosen version is not already on npm.
-- Use package-specific tags such as `pi-memoria-v0.3.2`, not a shared root `v0.3.2` tag. Commit, push, tag, release creation, and npm publication remain separately authorized actions; pushing a `pi-memoria-v<version>` tag is the publication authorization for the workflow.
+- Use package-specific tags such as `pi-memoria-v0.3.3`, not a shared root `v0.3.3` tag. Commit, push, tag, release creation, and npm publication remain separately authorized actions; pushing a `pi-memoria-v<version>` tag is the publication authorization for the workflow.
 - `.github/workflows/publish-pi-memoria.yml` publishes this package on a `pi-memoria-v<version>` tag after the full suite verifies, using npm trusted publishing (OIDC) with automatic provenance. Creating a GitHub release does not itself publish npm packages.
 - The old trusted-publisher configuration targeting the standalone `rcsaquino/pi-memoria` repository does not apply. The npm trusted publisher must target `rcsaquino/pi-extensions` with workflow filename `publish-pi-memoria.yml` and allow `npm publish`; verify it on npm before the first tagged release and never claim it is configured until then.
 - Manual publication needs the account's current npm authorization and any required interactive 2FA. A dry run cannot verify those permissions. Never include credentials in commands, documentation, logs, or model context.

package/README.md

@@ -19,7 +19,7 @@ pi-memoria gives Pi one memory shared across every project: instructions that mu
 
 - **Node.js 22.19+** (uses `node:sqlite`; earlier baselines 22.19/24.20, maintained suite 26.10.0).
 - A Node-based **Pi** host. The pinned development baseline is 1.0.0, the maintained Pi host. Standalone/Bun builds are not validated with `node:sqlite`.
-- **ripgrep (`rg`) on PATH** for session search.
+- **ripgrep (`rg`)**, either on PATH or in Pi's managed `<agent-dir>/bin/` directory, for session search.
 
 ## Installation
 
@@ -27,7 +27,7 @@ pi-memoria gives Pi one memory shared across every project: instructions that mu
 pi install npm:pi-memoria
 ```
 
-This installs the current public npm release. This checkout contains version **0.3.2**, the patch after the public 0.3.1 release.
+This installs the current public npm release. The source version is recorded in `package.json`; unpublished checkout changes require a local install.
 
 Activate with `/reload` in an idle session when intended, or a separately approved restart. To uninstall, run `pi remove npm:pi-memoria`; stored memory remains until you delete its directory.
 
@@ -132,7 +132,7 @@ Tool replies are compact; oversized results spill to a private `pi-memoria-resul
 
 | Variable | Effect |
 |---|---|
-| `PI_CODING_AGENT_DIR` | Pi's agent directory; memoria defaults to its `memoria/` child |
+| `PI_CODING_AGENT_DIR` | Pi's agent directory; memoria defaults to its `memoria/` child and looks for managed ripgrep in its `bin/` child |
 | `PI_MEMORIA_DIR` | Override the single global memory directory |
 | `PI_MEMORIA_SESSION_DIRS` | JSON array of additional absolute session roots |
 
@@ -146,6 +146,14 @@ The optional `synonyms.json` next to `memoria.sqlite` maps terms for `any`/`all`
 └── backups/
 ```
 
+Database startup recognizes truly empty stores and the exact shipped memoria v1/v2 schemas, including legacy stores without an application identifier. Current stores receive the `MEMO` application identifier without a schema-version bump. Foreign, future, customized or unsupported schemas are refused before chmod, journal-mode changes or migration. Supported v1 migration preserves facts, archives, duplicates and FTS indexes.
+
+Database/companion files must be regular single-link files, and existing directory components cannot be symlinks. Unsafe `-wal`, `-shm`, `-journal` aliases and orphan companions are refused. Ownership inspection uses a private mode-0700 temporary snapshot of the database/WAL/journal, because even SQLite READONLY can alter original SHM read marks. Snapshot files use 0600, copying uses a fixed-size buffer with bounded change retries, and cleanup runs on success/failure. Startup inspection is linear in stored bytes and needs temporary disk capacity; normal queries do not copy the store. Concurrent supported startup still re-attests under its migration transaction. These are focused startup checks, not an OS lease against uncoordinated path/schema mutations by another process.
+
+Session search prefers Pi's managed `<agent-dir>/bin/rg` (`rg.exe` on Windows), then inherited PATH if the managed executable is missing (ENOENT). Permission errors or other operational failures are reported, not hidden by fallback. Resolution is retried on each search so a binary provisioned after extension loading is recognized. `PI_CODING_AGENT_DIR` uses the same absolute/tilde normalization as the memory configuration; `PI_MEMORIA_DIR` does not move the managed-bin location. Explicit executable overrides for custom callers/tests remain authoritative.
+
+Memoria never downloads binaries or changes PATH. Normal interactive Pi startup can provision missing ripgrep on supported platforms. On an offline first start, after a failed download, or where Pi cannot provision it (such as Android/Termux), install system ripgrep or provision the managed binary separately. Android/Termux users can use `pkg install ripgrep`. Reading an original entry with `action=read` does not require ripgrep.
+
 The default session root is `<agent-dir>/sessions`; roots Pi uses are remembered across projects. Changing `PI_MEMORIA_DIR` selects a different store without migrating the old one, project `cwd` is never used to choose it, and no data is sent over the network.
 
 </details>

package/index.ts

@@ -286,10 +286,10 @@ export default function memoria(pi: ExtensionAPI) {
         let warning: string | undefined;
         try {
           const db = database(current);
-          sessions = new SessionSearch(() => db.roots());
+          sessions = new SessionSearch(() => db.roots(), undefined, current.config.ripgrepPath);
         } catch (error) {
           const sessionFile = ctx.sessionManager.getSessionFile();
-          sessions = new SessionSearch(() => [...current.config.sessionRoots, ctx.sessionManager.getSessionDir(), ...(sessionFile ? [dirname(sessionFile)] : [])]);
+          sessions = new SessionSearch(() => [...current.config.sessionRoots, ctx.sessionManager.getSessionDir(), ...(sessionFile ? [dirname(sessionFile)] : [])], undefined, current.config.ripgrepPath);
           warning = `SQLite unavailable: ${(error as Error).message}. Searching default/configured/current roots only; previously remembered custom roots may be missing.`;
         }
         if (params.action === "read") {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-memoria",
-  "version": "0.3.2",
+  "version": "0.3.3",
   "description": "Global working memory, SQLite FTS5 recall, and complete Pi session search",
   "type": "module",
   "license": "MIT",

package/src/config.ts

@@ -1,5 +1,5 @@
 import { homedir } from "node:os";
-import { isAbsolute, join, resolve } from "node:path";
+import { isAbsolute, join, posix, resolve, win32 } from "node:path";
 
 export function absolutePath(value: string, name: string): string {
   const expanded = value === "~" ? homedir() : value.startsWith("~/") ? join(homedir(), value.slice(2)) : value;
@@ -7,6 +7,12 @@ export function absolutePath(value: string, name: string): string {
   return resolve(expanded);
 }
 
+/** Pi's managed binary belongs to the agent directory, not the memory store. */
+export function managedRipgrepPath(agentDir: string, platform: NodeJS.Platform = process.platform): string {
+  const paths = platform === "win32" ? win32 : posix;
+  return paths.join(agentDir, "bin", platform === "win32" ? "rg.exe" : "rg");
+}
+
 export function configuration(agentDir: string, env: NodeJS.ProcessEnv = process.env) {
   agentDir = absolutePath(agentDir, "Pi agent directory");
   const directory = env.PI_MEMORIA_DIR ? absolutePath(env.PI_MEMORIA_DIR, "PI_MEMORIA_DIR") : join(agentDir, "memoria");
@@ -20,6 +26,7 @@ export function configuration(agentDir: string, env: NodeJS.ProcessEnv = process
   }
   return {
     directory,
+    ripgrepPath: managedRipgrepPath(agentDir),
     hotPath: join(directory, "MEMORY.md"),
     databasePath: join(directory, "memoria.sqlite"),
     aliasesPath: join(directory, "synonyms.json"),

package/src/database-path.ts

@@ -0,0 +1,89 @@
+import { constants, closeSync, fchmodSync, fstatSync, lstatSync, mkdirSync, mkdtempSync, openSync, readSync, rmSync, writeSync, type Stats } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join, parse, resolve } from "node:path";
+
+/** Conservative startup checks, not exclusion of uncoordinated same-user processes.
+ * No chmod or SQLite open occurs until the entire existing chain and companions
+ * have passed. SQLite needs named companions, so it still owns pathname I/O.
+ */
+export function databasePath(input: string) {
+  const path = resolve(input), dir = dirname(path);
+  const directories = () => {
+    let current = parse(dir).root;
+    for (const part of dir.slice(current.length).split(/[\\/]/).filter(Boolean)) {
+      current = join(current, part);
+      try { const info = lstatSync(current); if (!info.isDirectory() || info.isSymbolicLink()) throw new Error("Unsafe database directory."); }
+      catch (error) { if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error; }
+    }
+  };
+  const entry = (name: string) => {
+    try {
+      const info = lstatSync(name);
+      if (!info.isFile() || info.isSymbolicLink() || info.nlink !== 1) throw new Error("Unsafe database or SQLite companion alias.");
+      return info;
+    } catch (error) { if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error; return undefined; }
+  };
+  const check = () => {
+    directories(); const info = entry(path);
+    for (const suffix of ["-wal", "-shm", "-journal"]) if (entry(path + suffix) && !info) throw new Error("Orphaned SQLite companion without a database.");
+    return info;
+  };
+  check(); mkdirSync(dir, { recursive: true, mode: 0o700 }); check();
+  return {
+    path, check,
+    inspect(work: (snapshot: string) => void) {
+      // SQLite READONLY still writes WAL shared-memory read marks (and may create
+      // companions). Inspect a private coherent copy instead of touching foreign
+      // state. Do not copy -shm: SQLite reconstructs it ONLY in this private tree.
+      const scratch = mkdtempSync(join(tmpdir(), "pi-memoria-inspection-"));
+      const snapshot = join(scratch, "inspect.sqlite");
+      try {
+        for (let attempt = 0; ; attempt++) {
+          const originals: { name: string; info: Stats }[] = [];
+          const missing: string[] = [];
+          let changed = false;
+          for (const suffix of ["", "-wal", "-journal"]) {
+            const name = path + suffix, info = entry(name);
+            if (!info) { missing.push(name); continue; }
+            const source = openSync(name, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+            let target: number | undefined;
+            try {
+              const held = fstatSync(source);
+              if (!held.isFile() || held.nlink !== 1 || held.ino !== info.ino || held.dev !== info.dev) throw new Error("Unsafe database inspection identity.");
+              target = openSync(snapshot + suffix, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
+              const buffer = Buffer.allocUnsafe(64 * 1024);
+              let offset = 0;
+              while (offset < held.size) {
+                const count = readSync(source, buffer, 0, Math.min(buffer.length, Number(held.size) - offset), offset);
+                if (!count) { changed = true; break; }
+                let written = 0;
+                while (written < count) written += writeSync(target, buffer, written, count - written);
+                offset += count;
+              }
+              originals.push({ name, info: held });
+            } finally { closeSync(source); if (target !== undefined) closeSync(target); }
+          }
+          check();
+          if (missing.some(name => entry(name))) changed = true;
+          for (const { name, info } of originals) {
+            const now = entry(name);
+            if (!now || now.ino !== info.ino || now.dev !== info.dev || now.size !== info.size || now.mtimeMs !== info.mtimeMs || now.ctimeMs !== info.ctimeMs) changed = true;
+          }
+          if (!changed) { work(snapshot); return; }
+          for (const suffix of ["", "-wal", "-journal", "-shm"]) rmSync(snapshot + suffix, { force: true });
+          if (attempt >= 4) throw new Error("Database changed during ownership inspection.");
+          Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 10);
+        }
+      } finally { rmSync(scratch, { recursive: true, force: true }); }
+    },
+    privateMode() {
+      check();
+      const fd = openSync(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+      try {
+        const held = fstatSync(fd), named = check();
+        if (!held.isFile() || held.nlink !== 1 || !named || named.ino !== held.ino || named.dev !== held.dev) throw new Error("Database identity changed.");
+        fchmodSync(fd, 0o600);
+      } finally { closeSync(fd); }
+    },
+  };
+}

package/src/database-schema.ts

@@ -0,0 +1,64 @@
+import { DatabaseSync } from "node:sqlite";
+
+export const APPLICATION_ID = 0x4d454d4f; // MEMO. Pre-identifier v1/v2 stores remain supported.
+export const INITIAL_SCHEMA = `
+  CREATE TABLE memories (
+    rowid INTEGER PRIMARY KEY,
+    id TEXT NOT NULL UNIQUE,
+    content TEXT NOT NULL,
+    tags TEXT NOT NULL DEFAULT '[]',
+    tag_text TEXT NOT NULL DEFAULT '',
+    source TEXT NOT NULL DEFAULT '',
+    created_at TEXT NOT NULL,
+    updated_at TEXT NOT NULL,
+    revision INTEGER NOT NULL DEFAULT 1
+  ) STRICT;
+  CREATE VIRTUAL TABLE memories_fts USING fts5(
+    content, tag_text, source, content='memories', content_rowid='rowid',
+    tokenize='porter unicode61 remove_diacritics 2', prefix='2 3'
+  );
+  CREATE TRIGGER memories_insert AFTER INSERT ON memories BEGIN
+    INSERT INTO memories_fts(rowid, content, tag_text, source) VALUES(new.rowid, new.content, new.tag_text, new.source);
+  END;
+  CREATE TRIGGER memories_delete AFTER DELETE ON memories BEGIN
+    INSERT INTO memories_fts(memories_fts, rowid, content, tag_text, source)
+      VALUES('delete', old.rowid, old.content, old.tag_text, old.source);
+  END;
+  CREATE TRIGGER memories_update AFTER UPDATE ON memories BEGIN
+    INSERT INTO memories_fts(memories_fts, rowid, content, tag_text, source)
+      VALUES('delete', old.rowid, old.content, old.tag_text, old.source);
+    INSERT INTO memories_fts(rowid, content, tag_text, source) VALUES(new.rowid, new.content, new.tag_text, new.source);
+  END;
+  CREATE TABLE session_roots (path TEXT PRIMARY KEY) STRICT;
+  PRAGMA user_version=1;
+`;
+export const VERSION_TWO = "CREATE INDEX memories_content ON memories(content); PRAGMA user_version=2;";
+
+const schemas = new Map<number, string>();
+function fingerprint(db: DatabaseSync): string {
+  return JSON.stringify(db.prepare("SELECT type,name,tbl_name,sql FROM sqlite_master ORDER BY type,name").all().map(row => ({
+    ...row, sql: typeof row.sql === "string" ? row.sql.replace(/\s+/g, " ").trim() : row.sql,
+  })));
+}
+function recognized(version: number): string {
+  let value = schemas.get(version);
+  if (value) return value;
+  // Build signatures of the schemas actually shipped by this package, including
+  // FTS shadow objects/autoindexes. This template is memory-only, never a fixture
+  // or mutation of the configured path.
+  const template = new DatabaseSync(":memory:");
+  try {
+    template.exec(INITIAL_SCHEMA);
+    if (version === 2) template.exec(VERSION_TWO);
+    value = fingerprint(template); schemas.set(version, value); return value;
+  } finally { template.close(); }
+}
+export function attestSchema(db: DatabaseSync): number {
+  const version = Number(db.prepare("PRAGMA user_version").get()?.user_version);
+  const application = Number(db.prepare("PRAGMA application_id").get()?.application_id);
+  if (version > 2) throw new Error(`Database schema ${version} is newer than this pi-memoria version.`);
+  if (application !== 0 && application !== APPLICATION_ID) throw new Error("Unrecognized database application.");
+  if (version === 0 && application === 0 && db.prepare("SELECT COUNT(*) AS n FROM sqlite_master").get()?.n === 0) return 0;
+  if ((version !== 1 && version !== 2) || fingerprint(db) !== recognized(version)) throw new Error("Unsupported or unrelated memoria database schema.");
+  return version;
+}

package/src/database.ts

@@ -1,6 +1,7 @@
 import { createHash, randomUUID } from "node:crypto";
-import { chmodSync, mkdirSync } from "node:fs";
 import { dirname, resolve } from "node:path";
+import { databasePath } from "./database-path.ts";
+import { APPLICATION_ID, INITIAL_SCHEMA, VERSION_TWO, attestSchema } from "./database-schema.ts";
 import { DatabaseSync, type StatementSync } from "node:sqlite";
 import { expandQuery, loadAliases, type AliasConfiguration } from "./aliases.ts";
 import { ExpectedError, isSqliteError, storeUnavailable } from "./errors.ts";
@@ -52,55 +53,35 @@ export class MemoryDatabase {
   private closed = false;
 
   constructor(readonly path: string, private readonly aliasesPath?: string) {
-    try { mkdirSync(dirname(path), { recursive: true, mode: 0o700 }); }
-    catch (error) { throw storeUnavailable("open", path, error); }
-    try { this.db = new DatabaseSync(path); }
-    catch (error) { throw storeUnavailable("open", path, error); }
+    let location: ReturnType<typeof databasePath>;
     try {
-      chmodSync(path, 0o600);
-      this.db.exec("PRAGMA busy_timeout=5000; PRAGMA journal_mode=WAL; PRAGMA synchronous=FULL;");
+      location = databasePath(path);
+      // A rejected existing database never receives a writable connection, chmod,
+      // journal-mode change or migration. Version zero alone is not ownership.
+      const existing = location.check();
+      if (existing) {
+        location.inspect(snapshot => {
+          const inspection = new DatabaseSync(snapshot);
+          try { inspection.exec("PRAGMA busy_timeout=5000; BEGIN"); attestSchema(inspection); }
+          finally { inspection.close(); }
+        });
+      }
+      location.check();
+      this.db = new DatabaseSync(location.path);
+    } catch (error) { throw storeUnavailable("open", path, error); }
+    try {
+      this.db.exec("PRAGMA busy_timeout=5000;");
       this.db.function("memoria_fold", { deterministic: true }, (value) => String(value).toLowerCase());
       this.transaction(() => {
-        const version = Number(this.db.prepare("PRAGMA user_version").get()?.user_version);
-        if (version > 2) throw new Error(`Database schema ${version} is newer than this pi-memoria version.`);
-        if (version === 0) {
-          this.db.exec(`
-            CREATE TABLE memories (
-              rowid INTEGER PRIMARY KEY,
-              id TEXT NOT NULL UNIQUE,
-              content TEXT NOT NULL,
-              tags TEXT NOT NULL DEFAULT '[]',
-              tag_text TEXT NOT NULL DEFAULT '',
-              source TEXT NOT NULL DEFAULT '',
-              created_at TEXT NOT NULL,
-              updated_at TEXT NOT NULL,
-              revision INTEGER NOT NULL DEFAULT 1
-            ) STRICT;
-            CREATE VIRTUAL TABLE memories_fts USING fts5(
-              content, tag_text, source, content='memories', content_rowid='rowid',
-              tokenize='porter unicode61 remove_diacritics 2', prefix='2 3'
-            );
-            CREATE TRIGGER memories_insert AFTER INSERT ON memories BEGIN
-              INSERT INTO memories_fts(rowid, content, tag_text, source) VALUES(new.rowid, new.content, new.tag_text, new.source);
-            END;
-            CREATE TRIGGER memories_delete AFTER DELETE ON memories BEGIN
-              INSERT INTO memories_fts(memories_fts, rowid, content, tag_text, source)
-                VALUES('delete', old.rowid, old.content, old.tag_text, old.source);
-            END;
-            CREATE TRIGGER memories_update AFTER UPDATE ON memories BEGIN
-              INSERT INTO memories_fts(memories_fts, rowid, content, tag_text, source)
-                VALUES('delete', old.rowid, old.content, old.tag_text, old.source);
-              INSERT INTO memories_fts(rowid, content, tag_text, source) VALUES(new.rowid, new.content, new.tag_text, new.source);
-            END;
-            CREATE TABLE session_roots (path TEXT PRIMARY KEY) STRICT;
-            PRAGMA user_version=1;
-          `);
-        }
-        if (version < 2) {
-          // Keep existing duplicates and archive evidence intact; serialize new adds below.
-          this.db.exec("CREATE INDEX memories_content ON memories(content); PRAGMA user_version=2;");
-        }
+        // Re-attest under the writer transaction for concurrent initialization.
+        const version = attestSchema(this.db);
+        location.check();
+        if (version === 0) this.db.exec(INITIAL_SCHEMA);
+        if (version < 2) this.db.exec(VERSION_TWO);
+        this.db.exec(`PRAGMA application_id=${APPLICATION_ID};`);
       });
+      location.privateMode();
+      this.db.exec("PRAGMA journal_mode=WAL; PRAGMA synchronous=FULL;");
     } catch (error) {
       this.closed = true;
       try { this.db.close(); } catch { /* keep the original failure */ }

package/src/sessions.ts

@@ -98,8 +98,30 @@ function rgText(value: unknown): string {
   throw new Error("ripgrep returned an invalid text record.");
 }
 
+/** Try at most two binaries, only falling back when spawning reports ENOENT. */
+async function startRipgrep(executables: string[], args: string[], signal?: AbortSignal) {
+  for (const [index, executable] of executables.entries()) {
+    signal?.throwIfAborted();
+    const child = spawn(executable, args, { shell: false, stdio: ["ignore", "pipe", "pipe"], windowsHide: true });
+    try {
+      await new Promise<void>((done, fail) => {
+        child.once("spawn", done);
+        child.once("error", fail);
+      });
+      return { child, executable };
+    } catch (error) {
+      signal?.throwIfAborted();
+      if ((error as NodeJS.ErrnoException).code === "ENOENT" && index + 1 < executables.length) continue;
+      throw new Error(`Cannot run ripgrep (${executable}): ${(error as Error).message}. Install rg and ensure it is on PATH, or provision Pi's managed binary. Checked: ${executables.join(", ")}. Session search is incomplete.`);
+    }
+  }
+  throw new Error("No ripgrep executable configured.");
+}
+
 export class SessionSearch {
-  constructor(private roots: () => string[], private executable = "rg") {}
+  // An explicit executable remains authoritative. Otherwise prefer Pi's managed
+  // binary when supplied, then inherited PATH. Resolve anew on every search.
+  constructor(private roots: () => string[], private executable?: string, private managedExecutable?: string) {}
 
   async search(input: SessionQuery, signal?: AbortSignal) {
     signal?.throwIfAborted();
@@ -137,7 +159,9 @@ export class SessionSearch {
       const patterns = query && terms.length ? [...new Set([...rawTerms, ...terms.map((term) => JSON.stringify(term).slice(1, -1)), "\\u", "\\/"])] : [""];
       for (const pattern of patterns) args.push("-e", pattern);
       args.push("--", ...coverage.roots);
-      const child = spawn(this.executable, args, { shell: false, stdio: ["ignore", "pipe", "pipe"], windowsHide: true });
+      const executables = this.executable !== undefined ? [this.executable]
+        : this.managedExecutable ? [this.managedExecutable, "rg"] : ["rg"];
+      const { child, executable } = await startRipgrep(executables, args, signal);
       let spawnError: Error | undefined;
       let stderr = "";
       child.stderr.setEncoding("utf8");
@@ -201,7 +225,7 @@ export class SessionSearch {
         signal?.removeEventListener("abort", abort);
       }
       signal?.throwIfAborted();
-      if (spawnError) throw new Error(`Cannot run ripgrep (${this.executable}): ${spawnError.message}. Install rg and ensure it is on PATH.`);
+      if (spawnError) throw new Error(`Cannot run ripgrep (${executable}): ${spawnError.message}. Session search is incomplete.`);
       const code = await completion;
       if (stderr.trim()) coverage.warnings.push(`ripgrep: ${stderr.trim()}`);
       if (!hasMore && !timedOut && code !== 0 && code !== 1) coverage.warnings.push(`ripgrep stopped with exit code ${code}; search is incomplete.`);