pi-sessions 0.1.0 → 0.2.1

package/README.md

@@ -62,11 +62,20 @@ What session did I implement the db layer?
 
 `/handoff <goal>` starts a focused new session. Give pi a goal, and it will generate a prompt for you to review before kicking it off.
 
+You can either start a new session directly in your current one, or if you have Ghostty on macOS, you can spawn a new one in a split-pane and continue in your current:
+
+- `/handoff --left <goal>`
+- `/handoff --right <goal>`
+- `/handoff --up <goal>`
+- `/handoff --down <goal>`
+
+The flag indicates the Ghostty split direction.
+
 Flow:
 
-- run `/handoff <goal>`
+- run `/handoff [--<direction>] <goal>`
 - review the generated prompt preview
-- optionally edit the prompt to make any adjustments
+- optionally edit the prompt
 - start the new session
 
 If you do nothing, the preview autostarts after a short countdown.
@@ -138,8 +147,6 @@ To manage existing titles, run `/title`, where you can:
 
 Note that generating titles for all sessions can take some time, and will hit your configured model with the full contents of all sessions.
 
-Behavior notes:
-
 - automatic retitles run every few turns
 - if you manually rename a session with `/name`, automatic retitling pauses for that session
 - Regenerate the title for the current session to resume automatic retitling
@@ -147,7 +154,7 @@ Behavior notes:
   - `google/gemini-flash-lite-latest`
   - `anthropic/claude-haiku-4-5`
   - `openai/gpt-5.4-mini`
-- your currently configured model
+  - your currently configured model
 
 To change auto-titling settings, edit `~/.pi/agent/settings.json`:
 

package/extensions/session-handoff/metadata.ts

@@ -1,25 +1,29 @@
-import { randomUUID } from "node:crypto";
+import { Buffer } from "node:buffer";
 import type { CustomEntry, SessionEntry } from "@mariozechner/pi-coding-agent";
 import { type Static, Type } from "@sinclair/typebox";
 import { safeParseTypeBoxValue } from "../shared/typebox.js";
 
 export const HANDOFF_METADATA_CUSTOM_TYPE = "pi-sessions.handoff";
-export const PENDING_SEND_CONSUMED_CUSTOM_TYPE = "pi-sessions.pending-send-consumed";
+export const HANDOFF_BOOTSTRAP_ENV = "PI_SESSIONS_HANDOFF_BOOTSTRAP";
+export const HANDOFF_STALE_SESSION_MESSAGE =
+  "Session handoff failed: target session already has user input.";
 
 export const HANDOFF_SESSION_METADATA_SCHEMA = Type.Object({
   origin: Type.Literal("handoff"),
   goal: Type.String(),
   nextTask: Type.String(),
   initial_prompt: Type.String(),
-  initial_prompt_nonce: Type.String(),
 });
 
