akm-cli 0.9.0-rc.8 → 0.9.0

package/dist/commands/improve/improve.js

@@ -4,11 +4,13 @@
 import fs from "node:fs";
 import path from "node:path";
 import { assertNever } from "../../core/assert.js";
+import { parseRefInput } from "../../core/asset/resolve-ref.js";
 import { daysToMs } from "../../core/common.js";
-import { loadConfig } from "../../core/config/config.js";
-import { rethrowIfTestIsolationError } from "../../core/errors.js";
+import { bundlesToSourceEntries, loadConfig } from "../../core/config/config.js";
+import { ConfigError, rethrowIfTestIsolationError, UsageError } from "../../core/errors.js";
 import { appendEvent, readEvents } from "../../core/events.js";
 import { classifyImproveAction, foldDistillSkipped } from "../../core/improve-types.js";
+import { resolveMutationTarget } from "../../core/mutation-target.js";
 import { getDbPath, getStateDbPathInDataDir } from "../../core/paths.js";
 import { redactSensitiveText } from "../../core/redaction.js";
 import { openStateDatabase } from "../../core/state-db.js";
@@ -16,16 +18,16 @@ import { info, warn } from "../../core/warn.js";
 import { resolveWritable, resolveWriteTarget } from "../../core/write-source.js";
 import { ensureIndex } from "../../indexer/ensure-index.js";
 import { akmIndex } from "../../indexer/indexer.js";
-import { resolveSourceEntries } from "../../indexer/search/search-source.js";
+import { resolveEntryContentDir, resolveSourceEntries } from "../../indexer/search/search-source.js";
 import { collectEngineCredentialValues } from "../../integrations/agent/engine-resolution.js";
 import { materializeLlmRunnerConnection } from "../../integrations/agent/runner.js";
 import { installLlmUsagePersistence } 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";
 import { drainProposals } from "../proposal/drain.js";
 import { resolveDrainPolicy } from "../proposal/drain-policies.js";
+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";
@@ -34,7 +36,6 @@ import { resolveImprovePlan } from "./improve-strategies.js";
 import { improveLockPath, MIN_IMPROVE_LOCK_STALE_MS, releaseImproveLock, tryAcquireImproveLock } from "./locks.js";
 // The cycle loop / post-loop / maintenance stages live in ./loop-stages.
 import { runImproveLoopStage, runImprovePostLoopStage } from "./loop-stages.js";
-import { detectAndWriteContradictions } from "./memory/memory-contradiction-detect.js";
 import { analyzeMemoryCleanup } from "./memory/memory-improve.js";
 // The pre-loop preparation pipeline lives in ./preparation.
 import { runImprovePreparationStage } from "./preparation.js";
@@ -42,7 +43,6 @@ import { DEFAULT_DUE_DAYS, filterProactiveDue } from "./proactive-maintenance.js
 import { akmReflect } from "./reflect.js";
 import { createRunContext } from "./run-context.js";
 import { errMessage } from "./shared.js";
