akm-cli 0.9.0-beta.5 → 0.9.0-beta.51

package/dist/indexer/db/graph-db.js

@@ -4,7 +4,6 @@
 import fs from "node:fs";
 import { rethrowIfTestIsolationError } from "../../core/errors.js";
 import { getDbPath } from "../../core/paths.js";
-import { warn } from "../../core/warn.js";
 import { closeDatabase, openExistingDatabase } from "./db.js";
 function withReadableGraphDb(db, fn) {
     if (db)
@@ -26,38 +25,16 @@ function uniqueSorted(values) {
 function normalizeEntity(value) {
     return value.trim().toLowerCase();
 }
-/**
- * Resolve a file_path within a stash to its entries.id. Returns null when the
- * path has no indexed entry (orphan graph row).
- */
-export function resolveEntryIdForPath(db, stashRoot, filePath) {
-    try {
-        const row = db
-            .prepare("SELECT id FROM entries WHERE stash_dir = ? AND file_path = ? LIMIT 1")
-            .get(stashRoot, filePath);
-        if (row)
-            return row.id;
-        // Fall back to file_path-only match (legacy callers may pass a stash root
-        // that doesn't exactly match entries.stash_dir, e.g. trailing-slash diffs).
-        const fallback = db.prepare("SELECT id FROM entries WHERE file_path = ? LIMIT 1").get(filePath);
-        return fallback?.id ?? null;
-    }
-    catch {
-        return null;
-    }
-}
 /**
  * Persist (or update) a graph snapshot for a stash root.
  *
- * Implementation: incremental upsert keyed on entries.id. Unchanged files
- * (matching body_hash) are skipped; changed files have their child rows
- * deleted (CASCADE) and re-inserted; files in DB but absent from the new
- * snapshot are deleted. The old behaviour wiped every row for the stash on
- * each write, which produced ~22k row writes per re-index even when one
- * asset changed.
- *
- * Orphan files (no entries row resolvable) are skipped and counted in a
- * single warn() so the caller sees the magnitude without log spam.
+ * #624-P1: keyed on (stash_root, file_path, body_hash) — NOT entries.id. Graph
+ * rows are self-keyed by path, so they survive an entries delete + reinsert
+ * (a reindex) when body_hash is unchanged. Unchanged files (matching body_hash)
+ * only have their file-meta refreshed; files whose body_hash changed have their
+ * old row + child rows deleted and the new content inserted; files in DB but
+ * absent from the new snapshot are deleted. There is no entry_id resolution and
+ * no orphan-skip — a graph file no longer needs a matching entries row.
  */
 export function replaceStoredGraph(db, graph) {
     const upsertMeta = db.prepare(`INSERT INTO graph_meta (
@@ -98,87 +75,146 @@ export function replaceStoredGraph(db, graph) {
         cache_misses = excluded.cache_misses,
         truncation_count = excluded.truncation_count,
         failure_count = excluded.failure_count`);
-    const selectExisting = db.prepare("SELECT entry_id, file_path, body_hash FROM graph_files WHERE stash_root = ?");
-    const deleteFile = db.prepare("DELETE FROM graph_files WHERE entry_id = ?");
-    const deleteEntities = db.prepare("DELETE FROM graph_file_entities WHERE entry_id = ?");
-    const deleteRelations = db.prepare("DELETE FROM graph_file_relations WHERE entry_id = ?");
+    const selectExisting = db.prepare("SELECT file_path, body_hash, file_order FROM graph_files WHERE stash_root = ?");
+    const deleteFile = db.prepare("DELETE FROM graph_files WHERE stash_root = ? AND file_path = ? AND body_hash = ?");
+    const deleteEntities = db.prepare("DELETE FROM graph_file_entities WHERE stash_root = ? AND file_path = ? AND body_hash = ?");
+    const deleteRelations = db.prepare("DELETE FROM graph_file_relations WHERE stash_root = ? AND file_path = ? AND body_hash = ?");
     const insertFile = db.prepare(`INSERT INTO graph_files (
-       entry_id, stash_root, file_path, file_order, file_type, body_hash, confidence, status, reason, extraction_run_id
-     ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`);
+       stash_root, file_path, file_order, file_type, body_hash, confidence, status, reason, extraction_run_id
+     ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`);
     const updateFileMeta = db.prepare(`UPDATE graph_files
        SET file_order = ?, file_type = ?, confidence = ?, status = ?, reason = ?, extraction_run_id = ?
-        WHERE entry_id = ?`);
-    const insertEntity = db.prepare(`INSERT INTO graph_file_entities (entry_id, entity_order, stash_root, entity_norm, entity)
-     VALUES (?, ?, ?, ?, ?)`);
+        WHERE stash_root = ? AND file_path = ? AND body_hash = ?`);
+    const insertEntity = db.prepare(`INSERT INTO graph_file_entities (stash_root, file_path, body_hash, entity_order, entity_norm, entity)
+     VALUES (?, ?, ?, ?, ?, ?)`);
     const insertRelation = db.prepare(`INSERT INTO graph_file_relations (
-       entry_id, relation_order, from_entity_norm, from_entity, to_entity_norm, to_entity, relation_type, confidence
-     ) VALUES (?, ?, ?, ?, ?, ?, ?, ?)`);
+       stash_root, file_path, body_hash, relation_order, from_entity_norm, from_entity, to_entity_norm, to_entity, relation_type, confidence
+     ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`);
     const quality = graph.quality;
     const telemetry = graph.telemetry;
     db.transaction(() => {
         upsertMeta.run(graph.stashRoot, graph.schemaVersion, graph.generatedAt, quality?.consideredFiles ?? graph.files.length, quality?.extractedFiles ?? graph.files.length, quality?.entityCount ?? graph.entities?.length ?? 0, quality?.relationCount ?? graph.relations?.length ?? 0, quality?.extractionCoverage ?? 0, quality?.density ?? 0, telemetry?.extractorId ?? null, telemetry?.extractionRunId ?? null, telemetry?.model ?? null, telemetry?.promptVersion ?? null, telemetry?.batchSize ?? null, telemetry?.cacheHits ?? 0, telemetry?.cacheMisses ?? 0, telemetry?.truncationCount ?? 0, telemetry?.failureCount ?? 0);
-        // Build a snapshot of existing rows for incremental compare.
+        // Build a snapshot of existing rows for incremental compare. The unique
+        // index idx_graph_files_path guarantees at most one row per file_path.
         const existingRows = selectExisting.all(graph.stashRoot);
         const existingByPath = new Map();
         for (const row of existingRows)
             existingByPath.set(row.file_path, row);
-        let orphanCount = 0;
-        const presentEntryIds = new Set();
+        const presentPaths = new Set();
         for (const [fileOrder, node] of graph.files.entries()) {
-            // body_hash is NOT NULL in schema v2; default to a sentinel for inputs
-            // (test fixtures, legacy imports) that don't supply one. The sentinel
-            // never equals a real hash so subsequent staleness checks always
-            // re-extract — correct behaviour for "unknown" bodies.
+            // body_hash is part of the PK; default to a sentinel for inputs (test
+            // fixtures, legacy imports) that don't supply one. The sentinel never
+            // equals a real hash so subsequent staleness checks always re-extract —
+            // correct behaviour for "unknown" bodies. Distinct files in one stash
+            // are still keyed apart by file_path, so the empty sentinel is safe.
             const bodyHash = node.bodyHash && node.bodyHash.length > 0 ? node.bodyHash : "";
-            const entryId = resolveEntryIdForPath(db, graph.stashRoot, node.path);
-            if (entryId == null) {
-                orphanCount += 1;
-                continue;
-            }
-            presentEntryIds.add(entryId);
+            presentPaths.add(node.path);
             const existing = existingByPath.get(node.path);
-            if (existing && existing.entry_id === entryId && existing.body_hash === bodyHash) {
+            if (existing && existing.body_hash === bodyHash) {
                 // Body unchanged — only fix up file_order/confidence in case they drifted.
-                updateFileMeta.run(fileOrder, node.type, node.confidence ?? null, node.status ?? (node.entities.length > 0 ? "extracted" : "empty"), node.reason ?? (node.entities.length > 0 ? "none" : "no_graph_content"), node.extractionRunId ?? telemetry?.extractionRunId ?? null, entryId);
+                updateFileMeta.run(fileOrder, node.type, node.confidence ?? null, node.status ?? (node.entities.length > 0 ? "extracted" : "empty"), node.reason ?? (node.entities.length > 0 ? "none" : "no_graph_content"), node.extractionRunId ?? telemetry?.extractionRunId ?? null, graph.stashRoot, node.path, bodyHash);
                 continue;
             }
             if (existing) {
-                // Stale row (different body_hash, or entry_id moved to a different
-                // path under the same file_path). Wipe child rows; CASCADE would do
-                // it but explicit DELETE keeps the order deterministic.
-                deleteEntities.run(existing.entry_id);
-                deleteRelations.run(existing.entry_id);
-                deleteFile.run(existing.entry_id);
+                // Stale row (different body_hash for this path). Delete the old row by
+                // its OLD body_hash; child rows cascade, but explicit DELETE keeps the
+                // order deterministic and is safe regardless of the FK pragma.
+                deleteEntities.run(graph.stashRoot, existing.file_path, existing.body_hash);
+                deleteRelations.run(graph.stashRoot, existing.file_path, existing.body_hash);
+                deleteFile.run(graph.stashRoot, existing.file_path, existing.body_hash);
             }
-            insertFile.run(entryId, graph.stashRoot, node.path, fileOrder, node.type, bodyHash, node.confidence ?? null, node.status ?? (node.entities.length > 0 ? "extracted" : "empty"), node.reason ?? (node.entities.length > 0 ? "none" : "no_graph_content"), node.extractionRunId ?? telemetry?.extractionRunId ?? null);
+            insertFile.run(graph.stashRoot, node.path, fileOrder, node.type, bodyHash, node.confidence ?? null, node.status ?? (node.entities.length > 0 ? "extracted" : "empty"), node.reason ?? (node.entities.length > 0 ? "none" : "no_graph_content"), node.extractionRunId ?? telemetry?.extractionRunId ?? null);
             for (const [entityOrder, entity] of node.entities.entries()) {
-                insertEntity.run(entryId, entityOrder, graph.stashRoot, normalizeEntity(entity), entity);
+                insertEntity.run(graph.stashRoot, node.path, bodyHash, entityOrder, normalizeEntity(entity), entity);
             }
             for (const [relationOrder, relation] of node.relations.entries()) {
-                insertRelation.run(entryId, relationOrder, normalizeEntity(relation.from), relation.from, normalizeEntity(relation.to), relation.to, relation.type ?? null, relation.confidence ?? null);
+                insertRelation.run(graph.stashRoot, node.path, bodyHash, relationOrder, normalizeEntity(relation.from), relation.from, normalizeEntity(relation.to), relation.to, relation.type ?? null, relation.confidence ?? null);
             }
         }
         // Delete files present in DB but absent from the new snapshot. Child
-        // tables CASCADE on entry_id.
+        // tables CASCADE on the composite key; explicit DELETE keeps it determinstic.
         for (const row of existingRows) {
-            if (!presentEntryIds.has(row.entry_id)) {
-                deleteEntities.run(row.entry_id);
-                deleteRelations.run(row.entry_id);
-                deleteFile.run(row.entry_id);
+            if (!presentPaths.has(row.file_path)) {
+                deleteEntities.run(graph.stashRoot, row.file_path, row.body_hash);
+                deleteRelations.run(graph.stashRoot, row.file_path, row.body_hash);
+                deleteFile.run(graph.stashRoot, row.file_path, row.body_hash);
             }
         }
-        if (orphanCount > 0) {
-            warn(`[graph] replaceStoredGraph: skipped ${orphanCount} file(s) with no resolvable entry under ${graph.stashRoot}.`);
-        }
     })();
 }
 export function deleteStoredGraph(db, stashPath) {
     db.transaction(() => {
-        // Child rows cascade via entry_id; deleting graph_files clears them.
+        // Child rows cascade via the composite (stash_root, file_path, body_hash)
+        // FK; deleting graph_files clears them. This is the explicit full-clear
+        // path for a stash (entries-delete no longer wipes graph data — see #624-P1).
         db.prepare("DELETE FROM graph_files WHERE stash_root = ?").run(stashPath);
         db.prepare("DELETE FROM graph_meta WHERE stash_root = ?").run(stashPath);
     })();
 }
+/**
+ * #624-P1 — does any graph data exist for a file_path under a stash root?
+ * Consumed by show/curate flows (P3) but defined here so the schema and its
+ * accessors land together.
+ */
+export function hasGraphData(db, stashRoot, filePath) {
+    try {
+        const row = db
+            .prepare("SELECT 1 AS present FROM graph_files WHERE stash_root = ? AND file_path = ? LIMIT 1")
+            .get(stashRoot, filePath);
+        return row !== undefined;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * #624-P3 — enqueue a file for lazy graph extraction. Idempotent on the
+ * (stash_root, file_path) PK: a second enqueue refreshes body_hash + queued_at
+ * and keeps the HIGHER priority. Non-blocking, no LLM call — the queued row is
+ * drained later by the graph-extraction pass. Tolerant of a missing table /
+ * db error (best-effort), but never masks the bun-test isolation guard.
+ */
+export function enqueueGraphExtraction(db, stashRoot, filePath, bodyHash, priority = 0) {
+    try {
+        db.prepare(`INSERT INTO graph_extraction_queue (stash_root, file_path, body_hash, priority)
+         VALUES (?, ?, ?, ?)
+       ON CONFLICT(stash_root, file_path) DO UPDATE SET
+         body_hash = excluded.body_hash,
+         priority  = MAX(graph_extraction_queue.priority, excluded.priority),
+         queued_at = datetime('now')`).run(stashRoot, filePath, bodyHash, priority);
+    }
+    catch (err) {
+        rethrowIfTestIsolationError(err);
+    }
+}
+/**
+ * #624-P3 — drain up to `limit` queued files for a stash, highest-priority
+ * first (then oldest queued_at). The returned rows are DELETED from the queue
+ * in the SAME transaction (SELECT-then-DELETE-by-PK), so a drain is exactly
+ * once. Tolerant of a missing table / db error (returns []), but never masks
+ * the bun-test isolation guard.
+ */
+export function drainExtractionQueue(db, stashRoot, limit) {
+    try {
+        return db.transaction(() => {
+            const rows = db
+                .prepare(`SELECT file_path, body_hash, priority
+             FROM graph_extraction_queue
+             WHERE stash_root = ?
+             ORDER BY priority DESC, queued_at ASC
+             LIMIT ?`)
+                .all(stashRoot, limit);
+            const del = db.prepare("DELETE FROM graph_extraction_queue WHERE stash_root = ? AND file_path = ?");
+            for (const row of rows)
+                del.run(stashRoot, row.file_path);
+            return rows.map((row) => ({ filePath: row.file_path, bodyHash: row.body_hash, priority: row.priority }));
+        })();
+    }
+    catch (err) {
+        rethrowIfTestIsolationError(err);
+        return [];
+    }
+}
 /**
  * Scoped loader — only the graph_meta row for a stash. Used by callers that
  * only need summary numbers (e.g. `akm graph summary`).
@@ -195,13 +231,12 @@ export function loadGraphFilesOnly(stashPath, db) {
         return withReadableGraphDb(db, (readDb) => {
             try {
                 const rows = readDb
-                    .prepare(`SELECT entry_id, file_path, file_type, body_hash, confidence, status, reason
+                    .prepare(`SELECT file_path, file_type, body_hash, confidence, status, reason
                 FROM graph_files
                 WHERE stash_root = ?
                 ORDER BY file_order`)
                     .all(stashPath);
                 return rows.map((row) => ({
-                    entryId: row.entry_id,
                     path: row.file_path,
                     type: row.file_type,
                     bodyHash: row.body_hash,
@@ -222,13 +257,16 @@ export function loadGraphFilesOnly(stashPath, db) {
     }
 }
 /**
- * Scoped loader — entities for a single entry_id. Used by per-asset lookups.
+ * Scoped loader — entities for a single file, keyed on the #624-P1 composite
+ * (stash_root, file_path, body_hash). Used by per-asset show/curate lookups.
  */
-export function loadGraphEntitiesByEntry(db, entryId) {
+export function loadGraphEntitiesByPath(db, stashRoot, filePath, bodyHash) {
     try {
         const rows = db
-            .prepare("SELECT entity FROM graph_file_entities WHERE entry_id = ? ORDER BY entity_order")
-            .all(entryId);
+            .prepare(`SELECT entity FROM graph_file_entities
+          WHERE stash_root = ? AND file_path = ? AND body_hash = ?
+          ORDER BY entity_order`)
+            .all(stashRoot, filePath, bodyHash);
         return rows.map((r) => r.entity);
     }
     catch {
@@ -314,27 +352,32 @@ export function loadStoredGraphSnapshot(stashPath, db) {
                 return null;
             try {
                 const fileRows = readDb
-                    .prepare(`SELECT entry_id, file_path, file_type, body_hash, confidence, status, reason, extraction_run_id
+                    .prepare(`SELECT file_path, file_type, body_hash, confidence, status, reason, extraction_run_id
               FROM graph_files
               WHERE stash_root = ?
               ORDER BY file_order`)
                     .all(stashPath);
                 const entityRows = readDb
-                    .prepare(`SELECT gfe.entry_id AS entry_id, gf.file_path AS file_path, gfe.entity AS entity
+                    .prepare(`SELECT gf.file_path AS file_path, gfe.entity AS entity
              FROM graph_file_entities gfe
-             JOIN graph_files gf ON gf.entry_id = gfe.entry_id
+             JOIN graph_files gf
+               ON gf.stash_root = gfe.stash_root
+              AND gf.file_path = gfe.file_path
+              AND gf.body_hash = gfe.body_hash
              WHERE gf.stash_root = ?
              ORDER BY gf.file_order, gfe.entity_order`)
                     .all(stashPath);
                 const relationRows = readDb
-                    .prepare(`SELECT gfr.entry_id AS entry_id,
-                    gf.file_path AS file_path,
+                    .prepare(`SELECT gf.file_path AS file_path,
                     gfr.from_entity AS from_entity,
                     gfr.to_entity AS to_entity,
                     gfr.relation_type AS relation_type,
                     gfr.confidence AS confidence
              FROM graph_file_relations gfr
-             JOIN graph_files gf ON gf.entry_id = gfr.entry_id
+             JOIN graph_files gf
+               ON gf.stash_root = gfr.stash_root
+              AND gf.file_path = gfr.file_path
+              AND gf.body_hash = gfr.body_hash
              WHERE gf.stash_root = ?
              ORDER BY gf.file_order, gfr.relation_order`)
                     .all(stashPath);

package/dist/indexer/ensure-index.js

@@ -11,12 +11,14 @@
  * `searchLocal()` and `show.ts`, centralizing the "indexed yet?" gap handling
  * behind a single entry point.
  */
+import { spawn } from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
 import { ASSET_SPECS, TYPE_DIRS } from "../core/asset/asset-spec.js";
-import { getDbPath } from "../core/paths.js";
+import { getDataDir, getDbPath } from "../core/paths.js";
 import { warn } from "../core/warn.js";
-import { closeDatabase, getEntryCount, getMeta, openExistingDatabase } from "./db/db.js";
+import { closeDatabase, getEntryCount, getIndexedFilePaths, getMeta, openExistingDatabase } from "./db/db.js";
+import { acquireIndexWriterLease, handoffIndexWriterLeaseToPid } from "./index-writer-lock.js";
 function getIndexableFiles(root, spec) {
     if (!fs.existsSync(root))
         return [];
@@ -52,16 +54,34 @@ function getIndexableFiles(root, spec) {
     }
     return files;
 }
-function hasNewerIndexableFiles(stashDir, builtAt) {
-    if (!builtAt)
-        return true;
-    const builtAtMs = new Date(builtAt).getTime();
-    if (!Number.isFinite(builtAtMs))
-        return true;
+/**
+ * Whether any indexable file under `stashDir` is newer than the last build, or
+ * has never been indexed at all.
+ *
+ * Two independent signals, because neither alone is sufficient:
+ *   1. **mtime > builtAt** — catches in-place *edits* of already-indexed files.
+ *   2. **path not in `indexedPaths`** — catches *newly added* files. This is
+ *      clock-independent on purpose: a freshly-written file can have a
+ *      filesystem mtime that compares as *older* than the wall-clock `builtAt`
+ *      (the two clocks are not perfectly synchronized and `builtAt` is
+ *      millisecond-truncated), so the mtime test alone silently misses
+ *      additions made within ~a millisecond of the previous build.
+ *
+ * `getIndexableFiles` applies each asset type's own relevance filter, so
+ * non-indexed companion files (e.g. `package.json` next to a knowledge doc) are
+ * never considered and do not produce false "new file" positives.
+ */
+function hasNewerIndexableFiles(stashDir, builtAt, indexedPaths) {
+    const builtAtMs = builtAt ? new Date(builtAt).getTime() : Number.NaN;
+    const builtAtUsable = Number.isFinite(builtAtMs);
     for (const [type, spec] of Object.entries(ASSET_SPECS)) {
         const typeRoot = path.join(stashDir, TYPE_DIRS[type] ?? spec.stashDir);
         const files = getIndexableFiles(typeRoot, spec);
         for (const file of files) {
+            if (!indexedPaths.has(file))
+                return true;
+            if (!builtAtUsable)
+                return true;
             try {
                 if (fs.statSync(file).mtimeMs > builtAtMs)
                     return true;
@@ -89,7 +109,7 @@ export function isIndexStale(stashDir) {
         if (entryCount === 0)
             return true;
         const builtAt = getMeta(db, "builtAt");
-        if (hasNewerIndexableFiles(stashDir, builtAt))
+        if (hasNewerIndexableFiles(stashDir, builtAt, getIndexedFilePaths(db)))
             return true;
         const storedStashDir = getMeta(db, "stashDir");
         if (storedStashDir !== stashDir) {
@@ -114,16 +134,84 @@ export function isIndexStale(stashDir) {
     }
 }
 /**
- * Run an incremental index when the local index is stale. Best-effort —
- * failures are logged as warnings but never thrown, so the caller can
- * proceed (and surface a proper "not in index" error if the index is
- * still unusable).
- *
- * Returns `true` if an index run was attempted.
+ * Whether the existing index can serve queries for `stashDir` *right now* —
+ * i.e. the DB file exists, the `entries` table holds rows, and those rows were
+ * built for this stash (it is the stored primary stash or appears in the
+ * stored `stashDirs` set). When this is true the index is at worst
+ * content-stale, so the `#607` background-reindex optimization is safe: the
+ * caller gets slightly-stale-but-relevant results immediately. When it is
+ * false the existing index has nothing relevant to return (no DB, no `entries`
+ * table, zero rows, or built for a different stash), so a background reindex
+ * would leave the caller empty until the next read — those cases must rebuild
+ * inline.
  */
-export async function ensureIndex(stashDir) {
-    if (!isIndexStale(stashDir))
+function indexCanServeStash(stashDir) {
+    const dbPath = getDbPath();
+    if (!fs.existsSync(dbPath))
+        return false;
+    let db;
+    try {
+        db = openExistingDatabase(dbPath);
+        if (getEntryCount(db) === 0)
+            return false;
+        const storedStashDir = getMeta(db, "stashDir");
+        if (storedStashDir === stashDir)
+            return true;
+        try {
+            const storedDirs = JSON.parse(getMeta(db, "stashDirs") ?? "[]");
+            return storedDirs.includes(stashDir);
+        }
+        catch {
+            return false;
+        }
+    }
+    catch {
+        // No `entries` table (or otherwise unreadable) — cannot serve.
         return false;
+    }
+    finally {
+        if (db)
+            closeDatabase(db);
+    }
+}
+/**
+ * Spawn a background `akm index` process. Non-blocking — returns immediately.
+ * Background callers share the same global index-writer lease as foreground
+ * writers, so stale-read-triggered auto-index attempts coalesce safely.
+ */
+async function spawnBackgroundReindex(_stashDir) {
+    const dataDir = getDataDir();
+    const logFile = path.join(dataDir, "logs", "index-background.log");
+    fs.mkdirSync(path.dirname(logFile), { recursive: true });
+    const lease = await acquireIndexWriterLease({ mode: "try", purpose: "background-reindex-spawn" });
+    if (!lease)
+        return;
+    const akmBin = process.argv[0];
+    const akmScript = process.argv[1];
+    try {
+        const child = spawn(akmBin, [akmScript, "index", "--background"], {
+            detached: true,
+            stdio: ["ignore", fs.openSync(logFile, "a"), fs.openSync(logFile, "a")],
+            env: { ...process.env },
+        });
+        if (!child.pid) {
+            lease.release();
+            return;
+        }
+        handoffIndexWriterLeaseToPid(lease, child.pid, "background-reindex");
+        try {
+            child.unref();
+        }
+        catch {
+            // ignore
+        }
+    }
+    catch (error) {
+        lease.release();
+        throw error;
+    }
+}
+async function runInlineReindex(stashDir) {
     try {
         const { akmIndex } = await import("./indexer.js");
         await akmIndex({ stashDir });
@@ -134,3 +222,50 @@ export async function ensureIndex(stashDir) {
         return true;
     }
 }
+/**
+ * Ensure the local index exists and is fresh enough for the caller's needs.
+ *
+ * Default mode is `background`, which preserves the low-latency behavior used
+ * by read paths (`search`, `show`, `feedback`): when a populated index is
+ * merely stale, spawn a detached reindex and proceed against the existing
+ * index. When the index is entirely absent (no DB / no `entries` table / zero
+ * rows) the rebuild runs inline regardless of mode, since there is nothing to
+ * proceed against.
+ *
+ * `mode: "blocking"` waits for the rebuild to finish before returning. Use
+ * this for callers like `improve` whose planning logic depends on a populated
+ * `entries` table in the same process.
+ *
+ * Returns `true` if an index run was attempted.
+ */
+export async function ensureIndex(stashDir, options = {}) {
+    if (!isIndexStale(stashDir))
+        return false;
+    // Blocking when explicitly requested, or whenever the existing index cannot
+    // serve this stash (absent DB, no `entries` table, zero rows, or built for a
+    // different stash): a background reindex returns immediately and would leave
+    // a first-time caller (search, curate, wiki, show, feedback) with empty
+    // results. Building inline is a one-off cost; a populated index for this
+    // stash that is merely content-stale still refreshes in the background.
+    if (options.mode === "blocking" || !indexCanServeStash(stashDir)) {
+        return runInlineReindex(stashDir);
+    }
+    // The background path re-invokes the akm CLI as a detached child via
+    // `process.argv[1]`. That is only the akm entrypoint when THIS process is the
+    // akm CLI itself — which the CLI startup block signals with AKM_CLI_ENTRY=1.
+    // In any other host (the in-process test runner, a library embedding akm),
+    // argv[1] points at the host (e.g. the test runner), so spawning it would
+    // launch the wrong program and orphan it. Build inline there instead — same
+    // resulting index, no detached process.
+    if (process.env.AKM_CLI_ENTRY !== "1") {
+        return runInlineReindex(stashDir);
+    }
+    try {
+        await spawnBackgroundReindex(stashDir);
+        return true;
+    }
+    catch (error) {
+        warn("Background reindex spawn failed, proceeding with existing index:", error instanceof Error ? error.message : String(error));
+        return true;
+    }
+}