@timqi/pier 0.0.1 → 0.0.3

package/dist/core/inbox.js

@@ -0,0 +1,32 @@
+// Inbound user files: bytes land on disk exactly once.
+//
+// A photo pasted on the web, dropped in Telegram or uploaded to Slack used to
+// travel as base64 through the seam into the transcript, where it was re-sent
+// with every provider request until compaction. Now the adapter (or the web
+// upload route) saves the bytes under `$PIER_HOME/inbox/<channel>/` and the
+// prompt carries only a marker line (core/inbound-file.ts owns that grammar),
+// so the agent reads a file only when it decides the file is worth looking at.
+import { mkdir, writeFile } from "node:fs/promises";
+import { randomBytes } from "node:crypto";
+import { basename, join } from "node:path";
+import { pierPath } from "../paths.js";
+import { safeName } from "./inbound-file.js";
+/** Where every inbound file lives; web/files.ts allowlists this root. */
+export const INBOX_DIR = pierPath("inbox");
+/**
+ * Write one inbound file and return its absolute path. The timestamp-random
+ * prefix keeps concurrent saves collision-free (`wx` turns the impossible
+ * collision into an error instead of an overwrite) and makes `ls` read as a
+ * timeline. Owner-only modes: uploads are private conversation content on a
+ * possibly shared machine. Nothing is ever deleted here — pruning the inbox
+ * is the operator's call (docs/deploy.md).
+ */
+export async function saveInbound(channelId, name, mimeType, bytes) {
+    // The channel id is ours ("web" | "telegram" | "slack"), not user input,
+    // but basename() keeps a future id honest.
+    const dir = join(INBOX_DIR, basename(channelId));
+    await mkdir(dir, { recursive: true, mode: 0o700 });
+    const path = join(dir, `${String(Date.now())}-${randomBytes(3).toString("hex")}-${safeName(name, mimeType)}`);
+    await writeFile(path, bytes, { mode: 0o600, flag: "wx" });
+    return path;
+}

package/dist/core/queue.js

@@ -1,11 +1,17 @@
 // The whole queue policy. Fixed by docs/architecture.md — do not add options.
 export function decide(msg, state) {
+    // An explicit mode takes the text verbatim: IM sends steer for every
+    // message, so a leading "!" there is content, not a control prefix —
+    // consuming it silently rewrote what the person typed.
+    if (msg.mode === "steer" || msg.mode === "followUp") {
+        return { action: state === "idle" ? "prompt" : msg.mode, text: msg.text };
+    }
+    // On auto the "!" is a control prefix and always consumed — whether the
+    // turn happened to end first must not decide if it was content. Idle just
+    // means there is nothing to steer, so it degenerates to a prompt.
     const steerPrefixed = msg.text.startsWith("!");
     const text = steerPrefixed ? msg.text.slice(1).trimStart() : msg.text;
     if (state === "idle")
         return { action: "prompt", text };
-    if (msg.mode === "steer" || msg.mode === "followUp") {
-        return { action: msg.mode, text };
-    }
     return { action: steerPrefixed ? "steer" : "followUp", text };
 }

package/dist/core/reply.js

@@ -13,7 +13,7 @@
  * into the factory). Both halves of the feature live in this file: the syntax
  * the agent is told to emit, and the parser that reads it back.
  */
-export const REPLY_SURFACE_PROMPT = `## Pier chat surface
+const REPLY_SURFACE_PROMPT = `## Pier chat surface
 
 Your replies render in a chat UI (web and IM). Three optional markdown
 conventions:
