om-memory-system 3.2.0-next.11 → 3.2.0-next.12

package/dist/importer/opencode-project.js

@@ -1,38 +1,5 @@
-import { statSync } from "node:fs";
-function isDirectory(path) {
-    if (!path)
-        return false;
-    try {
-        return statSync(path).isDirectory();
-    }
-    catch {
-        return false;
-    }
-}
-/** Prefer the recorded directory, then an explicit map, then the project root. */
+import { resolveImportProject } from "./import-project.js";
+/** A directory map first, then the recorded directory, then the project root. */
 export function resolveOpencodeProject(recordedDirectory, projectWorktree, maps = []) {
-    if (isDirectory(recordedDirectory))
-        return recordedDirectory;
-    const mapped = maps.find((item) => item.from === recordedDirectory)?.to;
-    if (isDirectory(mapped))
-        return mapped;
-    return projectWorktree !== "/" && isDirectory(projectWorktree) ? projectWorktree : null;
-}
-/** Resolve each session without buffering its conversation windows. */
-export async function* resolveOpencodeSessions(sessions, maps, unresolved) {
-    for await (const session of sessions) {
-        const directory = resolveOpencodeProject(session.recordedDirectory, session.projectWorktree, maps);
-        if (directory) {
-            yield { ...session, directory };
-            continue;
-        }
-        const entry = unresolved.get(session.recordedDirectory) ?? {
-            directory: session.recordedDirectory,
-            sessions: 0,
-            units: 0,
-        };
-        entry.sessions++;
-        entry.units += session.units.length;
-        unresolved.set(entry.directory, entry);
-    }
+    return resolveImportProject(recordedDirectory, maps, projectWorktree).directory;
 }

package/dist/importer/opencode-reader.d.ts

