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

package/dist/commands/improve/outcome-loop.js

@@ -2,12 +2,6 @@
 // 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/.
 // ── Constants ─────────────────────────────────────────────────────────────────
-/**
- * Weight on the "retrieved-but-never-improved" penalty term. Setting this to
- * 0 degrades to a pure prediction-error score (no quality filter); setting it
- * to 1 heavily penalises assets whose retrievals never led to accepted changes.
- */
-export const OUTCOME_PENALTY_WEIGHT = 0.3;
 /**
  * EMA decay factor for the expected-retrieval rolling mean (α).
  * New expected = α × new_count + (1−α) × old_expected.
@@ -33,6 +27,15 @@ export const WARM_START_CAP = 0.3;
  * very-negative run can't send the score to −∞.
  */
 export const OUTCOME_SCORE_MIN = -1.0;
+/**
+ * Saturation ceiling: the maximum outcome_score. Biological RPE saturates —
+ * a fully predicted reward produces zero response, not an ever-growing one —
+ * so a long-lived popular asset must not accrue unbounded outcome mass that
+ * would dominate ranking once the outcome weight is enabled (analysis G2).
+ * 1.5 comfortably exceeds the max plausible single-cycle raw update while
+ * keeping the normalised outcomeSalience spread meaningful.
+ */
+export const OUTCOME_SCORE_MAX = 1.5;
 /**
  * Diversity floor: `outcomeSalience` for any asset is at least this fraction
  * of the maximum observed `outcome_score` in the table, so rare-but-correct
@@ -86,12 +89,8 @@ export function updateAssetOutcome(db, inputs) {
         //
         // retrieval_delta = current − stored (non-negative — we never go backwards)
         const retrievalDelta = Math.max(0, inputs.currentRetrievalCount - existing.retrieval_count);
-        // accepted_change_rate = accepted_count / max(1, retrieval_count)
-        const acceptedChangeRate = inputs.acceptedChangeCount / Math.max(1, inputs.currentRetrievalCount);
         // Differential prediction-error term:
-        // outcome = (retrieval_delta − expected_delta)
-        //           − PENALTY × retrieval_delta × (1 − accepted_change_rate)
-        //           + valence
+        // outcome = (retrieval_delta − expected_delta) + valence
         //
         // Prediction error is computed against the PRIOR stored EMA (before folding
         // in this cycle's observation), so the current delta cannot leak into its own
@@ -102,14 +101,16 @@ export function updateAssetOutcome(db, inputs) {
         // expected' = α × delta + (1−α) × prior_expected
         expectedRetrievalRate =
             OUTCOME_EMA_ALPHA * retrievalDelta + (1 - OUTCOME_EMA_ALPHA) * existing.expected_retrieval_rate;
-        const penalty = OUTCOME_PENALTY_WEIGHT * retrievalDelta * (1 - acceptedChangeRate);
         // Running sum (EMA approach): new score = α × update + (1−α) × old
         // so the score tracks the moving signal, not the cumulative sum.
-        const rawUpdate = predictionError - penalty + valence;
+        const rawUpdate = predictionError + valence;
         const newScore = OUTCOME_EMA_ALPHA * rawUpdate + (1 - OUTCOME_EMA_ALPHA) * existing.outcome_score;
-        // Clip to [OUTCOME_SCORE_MIN, +Infinity) — no upper cap so that very-active
-        // useful assets can accumulate a high positive score.
-        outcomeScore = Math.max(OUTCOME_SCORE_MIN, newScore);
+        // Clip to [OUTCOME_SCORE_MIN, OUTCOME_SCORE_MAX] — the ceiling is the RPE
+        // saturation analog (G2): without it, long-lived popular assets accumulate
+        // unbounded positive mass (live max was 3.13) and would dominate rank_score
+        // the moment the outcome weight is enabled. Stored legacy scores above the
+        // ceiling converge back under it on their next differential update.
+        outcomeScore = Math.min(OUTCOME_SCORE_MAX, Math.max(OUTCOME_SCORE_MIN, newScore));
         // ── review_pressure (#613) ─────────────────────────────────────────────
         // New negatives this cycle.
         const newNegatives = Math.max(0, inputs.negativeFeedbackCount - existing.negative_feedback_count);
@@ -211,6 +212,17 @@ export function outcomeScoreToSalience(outcomeScore, maxScore) {
     // Apply diversity floor.
     return Math.max(DIVERSITY_FLOOR_FRACTION, normalised);
 }
+// ── Proxy-adequacy tripwire ───────────────────────────────────────────────────
+/**
+ * Dead-proxy threshold: |corr| below this means outcome_score carries no
+ * information about improvement need (pure noise).
+ */
+export const PROXY_DEAD_CORR_THRESHOLD = 0.1;
+/**
+ * Minimum sample size before the dead-proxy check fires. Below this, a
+ * near-zero correlation is indistinguishable from small-sample noise.
+ */
+export const PROXY_DEAD_MIN_N = 500;
 /**
  * Compute `corr(outcome_score, accepted_change_rate)` across all asset_outcome
  * rows. Returns `{correlation: NaN, n, isInverted: false}` when there is
@@ -226,7 +238,7 @@ export function outcomeScoreToSalience(outcomeScore, maxScore) {
 export function computeProxyAdequacy(rows) {
     const n = rows.length;
     if (n < 3)
-        return { correlation: Number.NaN, n, isInverted: false };
+        return { correlation: Number.NaN, n, isInverted: false, isDead: false };
     // accepted_change_rate per row.
     const xs = rows.map((r) => r.outcome_score);
     const ys = rows.map((r) => r.accepted_change_count / Math.max(1, r.retrieval_count));
@@ -247,10 +259,12 @@ export function computeProxyAdequacy(rows) {
     varY /= n;
     const denom = Math.sqrt(varX) * Math.sqrt(varY);
     if (denom < 1e-12)
-        return { correlation: Number.NaN, n, isInverted: false };
+        return { correlation: Number.NaN, n, isInverted: false, isDead: false };
     const correlation = covXY / denom;
     // Inverted proxy: negative correlation between outcome and accepted_change_rate
     // means high-outcome assets are also high-need — the opposite of "useful".
     const isInverted = correlation < -0.3;
-    return { correlation, n, isInverted };
+    // Dead proxy: near-zero correlation at scale — the score is noise.
+    const isDead = n >= PROXY_DEAD_MIN_N && Math.abs(correlation) < PROXY_DEAD_CORR_THRESHOLD;
+    return { correlation, n, isInverted, isDead };
 }

package/dist/commands/improve/preparation.js

@@ -27,7 +27,7 @@ import { computeValenceScore, FEEDBACK_WEIGHT, UTILITY_WEIGHT } from "./feedback
 import { makeGateConfig, resolveExtractConfidence, runAutoAcceptGate } from "./improve-auto-accept.js";
 import { resolveProcessEnabled } from "./improve-profiles.js";
 import { applyMemoryCleanup } from "./memory/memory-improve.js";
-import { computeProxyAdequacy, getAllAssetOutcomes, getOutcomeScoresByRef, outcomeScoreToSalience, updateAssetOutcome, } from "./outcome-loop.js";
+import { computeProxyAdequacy, getAllAssetOutcomes, getOutcomeScoresByRef, OUTCOME_SCORE_MAX, outcomeScoreToSalience, updateAssetOutcome, } from "./outcome-loop.js";
 import { DEFAULT_DUE_DAYS, DEFAULT_MAX_PER_RUN, selectProactiveMaintenanceRefs } from "./proactive-maintenance.js";
 import { buildRankChangeReport, computeSalience, getAllRankScores, getAssetSalience, getConsecutiveNoOps, getLastUseMsByRef, isContentEncodingRow, SALIENCE_NO_OP_DAMPEN_FACTOR, SALIENCE_NO_OP_DAMPEN_THRESHOLD, upsertAssetSalience, } from "./salience.js";
 // ── improve preparation stage ───────────────────────
@@ -1145,23 +1145,32 @@ export async function runImprovePreparationStage(args) {
     const proactiveAndRetrievalSet = new Set([...highRetrievalRefs, ...proactiveRefs].map((r) => r.ref));
     try {
         withStateDb((dbForHighSalience) => {
-            const effectiveLimit = options.limit ?? 10;
+            // Derive the cap from the resolved reflect limit (mirrors improve.ts's
+            // options.limit resolution) so an unbounded whole-stash run does not
+            // collapse the lane to exactly 1 ref via the bare `?? 10` fallback.
+            const effectiveLimit = options.limit ?? improveProfile?.processes?.reflect?.limit ?? improveProfile.limit ?? 10;
             const highSalienceCap = Math.max(1, Math.floor(effectiveLimit * 0.1));
             // #632/#4 — session-capture telemetry (checkpoints) must never consume
             // the scarce high-salience budget. Even with a content-scored row, these
             // are pipeline bookkeeping, not assets worth reflecting/rewriting.
             const candidates = noFeedbackCandidates.filter((r) => !proactiveAndRetrievalSet.has(r.ref) && !isSessionCaptureMemoryName(parseAssetRef(r.ref).name));
+            // Collect ALL qualifying candidates, then take the top-N BY SCORE — the
+            // previous first-N-in-scan-order break meant a higher-salience candidate
+            // found later in the scan lost its slot to an earlier lower-scoring one.
+            const qualifying = [];
             for (const r of candidates) {
-                if (highSalienceRefs.length >= highSalienceCap)
-                    break;
                 const row = getAssetSalience(dbForHighSalience, r.ref);
                 if (row &&
                     isContentEncodingRow(row, parseAssetRef(r.ref).type) &&
                     row.encoding_salience >= salienceThreshold &&
                     !lastReflectProposalTs.has(r.ref)) {
-                    highSalienceRefs.push(r);
+                    qualifying.push({ ref: r, score: row.encoding_salience });
                 }
             }
+            qualifying.sort((a, b) => b.score - a.score);
+            for (const q of qualifying.slice(0, highSalienceCap)) {
+                highSalienceRefs.push(q.ref);
+            }
         }, { path: eventsCtx?.dbPath });
     }
     catch (err) {
@@ -1349,8 +1358,13 @@ export async function runImprovePreparationStage(args) {
                     if (row.outcome_score > maxOutcomeScore)
                         maxOutcomeScore = row.outcome_score;
                 }
-                // Proxy-adequacy tripwire: emit a health event if outcome_score is
-                // negatively correlated with accepted_change_rate (inverted proxy).
+                // Read-clip: legacy rows written before the OUTCOME_SCORE_MAX write-clip
+                // existed can sit above the ceiling (live max was 3.13). Without this
+                // clip they inflate the normalisation denominator and floor everyone
+                // else's outcomeSalience (#691 follow-up).
+                maxOutcomeScore = Math.min(maxOutcomeScore, OUTCOME_SCORE_MAX);
+                // Proxy-adequacy tripwire (two-tailed): inverted (corr < −0.3) and
+                // dead (|corr| < 0.1 at n ≥ 500) both emit health events.
                 const adequacy = computeProxyAdequacy(allOutcomes);
                 if (adequacy.isInverted) {
                     appendEvent({
@@ -1363,6 +1377,17 @@ export async function runImprovePreparationStage(args) {
                         },
                     }, eventsCtx);
                 }
+                if (adequacy.isDead) {
+                    appendEvent({
+                        eventType: "outcome_proxy_dead",
+                        ref: undefined,
+                        metadata: {
+                            correlation: adequacy.correlation,
+                            n: adequacy.n,
+                            note: "|corr(outcome_score, accepted_change_rate)| < 0.1 at n ≥ 500: outcome_score is statistically unrelated to improvement outcomes — the proxy is noise, not signal. Rank contributions derived from it are not currently informative.",
+                        },
+                    }, eventsCtx);
+                }
             }
             catch {
                 // best-effort: tripwire failure never blocks ranking
@@ -1392,11 +1417,11 @@ export async function runImprovePreparationStage(args) {
     // so feedback refs get their genuine retrieval frequency, not a 0-floor fallback.
     // outcomeSalienceByRef is populated by WS-2 above (or empty on first run).
     //
-    // Part-V gate: read the operator opt-in flag from config. Default false
-    // (WS-1 parity weights) until the maintainer runs scripts/akm-eval and sets
-    // improve.salience.outcomeWeightEnabled: true in the config.
+    // R1 loop closure: the outcome weight is ON by default (the G2 saturation
+    // cap makes it safe). Operators opt out with
+    // improve.salience.outcomeWeightEnabled: false in the config.
     const salienceConfig = (options.config ?? loadConfig()).improve?.salience;
-    const outcomeWeightEnabled = salienceConfig?.outcomeWeightEnabled === true;
+    const outcomeWeightEnabled = salienceConfig?.outcomeWeightEnabled !== false;
     const salienceMap = new Map();
     const nowForSalience = Date.now();
     // #644 — preserve content-derived encoding scores across runs.

package/dist/commands/improve/salience.js

@@ -21,12 +21,12 @@
  *
  * `rankScore = (w_e·encoding + w_o·outcome + w_r·retrieval) × sizePenalty`, normalized [0,1].
  *
- * **WS-2 default-off (Part-V gate):**
- * `w_o = 0.15` is the target but is applied only when `outcomeWeightEnabled=true`
- * (set via `improve.salience.outcomeWeightEnabled: true` in config after running
- * Part-V T0 baseline). Default: WS-1 parity weights `w_e=0.30, w_r=0.70, w_o=0`.
- * `outcomeSalience` is populated from `asset_outcome.outcome_score` (WS-2) for
- * observability regardless of the flag.
+ * **WS-2 default-ON (R1 loop closure):**
+ * `w_o = 0.15` is applied by default now that `outcome_score` saturates at
+ * `OUTCOME_SCORE_MAX` (G2). Operators can opt out via
+ * `improve.salience.outcomeWeightEnabled: false`, which restores the WS-1
+ * parity weights `w_e=0.30, w_r=0.70, w_o=0`. `outcomeSalience` is populated
+ * from `asset_outcome.outcome_score` regardless of the flag.
  *
  * ## Plasticity
  *
@@ -52,16 +52,30 @@ import { WARM_START_CAP } from "./outcome-loop.js";
 const DAY_MS = 86_400_000;
 // ── Recency decay half-life (mirrors the proactive-maintenance prototype) ─────
 const RECENCY_HALFLIFE_DAYS = 21;
+// ── Recency-floor half-life (R4 — SHY-style continuous downscaling) ──────────
+//
+// The recency floor itself decays on this (much longer) half-life so an
+// unreviewed-forever asset keeps drifting down instead of parking at the 0.1
+// floor. This replaces the deleted homeostatic demotion pass (which was
+// default-off and self-undoing — every salience recompute clobbered it);
+// folding the decay into the always-applied recency term makes it persist by
+// construction. At 180 days the floor halves; a 1-year-stale asset sits at
+// ~0.025 instead of 0.1.
+const RECENCY_FLOOR_HALFLIFE_DAYS = 180;
+// Absolute epsilon under the decaying floor. Keeps the frequency term ordinal
+// for assets whose last-use timestamp is unknown (utility_scores has no
+// last_used_at) — without it their retrieval salience collapses to exactly 0
+// and frequency ordering is lost for maintenance selection.
+const RECENCY_EPSILON = 0.01;
 // ── Size proxy floor (avoids log10(0)) ────────────────────────────────────────
 const SIZE_FLOOR_BYTES = 200;
 // ── Projection weights ────────────────────────────────────────────────────────
 //
-// These constants reflect the WS-2 TARGET values (used when outcomeWeightEnabled=true).
-// Default ranking uses WS-1 parity weights (w_e=0.30, w_r=0.70, w_o=0) until the
-// maintainer opts in via `improve.salience.outcomeWeightEnabled: true` after running
-// the Part-V T0 baseline (scripts/akm-eval + health report).
+// These constants are the DEFAULT ranking weights (R1 loop closure). Operators
+// can opt back out to the WS-1 parity weights (w_e=0.30, w_r=0.70, w_o=0) via
+// `improve.salience.outcomeWeightEnabled: false`.
 //
-// WS-2 opt-in split (w_e=0.25, w_o=0.15, w_r=0.60, sum = 1.0):
+// WS-2 split (w_e=0.25, w_o=0.15, w_r=0.60, sum = 1.0):
 // [exp] Expert recommendation: encoding should be moderate so a type-importance
 // stub does not completely dominate; retrieval should be strong since it directly
 // measures use; outcome provides a quality signal proportional to usefulness.
@@ -78,10 +92,10 @@ if (Math.abs(W_ENCODING + W_OUTCOME + W_RETRIEVAL - 1.0) > 1e-9) {
 }
 // ── WS-1 parity weights ───────────────────────────────────────────────────────
 //
-// These constants reflect the default WS-1 parity weights used when
-// `outcomeWeightEnabled` is false/absent (the default). They preserve the
+// These constants reflect the WS-1 parity weights used when the operator
+// explicitly opts out (`outcomeWeightEnabled: false`). They preserve the
 // WS-1 two-way split (w_e=0.30, w_r=0.70) with w_o=0 so outcome does not
-// affect rankScore until the operator opts in after the Part-V baseline run.
+// affect rankScore in the opt-out mode.
 //
 // Named here (rather than inline literals in the else branch) so a future
 // re-tune has a single source of truth and the sum-to-1 guard below catches
@@ -155,15 +169,19 @@ export function computeSalience(inputs) {
     //
     // Formula: log(1 + freq) × recencyDecay
     //   log(1+freq): sub-linear frequency term (same as proactive-maintenance prototype).
-    //   recencyDecay: 0.1 + 0.5^(useAgeDays/halflife) — decays to 0.1 floor when stale.
-    //     lastUseMs=0/undefined → useAgeDays=9999 → recencyDecay≈0.1 (floor).
+    //   recencyDecay: max(ε, 0.1·0.5^(useAgeDays/180) + 0.5^(useAgeDays/21)) —
+    //     the fast term halves every 21 days; the 0.1 floor itself halves every
+    //     180 days (R4: SHY-style continuous downscaling — an unreviewed-forever
+    //     asset keeps drifting down instead of parking at the floor). The ε=0.01
+    //     epsilon keeps the frequency term ordinal for unknown-last-use assets.
+    //     lastUseMs=0/undefined → useAgeDays=9999 → recencyDecay=ε.
     //
     // The recency term is MANDATORY (plan requirement §WS-1 step 2). Without it
-    // retrievalSalience degenerates to a non-decaying frequency count and the WS-3
-    // homeostatic step-0 demotion has nothing to act on.
+    // retrievalSalience degenerates to a non-decaying frequency count. This
+    // always-applied decay replaces the deleted homeostatic demotion pass.
     const lastUseMs = inputs.lastUseMs ?? 0;
     const useAgeDays = lastUseMs > 0 ? (now - lastUseMs) / DAY_MS : 9999;
-    const recencyDecay = 0.1 + 0.5 ** (useAgeDays / RECENCY_HALFLIFE_DAYS);
+    const recencyDecay = Math.max(RECENCY_EPSILON, 0.1 * 0.5 ** (useAgeDays / RECENCY_FLOOR_HALFLIFE_DAYS) + 0.5 ** (useAgeDays / RECENCY_HALFLIFE_DAYS));
     const rawRetrieval = Math.log(1 + inputs.retrievalFreq) * recencyDecay;
     // ── Size penalty ─────────────────────────────────────────────────────────────
     // 1/log10(size): larger assets are slightly deprioritized (same as proactive prototype).
@@ -184,29 +202,28 @@ export function computeSalience(inputs) {
     // which asymptotes to 1 and equals 0.5 at rawRetrieval=1. This is the same
     // formula used for MemRL utility updates.
     const retrieval = rawRetrieval / (rawRetrieval + 1);
-    // ── Weight selection (Part-V gate) ────────────────────────────────────────
-    //
-    // When `outcomeWeightEnabled` is false/absent (default): use WS-1 parity
-    // weights (w_e=0.30, w_r=0.70, w_o=0) so ranking is unchanged from the WS-1
-    // baseline. The `outcome` sub-score is still computed and stored in the
-    // salience vector for observability, but it does not affect rankScore.
+    // ── Weight selection (R1 — outcome loop closed by default) ───────────────
     //
-    // When `outcomeWeightEnabled` is true (operator opt-in after Part-V run):
-    // use WS-2 weights (w_e=0.25, w_o=0.15, w_r=0.60).
+    // When `outcomeWeightEnabled` is true/absent (DEFAULT ON since the G2
+    // saturation cap landed): use WS-2 weights (w_e=0.25, w_o=0.15, w_r=0.60)
+    // so the prediction-error outcome signal actually shapes rankScore — this
+    // is the R1 loop-closure from docs/design/improve-self-learning-analysis.md.
     //
-    // The constants W_ENCODING, W_OUTCOME, W_RETRIEVAL always reflect the
-    // WS-2 target values for documentation and re-tune reference.
+    // When `outcomeWeightEnabled` is explicitly false (operator opt-out via
+    // `improve.salience.outcomeWeightEnabled: false`): fall back to the WS-1
+    // parity weights (w_e=0.30, w_r=0.70, w_o=0). The `outcome` sub-score is
+    // still computed and stored for observability in that mode.
     let we;
     let wo;
     let wr;
-    if (inputs.outcomeWeightEnabled === true) {
-        // WS-2 active: three-way split from Part-V operator opt-in.
+    if (inputs.outcomeWeightEnabled !== false) {
+        // WS-2 active (default): three-way split.
         we = W_ENCODING; // 0.25
         wo = W_OUTCOME; // 0.15
         wr = W_RETRIEVAL; // 0.60
     }
     else {
-        // WS-1 parity (default): w_o=0, redistribute to WS-1 proportions.
+        // WS-1 parity (opt-out): w_o=0, redistribute to WS-1 proportions.
         // Original WS-1 split was w_e=0.30, w_r=0.70.
         we = W_ENCODING_PARITY;
         wo = W_OUTCOME_PARITY;

package/dist/commands/read/curate.js

@@ -19,12 +19,12 @@ import { parseFrontmatter } from "../../core/asset/frontmatter.js";
 import { getIndexPassConfig, loadConfig } from "../../core/config/config.js";
 import { rethrowIfTestIsolationError, UsageError } from "../../core/errors.js";
 import { appendEvent } from "../../core/events.js";
-import { closeDatabase, computeBodyHash, openExistingDatabase } from "../../indexer/db/db.js";
+import { computeBodyHash } from "../../indexer/db/db.js";
 import { enqueueGraphExtraction, hasGraphData } from "../../indexer/db/graph-db.js";
 import { findSourceForPath, resolveSourceEntries } from "../../indexer/search/search-source.js";
 import { insertUsageEvent } from "../../indexer/usage/usage-events.js";
 import { truncateDescription } from "../../output/shapes.js";
-import { withIndexDb } from "../../storage/repositories/index-db.js";
+import { TELEMETRY_BUSY_TIMEOUT_MS, withIndexDb } from "../../storage/repositories/index-db.js";
 import { akmSearch, parseSearchSource } from "./search.js";
 import { akmShowUnified } from "./show.js";
 const CURATE_FALLBACK_FILTER_WORDS = new Set([
@@ -58,15 +58,14 @@ const CURATE_REFERENCE_QUERY_RE = /\b(?:reference|docs?|guide|how|explain|learn|
  * Fire-and-forget: log a curate event to the usage_events table and events.jsonl.
  * Never blocks the caller; errors are silently ignored.
  */
