pi-sessions 0.15.0 → 0.16.0

package/README.md

@@ -51,9 +51,8 @@ pi -e /absolute/path/to/pi-sessions
 ## Quick start
 
 1. Install the package.
-2. Open Pi and run `/session-index`.
-3. Press `r` to build the index for all your prior sessions.
-4. Try the main flows:
+2. Open Pi. Your prior sessions are indexed automatically in the background.
+3. Try the main flows:
 
 ```text
 What session did I implement the db layer?
@@ -75,7 +74,7 @@ Open the frontend implementation task in a session to the right.
 | Session Index      | `/session-index` slash command                                         | Shows index status and rebuilds the local session index |
 | Session Auto Title | in background, `/title` slash command                                  | Give sessions titles                                    |
 
-Every feature is on by default. Turn one off with `enable: false` under its own settings namespace, which unregisters its tools and hooks.
+Every feature is on by default. Turn one off with `enable: false` under its own settings namespace. Index recovery and startup/switch sync always run, including when search is disabled. `hooks.enable` controls turn, tree, and compaction sync, not startup recovery.
 
 ```json
 {
@@ -230,12 +229,11 @@ Subagents require the handoff and messaging features. Limit recursive delegation
 
 ## Session Index
 
-By default, `pi-sessions` will start indexing all conversations moving forward. If you want to backfill all prior conversations:
+The index is a shared cache of your transcripts, used by search, messaging, and the other session features. Pi checks transcripts at startup and syncs files that changed, including sessions run without pi-sessions loaded. Missing, older-schema, or unreadable indexes rebuild automatically in the background; unreadable databases are moved aside rather than overwritten. A malformed transcript is skipped and reported.
 
-- run `/session-index`
-- hit `r` to (re)index everything
+During recovery, a tool may say "Session indexing in progress; try again shortly." Only one process rebuilds at a time, and readers retain the old index until its replacement is ready. Failed attempts share a backoff of 1 minute, then 5 minutes, then 30 minutes. `/session-index` shows status; press `r` to rebuild now, ignoring the backoff.
 
-this is idempotent, so if you run into any issues, or disable pi-sessions for a while, feel free to re-index to see if that resolves anything.
+If another Pi writes a newer index schema, the older process stops using the index and displays "pi-sessions was updated; /reload to use it". Reload instead of rebuilding: older code cannot replace a newer schema.
 
 By default the index lives at:
 

package/extensions/pi-sessions.ts

@@ -156,9 +156,7 @@ export default function piSessions(pi: ExtensionAPI): void {
       }),
     );
   }
-  if (settings.features.hooks) {
-    lifecycles.push(installHooks(pi, { index }));
-  }
+  lifecycles.push(index, installHooks(pi, { index, turnSync: settings.features.hooks }));
   // Messaging leads every session_start so the broker connection is registered before any
   // other feature hook runs. A side effect is that messaging's first relation snapshot can
   // predate hooks' index sync for this session; getCachedRelationTo self-heals on miss, so

package/extensions/session-handoff/metadata.ts

@@ -10,6 +10,8 @@ import {
 } from "./launch-target.ts";
 
 export const HANDOFF_METADATA_CUSTOM_TYPE = "pi-sessions.handoff";
+// Agent Switchboard's swb adopt (packages/cli/src/commands/adopt.ts) reads this
+// customType and data.subagent; renaming either breaks its subagent check.
 export const HANDOFF_BOOTSTRAP_PENDING_CUSTOM_TYPE = "pi-sessions.handoff-bootstrap";
 export const HANDOFF_BOOTSTRAP_CONSUMED_CUSTOM_TYPE = "pi-sessions.handoff-bootstrap-consumed";
 export const HANDOFF_BOOTSTRAP_FAILED_CUSTOM_TYPE = "pi-sessions.handoff-bootstrap-failed";

package/extensions/session-handoff/query.ts

@@ -1,5 +1,6 @@
 import { stripSearchSnippetMarkers } from "../shared/search-snippet.ts";
 import {
+  formatRequiredSessionIndexError,
   getSessionByPath,
   type SearchSessionResult,
   type SessionIndexDatabase,
@@ -100,7 +101,7 @@ export function listSessionPickerItems(
           defaultScopeLabel,
         };
       }) ?? {
-        items: [buildIndexErrorItem()],
+        items: [buildIndexErrorItem(options.indexPath)],
         scopeMode,
         defaultScopeLabel,
       }
@@ -309,11 +310,11 @@ function getSessionMarker(
   }
 }
 