@@ -25,15 +25,19 @@ conventions:
 - **Attachments** — link a file you produced by absolute \`file://\` URL:
   \`[report.md](file:///abs/path/report.md)\`. Images render as thumbnails,
   other files as a download card; only files inside the session's working
-  directory are readable.
+  directory or Pier's inbox are readable. The same convention runs inbound: a
+  user message ending in \`[name](file:///…)\` lines is carrying files the
+  sender attached, already saved to disk — read one only when it matters to
+  the task; every read puts its content in your context for good.
 - **Staying silent** — \`<silent>why</silent>\` is stripped, and if nothing else
   remains no message is sent. In a group chat you are handed every message,
   including humans talking to each other: stay silent rather than acknowledge
   what was not addressed to you.
 
 A message may start with \`[name<id> time]\` — the sender, added by Pier, not
-typed by them. It appears only when the speaker or the day changes, so the last
-one still applies. Use that \`id\` to mention someone; never ask for their own.
+typed by them. It appears only on a change — new speaker, a ~10-minute gap, a
+new day — so the last one still applies; a gap alone shows as time only, like
+\`[14:23]\`. Use that \`id\` to mention someone; never ask for their own.
 `;
 /**
  * The contract above plus the two facts about *this* deployment that an agent
@@ -124,6 +128,17 @@ export function cjkFriendly(markdown) {
     });
     return out.replace(/\uE010(\d+)\uE011/g, (_m, i) => stash[Number(i)] ?? "");
 }
+/**
+ * The one wording for a turn that said nothing, wherever it is shown — the
+ * chat surfaces and the task result path. The reason arrives pre-escaped
+ * because each surface escapes for its own markup; the label itself contains
+ * nothing any of them escape.
+ */
+export const quietLabel = (silence) => silence ? `stayed silent — ${silence}` : "no reply";
+/** One policy for "did this turn actually reply": options count as a reply —
+ *  the buttons are the answer, so a turn that is only its options is not
+ *  "nothing". Every surface decides through here. */
+export const isSilentReply = (reply) => !reply.text.trim() && reply.suggestions.length === 0;
 /** How a reasoning level is spelled wherever a human reads it. */
 export const thinkingLabel = (level) => level === "xhigh" ? "Extra high" : level[0].toUpperCase() + level.slice(1);
 /** 1200 → "1.2K", 12_000 → "12K" — absolute token counts read badly inline. */
