akm-cli 0.9.0-beta.52 → 0.9.0-beta.54

package/dist/indexer/ensure-index.js

@@ -2,23 +2,29 @@
 // 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/.
 /**
- * Auto-index: silently run an incremental `akm index` when the local index
- * is stale or absent, so that `search`, `show`, and `feedback` always operate
- * against current on-disk state without requiring the user to manually run
- * `akm index` first.
+ * Auto-index bootstrap: silently build the local index inline when it cannot
+ * serve the caller's stash at all (missing DB, no `entries` table, zero rows,
+ * or built for a different stash), so `search`, `show`, and `feedback` work
+ * on first use without a manual `akm index`.
  *
- * This replaces the old filesystem fallbacks that were scattered across
- * `searchLocal()` and `show.ts`, centralizing the "indexed yet?" gap handling
- * behind a single entry point.
+ * Content FRESHNESS is intentionally not this module's job on the read path.
+ * Writers maintain the index (`indexWrittenAssets` for `remember`/extract
+ * session assets; the mutation commands run `akmIndex()` themselves), and the
+ * improve cron / explicit `akm index` do full refreshes. Reads serve whatever
+ * populated index exists. The previous design — a staleness walk plus a
+ * detached background reindex per read — made every read on an actively
+ * written stash spawn a writer that the read's own telemetry then queued
+ * behind (see docs/design/read-path-reindex-contention-findings.md).
+ *
+ * `mode: "blocking"` (improve) still checks staleness and rebuilds inline,
+ * because its planning logic needs a current `entries` table in-process.
  */
-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 { getDataDir, getDbPath } from "../core/paths.js";
+import { getDbPath } from "../core/paths.js";
 import { warn } from "../core/warn.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 [];