-function buildIndexErrorItem(): SessionPickerNoticeItem {
+function buildIndexErrorItem(indexPath: string): SessionPickerNoticeItem {
   return {
     kind: "error",
-    title: "Session index missing or incompatible",
-    description: "Run /session-index to rebuild it.",
+    title: "Session index unavailable",
+    description: formatRequiredSessionIndexError(indexPath),
   };
 }
 

package/extensions/session-hooks/install.ts

@@ -3,28 +3,37 @@ import {
   findPendingHandoffBootstrap,
   getHandoffMetadataFromEntries,
 } from "../session-handoff/metadata.ts";
-import { createSessionHookController } from "../session-search/hooks.ts";
 import type { IndexHandle, SessionLifecycle } from "../shared/composition.ts";
+import { requestIndexRecovery } from "../shared/session-index/recovery.ts";
+import { createSessionHookController } from "../shared/session-index/sync.ts";
 
-export function installHooks(pi: ExtensionAPI, deps: { index: IndexHandle }): SessionLifecycle {
+export function installHooks(
+  pi: ExtensionAPI,
+  deps: { index: IndexHandle; turnSync: boolean },
+): SessionLifecycle {
   const controller = createSessionHookController({ indexPath: deps.index.path });
 
   pi.on("turn_end", async (_event, ctx) => {
-    await controller.handleTurnEnd(ctx.sessionManager.getSessionFile());
+    if (deps.turnSync) await controller.handleTurnEnd(ctx.sessionManager.getSessionFile());
   });
 
   pi.on("session_tree", async (_event, ctx) => {
-    await controller.handleSessionTree(ctx.sessionManager.getSessionFile());
+    if (deps.turnSync) await controller.handleSessionTree(ctx.sessionManager.getSessionFile());
   });
 
   pi.on("session_compact", async (_event, ctx) => {
-    await controller.handleSessionCompact(ctx.sessionManager.getSessionFile());
+    if (deps.turnSync) await controller.handleSessionCompact(ctx.sessionManager.getSessionFile());
   });
 
   return {
     async onSessionStart(event, ctx) {
       const { reason, previousSessionFile } = event;
       const sessionFile = ctx.sessionManager.getSessionFile();
+      void requestIndexRecovery(deps.index.path, true)
+        .then(() => controller.handleSessionStart(ctx.sessionManager.getSessionFile()))
+        .catch((error: unknown) =>
+          ctx.ui.notify(`Session index sync failed: ${String(error)}`, "error"),
+        );
 
       switch (reason) {
         case "new":

package/extensions/session-index/install.ts

@@ -1,15 +1,24 @@
 import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
-import { type ReindexResult, rebuildSessionIndex } from "../session-search/reindex.ts";
-import type { IndexHandle } from "../shared/composition.ts";
+import type { IndexHandle, SessionLifecycle } from "../shared/composition.ts";
 import { isTuiMode } from "../shared/pi-mode.ts";
 import { getIndexStatus } from "../shared/session-index/index.ts";
+import {
+  getIndexRecoveryMessage,
+  observeIndexRecovery,
+  type ReindexResult,
+  rebuildSessionIndex,
+} from "../shared/session-index/recovery.ts";
 import type { SessionSettings } from "../shared/settings.ts";
 
 import { ReindexLoader } from "./loader.ts";
 import { type SessionIndexAction, SessionIndexPanel } from "./panel.ts";
 
-export function installIndex(pi: ExtensionAPI, deps: { settings: SessionSettings }): IndexHandle {
+export function installIndex(
+  pi: ExtensionAPI,
+  deps: { settings: SessionSettings },
+): IndexHandle & SessionLifecycle {
   const indexPath = deps.settings.index.path;
+  let lastNotice: string | undefined;
 
   pi.registerCommand("session-index", {
     description: "Open the session index control panel",
@@ -20,6 +29,7 @@ export function installIndex(pi: ExtensionAPI, deps: { settings: SessionSettings
       }
 
       const status = getIndexStatus(indexPath);
+      status.recoveryMessage = getIndexRecoveryMessage(indexPath);
       const action = await ctx.ui.custom<SessionIndexAction>(
         (tui, theme, _keybindings, done) =>
           new SessionIndexPanel(theme, status, done, () => tui.requestRender()),
@@ -59,7 +69,18 @@ export function installIndex(pi: ExtensionAPI, deps: { settings: SessionSettings
     },
   });
 
-  return { path: indexPath };
+  return {
+    path: indexPath,
+    onSessionStart(_event, ctx) {
+      observeIndexRecovery(indexPath, (message) => {
+        ctx.ui.setStatus("session-index", message);
+        if (message && message !== lastNotice && !message.includes("in progress")) {
+          ctx.ui.notify(message, "error");
+        }
+        lastNotice = message;
+      });
+    },
+  };
 }
 
 async function runReindexWithLoader(

package/extensions/session-index/panel.ts

@@ -6,6 +6,7 @@ import {
   type TuiMouseEventResult,
   truncateToWidth,
   visibleWidth,
+  wrapTextWithAnsi,
 } from "@earendil-works/pi-tui";
 import { type LegendHit, LegendPointer, layoutLegend, legendHitAt } from "../shared/legend.ts";
 import type { SessionIndexStatus } from "../shared/session-index/index.ts";
@@ -73,6 +74,14 @@ export class SessionIndexPanel implements Focusable {
     lines.push(
       this.renderRow(innerWidth, ` Last full reindex: ${this.status.lastFullReindexAt ?? "n/a"}`),
     );
+    if (this.status.recoveryMessage) {
+      for (const line of wrapTextWithAnsi(
+        this.status.recoveryMessage,
+        Math.max(1, innerWidth - 2),
+      )) {
+        lines.push(this.renderRow(innerWidth, ` ${this.theme.fg("warning", line)}`));
+      }
+    }
     lines.push(this.renderRow(innerWidth, ""));
     this.renderAction(lines, innerWidth, "R", "rebuild from disk", () => this.done("reindex"));
     this.renderAction(lines, innerWidth, "Enter / Esc", "close", () => this.done(undefined));

package/extensions/shared/session-index/access.ts

@@ -6,6 +6,13 @@ import {
   type SessionIndexDatabase,
   type SessionIndexStatus,
 } from "./common.ts";
+import {
+  acquireIndexLock,
+  disableOlderIndexClient,
+  getIndexRecoveryMessage,
+  isIndexClientDisabled,
+  requestIndexRecovery,
+} from "./recovery.ts";
 import { getMetadata, openIndexDatabase } from "./schema.ts";
 
 export type SessionIndexOpenMode = "read" | "write";
@@ -67,28 +74,57 @@ function openValidatedSessionIndexInternal(
   indexPath: string,
   options: WithSessionIndexOptions,
 ): ValidSessionIndex | undefined {
+  if (isIndexClientDisabled(indexPath)) return handleUnavailableIndex(indexPath, options);
   if (!existsSync(indexPath)) {
     return handleUnavailableIndex(indexPath, options);
   }
 
   let db: SessionIndexDatabase | undefined;
+  let release: (() => void) | undefined;
   try {
+    if (options.mode === "write") {
+      release = acquireIndexLock(indexPath);
+      if (!release) return handleUnavailableIndex(indexPath, options);
+    }
     db = openIndexDatabase(indexPath, {
       create: false,
-      mode: options.mode,
+      mode: "read",
       ...(options.timeoutMs === undefined ? {} : { timeoutMs: options.timeoutMs }),
     });
-    const status = getIndexStatusFromDb(indexPath, db);
-    if (status.schemaVersion !== INDEX_SCHEMA_VERSION) {
+    const version = Number(getMetadata(db, "schema_version"));
+    if (version !== INDEX_SCHEMA_VERSION) {
       const invalidDb = db;
       db = undefined;
       invalidDb.close();
+      release?.();
+      release = undefined;
+      if (version > INDEX_SCHEMA_VERSION) disableOlderIndexClient(indexPath);
       return handleUnavailableIndex(indexPath, options);
     }
-
+    const status = getIndexStatusFromDb(indexPath, db);
+    if (options.mode === "write") {
+      db.close();
+      db = undefined;
+      db = openIndexDatabase(indexPath, {
+        create: false,
+        mode: "write",
+        timeoutMs: options.timeoutMs,
+      });
+      const close = db.close;
+      const unlock = release;
+      db.close = () => {
+        try {
+          close();
+        } finally {
+          unlock?.();
+        }
+      };
+      release = undefined;
+    }
     return { db, status };
   } catch (error) {
     db?.close();
+    release?.();
     return handleUnavailableIndex(indexPath, options, error);
   }
 }
@@ -112,7 +148,7 @@ export function getIndexStatusFromDb(dbPath: string, db: SessionIndexDatabase):
 }
 
 export function formatRequiredSessionIndexError(indexPath: string): string {
-  return `Session index missing or incompatible at ${indexPath}. Run /session-index and press r to rebuild it.`;
+  return getIndexRecoveryMessage(indexPath) ?? "Session indexing in progress; try again shortly.";
 }
 
 function handleUnavailableIndex(
@@ -120,6 +156,7 @@ function handleUnavailableIndex(
   options: WithSessionIndexOptions,
   cause?: unknown,
 ): undefined {
+  if (!isIndexClientDisabled(indexPath)) void requestIndexRecovery(indexPath);
   if (!options.required) {
     return undefined;
   }

package/extensions/shared/session-index/common.ts

@@ -148,6 +148,7 @@ export interface SessionIndexStatus {
   schemaVersion?: number | undefined;
   sessionCount?: number | undefined;
   lastFullReindexAt?: string | undefined;
+  recoveryMessage?: string | undefined;
 }
 
 export type SessionIndexDatabase = SqliteDatabase;

package/extensions/shared/session-index/recovery.ts

@@ -0,0 +1,270 @@
+import { createHash, randomUUID } from "node:crypto";
+import { existsSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { setTimeout as delay, setImmediate as yieldToEventLoop } from "node:timers/promises";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import { type Static, Type } from "typebox";
+import { listSessionFiles } from "../../session-search/extract.ts";
+import { parseTypeBoxValue } from "../typebox.ts";
+import { INDEX_SCHEMA_VERSION, ROW_COUNT_SCHEMA, type SessionIndexDatabase } from "./common.ts";
+import {
+  ensureIndexDir,
+  getMetadata,
+  initializeSchema,
+  openIndexDatabase,
+  setMetadata,
+} from "./schema.ts";
+import { syncSessionFileWithDb } from "./sync.ts";
+
+export const INDEX_UPDATED_WARNING = "pi-sessions was updated; /reload to use it";
+const BUILD = `index-v${INDEX_SCHEMA_VERSION}:${createHash("sha256")
+  .update(
+    ["recovery.ts", "schema.ts", "sync.ts"]
+      .map((file) => readFileSync(new URL(file, import.meta.url)))
+      .join(""),
+  )
+  .digest("hex")
+  .slice(0, 16)}`;
+const FAILURE_SCHEMA = Type.Object({
+  attempts: Type.Integer({ minimum: 1 }),
+  nextAllowedAt: Type.Number(),
+  error: Type.String(),
+  build: Type.String(),
+});
+export type IndexRecoveryFailure = Static<typeof FAILURE_SCHEMA>;
+export interface ReindexResult {
+  sessionCount: number;
+  chunkCount: number;
+  indexPath: string;
+  skipped: string[];
+}
+const running = new Map<string, Promise<ReindexResult | undefined>>();
+const notices = new Map<string, (message: string | undefined) => void>();
+const shown = new Map<string, string>();
+const disabled = new Set<string>();
+
+export function observeIndexRecovery(
+  indexPath: string,
+  notify: (message: string | undefined) => void,
+): void {
+  notices.set(indexPath, notify);
+  const message = getIndexRecoveryMessage(indexPath);
+  notify(message);
+  if (message) shown.set(indexPath, message);
+}
+
+function report(indexPath: string, message: string): void {
+  if (shown.get(indexPath) === message) return;
+  shown.set(indexPath, message);
+  const notify = notices.get(indexPath);
+  if (notify) notify(message);
+  else console.error(message);
+}
+
+export function disableOlderIndexClient(indexPath: string): void {
+  disabled.add(indexPath);
+  report(indexPath, INDEX_UPDATED_WARNING);
+}
+
+export function isIndexClientDisabled(indexPath: string): boolean {
+  return disabled.has(indexPath);
+}
+
+export function readIndexRecoveryFailure(indexPath: string): IndexRecoveryFailure | undefined {
+  const file = `${indexPath}.failure.json`;
+  let raw: string;
+  try {
+    raw = readFileSync(file, "utf8");
+  } catch (error) {
+    if (error instanceof Error && "code" in error && error.code === "ENOENT") return undefined;
+    throw error;
+  }
+  return parseTypeBoxValue(FAILURE_SCHEMA, JSON.parse(raw), "Invalid index recovery record");
+}
+
+export function getIndexRecoveryMessage(indexPath: string): string | undefined {
+  if (disabled.has(indexPath)) return INDEX_UPDATED_WARNING;
+  const failure = readIndexRecoveryFailure(indexPath);
+  if (failure)
+    return `Session indexing failed: ${failure.error}. Retry after ${new Date(failure.nextAllowedAt).toISOString()}; /session-index can rebuild now.`;
+  if (running.has(indexPath)) return "Session indexing in progress; try again shortly.";
+  if (existsSync(`${indexPath}.lock.sqlite`)) {
+    const release = acquireIndexLock(indexPath);
+    if (!release) return "Session indexing in progress; try again shortly.";
+    release();
+  }
+  return undefined;
+}
+
+// All index writers share this lock with recovery. Reads are short-lived and may
+// finish on the old inode after an atomic replacement (no WAL sidecars).
+// SQLite owns the lock lifetime, including process death; never unlink its file.
+export function acquireIndexLock(indexPath: string): (() => void) | undefined {
+  ensureIndexDir(dirname(indexPath));
+  let lock: SessionIndexDatabase | undefined;
+  try {
+    lock = openIndexDatabase(`${indexPath}.lock.sqlite`, { create: true, timeoutMs: 0 });
+    lock.exec("BEGIN EXCLUSIVE");
+    const held = lock;
+    return () => held.close();
+  } catch (error) {
+    lock?.close();
+    if (isSqliteBusy(error)) return undefined;
+    throw error;
+  }
+}
+
+function isSqliteBusy(error: unknown): boolean {
+  return (
+    error instanceof Error &&
+    (("code" in error && error.code === "SQLITE_BUSY") ||
+      ("errcode" in error && error.errcode === 5))
+  );
+}
+
+export function requestIndexRecovery(
+  indexPath: string,
+  reconcile = false,
+): Promise<ReindexResult | undefined> {
+  const pending = running.get(indexPath);
+  if (pending) return pending;
+  const sessionsDir = join(getAgentDir(), "sessions");
+  const task = yieldToEventLoop()
+    .then(() => recover(indexPath, sessionsDir, false, reconcile))
+    .catch((error: unknown) => {
+      report(indexPath, `Session indexing failed: ${String(error)}`);
+      return undefined;
+    })
+    .finally(() => running.delete(indexPath));
+  running.set(indexPath, task);
+  return task;
+}
+
+export async function rebuildSessionIndex(options: { indexPath: string }): Promise<ReindexResult> {
+  await running.get(options.indexPath);
+  const result = await recover(options.indexPath, join(getAgentDir(), "sessions"), true, true);
+  if (!result)
+    throw new Error(
+      getIndexRecoveryMessage(options.indexPath) ?? "Session index is busy; try again shortly.",
+    );
+  return result;
+}
+
+async function recover(
+  indexPath: string,
+  sessionsDir: string,
+  manual: boolean,
+  reconcile: boolean,
+): Promise<ReindexResult | undefined> {
+  if (disabled.has(indexPath)) return undefined;
+  let release = acquireIndexLock(indexPath);
+  const deadline = Date.now() + 30_000;
+  while (!release && Date.now() < deadline) {
+    await delay(50);
+    release = acquireIndexLock(indexPath);
+  }
+  if (!release) return undefined;
+  let db: SessionIndexDatabase | undefined;
+  const temp = `${indexPath}.${randomUUID()}.tmp`;
+  try {
+    const failure = readIndexRecoveryFailure(indexPath);
+    let version: number | undefined;
+    let corrupt = false;
+    if (existsSync(indexPath)) {
+      try {
+        const probe = openIndexDatabase(indexPath, { create: false, mode: "read" });
+        try {
+          version = Number(getMetadata(probe, "schema_version"));
+          if (version > INDEX_SCHEMA_VERSION) {
+            disableOlderIndexClient(indexPath);
+            return undefined;
+          }
+          probe.prepare("SELECT COUNT(*) FROM sessions").get();
+        } finally {
+          probe.close();
+        }
+      } catch (error) {
+        if (isSqliteBusy(error)) throw error;
+        corrupt = true;
+      }
+    }
+    if (!manual && failure && Date.now() < failure.nextAllowedAt) {
+      report(indexPath, getIndexRecoveryMessage(indexPath) ?? failure.error);
+      return undefined;
+    }
+    const rebuild = manual || corrupt || version !== INDEX_SCHEMA_VERSION;
+    if (!rebuild && !reconcile) {
+      if (!failure) notices.get(indexPath)?.(undefined);
+      return undefined;
+    }
+    db = openIndexDatabase(rebuild ? temp : indexPath, { create: rebuild });
+    if (rebuild) initializeSchema(db);
+    const skipped: string[] = [];
+    for (const file of listSessionFiles(sessionsDir)) {
+      if (!syncSessionFileWithDb(db, file, "reconcile")) skipped.push(file);
+      await yieldToEventLoop();
+    }
+    const indexedDb = db;
+    const count = (table: string) =>
+      parseTypeBoxValue(
+        ROW_COUNT_SCHEMA,
+        indexedDb.prepare(`SELECT COUNT(*) AS count FROM ${table}`).get(),
+        "Invalid index count",
+      ).count;
+    const result = {
+      sessionCount: count("sessions"),
+      chunkCount: count("session_text_chunks"),
+      indexPath,
+      skipped,
+    };
+    db.transaction(() => {
+      setMetadata(indexedDb, rebuild ? "indexed_at" : "reconciled_at", new Date().toISOString());
+      if (rebuild) setMetadata(indexedDb, "build", BUILD);
+    });
+    db.close();
+    db = undefined;
+    if (rebuild) {
+      if (corrupt) {
+        const backup = `${indexPath}.bad-${Date.now()}-${randomUUID()}`;
+        for (const suffix of ["", "-wal", "-shm", "-journal"]) {
+          if (existsSync(`${indexPath}${suffix}`))
+            renameSync(`${indexPath}${suffix}`, `${backup}${suffix}`);
+        }
+      } else if (existsSync(indexPath)) {
+        // Upgrade legacy WAL indexes before swapping: SQLite checkpoints and
+        // refuses the mode change while another connection still needs its WAL.
+        const previous = openIndexDatabase(indexPath, { create: false });
+        previous.close();
+      }
+      renameSync(temp, indexPath);
+    }
+    rmSync(`${indexPath}.failure.json`, { force: true });
+    shown.delete(indexPath);
+    notices.get(indexPath)?.(undefined);
+    if (skipped.length)
+      report(
+        indexPath,
+        `Session index skipped ${skipped.length} unreadable transcript(s): ${skipped.join(", ")}`,
+      );
+    return result;
+  } catch (error) {
+    const attempts = (readIndexRecoveryFailure(indexPath)?.attempts ?? 0) + 1;
+    const failure: IndexRecoveryFailure = {
+      attempts,
+      nextAllowedAt: Date.now() + (attempts === 1 ? 60_000 : attempts === 2 ? 300_000 : 1_800_000),
+      error: error instanceof Error ? error.message : String(error),
+      build: BUILD,
+    };
+    const record = `${indexPath}.failure.json`;
+    writeFileSync(`${record}.tmp`, JSON.stringify(failure));
+    renameSync(`${record}.tmp`, record);
+    report(indexPath, getIndexRecoveryMessage(indexPath) ?? failure.error);
+    if (manual) throw error;
+    return undefined;
+  } finally {
+    db?.close();
+    for (const suffix of ["", "-wal", "-shm", "-journal"])
+      rmSync(`${temp}${suffix}`, { force: true });
+    release();
+  }
+}

package/extensions/shared/session-index/schema.ts

@@ -22,7 +22,12 @@ export function openIndexDatabase(
 ): SessionIndexDatabase {
   const create = options?.create ?? true;
   const readonly = options?.mode === "read";
-  return openSqlite(dbPath, { create, readonly, timeoutMs: options?.timeoutMs });
+  return openSqlite(dbPath, {
+    create,
+    readonly,
+    timeoutMs: options?.timeoutMs,
+    journalMode: "DELETE",
+  });
 }
 
 export function initializeSchema(db: SessionIndexDatabase): void {
@@ -180,6 +185,9 @@ export function getIndexStatus(dbPath: string): SessionIndexStatus {
   try {
     db = openIndexDatabase(dbPath, { create: false, mode: "read" });
     const schemaVersionRaw = getMetadata(db, "schema_version");
+    if (Number(schemaVersionRaw) !== INDEX_SCHEMA_VERSION) {
+      return { dbPath, exists: true, schemaVersion: Number(schemaVersionRaw) };
+    }
     const lastFullReindexAt = getMetadata(db, "indexed_at");
     const sessionCountRow = parseTypeBoxValue(
       ROW_COUNT_SCHEMA,

package/extensions/shared/session-index/sqlite.ts

@@ -47,7 +47,12 @@ function loadDatabaseConstructor(): SqliteConstructor {
 
 export function openSqlite(
   dbPath: string,
-  options: { create: boolean; readonly?: boolean | undefined; timeoutMs?: number | undefined },
+  options: {
+    create: boolean;
+    readonly?: boolean | undefined;
+    timeoutMs?: number | undefined;
+    journalMode?: "DELETE" | "WAL";
+  },
 ): SqliteDatabase {
   const Database = loadDatabaseConstructor();
   const readonly = options.readonly ?? false;
@@ -66,15 +71,20 @@ export function openSqlite(
       })
     : new Database(dbPath, { readOnly: readonly });
 
-  db.exec(`PRAGMA busy_timeout = ${options.timeoutMs ?? DEFAULT_BUSY_TIMEOUT_MS}`);
-  db.exec("PRAGMA foreign_keys = ON");
-
-  if (!readonly) {
-    // journal_mode is the connection's first write-capable lock acquisition (and
-    // may run WAL recovery), and immediate transactions rely on busy_timeout to
-    // queue behind concurrent writers instead of failing.
-    db.exec("PRAGMA journal_mode = WAL");
-    db.exec("PRAGMA synchronous = NORMAL");
+  try {
+    db.exec(`PRAGMA busy_timeout = ${options.timeoutMs ?? DEFAULT_BUSY_TIMEOUT_MS}`);
+    db.exec("PRAGMA foreign_keys = ON");
+
+    if (!readonly) {
+      // journal_mode is the connection's first write-capable lock acquisition (and
+      // may run WAL recovery), and immediate transactions rely on busy_timeout to
+      // queue behind concurrent writers instead of failing.
+      db.exec(`PRAGMA journal_mode = ${options.journalMode ?? "WAL"}`);
+      db.exec("PRAGMA synchronous = NORMAL");
+    }
+  } catch (error) {
+    db.close();
+    throw error;
   }
 
   return withStatementCache(db);

package/extensions/{session-search/hooks.ts → shared/session-index/sync.ts}

@@ -1,4 +1,14 @@
 import { existsSync, type Stats, statSync } from "node:fs";
+import {
+  createSessionNameChunk,
+  type ExtractedSessionRecord,
+  type ExtractedSessionTail,
+  extractSessionRecord,
+  extractSessionTail,
+  inferSessionOrigin,
+  type SessionFileTouch,
+} from "../../session-search/extract.ts";
+import { deriveSessionRepoRoots } from "../../session-search/normalize.ts";
 import {
   clearSessionChunksBySourceKind,
   clearSessionIndexedData,
@@ -14,17 +24,7 @@ import {
   setMetadata,
   upsertSession,
   withSessionIndex,
-} from "../shared/session-index/index.ts";
-import {
-  createSessionNameChunk,
-  type ExtractedSessionRecord,
-  type ExtractedSessionTail,
-  extractSessionRecord,
-  extractSessionTail,
-  inferSessionOrigin,
-  type SessionFileTouch,
-} from "./extract.ts";
-import { deriveSessionRepoRoots } from "./normalize.ts";
+} from "./index.ts";
 
 export interface SessionHookController {
   handleSessionStart(sessionFile: string | undefined): Promise<boolean>;
@@ -107,32 +107,56 @@ interface TailSyncBaseline extends SessionRow {
   indexedFileAnchor: string;
 }
 
-function syncSessionFileWithDb(
+export function syncSessionFileWithDb(
   db: SessionIndexDatabase,
   sessionFile: string,
   eventType: string,
   sessionOrigin?: SessionOrigin,
 ): boolean {
   const baseline = asTailSyncBaseline(getSessionRowByPath(db, sessionFile));
-  const stat = statSync(sessionFile);
+  let stat: Stats;
+  try {
+    stat = statSync(sessionFile);
+  } catch {
+    return false;
+  }
 
   if (baseline && isIndexCurrent(baseline, stat, sessionOrigin)) {
-    db.transaction(() => writeHookSyncMetadata(db, eventType));
+    if (eventType !== "reconcile") db.transaction(() => writeHookSyncMetadata(db, eventType));
     return true;
   }
 
   if (baseline && stat.size > baseline.indexedFileSize) {
-    const tail = extractSessionTail(sessionFile, baseline);
+    let tail: ExtractedSessionTail | undefined;
+    try {
+      tail = extractSessionTail(sessionFile, baseline);
+    } catch {
+      return false;
+    }
     if (tail && applyTailSync(db, baseline, tail, eventType, sessionOrigin)) {
       return true;
     }
   }
 
-  const extracted = extractSessionRecord(sessionFile);
+  let extracted: ExtractedSessionRecord | undefined;
+  try {
+    extracted = extractSessionRecord(sessionFile);
+  } catch {
+    return false;
+  }
   if (!extracted) {
     return false;
   }
 
+  const existing = getSessionById(db, extracted.sessionId);
+  if (
+    existing &&
+    existing.sessionPath !== sessionFile &&
+    (existing.modifiedAt > extracted.modifiedAt ||
+      (existing.modifiedAt === extracted.modifiedAt && existing.sessionPath > sessionFile))
+  )
+    return true;
+
   applyFullSync(db, extracted, eventType, sessionOrigin);
   return true;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-sessions",
-  "version": "0.15.0",
+  "version": "0.16.0",
   "type": "module",
   "description": "Pi session search, ask, handoff, messaging, auto-titling, and indexing tools",
   "license": "MIT",

package/extensions/session-search/reindex.ts

@@ -1,97 +0,0 @@
-import path from "node:path";
-import { getAgentDir } from "@earendil-works/pi-coding-agent";
-import {
-  clearSessionIndexedData,
-  ensureIndexDir,
-  initializeSchema,
-  insertSessionFileTouch,
-  insertTextChunk,
-  openIndexDatabase,
-  rebuildSessionLineageRelations,
-  type SessionIndexDatabase,
-  setMetadata,
-  upsertSession,
-} from "../shared/session-index/index.ts";
-import { type ExtractedSessionRecord, extractSessionRecord, listSessionFiles } from "./extract.ts";
-
-export interface ReindexOptions {
-  indexPath: string;
-}
-
-export interface ReindexResult {
-  sessionCount: number;
-  chunkCount: number;
-  indexPath: string;
-}
-
-export async function rebuildSessionIndex(options: ReindexOptions): Promise<ReindexResult> {
-  const indexPath = options.indexPath;
-  ensureIndexDir(path.dirname(indexPath));
-  const sessionFiles = listSessionFiles(path.join(getAgentDir(), "sessions"));
-
-  const db = openIndexDatabase(indexPath, { create: true });
-  try {
-    db.transaction(() => {
-      dropIndexTables(db);
-      initializeSchema(db);
-    });
-
-    const indexedSessions = new Map<string, { modifiedAt: string; chunks: number }>();
-    let chunkCount = 0;
-    for (const sessionFile of sessionFiles) {
-      const extracted = extractSessionRecord(sessionFile);
-      if (!extracted) {
-        continue;
-      }
-
-      const previous = indexedSessions.get(extracted.sessionId);
-      if (previous && previous.modifiedAt > extracted.modifiedAt) continue;
-      db.transaction(() => indexSession(db, extracted));
-      chunkCount += extracted.chunks.length - (previous?.chunks ?? 0);
-      indexedSessions.set(extracted.sessionId, {
-        modifiedAt: extracted.modifiedAt,
-        chunks: extracted.chunks.length,
-      });
-    }
-
-    db.transaction(() => {
-      rebuildSessionLineageRelations(db);
-      setMetadata(db, "indexed_at", new Date().toISOString());
-      setMetadata(db, "session_source", "session files");
-    });
-
-    return { sessionCount: indexedSessions.size, chunkCount, indexPath };
-  } finally {
-    db.close();
-  }
-}
-
-function dropIndexTables(db: SessionIndexDatabase): void {
-  // Children before parents: foreign_keys is ON and DROP TABLE runs an
-  // implicit DELETE that parent-side constraints would reject.
-  db.exec(`
-    DROP TABLE IF EXISTS session_lineage_relations;
-    DROP TABLE IF EXISTS session_repo_roots;
-    DROP TABLE IF EXISTS session_text_chunks;
-    DROP TABLE IF EXISTS session_file_touches;
-    DROP TABLE IF EXISTS session_text_chunks_fts;
-    DROP TABLE IF EXISTS sessions;
-    DROP TABLE IF EXISTS metadata;
-  `);
-}
-
-function indexSession(db: SessionIndexDatabase, extracted: ExtractedSessionRecord): void {
-  clearSessionIndexedData(db, extracted.sessionId);
-  upsertSession(db, extracted, "full_reindex");
-
-  for (const chunk of extracted.chunks) {
-    insertTextChunk(db, { sessionId: extracted.sessionId, ...chunk });
-  }
-
-  for (const fileTouch of extracted.fileTouches) {
-    insertSessionFileTouch(db, {
-      sessionId: extracted.sessionId,
-      ...fileTouch,
-    });
-  }
-}