-import { shouldReadLegacyBareImproveState } from "./source-identity.js";
 // Re-exported from ./loop-stages for test importers (improve-db-locking).
 export { runImproveMaintenancePasses } from "./loop-stages.js";
 export function renderSyncCommitMessage(template, result, nowMs) {
@@ -98,10 +98,19 @@ export async function akmImprove(options = {}) {
     let memorySummary = { eligible: 0, derived: 0 };
     let strategyFilteredRefs = [];
     let memoryCleanupPlan;
+    let autonomyGatedDirectLanes = [];
     let guidance;
     let triageDrain;
     let improveLockOwnership;
     let exitBackstop;
+    // I1: open a single state.db connection for the main improve run so all
+    // appendEvent calls reuse one handle instead of open/migrate/close per call.
+    let eventsDb;
+    // Start boundary-pinned for prepass telemetry, then replace this binding with
+    // the long-lived handle after the prepass. The usage sink resolves it per
+    // append, so one owner and counter span both lifecycle phases.
+    let eventsCtx = { dbPath: resolvedStateDbPath };
+    let disposeLlmUsageSink = () => { };
     const releaseRunLock = () => {
         const ownership = improveLockOwnership;
         if (!ownership)
@@ -114,6 +123,13 @@ export async function akmImprove(options = {}) {
             // Best-effort cleanup. Exact ownership prevents deleting a successor.
         }
     };
+    const commitStashBatch = makeCommitStashBatch({
+        run: setup,
+        getInitialGitPaths: () => initialGitPaths,
+        // Captured via getter: the live `eventsCtx` binding is reassigned after the
+        // prepass, and the catch-path sync must write through the current context.
+        getEventsCtx: () => eventsCtx,
+    });
     if (!options.dryRun) {
         const remainingBudget = budgetAbortController.signal.remainingBudgetMs;
         clearBudgetTimer = armBudgetWatchdog(Math.max(1, remainingBudget ?? budgetMs), budgetAbortController);
@@ -129,6 +145,7 @@ export async function akmImprove(options = {}) {
                 return buildLockSkippedResult(selectedStrategy.name, scope, options.runId);
             }
             improveLockOwnership = acquisition.ownership;
+            disposeLlmUsageSink = installLlmUsagePersistence(() => eventsCtx);
             exitBackstop = releaseRunLock;
             process.on("exit", exitBackstop);
             initialGitPaths =
@@ -144,6 +161,7 @@ export async function akmImprove(options = {}) {
         memorySummary = collected.memorySummary;
         strategyFilteredRefs = collected.strategyFilteredRefs;
         memoryCleanupPlan = collected.memoryCleanupPlan;
+        autonomyGatedDirectLanes = collected.autonomyGatedDirectLanes;
         guidance = collected.guidance;
         preEnsureCleanupWarnings.push(...collected.warnings);
         if (options.dryRun) {
@@ -153,6 +171,9 @@ export async function akmImprove(options = {}) {
         }
     }
     catch (err) {
+        // If the live prepass fails, emit its summary and clear the owning sink
+        // before any run teardown. The disposer is idempotent with the main finalizer.
+        disposeLlmUsageSink();
         clearBudgetTimer();
         if (exitBackstop) {
             process.removeListener("exit", exitBackstop);
@@ -161,25 +182,6 @@ export async function akmImprove(options = {}) {
         releaseRunLock();
         throw err;
     }
-    // I1: open a single state.db connection for the entire improve run so all
-    // appendEvent calls reuse one handle instead of open/migrate/close per call.
-    let eventsDb;
-    // `eventsCtx` is read by the main catch (improve_failed) and finally, so it
-    // lives in the outer scope. It is always assigned at the top of the try.
-    // Pinned to the boundary snapshot so the fallback per-call `appendEvent`
-    // opens (when the long-lived handle below fails to open) never re-read env.
-    let eventsCtx = { dbPath: resolvedStateDbPath };
-    // #576: clears the per-run LLM usage sink. Defaults to a no-op until the sink
-    // is installed inside the try; the `finally` always calls it.
-    let disposeLlmUsageSink = () => { };
-    const commitStashBatch = makeCommitStashBatch({
-        run: setup,
-        getInitialGitPaths: () => initialGitPaths,
-        // Captured via getter: the live `eventsCtx` binding is reassigned inside
-        // the try below, and the catch-path sync must write through whichever
-        // context is current (#662 / P6/P7 in the chunk-7 ledger).
-        getEventsCtx: () => eventsCtx,
-    });
     try {
         try {
             eventsDb = openStateDatabase(resolvedStateDbPath);
@@ -191,11 +193,6 @@ export async function akmImprove(options = {}) {
             // still pinned to the boundary-resolved path, never a live env re-read.
             eventsCtx = { dbPath: resolvedStateDbPath };
         }
-        // #576: persist per-call LLM usage telemetry for this run as `llm_usage`
-        // events, reusing the same boundary-pinned events context (and long-lived
-        // handle when available). Disposed in `finally` so the sink never leaks
-        // across runs. Wrapping is best-effort end to end — see usage-telemetry.ts.
-        disposeLlmUsageSink = installLlmUsagePersistence(eventsCtx);
         // WI-9.10: construct the run's RunContext here — the first point after
         // run-setup where config/stashDir/eventsCtx/proposalsCtx/sourceRun/dryRun
         // are all in hand. See buildImproveRunContext for exactly which
@@ -206,6 +203,7 @@ export async function akmImprove(options = {}) {
             strategyFilteredRefs,
             plannedRefs,
             memoryCleanupPlan,
+            autonomyGatedDirectLanes,
             memorySummary,
             preEnsureCleanupWarnings,
             eventsCtx,
@@ -272,13 +270,33 @@ export async function akmImprove(options = {}) {
         }
     }
 }
-// ── akmImprove run-setup / stage-sequencing / run-teardown units ────────────
-// WI-7.7 step 1 (R31): the 810-line orchestrator body is decomposed into the
-// named units below. The two-try topology, all four early-exit paths, and the
-// exit-path cleanup ordering stay in akmImprove itself (they are the teardown
-// contract — see P1–P8 in the chunk-7 ledger); the units hold the straight-line
-// mass. Args objects carry the run-scoped values; return values replace the
-// old closure-mutated outer `let`s.
+/** Resolve a dry-run inspection source without adapting it into a write target. */
+function resolveImproveReadSource(config, scopedRef, explicitTarget, fallbackStashDir) {
+    if (scopedRef?.origin && explicitTarget && scopedRef.origin !== explicitTarget) {
+        throw new UsageError(`Qualified ref bundle "${scopedRef.origin}" conflicts with --target "${explicitTarget}".`, "INVALID_FLAG_VALUE", `Drop --target or use --target ${scopedRef.origin}.`);
+    }
+    const selector = scopedRef?.origin ?? explicitTarget ?? config.defaultWriteTarget;
+    if (!selector && fallbackStashDir) {
+        return { source: { name: "stash", path: fallbackStashDir } };
+    }
+    const configuredSelector = selector ?? config.defaultBundle;
+    if (configuredSelector) {
+        const entry = bundlesToSourceEntries(config)?.find((source) => source.name === configuredSelector);
+        if (!entry) {
+            throw new UsageError(`No source named "${configuredSelector}" is configured. Run \`akm bundle list\` to see available sources.`, "INVALID_FLAG_VALUE");
+        }
+        const sourcePath = resolveEntryContentDir(entry);
+        if (!sourcePath) {
+            throw new ConfigError(`Source "${configuredSelector}" has no resolvable on-disk path; improve cannot inspect this entry.`, "INVALID_CONFIG_FILE");
+        }
+        return { selector: configuredSelector, source: { name: configuredSelector, path: sourcePath } };
+    }
+    const implicit = resolveSourceEntries(undefined, config)[0];
+    if (!implicit) {
+        throw new ConfigError("no source configured; run `akm bundle create`", "STASH_DIR_NOT_FOUND");
+    }
+    return { source: { name: implicit.registryId ?? "stash", path: implicit.path } };
+}
 /**
  * Run-setup: budget/watchdog plumbing, scope + seam resolution, the invocation
  * plan, write-target resolution, the profile-defaulted options rebuild, and
@@ -316,18 +334,32 @@ function resolveImproveRunSetup(options) {
     const selectedStrategy = resolvedPlan.strategy;
     const improveSensitiveValues = collectEngineCredentialValues(_earlyConfig);
     const improveProfile = selectedStrategy.config;
-    const writeTarget = options.writeTarget ??
-        (options.target || _earlyConfig.defaultWriteTarget || !options.stashDir
-            ? resolveWriteTarget(_earlyConfig, options.target, { requireWritable: !options.dryRun })
-            : {
-                source: { kind: "filesystem", name: "stash", path: options.stashDir },
-                config: {
-                    type: "filesystem",
-                    name: "stash",
-                    path: options.stashDir,
-                    writable: true,
-                },
-            });
+    const scopedRef = scope.mode === "ref" && scope.value ? parseRefInput(scope.value) : undefined;
+    const readSource = options.dryRun
+        ? options.writeTarget
+            ? { selector: options.writeTarget.selector, source: options.writeTarget.source }
+            : resolveImproveReadSource(_earlyConfig, scopedRef, options.target, options.stashDir)
+        : undefined;
+    const writeTarget = options.dryRun
+        ? undefined
+        : scopedRef?.origin
+            ? resolveMutationTarget(_earlyConfig, scopedRef, options.writeTarget?.source.name ?? options.target).target
+            : (options.writeTarget ??
+                (options.target || _earlyConfig.defaultWriteTarget || !options.stashDir
+                    ? resolveWriteTarget(_earlyConfig, options.target)
+                    : {
+                        source: { kind: "filesystem", name: "stash", path: options.stashDir },
+                        config: {
+                            type: "filesystem",
+                            name: "stash",
+                            path: options.stashDir,
+                            writable: true,
+                        },
+                    }));
+    const selectedSource = writeTarget?.source ?? readSource?.source;
+    if (!selectedSource)
+        throw new ConfigError("improve could not resolve a source", "STASH_DIR_NOT_FOUND");
+    const selectedSelector = writeTarget?.selector ?? readSource?.selector;
     // Apply profile defaults — CLI flags take precedence over profile defaults.
     // Rebuild options with effective values so all downstream stage functions
     // automatically pick up the profile-driven defaults.
@@ -336,17 +368,15 @@ function resolveImproveRunSetup(options) {
         // Pin nested calls and quality gates to the same config snapshot as the
         // invocation plan. They must never reload a changed config mid-run.
         config: _earlyConfig,
-        target: writeTarget.selector,
-        sourceName: writeTarget.source.name,
-        writeTarget,
-        stashDir: writeTarget.source.path,
+        target: selectedSelector,
+        sourceName: selectedSource.name,
+        ...(writeTarget ? { writeTarget } : {}),
+        stashDir: selectedSource.path,
         consolidateOptions: {
             ...options.consolidateOptions,
-            target: writeTarget.selector,
-            writeTarget,
+            target: selectedSelector,
+            ...(writeTarget ? { writeTarget } : {}),
         },
-        legacyBareState: options.legacyBareState ??
-            shouldReadLegacyBareImproveState(writeTarget.source.name, writeTarget.source.path, _earlyConfig),
         // Profile-level limit, then process-level reflect.limit as fallback.
         // CLI --limit takes precedence over both.
         limit: options.limit ?? improveProfile?.processes?.reflect?.limit ?? improveProfile.limit,
@@ -465,7 +495,7 @@ function recordImproveFailure(err, run, eventsCtx) {
  */
 async function indexAndCollect(args) {
     const { signal } = args;
-    const { scope, options, primaryStashDir, improveProfile, resolvedPlan, _earlyConfig, ensureIndexFn, collectEligibleRefsImpl, } = args.run;
+    const { scope, options, primaryStashDir, improveProfile, _earlyConfig, ensureIndexFn, collectEligibleRefsImpl } = args.run;
     const warnings = [];
     let plannedRefs = [];
     let memorySummary = { eligible: 0, derived: 0 };
@@ -533,31 +563,23 @@ async function indexAndCollect(args) {
         plannedRefs,
         memorySummary,
         strategyFilteredRefs = [],
-    } = await collectEligibleRefsImpl(scope, options.stashDir, improveProfile));
+    } = await collectEligibleRefsImpl(scope, options.stashDir, improveProfile, _earlyConfig));
     const cleanupParentRef = memoryCleanupParentRef(scope, options.stashDir);
-    // M-1 (#367): Run contradiction-detection BEFORE analyzeMemoryCleanup so
-    // the SCC resolver in resolveFamilyContradictions has edges to work on.
-    // Best-effort: failures are warnings, never fatal.
-    if (!options.dryRun &&
-        primaryStashDir &&
-        shouldAnalyzeMemoryCleanup(scope, memorySummary.eligible, primaryStashDir)) {
-        try {
-            // Reuse the config resolved at the top of the run instead of a second load.
-            const contradictionDetectionFn = options.contradictionDetectionFn ?? detectAndWriteContradictions;
-            await withLlmStage("memory-contradiction", () => contradictionDetectionFn(primaryStashDir, _earlyConfig, undefined, improveProfile, resolvedPlan.processes.consolidate.runner
-                ? materializeLlmRunnerConnection(resolvedPlan.processes.consolidate.runner)
-                : null), { engine: resolvedPlan.processes.consolidate.runner?.engine, process: "consolidate" });
-        }
-        catch (err) {
-            if (signal.aborted)
-                throw err;
-            // Non-fatal: contradiction detection is a best-effort pass.
-            warn(`[improve] contradiction detection failed (non-fatal): ${errMessage(err)}`);
-        }
-    }
-    const memoryCleanupPlan = shouldAnalyzeMemoryCleanup(scope, memorySummary.eligible, primaryStashDir)
+    // 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
+    // decides whether each lane would have run, which is also what decides whether
+    // a gated lane is worth REPORTING. A lane that was never eligible was not
+    // suppressed by the gate, so claiming it was would be noise.
+    const cleanupEligible = shouldAnalyzeMemoryCleanup(scope, memorySummary.eligible, primaryStashDir);
+    // Cleanup remains independent of the disabled contradiction writer.
+    const memoryCleanupPlan = cleanupEligible
         ? analyzeMemoryCleanup(primaryStashDir, cleanupParentRef ? { parentRef: cleanupParentRef } : undefined)
         : undefined;
+    const cleanupWouldMutate = Boolean(memoryCleanupPlan &&
+        (memoryCleanupPlan.pruneCandidates.length > 0 ||
+            memoryCleanupPlan.beliefStateTransitions.length > 0 ||
+            memoryCleanupPlan.relativeDateCandidates.length > 0));
+    const autonomyGatedDirectLanes = cleanupWouldMutate && !isAutonomyLaneAllowed("memoryCleanup", _earlyConfig) ? ["memoryCleanup"] : [];
     const guidance = memorySummary.eligible > 0
         ? "Improve folds memory cleanup into the same proposal queue: speculative promotions still go through reflect/distill proposals, while high-confidence redundant derived memories are moved into a recoverable cleanup archive instead of being left active in the stash."
         : undefined;
@@ -566,6 +588,7 @@ async function indexAndCollect(args) {
         memorySummary,
         strategyFilteredRefs: strategyFilteredRefs ?? [],
         memoryCleanupPlan,
+        autonomyGatedDirectLanes,
         guidance,
         warnings,
     };
@@ -655,8 +678,6 @@ function makeCommitStashBatch(deps) {
         }
         const saveGitStashFn = options.saveGitStashFn ?? saveGitStash;
         const writableOverride = writeTarget ? resolveWritable(writeTarget.config) : resolveWritableOverride(_earlyConfig);
-        // pushOnCommit is deprecated and fully ignored (Decision 6, WI-9.6b) — it no
-        // longer participates in this fallback chain.
         const push = options.sync?.push ?? improveProfile.sync?.push ?? true;
         const message = renderSyncCommitMessage(effectiveSync.message ?? "akm improve auto-sync", messageContext, Date.now());
         try {
@@ -721,17 +742,17 @@ function preloadRejectedProposals() {
  * immediately before the loop so external proposal writes that occurred
  * before this run acquired its lock are visible.
  */
-export function refilterProactiveLoopRefs(loopRefs, options, improveProfile) {
+export function refilterProactiveLoopRefs(loopRefs, improveProfile) {
     // Re-read cooldown timestamps immediately before execution so external
     // proposal writes that occurred before this run acquired its lock are visible.
     const proactiveLoopRefs = loopRefs.filter((r) => r.eligibilitySource === "proactive");
     let postLockLoopRefs = loopRefs;
     if (proactiveLoopRefs.length > 0) {
         const proactiveRefStrs = proactiveLoopRefs.map((r) => r.ref);
-        // Chunk-5 flip F5e — dual-arm the proposal reverse map on item_ref too.
+        // Correlate proposal timestamps on each candidate's durable key.
         const proactiveItemRefByRef = new Map(proactiveLoopRefs.map((r) => [r.ref, r.itemRef]));
-        const freshReflectTs = buildLatestProposalTsMap(proactiveRefStrs, "reflect", options.sourceName, options.legacyBareState, proactiveItemRefByRef);
-        const freshDistillTs = buildLatestProposalTsMap(proactiveRefStrs, "distill", options.sourceName, options.legacyBareState, proactiveItemRefByRef);
+        const freshReflectTs = buildLatestProposalTsMap(proactiveRefStrs, "reflect", proactiveItemRefByRef);
+        const freshDistillTs = buildLatestProposalTsMap(proactiveRefStrs, "distill", proactiveItemRefByRef);
         const pmDueDays = improveProfile.processes?.proactiveMaintenance?.dueDays ?? DEFAULT_DUE_DAYS;
         const stillDue = new Set(filterProactiveDue(proactiveLoopRefs, freshReflectTs, freshDistillTs, pmDueDays, Date.now()).map((r) => r.ref));
         const dropped = proactiveLoopRefs.filter((r) => !stillDue.has(r.ref));
@@ -776,11 +797,9 @@ async function runPostLoopStageOrSkip(args) {
         improveProfile,
         resolvedPlan,
         consolidationRan: preparation.consolidationRan,
-        // R5: floor violations from this run's consolidate pass, plus the accepted
-        // volume — hardcoded 0 since the 0.9.0 confidence-gate deletion — for churn
-        // detection.
+        // R5: floor violations from this run's consolidate pass, for the collapse
+        // detector's merge-floor advisory.
         consolidationMergeFloorViolations: preparation.consolidation.mergeFloorViolations ?? 0,
-        acceptedActions: 0,
     });
 }
 /**
@@ -805,6 +824,24 @@ async function runImproveStageSequence(args) {
             },
         }, eventsCtx);
     }
+    // D8 — one event per lane the autonomy gate downgraded, naming the lane AND
+    // the config key that would enable it. This is the difference between a gate
+    // and a silent no-op: whatever the user would have seen happen, they now see
+    // explained. `health` already aggregates `improve_skipped` by reason
+    // (buildImproveSkipSummary), so these surface there without new machinery.
+    for (const lane of [...args.run.resolvedPlan.autonomyGated, ...describeGatedLanes(args.autonomyGatedDirectLanes)]) {
+        warn(`[improve] ${lane.lane} skipped — it ${lane.reason}. Set \`${lane.configKey}: true\` to enable it.`);
+        appendEvent({
+            eventType: "improve_skipped",
+            ref: undefined,
+            metadata: {
+                strategy: selectedStrategy.name,
+                reason: "autonomy_gated",
+                lane: lane.lane,
+                configKey: lane.configKey,
+            },
+        }, eventsCtx);
+    }
     // Single prep->loop->post-loop pass, run under the invocation's lock.
     // Accumulators are direct assignments from the single pass's results.
     let preparation;
@@ -844,7 +881,7 @@ async function runImproveStageSequence(args) {
         preparation = await runPreparation();
         const rejectedProposalsByRef = preloadRejectedProposals();
         const runLoop = () => {
-            const postLockLoopRefs = refilterProactiveLoopRefs(preparation.loopRefs, options, improveProfile);
+            const postLockLoopRefs = refilterProactiveLoopRefs(preparation.loopRefs, improveProfile);
             return runImproveLoopStageImpl({
                 ctx,
                 primaryStashDir,