akm-cli 0.9.1-beta.1 → 0.9.1-beta.2

package/dist/setup/setup.js

@@ -496,17 +496,32 @@ export function buildSetupSteps(options) {
     ];
     return { steps, outcome };
 }
-export async function runSetupWizard(opts) {
-    assertSetupConfigPreflight();
-    p.intro("akm setup");
-    const current = loadUserConfig();
-    const configPath = getConfigPath();
-    // Resolve stash directory early so akmInit can run before any prompts
-    const resolvedStashDir = opts?.dir ? path.resolve(opts.dir) : (primaryBundlePath(current) ?? getDefaultStashDir());
+/**
+ * Resolve the stash directory, apply stash isolation, and THEN read the config.
+ *
+ * Order is the whole point. The pre-isolation read exists only to discover
+ * where the stash is; `applyStashIsolationToEnv` can repoint AKM_CONFIG_DIR,
+ * after which both the config contents and `getConfigPath()` differ. Reading
+ * the merge base before isolation meant an isolated run merged the wizard's
+ * answers onto the HOST config and reported the host path as the save target
+ * while writing somewhere else.
+ */
+function resolveIsolatedSetupConfig(opts) {
+    const preIsolationConfig = loadUserConfig();
+    // Resolve stash directory early so akmInit can run before any prompts.
+    const resolvedStashDir = opts?.dir
+        ? path.resolve(opts.dir)
+        : (primaryBundlePath(preIsolationConfig) ?? getDefaultStashDir());
     // Refuse explicit --dir /tmp/... before doing any work — protects the host
     // config from being clobbered with a stashDir that the OS may reap.
     assertSetupSandbox(resolvedStashDir, opts?.dir != null);
     applyStashIsolationToEnv(resolvedStashDir, opts?.dir != null);
+    return { current: loadUserConfig(), configPath: getConfigPath(), resolvedStashDir };
+}
+export async function runSetupWizard(opts) {
+    assertSetupConfigPreflight();
+    p.intro("akm setup");
+    const { current, configPath, resolvedStashDir } = resolveIsolatedSetupConfig(opts);
     // Quick connectivity check — skip network-dependent steps when offline
     const online = await isOnline();
     if (!online) {

package/dist/sources/providers/git-install.js

@@ -90,6 +90,16 @@ export function assertNoIgnoredPathOverwrite(repoDir, targetRevision) {
         throw new UsageError(`Git update would overwrite ignored local path ${path.join(repoDir, conflict)}; move or remove it before update.`);
     }
 }
+/**
+ * Whether a requested ref is a full commit hash rather than a branch or tag.
+ *
+ * Only the unambiguous 40-hex (SHA-1) and 64-hex (SHA-256) forms count. An
+ * abbreviated hash is indistinguishable from a legal branch name, so it stays
+ * on the `--branch` path where git itself reports the mismatch.
+ */
+function isCommitSha(ref) {
+    return /^[0-9a-f]{40}$/i.test(ref) || /^[0-9a-f]{64}$/i.test(ref);
+}
 function normalizeRemoteUrl(value) {
     return value
         .trim()
@@ -199,10 +209,17 @@ async function doSyncGit(parsed, options) {
     let installRoot;
     let stashRoot;
     try {
+        // `git clone --branch` accepts only a branch or tag name, never a raw commit
+        // hash — so pinning an install to a commit (`#<40-hex-sha>`, which
+        // parseGithubShorthand/parseGitUrl accept and validateGitRef allows) made the
+        // clone fail outright. A commit pin needs a full clone followed by a
+        // checkout of that revision; `--depth 1` cannot fetch an arbitrary commit
+        // either, so the read-only shallow optimization is skipped in that case.
+        const pinnedCommit = parsed.requestedRef !== undefined && isCommitSha(parsed.requestedRef);
         const cloneArgs = ["clone"];
-        if (!options?.writable)
+        if (!options?.writable && !pinnedCommit)
             cloneArgs.push("--depth", "1");
-        if (parsed.requestedRef) {
+        if (parsed.requestedRef && !pinnedCommit) {
             cloneArgs.push("--branch", parsed.requestedRef);
         }
         cloneArgs.push(parsed.url, cloneDir);
@@ -210,6 +227,12 @@ async function doSyncGit(parsed, options) {
         if (cloneResult.status !== 0) {
             throw new Error(classifyCloneFailure(parsed.url, cloneResult.stderr, cloneResult.error));
         }
+        if (pinnedCommit) {
+            const checkout = runGit(["-C", cloneDir, "checkout", "--detach", parsed.requestedRef], { timeout: 120_000 });
+            if (checkout.status !== 0) {
+                throw new Error(`Could not check out commit ${parsed.requestedRef} from ${parsed.url}: ${checkout.stderr.trim() || "unknown git error"}`);
+            }
+        }
         // R-011: `resolved.resolvedRevision` was resolved via a SEPARATE
         // `git ls-remote` round-trip before this clone ran (resolveGitArtifact /
         // resolveGithubArtifact in registry/resolve.ts) and was never checked

package/dist/sources/snapshot-fetchers/content-extract.js

@@ -217,6 +217,30 @@ function markdownDestination(url) {
  * the stack — which would otherwise abort an entire crawl.
  */
 const MAX_NESTING_DEPTH = 2_000;
+/**
+ * HTML5 void elements. They have no closing tag and are conventionally written
+ * WITHOUT a trailing slash, so a depth counter that only decrements on `</x>`
+ * or `<x/>` treats each one as a permanent +1. The counter then measured total
+ * void-element COUNT rather than nesting depth, and an ordinary page with more
+ * than MAX_NESTING_DEPTH images or line breaks was misjudged as pathologically
+ * nested and degraded to plain text.
+ */
+const VOID_ELEMENTS = new Set([
+    "area",
+    "base",
+    "br",
+    "col",
+    "embed",
+    "hr",
+    "img",
+    "input",
+    "link",
+    "meta",
+    "param",
+    "source",
+    "track",
+    "wbr",
+]);
 function exceedsNestingBudget(html) {
     let depth = 0;
     let max = 0;
@@ -226,6 +250,8 @@ function exceedsNestingBudget(html) {
         const selfClosing = match[3] === "/";
         if (selfClosing)
             continue;
+        if (VOID_ELEMENTS.has(match[2].toLowerCase()))
+            continue;
         if (closing)
             depth = Math.max(0, depth - 1);
         else {
@@ -463,9 +489,45 @@ function escapeResidualMarkup(markdown) {
     // Only `<` that begins a tag-like construct; a bare `a < b` stays readable.
     return markdown.replace(/<(?=[a-zA-Z/!?])/g, "&lt;");
 }
+/**
+ * Apply {@link escapeResidualMarkup} everywhere EXCEPT inside fenced code
+ * blocks.
+ *
+ * Markup inside a fence is inert — a renderer shows it as text, it cannot
+ * execute — so the escape buys no safety there and actively corrupts content.
+ * Turndown emits code with entities already decoded, so a documentation page
+ * showing `&lt;div&gt;` in a `<pre><code>` block became a fence containing
+ * `<div>`, which this rewrote to `&lt;div>`: a half-escaped, wrong-on-both-ends
+ * rendering of the example the page exists to show. Every HTML, XML and JSX
+ * snippet in a snapshot was affected.
+ */
+function escapeOutsideCodeFences(markdown) {
+    const lines = markdown.split("\n");
+    let inFence = false;
+    let fenceMarker = "";
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        const fence = /^\s*(`{3,}|~{3,})/.exec(line);
+        if (fence) {
+            const marker = fence[1];
+            if (!inFence) {
+                inFence = true;
+                fenceMarker = marker[0];
+            }
+            else if (marker[0] === fenceMarker) {
+                inFence = false;
+                fenceMarker = "";
+            }
+            continue;
+        }
+        if (!inFence)
+            lines[i] = escapeResidualMarkup(line);
+    }
+    return lines.join("\n");
+}
 /** Escape residual markup, then normalize whitespace, into the final snapshot. */
 function finalizeMarkdown(markdown) {
-    return escapeResidualMarkup(markdown)
+    return escapeOutsideCodeFences(markdown)
         .replace(/\r/g, "")
         .replace(/[ \t]+\n/g, "\n")
         .replace(/\n{3,}/g, "\n\n")

package/dist/storage/database.js

@@ -149,6 +149,48 @@ function loadBunSqlite() {
     return bunSqliteModule;
 }
 let betterSqlite3Ctor;
+/**
+ * The binding is absent or unbuildable — a toolchain/install problem.
+ */
+const MISSING_BINDING_REMEDY = "akm could not load 'better-sqlite3', the SQLite driver it needs on Node.js.\n" +
+    "  • Reinstall akm with a working C/C++ build toolchain so its optional\n" +
+    "    'better-sqlite3' native binding builds (a global `npm i -g better-sqlite3`\n" +
+    "    will NOT be resolved — Node loads it from akm's own node_modules).\n" +
+    "  • Or run akm under Bun, which has a built-in SQLite driver and needs no native build.";
+/**
+ * Recognize a binding built for a DIFFERENT Node ABI than the one now running,
+ * and answer with the one command that fixes it.
+ *
+ * This is the most likely failure a real user hits, and it is not a broken
+ * install: a native addon is compiled (or a prebuilt binary is selected) for
+ * the Node major present at `npm install` time. Upgrade Node afterwards and the
+ * same file no longer loads.
+ *
+ * It is matched rather than described because the symptom text varies and the
+ * previous wording only named ONE of them. The prebuilt-binary path — which is
+ * now the normal path, since better-sqlite3 is pinned to a version publishing a
+ * prebuild for every supported Node (see package.json → pinNotes) — reports
+ * `Module did not self-register`, saying nothing about versions at all. A
+ * from-source build reports the explicit `NODE_MODULE_VERSION` mismatch. Asking
+ * the user to decide which bullet applies is the step worth deleting.
+ */
+export function abiMismatchRemedy(message) {
+    const ABI_MISMATCH_SHAPES = [
+        "did not self-register", // prebuilt binary for another ABI
+        "NODE_MODULE_VERSION", // explicit mismatch, from-source build
+        "was compiled against a different", // same, older phrasing
+        "invalid ELF header", // binary for another platform/arch entirely
+    ];
+    if (!ABI_MISMATCH_SHAPES.some((shape) => message.includes(shape)))
+        return undefined;
+    return ("akm could not load 'better-sqlite3': its native binding was built for a different\n" +
+        `Node.js version than the one now running (this Node is ABI ${process.versions.modules}).\n` +
+        "This is what happens when Node is upgraded after akm is installed. It is NOT a\n" +
+        "broken install, and reinstalling akm is not required.\n" +
+        "  Fix: npm rebuild better-sqlite3        # in akm's install directory\n" +
+        "  Or:  npm install -g akm-cli            # reinstall, rebuilding against this Node\n" +
+        "  Or:  run akm under Bun, whose built-in SQLite driver needs no native binding.");
+}
 function loadBetterSqlite3() {
     if (!betterSqlite3Ctor) {
         // Runtime-gated dynamic require: only reached when NOT on Bun, so Bun never
@@ -161,17 +203,13 @@ function loadBetterSqlite3() {
             mod = nodeRequire("better-sqlite3");
         }
         catch (err) {
-            throw new Error("akm could not load 'better-sqlite3', the SQLite driver it needs on Node.js.\n" +
-                "  • If the error below says the module was compiled against a DIFFERENT Node.js\n" +
-                "    version, you upgraded Node after installing akm. Reinstall akm (or run\n" +
-                "    `npm rebuild better-sqlite3` in its install directory) so the binding is\n" +
-                "    rebuilt for the Node you are now running. This is the common case after a\n" +
-                "    Node major upgrade, and it is NOT a broken install.\n" +
-                "  • Otherwise, reinstall akm with a working C/C++ build toolchain so its optional\n" +
-                "    'better-sqlite3' native binding rebuilds (a global `npm i -g better-sqlite3`\n" +
-                "    will NOT be resolved — Node loads it from akm's own node_modules).\n" +
-                "  • Or run akm under Bun, which has a built-in SQLite driver and needs no native build.\n" +
-                `  Underlying load error: ${err instanceof Error ? err.message : String(err)}`);
+            // An ABI mismatch does NOT arrive here — `require` succeeds and the
+            // failure lands at construction (see openNodeDatabase). This path is a
+            // genuinely absent or unresolvable module. `abiMismatchRemedy` is still
+            // consulted because a from-source build CAN fail at load with the
+            // explicit NODE_MODULE_VERSION message.
+            const raw = err instanceof Error ? err.message : String(err);
+            throw new Error(`${abiMismatchRemedy(raw) ?? MISSING_BINDING_REMEDY}\n  Underlying load error: ${raw}`);
         }
         betterSqlite3Ctor = mod.default ?? mod;
     }
@@ -188,7 +226,24 @@ function openNodeDatabase(path, opts) {
         options.readonly = opts.readonly;
     if (opts?.create === false)
         options.fileMustExist = true;
-    const db = opts ? new BetterSqlite3(path, options) : new BetterSqlite3(path);
+    // Construction, not `require`, is where an ABI mismatch surfaces.
+    // `require("better-sqlite3")` SUCCEEDS against a binding built for another
+    // Node ABI — the package resolves its `.node` file lazily — so the loader's
+    // catch never sees this error and cannot explain it. Verified against a real
+    // ABI-127 binding under Node 24 (ABI 137): `require()` returned a function
+    // and `new Database(...)` threw. Wrapping the require alone left the most
+    // likely real-world failure reported as a bare Node internals message.
+    let db;
+    try {
+        db = opts ? new BetterSqlite3(path, options) : new BetterSqlite3(path);
+    }
+    catch (err) {
+        const raw = err instanceof Error ? err.message : String(err);
+        const remedy = abiMismatchRemedy(raw);
+        if (!remedy)
+            throw err;
+        throw new Error(`${remedy}\n  Underlying error: ${raw}`);
+    }
     return {
         prepare: db.prepare.bind(db),
         exec: db.exec.bind(db),
@@ -196,6 +251,10 @@ function openNodeDatabase(path, opts) {
         // bun:sqlite also provides db.run(). Normalize the latter at the provider
         // boundary so callers and maintenance wrappers can rely on one contract.
         run: (sql, ...params) => db.prepare(sql).run(...params),
+        // sqlite-vec's load(db) calls db.loadExtension(). Without forwarding it the
+        // extension could never load on Node, so the vector fast path was dead
+        // across the entire npm distribution even when sqlite-vec was installed.
+        loadExtension: db.loadExtension.bind(db),
         transaction: db.transaction.bind(db),
         get inTransaction() {
             return db.inTransaction;

package/dist/storage/engines/sqlite-migrations.js

@@ -100,9 +100,68 @@ export function runMigrations(db, migrations, opts) {
         if (applied.has(migration.id))
             continue;
         opts?.beforeMigration?.(migration);
-        db.transaction(() => {
+        withImmediateWriteLock(db, () => {
+            // Re-check under the write lock. `applied` is a snapshot taken before the
+            // loop, so two processes bootstrapping the same fresh DB concurrently
+            // (both see existed=false, both run with applyPending) could each decide
+            // to apply migration N. The first commits; the second must not re-run the
+            // DDL and must not hit a UNIQUE violation on the ledger insert.
+            const already = db.prepare("SELECT 1 FROM schema_migrations WHERE id = ?").get(migration.id);
+            if (already)
+                return;
             db.exec(migration.up);
             db.prepare("INSERT INTO schema_migrations (id) VALUES (?)").run(migration.id);
-        })();
+        });
+        applied.add(migration.id);
     }
 }
+/** Attempts to acquire the write lock before giving up to the caller. */
+const IMMEDIATE_LOCK_MAX_ATTEMPTS = 5;
+/**
+ * Run `fn` inside a `BEGIN IMMEDIATE` transaction.
+ *
+ * The write lock is taken up front rather than upgraded from a read lock, so a
+ * second process bootstrapping the same database WAITS for the first to commit
+ * instead of racing it. `db.transaction()` opens a DEFERRED transaction, which
+ * only takes the write lock on first write — leaving the read-then-write gap
+ * this guards.
+ *
+ * Deliberately local rather than reusing `withImmediateTransaction` from
+ * core/state-db: that module imports this one, so the dependency cannot be
+ * pointed the other way.
+ */
+function withImmediateWriteLock(db, fn) {
+    if (db.inTransaction) {
+        fn();
+        return;
+    }
+    let lastBeginErr;
+    for (let attempt = 1; attempt <= IMMEDIATE_LOCK_MAX_ATTEMPTS; attempt++) {
+        try {
+            db.exec("BEGIN IMMEDIATE");
+        }
+        catch (err) {
+            // Busy despite busy_timeout (another writer holding it across the whole
+            // window). Retry a bounded number of times before surfacing.
+            lastBeginErr = err;
+            continue;
+        }
+        try {
+            fn();
+            db.exec("COMMIT");
+            return;
+        }
+        catch (err) {
+            try {
+                db.exec("ROLLBACK");
+            }
+            catch {
+                // Already rolled back by SQLite (e.g. the statement aborted the txn).
+            }
+            throw err;
+        }
+    }
+    throw lastBeginErr instanceof Error
+        ? lastBeginErr
+        : new Error(`could not acquire the migration write lock after ${IMMEDIATE_LOCK_MAX_ATTEMPTS} attempts`);
+}

package/dist/storage/repositories/index-connection.js

@@ -16,6 +16,7 @@ import { classifyPathAccess, describeInaccessiblePath } from "../../core/path-ac
 import { getDbPath } from "../../core/paths.js";
 import { openDatabase } from "../database.js";
 import { openManagedDatabase } from "../managed-db.js";
+import { SQLITE_BUSY_TIMEOUT_MS } from "../sqlite-pragmas.js";
 import { ensureSchema } from "./index-schema.js";
 import { loadVecExtension, warnIfVecMissing } from "./index-vec-repository.js";
 export function openIndexDatabase(dbPath, options) {
@@ -109,7 +110,16 @@ export function openReadonlyExistingDatabase(dbPath) {
     assertIndexPathReadable(resolvedPath);
     if (classifyPathAccess(resolvedPath).access === "absent")
         return undefined;
-    return openDatabase(resolvedPath, { readonly: true, create: false });
+    const db = openDatabase(resolvedPath, { readonly: true, create: false });
+    // This opener bypasses openManagedDatabase/applyStandardPragmas by design (no
+    // journal or schema work on a read-only handle), but that also left
+    // busy_timeout at SQLite's default of 0. In WAL that is harmless — readers
+    // never block — but in the DELETE/TRUNCATE modes the network-FS fallback and
+    // AKM_SQLITE_JOURNAL_MODE can select, a concurrent writer makes every read
+    // fail instantly with SQLITE_BUSY. busy_timeout is legal on a read-only
+    // connection, so apply just that one.
+    db.exec(`PRAGMA busy_timeout = ${SQLITE_BUSY_TIMEOUT_MS}`);
+    return db;
 }
 export function closeDatabase(db) {
     db.close();

package/dist/storage/repositories/index-meta-repository.js

@@ -17,6 +17,17 @@ export function getMeta(db, key) {
 export function setMeta(db, key, value) {
     db.prepare("INSERT OR REPLACE INTO index_meta (key, value) VALUES (?, ?)").run(key, value);
 }
+/**
+ * Remove a meta key entirely.
+ *
+ * Distinct from writing an empty string: absence is what callers test for
+ * (`getMeta(...) === undefined`), and it is what lets a value be re-derived —
+ * clearing `embeddingDim` after a model change is how the vec table gets
+ * rebuilt at the new width.
+ */
+export function deleteMeta(db, key) {
+    db.prepare("DELETE FROM index_meta WHERE key = ?").run(key);
+}
 // ── Per-directory index state ───────────────────────────────────────────────
 export function getIndexDirState(db, dirPath) {
     const row = db

package/dist/storage/repositories/index-schema.js

@@ -533,8 +533,23 @@ function ensureBundleRefColumns(db) {
  * fallback.
  */
 function ensureUniqueItemRefIndex(db) {
-    db.exec("DROP INDEX IF EXISTS idx_entries_item_ref");
-    db.exec("CREATE UNIQUE INDEX idx_entries_item_ref ON entries(item_ref)");
+    // Probe before mutating. This ran unconditionally on EVERY open as two
+    // separate autocommit statements, so there was always a window in which the
+    // index did not exist — a concurrent open (registry-cache search, indexer,
+    // improve) could DROP between the other's DROP and CREATE and then fail with
+    // "index idx_entries_item_ref already exists", or serve a query with no index
+    // at all. A DB whose index is already UNIQUE needs no work.
+    const existing = db
+        .prepare("SELECT sql FROM sqlite_master WHERE type = 'index' AND name = 'idx_entries_item_ref'")
+        .get();
+    if (existing?.sql && /\bUNIQUE\b/i.test(existing.sql))
+        return;
+    // Pre-v19 (non-unique index) or absent: convert atomically so a racing open
+    // sees either the old index or the new one, never neither.
+    db.transaction(() => {
+        db.exec("DROP INDEX IF EXISTS idx_entries_item_ref");
+        db.exec("CREATE UNIQUE INDEX IF NOT EXISTS idx_entries_item_ref ON entries(item_ref)");
+    })();
 }
 /**
  * Returns true when a table exists in the current database.

package/dist/storage/repositories/index-vec-repository.js

@@ -22,10 +22,10 @@ export function loadVecExtension(db) {
     try {
         const esmRequire = createRequire(import.meta.url);
         const sqliteVec = esmRequire("sqlite-vec");
-        // `db` here is the genuine underlying driver handle returned by the storage
-        // boundary (bun:sqlite on Bun, better-sqlite3 on Node) — only structurally
-        // narrowed for callers. sqlite-vec's `load()` accepts either real handle,
-        // so no raw-handle escape hatch is required.
+        // `db` is the storage boundary's handle. On Bun that IS the bun:sqlite
+        // handle; on Node it is a wrapper, which must forward `loadExtension` for
+        // this call to work at all (see openNodeDatabase in storage/database.ts —
+        // it did not, so vec could never load on the entire npm distribution).
         sqliteVec.load(db);
         vecStatus.set(db, true);
     }
@@ -56,7 +56,45 @@ export function setVecFastPathReady(db, ready) {
  * rather than silently returning partial fast-path results.
  */
 export function isVecFastPathReady(db) {
-    return getMeta(db, VEC_FAST_PATH_READY_META) !== "0";
+    if (getMeta(db, VEC_FAST_PATH_READY_META) === "0")
+        return false;
+    // The meta flag alone is not sufficient. An index built while sqlite-vec was
+    // unavailable wrote only BLOB rows, and because "unavailable" outcomes were
+    // not counted as failures the flag was still set to "1" against a table that
+    // is empty or absent. If sqlite-vec later becomes loadable — the user installs
+    // it, or the same index is opened under the other runtime — the fast path
+    // would then be trusted and return zero neighbours while the BLOB table holds
+    // every embedding. Indexes written by earlier versions still carry that stale
+    // flag, so the read path has to verify the table really exists.
+    return hasVecTable(db);
+}
+const vecTablePresent = new WeakMap();
+/**
+ * Whether `entries_vec` exists on this connection, memoized per handle.
+ *
+ * openExistingDatabase loads the vec extension but deliberately does not run
+ * ensureSchema, so the table is not created on read paths — its absence is a
+ * normal state, not an error.
+ */
+function hasVecTable(db) {
+    // Only a POSITIVE result is memoized. The table cannot vanish from a live
+    // connection, but it CAN appear — ensureSchema creates it partway through an
+    // index run — so caching "absent" would pin a stale answer for the rest of
+    // the handle's life.
+    if (vecTablePresent.get(db) === true)
+        return true;
+    let present = false;
+    try {
+        present =
+            db.prepare("SELECT 1 FROM sqlite_master WHERE type IN ('table','view') AND name = 'entries_vec'").get() !==
+                undefined;
+    }
+    catch {
+        present = false;
+    }
+    if (present)
+        vecTablePresent.set(db, true);
+    return present;
 }
 /** Remove both vector representations for an entry whose embedding input changed. */
 export function deleteEntryVectors(db, id) {

package/dist/storage/sqlite-pragmas.js

@@ -95,6 +95,17 @@ export function isNetworkFilesystem(fsType) {
         return false;
     return NETWORK_FS_MAGICS.has(fsType);
 }
+/** Options for {@link applyStandardPragmas}. */
+/**
+ * How long a statement waits for a lock before failing with SQLITE_BUSY.
+ *
+ * Exported so read-only openers can apply it too. They cannot run the rest of
+ * the standard set (journal_mode and foreign_keys are write operations), but
+ * the default of 0 makes reads fail INSTANTLY under writer contention — which
+ * matters in the DELETE/TRUNCATE journal modes 0.9.1's network-filesystem
+ * fallback and `AKM_SQLITE_JOURNAL_MODE` can select, where readers do block.
+ */
+export const SQLITE_BUSY_TIMEOUT_MS = 30_000;
 /**
  * Apply AKM's standard opening PRAGMAs to `db`, in order:
  *   1. `journal_mode` = the configured mode (with WAL→DELETE network-FS fallback)
@@ -128,7 +139,7 @@ export function applyStandardPragmas(db, opts = {}) {
     // lock instead of failing immediately with SQLITE_BUSY. For the WAL default
     // this is a no-op (WAL→WAL changes nothing), so byte-identical behaviour is
     // preserved.
-    db.exec("PRAGMA busy_timeout = 30000");
+    db.exec(`PRAGMA busy_timeout = ${SQLITE_BUSY_TIMEOUT_MS}`);
     db.exec(`PRAGMA journal_mode = ${mode}`);
     if (opts.foreignKeys !== false) {
         db.exec("PRAGMA foreign_keys = ON");