pi-memoria 0.3.1 → 0.3.3

package/AGENTS.md

@@ -1,7 +1,7 @@
 # Working on pi-memoria
 
 This is a TypeScript Pi extension with five tools and **one global memory store**.
-README.md documents the product; this file documents how to change and release the repository.
+README.md documents the product; this file documents how to change this package. Read the [monorepo instructions](https://github.com/rcsaquino/pi-extensions/blob/main/AGENTS.md) and [release process](https://github.com/rcsaquino/pi-extensions/blob/main/RELEASING.md) for shared tooling and authorized publication.
 
 ## North star
 
@@ -13,7 +13,9 @@ README.md documents the product; this file documents how to change and release t
 
 ## Commands
 
-- `npm ci --ignore-scripts`: install the locked development dependencies.
+From this package directory; from the monorepo root, use `npm --prefix packages/pi-memoria` before the same operation.
+
+- `npm install --ignore-scripts --legacy-peer-deps --workspaces=false`: install package-local development dependencies. No lockfile is currently committed; use `npm ci` only after a usable lock is deliberately supplied.
 - `npm run check`: strict TypeScript checking.
 - `npm test`: storage, concurrency, retrieval, and Pi integration tests; uses temporary directories.
 - `npm run verify`: typecheck and tests.
@@ -26,6 +28,7 @@ README.md documents the product; this file documents how to change and release t
 - `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.
@@ -51,59 +54,22 @@ README.md documents the product; this file documents how to change and release t
 
 ## Development conventions
 
-Use explicit `.ts` imports, strict types, Node built-ins, and small modules. Pi loads TypeScript directly; there is no build step. Keep the peer dependency ranges required by Pi packaging; pin the tested Pi version in devDependencies. Update package-lock.json through npm when dependencies change.
+Use explicit `.ts` imports, strict types, Node built-ins, and small modules. Pi loads TypeScript directly; there is no build step. Keep the peer dependency ranges required by Pi packaging; pin the tested Pi version in devDependencies. If maintaining a lockfile, update it through npm when dependencies change; never edit it manually or introduce root dependency hoisting as an unrelated fix.
 
-Read the installed Pi documentation and relevant examples before changing integration code. The reference installation for this workspace is `/home/rcsaquino/.npm-global/lib/node_modules/@earendil-works/pi-coding-agent/`; resolve `docs/...` and `examples/...` there, not here. Read referenced Markdown files completely. Check exported declarations for exact API signatures.
+Read the installed Pi documentation and relevant examples before changing integration code. Locate the host with `npm root -g`, then its `@earendil-works/pi-coding-agent` package (or the configured `PI_HOST_PACKAGE_DIR` for development tooling); resolve `docs/...` and `examples/...` there, not here. Read referenced Markdown files completely. Check exported declarations for exact API signatures.
 
 Add meaningful regression tests for cap boundaries, races, durable retrieval, pagination, and error paths when changing them. Run `npm run verify` before delivery. Benchmark claims must state corpus size and distinguish indexed SQLite lookups from linear session scans.
 
 ## Releasing
 
-Start a release only when the user decides to bump the version. Tags, GitHub releases, and npm versions are public and are not cleanly removable.
-
-1. Bump `version` in `package.json`, then run `npm run verify`. A version-only bump does not change dependencies, so `package-lock.json` needs no update.
-2. Commit as `Release X.Y.Z` and push `main`.
-3. Create an annotated tag `vX.Y.Z` with the message `pi-memoria X.Y.Z` (the convention for `v0.2.0` and later) and push it with the commit:
-
-    ```sh
-    git tag -a vX.Y.Z -m "pi-memoria X.Y.Z"
-    git push origin main vX.Y.Z
-    ```
-
-4. Create the GitHub release after the tag exists. Publishing the release triggers
-   `.github/workflows/npm-publish.yml`, which checks the tag against `package.json`, runs
-   `npm run verify`, and publishes to npm. `gh` is installed and authenticated as
-   `rcsaquino`:
-
-    ```sh
-    gh release create vX.Y.Z --title "pi-memoria X.Y.Z" --notes-file - <<'EOF'
-    ...
-    EOF
-    ```
-
-    Keep notes factual: what changed, requirements, and limits. Do not restate the README.
-
-5. Watch the workflow and confirm the registry:
-
-    ```sh
-    gh run list --workflow npm-publish.yml --limit 4
-    npm view pi-memoria version dist-tags
-    ```
-
-    - The workflow authenticates with npm trusted publishing (OIDC). The trusted publisher
-      on npmjs.com must name the repository `rcsaquino/pi-memoria` and the workflow file
-      `npm-publish.yml`. The package's publishing access disallows traditional tokens,
-      so OIDC is the only automated publish path.
-    - The `files` field in `package.json` controls the tarball; inspect it with
-      `npm pack --dry-run` first.
-    - The registry can accept the tarball (`HTTP 202`, "being processed") and take a few
-      minutes to expose it. Confirm with `npm view` before reporting success.
-    - Fallback only if the workflow is unavailable: `npm publish` locally. Writes require
-      2FA, so it starts the npmjs web-auth flow and needs a real terminal or pseudo-TTY to
-      open the browser; without one it fails with `EOTP`. An automation token with 2FA
-      bypass also works.
-
-Only push tags, create releases, or publish to npm for a user-requested version bump.
+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.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.
+- Confirm the exact published version and dist-tag from the public registry before reporting success. Keep release notes factual and specific to this package.
 
 ## Files and data to protect
 

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 Rey Christian
+Copyright (c) 2026 rcsaquino
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -5,7 +5,6 @@
 
 **Global memory for [Pi](https://github.com/earendil-works/pi): startup rules in `MEMORY.md`, durable facts in SQLite FTS5, and cited search across every past conversation.**
 
-[![GitHub release](https://img.shields.io/github/v/release/rcsaquino/pi-memoria?style=flat-square)](https://github.com/rcsaquino/pi-memoria/releases)
 [![Node.js >= 22.19](https://img.shields.io/badge/Node.js-%3E%3D22.19-3c873a?style=flat-square&logo=nodedotjs&logoColor=white)](https://nodejs.org)
 [![TypeScript](https://img.shields.io/badge/TypeScript-3178c6?style=flat-square&logo=typescript&logoColor=white)](https://www.typescriptlang.org)
 [![MIT license](https://img.shields.io/badge/license-MIT-yellow?style=flat-square)](LICENSE)
@@ -18,9 +17,9 @@ pi-memoria gives Pi one memory shared across every project: instructions that mu
 
 ## Requirements
 
-- **Node.js 22.19+** (uses `node:sqlite`; tested on 22.19 and 24.20).
-- **Pi** with the current extension API (tested with 0.87.1), Node-based. Standalone/Bun builds are not validated with `node:sqlite`.
-- **ripgrep (`rg`) on PATH** for session search.
+- **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`)**, either on PATH or in Pi's managed `<agent-dir>/bin/` directory, for session search.
 
 ## Installation
 