@@ -159,7 +174,6 @@ export const formatTurnMeta = (meta) => `${formatDuration(meta.durationMs)} · $
 const BLOCK = /(?:^|\n)[ \t]*-{3,}[ \t]*\r?\n((?:[ \t]*\[[^\]\r\n]+\][ \t]*(?:[|｜][ \t]*)?)+)\s*$/;
 const TOKEN = /\[([^\]\r\n]+)\]/g;
 const MAX_SUGGESTIONS = 5;
-/** Split an assistant turn's markdown into renderable text + next-step labels. */
 /**
  * A deliberate non-answer. In a group thread the agent is handed every message,
  * and most of them are two humans talking; a bot that replies to each one is
@@ -183,6 +197,7 @@ export function silentReason(markdown) {
         .filter(Boolean);
     return reasons.length ? reasons.join(" · ") : undefined;
 }
+/** Split an assistant turn's markdown into renderable text + next-step labels. */
 export function splitReply(rawMarkdown, meta) {
     // Every surface that renders this goes through here, and every CommonMark
     // parser has some version of the CJK emphasis hole — so the repair belongs

package/dist/core/router.js

@@ -1,11 +1,17 @@
-// Conversation → session routing plus event wiring. In-memory for v1;
-// persistence arrives with task storage (docs/plans/bootstrap.md step 4).
+// Conversation → session routing plus event wiring. In-memory on purpose:
+// the durable chat → session map lives in channels/conversations.ts.
 import { logger } from "../log.js";
 import { EventHub } from "./hub.js";
 import { SenderPrefix, withPrefix } from "./identity.js";
 import { decide } from "./queue.js";
 import { splitReply } from "./reply.js";
 const log = logger("core");
+/** How long a session may sit idle in memory before it is let go. Generous on
+ *  purpose: eviction is a memory measure, and re-opening one costs a Pi
+ *  resume plus the transcript being read back. */
+const IDLE_TTL_MS = 30 * 60_000;
+/** Sweep interval. Nothing here is urgent, so it is coarse. */
+const SWEEP_MS = 5 * 60_000;
 /** An error goes into a chat window, so it is trimmed to something readable. */
 const truncate = (message) => message.length > 600 ? `${message.slice(0, 600)}…` : message;
 function keyOf(key) {
@@ -16,9 +22,17 @@ export class Router {
     resolve;
     byKey = new Map();
     bySession = new Map();
+    /** Resolves in flight, so two surfaces asking at once share one session
+     *  object instead of opening a second Pi runtime on the same transcript.
+     *  Web and task keys collapse to the session id they both name. */
+    opening = new Map();
     channels = new Map();
     /** Who each session last heard from, so a header costs tokens only on news. */
     senders = new SenderPrefix();
+    /** Set by a graceful restart (src/drain.ts). Usually never unset, because
+     *  the process exits when the drain ends — `endDrain` exists for the one
+     *  caller that drains *speculatively* and may not get to exit. */
+    draining = false;
     constructor(hub, 
     /** Create or resume the session owning a conversation (wired in main.ts). */
     resolve) {
@@ -55,6 +69,67 @@ export class Router {
             });
         });
     }
+    /**
+     * Report something that happened *to* a session rather than in it: a task
+     * result that could not be delivered, say. Its conversation is told when one
+     * is attached — an agent that was promised an answer and a human watching the
+     * same thread learn it is not coming from the same place they were waiting.
+     * Otherwise the hub carries it for the web timeline.
+     */
+    reportTo(sessionId, message) {
+        const key = this.conversationOf(sessionId);
+        if (key)
+            this.report(sessionId, key, message);
+        else
+            this.hub.emit(sessionId, { type: "error", message });
+    }
+    /**
+     * Let go of every session that has been idle too long, so a process serving
+     * IM threads and task runs for weeks does not hold one live Pi runtime per
+     * conversation it ever saw. Only the in-memory attachment goes: the durable
+     * conversation → session mapping stays, so the next message resumes the very
+     * same transcript (channels/conversations.ts).
+     *
+     * Skipped for anything that would notice: a streaming turn, and a session
+     * someone is still watching over SSE.
+     *
+     * `includeWatched` is the one caller that may take a watched session too:
+     * configuration a session reads only when it opens has just changed, and the
+     * session most likely to need it is the one open in the tab that changed it.
+     * A turn in flight is still never touched — the exemption that stands is the
+     * one about interrupting work, not the one about being looked at.
+     */
+    async evictIdle(ttlMs = IDLE_TTL_MS, now = Date.now(), { includeWatched = false } = {}) {
+        let evicted = 0;
+        for (const [id, attached] of [...this.bySession]) {
+            if (attached.session.state === "streaming")
+                continue;
+            if (!includeWatched && this.hub.hasSubscribers(id))
+                continue;
+            if (now - attached.activeAt < ttlMs)
+                continue;
+            this.bySession.delete(id);
+            this.forgetKeys(attached.session);
+            attached.unsubscribe();
+            this.senders.forget(id);
+            this.hub.dropReplay(id);
+            evicted += 1;
+            log.info(`evicted idle session ${id} (${keyOf(attached.key)})`);
+            // Best-effort: a runtime that will not shut down must not keep the
+            // sweeper from releasing the rest.
+            await attached.session.dispose().catch((err) => log.error(`disposing session ${id} failed`, err));
+        }
+        return evicted;
+    }
+    /** Run evictIdle on a timer. Returns the stop function (main.ts owns it). */
+    startIdleEviction() {
+        // Unref'd: a sweep pending is never a reason for the process to stay up.
+        const timer = setInterval(() => {
+            void this.evictIdle().catch((err) => log.error("idle sweep failed", err));
+        }, SWEEP_MS);
+        timer.unref();
+        return () => clearInterval(timer);
+    }
     stateOf(sessionId) {
         return this.bySession.get(sessionId)?.session.state;
     }
@@ -74,21 +149,43 @@ export class Router {
     conversationOf(sessionId) {
         return this.bySession.get(sessionId)?.key;
     }
+    /** Every key that points at this session object. One session can be reached
+     *  under more than one — `web:<id>` and `task:<id>` name the same session —
+     *  and a key left behind hands out a session that is no longer live. */
+    forgetKeys(session) {
+        for (const [key, held] of this.byKey)
+            if (held === session)
+                this.byKey.delete(key);
+    }
     /** Attach an existing session to a conversation and wire its events. */
     attach(key, session) {
-        this.byKey.set(keyOf(key), session);
         const existing = this.bySession.get(session.id);
-        if (existing?.session === session)
+        if (existing?.session === session) {
+            this.byKey.set(keyOf(key), session);
+            existing.activeAt = Date.now();
             return;
-        this.bySession.set(session.id, { session, key, stateSince: Date.now() });
+        }
+        if (existing) {
+            // Two live objects on one transcript: both would write it and both would
+            // answer the chat. Single-flight `ensure` closes the race that makes
+            // this, so reaching here is a bug worth seeing — the replaced one is
+            // silenced and unreachable, rather than left answering under aliases
+            // nobody knows are stale.
+            log.warn(`session ${session.id} replaced while attached to ${keyOf(existing.key)}`);
+            existing.unsubscribe();
+            this.forgetKeys(existing.session);
+        }
+        this.byKey.set(keyOf(key), session);
         log.info(`attached ${keyOf(key)} → session ${session.id}`);
-        session.subscribe((payload) => {
+        const unsubscribe = session.subscribe((payload) => {
             this.hub.emit(session.id, payload);
             // Run state is workspace-visible: every client's session list shows it.
             if (payload.type === "state") {
                 const attached = this.bySession.get(session.id);
+                // Every turn passes through here, so this is also where a session
+                // proves to the sweeper that it is still in use.
                 if (attached)
-                    attached.stateSince = Date.now();
+                    attached.stateSince = attached.activeAt = Date.now();
                 this.hub.emitWorkspace({
                     type: "session-state",
                     sessionId: session.id,
@@ -132,10 +229,50 @@ export class Router {
                 }
             }
         });
+        this.bySession.set(session.id, {
+            session,
+            key,
+            stateSince: Date.now(),
+            activeAt: Date.now(),
+            unsubscribe,
+        });
     }
     async abort(sessionId) {
         await this.bySession.get(sessionId)?.session.abort();
     }
+    /** Refuse new work from every surface; in-flight turns keep running. */
+    beginDrain() {
+        this.draining = true;
+    }
+    /** Take work again. The auto-updater closes the gate *before* handing over,
+     *  so a turn cannot slip in behind the idle check — and when the handover
+     *  never happens, a Pier left refusing every message forever would be a far
+     *  worse outcome than the race it was avoiding. */
+    endDrain() {
+        this.draining = false;
+    }
+    /** For surfaces that mutate state before dispatching (the web's edit and
+     *  queue-deliver routes): ask first, so a refused dispatch cannot cost a
+     *  rewound transcript or a cleared queue. */
+    isDraining() {
+        return this.draining;
+    }
+    /** The drain gate, throwing. Told to the chat directly (5b): an adapter's
+     *  dispatch catch only logs, and the web caller gets the throw. */
+    refuseDraining(key) {
+        const message = "Pier is restarting — this message was not taken; send it again in a moment.";
+        this.channels.get(key.channelId)
+            ?.notify(key.conversationId, { text: message, origin: { kind: "error" } })
+            .catch((err) => log.error(`could not report the drain to ${key.channelId}`, err));
+        throw new Error(message);
+    }
+    /** Attached sessions still mid-turn — what the drain waits on, and what its
+     *  deadline snapshots into the ledger. */
+    busy() {
+        return [...this.bySession.values()]
+            .filter((attached) => attached.session.state === "streaming")
+            .map((attached) => ({ session: attached.session, key: attached.key }));
+    }
     /**
      * The session already attached to a conversation, if any. Never creates one:
      * a channel's stop or settings command must not be what opens a session.
@@ -157,31 +294,80 @@ export class Router {
                 this.byKey.set(keyOf(key), session);
         }
         if (!session) {
+            // Aliases share one lock: web:<id> and task:<id> must not each open one.
+            const lock = key.channelId === "web" || key.channelId === "task"
+                ? `session:${key.conversationId}`
+                : keyOf(key);
+            const inflight = this.opening.get(lock);
+            // A second caller rides the first one's resolve — which attaches before
+            // this continuation runs, having awaited it first — and registers its own
+            // key against the session that came back.
+            if (inflight) {
+                session = await inflight;
+                this.byKey.set(keyOf(key), session);
+                return this.reached(session);
+            }
             try {
-                session = await this.resolve(key);
+                // Inside the try: a resolver that throws synchronously is the same
+                // failure as one that rejects, and reports the same way.
+                const opening = this.resolve(key);
+                this.opening.set(lock, opening);
+                session = await opening;
             }
             catch (err) {
-                // The one failure with nowhere to report itself: there is no session id
-                // to emit under yet, and every caller only sees a rejected promise.
-                log.error(`could not open a session for ${keyOf(key)}`, err);
+                this.unopened(key, err);
                 throw err;
             }
+            finally {
+                this.opening.delete(lock);
+            }
             this.attach(key, session);
         }
+        return this.reached(session);
+    }
+    /** A session that would not open has no event stream of its own to report on
+     *  — unless its id is what we were asked for, which is what a web or task key
+     *  is. Otherwise the chat that is waiting is told directly. Callers still get
+     *  the rejection; this is only so the waiting side is not left with nothing. */
+    unopened(key, err) {
+        log.error(`could not open a session for ${keyOf(key)}`, err);
+        const message = truncate(`could not open a session: ${String(err)}`);
+        // A web or task key names the session that would not open, so its own
+        // stream is where the waiting surface is looking; an IM key names a chat.
+        if (key.channelId === "web" || key.channelId === "task") {
+            this.reportTo(key.conversationId, message);
+            return;
+        }
+        this.channels.get(key.channelId)
+            ?.notify(key.conversationId, { text: message, origin: { kind: "error" } })
+            .catch((e) => log.error(`could not report it to ${key.channelId}`, e));
+    }
+    /** Reached for, so not idle — every surface that uses a session comes
+     *  through `ensure`, including the ones that only read it. */
+    reached(session) {
+        const attached = this.bySession.get(session.id);
+        if (attached)
+            attached.activeAt = Date.now();
         return session;
     }
     async dispatch(msg) {
+        // Before ensure — a drain must not be what opens a session …
+        if (this.draining)
+            this.refuseDraining(msg.key);
         const session = await this.ensure(msg.key);
+        // … and after — a dispatch that was inside a slow ensure when the gate
+        // closed must not start the turn the drain just declared finished with.
+        if (this.draining)
+            this.refuseDraining(msg.key);
         const { action, text } = decide(msg, session.state);
         // A group chat is many people talking into one session; without a speaker
         // line the agent cannot tell them apart or mention anyone back. Emitted
         // only when the speaker or the clock says something new.
         const prompt = withPrefix(this.senders.next(session.id, msg.sender), text);
-        log.debug(`${action} ${keyOf(msg.key)} → session ${session.id}` +
-            ` (${String(prompt.length)} chars, ${String(msg.images?.length ?? 0)} images)`);
+        log.debug(`${action} ${keyOf(msg.key)} → session ${session.id} (${String(prompt.length)} chars)`);
         // Turn outcomes flow through the event stream; a rejected call surfaces
         // there too, never as a thrown exception across the seam.
-        session[action](prompt, msg.images).catch((err) => {
+        session[action](prompt).catch((err) => {
             this.report(session.id, msg.key, String(err));
         });
         return { sessionId: session.id };

package/dist/core/types.js

@@ -5,3 +5,56 @@
  *  drift, and boundary validators use isThinkingLevel instead of their own copy. */
 export const THINKING_LEVELS = ["off", "minimal", "low", "medium", "high", "xhigh", "max"];
 export const isThinkingLevel = (v) => typeof v === "string" && THINKING_LEVELS.includes(v);
+// Wire-protocol names, not SDK types — but they are pi-ai's spellings, and a
+// non-Pi backend is bound to them by this seam.
+export const PROVIDER_APIS = [
+    "openai-completions",
+    "openai-responses",
+    "anthropic-messages",
+    "google-generative-ai",
+];
+export const isProviderApi = (value) => typeof value === "string" && PROVIDER_APIS.includes(value);
+/** The rules of the ProviderSetup seam, in one place: agent/ enforces them on
+ *  write and web/ pre-checks them at its HTTP boundary, and neither may import
+ *  the other. Throws the message the surface shows. */
+export function validateProviderSetup(input) {
+    if (input.id.length > 100 || !/^[a-z0-9][a-z0-9._-]*$/.test(input.id)) {
+        throw new Error("invalid provider id");
+    }
+    if (input.endpoint) {
+        if (input.endpoint.length > 2048 || input.endpoint !== input.endpoint.trim()) {
+            throw new Error("invalid endpoint");
+        }
+        validateEndpoint(input.endpoint);
+    }
+    if (input.kind === "builtin")
+        return;
+    if (!input.endpoint)
+        throw new Error("custom provider endpoint required");
+    if (input.name && (input.name.length > 200 || input.name !== input.name.trim())) {
+        throw new Error("invalid provider name");
+    }
+    if (!isProviderApi(input.api))
+        throw new Error("unsupported provider API");
+    if (!input.models.length || input.models.length > 100)
+        throw new Error("1-100 models required");
+    const ids = input.models.map((model) => model.id);
+    if (ids.some((id) => !id || id.length > 200 || id !== id.trim()) || new Set(ids).size !== ids.length) {
+        throw new Error("model ids must be non-empty, trimmed and unique");
+    }
+}
+export function validateEndpoint(endpoint) {
+    let url;
+    try {
+        url = new URL(endpoint);
+    }
+    catch {
+        throw new Error("endpoint must be an http(s) URL");
+    }
+    if (url.protocol !== "http:" && url.protocol !== "https:") {
+        throw new Error("endpoint must be an http(s) URL");
+    }
+    if (url.username || url.password || url.search || url.hash) {
+        throw new Error("endpoint must not contain credentials, query or fragment");
+    }
+}

package/dist/db.js

@@ -126,6 +126,18 @@ const MIGRATIONS = [
     key TEXT PRIMARY KEY,
     value TEXT NOT NULL
   );
+  `,
+    // 3 — what a restart's drain deadline cut off, told to the chat at next boot.
+    `
+  -- Written only when a graceful restart aborts a still-running turn; the next
+  -- boot delivers each row and clears it once delivered. Owned by drain.ts.
+  CREATE TABLE restart_ledger (
+    id INTEGER PRIMARY KEY,
+    channel_id TEXT NOT NULL,
+    conversation_id TEXT NOT NULL,
+    note TEXT NOT NULL,
+    created_at INTEGER NOT NULL
+  );
   `,
 ];
 let shared;