-export const PENDING_SEND_CONSUMED_ENTRY_SCHEMA = Type.Object({
-  nonce: Type.String(),
+export const HANDOFF_BOOTSTRAP_SCHEMA = Type.Object({
+  sessionId: Type.String(),
+  goal: Type.String(),
+  nextTask: Type.String(),
+  initialPrompt: Type.String(),
 });
 
 export type HandoffSessionMetadata = Static<typeof HANDOFF_SESSION_METADATA_SCHEMA>;
-export type PendingSendConsumedEntryData = Static<typeof PENDING_SEND_CONSUMED_ENTRY_SCHEMA>;
+export type HandoffBootstrap = Static<typeof HANDOFF_BOOTSTRAP_SCHEMA>;
 
 export function createHandoffSessionMetadata(
   goal: string,
@@ -28,69 +32,69 @@ export function createHandoffSessionMetadata(
 ): HandoffSessionMetadata {
   const normalizedGoal = goal.trim();
   const normalizedNextTask = nextTask.trim() || normalizedGoal;
-  const normalizedInitialPrompt = initialPrompt.trim();
 
   return {
     origin: "handoff",
     goal: normalizedGoal,
     nextTask: normalizedNextTask,
-    initial_prompt: normalizedInitialPrompt,
-    initial_prompt_nonce: randomUUID(),
+    initial_prompt: initialPrompt.trim(),
+  };
+}
+
+export function createHandoffBootstrap(
+  sessionId: string,
+  metadata: HandoffSessionMetadata,
+): HandoffBootstrap {
+  return {
+    sessionId,
+    goal: metadata.goal,
+    nextTask: metadata.nextTask,
+    initialPrompt: metadata.initial_prompt,
   };
 }
 
-export function createPendingSendConsumedEntry(nonce: string): PendingSendConsumedEntryData {
-  return { nonce };
+export function encodeHandoffBootstrap(bootstrap: HandoffBootstrap): string {
+  return Buffer.from(JSON.stringify(bootstrap), "utf8").toString("base64");
 }
 
-export function parsePendingSendConsumedEntry(
-  value: unknown,
-): PendingSendConsumedEntryData | undefined {
-  return safeParseTypeBoxValue(PENDING_SEND_CONSUMED_ENTRY_SCHEMA, value);
+export function parseHandoffBootstrap(value: string): HandoffBootstrap | undefined {
+  try {
+    const decoded = Buffer.from(value, "base64").toString("utf8");
+    return safeParseTypeBoxValue(HANDOFF_BOOTSTRAP_SCHEMA, JSON.parse(decoded));
+  } catch {
+    return undefined;
+  }
 }
 
 export function parseHandoffSessionMetadata(value: unknown): HandoffSessionMetadata | undefined {
   return safeParseTypeBoxValue(HANDOFF_SESSION_METADATA_SCHEMA, value);
 }
 
-export function getPendingInitialPromptFromEntries(
+export function getHandoffMetadataFromEntries(
   entries: readonly SessionEntry[],
 ): HandoffSessionMetadata | undefined {
-  const consumed = new Set<string>();
-  let pending: HandoffSessionMetadata | undefined;
-
   for (const entry of entries) {
     if (entry.type !== "custom") {
       continue;
     }
 
-    const customEntry = entry as CustomEntry;
-    if (customEntry.customType === PENDING_SEND_CONSUMED_CUSTOM_TYPE) {
-      const consumedEntry = parsePendingSendConsumedEntry(customEntry.data);
-      if (consumedEntry) {
-        consumed.add(consumedEntry.nonce);
-        if (pending?.initial_prompt_nonce === consumedEntry.nonce) {
-          pending = undefined;
-        }
-      }
-      continue;
-    }
-
-    if (customEntry.customType !== HANDOFF_METADATA_CUSTOM_TYPE) {
-      continue;
+    const metadata = parseCustomHandoffMetadata(entry);
+    if (metadata) {
+      return metadata;
     }
+  }
 
-    const metadata = parseHandoffSessionMetadata(customEntry.data);
-    if (!metadata) {
-      continue;
-    }
+  return undefined;
+}
 
-    if (consumed.has(metadata.initial_prompt_nonce)) {
-      continue;
-    }
+export function hasUserMessages(entries: readonly SessionEntry[]): boolean {
+  return entries.some((entry) => entry.type === "message" && entry.message.role === "user");
+}
 
-    pending = metadata;
+function parseCustomHandoffMetadata(entry: CustomEntry): HandoffSessionMetadata | undefined {
+  if (entry.customType !== HANDOFF_METADATA_CUSTOM_TYPE) {
+    return undefined;
   }
 
-  return pending;
+  return parseHandoffSessionMetadata(entry.data);
 }

package/extensions/session-handoff/spawn.ts

@@ -0,0 +1,142 @@
+import { randomUUID } from "node:crypto";
+import { writeFileSync } from "node:fs";
+import { join } from "node:path";
+import {
+  CURRENT_SESSION_VERSION,
+  type ExtensionAPI,
+  type ExtensionCommandContext,
+  type SessionHeader,
+} from "@mariozechner/pi-coding-agent";
+import { HANDOFF_BOOTSTRAP_ENV } from "./metadata.js";
+
+const GHOSTTY_MACOS_ONLY_MESSAGE = "Split handoff currently supports Ghostty on macOS only.";
+const GHOSTTY_REQUIRED_MESSAGE = "Split handoff requires running inside Ghostty.";
+const GHOSTTY_SPLIT_TIMEOUT_MS = 15_000;
+const OSASCRIPT_PATH = "/usr/bin/osascript";
+
+export type HandoffSplitDirection = "left" | "right" | "up" | "down";
+
+export interface CreatedHandoffSession {
+  sessionId: string;
+  sessionFile: string;
+}
+
+export async function validateSplitHandoffPrerequisites(
+  _pi: ExtensionAPI,
+  ctx: ExtensionCommandContext,
+): Promise<string | undefined> {
+  if (!ctx.sessionManager.getSessionFile()) {
+    return "Split handoff requires a persisted current session.";
+  }
+
+  if (process.platform !== "darwin") {
+    return GHOSTTY_MACOS_ONLY_MESSAGE;
+  }
+
+  if (process.env.TERM_PROGRAM !== "ghostty") {
+    return GHOSTTY_REQUIRED_MESSAGE;
+  }
+
+  return undefined;
+}
+
+export function createHandoffSession(options: {
+  cwd: string;
+  sessionDir: string;
+  parentSessionFile: string;
+}): CreatedHandoffSession {
+  const sessionId = randomUUID();
+  const timestamp = new Date().toISOString();
+  const fileTimestamp = timestamp.replace(/[:.]/g, "-");
+  const sessionFile = join(options.sessionDir, `${fileTimestamp}_${sessionId}.jsonl`);
+
+  const header: SessionHeader = {
+    type: "session",
+    version: CURRENT_SESSION_VERSION,
+    id: sessionId,
+    timestamp,
+    cwd: options.cwd,
+    parentSession: options.parentSessionFile,
+  };
+
+  writeFileSync(sessionFile, `${JSON.stringify(header)}\n`);
+
+  return { sessionId, sessionFile };
+}
+
+export async function launchSplitHandoffSession(
+  pi: ExtensionAPI,
+  options: {
+    cwd: string;
+    sessionDir: string;
+    direction: HandoffSplitDirection;
+    sessionId: string;
+    bootstrapValue: string;
+  },
+): Promise<{ success: true } | { success: false; error: string }> {
+  const piCommand = buildPiLaunchCommand(
+    options.sessionDir,
+    options.sessionId,
+    options.bootstrapValue,
+  );
+  const escapedCwd = escapeAppleScriptString(options.cwd);
+  const escapedCommand = escapeAppleScriptString(piCommand);
+  const appleScript = [
+    'tell application "Ghostty"',
+    "    set targetTerminal to focused terminal of selected tab of front window",
+    "    set cfg to new surface configuration",
+    `    set initial working directory of cfg to "${escapedCwd}"`,
+    `    set command of cfg to "${escapedCommand}"`,
+    `    set newTerminal to split targetTerminal direction ${options.direction} with configuration cfg`,
+    "    focus targetTerminal",
+    "end tell",
+  ].join("\n");
+  const result = await pi.exec(OSASCRIPT_PATH, ["-e", appleScript], {
+    cwd: options.cwd,
+    timeout: GHOSTTY_SPLIT_TIMEOUT_MS,
+  });
+
+  if (result.code === 0) {
+    return { success: true };
+  }
+
+  const details = `${result.stderr || result.stdout}`.trim() || `exit code ${result.code}`;
+  return {
+    success: false,
+    error:
+      `Failed to launch Ghostty split: ${details}. ` +
+      "Split handoff currently supports Ghostty on macOS only.",
+  };
+}
+
+export function buildPiResumeCommand(
+  sessionDir: string,
+  sessionId: string,
+  bootstrapValue: string,
+): string {
+  return [
+    `${HANDOFF_BOOTSTRAP_ENV}=${shellQuote(bootstrapValue)}`,
+    "pi",
+    "--session-dir",
+    shellQuote(sessionDir),
+    "--session",
+    shellQuote(sessionId),
+  ].join(" ");
+}
+
+export function buildPiLaunchCommand(
+  sessionDir: string,
+  sessionId: string,
+  bootstrapValue: string,
+): string {
+  const payload = `${buildPiResumeCommand(sessionDir, sessionId, bootstrapValue)}; exec /bin/zsh -il`;
+  return `/bin/zsh -ilc ${shellQuote(payload)}`;
+}
+
+function escapeAppleScriptString(value: string): string {
+  return value.replaceAll("\\", "\\\\").replaceAll('"', '\\"');
+}
+
+function shellQuote(value: string): string {
+  return `'${value.replaceAll("'", `'"'"'`)}'`;
+}

package/extensions/session-handoff.ts

@@ -1,23 +1,32 @@
-import type {
-  ExtensionAPI,
-  ExtensionCommandContext,
-  SessionManager,
-} from "@mariozechner/pi-coding-agent";
+import type { ExtensionAPI, ExtensionCommandContext } from "@mariozechner/pi-coding-agent";
 import { buildSessionContext } from "@mariozechner/pi-coding-agent";
 import { Key, matchesKey } from "@mariozechner/pi-tui";
 import { generateHandoffDraft, type HandoffDraftResult } from "./session-handoff/extract.js";
 import {
+  createHandoffBootstrap,
   createHandoffSessionMetadata,
-  createPendingSendConsumedEntry,
-  getPendingInitialPromptFromEntries,
+  encodeHandoffBootstrap,
+  getHandoffMetadataFromEntries,
+  HANDOFF_BOOTSTRAP_ENV,
   HANDOFF_METADATA_CUSTOM_TYPE,
-  PENDING_SEND_CONSUMED_CUSTOM_TYPE,
+  HANDOFF_STALE_SESSION_MESSAGE,
+  hasUserMessages,
+  parseHandoffBootstrap,
 } from "./session-handoff/metadata.js";
 import { openSessionReferencePicker } from "./session-handoff/picker.js";
 import { SESSION_TOKEN_PREFIX } from "./session-handoff/query.js";
 import { renderStrongModal, reviewHandoffDraft } from "./session-handoff/review.js";
+import {
+  buildPiResumeCommand,
+  createHandoffSession,
+  type HandoffSplitDirection,
+  launchSplitHandoffSession,
+  validateSplitHandoffPrerequisites,
+} from "./session-handoff/spawn.js";
 import { loadSettings } from "./shared/settings.js";
 
+const HANDOFF_USAGE = "Usage: /handoff [--left|--right|--up|--down] <goal for new thread>";
+
 export default function sessionHandoffExtension(pi: ExtensionAPI): void {
   const settings = loadSettings();
 
@@ -34,9 +43,9 @@ export default function sessionHandoffExtension(pi: ExtensionAPI): void {
         return;
       }
 
-      const goal = args.trim();
-      if (!goal) {
-        ctx.ui.notify("Usage: /handoff <goal for new thread>", "error");
+      const parsedArgs = parseHandoffCommandArgs(args);
+      if (parsedArgs.kind === "error") {
+        ctx.ui.notify(parsedArgs.message, "error");
         return;
       }
 
@@ -49,12 +58,20 @@ export default function sessionHandoffExtension(pi: ExtensionAPI): void {
         return;
       }
 
+      if (parsedArgs.splitDirection) {
+        const preflightError = await validateSplitHandoffPrerequisites(pi, ctx);
+        if (preflightError) {
+          ctx.ui.notify(preflightError, "error");
+          return;
+        }
+      }
+
       let generatedDraft: HandoffDraftResult | undefined;
       try {
         generatedDraft = await runWithLoader(
           ctx,
           "Generating handoff draft...",
-          async (signal: AbortSignal) => generateHandoffDraft(ctx, goal, signal),
+          async (signal: AbortSignal) => generateHandoffDraft(ctx, parsedArgs.goal, signal),
         );
       } catch (error) {
         ctx.ui.notify(formatHandoffError(error), "error");
@@ -72,26 +89,57 @@ export default function sessionHandoffExtension(pi: ExtensionAPI): void {
         return;
       }
 
-      const parentSession = ctx.sessionManager.getSessionFile();
+      const parentSessionFile = ctx.sessionManager.getSessionFile();
+      if (!parentSessionFile) {
+        ctx.ui.notify("Handoff requires a persisted current session.", "error");
+        return;
+      }
 
       const handoffMetadata = createHandoffSessionMetadata(
-        goal,
+        parsedArgs.goal,
         generatedDraft.context.nextTask,
         approvedDraft,
       );
-      const writeMetadata = async (sm: SessionManager) => {
-        sm.appendCustomEntry(HANDOFF_METADATA_CUSTOM_TYPE, handoffMetadata);
-      };
-      const newSessionResult = parentSession
-        ? await ctx.newSession({ parentSession, setup: writeMetadata })
-        : await ctx.newSession({ setup: writeMetadata });
+      const createdSession = createHandoffSession({
+        cwd: ctx.cwd,
+        sessionDir: ctx.sessionManager.getSessionDir(),
+        parentSessionFile,
+      });
+      const bootstrapValue = encodeHandoffBootstrap(
+        createHandoffBootstrap(createdSession.sessionId, handoffMetadata),
+      );
+
+      if (parsedArgs.splitDirection) {
+        const launchResult = await launchSplitHandoffSession(pi, {
+          cwd: ctx.cwd,
+          sessionDir: ctx.sessionManager.getSessionDir(),
+          direction: parsedArgs.splitDirection,
+          sessionId: createdSession.sessionId,
+          bootstrapValue,
+        });
+
+        if (!launchResult.success) {
+          ctx.ui.notify(
+            `${launchResult.error} Created handoff session ${createdSession.sessionId}; start it manually with: ${buildPiResumeCommand(ctx.sessionManager.getSessionDir(), createdSession.sessionId, bootstrapValue)}`,
+            "error",
+          );
+          return;
+        }
 
-      if (newSessionResult.cancelled) {
-        ctx.ui.notify("New session cancelled", "info");
+        ctx.ui.notify(`Handoff started in a new pane (${parsedArgs.splitDirection}).`, "info");
         return;
       }
 
-      ctx.ui.notify("Handoff started in a new session.", "info");
+      const switchResult = await ctx.switchSession(createdSession.sessionFile, {
+        withSession: async (nextCtx) => {
+          await nextCtx.sendUserMessage(approvedDraft);
+          nextCtx.ui.notify("Handoff started in a new session.", "info");
+        },
+      });
+
+      if (switchResult.cancelled) {
+        ctx.ui.notify("Session switch cancelled", "info");
+      }
     },
   });
 
@@ -116,24 +164,48 @@ export default function sessionHandoffExtension(pi: ExtensionAPI): void {
   });
 
   pi.on("session_start", async (_event, ctx) => {
-    const sessionFile = ctx.sessionManager.getSessionFile();
-    const pending = getPendingInitialPromptFromEntries(ctx.sessionManager.getEntries());
+    const encodedBootstrap = process.env[HANDOFF_BOOTSTRAP_ENV];
+    if (!encodedBootstrap) {
+      return;
+    }
 
-    if (!sessionFile || !pending) {
+    const bootstrap = parseHandoffBootstrap(encodedBootstrap);
+    if (!bootstrap) {
+      delete process.env[HANDOFF_BOOTSTRAP_ENV];
       return;
     }
 
-    pi.appendEntry(
-      PENDING_SEND_CONSUMED_CUSTOM_TYPE,
-      createPendingSendConsumedEntry(pending.initial_prompt_nonce),
-    );
-    pi.sendUserMessage(pending.initial_prompt);
+    if (bootstrap.sessionId !== ctx.sessionManager.getSessionId()) {
+      return;
+    }
+
+    try {
+      const entries = ctx.sessionManager.getEntries();
+      if (hasUserMessages(entries)) {
+        if (ctx.hasUI) {
+          ctx.ui.notify(HANDOFF_STALE_SESSION_MESSAGE, "error");
+        }
+        return;
+      }
+
+      if (!getHandoffMetadataFromEntries(entries)) {
+        pi.appendEntry(
+          HANDOFF_METADATA_CUSTOM_TYPE,
+          createHandoffSessionMetadata(bootstrap.goal, bootstrap.nextTask, bootstrap.initialPrompt),
+        );
+      }
+
+      pi.sendUserMessage(bootstrap.initialPrompt);
+    } finally {
+      delete process.env[HANDOFF_BOOTSTRAP_ENV];
+    }
   });
 
-  pi.on("before_agent_start", async () => {
+  pi.on("before_agent_start", async (event) => {
     return {
       systemPrompt:
-        "When the user references @session:<uuid>, treat it as a session token. If you call session_ask, pass only the UUID value, not the @session: prefix.",
+        event.systemPrompt +
+        "\n\nWhen the user references @session:<uuid>, treat it as a session token. If you call session_ask, pass only the UUID value, not the @session: prefix.",
     };
   });
 }
@@ -201,3 +273,56 @@ function formatHandoffError(error: unknown): string {
 
   return "Handoff generation failed.";
 }
+
+function parseHandoffCommandArgs(
+  args: string,
+):
+  | { kind: "ok"; goal: string; splitDirection?: HandoffSplitDirection | undefined }
+  | { kind: "error"; message: string } {
+  const tokens = args
+    .trim()
+    .split(/\s+/)
+    .filter((token) => token.length > 0);
+
+  if (tokens.length === 0) {
+    return { kind: "error", message: HANDOFF_USAGE };
+  }
+
+  const directionFlags = new Map<string, HandoffSplitDirection>([
+    ["--left", "left"],
+    ["--right", "right"],
+    ["--up", "up"],
+    ["--down", "down"],
+  ]);
+
+  let splitDirection: HandoffSplitDirection | undefined;
+  const goalTokens: string[] = [];
+
+  for (const token of tokens) {
+    const direction = directionFlags.get(token);
+    if (!direction) {
+      goalTokens.push(token);
+      continue;
+    }
+
+    if (splitDirection) {
+      return {
+        kind: "error",
+        message: "Use only one split flag: --left, --right, --up, or --down.",
+      };
+    }
+
+    splitDirection = direction;
+  }
+
+  const goal = goalTokens.join(" ").trim();
+  if (!goal) {
+    return { kind: "error", message: HANDOFF_USAGE };
+  }
+
+  return {
+    kind: "ok",
+    goal,
+    splitDirection,
+  };
+}

package/extensions/session-hooks.ts

@@ -1,4 +1,5 @@
-import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import type { ExtensionAPI, ExtensionContext } from "@mariozechner/pi-coding-agent";
+import { HANDOFF_BOOTSTRAP_ENV, parseHandoffBootstrap } from "./session-handoff/metadata.js";
 import { createSessionHookController } from "./session-search/hooks.js";
 import { loadSettings } from "./shared/settings.js";
 
@@ -18,7 +19,12 @@ export default function sessionHooksExtension(pi: ExtensionAPI): void {
     switch (reason) {
       case "new":
       case "resume":
-        await controller.handleSessionSwitch(previousSessionFile, sessionFile, ctx.cwd);
+        await controller.handleSessionSwitch(
+          previousSessionFile,
+          sessionFile,
+          ctx.cwd,
+          getSessionStartOrigin(ctx),
+        );
         break;
       case "fork":
         await controller.handleSessionFork(previousSessionFile, sessionFile, ctx.cwd);
@@ -53,3 +59,17 @@ export default function sessionHooksExtension(pi: ExtensionAPI): void {
     await controller.handleSessionShutdown(ctx.sessionManager.getSessionFile(), ctx.cwd);
   });
 }
+
+function getSessionStartOrigin(ctx: ExtensionContext): "handoff" | undefined {
+  const encodedBootstrap = process.env[HANDOFF_BOOTSTRAP_ENV];
+  if (!encodedBootstrap) {
+    return undefined;
+  }
+
+  const bootstrap = parseHandoffBootstrap(encodedBootstrap);
+  if (!bootstrap) {
+    return undefined;
+  }
+
+  return bootstrap.sessionId === ctx.sessionManager.getSessionId() ? "handoff" : undefined;
+}

package/extensions/session-search/extract.ts

@@ -157,7 +157,7 @@ export function extractSessionRecord(sessionPath: string): ExtractedSessionRecor
       }
       case "custom": {
         const nextHandoffMetadata = extractHandoffMetadata(entry, entryTs);
-        if (nextHandoffMetadata) {
+        if (nextHandoffMetadata && !durableHandoffMetadata) {
           durableHandoffMetadata = nextHandoffMetadata;
         }
         continue;
@@ -282,7 +282,7 @@ function findDurableHandoffMetadata(
     }
 
     const parsed = extractHandoffMetadata(entry, getEntryTimestamp(entry, fallbackTs));
-    if (parsed) {
+    if (parsed && !durableHandoffMetadata) {
       durableHandoffMetadata = parsed;
     }
   }

package/extensions/session-search/hooks.ts

@@ -22,6 +22,9 @@ import {
 import { type ExtractedSessionRecord, extractSessionRecord } from "./extract.js";
 
 const TOOL_RESULT_TEXT_LIMIT = 500;
+const HOOK_INDEX_WRITE_TIMEOUT_MS = 500;
+const HOOK_INDEX_WRITE_MAX_ATTEMPTS = 4;
+const HOOK_INDEX_WRITE_RETRY_DELAYS_MS = [150, 400, 1000];
 
 type TrackedToolName = "read" | "edit" | "write";
 
@@ -96,15 +99,24 @@ export function createSessionHookController(options: { indexPath: string }): Ses
       return syncAttachedSession(indexPath, state, "session_start");
     },
     async handleSessionSwitch(previousSessionFile, sessionFile, cwd, sessionOrigin) {
-      const previousSynced = syncSessionFile(indexPath, previousSessionFile, "session_switch");
+      const previousSynced = await syncSessionFile(
+        indexPath,
+        previousSessionFile,
+        "session_switch",
+      );
       attachSession(state, sessionFile, cwd);
-      const currentSynced = syncAttachedSession(indexPath, state, "session_switch", sessionOrigin);
+      const currentSynced = await syncAttachedSession(
+        indexPath,
+        state,
+        "session_switch",
+        sessionOrigin,
+      );
       return previousSynced || currentSynced;
     },
     async handleSessionFork(previousSessionFile, sessionFile, cwd) {
-      const previousSynced = syncSessionFile(indexPath, previousSessionFile, "session_fork");
+      const previousSynced = await syncSessionFile(indexPath, previousSessionFile, "session_fork");
       attachSession(state, sessionFile, cwd);
-      const currentSynced = syncAttachedSession(indexPath, state, "session_fork", "fork");
+      const currentSynced = await syncAttachedSession(indexPath, state, "session_fork", "fork");
       return previousSynced || currentSynced;
     },
     handleToolCall(event, sessionFile, cwd) {
@@ -131,9 +143,11 @@ export function createSessionHookController(options: { indexPath: string }): Ses
     },
     async handleTurnEnd(sessionFile, cwd) {
       attachSession(state, sessionFile, cwd);
-      const synced = syncAttachedSession(indexPath, state, "turn_end");
-      clearTurnState(state);
-      return synced;
+      try {
+        return await syncAttachedSession(indexPath, state, "turn_end");
+      } finally {
+        clearTurnState(state);
+      }
     },
     async handleSessionTree(sessionFile, cwd) {
       attachSession(state, sessionFile, cwd);
@@ -145,11 +159,13 @@ export function createSessionHookController(options: { indexPath: string }): Ses
     },
     async handleSessionShutdown(sessionFile, cwd) {
       attachSession(state, sessionFile, cwd);
-      const synced = syncAttachedSession(indexPath, state, "session_shutdown");
-      clearTurnState(state);
-      state.currentSessionFile = undefined;
-      state.currentCwd = undefined;
-      return synced;
+      try {
+        return await syncAttachedSession(indexPath, state, "session_shutdown");
+      } finally {
+        clearTurnState(state);
+        state.currentSessionFile = undefined;
+        state.currentCwd = undefined;
+      }
     },
   };
 }
@@ -166,22 +182,66 @@ function attachSession(
   state.currentCwd = cwd;
 }
 
+async function retryIndexWrite<T>(action: () => T): Promise<T> {
+  for (let attempt = 1; attempt <= HOOK_INDEX_WRITE_MAX_ATTEMPTS; attempt += 1) {
+    try {
+      return action();
+    } catch (error) {
+      if (!isRetryableSqliteLock(error) || attempt >= HOOK_INDEX_WRITE_MAX_ATTEMPTS) {
+        throw error;
+      }
+
+      await sleep(getRetryDelayMs(attempt));
+    }
+  }
+
+  return action();
+}
+
+function getRetryDelayMs(attempt: number): number {
+  return (
+    HOOK_INDEX_WRITE_RETRY_DELAYS_MS[attempt - 1] ??
+    HOOK_INDEX_WRITE_RETRY_DELAYS_MS[HOOK_INDEX_WRITE_RETRY_DELAYS_MS.length - 1] ??
+    0
+  );
+}
+
+function isRetryableSqliteLock(error: unknown): boolean {
+  if (!(error instanceof Error)) {
+    return false;
+  }
+
+  const code = "code" in error && typeof error.code === "string" ? error.code : undefined;
+  const message = error.message.toLowerCase();
+  return (
+    code === "SQLITE_BUSY" ||
+    code === "SQLITE_LOCKED" ||
+    code?.startsWith("SQLITE_BUSY_") === true ||
+    code?.startsWith("SQLITE_LOCKED_") === true ||
+    message.includes("database is locked")
+  );
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
 function syncAttachedSession(
   indexPath: string,
   state: SessionHookState,
   eventType: string,
   sessionOrigin?: SessionOrigin,
-): boolean {
+): Promise<boolean> {
   return syncSessionFile(indexPath, state.currentSessionFile, eventType, state, sessionOrigin);
 }
 
-function syncSessionFile(
+async function syncSessionFile(
   indexPath: string,
   sessionFile: string | undefined,
   eventType: string,
   state?: SessionHookState,
   sessionOrigin?: SessionOrigin,
-): boolean {
+): Promise<boolean> {
   if (!sessionFile || !existsSync(sessionFile)) {
     return false;
   }
@@ -196,31 +256,36 @@ function syncSessionFile(
     return false;
   }
 
-  const db = openIndexDatabase(indexPath, { create: false });
-  try {
-    db.transaction(() => {
-      const existingSession = getSessionById(db, extracted.sessionId);
-      const sessionRow = mergeSessionLineage(extracted, existingSession, sessionOrigin);
-      upsertSession(db, sessionRow, "hook");
-      if (shouldRefreshLineageRelations(existingSession, sessionRow)) {
-        rebuildSessionLineageRelations(db);
-      }
-      clearSessionIndexedData(db, extracted.sessionId);
-
-      for (const chunk of extracted.chunks) {
-        insertTextChunk(db, { sessionId: extracted.sessionId, ...chunk });
-      }
-
-      for (const fileTouch of extracted.fileTouches) {
-        insertSessionFileTouch(db, { sessionId: extracted.sessionId, ...fileTouch });
-      }
-
-      setMetadata(db, "hook_updated_at", new Date().toISOString());
-      setMetadata(db, "hook_last_event", eventType);
-    })();
-  } finally {
-    db.close();
-  }
+  await retryIndexWrite(() => {
+    const db = openIndexDatabase(indexPath, {
+      create: false,
+      timeoutMs: HOOK_INDEX_WRITE_TIMEOUT_MS,
+    });
+    try {
+      db.transaction(() => {
+        const existingSession = getSessionById(db, extracted.sessionId);
+        const sessionRow = mergeSessionLineage(extracted, existingSession, sessionOrigin);
+        upsertSession(db, sessionRow, "hook");
+        if (shouldRefreshLineageRelations(existingSession, sessionRow)) {
+          rebuildSessionLineageRelations(db);
+        }
+        clearSessionIndexedData(db, extracted.sessionId);
+
+        for (const chunk of extracted.chunks) {
+          insertTextChunk(db, { sessionId: extracted.sessionId, ...chunk });
+        }
+
+        for (const fileTouch of extracted.fileTouches) {
+          insertSessionFileTouch(db, { sessionId: extracted.sessionId, ...fileTouch });
+        }
+
+        setMetadata(db, "hook_updated_at", new Date().toISOString());
+        setMetadata(db, "hook_last_event", eventType);
+      })();
+    } finally {
+      db.close();
+    }
+  });
 
   if (state) {
     state.lastFlushedSessionFile = sessionFile;

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

@@ -26,10 +26,15 @@ export function createTempIndexPath(finalPath: string): string {
 
 export function openIndexDatabase(
   dbPath: string,
-  options?: { create?: boolean },
+  options?: { create?: boolean; timeoutMs?: number },
 ): SessionIndexDatabase {
   const create = options?.create ?? true;
-  const db = new Database(dbPath, { fileMustExist: !create });
+  const db = new Database(
+    dbPath,
+    options?.timeoutMs === undefined
+      ? { fileMustExist: !create }
+      : { fileMustExist: !create, timeout: options.timeoutMs },
+  );
   db.pragma("journal_mode = WAL");
   db.pragma("synchronous = NORMAL");
   db.pragma("foreign_keys = ON");

package/extensions/shared/settings.ts

@@ -1,6 +1,6 @@
 import os from "node:os";
 import path from "node:path";
-import { getAgentDir, SettingsManager } from "@mariozechner/pi-coding-agent";
+import { SettingsManager } from "@mariozechner/pi-coding-agent";
 import type { KeyId } from "@mariozechner/pi-tui";
 import { type Static, Type } from "@sinclair/typebox";
 import { parseTypeBoxValue } from "./typebox.js";
@@ -114,7 +114,7 @@ function parseModelReference(value: string | undefined): ModelReference | undefi
 }
 
 function loadSessionFileSettings(): SessionFileSettings {
-  const globalSettings = SettingsManager.create(undefined, getAgentDir()).getGlobalSettings();
+  const globalSettings = SettingsManager.create(process.cwd()).getGlobalSettings();
   const parsed = parseTypeBoxValue(ROOT_SETTINGS_SCHEMA, globalSettings, "Invalid settings");
   return parsed.sessions ?? {};
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-sessions",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "type": "module",
   "description": "Pi session search, ask, handoff, auto-titling, and indexing tools",
   "license": "MIT",
@@ -38,27 +38,28 @@
     "prepare": "husky"
   },
   "devDependencies": {
-    "@biomejs/biome": "^2.4.11",
-    "@mariozechner/pi-ai": "^0.66.1",
-    "@mariozechner/pi-coding-agent": "^0.66.1",
-    "@mariozechner/pi-tui": "^0.66.1",
+    "@biomejs/biome": "^2.4.12",
+    "@mariozechner/pi-ai": "^0.70.2",
+    "@mariozechner/pi-coding-agent": "^0.70.2",
+    "@mariozechner/pi-tui": "^0.70.2",
+    "@sinclair/typebox": "^0.34.49",
     "@types/better-sqlite3": "^7.6.13",
     "@types/node": "^25.6.0",
     "husky": "^9.1.7",
     "lint-staged": "^16.4.0",
-    "typescript": "^6.0.2",
+    "typescript": "^6.0.3",
     "vitest": "^4.1.4"
   },
-  "dependencies": {
-    "better-sqlite3": "^12.8.0"
-  },
   "peerDependencies": {
-    "@mariozechner/pi-ai": ">=0.66.1",
-    "@mariozechner/pi-coding-agent": ">=0.66.1",
-    "@mariozechner/pi-tui": ">=0.66.1",
-    "@sinclair/typebox": ">=0.34.49"
+    "@mariozechner/pi-ai": ">=0.70.2",
+    "@mariozechner/pi-coding-agent": ">=0.70.2",
+    "@mariozechner/pi-tui": ">=0.70.2",
+    "@sinclair/typebox": ">=0.34.41"
   },
   "lint-staged": {
     "*.{js,cjs,mjs,jsx,ts,tsx,json,jsonc}": "biome check --write --no-errors-on-unmatched"
+  },
+  "dependencies": {
+    "better-sqlite3": "^12.9.0"
   }
 }