@holon-run/agentinbox 1.5.1 → 1.6.0

package/README.md

@@ -299,6 +299,22 @@ that database next to the DB path (for example,
 `~/.agentinbox/agentinbox.sqlite.pre-v1.<timestamp>.bak`) and starts with a
 fresh v1 database; pre-v1 local data is not imported.
 
+## Database Backups
+
+Startup backups are event-driven, not unconditional:
+
+- before pending schema migrations run, a full backup is written to
+  `<db>.pre-migrate-v<N>.bak` (bounded by `AGENTINBOX_MIGRATION_BACKUP_KEEP`,
+  default 5; `0` keeps all)
+- `agentinbox backup [--home DIR] [--state PATH]` writes a manual snapshot to
+  `<db>.bak` on demand, for scheduled or pre-upgrade snapshots
+- regular opens verify the database with `PRAGMA quick_check` and escalate to
+  a full `integrity_check` only when the quick pass fails; recovery considers
+  manual and pre-migration backups, most recent first
+
+Setting `AGENTINBOX_STARTUP_BACKUP=1` restores the legacy behavior of backing
+up (and fully checking) the database on every open.
+
 ## License
 
 Apache-2.0

package/dist/src/cli.js

@@ -60,6 +60,14 @@ async function main() {
         await runDaemon(normalized.slice(1));
         return;
     }