-function logCurateEvent(query, result) {
+function logCurateEvent(query, result, eventSource = "user") {
     const itemRefs = result.items.map((item) => ("ref" in item ? item.ref : `registry:${item.id}`));
     appendEvent({
         eventType: "curate",
         metadata: { query, itemCount: result.items.length, itemRefs },
     });
     try {
-        const db = openExistingDatabase();
-        try {
+        withIndexDb((db) => {
             insertUsageEvent(db, {
                 event_type: "curate",
                 query,
@@ -74,7 +73,7 @@ function logCurateEvent(query, result) {
                     itemCount: result.items.length,
                     itemRefs,
                 }),
-                source: "user",
+                source: eventSource,
             });
             for (const item of result.items) {
                 if (!("ref" in item) || typeof item.ref !== "string")
@@ -83,13 +82,10 @@ function logCurateEvent(query, result) {
                     event_type: "curate",
                     query,
                     entry_ref: item.ref,
-                    source: "user",
+                    source: eventSource,
                 });
             }
-        }
-        finally {
-            closeDatabase(db);
-        }
+        }, { busyTimeoutMs: TELEMETRY_BUSY_TIMEOUT_MS });
     }
     catch (err) {
         rethrowIfTestIsolationError(err);
@@ -110,7 +106,7 @@ export async function akmCurate(options) {
             source,
         }));
     const result = await curateSearchResults(options.query, searchResponse, limit, options.type);
