akm-cli 0.9.0 → 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/providers/git-stash.js

@@ -56,6 +56,21 @@ export class GitStashPushError extends Error {
 }
 const GIT_PUSH_TIMEOUT_MS = 120_000;
 const ZERO_OID = "0000000000000000000000000000000000000000";
+let exactCommitHookForTests;
+/**
+ * TEST-ONLY. Interleave work into the exact-path commit sequence; `undefined`
+ * restores. Exists because the CAS window is a few microseconds wide between
+ * two synchronous `git` invocations — a wall-clock race would be
+ * non-deterministic, and every earlier pre-check would swallow a commit that
+ * landed before the window opened. Inert in production.
+ */
+export function _setGitExactCommitHookForTests(hook) {
+    exactCommitHookForTests = hook;
+}
+/** Fire a named exact-path-commit race point (no-op outside tests). */
+function gitExactCommitHook(point) {
+    exactCommitHookForTests?.(point);
+}
 /**
  * Resolve the writable flag for an end-of-run / `akm sync` commit from the
  * configured default bundle.
@@ -523,6 +538,10 @@ function createExactPathCommit(repoDir, options) {
             throw new Error(`Git target changed before its exact commit could be attached.`);
         }
         assertWorktreeMatchesExpected(repoDir, options.paths, expected);
+        // Race window: everything below this line is defended only by the
+        // update-ref compare-and-swap. See
+        // tests/integration/sync-exact-commit-cas.test.ts.
+        gitExactCommitHook("before-update-ref");
         const update = runGit(["-C", repoDir, "update-ref", branchRef, commitOid, options.baseHead ?? ZERO_OID]);
         if (update.status !== 0) {
             throw new Error(`Git target advanced before its exact commit could be attached.`);

package/dist/sources/providers/git.js

@@ -10,4 +10,4 @@
 // keeps importing from a single module namespace.
 export { classifyCloneFailure, cloneRepo, inspectGitUpstream, runGit, syncExistingWritableCheckout, } from "./git-install.js";
 export { ensureGitMirror, GitSourceProvider, getCachePaths, parseGitRepoUrl, syncMirroredRepo, } from "./git-provider.js";
-export { GitStashPushError, isGitBackedStash, listGitChangedPaths, resolveWritableOverride, saveGitStash, } from "./git-stash.js";
+export { _setGitExactCommitHookForTests, GitStashPushError, isGitBackedStash, listGitChangedPaths, resolveWritableOverride, saveGitStash, } from "./git-stash.js";

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/sources/snapshot-fetchers/website-ingest.js

@@ -1,7 +1,7 @@
 // This Source Code Form is subject to the terms of the Mozilla Public
 // License, v. 2.0. If a copy of the MPL was not distributed with this
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
-import { createHash } from "node:crypto";
+import { createHash, randomBytes } from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
 import { fetchWithRetry, isWithin, ResponseTooLargeError, readBodyWithByteCap, resolveStashDir, todayIso, } from "../../core/common.js";
@@ -201,19 +201,111 @@ async function fetchSnapshotViaRegistry(startUrl, stashDir, allowPrivateHosts, r
     };
     return dispatchSnapshotFetchers(parsed, context, stashDir);
 }
+let snapshotWriteHookForTests;
+/**
+ * TEST-ONLY. Interrupt a refresh partway through its page-write loop;
+ * `undefined` restores. Exists because "a process killed mid-refresh" cannot
+ * be staged from outside the module — the whole loop is a single synchronous
+ * burst between two awaits. Inert in production (one `undefined?.()` per page).
+ */
+export function _setWebsiteSnapshotWriteHookForTests(hook) {
+    snapshotWriteHookForTests = hook;
+}
+function snapshotWriteHook(event) {
+    snapshotWriteHookForTests?.(event);
+}
+function snapshotSiblingPrefix(stashDir, kind) {
+    return `.${path.basename(stashDir)}.${kind}-`;
+}
+function snapshotSiblingPath(stashDir, kind) {
+    const unique = `${process.pid}-${randomBytes(6).toString("hex")}`;
+    return path.join(path.dirname(stashDir), `${snapshotSiblingPrefix(stashDir, kind)}${unique}`);
+}
+/**
+ * Age gate for the staging sweep. Nothing enforces one refresh at a time for a
+ * given website source, so a sibling directory may belong to a refresh that is
+ * still running in another process; deleting it would break a healthy run
+ * instead of cleaning up after a dead one. Only clearly-abandoned directories
+ * (untouched for an hour — far longer than the 10-minute crawl wall-clock cap)
+ * are swept. Leftovers are inert until then: they are dot-prefixed, so the
+ * indexer's walk skips them.
+ */
+const SNAPSHOT_STAGING_SWEEP_AGE_MS = 60 * 60 * 1000;
+/** Remove staging/retired directories abandoned by an earlier interrupted run. */
+function sweepSnapshotStaging(stashDir) {
+    const parent = path.dirname(stashDir);
+    let entries;
+    try {
+        entries = fs.readdirSync(parent);
+    }
+    catch {
+        return;
+    }
+    const prefixes = [snapshotSiblingPrefix(stashDir, "staging"), snapshotSiblingPrefix(stashDir, "retired")];
+    const cutoff = Date.now() - SNAPSHOT_STAGING_SWEEP_AGE_MS;
+    for (const entry of entries) {
+        if (!prefixes.some((prefix) => entry.startsWith(prefix)))
+            continue;
+        const abandoned = path.join(parent, entry);
+        try {
+            if (fs.statSync(abandoned).mtimeMs > cutoff)
+                continue;
+        }
+        catch {
+            continue;
+        }
+        fs.rmSync(abandoned, { recursive: true, force: true });
+    }
+}
+function beginSnapshotStaging(stashDir) {
+    fs.mkdirSync(path.dirname(stashDir), { recursive: true });
+    sweepSnapshotStaging(stashDir);
+    const dir = snapshotSiblingPath(stashDir, "staging");
+    fs.mkdirSync(dir, { recursive: true });
+    return { dir, target: stashDir };
+}
+/**
+ * Swap the staged snapshot in. POSIX cannot atomically exchange two non-empty
+ * directories, so the previous snapshot is renamed ASIDE first and deleted
+ * afterwards: the window in which the target does not exist is one syscall
+ * wide instead of an entire write loop.
+ */
+function publishSnapshotStaging(staging) {
+    let retired;
+    if (fs.existsSync(staging.target)) {
+        retired = snapshotSiblingPath(staging.target, "retired");
+        fs.renameSync(staging.target, retired);
+    }
+    fs.renameSync(staging.dir, staging.target);
+    if (retired)
+        fs.rmSync(retired, { recursive: true, force: true });
+}
+/** Drop an unpublished staging directory (no-op once it has been renamed). */
+function discardSnapshotStaging(staging) {
+    fs.rmSync(staging.dir, { recursive: true, force: true });
+}
 /** Materialize a single fetcher snapshot as the source's whole stash. */
 function writeSnapshotToStash(stashDir, snapshot) {
     const preferredName = snapshot.preferredName ?? deriveImportPath(snapshot.url);
     const relPath = avoidReservedBasename(preferredName);
+    // Validate against the FINAL location so the guarantee (and the error text)
+    // is independent of where the file is staged.
     const knowledgeDir = path.join(stashDir, "knowledge");
-    const filePath = path.resolve(knowledgeDir, `${relPath}.md`);
-    if (!isWithin(filePath, knowledgeDir)) {
+    if (!isWithin(path.resolve(knowledgeDir, `${relPath}.md`), knowledgeDir)) {
         throw new UsageError(`Snapshot fetcher returned an unsafe preferred name: ${JSON.stringify(preferredName)}`);
     }
-    fs.rmSync(stashDir, { recursive: true, force: true });
-    fs.mkdirSync(path.dirname(filePath), { recursive: true });
-    const slug = relPath.split("/").pop() ?? "index";
-    fs.writeFileSync(filePath, buildMarkdownSnapshot({ url: snapshot.url, title: snapshot.title, markdown: snapshot.markdown }, slug, snapshot.tags), "utf8");
+    const staging = beginSnapshotStaging(stashDir);
+    try {
+        const filePath = path.resolve(path.join(staging.dir, "knowledge"), `${relPath}.md`);
+        fs.mkdirSync(path.dirname(filePath), { recursive: true });
+        const slug = relPath.split("/").pop() ?? "index";
+        fs.writeFileSync(filePath, buildMarkdownSnapshot({ url: snapshot.url, title: snapshot.title, markdown: snapshot.markdown }, slug, snapshot.tags), "utf8");
+        snapshotWriteHook({ point: "page-written", index: 1, total: 1, relPath: `knowledge/${relPath}.md` });
+        publishSnapshotStaging(staging);
+    }
+    finally {
+        discardSnapshotStaging(staging);
+    }
 }
 async function scrapeWebsiteToStash(startUrl, stashDir, options) {
     // Offer the URL to the specialized fetchers before falling back to a crawl.
@@ -229,19 +321,33 @@ async function scrapeWebsiteToStash(startUrl, stashDir, options) {
     if (pages.length === 0) {
         throw new Error(`No content could be scraped from ${startUrl}`);
     }
-    fs.rmSync(stashDir, { recursive: true, force: true });
-    const knowledgeDir = path.join(stashDir, "knowledge");
-    fs.mkdirSync(knowledgeDir, { recursive: true });
-    const usedPaths = new Set();
-    for (const page of pages) {
-        const relPath = avoidReservedBasename(urlToRelativePath(page.url));
-        const uniquePath = uniqueSlug(relPath, usedPaths);
-        const filePath = path.join(knowledgeDir, `${uniquePath}.md`);
-        const dir = path.dirname(filePath);
-        if (dir !== knowledgeDir)
-            fs.mkdirSync(dir, { recursive: true });
-        const slug = uniquePath.split("/").pop() ?? "index";
-        fs.writeFileSync(filePath, buildMarkdownSnapshot(page, slug), "utf8");
+    const staging = beginSnapshotStaging(stashDir);
+    try {
+        const knowledgeDir = path.join(staging.dir, "knowledge");
+        fs.mkdirSync(knowledgeDir, { recursive: true });
+        const usedPaths = new Set();
+        let written = 0;
+        for (const page of pages) {
+            const relPath = avoidReservedBasename(urlToRelativePath(page.url));
+            const uniquePath = uniqueSlug(relPath, usedPaths);
+            const filePath = path.join(knowledgeDir, `${uniquePath}.md`);
+            const dir = path.dirname(filePath);
+            if (dir !== knowledgeDir)
+                fs.mkdirSync(dir, { recursive: true });
+            const slug = uniquePath.split("/").pop() ?? "index";
+            fs.writeFileSync(filePath, buildMarkdownSnapshot(page, slug), "utf8");
+            written++;
+            snapshotWriteHook({
+                point: "page-written",
+                index: written,
+                total: pages.length,
+                relPath: `knowledge/${uniquePath}.md`,
+            });
+        }
+        publishSnapshotStaging(staging);
+    }
+    finally {
+        discardSnapshotStaging(staging);
     }
 }
 export async function fetchWebsiteMarkdownSnapshot(rawUrl, options) {

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,12 +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" +
-                "  • 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;
     }
@@ -183,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),
@@ -191,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/managed-db.js

@@ -26,6 +26,25 @@ import { applyStandardPragmas } from "./sqlite-pragmas.js";
  * Open a managed SQLite database: ensure the parent dir exists, open the handle,
  * apply standard pragmas, then run the schema initializer. The single home for
  * the open→pragmas→migrate recipe.
+ *
+ * ── On file permissions (reverted, issue #791) ──
+ *
+ * This function briefly chmodded the database, its `-wal`/`-shm` sidecars, and
+ * THE CONTAINING DIRECTORY to owner-only on every open (#756). That was a
+ * mistake and is deliberately not coming back:
+ *
+ *   - It mutated state akm did not create. The data directory belongs to the
+ *     operator; a read of the index is not consent to re-permission their disk.
+ *   - It ran on the most-traveled path in the CLI, including `create: false`
+ *     (read-only) opens, so any command at all silently converted a legacy
+ *     `0755` directory to `0700` with no prompt, warning, or migration note.
+ *   - It therefore broke installs that share `$XDG_DATA_HOME` across uids —
+ *     agent sandboxes, containers, service accounts — which worked in 0.9.0.
+ *     Worse, the read path answers an unreadable index with a false
+ *     "No search index available" at exit 0 rather than an error (#791).
+ *
+ * Files akm creates here get the process umask, which is the operator's lever
+ * for this and always was. akm neither sets these modes nor reports on them.
  */
 export function openManagedDatabase(spec) {
     const dir = path.dirname(spec.path);