akm-cli 0.9.16 → 0.9.17-alpha.1

package/dist/commands/improve/improve.js

@@ -18,11 +18,13 @@ import { info, warn, warnVerbose } from "../../core/warn.js";
 import { beginWriteProvenance, relativeWrittenPath } from "../../core/write-provenance.js";
 import { resolveWritable, resolveWriteTarget } from "../../core/write-source.js";
 import { ensureIndex } from "../../indexer/ensure-index.js";
+import { indexWrittenAssets } from "../../indexer/index-written-assets.js";
 import { akmIndex } from "../../indexer/indexer.js";
 import { collectPendingMemories } from "../../indexer/passes/memory-inference.js";
 import { resolveEntryContentDir, resolveSourceEntries } from "../../indexer/search/search-source.js";
 import { collectEngineCredentialValues } from "../../integrations/agent/engine-resolution.js";
 import { installLlmUsagePersistence, LLM_USAGE_EVENT } from "../../llm/usage-persist.js";
+import { withLlmStage } from "../../llm/usage-telemetry.js";
 import { isGitBackedStash, listGitChangedPaths, resolveWritableOverride, saveGitStash, } from "../../sources/providers/git.js";
 import { closeDatabase, openExistingDatabase } from "../../storage/repositories/index-connection.js";
 import { getEntryCount } from "../../storage/repositories/index-entries-repository.js";
@@ -34,7 +36,6 @@ import { describeGatedLanes, isAutonomyLaneAllowed } from "./autonomy-gate.js";
 import { akmDistill } from "./distill.js";
 // Eligibility / candidate-selection predicates live in ./eligibility.
 import { buildLatestProposalTsMap, collectEligibleRefs, collectEligibleRefsReadOnly, memoryCleanupParentRef, resolveImproveScope, shouldAnalyzeMemoryCleanup, } from "./eligibility.js";
-import { countEvalCases } from "./eval-cases.js";
 import { projectResolvedProcessRouting, resolveImprovePlan, resolveImproveStrategy, shouldSkipRef, } from "./improve-strategies.js";
 import { buildImproveUsageReport } from "./improve-usage-report.js";
 import { improveLockPath, releaseImproveLock, tryAcquireImproveLock } from "./locks.js";