-    logCurateEvent(options.query, result);
+    logCurateEvent(options.query, result, options.eventSource);
     return result;
 }
 export async function curateSearchResults(query, result, limit, selectedType) {
@@ -207,7 +203,7 @@ function maybeEnqueueLazyGraph(assetPath) {
             if (!hasGraphData(db, stashRoot, assetPath)) {
                 enqueueGraphExtraction(db, stashRoot, assetPath, bodyHash, 0);
             }
-        });
+        }, { busyTimeoutMs: TELEMETRY_BUSY_TIMEOUT_MS });
     }
     catch (err) {
         rethrowIfTestIsolationError(err);

package/dist/commands/read/knowledge.js

@@ -16,6 +16,7 @@ import { isHttpUrl, isWithin, tryReadStdinText } from "../../core/common.js";
 import { loadConfig } from "../../core/config/config.js";
 import { UsageError } from "../../core/errors.js";
 import { commitWriteTargetBoundary, formatRefForMessage, resolveWriteTarget, writeAssetToSource, } from "../../core/write-source.js";
+import { indexWrittenAssets } from "../../indexer/index-written-assets.js";
 import { fetchWebsiteMarkdownSnapshot, shouldAllowPrivateWebsiteUrlForTests } from "../../sources/website-ingest.js";
 const MAX_CAPTURED_ASSET_SLUG_LENGTH = 64;
 // ── Asset-name normalisation ─────────────────────────────────────────────────
@@ -144,6 +145,9 @@ export async function writeMarkdownAsset(options) {
     // 0.9.0 (issue #507): single batch commit at the write boundary for git
     // targets. No-op for filesystem/primary-stash targets.
     commitWriteTargetBoundary(target, `Update ${formatRefForMessage(ref)}`);
+    // Write-path indexing: the asset is searchable immediately. Fail-open; reads
+    // no longer trigger reindexes, so keeping the index current is the writer's job.
+    await indexWrittenAssets(source.path, [result.path]);
     return {
         ref: result.ref,
         path: result.path,

package/dist/commands/read/search-cli.js

@@ -21,13 +21,15 @@ import { getHyphenatedBoolean, getOutputMode, parseFlagValue } from "../../outpu
 import { akmCurate } from "./curate.js";
 import { akmSearch, parseBeliefFilterMode, parseScopeFilterFlags, parseSearchSource } from "./search.js";
 import { akmShowUnified } from "./show.js";
-// AKM_EVENT_SOURCE attributes a query to a `user` invocation or the internal
-// `improve` loop so the event log can distinguish them; any other value is
-// treated as unset.
+// AKM_EVENT_SOURCE attributes a query to a `user` invocation, the internal
+// `improve` loop, or the `task` runner so the event log can distinguish
+// genuine demand from machine traffic; any other value is treated as unset.
 function resolveEventSource() {
     const raw = process.env.AKM_EVENT_SOURCE;
     if (raw === "improve")
         return "improve";
+    if (raw === "task")
+        return "task";
     if (raw === "user")
         return "user";
     return undefined;
@@ -129,7 +131,7 @@ export const curateCommand = defineJsonCommand({
         const limitParsed = parsePositiveIntFlag(args.limit ?? undefined);
         const limit = limitParsed && limitParsed > 0 ? limitParsed : 4;
         const source = parseSearchSource(args.source ?? "stash");
-        const curated = await akmCurate({ query: args.query, type, limit, source });
+        const curated = await akmCurate({ query: args.query, type, limit, source, eventSource: resolveEventSource() });
         output("curate", curated);
     },
 });

package/dist/commands/read/search.js

@@ -16,14 +16,14 @@ import { rethrowIfTestIsolationError, UsageError } from "../../core/errors.js";
 import { appendEvent } from "../../core/events.js";
 import { isTransientStashPath } from "../../core/paths.js";
 import { bumpUtilityScoresBatch, getEntryIdByFilePath } from "../../indexer/db/db.js";
+import { resolveReadSources } from "../../indexer/read-preflight.js";
 import { searchLocal } from "../../indexer/search/db-search.js";
-import { resolveSourceEntries } from "../../indexer/search/search-source.js";
 import { getCurrentWorkflowScopeKey } from "../../workflows/authoring/scope-key.js";
 // Eagerly import source providers to trigger self-registration before the
 // indexer or path-resolution code runs.
 import "../../sources/providers/index.js";
 import { insertUsageEvent } from "../../indexer/usage/usage-events.js";
-import { withIndexDb } from "../../storage/repositories/index-db.js";
+import { TELEMETRY_BUSY_TIMEOUT_MS, withIndexDb } from "../../storage/repositories/index-db.js";
 import { searchRegistry } from "./registry-search.js";
 const DEFAULT_LIMIT = 20;
 export async function akmSearch(input) {
@@ -57,7 +57,7 @@ export async function akmSearch(input) {
     else {
         source = parsedSource;
     }
-    let allSources = resolveSourceEntries(undefined, config);
+    let allSources = resolveReadSources(undefined, config).sources;
     // When a named source was requested, narrow the sources list to just that entry.
     // `resolveSourceEntries` sets `registryId` to `entry.name` for each config source.
     if (namedSourceName !== undefined) {
@@ -227,6 +227,9 @@ function logSearchEvent(query, response, mode = "keyword", eventSource = "user",
         metadata: { query, hitCount: stashHits.length, resultRefs: allResultRefs, mode },
     });
     try {
+        // Short busy timeout: telemetry must never stall the search result behind
+        // a background reindex holding the index.db write lock (30s default wait).
+        // Under contention these usage hints are skipped, not waited for.
         withIndexDb((db) => {
             const resolved = resolveEntryIds(db, stashHits.slice(0, 50));
             for (const { entryId, ref } of resolved) {
@@ -240,7 +243,11 @@ function logSearchEvent(query, response, mode = "keyword", eventSource = "user",
             }
             // Bump utility scores for all resolved entries (MemRL retrieval signal).
             // The indexer overwrites these at next reindex; bumps are temporary hints.
-            const resolvedIds = resolved.map((r) => r.entryId).filter((id) => id !== undefined);
+            // Gated to user-sourced events: pipeline searches (improve probes, task
+            // runner) must not feed the utility signal (meta-review 05 DRIFT-6 —
+            // the bump previously fired unconditionally, so even correctly-tagged
+            // machine traffic inflated utility).
+            const resolvedIds = eventSource === "user" ? resolved.map((r) => r.entryId).filter((id) => id !== undefined) : [];
             if (resolvedIds.length > 0) {
                 let scopeKey;
                 try {
@@ -269,7 +276,7 @@ function logSearchEvent(query, response, mode = "keyword", eventSource = "user",
                 }),
                 source: eventSource,
             });
-        });
+        }, { busyTimeoutMs: TELEMETRY_BUSY_TIMEOUT_MS });
     }
     catch (err) {
         rethrowIfTestIsolationError(err);

package/dist/commands/read/show.js

@@ -28,10 +28,10 @@ import { NotFoundError, rethrowIfTestIsolationError, UsageError } from "../../co
 import { appendEvent, readEvents } from "../../core/events.js";
 import { closeDatabase, computeBodyHash, findEntryIdByRef, openExistingDatabase } from "../../indexer/db/db.js";
 import { hasGraphData } from "../../indexer/db/graph-db.js";
-import { ensureIndex } from "../../indexer/ensure-index.js";
 import { listRelatedPathsForFile } from "../../indexer/graph/graph-boost.js";
 import { extractGraphForSingleFile } from "../../indexer/graph/graph-extraction.js";
 import { lookup } from "../../indexer/indexer.js";
+import { ensurePrimaryIndexForRead, resolveReadSources } from "../../indexer/read-preflight.js";
 import { buildEditHint, findSourceForPath, isEditable, resolveSourceEntries } from "../../indexer/search/search-source.js";
 import { insertUsageEvent } from "../../indexer/usage/usage-events.js";
 import { buildFileContext, buildRenderContext, getRenderer, runMatchers } from "../../indexer/walk/file-context.js";
@@ -39,7 +39,7 @@ import { resolveAssetPath } from "../../indexer/walk/path-resolver.js";
 import { resolveIndexPassLLM } from "../../llm/index-passes.js";
 import { resolveSourcesForOrigin } from "../../registry/origin-resolve.js";
 import { resolveStorageLocations } from "../../storage/locations.js";
-import { withIndexDb } from "../../storage/repositories/index-db.js";
+import { TELEMETRY_BUSY_TIMEOUT_MS, withIndexDb } from "../../storage/repositories/index-db.js";
 // Eagerly import source providers to trigger self-registration.
 import "../../sources/providers/index.js";
 import { getCurrentWorkflowScopeKey } from "../../workflows/authoring/scope-key.js";
@@ -147,10 +147,8 @@ export async function akmShowUnified(input) {
         }
     }
     // Auto-index when stale so the index is current before lookup.
-    const allSources = resolveSourceEntries();
-    if (allSources.length > 0) {
-        await ensureIndex(allSources[0].path);
-    }
+    const { primarySource } = resolveReadSources();
+    await ensurePrimaryIndexForRead(primarySource);
     // Try local filesystem (FTS5 index lookup)
     const result = await showLocal(input);
     // Scope filter narrows resolution: if --scope was supplied, the asset's
@@ -301,7 +299,7 @@ function logShowEvent(ref, eventSource = "user") {
                 entry_id: findEntryIdByRef(db, ref),
                 source: eventSource,
             });
-        });
+        }, { busyTimeoutMs: TELEMETRY_BUSY_TIMEOUT_MS });
     }
     catch (err) {
         rethrowIfTestIsolationError(err);
@@ -431,7 +429,7 @@ async function maybeExtractGraphInline(config, sourceStashDir, assetPath) {
         }
         withIndexDb((db) => {
             alreadyGraphed = hasGraphData(db, sourceStashDir, assetPath);
-        });
+        }, { busyTimeoutMs: TELEMETRY_BUSY_TIMEOUT_MS });
         if (alreadyGraphed)
             return;
         // Open the db for the async extraction ourselves: `withIndexDb` is