@@ -138,12 +144,9 @@ export function isIndexStale(stashDir) {
  * 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.
+ * content-stale, so read paths serve it as-is. 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 those cases must rebuild inline.
  */
 function indexCanServeStash(stashDir) {
     const dbPath = getDbPath();
@@ -174,43 +177,6 @@ function indexCanServeStash(stashDir) {
             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");
@@ -219,53 +185,31 @@ async function runInlineReindex(stashDir) {
     }
     catch (error) {
         warn("Auto-index failed, proceeding with existing index:", error instanceof Error ? error.message : String(error));
-        return true;
+        return false;
     }
 }
 /**
- * Ensure the local index exists and is fresh enough for the caller's needs.
+ * Ensure the local index exists and can serve the caller.
  *
- * 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.
+ * Default mode is `background` — the read-path contract (`search`, `show`,
+ * `feedback`): a populated index built for this stash is served as-is (its
+ * freshness is the writers' job, see module doc); an unusable index rebuilds
+ * inline, 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.
+ * `mode: "blocking"` additionally treats content-staleness as a rebuild
+ * trigger and waits for it. Use this for callers like `improve` whose
+ * planning logic depends on a current `entries` table in the same process.
  *
- * Returns `true` if an index run was attempted.
+ * Returns `true` only when an inline index run succeeds.
+ * A rebuild attempt that fails (throws) resolves to `false`.
  */
 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") {
+    if (options.mode === "blocking") {
+        if (!isIndexStale(stashDir))
+            return false;
         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;
-    }
+    if (indexCanServeStash(stashDir))
+        return false;
+    return runInlineReindex(stashDir);
 }

package/dist/indexer/index-writer-lock.js

@@ -7,6 +7,7 @@ import { probeLock, releaseLock, releaseLockIfOwned, tryAcquireLockSync } from "
 import { getDbPath, getIndexWriterLockPath } from "../core/paths.js";
 const INDEX_WRITER_LOCK_STALE_AFTER_MS = 12 * 60 * 60 * 1000;
 const INDEX_WRITER_WAIT_MS = 100;
+const DEFAULT_INDEX_WRITER_MAX_WAIT_MS = 10 * 60 * 1000;
 const heldLocks = new Map();
 function buildPayload(purpose, pid = process.pid) {
     return JSON.stringify({
@@ -46,16 +47,11 @@ function retainHeldLock(lockPath) {
     heldLocks.set(lockPath, { depth: 1, exitHandler });
     return { lockPath, release: () => releaseHeldLock(lockPath) };
 }
-function detachHeldLock(lockPath) {
-    const held = heldLocks.get(lockPath);
-    if (!held)
-        return;
-    heldLocks.delete(lockPath);
-    process.off("exit", held.exitHandler);
-}
 export async function acquireIndexWriterLease(options) {
     const mode = options.mode ?? "wait";
     const lockPath = getIndexWriterLockPath();
+    const startedAt = Date.now();
+    const maxWaitMs = options.maxWaitMs ?? DEFAULT_INDEX_WRITER_MAX_WAIT_MS;
     fs.mkdirSync(path.dirname(lockPath), { recursive: true });
     if (heldLocks.has(lockPath)) {
         return retainHeldLock(lockPath);
@@ -75,6 +71,12 @@ export async function acquireIndexWriterLease(options) {
         }
         if (mode === "try")
             return undefined;
+        // Held by another live process. Time out only *after* a real acquisition
+        // attempt, so a caller with maxWaitMs:0 still gets one chance at a free lock
+        // instead of throwing before it ever tries.
+        if (maxWaitMs >= 0 && Date.now() - startedAt >= maxWaitMs) {
+            throw new Error(`timed out waiting for index writer lease for ${options.purpose}`);
+        }
         await delay(INDEX_WRITER_WAIT_MS);
     }
 }
@@ -90,10 +92,6 @@ export async function withIndexWriterLease(options, run) {
         lease.release();
     }
 }
-export function handoffIndexWriterLeaseToPid(lease, pid, purpose) {
-    fs.writeFileSync(lease.lockPath, buildPayload(purpose, pid), "utf8");
-    detachHeldLock(lease.lockPath);
-}
 export function probeIndexWriterLease() {
     return probeLock(getIndexWriterLockPath(), { staleAfterMs: INDEX_WRITER_LOCK_STALE_AFTER_MS });
 }

package/dist/indexer/index-written-assets.js

@@ -0,0 +1,105 @@
+// 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/.
+/**
+ * Write-path indexing: targeted single-file index updates for asset writers.
+ *
+ * The index is maintained eagerly by every first-class mutation command
+ * (`source add`, `wiki`, `workflow`, `setup` all run `akmIndex()` after
+ * writing). The memory write paths — `akm remember` / `writeMarkdownAsset`
+ * and extract's session assets — historically did not, which is why reads
+ * used to compensate with stale-triggered background reindexes (the
+ * lock-contention footgun removed alongside this module's introduction; see
+ * docs/design/read-path-reindex-contention-findings.md §7).
+ *
+ * This is NOT a general reindex. It upserts exactly the files the caller just
+ * wrote: frontmatter/metadata via the shared matcher pipeline, the `entries`
+ * row, and an incremental FTS refresh. Embeddings, index-time LLM passes,
+ * graph extraction, `builtAt`, and the per-dir walk cache are all deliberately
+ * untouched — the next full run heals them (the opportunistic-recovery
+ * strategy of docs/technical/index-consistency-adr.md).
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { getDbPath } from "../core/paths.js";
+import { warnVerbose } from "../core/warn.js";
+import { closeDatabase, getEntryCount, openExistingDatabase, rebuildFts, upsertEntry } from "./db/db.js";
+import { generateMetadataFlat } from "./passes/metadata.js";
+import { buildSearchText } from "./search/search-fields.js";
+/**
+ * Busy-timeout (ms) for write-path index upserts. A real write — unlike the
+ * 250ms telemetry inserts — but it must not hang `akm remember` for the full
+ * default 30s behind a running full reindex. When it times out, the upsert is
+ * skipped and the asset becomes searchable after that reindex instead.
+ */
+export const WRITE_PATH_INDEX_BUSY_TIMEOUT_MS = 5_000;
+/**
+ * Index the given just-written asset files into the existing local index.
+ *
+ * FAIL-OPEN at every step: any error (index.db absent, empty, locked past the
+ * busy timeout, unparseable file) is reduced to a verbose-only warning and the
+ * write command succeeds untouched. The degraded outcome is exactly the
+ * pre-write-path-indexing behavior: the asset appears after the next full
+ * `akm index` / improve-cron run.
+ *
+ * An absent or empty index is skipped on purpose — bootstrap belongs to the
+ * first read (`ensureIndex`) or an explicit `akm index`, which also cover
+ * embeddings and the other passes this fast path skips.
+ */
+export async function indexWrittenAssets(stashDir, filePaths) {
+    try {
+        const dbPath = getDbPath();
+        if (!fs.existsSync(dbPath))
+            return;
+        // The full walk never descends into dot-directories (they hold state like
+        // `.meta/`, `.stash.json`), and `shouldIndexStashFile` relies on the walker
+        // for that — mirror it here so this fast path indexes exactly what a full
+        // run would.
+        const files = filePaths.filter((f) => {
+            if (!fs.existsSync(f))
+                return false;
+            const rel = path.relative(stashDir, f);
+            return !rel.split(/[\\/]+/).some((segment) => segment.startsWith("."));
+        });
+        if (files.length === 0)
+            return;
+        // Generate metadata BEFORE opening the DB so the write window stays
+        // short. One call per file keeps the entry↔path pairing exact.
+        const pairs = [];
+        for (const file of files) {
+            const generated = await generateMetadataFlat(stashDir, [file]);
+            const entry = generated.entries[0];
+            // Workflows carry a side-table document upsert this fast path doesn't
+            // do; no current caller writes them, but guard so one never lands
+            // half-indexed.
+            if (entry && entry.type !== "workflow")
+                pairs.push({ file, entry });
+        }
+        if (pairs.length === 0)
+            return;
+        const db = openExistingDatabase(dbPath);
+        try {
+            db.exec(`PRAGMA busy_timeout = ${WRITE_PATH_INDEX_BUSY_TIMEOUT_MS}`);
+            if (getEntryCount(db) === 0)
+                return;
+            for (const { file, entry } of pairs) {
+                const entryKey = `${stashDir}:${entry.type}:${entry.name}`;
+                let entryWithSize = entry;
+                try {
+                    entryWithSize = { ...entry, fileSize: fs.statSync(file).size };
+                }
+                catch {
+                    // stat raced a delete — index without the size, like the full walk does.
+                }
+                upsertEntry(db, entryKey, path.dirname(file), file, stashDir, entryWithSize, buildSearchText(entry));
+            }
+            rebuildFts(db, { incremental: true });
+        }
+        finally {
+            closeDatabase(db);
+        }
+    }
+    catch (error) {
+        warnVerbose("Write-path index update skipped (asset appears after the next full index):", error instanceof Error ? error.message : String(error));
+    }
+}

package/dist/indexer/indexer.js

@@ -118,7 +118,7 @@ async function runWalkPhase(ctx) {
     ctx.timing.tWalkEnd = Date.now();
     throwIfAborted(signal);
     // LLM enrichment for directories that need it
-    await enhanceDirsWithLlm(db, config, dirsNeedingLlm, onProgress, signal, true, reEnrich);
+    await enhanceDirsWithLlm(db, config, dirsNeedingLlm, onProgress, signal, reEnrich);
     onProgress({
         phase: "llm",
         message: resolveIndexPassLLM("enrichment", config)
@@ -226,7 +226,19 @@ function runCleanPass(db, dryRun) {
     };
 }
 // ── Indexer ──────────────────────────────────────────────────────────────────
+// ── Test seam ────────────────────────────────────────────────────────────────
+// Swap-and-restore override. Inert in production; only tests call the setter.
+let akmIndexOverride;
+/** TEST-ONLY. Swap the implementation of `akmIndex`; pass undefined to restore. */
+export function _setAkmIndexForTests(fake) {
+    akmIndexOverride = fake;
+}
 export async function akmIndex(options) {
+    if (akmIndexOverride)
+        return akmIndexOverride(options);
+    return akmIndexReal(options);
+}
+async function akmIndexReal(options) {
     return withIndexWriterLease({ purpose: "akm-index", signal: options?.signal }, async () => {
         const stashDir = options?.stashDir || resolveStashDir();
         const onProgress = options?.onProgress ?? (() => { });
@@ -640,7 +652,7 @@ async function indexEntries(db, allSourceEntries, isIncremental, builtAtMs, hadR
     insertTransaction();
     return { scannedDirs, skippedDirs, generatedCount, warnings, dirsNeedingLlm };
 }
-async function enhanceDirsWithLlm(db, config, dirsNeedingLlm, onProgress, signal, _enrich = false, reEnrich = false) {
+async function enhanceDirsWithLlm(db, config, dirsNeedingLlm, onProgress, signal, reEnrich = false) {
     // Resolve per-pass LLM config via the unified shim. Returns undefined when
     // either no `akm.llm` is configured or the user opted this pass out via
     // `index.enrichment.llm = false`. (#208)
@@ -977,7 +989,7 @@ function resolveIndexedFiles(dirPath, files, stash) {
     for (const entry of stash.entries) {
         const entryPath = entry.filename
             ? path.join(dirPath, entry.filename)
-            : matchEntryToFile(entry.name, fileBasenameMap, files);
+            : matchEntryToFile(entry.name, fileBasenameMap);
         if (entryPath)
             resolved.add(entryPath);
     }
@@ -1096,7 +1108,7 @@ export function buildFileBasenameMap(files) {
  *      try matching the last segment
  *   3. No implicit file fallback: ambiguous legacy entries are skipped
  */
-export function matchEntryToFile(entryName, fileMap, _files) {
+export function matchEntryToFile(entryName, fileMap) {
     // Exact match on entry name
     const exact = fileMap.get(entryName);
     if (exact)

package/dist/indexer/passes/metadata.js

@@ -191,6 +191,15 @@ export function validateStashEntry(entry) {
     const contradictedBy = normalizeNonEmptyStringList(e.contradictedBy);
     if (contradictedBy)
         result.contradictedBy = contradictedBy;
+    // R5 — consolidation provenance fields must survive the whitelist too, or
+    // stash.json-overridden merge products lose merge-following + generation
+    // counting in the collapse detector.
+    if (typeof e.generation === "number" && Number.isFinite(e.generation) && e.generation > 0) {
+        result.generation = Math.floor(e.generation);
+    }
+    const sourceRefs = normalizeNonEmptyStringList(e.sourceRefs);
+    if (sourceRefs)
+        result.sourceRefs = sourceRefs;
     const currentBeliefRefs = normalizeNonEmptyStringList(e.currentBeliefRefs);
     if (currentBeliefRefs)
         result.currentBeliefRefs = currentBeliefRefs;
@@ -342,6 +351,17 @@ export function applyCuratedFrontmatter(entry, fmData) {
     const contradictedBy = normalizeStringListOrUndefined(fmData.contradictedBy);
     if (contradictedBy)
         entry.contradictedBy = contradictedBy;
+    // R5 — consolidation provenance. `generation` (merge depth counter) and
+    // `source_refs` (merge/distill provenance pointers) are written by the
+    // improve pipeline; captured into the index so the collapse detector can
+    // count over-generation assets and follow merges without filesystem reads.
+    const generation = fmData.generation;
+    if (typeof generation === "number" && Number.isFinite(generation) && generation > 0) {
+        entry.generation = Math.floor(generation);
+    }
+    const sourceRefs = normalizeStringListOrUndefined(fmData.source_refs);
+    if (sourceRefs)
+        entry.sourceRefs = sourceRefs;
     const currentBeliefRefs = normalizeStringListOrUndefined(fmData.currentBeliefRefs);
     if (currentBeliefRefs)
         entry.currentBeliefRefs = currentBeliefRefs;

package/dist/indexer/read-preflight.js

@@ -0,0 +1,23 @@
+// 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 { ensureIndex } from "./ensure-index.js";
+import { resolveSourceEntries } from "./search/search-source.js";
+/** Resolve the active read sources using the same resolution rules as search/show. */
+export function resolveReadSources(overrideStashDir, existingConfig) {
+    const sources = resolveSourceEntries(overrideStashDir, existingConfig);
+    return { sources, primarySource: sources[0] };
+}
+/** Ensure the primary source index is readable for reads, when a primary exists. */
+export async function ensurePrimaryIndexForRead(primarySource) {
+    if (!primarySource?.path)
+        return false;
+    return ensureIndex(primarySource.path);
+}
+/**
+ * Convenience helper for callers that only need to ensure a read index from a
+ * configured stash path and default config.
+ */
+export async function ensurePrimaryIndexFromConfig(overrideStashDir, existingConfig) {
+    return ensurePrimaryIndexForRead(resolveReadSources(overrideStashDir, existingConfig).primarySource);
+}

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

@@ -29,6 +29,29 @@ import { applyRankingRules, combineSearchScores, normalizeFtsScores } from "./ra
 import { enrichSearchHit } from "./search-hit-enrichers.js";
 import { buildEditHint, findSourceForPath, isEditable } from "./search-source.js";
 import { deriveSemanticProviderFingerprint, getEffectiveSemanticStatus, isSemanticRuntimeReady, readSemanticStatus, } from "./semantic-status.js";
+/**
+ * Age past which search surfaces a "run akm index" hint. Reads serve the
+ * existing index as-is (freshness is the writers' job — `indexWrittenAssets`
+ * plus full runs), so on installs with no improve cron a hand-edited or
+ * git-pulled file stays invisible until someone reindexes. The hint makes that
+ * actionable without re-introducing read-triggered reindexing.
+ */
+const STALE_INDEX_HINT_MS = 7 * 24 * 60 * 60 * 1000;
+function buildStaleIndexHint(db) {
+    try {
+        const builtAt = getMeta(db, "builtAt");
+        if (!builtAt)
+            return undefined;
+        const ageMs = Date.now() - new Date(builtAt).getTime();
+        if (!Number.isFinite(ageMs) || ageMs < STALE_INDEX_HINT_MS)
+            return undefined;
+        const days = Math.floor(ageMs / (24 * 60 * 60 * 1000));
+        return `Search index was last built ${days} day(s) ago. Files added or edited outside akm since then are not searchable — run 'akm index' to refresh.`;
+    }
+    catch {
+        return undefined;
+    }
+}
 export function buildLocalAction(type, ref, registry = defaultRendererRegistry) {
     return buildActionFromContributors({ type, ref }, defaultActionContributors(registry)) ?? `akm show ${ref}`;
 }
@@ -95,7 +118,9 @@ export async function searchLocal(input) {
     if (config.semanticSearchMode === "auto" && semanticStatus === "blocked") {
         warnings.push("Semantic search is currently blocked. Using keyword search until the semantic backend is healthy again.");
     }
-    // Auto-index when stale so the DB is always current before querying.
+    // Bootstrap-only: builds the index inline when it cannot serve this stash.
+    // Content freshness is the writers' job (indexWrittenAssets + full runs);
+    // reads serve the existing index as-is.
     await ensureIndex(stashDir);
     const dbPath = getDbPath();
     if (!fs.existsSync(dbPath)) {
@@ -117,6 +142,9 @@ export async function searchLocal(input) {
                 mode: "keyword",
             };
         }
+        const staleHint = buildStaleIndexHint(db);
+        if (staleHint)
+            warnings.push(staleHint);
         const { hits, embedMs, rankMs } = await searchDatabase(db, query, searchType, limit, stashDir, allSourceDirs, config, sources, rendererRegistry, filters, includeProposed, beliefFilter, restrictToSources, includeExcludedTypes, disableProjectContext, disableScopedUtility);
         return {
             hits,

package/dist/indexer/search/ranking-contributors.js

@@ -17,6 +17,14 @@ const TYPE_BOOST = {
 const MAX_BOOST_SUM = 3.0;
 const UTILITY_WEIGHT = 0.5;
 const UTILITY_MAX_BOOST = 1.5;
+/**
+ * R2 (docs/design/improve-self-learning-analysis.md) — weight of the improve
+ * loop's `asset_salience.rank_score` in user-facing ranking. Bounded well
+ * below the utility boost so the composed signal refines, never dominates,
+ * lexical/semantic relevance. rank_score ∈ [0,1] → boost ∈ [1, 1.2].
+ */
+const SALIENCE_WEIGHT = 0.2;
+const SALIENCE_MAX_BOOST = 1.2;
 /**
  * Phase 2A / Rec 5: default recency half-life (days) used when no
  * `utilityDecayConfig` is supplied to the ranking pipeline. Matches the
@@ -334,7 +342,31 @@ export const defaultRankingContributors = [
     pinnedFactRankingContributor,
     projectContextRankingContributor,
 ];
-export const defaultUtilityRankingContributors = [utilityRankingContributor];
+/**
+ * R2 — compose the improve loop's salience core into user-facing ranking.
+ *
+ * `asset_salience.rank_score` (encoding + outcome + retrieval projection,
+ * maintained every improve run) previously drove only improve's INTERNAL
+ * maintenance selection — the "better assets surface more" loop ran solely
+ * through the utility EMA. This bounded multiplicative boost closes the outer
+ * loop: usage/outcome-reinforced assets rank higher in `search`/`curate`.
+ */
+const salienceRankingContributor = {
+    name: "salience-ranking",
+    appliesTo(item, ctx) {
+        const rank = ctx.salienceRankScores?.get(item.id);
+        return rank !== undefined && rank > 0;
+    },
+    apply(item, ctx) {
+        const rank = ctx.salienceRankScores?.get(item.id) ?? 0;
+        const rawBoost = 1 + Math.min(1, Math.max(0, rank)) * SALIENCE_WEIGHT;
+        item.score *= Math.min(rawBoost, SALIENCE_MAX_BOOST);
+    },
+};
+export const defaultUtilityRankingContributors = [
+    utilityRankingContributor,
+    salienceRankingContributor,
+];
 export function applyScoreContributors(item, ctx, contributors = defaultRankingContributors) {
     let boostSum = 0;
     for (const contributor of contributors) {

package/dist/indexer/search/ranking.js

@@ -1,8 +1,68 @@
 // 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 fs from "node:fs";
+import { makeAssetRef } from "../../core/asset/asset-ref.js";
+import { getStateDbPath } from "../../core/state-db.js";
+import { openDatabase } from "../../storage/database.js";
 import { getUtilityScoresByIds } from "../db/db.js";
 import { applyScoreContributors, applyUtilityContributors } from "./ranking-contributors.js";
+/**
+ * R2 — best-effort load of `asset_salience.rank_score` from state.db for the
+ * ranked items. Fail-open: any error (state.db locked by a concurrent improve
+ * run, missing table, unreadable path) returns an empty map, which makes the
+ * salience contributor a no-op — byte-identical to pre-R2 ranking.
+ *
+ * Deliberately NOT `openStateDatabase()`: that helper runs migrations and sets
+ * a 30 s busy timeout — too heavy for a search hot path. This opens read-only,
+ * never creates or migrates state.db (missing file / missing table = empty
+ * map), and caps lock waits at 250 ms so a concurrent improve run can only
+ * ever cost the search a quarter second, not a stall.
+ */
+export function loadSalienceRankScores(items) {
+    const result = new Map();
+    if (items.length === 0)
+        return result;
+    try {
+        const dbPath = getStateDbPath();
+        if (!fs.existsSync(dbPath))
+            return result; // improve loop has never run here
+        const idByRef = new Map();
+        for (const item of items) {
+            idByRef.set(makeAssetRef(item.entry.type, item.entry.name), item.id);
+        }
+        const stateDb = openDatabase(dbPath, { readonly: true });
+        try {
+            try {
+                stateDb.exec("PRAGMA busy_timeout = 250");
+            }
+            catch {
+                // pragma failure on a readonly handle is fine — default timeout applies
+            }
+            const refs = [...idByRef.keys()];
+            const CHUNK = 500;
+            for (let i = 0; i < refs.length; i += CHUNK) {
+                const chunk = refs.slice(i, i + CHUNK);
+                const placeholders = chunk.map(() => "?").join(",");
+                const rows = stateDb
+                    .prepare(`SELECT asset_ref, rank_score FROM asset_salience WHERE asset_ref IN (${placeholders})`)
+                    .all(...chunk);
+                for (const row of rows) {
+                    const id = idByRef.get(row.asset_ref);
+                    if (id !== undefined)
+                        result.set(id, row.rank_score);
+                }
+            }
+        }
+        finally {
+            stateDb.close();
+        }
+    }
+    catch {
+        // Fail open — search must never break because state.db is unavailable.
+    }
+    return result;
+}
 export function normalizeFtsScores(results) {
     const ftsScoreMap = new Map();
     if (results.length === 0)
@@ -71,12 +131,18 @@ export function applyRankingRules(options) {
         applyScoreContributors(item, rankingContext);
     }
     const { global: utilScoresMap, scoped: scopedUtilScoresMap } = getUtilityScoresByIds(options.db, options.items.map((item) => item.id), options.scopeKey);
+    // R2 — compose the improve loop's salience into user-facing ranking.
+    // undefined = load from state.db (default); null = explicitly disabled.
+    const salienceRankScores = options.salienceRankScores === null
+        ? new Map()
+        : (options.salienceRankScores ?? loadSalienceRankScores(options.items));
     const utilityContext = {
         ...rankingContext,
         utilityScores: utilScoresMap,
         scopedUtilityScores: scopedUtilScoresMap,
         utilityDecayConfig: options.utilityDecayConfig,
         positiveFeedbackCounts: options.positiveFeedbackCounts,
+        salienceRankScores,
     };
     for (const item of options.items) {
         applyUtilityContributors(item, utilityContext);

package/dist/indexer/search/search-fields.js

@@ -11,6 +11,12 @@
  *  - hints: searchHints + examples + usage + intent fields
  *  - content: TOC headings (lowest-weight catch-all)
  */
+// NOTE (R5): the collapse detector's frozen canary queries are built from the
+// same surface this function indexes (name tokens / tags / description) and
+// scored via FTS against it. Changing what buildSearchFields includes shifts
+// the detector's recall baseline for ALL existing canary sets — coordinate
+// with src/commands/improve/collapse-detector.ts (buildCanaryQuery) and expect
+// operators to re-mint via `akm improve canary --refresh` after such a change.
 export function buildSearchFields(entry) {
     const name = entry.name.replace(/[-_]/g, " ").toLowerCase();
     const description = (entry.description ?? "").toLowerCase();