akm-cli 0.9.0-beta.0 → 0.9.0-beta.10

package/dist/core/state-db.js

@@ -86,11 +86,12 @@ export function getStateDbPath() {
  *     backwards compatibility; enabling them prevents orphaned rows in tables
  *     that reference each other (not used in v1 schema but guards future ones).
  *
- *   busy_timeout = 5000
+ *   busy_timeout = 30000
  *     When another connection holds a write lock, SQLite retries for up to
- *     5 000 ms before returning SQLITE_BUSY. Without this, the default timeout
- *     is 0 ms — any concurrent writer causes an immediate error. 5 s matches
- *     the same value used in openDatabase() for index.db.
+ *     30 000 ms before returning SQLITE_BUSY. Without this, the default timeout
+ *     is 0 ms — any concurrent writer causes an immediate error. 30 s (#589)
+ *     matches the value used in openDatabase() for index.db; 5 s proved too
+ *     narrow when a post-inference reindex overlapped a parallel event write.
  */
 export function openStateDatabase(dbPath) {
     const resolvedPath = dbPath ?? getStateDbPath();
@@ -102,7 +103,7 @@ export function openStateDatabase(dbPath) {
     // PRAGMAs must run before any DDL or DML.
     db.exec("PRAGMA journal_mode = WAL");
     db.exec("PRAGMA foreign_keys = ON");
-    db.exec("PRAGMA busy_timeout = 5000");
+    db.exec("PRAGMA busy_timeout = 30000");
     runMigrations(db);
     return db;
 }
@@ -190,7 +191,9 @@ const MIGRATIONS = [
       --
       -- Extensible (metadata_json) columns:
       --   metadata_json TEXT      — JSON object for future proposal fields.
-      --                             Current fields stored here: sourceRun, review.
+      --                             Current fields stored here: sourceRun,
+      --                             review, confidence, gateDecision (#577),
+      --                             backupContent, eligibilitySource.
       --
       -- ADD COLUMN extension points (future migrations):
       --   ALTER TABLE proposals ADD COLUMN source_run TEXT DEFAULT NULL;
@@ -458,6 +461,47 @@ const MIGRATIONS = [
         ON extract_sessions_seen(processed_at);
     `,
     },
+    // ── Migration 005 — proposal_fs_imports ─────────────────────────────────────
+    //
+    // One-shot ledger for the legacy filesystem→SQLite proposal import (#578).
+    //
+    // Before 0.9.0 the proposal queue lived as per-uuid JSON directories under
+    // `<stashDir>/.akm/proposals/` and the `proposals` table (created in 001) was
+    // dead weight. 0.9.0 makes the table canonical; the first proposal operation
+    // against a stash imports any legacy `proposal.json` files it finds (INSERT
+    // OR IGNORE, so re-runs never duplicate) and records the stash here so later
+    // invocations skip the directory walk entirely.
+    //
+    // Indexed (query) columns:
+    //   stash_dir    TEXT PK  — absolute stash root the import ran against.
+    //
+    // Non-indexed columns:
+    //   imported_at    TEXT     — ISO-8601 UTC; when the import completed.
+    //   imported_count INTEGER  — rows actually inserted by the import.
+    {
+        id: "005-proposal-fs-imports",
+        up: `
+      CREATE TABLE IF NOT EXISTS proposal_fs_imports (
+        stash_dir      TEXT    PRIMARY KEY,
+        imported_at    TEXT    NOT NULL,
+        imported_count INTEGER NOT NULL DEFAULT 0
+      );
+    `,
+    },
+    // ── Migration 006 — pending proposal lookup index ──────────────────────────
+    //
+    // Supports the transaction-scoped dedup / queue-mutation hardening added in
+    // 0.9.x. The queue now acquires an IMMEDIATE write transaction before it
+    // reads pending proposals, so the hot path is a stash-scoped `status='pending'
+    // AND ref=?` probe followed by an update/insert. This composite index keeps
+    // that lookup index-covered under contention.
+    {
+        id: "006-proposals-pending-ref-source",
+        up: `
+      CREATE INDEX IF NOT EXISTS idx_proposals_stash_status_ref_source
+        ON proposals(stash_dir, status, ref, source);
+    `,
+    },
 ];
 /**
  * Apply every pending migration in a single transaction per migration.
@@ -529,6 +573,12 @@ export function proposalRowToProposal(row) {
             ...(frontmatter !== undefined ? { frontmatter } : {}),
         },
         ...(meta.review !== undefined ? { review: meta.review } : {}),
+        ...(typeof meta.confidence === "number" ? { confidence: meta.confidence } : {}),
+        ...(meta.gateDecision !== undefined ? { gateDecision: meta.gateDecision } : {}),
+        ...(typeof meta.backupContent === "string" ? { backupContent: meta.backupContent } : {}),
+        ...(typeof meta.eligibilitySource === "string"
+            ? { eligibilitySource: meta.eligibilitySource }
+            : {}),
     };
 }
 /**
@@ -542,6 +592,14 @@ export function proposalToRowValues(proposal, stashDir) {
         metaObj.sourceRun = proposal.sourceRun;
     if (proposal.review !== undefined)
         metaObj.review = proposal.review;
+    if (proposal.confidence !== undefined)
+        metaObj.confidence = proposal.confidence;
+    if (proposal.gateDecision !== undefined)
+        metaObj.gateDecision = proposal.gateDecision;
+    if (proposal.backupContent !== undefined)
+        metaObj.backupContent = proposal.backupContent;
+    if (proposal.eligibilitySource !== undefined)
+        metaObj.eligibilitySource = proposal.eligibilitySource;
     return {
         id: proposal.id,
         stash_dir: stashDir,
@@ -656,7 +714,10 @@ export function upsertProposal(db, proposal, stashDir) {
 }
 /**
  * List proposals, optionally filtered by stashDir, status, and/or ref.
- * Results are sorted by created_at ASC to match the existing listProposals() behaviour.
+ *
+ * Results are ordered by `created_at ASC` (matching the historical
+ * `listProposals()` sort), with `rowid` as a deterministic tiebreak so two
+ * proposals created in the same millisecond list in insertion order.
  */
 export function listStateProposals(db, options = {}) {
     const conditions = [];
@@ -677,21 +738,98 @@ export function listStateProposals(db, options = {}) {
     const rows = db
         .prepare(`SELECT id, stash_dir, ref, status, source, created_at, updated_at,
               content, frontmatter_json, metadata_json
-       FROM proposals ${where} ORDER BY created_at ASC`)
+       FROM proposals ${where} ORDER BY created_at ASC, rowid ASC`)
         .all(...params);
     return rows.map(proposalRowToProposal);
 }
 /**
- * Look up a single proposal by id. Returns undefined when not found.
+ * Look up a single proposal by id, optionally scoped to one stash root.
+ * Returns undefined when not found.
  */
-export function getStateProposal(db, id) {
-    const row = db
-        .prepare(`SELECT id, stash_dir, ref, status, source, created_at, updated_at,
+export function getStateProposal(db, id, stashDir) {
+    const sql = `SELECT id, stash_dir, ref, status, source, created_at, updated_at,
               content, frontmatter_json, metadata_json
-       FROM proposals WHERE id = ?`)
-        .get(id);
+       FROM proposals WHERE id = ?${stashDir ? " AND stash_dir = ?" : ""}`;
+    const row = (stashDir ? db.prepare(sql).get(id, stashDir) : db.prepare(sql).get(id));
     return row ? proposalRowToProposal(row) : undefined;
 }
+/**
+ * Find PENDING proposal ids in one stash whose id starts with `idPrefix`.
+ * Backs the UUID-prefix form of `akm proposal show/accept/... <prefix>` —
+ * prefix resolution is deliberately scoped to the live (pending) queue,
+ * mirroring the historical behaviour of scanning only the live directory.
+ *
+ * `%` / `_` / `\` in the prefix are escaped so the LIKE pattern is literal.
+ */
+export function listStateProposalIdsByPrefix(db, stashDir, idPrefix) {
+    const escaped = idPrefix.replace(/[\\%_]/g, (ch) => `\\${ch}`);
+    const rows = db
+        .prepare(`SELECT id FROM proposals
+       WHERE stash_dir = ? AND status = 'pending' AND id LIKE ? ESCAPE '\\'
+       ORDER BY id ASC`)
+        .all(stashDir, `${escaped}%`);
+    return rows.map((r) => r.id);
+}
+/**
+ * Whether the legacy filesystem proposal import has already run for `stashDir`.
+ * See migration 005 (`proposal_fs_imports`).
+ */
+export function hasImportedFsProposals(db, stashDir) {
+    // Drivers disagree on the no-row sentinel (bun:sqlite → null,
+    // better-sqlite3 → undefined) — Boolean() covers both.
+    return Boolean(db.prepare("SELECT 1 FROM proposal_fs_imports WHERE stash_dir = ?").get(stashDir));
+}
+/**
+ * Record that the legacy filesystem proposal import completed for `stashDir`
+ * so subsequent invocations skip the directory walk. INSERT OR REPLACE keeps
+ * the call idempotent.
+ */
+export function recordFsProposalsImport(db, stashDir, importedCount) {
+    db.prepare("INSERT OR REPLACE INTO proposal_fs_imports (stash_dir, imported_at, imported_count) VALUES (?, ?, ?)").run(stashDir, new Date().toISOString(), importedCount);
+}
+/**
+ * Insert a proposal row ONLY when the id is not already present (used by the
+ * legacy filesystem import so re-runs never clobber rows that have since been
+ * mutated through the canonical store). Returns true when a row was inserted.
+ */
+export function insertProposalIfAbsent(db, proposal, stashDir) {
+    const v = proposalToRowValues(proposal, stashDir);
+    const result = db
+        .prepare(`
+      INSERT OR IGNORE INTO proposals
+        (id, stash_dir, ref, status, source, created_at, updated_at, content, frontmatter_json, metadata_json)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `)
+        .run(v.id, v.stash_dir, v.ref, v.status, v.source, v.created_at, v.updated_at, v.content, v.frontmatter_json, v.metadata_json);
+    const changes = result.changes ?? 0;
+    return Number(changes) > 0;
+}
+/**
+ * Run `fn` inside a `BEGIN IMMEDIATE` transaction.
+ *
+ * `db.transaction()` is DEFERRED by default on both Bun and better-sqlite3,
+ * which means two writers can both perform stale preflight reads and only race
+ * when they finally attempt the write. Proposal creation and queue mutation
+ * need the write lock BEFORE those reads so concurrent processes serialize on
+ * the live queue state rather than clobbering each other.
+ */
+export function withImmediateTransaction(db, fn) {
+    db.exec("BEGIN IMMEDIATE");
+    try {
+        const result = fn();
+        db.exec("COMMIT");
+        return result;
+    }
+    catch (err) {
+        try {
+            db.exec("ROLLBACK");
+        }
+        catch {
+            // Ignore rollback failures so the original error is preserved.
+        }
+        throw err;
+    }
+}
 // ── task_history table helpers ───────────────────────────────────────────────
 /**
  * Upsert a task history row.

package/dist/indexer/db/db.js

@@ -28,7 +28,7 @@ export function openDatabase(dbPath, options) {
     }
     const db = openSqlite(resolvedPath);
     db.exec("PRAGMA journal_mode = WAL");
-    db.exec("PRAGMA busy_timeout = 5000");
+    db.exec("PRAGMA busy_timeout = 30000");
     db.exec("PRAGMA foreign_keys = ON");
     // Try to load sqlite-vec extension
     loadVecExtension(db);
@@ -69,7 +69,7 @@ export function openExistingDatabase(dbPath) {
     const resolvedPath = dbPath ?? getDbPath();
     const db = openSqlite(resolvedPath);
     db.exec("PRAGMA journal_mode = WAL");
-    db.exec("PRAGMA busy_timeout = 5000");
+    db.exec("PRAGMA busy_timeout = 30000");
     db.exec("PRAGMA foreign_keys = ON");
     // Existing-DB callers must not mutate schema or embedding metadata on open,
     // but some paths still need write access to usage_events and other tables.
@@ -1262,6 +1262,19 @@ export function getEntryIdByFilePath(db, filePath) {
     const row = db.prepare("SELECT id FROM entries WHERE file_path = ? LIMIT 1").get(filePath);
     return row?.id;
 }
+/**
+ * Set of every non-empty `entries.file_path` currently indexed (across all
+ * stashes/sources). Used by staleness detection to spot files that exist on
+ * disk but were never indexed — a clock-independent signal for newly-added
+ * assets that an mtime-vs-builtAt comparison can miss when the two clocks
+ * (filesystem vs wall-clock) are skewed within the same millisecond.
+ */
+export function getIndexedFilePaths(db) {
+    const rows = db
+        .prepare("SELECT DISTINCT file_path FROM entries WHERE file_path IS NOT NULL AND file_path <> ''")
+        .all();
+    return new Set(rows.map((r) => r.file_path));
+}
 /**
  * Resolve a single `entries.file_path` by primary key, or `undefined` if no
  * row matches.
@@ -1477,25 +1490,98 @@ export function computeBodyHash(body) {
     return sha256Hex(body);
 }
 /**
- * Count search and show events for the given entry refs.
- * Returns a Map<ref, count> with only refs that have at least one event.
- * Used by the improve loop to find high-retrieval assets without feedback.
+ * Reduce a ref to its bare `type:name` form, dropping any `origin//` prefix.
+ *
+ * usage_events store entry_ref inconsistently: search/show writers persist
+ * whatever ref the result carried, which is sometimes stash-prefixed
+ * (`origin//type:name`) and sometimes bare (`type:name`). Retrieval counting
+ * keys on the bare form so both spellings of the same asset collapse together.
+ *
+ * Returns the bare form, or the original string when it cannot be parsed (best
+ * effort — never throws so a malformed stored ref can't break counting).
+ */
+function bareRef(ref) {
+    try {
+        const parsed = parseAssetRef(ref);
+        return `${parsed.type}:${parsed.name}`;
+    }
+    catch {
+        return ref;
+    }
+}
+/**
+ * Count retrieval events for the given entry refs.
+ *
+ * Counts `search`, `show`, and `curate` usage events. Returns a
+ * Map<inputRef, count> keyed by the *input* ref strings (only those with at
+ * least one matching event appear). Used by the improve loop to find
+ * high-retrieval assets without feedback.
+ *
+ * Matching is normalization-aware: each stored `entry_ref` is reduced to its
+ * bare `type:name` form before comparison, so a stash-prefixed stored ref
+ * (`origin//type:name`) still matches a bare input ref (`type:name`) and vice
+ * versa. Previously the raw `entry_ref IN (...)` comparison silently dropped
+ * roughly half the signal whenever the two spellings disagreed.
+ *
+ * `curate` events are included: their per-item rows are written with
+ * entry_ref populated (see logCurateEvent), so curation is a real retrieval
+ * signal here. Legacy summary-only curate rows with a NULL entry_ref simply
+ * contribute nothing.
  */
 export function getRetrievalCounts(db, refs) {
     if (refs.length === 0)
         return new Map();
-    const result = new Map();
+    // Map each distinct bare form back to the input ref(s) that produced it so we
+    // can re-key DB results (grouped by bare form) onto the caller's ref strings.
+    const bareToInputs = new Map();
+    for (const ref of refs) {
+        const bare = bareRef(ref);
+        const existing = bareToInputs.get(bare);
+        if (existing)
+            existing.push(ref);
+        else
+            bareToInputs.set(bare, [ref]);
+    }
+    const bareForms = [...bareToInputs.keys()];
+    // Accumulate counts per bare form across chunks before re-keying.
+    const countsByBare = new Map();
     // Chunk to stay within SQLITE_MAX_VARIABLE_NUMBER (same pattern as getUtilityScoresByIds).
-    for (let i = 0; i < refs.length; i += SQLITE_CHUNK_SIZE) {
-        const chunk = refs.slice(i, i + SQLITE_CHUNK_SIZE);
+    for (let i = 0; i < bareForms.length; i += SQLITE_CHUNK_SIZE) {
+        const chunk = bareForms.slice(i, i + SQLITE_CHUNK_SIZE);
         const placeholders = chunk.map(() => "?").join(", ");
+        // Normalize the stored entry_ref to its bare form inside SQL by stripping
+        // everything up to and including the last `//` separator. SQLite has no
+        // rfind, but stored origins never themselves contain `//`, so a stash ref
+        // has exactly one `//` and `substr(... instr ...)` is exact; bare refs have
+        // no `//` and pass through unchanged.
         const rows = db
-            .prepare(`SELECT entry_ref, COUNT(*) AS cnt FROM usage_events
-         WHERE event_type IN ('search','show') AND entry_ref IN (${placeholders})
-         GROUP BY entry_ref`)
+            .prepare(`SELECT
+           CASE
+             WHEN instr(entry_ref, '//') > 0
+               THEN substr(entry_ref, instr(entry_ref, '//') + 2)
+             ELSE entry_ref
+           END AS bare_ref,
+           COUNT(*) AS cnt
+         FROM usage_events
+         WHERE event_type IN ('search','show','curate')
+           AND entry_ref IS NOT NULL
+           AND CASE
+                 WHEN instr(entry_ref, '//') > 0
+                   THEN substr(entry_ref, instr(entry_ref, '//') + 2)
+                 ELSE entry_ref
+               END IN (${placeholders})
+         GROUP BY bare_ref`)
             .all(...chunk);
-        for (const r of rows)
-            result.set(r.entry_ref, r.cnt);
+        for (const r of rows) {
+            countsByBare.set(r.bare_ref, (countsByBare.get(r.bare_ref) ?? 0) + r.cnt);
+        }
+    }
+    // Re-key bare-form counts onto every input ref that maps to that bare form.
+    const result = new Map();
+    for (const [bare, count] of countsByBare) {
+        for (const input of bareToInputs.get(bare) ?? []) {
+            result.set(input, count);
+        }
     }
     return result;
 }

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;
+    }
+}