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

package/dist/core/state-db.js

@@ -472,19 +472,20 @@ export function insertProposalIfAbsent(db, proposal, stashDir) {
 /**
  * Errors `BEGIN IMMEDIATE` can throw under concurrent-writer contention that are
  * transient (the statement did NOT start a usable transaction) and safe to
- * retry after clearing any phantom transaction state:
+ * retry:
  *   - "database is locked" / SQLITE_BUSY — another writer holds the lock.
- *   - "cannot start a transaction within a transaction" — bun:sqlite can leave
- *     the connection reporting an open transaction after a contended busy-wait
- *     on BEGIN IMMEDIATE (observed only under heavy parallel load, e.g. the
- *     proposal-queue worker race). A ROLLBACK clears that phantom state.
  * These are start-of-transaction failures only; an error thrown by `fn` is a
  * real failure and is NEVER retried.
+ *
+ * "cannot start a transaction within a transaction" is deliberately NOT
+ * retryable: it means a transaction is already open on this connection (a
+ * re-entrant call — handled by the entry guard in withImmediateTransaction),
+ * and "retrying" it with a ROLLBACK would destroy the caller's transaction
+ * (issue #686).
  */
 function isRetryableBeginError(err) {
     const msg = (err instanceof Error ? err.message : String(err)).toLowerCase();
-    return (msg.includes("within a transaction") ||
-        msg.includes("database is locked") ||
+    return (msg.includes("database is locked") ||
         msg.includes("database table is locked") ||
         // Phantom BEGIN (see below) — synthesized when BEGIN IMMEDIATE returns
         // without opening a transaction. Safe to retry: fn() has not run.
@@ -498,6 +499,16 @@ function sleepSyncMs(ms) {
     Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
 }
 export function withImmediateTransaction(db, fn) {
+    // Re-entrancy guard (issue #686): if a transaction is already open on this
+    // connection (e.g. a nested withImmediateTransaction call inside an outer
+    // frame's fn), join it — run fn directly with no BEGIN/COMMIT/ROLLBACK of
+    // our own. Without this, the nested BEGIN throws "cannot start a transaction
+    // within a transaction", which the old retry path answered with an
+    // unconditional ROLLBACK — destroying the OUTER transaction and leaving its
+    // COMMIT to fail with "cannot commit - no transaction is active".
+    if (db.inTransaction) {
+        return fn();
+    }
     let lastBeginErr;
     for (let attempt = 1; attempt <= WITH_IMMEDIATE_TX_MAX_ATTEMPTS; attempt++) {
         try {
@@ -515,13 +526,15 @@ export function withImmediateTransaction(db, fn) {
         catch (err) {
             lastBeginErr = err;
             if (isRetryableBeginError(err) && attempt < WITH_IMMEDIATE_TX_MAX_ATTEMPTS) {
-                // Clear any phantom/stale transaction left by the contended BEGIN, then
-                // retry with a small backoff so concurrent writers serialize cleanly.
-                try {
-                    db.exec("ROLLBACK");
-                }
-                catch {
-                    // No active transaction to roll back — fine.
+                // Only roll back a transaction we can see — never blind-ROLLBACK, since
+                // that could destroy a transaction this frame does not own.
+                if (db.inTransaction) {
+                    try {
+                        db.exec("ROLLBACK");
+                    }
+                    catch {
+                        // Transaction already gone — fine.
+                    }
                 }
                 sleepSyncMs(2 ** (attempt - 1));
                 continue;
@@ -530,15 +543,25 @@ export function withImmediateTransaction(db, fn) {
         }
         try {
             const result = fn();
+            if (!db.inTransaction) {
+                // The transaction we opened vanished while fn() ran (e.g. an
+                // auto-rollback or a stray ROLLBACK inside fn). fn's writes may have
+                // escaped serialization, so retrying is unsafe — fail loudly instead of
+                // letting COMMIT throw the opaque "cannot commit - no transaction is
+                // active" SQLiteError.
+                throw new Error("withImmediateTransaction invariant violated: transaction opened by BEGIN IMMEDIATE was no longer active after the transaction body ran; refusing to COMMIT (writes may have escaped serialization)");
+            }
             db.exec("COMMIT");
             return result;
         }
         catch (err) {
-            try {
-                db.exec("ROLLBACK");
-            }
-            catch {
-                // Ignore rollback failures so the original error is preserved.
+            if (db.inTransaction) {
+                try {
+                    db.exec("ROLLBACK");
+                }
+                catch {
+                    // Ignore rollback failures so the original error is preserved.
+                }
             }
             throw err; // a real error inside the transaction body — never retried.
         }
@@ -1252,3 +1275,107 @@ export function upsertBodyEmbeddings(db, entries) {
         }
     })();
 }
+/** Insert a freshly minted canary set (all rows active, one shared set id). */
+export function insertCanaries(db, canarySetId, canaries, now) {
+    if (canaries.length === 0)
+        return;
+    const ts = now ?? new Date().toISOString();
+    const stmt = db.prepare(`
+    INSERT INTO canary_queries (canary_set_id, anchor_ref, query, source, active, created_at)
+    VALUES (?, ?, ?, ?, 1, ?)
+  `);
+    db.transaction(() => {
+        for (const c of canaries) {
+            stmt.run(canarySetId, c.anchorRef, c.query, c.source ?? "auto", ts);
+        }
+    })();
+}
+/** Load the active canary set (empty array = never minted). */
+export function getActiveCanaries(db) {
+    // Scope to the NEWEST active set: if an interrupted refresh (or a bug) ever
+    // leaves two sets active, mixing their rows would silently corrupt the
+    // recall/entropy trend baselines. The newest set wins; stale-active rows are
+    // simply never returned.
+    return db
+        .prepare(`SELECT * FROM canary_queries
+       WHERE active = 1 AND canary_set_id = (
+         SELECT canary_set_id FROM canary_queries WHERE active = 1
+         ORDER BY created_at DESC, id DESC LIMIT 1
+       )
+       ORDER BY id`)
+        .all();
+}
+/** Load one canary set's rows by its exact set id (any active state), insertion order. */
+export function getCanariesBySetId(db, canarySetId) {
+    return db
+        .prepare(`SELECT * FROM canary_queries WHERE canary_set_id = ? ORDER BY id`)
+        .all(canarySetId);
+}
+/** List every distinct canary_set_id that still has active rows. */
+export function listActiveCanarySetIds(db) {
+    const rows = db.prepare(`SELECT DISTINCT canary_set_id FROM canary_queries WHERE active = 1`).all();
+    return rows.map((r) => r.canary_set_id);
+}
+/**
+ * Deactivate every canary row in a set. Rows are RETAINED (active = 0) so
+ * historical improve_cycle_metrics rows keyed on the old canary_set_id stay
+ * interpretable; only `akm improve canary --refresh` calls this.
+ */
+export function deactivateCanarySet(db, canarySetId) {
+    const result = db
+        .prepare(`UPDATE canary_queries SET active = 0 WHERE canary_set_id = ? AND active = 1`)
+        .run(canarySetId);
+    const changes = result.changes ?? 0;
+    return typeof changes === "bigint" ? Number(changes) : changes;
+}
+/** Persist one qualifying cycle's store-health snapshot. */
+export function insertCycleMetrics(db, row) {
+    db.prepare(`
+    INSERT INTO improve_cycle_metrics
+      (run_id, ts, pass, canary_set_id, mean_recall, mean_ndcg, mean_mrr,
+       canary_ranks_json, store_total, store_by_type_json, distinct_content_ratio,
+       mean_bigram_diversity, over_generation_count, accepted_actions,
+       merge_floor_violations, alerts_json)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+  `).run(row.run_id, row.ts, row.pass, row.canary_set_id, row.mean_recall, row.mean_ndcg, row.mean_mrr, row.canary_ranks_json, row.store_total, row.store_by_type_json, row.distinct_content_ratio, row.mean_bigram_diversity, row.over_generation_count, row.accepted_actions, row.merge_floor_violations, row.alerts_json);
+}
+/**
+ * Load the most recent cycle rows for one canary set, OLDEST-first (the alert
+ * evaluator's window order). Scoped by canary_set_id so trends never compare
+ * across canary re-mints.
+ */
+export function queryRecentCycleMetrics(db, canarySetId, limit) {
+    const rows = db
+        .prepare(`SELECT run_id, ts, pass, canary_set_id, mean_recall, mean_ndcg, mean_mrr,
+              canary_ranks_json, store_total, store_by_type_json, distinct_content_ratio,
+              mean_bigram_diversity, over_generation_count, accepted_actions,
+              merge_floor_violations, alerts_json
+       FROM improve_cycle_metrics WHERE canary_set_id = ?
+       ORDER BY ts DESC, id DESC LIMIT ?`)
+        .all(canarySetId, Math.max(0, limit));
+    return rows.reverse();
+}
+/** Load the single most recent cycle row across all canary sets (health surface). */
+export function getLatestCycleMetrics(db) {
+    const row = db
+        .prepare(`SELECT run_id, ts, pass, canary_set_id, mean_recall, mean_ndcg, mean_mrr,
+              canary_ranks_json, store_total, store_by_type_json, distinct_content_ratio,
+              mean_bigram_diversity, over_generation_count, accepted_actions,
+              merge_floor_violations, alerts_json
+       FROM improve_cycle_metrics ORDER BY ts DESC, id DESC LIMIT 1`)
+        .get();
+    return row == null ? undefined : row;
+}
+/**
+ * Delete cycle rows older than `retentionDays` (default 365 — owner-approved;
+ * a slow collapse needs a longer trend window than the 90-day events log).
+ * Returns the purged row count. canary_queries rows are never purged.
+ */
+export function purgeOldCycleMetrics(db, retentionDays = 365) {
+    if (!Number.isFinite(retentionDays) || retentionDays <= 0)
+        return 0;
+    const cutoff = new Date(Date.now() - retentionDays * 86_400_000).toISOString();
+    const result = db.prepare("DELETE FROM improve_cycle_metrics WHERE ts < ?").run(cutoff);
+    const changes = result.changes ?? 0;
+    return typeof changes === "bigint" ? Number(changes) : changes;
+}

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");
@@ -223,49 +189,26 @@ async function runInlineReindex(stashDir) {
     }
 }
 /**
- * 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.
  */
 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

@@ -46,13 +46,6 @@ 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();
@@ -90,10 +83,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/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/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) {