@@ -1,19 +1,39 @@
-import type { ImportSourceSession } from "./importer.js";
-export interface OpencodeSourceSession extends ImportSourceSession {
+import type { ImportWindow } from "./importer.js";
+export declare const DEFAULT_OPENCODE_DB: string;
+/** One top-level session's metadata; its turns are built on demand. */
+export interface OpencodeSessionMeta {
+    sessionId: string;
     recordedDirectory: string;
     projectWorktree: string | null;
     timeCreated: number;
 }
-export interface OpencodeReader {
+export interface OpencodeHistory {
     childSessions: number;
     topLevelSessions: number;
-    sessions: AsyncIterable<OpencodeSourceSession>;
+    /** Top-level sessions matching the filters, oldest first. */
+    sessions: OpencodeSessionMeta[];
+    /** Build one session's work units; call only before `close`. */
+    loadUnits: (sessionId: string) => ImportWindow[];
+    close: () => Promise<void>;
 }
 export interface OpencodeReaderFilters {
     session?: string;
+    /** Web selection; never combined with `session` or `maxSessions`. */
+    sessionIds?: string[];
     maxSessions?: number;
     since?: number;
     until?: number;
 }
+export interface OpencodeOpenOptions {
+    /**
+     * Share the snapshot with the web listing and jobs under this source key.
+     * `fresh` copies again, `reuse` fails when no copy exists, `any` does either.
+     */
+    shared?: {
+        key: string;
+        mode: "fresh" | "reuse" | "any";
+    };
+    signal?: AbortSignal;
+}
 /** Read V1 OpenCode history without changing its database or WAL sidecars. */
-export declare function readOpencodeHistory(dbPath: string, filters?: OpencodeReaderFilters): OpencodeReader;
+export declare function openOpencodeHistory(dbPath: string, filters?: OpencodeReaderFilters, options?: OpencodeOpenOptions): Promise<OpencodeHistory>;

package/dist/importer/opencode-reader.js

@@ -1,11 +1,11 @@
-import { constants, copyFileSync, existsSync, mkdtempSync, rmSync, statSync } from "node:fs";
-import { tmpdir } from "node:os";
+import { existsSync, statSync } from "node:fs";
+import { homedir } from "node:os";
 import { join } from "node:path";
 import { pathToFileURL } from "node:url";
 import { DatabaseSync } from "node:sqlite";
 import { INTERNAL_CAPTURE_SESSION_TITLES } from "../services/ai/internal-capture-sessions.js";
-import { log } from "../services/logger.js";
-import { withSqliteFileLockRetry } from "../services/turso/sqlite-handle-release.js";
+import { acquirePrivateSnapshot, opencodeSnapshots, OpencodeSnapshotError, } from "./opencode-snapshot.js";
+export const DEFAULT_OPENCODE_DB = join(homedir(), ".local/share/opencode/opencode.db");
 function validateSchema(db) {
     const required = {
         session: ["id", "directory", "project_id", "parent_id", "time_created"],
@@ -113,121 +113,107 @@ function fileStamp(path) {
     const info = statSync(path, { bigint: true });
     return `${info.size}:${info.mtimeNs}`;
 }
-/**
- * Copy the database and its WAL into a private folder. `immutable=1` ignores
- * the WAL, and a normal open writes to OpenCode's `-shm`, so a copy is the only
- * way to see uncheckpointed turns while leaving every source file untouched.
- * A copy that raced a write or checkpoint is discarded and retried.
- */
-/**
- * Remove a snapshot folder without ever failing the import. Windows can hold
- * SQLite files briefly after close, so retry lock errors; if the lock
- * outlasts the retries, log the leftover path instead of throwing.
- */
-async function removeSnapshotDir(dir) {
-    try {
-        await withSqliteFileLockRetry(() => rmSync(dir, { recursive: true, force: true }));
-    }
-    catch (error) {
-        log("OpenCode import: could not remove the temporary database copy", {
-            dir,
-            error: String(error),
-        });
-    }
-}
-function snapshotWalDatabase(dbPath) {
-    const dir = mkdtempSync(join(tmpdir(), "omms-opencode-"));
-    const cleanup = () => removeSnapshotDir(dir);
-    const copy = join(dir, "opencode.db");
+async function openSnapshot(dbPath, options) {
+    const lease = options.shared
+        ? await opencodeSnapshots.acquire(options.shared.key, dbPath, options.shared.mode, options.signal)
+        : await acquirePrivateSnapshot(dbPath, options.signal);
     try {
-        for (let attempt = 0; attempt < 5; attempt++) {
-            const before = [fileStamp(dbPath), fileStamp(`${dbPath}-wal`)];
-            // Clone where the file system supports it (APFS, Btrfs): large databases copy instantly.
-            copyFileSync(dbPath, copy, constants.COPYFILE_FICLONE);
-            copyFileSync(`${dbPath}-wal`, `${copy}-wal`, constants.COPYFILE_FICLONE);
-            const after = [fileStamp(dbPath), fileStamp(`${dbPath}-wal`)];
-            if (before[0] === after[0] && before[1] === after[1])
-                return { path: copy, cleanup };
-        }
+        return { db: new DatabaseSync(lease.path), lease };
     }
     catch (error) {
-        void cleanup();
+        await lease.release();
         throw error;
     }
-    void cleanup();
-    throw new Error("OpenCode database kept changing while it was copied; retry the import");
 }
-function openSnapshot(dbPath) {
-    if (!existsSync(`${dbPath}-wal`)) {
-        // No WAL: every committed page is in the main file, so read it in place.
-        const uri = `${pathToFileURL(dbPath).href}?immutable=1`;
-        return { db: new DatabaseSync(uri, { readOnly: true }), cleanup: async () => { } };
-    }
-    const snapshot = snapshotWalDatabase(dbPath);
-    try {
-        return { db: new DatabaseSync(snapshot.path), cleanup: snapshot.cleanup };
-    }
-    catch (error) {
-        void snapshot.cleanup();
-        throw error;
+/**
+ * Without a WAL every committed page is in the main file, so read it in place
+ * with `immutable=1`. A rollback journal means a writer is mid-transaction,
+ * which an immutable read could see half-done.
+ */
+async function openSource(dbPath, options) {
+    if (existsSync(`${dbPath}-wal`))
+        return openSnapshot(dbPath, options);
+    if (existsSync(`${dbPath}-journal`)) {
+        throw new OpencodeSnapshotError("busy", "The OpenCode database is being written. Retry in a moment, or choose a backup.");
     }
+    const stamp = fileStamp(dbPath);
+    const uri = `${pathToFileURL(dbPath).href}?immutable=1`;
+    return { db: new DatabaseSync(uri, { readOnly: true }), stamp };
+}
+/** True when an in-place read may have raced a writer that started meanwhile. */
+function changedSinceOpen(dbPath, source) {
+    if (source.stamp === undefined)
+        return false;
+    return existsSync(`${dbPath}-wal`) || fileStamp(dbPath) !== source.stamp;
+}
+function readSessions(db, filters) {
+    validateSchema(db);
+    // omms's own capture/profile calls run in OpenCode sessions; never import them as history.
+    const hasTitle = db.prepare("PRAGMA table_info(session)").all().some((column) => column.name === "title");
+    const notInternal = hasTitle
+        ? `AND (s.title IS NULL OR s.title NOT IN (${INTERNAL_CAPTURE_SESSION_TITLES.map(() => "?").join(", ")}))`
+        : "";
+    const internalArgs = hasTitle ? [...INTERNAL_CAPTURE_SESSION_TITLES] : [];
+    const count = (where) => Number(db
+        .prepare(`SELECT COUNT(*) AS count FROM session s WHERE ${where} ${notInternal}`)
+        .get(...internalArgs).count);
+    const query = `SELECT s.id, s.directory, p.worktree AS project_worktree, s.time_created
+    FROM session s LEFT JOIN project p ON p.id = s.project_id
+    WHERE s.parent_id IS NULL ${notInternal} ${filters.session ? "AND s.id = ?" : ""}
+    ${filters.sessionIds ? "AND s.id IN (SELECT value FROM json_each(?))" : ""}
+    ORDER BY s.time_created, s.id ${filters.maxSessions ? "LIMIT ?" : ""}`;
+    const args = [...internalArgs];
+    if (filters.session)
+        args.push(filters.session);
+    if (filters.sessionIds)
+        args.push(JSON.stringify(filters.sessionIds));
+    if (filters.maxSessions)
+        args.push(filters.maxSessions);
+    const sessions = db.prepare(query).all(...args).map((row) => ({
+        sessionId: row.id,
+        recordedDirectory: row.directory,
+        projectWorktree: row.project_worktree,
+        timeCreated: Number(row.time_created),
+    }));
+    return {
+        childSessions: count("s.parent_id IS NOT NULL"),
+        topLevelSessions: count("s.parent_id IS NULL"),
+        sessions,
+    };
 }
 /** Read V1 OpenCode history without changing its database or WAL sidecars. */
-export function readOpencodeHistory(dbPath, filters = {}) {
+export async function openOpencodeHistory(dbPath, filters = {}, options = {}) {
     if (!existsSync(dbPath))
-        throw new Error(`OpenCode database not found: ${dbPath}`);
-    const { db, cleanup } = openSnapshot(dbPath);
-    const close = async () => {
-        db.close();
-        await cleanup();
-    };
+        throw new Error("OpenCode database not found");
+    let source = await openSource(dbPath, options);
+    let listed;
     try {
-        validateSchema(db);
-        // omms's own capture/profile calls run in OpenCode sessions; never import them as history.
-        const hasTitle = db.prepare("PRAGMA table_info(session)").all().some((column) => column.name === "title");
-        const notInternal = hasTitle
-            ? `AND (s.title IS NULL OR s.title NOT IN (${INTERNAL_CAPTURE_SESSION_TITLES.map(() => "?").join(", ")}))`
-            : "";
-        const internalArgs = hasTitle ? [...INTERNAL_CAPTURE_SESSION_TITLES] : [];
-        const count = (where) => Number(db
-            .prepare(`SELECT COUNT(*) AS count FROM session s WHERE ${where} ${notInternal}`)
-            .get(...internalArgs).count);
-        const childSessions = count("s.parent_id IS NOT NULL");
-        const topLevelSessions = count("s.parent_id IS NULL");
-        const sessions = {
-            async *[Symbol.asyncIterator]() {
-                try {
-                    const query = `SELECT s.id, s.directory, p.worktree AS project_worktree, s.time_created
-            FROM session s LEFT JOIN project p ON p.id = s.project_id
-            WHERE s.parent_id IS NULL ${notInternal} ${filters.session ? "AND s.id = ?" : ""}
-            ORDER BY s.time_created, s.id ${filters.maxSessions ? "LIMIT ?" : ""}`;
-                    const args = [...internalArgs];
-                    if (filters.session)
-                        args.push(filters.session);
-                    if (filters.maxSessions)
-                        args.push(filters.maxSessions);
-                    for (const row of db.prepare(query).all(...args)) {
-                        yield {
-                            sessionId: row.id,
-                            recordedDirectory: row.directory,
-                            directory: row.directory,
-                            sourceFile: dbPath,
-                            projectWorktree: row.project_worktree,
-                            timeCreated: row.time_created,
-                            units: buildWindows(db, row.id, filters),
-                        };
-                    }
-                }
-                finally {
-                    await close();
-                }
-            },
-        };
-        return { childSessions, topLevelSessions, sessions };
+        listed = readSessions(source.db, filters);
+        if (changedSinceOpen(dbPath, source)) {
+            // OpenCode started writing during the in-place read: read a private copy instead.
+            source.db.close();
+            source = undefined;
+            source = await openSnapshot(dbPath, options);
+            listed = readSessions(source.db, filters);
+        }
     }
     catch (error) {
-        // Cleanup never throws, so the original error is what the caller sees.
-        void close();
+        // Close only what is still open, so the original error is what the caller sees.
+        source?.db.close();
+        await source?.lease?.release();
         throw error;
     }
+    const opened = source;
+    let closed = false;
+    return {
+        ...listed,
+        loadUnits: (sessionId) => buildWindows(opened.db, sessionId, filters),
+        close: async () => {
+            if (closed)
+                return;
+            closed = true;
+            opened.db.close();
+            await opened.lease?.release();
+        },
+    };
 }

package/dist/importer/opencode-snapshot.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Private copies of a live OpenCode database. A normal SQLite open writes to
+ * OpenCode's `-shm`, and `immutable=1` ignores the WAL, so a copy of the
+ * database and its WAL is the only way to read uncheckpointed turns while
+ * leaving every source file untouched.
+ *
+ * Copies run asynchronously so the OpenCode process that hosts the web UI and
+ * live capture keeps responding, and they can be cancelled. One copy per
+ * source is shared by the web listing, preview, and import.
+ */
+export declare const SNAPSHOT_PREFIX = "omms-opencode-";
+export declare const SNAPSHOT_IDLE_MS: number;
+/** Sources above this size, or on another device, get one copy attempt instead of five. */
+export declare const SINGLE_ATTEMPT_BYTES: number;
+export type SnapshotErrorCode = "no-space" | "changing" | "busy" | "expired";
+export declare class OpencodeSnapshotError extends Error {
+    readonly code: SnapshotErrorCode;
+    constructor(code: SnapshotErrorCode, message: string);
+}
+export interface SnapshotLease {
+    /** Path of the private database copy. */
+    path: string;
+    release: () => Promise<void>;
+}
+/** Bytes a snapshot of `dbPath` needs in the temporary folder, margin included. */
+export declare function snapshotSpaceNeeded(dbPath: string): number;
+export declare function checkSnapshotSpace(dbPath: string, folder?: string, available?: number): void;
+/**
+ * Remove a snapshot folder without ever failing the import. Windows can hold
+ * SQLite files briefly after close, so retry lock errors; if the lock
+ * outlasts the retries, log the leftover path instead of throwing.
+ */
+export declare function removeSnapshotDir(dir: string): Promise<void>;
+/**
+ * Delete snapshot folders left by processes that no longer run, such as an
+ * OpenCode window that quit mid-import. A folder whose owner is alive, or
+ * whose owner file is unreadable because it is still being created, is kept.
+ */
+export declare function sweepOrphanSnapshots(folder?: string): Promise<number>;
+/**
+ * Copy `dbPath` and its WAL into a private folder. A copy that raced a write
+ * or checkpoint is discarded and retried, but only once for large or
+ * cross-device sources, where each attempt can take minutes.
+ */
+export declare function createOpencodeSnapshot(dbPath: string, options?: {
+    signal?: AbortSignal;
+    folder?: string;
+    clone?: boolean;
+}): Promise<{
+    dir: string;
+    path: string;
+}>;
+/**
+ * Snapshots shared by source key (real path, device, inode). A fresh request
+ * replaces the current copy for later callers; a job still reading the old
+ * copy keeps it until it releases it.
+ */
+export declare class OpencodeSnapshotRegistry {
+    private readonly idleMs;
+    private readonly create;
+    private readonly current;
+    private readonly pending;
+    private readonly all;
+    constructor(idleMs?: number, create?: typeof createOpencodeSnapshot);
+    /**
+     * `fresh` makes a new copy (a listing refresh); `reuse` only returns an
+     * existing copy and fails as expired when there is none (a job).
+     */
+    acquire(key: string, dbPath: string, mode: "fresh" | "reuse" | "any", signal?: AbortSignal): Promise<SnapshotLease>;
+    private retire;
+    private remove;
+    /**
+     * Drop the current copy for a source after a real import: a later listing
+     * copies afresh. A job still reading it keeps it until it releases it.
+     */
+    discard(key: string): void;
+    /** Remove every copy, for server shutdown. */
+    closeAll(): Promise<void>;
+}
+export declare const opencodeSnapshots: OpencodeSnapshotRegistry;
+/** An unshared snapshot for one CLI or slash-command run. */
+export declare function acquirePrivateSnapshot(dbPath: string, signal?: AbortSignal): Promise<SnapshotLease>;

package/dist/importer/opencode-snapshot.js

@@ -0,0 +1,276 @@
+import { constants, createReadStream, createWriteStream, mkdtempSync, readdirSync, readFileSync, rmSync, statfsSync, statSync, writeFileSync, } from "node:fs";
+import { copyFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { pipeline } from "node:stream/promises";
+import { log } from "../services/logger.js";
+import { withSqliteFileLockRetry } from "../services/turso/sqlite-handle-release.js";
+/**
+ * Private copies of a live OpenCode database. A normal SQLite open writes to
+ * OpenCode's `-shm`, and `immutable=1` ignores the WAL, so a copy of the
+ * database and its WAL is the only way to read uncheckpointed turns while
+ * leaving every source file untouched.
+ *
+ * Copies run asynchronously so the OpenCode process that hosts the web UI and
+ * live capture keeps responding, and they can be cancelled. One copy per
+ * source is shared by the web listing, preview, and import.
+ */
+export const SNAPSHOT_PREFIX = "omms-opencode-";
+export const SNAPSHOT_IDLE_MS = 30 * 60 * 1000;
+/** Sources above this size, or on another device, get one copy attempt instead of five. */
+export const SINGLE_ATTEMPT_BYTES = 1024 ** 3;
+const MIN_MARGIN_BYTES = 256 * 1024 ** 2;
+const OWNER_FILE = "owner.json";
+export class OpencodeSnapshotError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "OpencodeSnapshotError";
+    }
+}
+function formatBytes(bytes) {
+    if (bytes >= 1024 ** 3)
+        return `${(bytes / 1024 ** 3).toFixed(1)} GB`;
+    return `${Math.ceil(bytes / 1024 ** 2)} MB`;
+}
+function fileStamp(path) {
+    const info = statSync(path, { bigint: true });
+    return `${info.size}:${info.mtimeNs}`;
+}
+function fileSize(path) {
+    try {
+        return statSync(path).size;
+    }
+    catch {
+        return 0;
+    }
+}
+/** Bytes a snapshot of `dbPath` needs in the temporary folder, margin included. */
+export function snapshotSpaceNeeded(dbPath) {
+    const total = fileSize(dbPath) + fileSize(`${dbPath}-wal`);
+    return total + Math.max(MIN_MARGIN_BYTES, Math.ceil(total * 0.1));
+}
+export function checkSnapshotSpace(dbPath, folder = tmpdir(), available = (() => {
+    const info = statfsSync(folder);
+    return Number(info.bavail) * Number(info.bsize);
+})()) {
+    const needed = snapshotSpaceNeeded(dbPath);
+    if (available < needed) {
+        throw new OpencodeSnapshotError("no-space", `Not enough temporary space to copy the OpenCode database: needs ${formatBytes(needed)}, ` +
+            `${formatBytes(available)} free in ${folder}. Free space there or choose a checkpointed backup.`);
+    }
+}
+/**
+ * Remove a snapshot folder without ever failing the import. Windows can hold
+ * SQLite files briefly after close, so retry lock errors; if the lock
+ * outlasts the retries, log the leftover path instead of throwing.
+ */
+export async function removeSnapshotDir(dir) {
+    try {
+        await withSqliteFileLockRetry(() => rmSync(dir, { recursive: true, force: true }));
+    }
+    catch (error) {
+        log("OpenCode import: could not remove the temporary database copy", {
+            dir,
+            code: error.code ?? "error",
+        });
+    }
+}
+function processAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        // EPERM: the process exists but belongs to someone else.
+        return error.code === "EPERM";
+    }
+}
+/**
+ * Delete snapshot folders left by processes that no longer run, such as an
+ * OpenCode window that quit mid-import. A folder whose owner is alive, or
+ * whose owner file is unreadable because it is still being created, is kept.
+ */
+export async function sweepOrphanSnapshots(folder = tmpdir()) {
+    let removed = 0;
+    let entries;
+    try {
+        entries = readdirSync(folder).filter((name) => name.startsWith(SNAPSHOT_PREFIX));
+    }
+    catch {
+        return 0;
+    }
+    for (const name of entries) {
+        const dir = join(folder, name);
+        let owner;
+        try {
+            owner = JSON.parse(readFileSync(join(dir, OWNER_FILE), "utf8"));
+        }
+        catch {
+            continue;
+        }
+        if (typeof owner.pid !== "number" || processAlive(owner.pid))
+            continue;
+        await removeSnapshotDir(dir);
+        removed++;
+    }
+    return removed;
+}
+async function copyOne(source, target, signal, clone = true) {
+    signal?.throwIfAborted();
+    if (clone) {
+        try {
+            // A copy-on-write clone (APFS, Btrfs) is instant and runs off the event loop.
+            await copyFile(source, target, constants.COPYFILE_FICLONE_FORCE);
+            return;
+        }
+        catch {
+            // No clone support here, or another device: stream the bytes instead.
+        }
+    }
+    await pipeline(createReadStream(source), createWriteStream(target), { signal });
+}
+/**
+ * Copy `dbPath` and its WAL into a private folder. A copy that raced a write
+ * or checkpoint is discarded and retried, but only once for large or
+ * cross-device sources, where each attempt can take minutes.
+ */
+export async function createOpencodeSnapshot(dbPath, options = {}) {
+    const folder = options.folder ?? tmpdir();
+    await sweepOrphanSnapshots(folder);
+    checkSnapshotSpace(dbPath, folder);
+    const wal = `${dbPath}-wal`;
+    const total = fileSize(dbPath) + fileSize(wal);
+    let sameDevice = false;
+    try {
+        sameDevice = statSync(folder).dev === statSync(dbPath).dev;
+    }
+    catch {
+        // Unknown device: treat it as another one.
+    }
+    const attempts = sameDevice && total <= SINGLE_ATTEMPT_BYTES ? 5 : 1;
+    const dir = mkdtempSync(join(folder, SNAPSHOT_PREFIX));
+    writeFileSync(join(dir, OWNER_FILE), JSON.stringify({ pid: process.pid, createdAt: Date.now() }));
+    const copy = join(dir, "opencode.db");
+    try {
+        for (let attempt = 0; attempt < attempts; attempt++) {
+            const before = [fileStamp(dbPath), fileStamp(wal)];
+            await copyOne(dbPath, copy, options.signal, options.clone);
+            await copyOne(wal, `${copy}-wal`, options.signal, options.clone);
+            const after = [fileStamp(dbPath), fileStamp(wal)];
+            if (before[0] === after[0] && before[1] === after[1])
+                return { dir, path: copy };
+        }
+    }
+    catch (error) {
+        await removeSnapshotDir(dir);
+        throw error;
+    }
+    await removeSnapshotDir(dir);
+    throw new OpencodeSnapshotError("changing", attempts === 1
+        ? "The OpenCode database changed while it was copied. Quit OpenCode, or choose a checkpointed backup, and retry."
+        : "OpenCode database kept changing while it was copied; retry the import");
+}
+/**
+ * Snapshots shared by source key (real path, device, inode). A fresh request
+ * replaces the current copy for later callers; a job still reading the old
+ * copy keeps it until it releases it.
+ */
+export class OpencodeSnapshotRegistry {
+    idleMs;
+    create;
+    current = new Map();
+    pending = new Map();
+    all = new Set();
+    constructor(idleMs = SNAPSHOT_IDLE_MS, create = createOpencodeSnapshot) {
+        this.idleMs = idleMs;
+        this.create = create;
+    }
+    /**
+     * `fresh` makes a new copy (a listing refresh); `reuse` only returns an
+     * existing copy and fails as expired when there is none (a job).
+     */
+    async acquire(key, dbPath, mode, signal) {
+        let shared = mode === "fresh" ? undefined : this.current.get(key);
+        if (!shared) {
+            if (mode === "reuse") {
+                throw new OpencodeSnapshotError("expired", "The session list is out of date. Refresh the list and try again.");
+            }
+            let creating = mode === "fresh" ? undefined : this.pending.get(key);
+            if (!creating) {
+                creating = this.create(dbPath, { signal }).then((copy) => {
+                    const next = { ...copy, refs: 0, retired: false };
+                    const previous = this.current.get(key);
+                    if (previous)
+                        this.retire(previous);
+                    this.current.set(key, next);
+                    this.all.add(next);
+                    return next;
+                });
+                this.pending.set(key, creating);
+                creating.then(() => this.pending.delete(key), () => this.pending.delete(key));
+            }
+            shared = await creating;
+        }
+        const lease = shared;
+        lease.refs++;
+        if (lease.timer)
+            clearTimeout(lease.timer);
+        lease.timer = undefined;
+        let released = false;
+        return {
+            path: lease.path,
+            release: async () => {
+                if (released)
+                    return;
+                released = true;
+                lease.refs--;
+                if (lease.refs > 0)
+                    return;
+                if (lease.retired)
+                    return this.remove(lease);
+                lease.timer = setTimeout(() => {
+                    if (this.current.get(key) === lease)
+                        this.current.delete(key);
+                    void this.remove(lease);
+                }, this.idleMs);
+                lease.timer.unref?.();
+            },
+        };
+    }
+    retire(shared) {
+        shared.retired = true;
+        if (shared.refs === 0)
+            void this.remove(shared);
+    }
+    async remove(shared) {
+        if (shared.timer)
+            clearTimeout(shared.timer);
+        if (!this.all.delete(shared))
+            return;
+        await removeSnapshotDir(shared.dir);
+    }
+    /**
+     * Drop the current copy for a source after a real import: a later listing
+     * copies afresh. A job still reading it keeps it until it releases it.
+     */
+    discard(key) {
+        const shared = this.current.get(key);
+        if (!shared)
+            return;
+        this.current.delete(key);
+        this.retire(shared);
+    }
+    /** Remove every copy, for server shutdown. */
+    async closeAll() {
+        this.current.clear();
+        await Promise.all([...this.all].map((shared) => this.remove(shared)));
+    }
+}
+export const opencodeSnapshots = new OpencodeSnapshotRegistry();
+/** An unshared snapshot for one CLI or slash-command run. */
+export async function acquirePrivateSnapshot(dbPath, signal) {
+    const copy = await createOpencodeSnapshot(dbPath, { signal });
+    return { path: copy.path, release: () => removeSnapshotDir(copy.dir) };
+}