@@ -149,6 +150,7 @@ export async function akmImprove(options = {}) {
     let autonomyGatedDirectLanes = [];
     let guidance;
     let triageDrain;
+    let ensureIndexDurationMs;
     let improveLockOwnership;
     let exitBackstop;
     // I1: open a single state.db connection for the main improve run so all
@@ -205,13 +207,33 @@ export async function akmImprove(options = {}) {
             // #652: open AFTER the lock, so the journal covers exactly the window in
             // which this run — and only this run — is allowed to write.
             runJournal.open();
-            // Drain the standing proposal backlog before indexing so fresh proposal
-            // generation sees promotions from this same serialized run.
+            // R6: ensureIndex BEFORE triage, not after. Triage promotes proposals
+            // straight into the flat `knowledge/` root; running the blocking
+            // reindex only afterward (inside indexAndCollect, below) meant every
+            // triage promotion dirtied the stash right before the rescan that is
+            // supposed to precede it, so the "blocking" reindex always found fresh
+            // work and paid for a full walk on the very run it was meant to avoid.
+            const bootstrap = await runIndexBootstrapPass(setup, budgetAbortController.signal);
+            preEnsureCleanupWarnings.push(...bootstrap.warnings);
+            ensureIndexDurationMs = bootstrap.ensureIndexDurationMs;
+            // Drain the standing proposal backlog under the now-current index, so
+            // fresh proposal generation sees promotions from this same serialized
+            // run.
             triageDrain = await runTriagePrePass(setup);
+            // R6: index triage's own writes incrementally (the R8
+            // `indexWrittenAssets` pattern) instead of letting them sit newer than
+            // `builtAt` until the next full reindex. `collectEligibleRefs` below
+            // still needs to see them, and per-file staleness (`ensure-index.ts`)
+            // needs their `content_hash` recorded so it does not re-trigger a full
+            // rescan next run for content it already has.
+            if (setup.primaryStashDir) {
+                const triageWrittenPaths = runJournal.current()?.writtenPaths() ?? [];
+                if (triageWrittenPaths.length > 0) {
+                    await indexWrittenAssets(setup.primaryStashDir, triageWrittenPaths);
+                }
+            }
         }
-        // #339 fix: ensureIndex MUST run BEFORE collectEligibleRefs (inside the
-        // indexAndCollect helper).
-        const collected = await indexAndCollect({ run: setup, signal: budgetAbortController.signal });
+        const collected = await indexAndCollect({ run: setup });
         plannedRefs = collected.plannedRefs;
         memorySummary = collected.memorySummary;
         strategyFilteredRefs = collected.strategyFilteredRefs;
@@ -219,7 +241,6 @@ export async function akmImprove(options = {}) {
         memoryCleanupPlan = collected.memoryCleanupPlan;
         autonomyGatedDirectLanes = collected.autonomyGatedDirectLanes;
         guidance = collected.guidance;
-        preEnsureCleanupWarnings.push(...collected.warnings);
         if (options.dryRun) {
             const result = await runDryPlanningStage({
                 run: setup,
@@ -291,6 +312,7 @@ export async function akmImprove(options = {}) {
             rawPlannedRefs: plannedRefs,
             indexSnapshot,
             triageDrain,
+            ensureIndexDurationMs,
             eventsCtx,
         });
         // End-of-run BATCH auto-sync — the converged commit. Recognition is
@@ -620,83 +642,97 @@ function recordImproveFailure(err, run, eventsCtx) {
     }, eventsCtx);
 }
 /**
- * ensureIndex + collectEligibleRefs + the contradiction pre-pass + the
- * memory-cleanup recompute (#339 ordering). Formerly the runIndexAndCollect
- * closure mutating outer `let`s; now a pure pass returning its results.
+ * R6: ensureIndex bootstrap pass, hoisted out of `indexAndCollect` (below) so
+ * the caller can run it BEFORE the triage pre-pass instead of after it —
+ * triage promotes proposals straight into `knowledge/`, so ensureIndex must
+ * see a current index before triage dirties it, not after. Gated exactly as
+ * this logic was gated inside `indexAndCollect`: only for a resolved
+ * `primaryStashDir` on a non-dry-run.
+ *
+ * #339 fix carried over unchanged: ensureIndex MUST run before
+ * collectEligibleRefs. The eligible-ref query reads the `entries` table; if a
+ * DB version upgrade just dropped that table (or the index is otherwise
+ * empty), skipping this would silently return plannedRefs=[] and the improve
+ * loop would no-op.
  */
-async function indexAndCollect(args) {
-    const { signal } = args;
-    const { scope, options, primaryStashDir, improveProfile, _earlyConfig, ensureIndexFn, collectEligibleRefsImpl } = args.run;
+async function runIndexBootstrapPass(run, signal) {
+    const { primaryStashDir, options, ensureIndexFn } = run;
     const warnings = [];
-    let plannedRefs = [];
-    let memorySummary = { eligible: 0, derived: 0 };
-    let strategyFilteredRefs = [];
-    let indexSnapshot;
-    // #339 fix: ensureIndex MUST run BEFORE collectEligibleRefs. The eligible-ref
-    // query reads the `entries` table; if a DB version upgrade just dropped that
-    // table (or the index is otherwise empty), the prior run order silently
-    // returned plannedRefs=[] and the improve loop no-op'd. Hoisting the call
-    // here repopulates the index first so the subsequent query sees fresh data.
-    if (primaryStashDir && !options.dryRun) {
-        // Probe pre-ensureIndex entry count to drive the loud-fail warning below.
-        // Best-effort: a missing DB / unreadable schema is the fresh-install case
-        // and not a bug — we silently skip the probe.
-        let preEnsureEntryCount;
-        try {
-            const dbPath = getDbPath();
-            if (fs.existsSync(dbPath)) {
-                const probeDb = openExistingDatabase();
-                try {
-                    preEnsureEntryCount = getEntryCount(probeDb);
-                }
-                finally {
-                    closeDatabase(probeDb);
-                }
+    if (!primaryStashDir || options.dryRun)
+        return { warnings };
+    // Probe pre-ensureIndex entry count to drive the loud-fail warning below.
+    // Best-effort: a missing DB / unreadable schema is the fresh-install case
+    // and not a bug — we silently skip the probe.
+    let preEnsureEntryCount;
+    try {
+        const dbPath = getDbPath();
+        if (fs.existsSync(dbPath)) {
+            const probeDb = openExistingDatabase();
+            try {
+                preEnsureEntryCount = getEntryCount(probeDb);
+            }
+            finally {
+                closeDatabase(probeDb);
             }
         }
-        catch (err) {
-            rethrowIfTestIsolationError(err);
-            // best-effort; leave preEnsureEntryCount undefined
-        }
+    }
+    catch (err) {
+        rethrowIfTestIsolationError(err);
+        // best-effort; leave preEnsureEntryCount undefined
+    }
+    let ensureIndexDurationMs;
+    try {
+        await ensureIndexFn(primaryStashDir, {
+            mode: "blocking",
+            signal,
+            // R6: capture the implicit reindex's wall-clock cost (otherwise
+            // discarded) so the caller can surface it on the improve result.
+            onReindexTiming: ({ durationMs }) => {
+                ensureIndexDurationMs = durationMs;
+            },
+        });
+    }
+    catch (err) {
+        if (signal.aborted)
+            throw err;
+        warnings.push(`ensureIndex failed: ${errMessage(err)}`);
+    }
+    // #339 loud-fail: if the index was empty pre-ensureIndex but is now
+    // populated, a version-upgrade-triggered rebuild just happened. Surface
+    // that on stderr so the improve run is not silently masked by stale
+    // index state. Zero-before AND zero-after is the empty-stash case and
+    // is intentionally not warned (not a bug).
+    if (preEnsureEntryCount === 0) {
         try {
-            await ensureIndexFn(primaryStashDir, { mode: "blocking", signal: signal });
-        }
-        catch (err) {
-            if (signal.aborted)
-                throw err;
-            warnings.push(`ensureIndex failed: ${errMessage(err)}`);
-        }
-        // #339 loud-fail: if the index was empty pre-ensureIndex but is now
-        // populated, a version-upgrade-triggered rebuild just happened. Surface
-        // that on stderr so the improve run is not silently masked by stale
-        // index state. Zero-before AND zero-after is the empty-stash case and
-        // is intentionally not warned (not a bug).
-        if (preEnsureEntryCount === 0) {
+            const probeDb = openExistingDatabase();
+            let postCount = 0;
             try {
-                const probeDb = openExistingDatabase();
-                let postCount = 0;
-                try {
-                    postCount = getEntryCount(probeDb);
-                }
-                finally {
-                    closeDatabase(probeDb);
-                }
-                if (postCount > 0) {
-                    warn("[improve] index was empty after DB version upgrade — repopulating before continuing");
-                }
+                postCount = getEntryCount(probeDb);
             }
-            catch (err) {
-                rethrowIfTestIsolationError(err);
-                // best-effort
+            finally {
+                closeDatabase(probeDb);
+            }
+            if (postCount > 0) {
+                warn("[improve] index was empty after DB version upgrade — repopulating before continuing");
             }
         }
+        catch (err) {
+            rethrowIfTestIsolationError(err);
+            // best-effort
+        }
     }
-    ({
-        plannedRefs,
-        memorySummary,
-        strategyFilteredRefs = [],
-        indexSnapshot,
-    } = await collectEligibleRefsImpl(scope, options.stashDir, improveProfile, _earlyConfig));
+    return { warnings, ensureIndexDurationMs };
+}
+/**
+ * collectEligibleRefs + the contradiction pre-pass + the memory-cleanup
+ * recompute. Formerly the runIndexAndCollect closure mutating outer `let`s;
+ * now a pure pass returning its results. The ensureIndex bootstrap this
+ * function used to open with now runs earlier, before triage — see
+ * {@link runIndexBootstrapPass} and its call site in `akmImprove`.
+ */
+async function indexAndCollect(args) {
+    const { scope, options, primaryStashDir, improveProfile, _earlyConfig, collectEligibleRefsImpl } = args.run;
+    const { plannedRefs, memorySummary, strategyFilteredRefs = [], indexSnapshot, } = await collectEligibleRefsImpl(scope, options.stashDir, improveProfile, _earlyConfig);
     const cleanupParentRef = memoryCleanupParentRef(scope, options.stashDir);
     // D8 — the two direct lanes share one eligibility predicate, which reads scope
     // and eligible-memory count and no strategy flag at all. Compute it once: it
@@ -724,7 +760,6 @@ async function indexAndCollect(args) {
         memoryCleanupPlan,
         autonomyGatedDirectLanes,
         guidance,
-        warnings,
     };
 }
 /** The P2 lock-skipped envelope (graceful `skipIfLocked` early return). Exported for unit tests. */
@@ -810,6 +845,7 @@ export function buildDryRunResult(run, collected, preparation) {
             : {}),
         ...(strategyFilteredRefs.length > 0 ? { strategyFilteredRefs } : {}),
         ...(run.resolvedPlan.engineUnavailable.length > 0 ? { skippedProcesses: run.resolvedPlan.engineUnavailable } : {}),
+        ...(run.options.engineProbe !== undefined ? { engineProbe: run.options.engineProbe } : {}),
         ...(preparation?.proactiveMaintenance ? { proactiveMaintenance: preparation.proactiveMaintenance } : {}),
     };
 }
@@ -935,7 +971,7 @@ async function runTriagePrePass(run) {
                 const policy = resolveDrainPolicy(triageConfig?.policy);
                 const applyMode = triageConfig?.applyMode ?? "queue";
                 const maxAccepts = triageConfig?.maxAcceptsPerRun ?? 25;
-                triageDrain = await drainProposalsFn({
+                triageDrain = await withLlmStage("triage", () => drainProposalsFn({
                     stashDir: primaryStashDir,
                     ...(options.target ? { target: options.target } : {}),
                     config: options.config,
@@ -946,7 +982,7 @@ async function runTriagePrePass(run) {
                     excludeIds: new Set(),
                     ...(triageConfig?.maxDiffLines !== undefined ? { maxDiffLines: triageConfig.maxDiffLines } : {}),
                     judgment: resolvedPlan.triageJudgment,
-                });
+                }), { engine: resolvedPlan.triageJudgment?.engine, process: "triage.judgment" });
             }
             catch (err) {
                 warn(`[improve] triage pre-pass failed (non-fatal): ${errMessage(err)}`);
@@ -1123,7 +1159,7 @@ export function refilterProactiveLoopRefs(loopRefs, improveProfile) {
  * `runImproveStageSequence` — fn-size decomposition, no logic change).
  */
 async function runPostLoopStageOrSkip(args) {
-    const { budgetAbortController, scope, options, primaryStashDir, preparation, memoryRefsForInference, reindexFn, eventsCtx, improveProfile, resolvedPlan, runImprovePostLoopStageImpl, } = args;
+    const { budgetAbortController, scope, options, primaryStashDir, preparation, memoryRefsForInference, eventsCtx, improveProfile, resolvedPlan, runImprovePostLoopStageImpl, } = args;
     // Do not start new post-loop work after the shared wall-clock budget. The
     // result still finalizes normally, so scheduled budget exhaustion exits 0.
     const emptyPostLoopResult = {
@@ -1144,7 +1180,6 @@ async function runPostLoopStageOrSkip(args) {
         appliedCleanup: preparation.appliedCleanup,
         cleanupWarnings: preparation.cleanupWarnings,
         memoryRefsForInference,
-        reindexFn,
         eventsCtx,
         budgetSignal: budgetAbortController.signal,
         improveProfile,
@@ -1283,7 +1318,6 @@ async function runImproveStageSequence(args) {
             primaryStashDir,
             preparation,
             memoryRefsForInference,
-            reindexFn,
             eventsCtx,
             improveProfile,
             resolvedPlan,
@@ -1343,8 +1377,8 @@ async function runImproveStageSequence(args) {
  * side effects run between assembly and emit).
  */
 function finalizeImproveResult(args) {
-    const { guidance, memorySummary, memoryCleanupPlan, strategyFilteredRefs, rawPlannedRefs, indexSnapshot, triageDrain, eventsCtx, } = args;
-    const { selectedStrategy, scope, options, primaryStashDir, startMs, resolvedPlan } = args.run;
+    const { guidance, memorySummary, memoryCleanupPlan, strategyFilteredRefs, rawPlannedRefs, indexSnapshot, triageDrain, ensureIndexDurationMs, eventsCtx, } = args;
+    const { selectedStrategy, scope, options, startMs, resolvedPlan } = args.run;
     const { preparation, consolidation, memoryInference, graphExtraction, cycleMetrics, reflectsWithErrorContext, memoryInferenceDurationMs, graphExtractionDurationMs, orphansPurged, proposalsExpired, allWarnings, deadUrls, deadUrlCoverage, finalActions, } = args.seq;
     // C1 (13-bus-factor): fold the per-ref `distill-skipped` rows (~13k/run,
     // ~91% of result_json bytes) into a bounded aggregate BEFORE persistence.
@@ -1416,6 +1450,7 @@ function finalizeImproveResult(args) {
             : {}),
         ...(strategyFilteredRefs.length > 0 ? { strategyFilteredRefs } : {}),
         ...(resolvedPlan.engineUnavailable.length > 0 ? { skippedProcesses: resolvedPlan.engineUnavailable } : {}),
+        ...(options.engineProbe !== undefined ? { engineProbe: options.engineProbe } : {}),
         ...(usageReport ? { usageReport } : {}),
         actions: persistedActions,
         ...(distillSkippedAggregate ? { distillSkipped: distillSkippedAggregate } : {}),
@@ -1426,7 +1461,6 @@ function finalizeImproveResult(args) {
         ...(preparation.memoryIndexHealth !== undefined ? { memoryIndexHealth: preparation.memoryIndexHealth } : {}),
         ...(preparation.coverageGaps.length > 0 ? { coverageGaps: preparation.coverageGaps } : {}),
         ...(preparation.extract && preparation.extract.length > 0 ? { extract: preparation.extract } : {}),
-        ...(primaryStashDir !== undefined ? { evalCasesWritten: countEvalCases(primaryStashDir) } : {}),
         ...(deadUrls !== undefined && deadUrls.length > 0 ? { deadUrls } : {}),
         // Present whenever the check ran, unlike `deadUrls` above — a clean run
         // (zero dead links) still needs to tell the health report how much of
@@ -1449,6 +1483,10 @@ function finalizeImproveResult(args) {
         // `/tmp/akm-health-investigations/metrics-taxonomy-review.md` §1k / §3.
         ...(memoryInferenceDurationMs > 0 ? { memoryInferenceDurationMs } : {}),
         ...(graphExtractionDurationMs > 0 ? { graphExtractionDurationMs } : {}),
+        // R6: the start-of-run implicit reindex's wall-clock cost, when one ran
+        // (absent — not zero — when the index was already fresh and no inline
+        // rebuild was needed).
+        ...(ensureIndexDurationMs !== undefined ? { ensureIndexDurationMs } : {}),
         ...(cycleMetrics ? { cycleMetrics } : {}),
         ...(orphansPurged !== undefined ? { orphansPurged } : {}),
         ...(proposalsExpired !== undefined && proposalsExpired > 0 ? { proposalsExpired } : {}),
@@ -1606,7 +1644,6 @@ function emitImproveCompletedEvent(result, durations, eventsCtx) {
             noopActions: classCounts.noop,
             reflectsWithErrorContext: result.reflectsWithErrorContext ?? 0,
             coverageGapCount: result.coverageGaps?.length ?? 0,
-            evalCasesWritten: result.evalCasesWritten ?? 0,
             deadUrlCount: result.deadUrls?.length ?? 0,
             deadUrlsChecked: result.deadUrlCoverage?.checked ?? 0,
             deadUrlsTotal: result.deadUrlCoverage?.total ?? 0,