+    if (command === "backup") {
+        if (hasHelpFlag(normalized.slice(1))) {
+            printHelp(["backup"]);
+            return;
+        }
+        await runBackup(normalized.slice(1));
+        return;
+    }
     if (hasHelpFlag(normalized.slice(1))) {
         printHelp([command]);
         return;
@@ -971,6 +979,7 @@ const COMMAND_SHELL_SPECS = [
     { name: "subscription", group: true, summary: "Manage source subscriptions." },
     { name: "inbox", group: true, summary: "Read and manage agent inboxes." },
     { name: "gc", group: false, summary: "Run garbage collection." },
+    { name: "backup", group: false, summary: "Write a local database backup snapshot." },
     { name: "deliver", group: true, summary: "Send outbound delivery actions." },
     { name: "status", group: false, summary: "Show daemon status." },
     { name: "version", group: false, summary: "Show CLI version." },
@@ -1006,6 +1015,25 @@ function parseCommanderShell(args) {
         isBareGroup: Boolean(COMMAND_SHELL_SPECS.find((item) => item.name === spec?.name())?.group && args.length === 1),
     };
 }
+async function runBackup(args) {
+    const serveConfig = (0, paths_1.resolveServeConfig)({
+        env: process.env,
+        homeDirOverride: takeFlagValue(args, "--home"),
+        statePathOverride: takeFlagValue(args, "--state"),
+    });
+    const store = await store_1.AgentInboxStore.open(serveConfig.dbPath);
+    try {
+        const backupPath = await store.backupDatabase();
+        console.log((0, util_1.jsonResponse)({
+            ok: true,
+            dbPath: serveConfig.dbPath,
+            backupPath,
+        }));
+    }
+    finally {
+        store.close();
+    }
+}
 async function runServe(args) {
     const port = parseOptionalNumber(takeFlagValue(args, "--port"));
     const homeOverride = takeFlagValue(args, "--home");
@@ -1019,6 +1047,25 @@ async function runServe(args) {
     const daemonPaths = (0, paths_1.resolveDaemonPaths)(process.env, homeOverride);
     const logLevel = (0, logging_1.parseLogLevel)(takeFlagValue(args, "--log-level") ?? process.env.AGENTINBOX_LOG_LEVEL);
     const logger = new logging_1.JsonLogger(logLevel, "agentinbox");
+    // Socket transport: take the admission lock and publish the pid file before
+    // opening the store, so concurrent starters and status checks see this
+    // process during the (possibly slow) store open instead of racing it.
+    let daemonLock = null;
+    if (serveConfig.transport.kind === "socket") {
+        daemonLock = (0, paths_1.daemonLockPath)(serveConfig.transport.socketPath);
+        const acquisition = (0, daemon_1.acquireDaemonLock)(daemonLock);
+        if (!acquisition.acquired) {
+            const holderPid = acquisition.holder?.pid ?? null;
+            logger.warn("daemon.already_running", {
+                pid: holderPid,
+                socketPath: serveConfig.transport.socketPath,
+                lockPath: daemonLock,
+            });
+            console.error(`agentinbox daemon already running${holderPid != null ? ` (pid ${holderPid})` : ""}; not starting a second instance`);
+            process.exit(0);
+        }
+        (0, daemon_1.writePidFile)(daemonPaths.pidPath, process.pid);
+    }
     const store = await store_1.AgentInboxStore.open(serveConfig.dbPath);
     let service;
     const adapters = new adapters_1.AdapterRegistry(store, async (input) => service.appendSourceEvent(input), {
@@ -1029,9 +1076,6 @@ async function runServe(args) {
     await adapters.start();
     await service.start();
     const controlServer = await (0, control_server_1.startControlServer)(server, serveConfig.transport);
-    if (serveConfig.transport.kind === "socket") {
-        (0, daemon_1.writePidFile)(daemonPaths.pidPath, process.pid);
-    }
     (0, daemon_1.writeDaemonMetadata)(daemonPaths.metadataPath, { logLevel });
     logger.info("daemon.ready", {
         homeDir: serveConfig.homeDir,
@@ -1050,8 +1094,11 @@ async function runServe(args) {
             void adapters.stop();
             void service.stop();
             store.close();
-            if (serveConfig.transport.kind === "socket") {
-                (0, daemon_1.removePidFile)(daemonPaths.pidPath);
+            if (serveConfig.transport.kind === "socket" && daemonLock != null) {
+                // Ownership: only remove files that still belong to this process so a
+                // replaced or rebound instance keeps its own pid file and socket.
+                (0, daemon_1.removePidFileIfOwned)(daemonPaths.pidPath, process.pid);
+                (0, daemon_1.releaseDaemonLock)(daemonLock, process.pid);
             }
             (0, daemon_1.removePidFile)(daemonPaths.metadataPath);
             process.exit(0);
@@ -1658,6 +1705,14 @@ Usage:
   agentinbox daemon start [--home ~/.agentinbox] [--socket ~/.agentinbox/agentinbox.sock] [--log-level error|warn|info|debug|trace]
   agentinbox daemon stop [--home ~/.agentinbox] [--socket ~/.agentinbox/agentinbox.sock]
   agentinbox daemon status [--home ~/.agentinbox] [--socket ~/.agentinbox/agentinbox.sock]
+`,
+        backup: `agentinbox backup
+
+Usage:
+  agentinbox backup [--home ~/.agentinbox] [--state ~/.agentinbox/agentinbox.sqlite]
+
+Writes a verified snapshot to <db>.bak (replaces the previous manual backup).
+Pre-migration backups (<db>.pre-migrate-v<N>.bak) are created automatically.
 `,
         host: `agentinbox host
 

package/dist/src/daemon.js

@@ -3,12 +3,20 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.autostartDisabled = autostartDisabled;
 exports.ensureDaemonForClient = ensureDaemonForClient;
 exports.startDaemon = startDaemon;
 exports.stopDaemon = stopDaemon;
 exports.daemonStatus = daemonStatus;
 exports.writePidFile = writePidFile;
 exports.removePidFile = removePidFile;
+exports.removePidFileIfOwned = removePidFileIfOwned;
+exports.readDaemonLock = readDaemonLock;
+exports.isLockHolderLive = isLockHolderLive;
+exports.readLiveDaemonLockHolder = readLiveDaemonLockHolder;
+exports.acquireDaemonLock = acquireDaemonLock;
+exports.releaseDaemonLock = releaseDaemonLock;
+exports.resolveStartTimeoutMs = resolveStartTimeoutMs;
 exports.resolveDaemonLogLevel = resolveDaemonLogLevel;
 exports.writeDaemonMetadata = writeDaemonMetadata;
 const node_fs_1 = __importDefault(require("node:fs"));
@@ -17,11 +25,20 @@ const node_child_process_1 = require("node:child_process");
 const client_1 = require("./client");
 const paths_1 = require("./paths");
 const logging_1 = require("./logging");
-const START_TIMEOUT_MS = 15_000;
+const util_1 = require("./util");
+const DEFAULT_START_TIMEOUT_MS = 60_000;
+// A freshly created but still-empty lock file may belong to a process between
+// create and write; never steal it within this grace window.
+const STALE_LOCK_GRACE_MS = 5_000;
 const PACKAGE_VERSION = readOwnPackageVersion();
+/** AGENTINBOX_NO_AUTOSTART disables implicit daemon spawning (systemd-style deployments). */
+function autostartDisabled(env = process.env) {
+    return (0, util_1.isEnvFlagEnabled)(env.AGENTINBOX_NO_AUTOSTART);
+}
 async function ensureDaemonForClient(options = {}) {
+    const env = options.env ?? process.env;
     const transport = resolveDaemonClientTransport(options);
-    if (options.noAutoStart || transport.kind !== "socket") {
+    if (options.noAutoStart || autostartDisabled(env) || transport.kind !== "socket") {
         return transport;
     }
     if (await canReachHealthz(transport)) {
@@ -37,7 +54,6 @@ async function startDaemon(options = {}) {
     const homeDir = (0, paths_1.resolveAgentInboxHome)(env, options.homeDirOverride);
     const { pidPath, logPath } = (0, paths_1.resolveDaemonPaths)(env, options.homeDirOverride);
     node_fs_1.default.mkdirSync(homeDir, { recursive: true });
-    cleanupStalePidFile(pidPath);
     if (await canReachHealthz(transport)) {
         const pid = readPidFile(pidPath);
         return {
@@ -49,6 +65,31 @@ async function startDaemon(options = {}) {
             transport,
         };
     }
+    // Admission: a live lock holder is starting (or serving) this socket — never
+    // spawn a competing daemon. This check is advisory; the spawned serve
+    // process enforces the lock authoritatively.
+    const lockPath = (0, paths_1.daemonLockPath)(transport.socketPath);
+    const timeoutMs = resolveStartTimeoutMs(env);
+    let pendingHolder = readLiveDaemonLockHolder(lockPath);
+    while (pendingHolder) {
+        const outcome = await waitForDaemonReady(transport, lockPath, timeoutMs);
+        if (outcome === "ready") {
+            const pid = readPidFile(pidPath) ?? pendingHolder.pid;
+            return {
+                started: false,
+                pid,
+                logLevel,
+                pidPath,
+                logPath,
+                transport,
+            };
+        }
+        if (outcome === "timeout") {
+            throw new Error(`AgentInbox daemon is already starting (pid ${pendingHolder.pid}) but did not become ready within ${timeoutMs}ms`);
+        }
+        // The pending holder exited before becoming ready; re-check admission.
+        pendingHolder = readLiveDaemonLockHolder(lockPath);
+    }
     const logFd = openLogFile(logPath);
     let child;
     try {
@@ -69,7 +110,7 @@ async function startDaemon(options = {}) {
         node_fs_1.default.closeSync(logFd);
     }
     child.unref();
-    await waitForHealthz(transport, START_TIMEOUT_MS);
+    await waitForHealthz(transport, timeoutMs);
     return {
         started: true,
         pid: child.pid ?? -1,
@@ -83,42 +124,69 @@ async function stopDaemon(options = {}) {
     const env = options.env ?? process.env;
     const transport = requireSocketTransport(resolveDaemonClientTransport(options), "daemon stop");
     const { pidPath, logPath, metadataPath } = (0, paths_1.resolveDaemonPaths)(env, options.homeDirOverride);
-    const pid = readPidFile(pidPath);
-    if (pid != null && isProcessAlive(pid)) {
+    let pid = readPidFile(pidPath);
+    if (pid == null || !(0, util_1.isPidAlive)(pid)) {
+        // The pid file may be stale or overwritten while the live daemon still
+        // owns the socket; fall back to the admission lock holder.
+        pid = readLiveDaemonLockHolder((0, paths_1.daemonLockPath)(transport.socketPath))?.pid ?? pid;
+    }
+    if (pid != null && (0, util_1.isPidAlive)(pid)) {
         process.kill(pid, "SIGTERM");
         await waitForProcessExit(pid, 3_000);
     }
-    cleanupStalePidFile(pidPath, true);
-    cleanupFile(transport.socketPath);
-    cleanupFile(metadataPath);
+    // Ownership: if an instance we did not stop still serves the socket, the
+    // files may now belong to it — leave them untouched. Otherwise remove the
+    // pid file only when it no longer references a live process.
+    if (!(await canReachHealthz(transport))) {
+        cleanupStalePidFile(pidPath);
+        cleanupFile(transport.socketPath);
+        cleanupFile(metadataPath);
+    }
     return daemonStatus(options);
 }
 async function daemonStatus(options = {}) {
     const env = options.env ?? process.env;
     const transport = requireSocketTransport(resolveDaemonClientTransport(options), "daemon status");
     const { pidPath, logPath, metadataPath } = (0, paths_1.resolveDaemonPaths)(env, options.homeDirOverride);
-    const pid = readPidFile(pidPath);
-    if (pid != null && !isProcessAlive(pid)) {
-        cleanupStalePidFile(pidPath, true);
-        cleanupFile(transport.socketPath);
-        cleanupFile(metadataPath);
-        return {
-            running: false,
-            pid: null,
-            logLevel: null,
-            version: null,
-            startedAt: null,
-            command: null,
-            nodeVersion: null,
-            pidPath,
-            logPath,
-            transport,
-        };
+    let pid = readPidFile(pidPath);
+    if (pid != null && !(0, util_1.isPidAlive)(pid)) {
+        const holder = readLiveDaemonLockHolder((0, paths_1.daemonLockPath)(transport.socketPath));
+        if (holder != null) {
+            // The admission lock identifies the live daemon even when the pid file
+            // is stale (e.g. overwritten by a mixed-version writer).
+            pid = holder.pid;
+        }
+        else if (!(await canReachHealthz(transport))) {
+            // Nothing is serving and no live owner exists: clean stale files.
+            cleanupStalePidFile(pidPath);
+            cleanupFile(transport.socketPath);
+            cleanupFile(metadataPath);
+            return {
+                running: false,
+                starting: false,
+                pid: null,
+                logLevel: null,
+                version: null,
+                startedAt: null,
+                command: null,
+                nodeVersion: null,
+                pidPath,
+                logPath,
+                transport,
+            };
+        }
+        else {
+            // Something answers healthz (e.g. an older daemon without a lock);
+            // report it without owning its files.
+            pid = null;
+        }
     }
     const processInfo = pid == null ? null : readProcessMetadata(pid);
     const daemonMetadata = readDaemonMetadata(metadataPath);
+    const running = await canReachHealthz(transport);
     return {
-        running: await canReachHealthz(transport),
+        running,
+        starting: !running && pid != null && (0, util_1.isPidAlive)(pid),
         pid,
         logLevel: daemonMetadata?.logLevel ?? null,
         version: pid == null ? null : PACKAGE_VERSION,
@@ -137,6 +205,127 @@ function writePidFile(pidPath, pid) {
 function removePidFile(pidPath) {
     cleanupFile(pidPath);
 }
+/** Removes the pid file only when it still belongs to the given pid. */
+function removePidFileIfOwned(pidPath, pid) {
+    if (readPidFile(pidPath) !== pid) {
+        return false;
+    }
+    cleanupFile(pidPath);
+    return true;
+}
+function readDaemonLock(lockPath) {
+    try {
+        const parsed = JSON.parse(node_fs_1.default.readFileSync(lockPath, "utf8"));
+        if (typeof parsed.pid !== "number" || !Number.isInteger(parsed.pid) || parsed.pid <= 0) {
+            return null;
+        }
+        return {
+            pid: parsed.pid,
+            processStartedAt: typeof parsed.processStartedAt === "string" ? parsed.processStartedAt : null,
+            acquiredAt: typeof parsed.acquiredAt === "string" ? parsed.acquiredAt : new Date(0).toISOString(),
+        };
+    }
+    catch {
+        return null;
+    }
+}
+function isLockHolderLive(holder) {
+    if (!(0, util_1.isPidAlive)(holder.pid)) {
+        return false;
+    }
+    if (holder.processStartedAt == null) {
+        return true;
+    }
+    const current = readProcessMetadata(holder.pid);
+    if (current?.startedAt == null) {
+        return true;
+    }
+    return current.startedAt === holder.processStartedAt;
+}
+function readLiveDaemonLockHolder(lockPath) {
+    const holder = readDaemonLock(lockPath);
+    return holder != null && isLockHolderLive(holder) ? holder : null;
+}
+/**
+ * Atomically (O_EXCL) acquires the daemon admission lock for this process.
+ * A stale lock (dead pid or pid reuse) is removed and retried once. A freshly
+ * created but still-empty lock is treated as held to avoid racing a concurrent
+ * creator between create and write.
+ */
+function acquireDaemonLock(lockPath) {
+    let holder = null;
+    for (let attempt = 0; attempt < 2; attempt += 1) {
+        holder = null;
+        try {
+            const metadata = readProcessMetadata(process.pid);
+            const info = {
+                pid: process.pid,
+                processStartedAt: metadata?.startedAt ?? null,
+                acquiredAt: new Date().toISOString(),
+            };
+            node_fs_1.default.writeFileSync(lockPath, `${JSON.stringify(info)}\n`, { encoding: "utf8", flag: "wx" });
+            return { acquired: true, lockPath, holder: null };
+        }
+        catch (error) {
+            if (!isFileExistsError(error)) {
+                throw error;
+            }
+        }
+        holder = readDaemonLock(lockPath);
+        if (holder != null && isLockHolderLive(holder)) {
+            return { acquired: false, lockPath, holder };
+        }
+        if (holder == null && isLockFileFresh(lockPath)) {
+            return { acquired: false, lockPath, holder: null };
+        }
+        cleanupFile(lockPath);
+    }
+    return { acquired: false, lockPath, holder };
+}
+/** Releases the lock only when it still belongs to the given pid. */
+function releaseDaemonLock(lockPath, pid) {
+    const holder = readDaemonLock(lockPath);
+    if (holder?.pid === pid) {
+        cleanupFile(lockPath);
+    }
+}
+function resolveStartTimeoutMs(env = process.env) {
+    const raw = env.AGENTINBOX_START_TIMEOUT_MS;
+    if (raw == null || raw.trim() === "") {
+        return DEFAULT_START_TIMEOUT_MS;
+    }
+    const parsed = Number.parseInt(raw, 10);
+    return Number.isInteger(parsed) && parsed > 0 ? parsed : DEFAULT_START_TIMEOUT_MS;
+}
+function isFileExistsError(error) {
+    return typeof error === "object" && error != null && error.code === "EEXIST";
+}
+function isLockFileFresh(lockPath) {
+    try {
+        return Date.now() - node_fs_1.default.statSync(lockPath).mtimeMs < STALE_LOCK_GRACE_MS;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Waits for the daemon holding the lock to serve healthz. Returns "lost" when
+ * the holder disappears without becoming ready so the caller can re-check
+ * admission instead of timing out.
+ */
+async function waitForDaemonReady(transport, lockPath, timeoutMs) {
+    const startedAt = Date.now();
+    while (Date.now() - startedAt < timeoutMs) {
+        if (await canReachHealthz(transport)) {
+            return "ready";
+        }
+        if (readLiveDaemonLockHolder(lockPath) == null) {
+            return "lost";
+        }
+        await sleep(100);
+    }
+    return "timeout";
+}
 function daemonChildArgs() {
     const execArgv = [...process.execArgv];
     return [...execArgv, process.argv[1], "serve"];
@@ -232,20 +421,20 @@ async function waitForHealthz(transport, timeoutMs) {
 async function waitForProcessExit(pid, timeoutMs) {
     const startedAt = Date.now();
     while (Date.now() - startedAt < timeoutMs) {
-        if (!isProcessAlive(pid)) {
+        if (!(0, util_1.isPidAlive)(pid)) {
             return;
         }
         await sleep(100);
     }
     throw new Error(`timed out waiting for process ${pid} to exit`);
 }
-function cleanupStalePidFile(pidPath, force = false) {
+function cleanupStalePidFile(pidPath) {
     const pid = readPidFile(pidPath);
     if (pid == null) {
         cleanupFile(pidPath);
         return;
     }
-    if (force || !isProcessAlive(pid)) {
+    if (!(0, util_1.isPidAlive)(pid)) {
         cleanupFile(pidPath);
     }
 }
@@ -325,15 +514,6 @@ function inferNodeVersionFromCommand(command) {
     const match = command.match(/node\/(v\d+\.\d+\.\d+)\//);
     return match ? match[1] : null;
 }
-function isProcessAlive(pid) {
-    try {
-        process.kill(pid, 0);
-        return true;
-    }
-    catch {
-        return false;
-    }
-}
 function cleanupFile(filePath) {
     try {
         if (node_fs_1.default.existsSync(filePath)) {

package/dist/src/paths.js

@@ -7,6 +7,7 @@ exports.DEFAULT_AGENTINBOX_PORT = void 0;
 exports.resolveAgentInboxHome = resolveAgentInboxHome;
 exports.resolveServeConfig = resolveServeConfig;
 exports.resolveDaemonPaths = resolveDaemonPaths;
+exports.daemonLockPath = daemonLockPath;
 exports.resolveClientTransport = resolveClientTransport;
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_os_1 = __importDefault(require("node:os"));
@@ -74,6 +75,13 @@ function resolveDaemonPaths(env = process.env, homeDirOverride) {
         metadataPath: node_path_1.default.join(homeDir, "agentinbox.daemon.json"),
     };
 }
+/**
+ * Admission lock for the daemon serving a given socket. Scoped to the socket
+ * identity (not the home dir) so an explicit --socket gets its own lock.
+ */
+function daemonLockPath(socketPath) {
+    return `${socketPath}.lock`;
+}
 function resolveClientTransport(input = {}) {
     const env = input.env ?? process.env;
     const homeDir = resolveAgentInboxHome(env, input.homeDirOverride);

package/dist/src/store.js

@@ -35,27 +35,34 @@ class AgentInboxStore {
         this.dbPath = dbPath;
         this.db = db;
     }
-    static async open(dbPath) {
+    static async open(dbPath, options = {}) {
+        const env = options.env ?? process.env;
         node_fs_1.default.mkdirSync(node_path_1.default.dirname(dbPath), { recursive: true });
+        removeOrphanBackupTmps(dbPath);
         const existedBeforeOpen = node_fs_1.default.existsSync(dbPath);
-        let db = await this.openDatabaseWithRecovery(dbPath);
+        // Legacy AGENTINBOX_STARTUP_BACKUP=1 mode pays for a full check and an
+        // unconditional backup on every open, matching v1.5.2 behavior.
+        const legacyStartupBackup = legacyStartupBackupEnabled(env);
+        let db = await this.openDatabaseWithRecovery(dbPath, legacyStartupBackup);
         let store = new AgentInboxStore(dbPath, db);
+        let archivedPreV1 = false;
         if (existedBeforeOpen && store.shouldArchivePreV1Database()) {
             const archivedPath = store.archivePreV1Database();
             console.warn(`[agentinbox] archived pre-v1 local database to ${archivedPath}; starting with a fresh v1 database (no data imported).`);
             db = this.openDatabase(dbPath);
             store = new AgentInboxStore(dbPath, db);
+            archivedPreV1 = true;
         }
-        else if (existedBeforeOpen) {
-            await store.backupHealthyDatabase();
+        else if (existedBeforeOpen && legacyStartupBackup) {
+            await store.backupDatabase();
         }
-        store.migrate();
+        await store.migrate({ existedBeforeOpen: existedBeforeOpen && !archivedPreV1, env });
         store.persist();
         return store;
     }
-    static async openDatabaseWithRecovery(dbPath) {
+    static async openDatabaseWithRecovery(dbPath, fullCheck) {
         try {
-            return this.openDatabase(dbPath);
+            return this.openDatabase(dbPath, fullCheck);
         }
         catch (error) {
             if (!node_fs_1.default.existsSync(dbPath)) {
@@ -69,19 +76,29 @@ class AgentInboxStore {
             node_fs_1.default.renameSync(dbPath, corruptPath);
             node_fs_1.default.copyFileSync(backupPath, dbPath);
             console.warn(`[agentinbox] recovered local database from ${backupPath}; archived corrupt database to ${corruptPath}.`);
-            return this.openDatabase(dbPath);
+            return this.openDatabase(dbPath, fullCheck);
         }
     }
-    static openDatabase(dbPath) {
+    static openDatabase(dbPath, fullCheck = false) {
         const db = new better_sqlite3_1.default(dbPath);
         db.pragma("busy_timeout = 5000");
         db.pragma("journal_mode = WAL");
         db.pragma("synchronous = NORMAL");
         db.pragma("foreign_keys = ON");
-        this.assertHealthy(db, dbPath);
+        this.assertHealthy(db, dbPath, fullCheck);
         return db;
     }
-    static assertHealthy(db, dbPath) {
+    /**
+     * Verifies database integrity. Regular opens run `quick_check` and only
+     * escalate to a full `integrity_check` when the quick pass fails, so large
+     * databases do not pay a full scan on every startup. Conservative callers
+     * (legacy `AGENTINBOX_STARTUP_BACKUP=1` mode, recovery-candidate
+     * validation) pass `fullCheck`.
+     */
+    static assertHealthy(db, dbPath, fullCheck) {
+        if (!fullCheck && db.pragma("quick_check", { simple: true }) === "ok") {
+            return;
+        }
         const result = db.pragma("integrity_check", { simple: true });
         if (result !== "ok") {
             db.close();
@@ -93,7 +110,7 @@ class AgentInboxStore {
         for (const candidate of candidates) {
             try {
                 const db = new better_sqlite3_1.default(candidate, { readonly: true, fileMustExist: true });
-                this.assertHealthy(db, candidate);
+                this.assertHealthy(db, candidate, true);
                 db.close();
                 return candidate;
             }
@@ -106,14 +123,32 @@ class AgentInboxStore {
     static listBackupCandidates(dbPath) {
         const dir = node_path_1.default.dirname(dbPath);
         const baseName = node_path_1.default.basename(dbPath);
-        const startupBackups = node_fs_1.default.existsSync(dir)
-            ? node_fs_1.default.readdirSync(dir)
-                .filter((name) => name.startsWith(`${baseName}.startup.`) && name.endsWith(".bak"))
-                .sort()
-                .reverse()
-                .map((name) => node_path_1.default.join(dir, name))
-            : [];
-        return [`${dbPath}.bak`, ...startupBackups].filter((candidate, index, all) => node_fs_1.default.existsSync(candidate) && all.indexOf(candidate) === index);
+        const preMigrationPattern = new RegExp(`^${escapeRegExp(baseName)}\\.pre-migrate-v(\\d+)\\.bak$`);
+        let entries;
+        try {
+            entries = node_fs_1.default.readdirSync(dir);
+        }
+        catch {
+            return [];
+        }
+        const candidates = [];
+        for (const name of entries) {
+            const candidatePath = node_path_1.default.join(dir, name);
+            if (name === `${baseName}.bak`) {
+                candidates.push({ path: candidatePath, version: 0, modifiedAtMs: backupMtimeMs(candidatePath) });
+                continue;
+            }
+            const preMigration = preMigrationPattern.exec(name);
+            if (preMigration) {
+                candidates.push({
+                    path: candidatePath,
+                    version: Number.parseInt(preMigration[1], 10),
+                    modifiedAtMs: backupMtimeMs(candidatePath),
+                });
+            }
+        }
+        candidates.sort((left, right) => right.modifiedAtMs - left.modifiedAtMs || right.version - left.version);
+        return candidates.map((candidate) => candidate.path);
     }
     static nextPath(base) {
         if (!node_fs_1.default.existsSync(base)) {
@@ -133,13 +168,22 @@ class AgentInboxStore {
     }
     getDatabaseHealth() {
         return {
-            integrityCheck: String(this.db.pragma("integrity_check", { simple: true })),
+            quickCheck: String(this.db.pragma("quick_check", { simple: true })),
             journalMode: String(this.db.pragma("journal_mode", { simple: true })),
             foreignKeys: Number(this.db.pragma("foreign_keys", { simple: true })) === 1,
         };
     }
-    async backupHealthyDatabase() {
+    /**
+     * Writes a snapshot to `<db>.bak`, used by `agentinbox backup` and by the
+     * opt-in legacy `AGENTINBOX_STARTUP_BACKUP=1` startup backup. The open-time
+     * health check has already run against this handle. Returns the backup path.
+     */
+    async backupDatabase() {
         const backupPath = `${this.dbPath}.bak`;
+        await this.writeBackupTo(backupPath);
+        return backupPath;
+    }
+    async writeBackupTo(backupPath) {
         const tmpPath = `${backupPath}.${process.pid}.tmp`;
         try {
             node_fs_1.default.rmSync(tmpPath, { force: true });
@@ -150,17 +194,57 @@ class AgentInboxStore {
             node_fs_1.default.rmSync(tmpPath, { force: true });
         }
     }
-    migrate() {
+    async migrate(options) {
         const migrations = this.loadSqlMigrations();
         this.ensureDrizzleMigrationsTable();
         const applied = this.listAppliedMigrationTags();
         const pending = migrations.filter((migration) => !applied.has(migration.tag));
+        if (options.existedBeforeOpen && pending.length > 0) {
+            const backupPath = await this.backupBeforeMigration(migrations.length);
+            console.warn(`[agentinbox] pending schema migrations detected; backed up the local database to ${backupPath} before migrating to schema v${migrations.length}.`);
+            this.pruneMigrationBackups(options.env);
+        }
         for (const migration of pending) {
             this.applyMigration(migration);
         }
         this.ensureInboxEntryBackfill();
         this.setUserVersion(migrations.length);
     }
+    async backupBeforeMigration(targetVersion) {
+        const backupPath = `${this.dbPath}.pre-migrate-v${targetVersion}.bak`;
+        await this.writeBackupTo(backupPath);
+        return backupPath;
+    }
+    /**
+     * Keeps only the newest `AGENTINBOX_MIGRATION_BACKUP_KEEP` pre-migration
+     * backups (default 5; values <= 0 keep everything). Migration backups are
+     * rare, so pruning only runs right after a new one is written.
+     */
+    pruneMigrationBackups(env) {
+        const keep = migrationBackupKeep(env);
+        if (keep <= 0) {
+            return;
+        }
+        const dir = node_path_1.default.dirname(this.dbPath);
+        const pattern = new RegExp(`^${escapeRegExp(node_path_1.default.basename(this.dbPath))}\\.pre-migrate-v(\\d+)\\.bak$`);
+        const entries = [];
+        for (const name of node_fs_1.default.readdirSync(dir)) {
+            const match = pattern.exec(name);
+            if (!match) {
+                continue;
+            }
+            entries.push({ path: node_path_1.default.join(dir, name), version: Number.parseInt(match[1], 10) });
+        }
+        entries.sort((left, right) => right.version - left.version);
+        for (const entry of entries.slice(keep)) {
+            try {
+                node_fs_1.default.rmSync(entry.path, { force: true });
+            }
+            catch {
+                // Best-effort pruning.
+            }
+        }
+    }
     loadSqlMigrations() {
         const migrationsDir = this.resolveMigrationsDir();
         const files = node_fs_1.default
@@ -2382,3 +2466,61 @@ function uniqueSorted(values) {
 function summarizeBackfilledItemEntry(item) {
     return `${item.eventVariant} from ${item.sourceId}`;
 }
+const DEFAULT_MIGRATION_BACKUP_KEEP = 5;
+/**
+ * Backups are event-driven: a full database backup is taken only before
+ * pending schema migrations run, plus explicit `agentinbox backup` snapshots.
+ * Setting `AGENTINBOX_STARTUP_BACKUP=1` opts back into the legacy v1.5.2
+ * behavior of an unconditional backup and a full `integrity_check` on every
+ * open.
+ */
+function legacyStartupBackupEnabled(env) {
+    return (0, util_1.isEnvFlagEnabled)(env.AGENTINBOX_STARTUP_BACKUP);
+}
+function migrationBackupKeep(env) {
+    const parsed = Number.parseInt(env.AGENTINBOX_MIGRATION_BACKUP_KEEP ?? "", 10);
+    return Number.isInteger(parsed) ? parsed : DEFAULT_MIGRATION_BACKUP_KEEP;
+}
+function backupMtimeMs(candidatePath) {
+    try {
+        return node_fs_1.default.statSync(candidatePath).mtimeMs;
+    }
+    catch {
+        return 0;
+    }
+}
+/**
+ * Removes leftover `<db>.*.bak.<pid>.tmp` files (manual and pre-migration
+ * backup temporaries) whose owning process is dead. Tmp files owned by a live
+ * pid belong to a concurrent open and are preserved.
+ */
+function removeOrphanBackupTmps(dbPath) {
+    const dir = node_path_1.default.dirname(dbPath);
+    const pattern = new RegExp(`^${escapeRegExp(node_path_1.default.basename(dbPath))}\\.(?:.+\\.)?bak\\.(\\d+)\\.tmp$`);
+    let entries;
+    try {
+        entries = node_fs_1.default.readdirSync(dir);
+    }
+    catch {
+        return;
+    }
+    for (const name of entries) {
+        const match = pattern.exec(name);
+        if (!match) {
+            continue;
+        }
+        const pid = Number.parseInt(match[1], 10);
+        if (Number.isInteger(pid) && pid > 0 && (0, util_1.isPidAlive)(pid)) {
+            continue;
+        }
+        try {
+            node_fs_1.default.rmSync(node_path_1.default.join(dir, name), { force: true });
+        }
+        catch {
+            // Best-effort GC.
+        }
+    }
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}

package/dist/src/util.js

@@ -4,6 +4,9 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.nowIso = nowIso;
+exports.isPidAlive = isPidAlive;
+exports.isEnvFlagDisabled = isEnvFlagDisabled;
+exports.isEnvFlagEnabled = isEnvFlagEnabled;
 exports.generateCanonicalId = generateCanonicalId;
 exports.generateId = generateId;
 exports.generateShortToken = generateShortToken;
@@ -21,6 +24,32 @@ const ENTRY_THREAD_ID_PATTERN = new RegExp(`^(ent|thr)_[${CANONICAL_ID_ALPHABET}
 function nowIso() {
     return new Date().toISOString();
 }
+function isPidAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Treats an env flag as disabled only when it holds an explicit falsy word.
+ * Missing or empty values mean "unset" and keep the default behavior.
+ */
+function isEnvFlagDisabled(raw) {
+    if (raw == null) {
+        return false;
+    }
+    const normalized = raw.trim().toLowerCase();
+    return normalized === "0" || normalized === "false" || normalized === "no" || normalized === "off";
+}
+/**
+ * Treats an env flag as set only when it holds a non-empty, non-falsy value.
+ */
+function isEnvFlagEnabled(raw) {
+    return raw != null && raw.trim() !== "" && !isEnvFlagDisabled(raw);
+}
 function generateCanonicalId(prefix, length = CANONICAL_ID_TOKEN_LENGTH) {
     return `${prefix}_${generateShortToken(length)}`;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@holon-run/agentinbox",
-  "version": "1.5.1",
+  "version": "1.6.0",
   "description": "Local event subscription and delivery service for agents.",
   "license": "Apache-2.0",
   "repository": {