@@ -28,20 +27,24 @@ pi-memoria gives Pi one memory shared across every project: instructions that mu
 pi install npm:pi-memoria
 ```
 
-Restart Pi or run `/reload`. To uninstall, run `pi remove npm:pi-memoria`; stored memory remains until you delete its directory.
+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.
 
 <details>
 <summary><strong>Install from a local checkout</strong></summary>
 
+From the monorepo root:
+
 ```sh
-npm ci --ignore-scripts
-pi install /absolute/path/to/pi-memoria
+npm --prefix packages/pi-memoria install --ignore-scripts --legacy-peer-deps --workspaces=false
+pi install /absolute/path/to/pi-extensions/packages/pi-memoria
 ```
 
 Keep the checkout in place: a local install references it directly. To try it without installing:
 
 ```sh
-pi -e /absolute/path/to/pi-memoria/index.ts
+pi -e /absolute/path/to/pi-extensions/packages/pi-memoria/index.ts
 ```
 
 </details>
@@ -129,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 |
 
@@ -143,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>
@@ -168,12 +179,17 @@ The default session root is `<agent-dir>/sessions`; roots Pi uses are remembered
 
 ## Development
 
+From the monorepo root:
+
 ```sh
-npm ci --ignore-scripts
-npm run verify
-npm run bench
+npm --prefix packages/pi-memoria install --ignore-scripts --legacy-peer-deps --workspaces=false
+npm run link-host
+npm --prefix packages/pi-memoria run verify
+npm --prefix packages/pi-memoria run bench
 ```
 
+No package lockfile is currently committed, so `npm ci` is not a fresh-checkout setup command. The shared host-link helper preserves working dependencies and only repairs missing/broken links.
+
 There is no build step: Pi loads `index.ts` directly. `src/database.ts`, `src/hot-memory.ts`, and `src/sessions.ts` own the storage layers; `index.ts` wires them to lifecycle events and the tool schemas. Tests use temporary directories, real SQLite FTS5, real `rg`, concurrent writers, and Pi's extension loader. See [AGENTS.md](AGENTS.md) for architecture and contribution rules.
 
 ## Support and contact

package/index.ts

@@ -15,7 +15,7 @@ import { chunk, HOT_LIMIT, MEMORY_LIMIT } from "./src/text.ts";
 const SAVE_GUIDANCE = "Before saving a durable fact, search SQLite with memoria_search using topic keywords and aliases, and inspect relevant matches. If the same fact is already stored, do not add it again; use memoria_edit with its ID only when information changes or useful detail is missing. Different wording can express the same fact. For hot memory, check the injected MEMORY.md before adding a bullet.";
 
 export const MEMORY_GUIDANCE = `You have global, persistent memory shared across all projects.
