pi-sessions 0.15.0 → 0.17.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,9 @@ 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.
+Settings live under `sessions` in `~/.pi/agent/settings.json`. A project's `.pi/settings.json` overrides them the way pi merges its own settings: nested objects merge key by key, and the project wins.
+
+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
 {
@@ -200,6 +201,7 @@ If you want to override the shortcut, put this in your `~/.pi/agent/settings.jso
       "thinkingLevel": "low",
       "roster": ["anthropic/*", "openai-codex/gpt-5.6-terra:high"],
       "deferred": {
+        "enable": true,
         "copyToClipboard": true
       }
     }
@@ -211,6 +213,8 @@ If you want to override the shortcut, put this in your `~/.pi/agent/settings.jso
 
 `roster` limits which models a handoff may launch a child session on. Defaults to pi's own `enabledModels` scoping, then to all configured models. May optionally include a thinking level; listing a model more than once adds to the levels it allows.
 
+`deferred.enable` (default `true`) offers the `deferred` launch. Turn it off, along with `sessions.subagents.enable`, to leave only host and split launches.
+
 `deferred.copyToClipboard` (default `true`) controls whether deferred handoffs copy the resume command to the clipboard. When off, the resume command is only shown in the tool call.
 
 Subagents require the handoff and messaging features. Limit recursive delegation depth with `sessions.subagents.maxDepth` (default `2`), or cap the context a subagent runs in with `sessions.subagents.contextLimit`:
@@ -230,12 +234,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/install.ts

@@ -28,7 +28,11 @@ import {
 } from "./tool.ts";
 import { HANDOFF_TOOL_DETAILS_SCHEMA } from "./tool-contract.ts";
 import { HandoffToolComponent } from "./tool-renderer.ts";
-import { buildHandoffLaunchSchema, buildHandoffPromptGuidelines } from "./tool-schema.ts";
+import {
+  buildHandoffLaunchSchema,
+  buildHandoffPromptGuidelines,
+  offersSubagentLaunch,
+} from "./tool-schema.ts";
 import { buildHandoffToolView } from "./tool-view-model.ts";
 import { formatHandoffError } from "./ui.ts";
 
@@ -66,14 +70,16 @@ export function installHandoff(
     launchTargets: readonly HandoffLaunchTarget[],
     roster: HandoffRoster | undefined,
   ): void {
+    const offersSubagent = offersSubagentLaunch(launchTargets);
     pi.registerTool({
       name: "session_handoff",
       label: "Session Handoff",
       description: "Start a new Pi session with a self-contained task.",
       // Nested calls write no toolResult entry, so the board would never see the launch receipt.
       exposure: "model-only",
-      promptSnippet:
-        "Delegate bounded work to a background subagent or hand off context to another Pi session",
+      promptSnippet: offersSubagent
+        ? "Delegate bounded work to a background subagent or hand off context to another Pi session"
+        : "Hand off context to another Pi session",
       promptGuidelines: buildHandoffPromptGuidelines(launchTargets, models, roster),
       parameters: Type.Object({
         goal: Type.String({
@@ -93,8 +99,7 @@ export function installHandoff(
         ),
         requestResponse: Type.Optional(
           Type.Boolean({
-            description:
-              "Whether the child session should report completion/results of its task back to this session. Defaults to true for subagent launches and false otherwise.",
+            description: `Whether the child session should report completion/results of its task back to this session. ${offersSubagent ? "Defaults to true for subagent launches and false otherwise." : "Defaults to false."}`,
           }),
         ),
         provider: Type.Optional(
@@ -111,8 +116,9 @@ export function installHandoff(
           Type.Union(
             THINKING_LEVELS.map((level) => Type.Literal(level)),
             {
-              description:
-                "Thinking level for the child session. For directional or deferred, override only when the user requests it.",
+              description: offersSubagent
+                ? "Thinking level for the child session. For launches other than subagent, override only when the user requests it."
+                : "Thinking level for the child session. Override only when the user requests it.",
             },
           ),
         ),
@@ -215,7 +221,7 @@ export function installHandoff(
         createHandoffLaunchTargets({
           pi,
           splitBackend,
-          copyDeferredToClipboard: settings.handoff.deferred.copyToClipboard,
+          deferred: settings.handoff.deferred,
           additionalTargets: deps.getLaunchTargets?.() ?? [],
           hosts: deps.getHosts?.() ?? [],
         }),

package/extensions/session-handoff/launch-options.ts

@@ -1,5 +1,6 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import type { Host } from "../hosts/contract.ts";
+import type { HandoffSettings } from "../shared/settings.ts";
 import { createDeferredLaunchBackend } from "./launch/deferred.ts";
 import type { SplitLaunchBackend } from "./launch/resolution.ts";
 import {
@@ -18,7 +19,7 @@ export interface ResolvedHandoffLaunchTarget {
 export function createHandoffLaunchTargets(options: {
   pi: ExtensionAPI;
   splitBackend: SplitLaunchBackend | undefined;
-  copyDeferredToClipboard: boolean;
+  deferred: HandoffSettings["deferred"];
   additionalTargets: readonly HandoffLaunchTarget[];
   hosts?: readonly Host[];
 }): HandoffLaunchTarget[] {
@@ -35,11 +36,15 @@ export function createHandoffLaunchTargets(options: {
         ),
       )
     : [];
-  const deferred = createBackendLaunchTarget(
-    DEFERRED_LAUNCH,
-    createDeferredLaunchBackend({ copyToClipboard: options.copyDeferredToClipboard }),
-    "'deferred' creates the session and returns its resume command without opening anything.",
-  );
+  const deferredTargets = options.deferred.enable
+    ? [
+        createBackendLaunchTarget(
+          DEFERRED_LAUNCH,
+          createDeferredLaunchBackend({ copyToClipboard: options.deferred.copyToClipboard }),
+          "'deferred' creates the session and returns its resume command without opening anything.",
+        ),
+      ]
+    : [];
   return [
     ...hosts.map((host) =>
       createBackendLaunchTarget(
@@ -50,7 +55,7 @@ export function createHandoffLaunchTargets(options: {
       ),
     ),
     ...splitTargets,
-    deferred,
+    ...deferredTargets,
     ...options.additionalTargets,
   ];
 }

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-handoff/tool-schema.ts

@@ -1,6 +1,11 @@
 import type { Api, Model } from "@earendil-works/pi-ai";
 import { Type } from "typebox";
-import { type HandoffLaunchTarget, LAUNCH_DIRECTIONS, SUBAGENT_LAUNCH } from "./launch-target.ts";
+import {
+  DEFERRED_LAUNCH,
+  type HandoffLaunchTarget,
+  LAUNCH_DIRECTIONS,
+  SUBAGENT_LAUNCH,
+} from "./launch-target.ts";
 import { formatRosterEntry, type HandoffRoster } from "./roster.ts";
 
 export function buildHandoffLaunchSchema(targets: readonly HandoffLaunchTarget[]) {
@@ -23,9 +28,6 @@ const SUBAGENT_GUIDELINES = [
   "After launching a subagent, do not sleep, poll, or repeatedly check its progress; continue useful work or finish the current turn and wait for its report.",
 ];
 
-const LAUNCH_TARGET_GUIDELINE =
-  "Use session_handoff directional or deferred launches only when the user requests one.";
-
 const MODEL_INHERITANCE_GUIDELINES = [
   "Leave provider and model unset to run the handoff on this session's current model.",
   "To run the handoff on a different model, set both provider and model together (both are required).",
@@ -35,7 +37,7 @@ const RESTRICTED_THINKING_GUIDELINE =
   'A ":level" suffix on a listed model limits it to those thinking levels; set thinkingLevel to one of them, or leave it unset when only one is listed.';
 
 const SUBAGENT_MODEL_OVERRIDE_GUIDELINE =
-  "For subagents, choose the model that best fits the delegated task; for directional or deferred handoffs, only override the model when the task clearly warrants it. When unsure, ask the user for their preference.";
+  "For subagents, choose the model that best fits the delegated task; for other launches, only override the model when the task clearly warrants it. When unsure, ask the user for their preference.";
 
 const DEFAULT_MODEL_OVERRIDE_GUIDELINE =
   "Only override the model when the task clearly warrants it.";
@@ -45,20 +47,15 @@ export function buildHandoffPromptGuidelines(
   models: readonly Model<Api>[],
   roster: HandoffRoster | undefined,
 ): string[] {
-  const hasSubagent = targets.some((target) => target.value === SUBAGENT_LAUNCH);
-  const hasHost = targets.some(
-    (target) =>
-      target.value !== "subagent" &&
-      target.value !== "deferred" &&
-      !LAUNCH_DIRECTIONS.some((direction) => direction === target.value),
-  );
+  const hasSubagent = offersSubagentLaunch(targets);
+  const userFacingKinds = describeUserFacingLaunchKinds(targets);
   const selectable =
     roster?.map(formatRosterEntry) ?? models.map((model) => `${model.provider}/${model.id}`);
   return [
     ...(hasSubagent ? SUBAGENT_GUIDELINES : []),
-    hasHost
-      ? "Use session_handoff host or deferred launches only when the user requests one."
-      : LAUNCH_TARGET_GUIDELINE,
+    ...(userFacingKinds
+      ? [`Use session_handoff ${userFacingKinds} launches only when the user requests one.`]
+      : []),
     ...MODEL_INHERITANCE_GUIDELINES,
     hasSubagent ? SUBAGENT_MODEL_OVERRIDE_GUIDELINE : DEFAULT_MODEL_OVERRIDE_GUIDELINE,
     ...(selectable.length > 0
@@ -67,3 +64,24 @@ export function buildHandoffPromptGuidelines(
     ...(roster?.some((entry) => entry.thinkingLevels) ? [RESTRICTED_THINKING_GUIDELINE] : []),
   ];
 }
+
+export function offersSubagentLaunch(targets: readonly HandoffLaunchTarget[]): boolean {
+  return targets.some((target) => target.value === SUBAGENT_LAUNCH);
+}
+
+function describeUserFacingLaunchKinds(targets: readonly HandoffLaunchTarget[]): string {
+  const isDirection = (value: string) => LAUNCH_DIRECTIONS.some((direction) => direction === value);
+  const kinds = [
+    targets.some((target) => isDirection(target.value)) ? "directional" : undefined,
+    targets.some(
+      (target) =>
+        target.value !== SUBAGENT_LAUNCH &&
+        target.value !== DEFERRED_LAUNCH &&
+        !isDirection(target.value),
+    )
+      ? "host"
+      : undefined,
+    targets.some((target) => target.value === DEFERRED_LAUNCH) ? "deferred" : undefined,
+  ];
+  return kinds.filter((kind) => kind !== undefined).join(" or ");
+}

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/extensions/shared/settings.ts

@@ -35,6 +35,7 @@ const SESSION_FILE_SETTINGS_SCHEMA = Type.Object({
       roster: Type.Optional(Type.Array(Type.String())),
       deferred: Type.Optional(
         Type.Object({
+          enable: Type.Optional(Type.Boolean()),
           copyToClipboard: Type.Optional(Type.Boolean()),
         }),
       ),
@@ -103,6 +104,7 @@ export interface HandoffSettings extends AgentModelSettings {
   /** Patterns naming the models a handoff may launch a child on. Empty means unrestricted. */
   roster: readonly ModelSelection[];
   deferred: {
+    enable: boolean;
     copyToClipboard: boolean;
   };
 }
@@ -228,9 +230,14 @@ function normalizeAutoTitlePrompt(value: string | undefined): string {
   return trimmed ? trimmed : DEFAULT_AUTO_TITLE_PROMPT;
 }
 
+/**
+ * pi's merged view: project `.pi/settings.json` deep-merged over the global file.
+ * Extensions load before `pi.getSettings()` is bound, and the trust decision it
+ * honors is not visible at load time, so project settings apply regardless of trust.
+ */
 function loadSessionFileSettings(): SessionFileSettings {
-  const globalSettings = SettingsManager.create(process.cwd()).getGlobalSettings();
-  const parsed = parseTypeBoxValue(ROOT_SETTINGS_SCHEMA, globalSettings, "Invalid settings");
+  const mergedSettings = SettingsManager.create(process.cwd()).getSettings();
+  const parsed = parseTypeBoxValue(ROOT_SETTINGS_SCHEMA, mergedSettings, "Invalid settings");
   return parsed.sessions ?? {};
 }
 
@@ -263,6 +270,7 @@ function resolveSessionSettings(fileSettings: SessionFileSettings): SessionSetti
       persistRuns: fileSettings.handoff?.persistRuns ?? false,
       roster: normalizeRoster(fileSettings.handoff?.roster),
       deferred: {
+        enable: fileSettings.handoff?.deferred?.enable ?? true,
         copyToClipboard: fileSettings.handoff?.deferred?.copyToClipboard ?? true,
       },
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-sessions",
-  "version": "0.15.0",
+  "version": "0.17.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,
-    });
-  }
-}