@@ -134,6 +146,17 @@ let shared;
  * defaults to it; a test passes `openDb(":memory:")` instead.
  */
 export const pierDb = () => (shared ??= openDb(PIER_DB));
+/** A release-level restore point, taken while the service is stopped even when
+ * the release has no schema migration. The previous complete copy stays put if
+ * writing its replacement fails. */
+export function backupDb(path = PIER_DB) {
+    if (!existsSync(path))
+        return undefined;
+    const bak = `${path}.release.bak`;
+    copyDatabase(path, bak);
+    log.info(`pre-update backup: ${bak}`);
+    return bak;
+}
 /** Open a database, bring it to the current schema, and lock down its files.
  *  `migrations` is injectable only so tests can exercise an upgrade — there is
  *  exactly one real list. */
@@ -141,10 +164,11 @@ export function openDb(path, migrations = MIGRATIONS) {
     if (path !== ":memory:")
         mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
     const db = new DatabaseSync(path);
-    // Outside the transaction below: journal_mode is a property of the file, and
-    // SQLite refuses to change it inside one.
-    db.exec("PRAGMA journal_mode = WAL");
+    // Timeout first: two processes booting together contend on the WAL switch
+    // itself. Outside the transaction below: journal_mode is a property of the
+    // file, and SQLite refuses to change it inside one.
     db.exec(`PRAGMA busy_timeout = ${BUSY_TIMEOUT_MS}`);
+    db.exec("PRAGMA journal_mode = WAL");
     migrate(db, path, migrations);
     if (path !== ":memory:")
         restrict(path);
@@ -175,8 +199,6 @@ function migrate(db, path, migrations) {
     }
     if (at === target)
         return;
-    if (at > 0 && path !== ":memory:")
-        snapshot(db, path, at);
     // One transaction for the statements *and* the version number: a crash
     // between them would leave a database whose version describes a schema it
     // does not have, which is worse than a crash.
@@ -188,9 +210,24 @@ function migrate(db, path, migrations) {
     const { user_version: locked } = db.prepare("PRAGMA user_version").get();
     if (locked >= target) {
         db.exec("ROLLBACK");
+        if (locked > target) {
+            throw new Error(`${path} advanced to schema ${locked} while this Pier was waiting; it speaks ${target}`);
+        }
         log.info(`schema already at ${locked}, migrated by another process`);
         return;
     }
+    // Keep the write lock while a second, read-only connection copies the last
+    // committed state. That connection may VACUUM while this one holds a RESERVED
+    // lock; other Pier starts wait here instead of racing on the shared .tmp.
+    if (locked > 0 && path !== ":memory:") {
+        try {
+            snapshot(path, locked);
+        }
+        catch (err) {
+            db.exec("ROLLBACK");
+            throw err;
+        }
+    }
     let step = locked;
     try {
         for (; step < target; step++)
@@ -221,14 +258,23 @@ function migrate(db, path, migrations) {
  * old snapshot nor a complete new one. A rename is atomic: the `.bak` name only
  * ever refers to a finished copy.
  */
-function snapshot(db, path, at) {
+function snapshot(path, at) {
     const bak = `${path}.v${at}.bak`;
+    copyDatabase(path, bak);
+    log.info(`pre-migration backup: ${bak}`);
+}
+function copyDatabase(path, bak) {
     const tmp = `${bak}.tmp`;
     rmSync(tmp, { force: true }); // a previous crash may have left one
-    db.exec(`VACUUM INTO '${tmp.replaceAll("'", "''")}'`);
+    const source = new DatabaseSync(path, { readOnly: true });
+    try {
+        source.exec(`VACUUM INTO '${tmp.replaceAll("'", "''")}'`);
+    }
+    finally {
+        source.close();
+    }
     chmodSync(tmp, 0o600); // it holds everything the 0600 database holds
     renameSync(tmp, bak);
-    log.info(`pre-migration backup: ${bak}`);
 }
 /** Snapshots beside the database, newest schema first. */
 function backups(path) {