-- MEMORY.md below is working memory, available before every user prompt. Store only requirements needed without a retrieval cue, e.g. "Start every sentence with beep_boop." Topic-triggered facts such as liking apples belong in SQLite, tagged with useful retrieval cues such as fruit and preferences.
+- The hot_memory block contains standing instructions from MEMORY.md, available before every user prompt, not merely quoted reference material. Follow them subject to higher-priority instructions and the conflict guidance below. Store only requirements needed without a retrieval cue, e.g. "Start every sentence with beep_boop." Topic-triggered facts such as liking apples belong in SQLite, tagged with useful retrieval cues such as fruit and preferences.
 - Proactively save durable user instructions, preferences, and decisions with memoria_add; update corrections with memoria_edit and remove obsolete facts with memoria_delete. Do not save guesses as facts or secrets unless explicitly requested. Use the memory tools for writes, not direct file/database edits.
 - ${SAVE_GUIDANCE}
 - For hot writes use store="hot", content, and optional priority. Hot content must be one line and internal spacing is preserved. Tags and source are SQLite metadata; omit them for hot memory.
@@ -116,21 +116,23 @@ export default function memoria(pi: ExtensionAPI) {
   });
 
   pi.on("before_agent_start", async (event, ctx) => {
-    let text = MEMORY_GUIDANCE;
+    let text = `<instructions>\n${MEMORY_GUIDANCE}\n</instructions>`;
+    const status: string[] = [];
     const current = stores(ctx);
     try {
       const snapshot = await current.hot.load();
-      text += `\n\nGlobal MEMORY.md (${snapshot.characters}/${HOT_LIMIT} characters; ${current.config.hotPath}):\n${snapshot.text || "(empty)"}`;
+      text += `\n\n<hot_memory>\nGlobal MEMORY.md (${snapshot.characters}/${HOT_LIMIT} characters; ${current.config.hotPath}):\n${snapshot.text || "(empty)"}\n</hot_memory>`;
       for (const repaired of [startupRepair, snapshot]) {
-        if (repaired?.archived.length) text += `\nRepaired an oversized manual edit: ${repaired.archived.length} bullets archived to SQLite; original backup: ${repaired.backup}.`;
+        if (repaired?.archived.length) status.push(`Repaired an oversized manual edit: ${repaired.archived.length} bullets archived to SQLite; original backup: ${repaired.backup}.`);
       }
       startupRepair = undefined;
     } catch (error) {
-      text += `\n\nMEMORY UNAVAILABLE: ${(error as Error).message}. Hot instructions were not loaded; tell the user and do not assume that memory is empty.`;
+      status.push(`MEMORY UNAVAILABLE: ${(error as Error).message}. Hot instructions were not loaded; tell the user and do not assume that memory is empty.`);
     }
     if (!current.database && current.databaseError !== undefined) {
-      text += `\n\nSQLITE LONG-TERM MEMORY UNAVAILABLE: ${(current.databaseError as Error).message}. Hot memory above remains valid; SQLite add/edit/delete/search and archive operations fail until the store is fixed. Session search uses default, configured, and current roots only, so remembered custom roots may be missing.`;
+      status.push(`SQLITE LONG-TERM MEMORY UNAVAILABLE: ${(current.databaseError as Error).message}. Any successfully loaded hot memory remains valid; SQLite add/edit/delete/search and archive operations fail until the store is fixed. Session search uses default, configured, and current roots only, so remembered custom roots may be missing.`);
     }
+    if (status.length) text += `\n\n<status>\n${status.join("\n")}\n</status>`;
     event.systemPromptOptions.sections.pi_memoria = text;
     // Respect earlier extensions that supply an opaque, complete system prompt.
     if (event.systemPromptOptions.forceSystemPrompt !== undefined) {
@@ -284,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,10 +1,13 @@
 {
   "name": "pi-memoria",
-  "version": "0.3.1",
+  "version": "0.3.3",
   "description": "Global working memory, SQLite FTS5 recall, and complete Pi session search",
   "type": "module",
   "license": "MIT",
-  "repository": { "type": "git", "url": "git+https://github.com/rcsaquino/pi-memoria.git" },
+  "repository": { "type": "git", "url": "git+https://github.com/rcsaquino/pi-extensions.git", "directory": "packages/pi-memoria" },
+  "homepage": "https://github.com/rcsaquino/pi-extensions/tree/main/packages/pi-memoria#readme",
+  "bugs": { "url": "https://github.com/rcsaquino/pi-extensions/issues" },
+  "publishConfig": { "access": "public" },
   "keywords": ["pi-package", "pi-extension", "memory", "sqlite", "fts5"],
   "files": ["index.ts", "src", "README.md", "AGENTS.md", "LICENSE"],
   "pi": { "extensions": ["./index.ts"] },
@@ -21,7 +24,7 @@
     "typebox": "*"
   },
   "devDependencies": {
-    "@earendil-works/pi-coding-agent": "0.87.1",
+    "@earendil-works/pi-coding-agent": "1.0.0",
     "@types/node": "^22.19.0",
     "@types/proper-lockfile": "^4.1.4",
     "tsx": "^4.20.0",

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.`);