package/dist/commands/sources/add-cli.js

@@ -3,8 +3,8 @@
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
 import fs from "node:fs";
 import path from "node:path";
-import * as p from "@clack/prompts";
 import { defineCommand } from "citty";
+import * as p from "../../cli/clack.js";
 import { output, runWithJsonErrors } from "../../cli/shared.js";
 import { UsageError } from "../../core/errors.js";
 import { appendEvent } from "../../core/events.js";

package/dist/commands/sources/init.js

@@ -55,7 +55,19 @@ function assertInitSandbox(stashDir, dirExplicitlyProvided) {
 function isUnderTestRunner() {
     return process.env.BUN_TEST === "1" || process.env.NODE_ENV === "test";
 }
+// ── Test seam ────────────────────────────────────────────────────────────────
+// Swap-and-restore override. Inert in production; only tests call the setter.
+let akmInitOverride;
+/** TEST-ONLY. Swap the implementation of `akmInit`; pass undefined to restore. */
+export function _setAkmInitForTests(fake) {
+    akmInitOverride = fake;
+}
 export async function akmInit(options) {
+    if (akmInitOverride)
+        return akmInitOverride(options);
+    return akmInitReal(options);
+}
+async function akmInitReal(options) {
     const dirExplicitlyProvided = options?.dir != null;
     const setDefault = options?.setDefault === true;
     const stashDir = options?.dir ? path.resolve(options.dir) : getDefaultStashDir();

package/dist/commands/sources/stash-cli.js

@@ -25,8 +25,8 @@
  * SIGINT/SIGTERM handlers in a try/finally — left byte-for-byte untouched.
  */
 import path from "node:path";
-import * as p from "@clack/prompts";
 import { defineCommand } from "citty";
+import * as p from "../../cli/clack.js";
 import { defineJsonCommand, output, runWithJsonErrors } from "../../cli/shared.js";
 import { assertFlatAssetName } from "../../core/asset/asset-create.js";
 import { isHttpUrl } from "../../core/common.js";