@tekmidian/pai 0.30.1 → 0.32.0

package/docs/commands/projects.md

@@ -20,6 +20,8 @@ pai projects <subcommand> [options]
 | [`pai projects add <path>`](#pai-projects-add-path) | Register a project directory in the PAI registry |
 | [`pai projects info <slug>`](#pai-projects-info-slug) | Show full details for a project |
 | [`pai projects archive <slug>`](#pai-projects-archive-slug) | Archive a project |
+| [`pai projects merge <from> <into>`](#pai-projects-merge-from-into) | Fold a duplicate project into another: move its sessions (renumbered), repoint its tags, aliases, compaction records and links, keep the old slug as an alias, then delete the row. Preview unless --execute is given. |
+| [`pai projects unregister <slug>`](#pai-projects-unregister-slug) | Remove a project row entirely, for paths that should never have been registered (worktrees, temp dirs). Refuses when the row holds sessions — merge those first. Preview unless --execute is given. The directory itself is never touched. |
 | [`pai projects unarchive <slug>`](#pai-projects-unarchive-slug) | Restore an archived project to active status |
 | [`pai projects move <slug> <new-path>`](#pai-projects-move-slug-new-path) | Update the root path for a project |
 | [`pai projects rebind <slug> <new-path>`](#pai-projects-rebind-slug-new-path) | Manually update the root_path for a project (for when auto-detect found multiple matches). |
@@ -119,6 +121,42 @@ Archive a project
 | `<slug>` | required |
 
 
+### pai projects merge <from> <into>
+
+Fold a duplicate project into another: move its sessions (renumbered), repoint its tags, aliases, compaction records and links, keep the old slug as an alias, then delete the row. Preview unless --execute is given.
+
+**Arguments**
+
+| Argument | Kind |
+|----------|------|
+| `<from>` | required |
+| `<into>` | required |
+
+**Options**
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `--execute` | Actually perform the merge |  |
+
+
+### pai projects unregister <slug>
+
+Remove a project row entirely, for paths that should never have been registered (worktrees, temp dirs). Refuses when the row holds sessions — merge those first. Preview unless --execute is given. The directory itself is never touched.
+
+**Arguments**
+
+| Argument | Kind |
+|----------|------|
+| `<slug>` | required |
+
+**Options**
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `--execute` | Actually remove the row |  |
+| `--force` | Remove even though sessions would be deleted with it |  |
+
+
 ### pai projects unarchive <slug>
 
 Restore an archived project to active status

package/docs/commands/session.md

@@ -17,6 +17,7 @@ pai session <subcommand> [options]
 | Command | Description |
 |---------|-------------|
 | [`pai session list`](#pai-session-list) | Resumable sessions catalog — named sessions with resume status. |
+| [`pai session restore`](#pai-session-restore) | Restore transcripts PAI displaced into sessions/ so claude --resume can find them again. Reports what is unresumable, which checkpoints promise it, and which transcripts are empty. Dry run unless --execute is given. |
 | [`pai session info <project-slug> <number>`](#pai-session-info-project-slug-number) | Show full details for a specific session |
 | [`pai session rename <project-slug> <number> <new-slug>`](#pai-session-rename-project-slug-number-new-slug) | Rename a session note — updates file on disk, H1 title, and registry |
 | [`pai session slug <project-slug> <number>`](#pai-session-slug-project-slug-number) | Generate a descriptive slug from the session JSONL transcript |
@@ -49,6 +50,22 @@ Use --all to also show unnamed orphan sessions.
 | `--json` | Output raw JSON instead of formatted table |  |
 
 
+### pai session restore
+
+Restore transcripts PAI displaced into sessions/ so claude --resume can find them again. Reports what is unresumable, which checkpoints promise it, and which transcripts are empty. Dry run unless --execute is given.
+
+**Options**
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `--execute` | Actually restore (hardlink back to the project root) |  |
+| `--promised` | Only sessions a checkpoint tells you to resume |  |
+| `--cwd <path>` | Only sessions belonging to this working directory |  |
+| `--all` | List every displaced session, not just the largest few |  |
+| `--include-stubs` | Also restore transcripts that hold no conversation |  |
+| `--json` | Output raw JSON instead of a formatted report |  |
+
+
 ### pai session info <project-slug> <number>
 
 Show full details for a specific session

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tekmidian/pai",
-  "version": "0.30.1",
+  "version": "0.32.0",
   "description": "PAI Knowledge OS — Personal AI Infrastructure with federated memory and project management",
   "type": "module",
   "main": "dist/index.mjs",

package/src/hooks/ts/lib/project-utils/index.ts

@@ -17,7 +17,7 @@ export {
   ensureNotesDirSmart,
   ensureSessionsDir,
   ensureSessionsDirFromProjectDir,
-  moveSessionFilesToSessionsDir,
+  archiveSessionFilesToSessionsDir,
   findTodoPath,
   findClaudeMdPath,
   findAllClaudeMdPaths,

package/src/hooks/ts/lib/project-utils/paths.test.ts

@@ -0,0 +1,125 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import {
+  mkdtempSync,
+  rmSync,
+  mkdirSync,
+  writeFileSync,
+  existsSync,
+  statSync,
+  readFileSync,
+} from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { archiveSessionFilesToSessionsDir } from "./paths.js";
+
+/**
+ * The archiver is the function that destroyed users' sessions.
+ *
+ * It used to renameSync transcripts out of the project root into sessions/, and
+ * `claude --resume <uuid>` only finds them at the root. Measured 2026-08-04:
+ * resuming an 867 KB transcript that lived only in sessions/ answered
+ * "No conversation found with session ID". It ran from a UserPromptSubmit hook
+ * excluding only the current session, so every prompt anyone typed unresumed
+ * every other session in the project — one project measured 1 transcript at the
+ * root against 52 underneath.
+ *
+ * So the assertion that matters in every case below is the same one, and it is
+ * about the SOURCE, not the destination: the root file must still be there.
+ */
+
+let projectDir: string;
+const sessions = () => join(projectDir, "sessions");
+const A = "aaaaaaaa-1111-4111-8111-111111111111.jsonl";
+const B = "bbbbbbbb-2222-4222-8222-222222222222.jsonl";
+
+beforeEach(() => {
+  projectDir = mkdtempSync(join(tmpdir(), "pai-paths-"));
+});
+
+afterEach(() => {
+  rmSync(projectDir, { recursive: true, force: true });
+});
+
+describe("archiving a transcript never removes it from the project root", () => {
+  it("leaves the source in place — the whole bug in one assertion", () => {
+    writeFileSync(join(projectDir, A), '{"type":"user"}\n');
+
+    expect(archiveSessionFilesToSessionsDir(projectDir, undefined, true)).toBe(1);
+
+    expect(existsSync(join(projectDir, A))).toBe(true); // resume needs THIS one
+    expect(existsSync(join(sessions(), A))).toBe(true); // consumers need this one
+  });
+
+  it("links rather than copies, so the archive cannot drift or cost space", () => {
+    writeFileSync(join(projectDir, A), '{"type":"user"}\n');
+    archiveSessionFilesToSessionsDir(projectDir, undefined, true);
+
+    const root = statSync(join(projectDir, A));
+    const archived = statSync(join(sessions(), A));
+    expect(archived.ino).toBe(root.ino);
+    expect(archived.nlink).toBeGreaterThanOrEqual(2);
+  });
+
+  it("keeps the archive current as the live transcript grows", () => {
+    // One inode means appends are visible through both names. A copy would
+    // freeze the archive at archive time, and session-summary-worker reads the
+    // archive to write session notes — it would summarise a truncated session.
+    writeFileSync(join(projectDir, A), '{"type":"user"}\n');
+    archiveSessionFilesToSessionsDir(projectDir, undefined, true);
+    writeFileSync(join(projectDir, A), '{"type":"user"}\n{"type":"assistant"}\n');
+
+    expect(readFileSync(join(sessions(), A), "utf8")).toContain("assistant");
+  });
+});
+
+describe("what it archives", () => {
+  it("archives every transcript in the root", () => {
+    writeFileSync(join(projectDir, A), "a");
+    writeFileSync(join(projectDir, B), "b");
+
+    expect(archiveSessionFilesToSessionsDir(projectDir, undefined, true)).toBe(2);
+    expect(existsSync(join(projectDir, A))).toBe(true);
+    expect(existsSync(join(projectDir, B))).toBe(true);
+  });
+
+  it("skips the excluded live session", () => {
+    writeFileSync(join(projectDir, A), "a");
+    writeFileSync(join(projectDir, B), "b");
+
+    expect(archiveSessionFilesToSessionsDir(projectDir, B, true)).toBe(1);
+    expect(existsSync(join(sessions(), A))).toBe(true);
+    expect(existsSync(join(sessions(), B))).toBe(false);
+    expect(existsSync(join(projectDir, B))).toBe(true);
+  });
+
+  it("ignores files that are not transcripts", () => {
+    writeFileSync(join(projectDir, "notes.md"), "x");
+    expect(archiveSessionFilesToSessionsDir(projectDir, undefined, true)).toBe(0);
+  });
+
+  it("is idempotent, and does not disturb what is already archived", () => {
+    // The hooks call this on every prompt and at every session end, so running
+    // twice is the normal case, not an edge case.
+    writeFileSync(join(projectDir, A), "a");
+    expect(archiveSessionFilesToSessionsDir(projectDir, undefined, true)).toBe(1);
+    expect(archiveSessionFilesToSessionsDir(projectDir, undefined, true)).toBe(0);
+    expect(existsSync(join(projectDir, A))).toBe(true);
+  });
+
+  it("leaves an already-archived transcript alone rather than relinking it", () => {
+    // A transcript archived by the OLD destructive version: present underneath,
+    // absent from the root. Restoring those is a separate repair (launch.ts),
+    // and this must not clobber the archived copy while that is pending.
+    mkdirSync(sessions(), { recursive: true });
+    writeFileSync(join(sessions(), A), "archived-by-the-old-rename");
+
+    expect(archiveSessionFilesToSessionsDir(projectDir, undefined, true)).toBe(0);
+    expect(readFileSync(join(sessions(), A), "utf8")).toBe("archived-by-the-old-rename");
+  });
+
+  it("returns 0 for a project directory that does not exist", () => {
+    expect(
+      archiveSessionFilesToSessionsDir(join(projectDir, "nope"), undefined, true)
+    ).toBe(0);
+  });
+});

package/src/hooks/ts/lib/project-utils/paths.ts

@@ -2,7 +2,7 @@
  * Path utilities — encoding, Notes/Sessions directory discovery and creation.
  */
 
-import { existsSync, mkdirSync, readdirSync, renameSync } from 'fs';
+import { existsSync, mkdirSync, readdirSync, linkSync, copyFileSync } from 'fs';
 import { join, basename } from 'path';
 import { PAI_DIR } from '../pai-paths.js';
 
@@ -137,10 +137,43 @@ export function ensureSessionsDirFromProjectDir(projectDir: string): string {
 }
 
 /**
- * Move all .jsonl session files from project root to sessions/ subdirectory.
- * Returns the number of files moved.
+ * Publish every project-root .jsonl into sessions/ as well, WITHOUT removing it.
+ *
+ * This used to renameSync, and that is how PAI destroyed its users' sessions.
+ *
+ * `claude --resume <uuid>` finds a transcript only at the project root. Move it
+ * into sessions/ and the session becomes permanently unresumable — measured
+ * 2026-08-04: `claude --resume b3462801` (867 KB of real work, sessions/ only)
+ * answers "No conversation found with session ID", while a top-level id is found
+ * fine. Nothing warned; the id still looked valid everywhere PAI displayed it.
+ *
+ * The damage was not occasional. This ran from a UserPromptSubmit hook excluding
+ * only the CURRENT session, so every prompt anyone typed unresumed every other
+ * session in the project. One PAI project measured 1 transcript at top level
+ * against 52 underneath. Among the casualties was 046bb712 — the exact id PAI's
+ * own handover tells the user to resume.
+ *
+ * A hardlink satisfies both sides, which is why this is a two-line fix rather
+ * than a redesign: the archive genuinely has consumers that read sessions/
+ * (session-summary-worker, registry/moved, session/autosave), and `--resume`
+ * needs the root path. One inode, two names, no copy, no window where the file
+ * is missing from either place.
+ *
+ * Never unlink the source. Tidying up another tool's store was the whole
+ * mistake; a stale duplicate is free, a lost session is not. Every caller of
+ * `transcriptFiles()` was checked before choosing this — they all test emptiness
+ * (`.length > 0`), never count, so the duplicate cannot skew a project's stats.
+ *
+ * `excludeFile` keeps a hook from archiving the transcript it is itself watching
+ * being written. It is not a "finished sessions only" guard and must not be read
+ * as one: it excludes exactly one file, the caller's own, so with two sessions
+ * live in one project each still archives the other mid-turn. A consumer that
+ * needs "finished only" has to enforce that itself — this function cannot know
+ * what is live.
+ *
+ * Returns the number of files newly archived.
  */
-export function moveSessionFilesToSessionsDir(
+export function archiveSessionFilesToSessionsDir(
   projectDir: string,
   excludeFile?: string,
   silent = false
@@ -150,25 +183,46 @@ export function moveSessionFilesToSessionsDir(
   if (!existsSync(projectDir)) return 0;
 
   const files = readdirSync(projectDir);
-  let movedCount = 0;
+  let archivedCount = 0;
 
   for (const file of files) {
-    if (file.endsWith('.jsonl') && file !== excludeFile) {
-      const sourcePath = join(projectDir, file);
-      const destPath = join(sessionsDir, file);
+    if (!file.endsWith('.jsonl') || file === excludeFile) continue;
+
+    const sourcePath = join(projectDir, file);
+    const destPath = join(sessionsDir, file);
+
+    // Already archived — including by an earlier rename, before this was a
+    // hardlink. Those are the sessions that need restoring to the root, which is
+    // a separate repair and not this function's job.
+    if (existsSync(destPath)) continue;
+
+    try {
+      linkSync(sourcePath, destPath);
+      if (!silent) console.error(`Archived ${file} → sessions/ (still resumable)`);
+      archivedCount++;
+    } catch (error) {
+      // Cross-device (EXDEV) is the realistic failure: sessions/ on another
+      // volume. Copy instead, and still leave the original alone.
       try {
-        renameSync(sourcePath, destPath);
-        if (!silent) console.error(`Moved ${file} → sessions/`);
-        movedCount++;
-      } catch (error) {
-        if (!silent) console.error(`Could not move ${file}: ${error}`);
+        copyFileSync(sourcePath, destPath);
+        if (!silent) console.error(`Copied ${file} → sessions/ (hardlink unavailable)`);
+        archivedCount++;
+      } catch {
+        if (!silent) console.error(`Could not archive ${file}: ${error}`);
       }
     }
   }
 
-  return movedCount;
+  return archivedCount;
 }
 
+/**
+ * @deprecated Renamed to `archiveSessionFilesToSessionsDir`, which is what it
+ * now does. Kept so an out-of-tree caller fails loudly at the type level rather
+ * than silently keeping the old destructive name for a non-destructive action.
+ */
+export const moveSessionFilesToSessionsDir = archiveSessionFilesToSessionsDir;
+
 // ---------------------------------------------------------------------------
 // CLAUDE.md / TODO.md discovery
 // ---------------------------------------------------------------------------

package/src/hooks/ts/lib/project-utils.ts

@@ -17,7 +17,7 @@ export {
   ensureNotesDirSmart,
   ensureSessionsDir,
   ensureSessionsDirFromProjectDir,
-  moveSessionFilesToSessionsDir,
+  archiveSessionFilesToSessionsDir,
   findTodoPath,
   findClaudeMdPath,
   findAllClaudeMdPaths,

package/src/hooks/ts/session-start/load-project-context.ts

@@ -31,7 +31,8 @@ import {
   findTodoPath,
   findAllClaudeMdPaths,
   sendNtfyNotification,
-  isProbeSession
+  isProbeSession,
+  archiveSessionFilesToSessionsDir
 } from '../lib/project-utils';
 
 /**
@@ -244,40 +245,42 @@ async function main() {
     }
   }
 
-  // 3. Cleanup old .jsonl files from project root (move to sessions/)
-  // Keep the newest one for potential resume, move older ones to sessions/
+  // 3. Archive the project's transcripts into sessions/ — by LINKING, never moving.
+  //
+  // This used to renameSync every .jsonl except the newest out of the project
+  // root. `claude --resume <uuid>` reads ~/.claude/projects/<encoded>/<uuid>.jsonl
+  // and only that path, so moving the file is what makes a session unresumable —
+  // and because this is a SessionStart hook, the act of STARTING a session in a
+  // project destroyed the resumability of every earlier session in it. The old
+  // comment ("keep the newest one for potential resume") shows the dependency was
+  // known; keeping one file was not enough.
+  //
+  // Measured 2026-08-04: this repo had 1 transcript at the top level and 52 under
+  // sessions/, every one of the 52 unresumable. Among them was the id PAI prints
+  // in its own archived handovers as `claude --resume <uuid>`, so the instruction
+  // we ship in every checkpoint could not work.
+  //
+  // It also completes the incident of that morning: `pai Paperfull` failed to
+  // resume b3462801 because of a probe bug, started a fresh session instead, and
+  // THIS hook then moved b3462801 — 867 KB of real work — out of reach. The
+  // failed resume destroyed what it had failed to open.
+  //
+  // A hard link keeps both truths: the archive under sessions/ is populated for
+  // everything that reads it, and the file Claude Code owns stays where Claude
+  // Code put it. Same inode, so it costs nothing.
+  // This was the fourth mover, with its own inline loop. It now calls the one
+  // shared archiver instead: a second implementation is exactly how the earlier
+  // probeResume fix came to land in one of three copies and leave `pai <Name>`
+  // broken for a day.
   const projectDir = getProjectDir(cwd);
   if (existsSync(projectDir)) {
     try {
-      const files = readdirSync(projectDir);
-      const jsonlFiles = files
-        .filter(f => f.endsWith('.jsonl'))
-        .map(f => ({
-          name: f,
-          path: join(projectDir, f),
-          mtime: statSync(join(projectDir, f)).mtime.getTime()
-        }))
-        .sort((a, b) => b.mtime - a.mtime); // newest first
-
-      if (jsonlFiles.length > 1) {
-        const { mkdirSync, renameSync } = await import('fs');
-        const sessionsDir = join(projectDir, 'sessions');
-        if (!existsSync(sessionsDir)) {
-          mkdirSync(sessionsDir, { recursive: true });
-        }
-
-        // Move all except the newest
-        for (let i = 1; i < jsonlFiles.length; i++) {
-          const file = jsonlFiles[i];
-          const destPath = join(sessionsDir, file.name);
-          if (!existsSync(destPath)) {
-            renameSync(file.path, destPath);
-            console.error(`Moved old session: ${file.name} → sessions/`);
-          }
-        }
-      }
+      // Exclude this session's own transcript: it is being written right now,
+      // and the archive is meant to hold finished sessions.
+      const own = hookInput?.session_id ? `${hookInput.session_id}.jsonl` : undefined;
+      archiveSessionFilesToSessionsDir(projectDir, own, true);
     } catch (error) {
-      console.error(`Could not cleanup old .jsonl files: ${error}`);
+      console.error(`Could not archive session transcripts: ${error}`);
     }
   }
 

package/src/hooks/ts/stop/stop-hook.ts

@@ -8,7 +8,7 @@ import {
   sendNtfyNotification,
   getCurrentNotePath,
   finalizeSessionNote,
-  moveSessionFilesToSessionsDir,
+  archiveSessionFilesToSessionsDir,
   addWorkToSessionNote,
   findNotesDir,
   isProbeSession,
@@ -668,12 +668,12 @@ async function executeDirectly(
   // Move session .jsonl files to sessions/
   try {
     const transcriptDir = dirname(transcriptPath);
-    const movedCount = moveSessionFilesToSessionsDir(transcriptDir);
-    if (movedCount > 0) {
-      console.error(`Moved ${movedCount} session file(s) to sessions/`);
+    const archivedCount = archiveSessionFilesToSessionsDir(transcriptDir);
+    if (archivedCount > 0) {
+      console.error(`Archived ${archivedCount} session file(s) to sessions/`);
     }
   } catch (moveError) {
-    console.error(`Could not move session files: ${moveError}`);
+    console.error(`Could not archive session files: ${moveError}`);
   }
 }
 

package/src/hooks/ts/user-prompt/cleanup-session-files.ts

@@ -9,7 +9,7 @@
  */
 
 import { dirname, basename } from 'path';
-import { moveSessionFilesToSessionsDir } from '../lib/project-utils';
+import { archiveSessionFilesToSessionsDir } from '../lib/project-utils';
 
 interface HookInput {
   session_id: string;
@@ -31,11 +31,24 @@ async function main() {
     const projectDir = dirname(data.transcript_path);
     const currentSessionFile = basename(data.transcript_path);
 
-    // Move stray .jsonl files, excluding the current active session (silent mode)
-    const movedCount = moveSessionFilesToSessionsDir(projectDir, currentSessionFile, true);
-
-    if (movedCount > 0) {
-      console.error(`Cleaned up ${movedCount} session file(s) to sessions/`);
+    // Archive stray .jsonl files, excluding this session's own transcript.
+    //
+    // That exclusion is narrow, and worth stating precisely because it is easy to
+    // read as more: it keeps a hook from archiving the very file it is watching
+    // being written. It does NOT make the archive "finished sessions only" — it
+    // excludes exactly one file, the caller's. With two sessions live in one
+    // project, each one's prompt still archives the other's in-progress
+    // transcript.
+    //
+    // Harmless now that archiving is a hardlink and nothing is destroyed. If a
+    // consumer ever needs "finished only", the guard belongs in that consumer —
+    // session-summary-worker could skip a transcript modified seconds ago, or one
+    // whose uuid is in AIBroker's live-session list. The archiver cannot know
+    // what is live and should not pretend to.
+    const archivedCount = archiveSessionFilesToSessionsDir(projectDir, currentSessionFile, true);
+
+    if (archivedCount > 0) {
+      console.error(`Archived ${archivedCount} session file(s) to sessions/`);
     }
   } catch {
     // Silent failure - don't block user prompts

package/dist/factory-BqAdO21B.mjs.map

@@ -1 +0,0 @@
-{"version":3,"file":"factory-BqAdO21B.mjs","names":[],"sources":["../src/storage/outage.ts","../src/storage/factory.ts"],"sourcesContent":["/**\n * outage.ts — is the storage backend actually reachable right now?\n *\n * The daemon retries a dead backend forever, which is correct: a Postgres\n * container that is down will usually come back, and giving up would lose the\n * work queue. What was wrong is that it did so in complete silence.\n *\n * Observed 2026-07-26: the container was down for roughly two days. The daemon\n * logged \"Postgres unavailable\" 144 times over 36 minutes, the work queue backed\n * up, session notes for the whole period were never written — and\n * `pai daemon status` reported \"Index: idle\" throughout. The one command anyone\n * would run to check said everything was fine.\n *\n * So the outage is recorded where the status command can see it, and escalated\n * once through the notification channels that were already configured and\n * already unused for this.\n */\n\nexport interface BackendOutage {\n  backend: string;\n  /** When the current run of failures began. */\n  since: number;\n  /** Consecutive failed attempts so far. */\n  attempts: number;\n  lastError: string;\n}\n\nlet current: BackendOutage | null = null;\n\n/** Record that the backend is currently unreachable. */\nexport function setBackendOutage(outage: BackendOutage): void {\n  current = outage;\n}\n\n/**\n * Record that the backend answered.\n *\n * Called on every successful connection, including the first — so a daemon that\n * never had a problem reports none, and one that recovered stops reporting an\n * outage that has ended.\n */\nexport function clearBackendOutage(): void {\n  current = null;\n}\n\n/** The current outage, or null when the backend is answering. */\nexport function getBackendOutage(): BackendOutage | null {\n  return current;\n}\n\n/** Human-readable duration, for a status line rather than a log. */\nexport function describeOutage(o: BackendOutage, now = Date.now()): string {\n  const mins = Math.max(1, Math.round((now - o.since) / 60_000));\n  const forHow = mins < 60 ? `${mins} min` : `${(mins / 60).toFixed(1)} h`;\n  return `${o.backend} unreachable for ${forHow}, ${o.attempts} attempts — ${o.lastError}`;\n}\n","/**\n * Storage backend factory.\n *\n * Reads the daemon config and returns the appropriate StorageBackend.\n *\n * When Postgres is the configured backend we NEVER silently fall back to\n * SQLite — doing so would split the corpus across two databases. Instead:\n *  - Daemon (waitForPostgres: true) retries Postgres forever with capped\n *    backoff until it comes up (handles the boot race where launchd starts\n *    the daemon before Docker Desktop / Postgres is ready).\n *  - CLI / one-shot callers (default) retry a few times, then throw a clear\n *    error rather than returning a wrong/empty SQLite database.\n */\n\nimport type { PaiDaemonConfig } from \"../daemon/config.js\";\nimport type { StorageBackend } from \"./interface.js\";\nimport { setBackendOutage, clearBackendOutage } from \"./outage.js\";\n\nexport interface StorageBackendOptions {\n  /**\n   * When true, retry Postgres indefinitely instead of giving up. Used by the\n   * long-lived daemon so a not-yet-ready Postgres at boot is tolerated.\n   * Defaults to false (one-shot CLI behaviour: bounded retries, then throw).\n   */\n  waitForPostgres?: boolean;\n}\n\n/** Backoff schedule (ms) for the bounded CLI retry path. */\nconst CLI_RETRY_DELAYS_MS = [500, 1_000, 2_000];\n\n/** Backoff cap (ms) for the daemon's infinite retry path. */\nconst DAEMON_RETRY_CAP_MS = 15_000;\n\n/**\n * Create and return the configured StorageBackend.\n *\n * Auto-behaviour:\n *  - storageBackend = \"sqlite\"   → SQLiteBackend always\n *  - storageBackend = \"postgres\" → PostgresBackend (retried; never falls back)\n */\nexport async function createStorageBackend(\n  config: PaiDaemonConfig,\n  opts: StorageBackendOptions = {}\n): Promise<StorageBackend> {\n  if (config.storageBackend === \"postgres\") {\n    return await connectPostgres(config, opts.waitForPostgres ?? false);\n  }\n\n  // Default: SQLite\n  return createSQLiteBackend();\n}\n\n/**\n * Attempt a single Postgres connection (ensure DB + test). Returns the live\n * backend on success, or an error string describing why it failed.\n */\nasync function attemptPostgres(\n  config: PaiDaemonConfig\n): Promise<{ backend: StorageBackend } | { error: string }> {\n  const { PostgresBackend } = await import(\"./postgres.js\");\n  const pgConfig = config.postgres ?? {};\n\n  let backend: InstanceType<typeof PostgresBackend> | null = null;\n  try {\n    // Ensure the per-user database exists and has the schema applied.\n    await PostgresBackend.ensureDatabase(pgConfig);\n\n    backend = new PostgresBackend(pgConfig);\n    const err = await backend.testConnection();\n    if (err) {\n      await backend.close().catch(() => {});\n      return { error: err };\n    }\n    return { backend };\n  } catch (e) {\n    if (backend) await backend.close().catch(() => {});\n    return { error: e instanceof Error ? e.message : String(e) };\n  }\n}\n\n/**\n * Consecutive failures before the outage is escalated to the user.\n *\n * Not the first failure: a container restarting, or the daemon starting before\n * Docker is up, recovers within a few seconds and is not worth a notification.\n * By the fifth attempt the backoff has already spent tens of seconds, which is\n * long enough that something is actually wrong.\n */\nconst ESCALATE_AFTER_ATTEMPTS = 5;\n\n/** Tell the user the backend is down, through whatever channels are configured. */\nasync function notifyBackendDown(attempts: number, lastError: string): Promise<void> {\n  try {\n    const { routeNotification } = await import(\"../notifications/router.js\");\n    const { loadConfig } = await import(\"../daemon/config.js\");\n    await routeNotification(\n      {\n        event: \"error\",\n        title: \"PAI: storage backend unreachable\",\n        message:\n          `Postgres has not answered in ${attempts} attempts (${lastError}). ` +\n          `Indexing, session notes and the work queue are stalled until it returns. ` +\n          `Check the container, then \\`pai daemon status\\`.`,\n      },\n      loadConfig().notifications\n    );\n  } catch {\n    // A notification that cannot be sent must never take the daemon down with\n    // it — the daemon retrying is still the useful behaviour here.\n  }\n}\n\n/** And say when it comes back, so the alert is not left hanging. */\nasync function notifyBackendRecovered(\n  attempts: number,\n  since: number | null\n): Promise<void> {\n  try {\n    const { routeNotification } = await import(\"../notifications/router.js\");\n    const { loadConfig } = await import(\"../daemon/config.js\");\n    const mins = since ? Math.max(1, Math.round((Date.now() - since) / 60_000)) : null;\n    await routeNotification(\n      {\n        event: \"completion\",\n        title: \"PAI: storage backend back\",\n        message:\n          `Postgres answered after ${attempts} attempts` +\n          (mins ? `, ${mins} min down` : \"\") +\n          `. The queue will drain on its own.`,\n      },\n      loadConfig().notifications\n    );\n  } catch {\n    /* same reasoning as above */\n  }\n}\n\nasync function connectPostgres(\n  config: PaiDaemonConfig,\n  waitForever: boolean\n): Promise<StorageBackend> {\n  let attempt = 0;\n  let lastError = \"unknown error\";\n  let outageSince: number | null = null;\n  let escalated = false;\n\n  // eslint-disable-next-line no-constant-condition\n  while (true) {\n    attempt++;\n    const result = await attemptPostgres(config);\n    if (\"backend\" in result) {\n      if (attempt > 1) {\n        process.stderr.write(\n          `[pai-daemon] Connected to PostgreSQL backend (after ${attempt} attempts).\\n`\n        );\n      } else {\n        process.stderr.write(\"[pai-daemon] Connected to PostgreSQL backend.\\n\");\n      }\n      // An outage that ended must stop being reported, or the status command\n      // trades one wrong answer for another.\n      clearBackendOutage();\n      if (escalated) void notifyBackendRecovered(attempt, outageSince);\n      return result.backend;\n    }\n\n    lastError = result.error;\n\n    if (!waitForever && attempt > CLI_RETRY_DELAYS_MS.length) {\n      // Bounded CLI path exhausted — fail loudly, never silently use SQLite.\n      throw new Error(\n        `Postgres backend unreachable after ${attempt} attempts: ${lastError}. ` +\n          `Is Docker Desktop / Postgres running? Refusing to fall back to SQLite ` +\n          `(would split the corpus). Start Postgres and retry.`\n      );\n    }\n\n    const delayMs = waitForever\n      ? Math.min(DAEMON_RETRY_CAP_MS, 1_000 * 2 ** Math.min(attempt - 1, 4))\n      : CLI_RETRY_DELAYS_MS[attempt - 1];\n\n    process.stderr.write(\n      `[pai-daemon] Postgres unavailable (${lastError}). ` +\n        `Retry ${attempt}${waitForever ? \"\" : `/${CLI_RETRY_DELAYS_MS.length + 1}`} ` +\n        `in ${delayMs}ms...\\n`\n    );\n\n    // Publish the outage so `pai daemon status` can report it. Without this the\n    // daemon retries silently forever and status still reads \"idle\" — which is\n    // what happened for two days in July: 144 retries over 36 minutes, session\n    // notes never written, and the one command anyone would run to check\n    // reporting that everything was fine.\n    setBackendOutage({\n      backend: \"postgres\",\n      since: outageSince ?? (outageSince = Date.now()),\n      attempts: attempt,\n      lastError: String(lastError),\n    });\n\n    // And escalate once, out loud, rather than only into a log nobody tails.\n    // Once — not per retry — because a notification that repeats every few\n    // seconds is filtered within a minute and stops being a signal at all.\n    if (waitForever && attempt === ESCALATE_AFTER_ATTEMPTS && !escalated) {\n      escalated = true;\n      void notifyBackendDown(attempt, String(lastError));\n    }\n\n    await new Promise((r) => setTimeout(r, delayMs));\n  }\n}\n\nasync function createSQLiteBackend(): Promise<StorageBackend> {\n  const { openFederation } = await import(\"../memory/db.js\");\n  const { SQLiteBackend } = await import(\"./sqlite.js\");\n  const db = openFederation();\n  return new SQLiteBackend(db);\n}\n"],"mappings":"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"}