akm-cli 0.9.0-rc.1 → 0.9.0-rc.2

package/dist/commands/improve/improve.js

@@ -10,13 +10,15 @@ import { rethrowIfTestIsolationError } from "../../core/errors.js";
 import { appendEvent, readEvents } from "../../core/events.js";
 import { classifyImproveAction, foldDistillSkipped } from "../../core/improve-types.js";
 import { getDbPath, getStateDbPathInDataDir } from "../../core/paths.js";
+import { redactSensitiveText } from "../../core/redaction.js";
 import { openStateDatabase } from "../../core/state-db.js";
 import { info, warn } from "../../core/warn.js";
 import { closeDatabase, getEntryCount, openExistingDatabase } from "../../indexer/db/db.js";
 import { ensureIndex } from "../../indexer/ensure-index.js";
 import { akmIndex } from "../../indexer/indexer.js";
 import { resolveSourceEntries } from "../../indexer/search/search-source.js";
-import { resolveTriageJudgmentRunner } from "../../integrations/agent/runner.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, resolveWritableOverride, saveGitStash } from "../../sources/providers/git.js";
@@ -24,9 +26,9 @@ import { drainProposals } from "../proposal/drain.js";
 import { resolveDrainPolicy } from "../proposal/drain-policies.js";
 import { akmDistill } from "./distill.js";
 // Eligibility / candidate-selection predicates live in ./eligibility.
-import { buildLatestProposalTsMap, collectEligibleRefs, memoryCleanupParentRef, resolveImproveScope, shouldAnalyzeMemoryCleanup, } from "./eligibility.js";
+import { buildLatestProposalTsMap, collectEligibleRefs, collectEligibleRefsReadOnly, memoryCleanupParentRef, resolveImproveScope, shouldAnalyzeMemoryCleanup, } from "./eligibility.js";
 import { countEvalCases } from "./eval-cases.js";
-import { resolveImproveProfile, resolveProcessEnabled } from "./improve-profiles.js";
+import { resolveImprovePlan } from "./improve-strategies.js";
 // #607 per-process lock primitives live in ./locks. Imported for internal use;
 // resetHeldProcessLocks is re-exported (the test seam imports it from here).
 import { PROCESS_LOCK_DEFS, processLockPath, releaseAllProcessLocks, releaseHeldLocksIfOwned, releaseProcessLock, tryAcquireProcessLock, withOptionalProcessLock, } from "./locks.js";
@@ -91,19 +93,28 @@ export async function akmImprove(options = {}) {
     const reindexFn = options.reindexFn ?? akmIndex;
     const drainProposalsFn = options.drainProposalsFn ?? drainProposals;
     // #616 multi-cycle test seams. Default to the real module-local fns.
-    const collectEligibleRefsImpl = options.collectEligibleRefsFn ?? collectEligibleRefs;
+    const collectEligibleRefsImpl = options.collectEligibleRefsFn ?? (options.dryRun ? collectEligibleRefsReadOnly : collectEligibleRefs);
     const runImprovePreparationStageImpl = options.runImprovePreparationStageFn ?? runImprovePreparationStage;
     const runImproveLoopStageImpl = options.runImproveLoopStageFn ?? runImproveLoopStage;
     const runImprovePostLoopStageImpl = options.runImprovePostLoopStageFn ?? runImprovePostLoopStage;
     // Resolve the improve profile for this run. Profile drives type filtering,
     // process gating, and default autoAccept/limit values.
     const _earlyConfig = options.config ?? loadConfig();
-    const improveProfile = resolveImproveProfile(options.profile, _earlyConfig);
+    const resolvedPlan = options.resolvedPlan ??
+        resolveImprovePlan(options.strategy, _earlyConfig, {
+            repairValidationFailures: options.repairValidationFailures,
+        });
+    const selectedStrategy = resolvedPlan.strategy;
+    const improveSensitiveValues = collectEngineCredentialValues(_earlyConfig);
+    const improveProfile = selectedStrategy.config;
     // 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.
     options = {
         ...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,
         autoAccept: options.autoAccept ?? improveProfile.autoAccept,
         // Profile-level limit, then process-level reflect.limit as fallback.
         // CLI --limit takes precedence over both.
@@ -161,7 +172,7 @@ export async function akmImprove(options = {}) {
     // (cycle 1, in the first try) always overwrites them before any read.
     let plannedRefs = [];
     let memorySummary = { eligible: 0, derived: 0 };
-    let profileFilteredRefs = [];
+    let strategyFilteredRefs = [];
     let memoryCleanupPlan;
     let guidance;
     let triageDrain;
@@ -170,7 +181,7 @@ export async function akmImprove(options = {}) {
     // first try) and is re-run at the top of each subsequent multi-cycle cycle.
     // Re-running ensureIndex between cycles makes cycle N's gate-promoted
     // proposals visible to cycle N+1's collectEligibleRefs. Mutates the
-    // outer-scope plannedRefs/memorySummary/profileFilteredRefs/memoryCleanupPlan/
+    // outer-scope plannedRefs/memorySummary/strategyFilteredRefs/memoryCleanupPlan/
     // guidance so for maxCycles:1 the body is byte-identical to pre-#616.
     const runIndexAndCollect = async () => {
         // #339 fix: ensureIndex MUST run BEFORE collectEligibleRefs. The eligible-ref
@@ -178,7 +189,7 @@ export async function akmImprove(options = {}) {
         // 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) {
+        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.
@@ -230,15 +241,24 @@ export async function akmImprove(options = {}) {
                 }
             }
         }
-        ({ plannedRefs, memorySummary, profileFilteredRefs } = await collectEligibleRefsImpl(scope, options.stashDir, improveProfile));
+        ({
+            plannedRefs,
+            memorySummary,
+            strategyFilteredRefs = [],
+        } = await collectEligibleRefsImpl(scope, options.stashDir, improveProfile));
         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 (primaryStashDir && shouldAnalyzeMemoryCleanup(scope, memorySummary.eligible, primaryStashDir)) {
+        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.
-                await withLlmStage("memory-contradiction", () => detectAndWriteContradictions(primaryStashDir, _earlyConfig));
+                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) {
                 // Non-fatal: contradiction detection is a best-effort pass.
@@ -264,7 +284,7 @@ export async function akmImprove(options = {}) {
         if (!options.dryRun) {
             // Backstop release on process.exit() (signal handler / budget watchdog),
             // which skips the finally below. Removed in that finally on the normal path.
-            const releaseAllOnExit = () => releaseHeldLocksIfOwned(process.pid);
+            const releaseAllOnExit = () => releaseHeldLocksIfOwned();
             exitBackstop = releaseAllOnExit;
             process.on("exit", releaseAllOnExit);
             // #607 triage pre-pass: acquire triage.lock, drain the standing pending
@@ -272,14 +292,14 @@ export async function akmImprove(options = {}) {
             // a cleared queue (no `duplicate_pending` collisions) and ensureIndex
             // absorbs triage's promotions for free. Release immediately after —
             // triage.lock is not needed again until the next improve run.
-            if (primaryStashDir && resolveProcessEnabled("triage", improveProfile)) {
+            if (primaryStashDir && resolvedPlan.processes.triage.enabled) {
                 if (scope.mode === "ref") {
                     warn("[improve] triage pre-pass skipped (single-ref scope never drains the whole queue)");
                 }
                 else {
                     const triageLPath = processLockPath(lockBaseDir, "triage");
                     const triageResult = tryAcquireProcessLock(triageLPath, PROCESS_LOCK_DEFS.triage.staleAfterMs, options.skipIfLocked, "triage");
-                    if (triageResult === "skipped") {
+                    if (triageResult.state === "skipped") {
                         triageDrain = undefined;
                     }
                     else {
@@ -288,9 +308,6 @@ export async function akmImprove(options = {}) {
                             const policy = resolveDrainPolicy(triageConfig?.policy);
                             const applyMode = triageConfig?.applyMode ?? "queue";
                             const maxAccepts = triageConfig?.maxAcceptsPerRun ?? 25;
-                            const judgment = triageConfig?.judgment
-                                ? resolveTriageJudgmentRunner(triageConfig.judgment, _earlyConfig)
-                                : null;
                             triageDrain = await drainProposalsFn({
                                 stashDir: primaryStashDir,
                                 policy,
@@ -299,14 +316,14 @@ export async function akmImprove(options = {}) {
                                 dryRun: false,
                                 excludeIds: new Set(),
                                 ...(triageConfig?.maxDiffLines !== undefined ? { maxDiffLines: triageConfig.maxDiffLines } : {}),
-                                judgment,
+                                judgment: resolvedPlan.triageJudgment,
                             });
                         }
                         catch (err) {
                             warn(`[improve] triage pre-pass failed (non-fatal): ${errMessage(err)}`);
                         }
                         finally {
-                            releaseProcessLock(triageLPath);
+                            releaseProcessLock(triageResult.ownership);
                         }
                     }
                 }
@@ -318,15 +335,16 @@ export async function akmImprove(options = {}) {
         await runIndexAndCollect();
         if (options.dryRun) {
             const result = {
-                schemaVersion: 1,
+                schemaVersion: 2,
                 ok: true,
+                strategy: selectedStrategy.name,
                 scope,
                 dryRun: true,
                 ...(guidance ? { guidance } : {}),
                 memorySummary,
                 ...(memoryCleanupPlan ? { memoryCleanup: shapeMemoryCleanup(memoryCleanupPlan) } : {}),
                 plannedRefs,
-                ...(profileFilteredRefs.length > 0 ? { profileFilteredRefs } : {}),
+                ...(strategyFilteredRefs.length > 0 ? { strategyFilteredRefs } : {}),
             };
             return result;
         }
@@ -459,14 +477,15 @@ export async function akmImprove(options = {}) {
         // event per ref (#592) — the per-ref loop caused O(n) sequential state.db
         // writes that consumed ~500 s on a 9 000-ref stash. No downstream consumer
         // needs the per-ref audit trail: health's skip histogram reads the
-        // `profile_filtered_all_passes` counters from `improve_completed` metadata.
-        if (profileFilteredRefs.length > 0) {
+        // `strategy_filtered_all_passes` counters from `improve_completed` metadata.
+        if (strategyFilteredRefs.length > 0) {
             appendEvent({
                 eventType: "improve_skipped",
                 ref: undefined,
                 metadata: {
-                    reason: "profile_filtered_all_passes",
-                    count: profileFilteredRefs.length,
+                    strategy: selectedStrategy.name,
+                    reason: "strategy_filtered_all_passes",
+                    count: strategyFilteredRefs.length,
                 },
             }, eventsCtx);
         }
@@ -534,11 +553,15 @@ export async function akmImprove(options = {}) {
             if (cycleIndex > 0) {
                 await runIndexAndCollect();
                 // Re-emit the profile-filtered audit summary for this cycle's selection.
-                if (profileFilteredRefs.length > 0) {
+                if (strategyFilteredRefs.length > 0) {
                     appendEvent({
                         eventType: "improve_skipped",
                         ref: undefined,
-                        metadata: { reason: "profile_filtered_all_passes", count: profileFilteredRefs.length },
+                        metadata: {
+                            strategy: selectedStrategy.name,
+                            reason: "strategy_filtered_all_passes",
+                            count: strategyFilteredRefs.length,
+                        },
                     }, eventsCtx);
                 }
             }
@@ -563,6 +586,8 @@ export async function akmImprove(options = {}) {
                 eventsCtx,
                 initialCleanupWarnings: preEnsureCleanupWarnings,
                 improveProfile,
+                resolvedPlan,
+                strategyName: selectedStrategy.name,
                 budgetSignal: budgetAbortController.signal,
             }));
             prepGateCount += preparation.gateAutoAcceptedCount;
@@ -624,6 +649,7 @@ export async function akmImprove(options = {}) {
                     budgetMs,
                     eventsCtx,
                     improveProfile,
+                    resolvedPlan,
                     budgetSignal: budgetAbortController.signal,
                 });
             });
@@ -655,6 +681,7 @@ export async function akmImprove(options = {}) {
                 eventsCtx,
                 budgetSignal: budgetAbortController.signal,
                 improveProfile,
+                resolvedPlan,
                 consolidationRan: preparation.consolidationRan,
                 // R5: floor violations from this run's consolidate pass + the
                 // auto-accepted volume so far (prep + loop gates) for churn detection.
@@ -709,8 +736,9 @@ export async function akmImprove(options = {}) {
         // below still read `finalActions` (reflect skips are not folded).
         const { actions: persistedActions, aggregate: distillSkippedAggregate } = foldDistillSkipped(finalActions);
         const result = {
-            schemaVersion: 1,
+            schemaVersion: 2,
             ok: true,
+            strategy: selectedStrategy.name,
             scope,
             dryRun: false,
             ...(guidance ? { guidance } : {}),
@@ -737,7 +765,7 @@ export async function akmImprove(options = {}) {
                 }
                 : {}),
             plannedRefs: preparation.actionableRefs,
-            ...(profileFilteredRefs.length > 0 ? { profileFilteredRefs } : {}),
+            ...(strategyFilteredRefs.length > 0 ? { strategyFilteredRefs } : {}),
             actions: persistedActions,
             ...(distillSkippedAggregate ? { distillSkipped: distillSkippedAggregate } : {}),
             ...(preparation.validationFailures.length > 0 ? { validationFailures: preparation.validationFailures } : {}),
@@ -826,7 +854,8 @@ export async function akmImprove(options = {}) {
             eventType: "improve_failed",
             ref: scope.mode === "ref" ? scope.value : `improve:${scope.mode}:${scope.value ?? "all"}`,
             metadata: {
-                error: errMessage(err),
+                strategy: selectedStrategy.name,
+                error: redactSensitiveText(errMessage(err), improveSensitiveValues),
                 durationMs: Date.now() - startMs,
             },
         }, eventsCtx);
@@ -942,6 +971,7 @@ function emitImproveCompletedEvent(result, durations, eventsCtx) {
             ? result.scope.value
             : `improve:${result.scope.mode}:${result.scope.value ?? "all"}`,
         metadata: {
+            strategy: result.strategy,
             plannedRefs: result.plannedRefs.length,
             reflectActions: actionCounts.reflect,
             distillActions: actionCounts.distill,

package/dist/commands/improve/locks.js

@@ -5,7 +5,8 @@ import fs from "node:fs";
 import path from "node:path";
 import { ConfigError } from "../../core/errors.js";
 import { appendEvent } from "../../core/events.js";
-import { probeLock, releaseLock, releaseLockIfOwned, tryAcquireLockSync } from "../../core/file-lock.js";
+import { createLockPayload, probeLock, reclaimStaleLock, releaseLock, tryAcquireLockSync, } from "../../core/file-lock.js";
+import { withMaintenanceStartBarrier } from "../../core/maintenance-barrier.js";
 import { warn } from "../../core/warn.js";
 // #607 Lock Decomposition: fine-grained per-process locks replace the single
 // `improve.lock`. Three independent locks allow concurrent improve runs when
@@ -32,11 +33,27 @@ export function processLockPath(lockBaseDir, lockName) {
     return path.join(lockBaseDir, PROCESS_LOCK_DEFS[lockName].fileName);
 }
 export function tryAcquireProcessLock(lockPath, staleAfterMs, skipIfLocked, lockLabel) {
+    let recoveryEvent;
+    const result = withMaintenanceStartBarrier(() => tryAcquireProcessLockUnlocked(lockPath, staleAfterMs, skipIfLocked, lockLabel, (event) => {
+        recoveryEvent = event;
+    }));
+    if (recoveryEvent) {
+        try {
+            appendEvent(recoveryEvent);
+        }
+        catch {
+            /* event emission is best-effort; never block lock recovery */
+        }
+    }
+    return result;
+}
+function tryAcquireProcessLockUnlocked(lockPath, staleAfterMs, skipIfLocked, lockLabel, onRecovered) {
     fs.mkdirSync(path.dirname(lockPath), { recursive: true });
-    const lockPayload = () => JSON.stringify({ pid: process.pid, startedAt: new Date().toISOString() });
-    if (tryAcquireLockSync(lockPath, lockPayload())) {
-        heldProcessLocks.add(lockPath);
-        return "acquired";
+    const lockPayload = () => createLockPayload({ startedAt: new Date().toISOString() });
+    let ownership = tryAcquireLockSync(lockPath, lockPayload());
+    if (ownership) {
+        heldProcessLocks.add(ownership);
+        return { state: "acquired", ownership };
     }
     const probe = probeLock(lockPath, { staleAfterMs });
     // Race: the holder released the lock between our failed `tryAcquireLockSync`
@@ -45,9 +62,10 @@ export function tryAcquireProcessLock(lockPath, staleAfterMs, skipIfLocked, lock
     // would warn/throw with a null PID for a lock that nobody actually holds.
     // (Mirrors the absent/stale reclaim-and-retry in `acquireExtractSessionLock`.)
     if (probe.state === "absent") {
-        if (tryAcquireLockSync(lockPath, lockPayload())) {
-            heldProcessLocks.add(lockPath);
-            return "acquired";
+        ownership = tryAcquireLockSync(lockPath, lockPayload());
+        if (ownership) {
+            heldProcessLocks.add(ownership);
+            return { state: "acquired", ownership };
         }
         // Re-grabbed by another racer in the window — fall through and treat as held.
     }
@@ -63,52 +81,55 @@ export function tryAcquireProcessLock(lockPath, staleAfterMs, skipIfLocked, lock
         })()
         : null;
     if (probe.state === "stale") {
-        try {
-            appendEvent({
-                eventType: "improve_lock_recovered",
-                metadata: {
-                    lockName: lockLabel,
-                    stalePid: lock?.pid ?? null,
-                    lockedAt: lock?.startedAt ?? null,
-                    recoveredAt: new Date().toISOString(),
-                    lockAgeMs: probe.ageMs ?? null,
-                    reason: probe.reason === "pid_dead" ? "pid_not_alive" : probe.reason,
-                },
-            });
-        }
-        catch {
-            /* event emission is best-effort; never block lock recovery */
+        if (!reclaimStaleLock(lockPath, probe)) {
+            if (skipIfLocked) {
+                warn(`[improve] ${lockLabel} lock changed ownership during stale recovery; skipping (--skip-if-locked)`);
+                return { state: "skipped" };
+            }
+            throw new ConfigError(`akm improve ${lockLabel} is already running. Delete ${lockPath} to force.`, "INVALID_CONFIG_FILE");
         }
-        releaseLock(lockPath);
-        if (tryAcquireLockSync(lockPath, lockPayload())) {
-            heldProcessLocks.add(lockPath);
-            return "acquired";
+        onRecovered({
+            eventType: "improve_lock_recovered",
+            metadata: {
+                lockName: lockLabel,
+                stalePid: lock?.pid ?? null,
+                lockedAt: lock?.startedAt ?? null,
+                recoveredAt: new Date().toISOString(),
+                lockAgeMs: probe.ageMs ?? null,
+                reason: probe.reason === "pid_dead" ? "pid_not_alive" : probe.reason,
+            },
+        });
+        ownership = tryAcquireLockSync(lockPath, lockPayload());
+        if (ownership) {
+            heldProcessLocks.add(ownership);
+            return { state: "acquired", ownership };
         }
         if (skipIfLocked) {
             warn(`[improve] ${lockLabel} lock acquired by another run during stale recovery; skipping (--skip-if-locked)`);
-            return "skipped";
+            return { state: "skipped" };
         }
         throw new ConfigError(`akm improve ${lockLabel} is already running. Delete ${lockPath} to force.`, "INVALID_CONFIG_FILE");
     }
     if (skipIfLocked) {
         warn(`[improve] ${lockLabel} lock held by another run (PID ${lock?.pid}, started ${lock?.startedAt}); skipping (--skip-if-locked)`);
-        return "skipped";
+        return { state: "skipped" };
     }
     throw new ConfigError(`akm improve ${lockLabel} is already running (PID ${lock?.pid}, started ${lock?.startedAt}). Delete ${lockPath} to force.`, "INVALID_CONFIG_FILE");
 }
-export function releaseProcessLock(lockPath) {
+export function releaseProcessLock(ownership) {
+    if (!heldProcessLocks.has(ownership))
+        return;
     try {
-        fs.unlinkSync(lockPath);
+        releaseLock(ownership);
     }
-    catch {
-        // ignore
+    finally {
+        heldProcessLocks.delete(ownership);
     }
-    heldProcessLocks.delete(lockPath);
 }
 export function releaseAllProcessLocks() {
-    for (const p of heldProcessLocks) {
+    for (const ownership of heldProcessLocks) {
         try {
-            fs.unlinkSync(p);
+            releaseLock(ownership);
         }
         catch {
             // ignore
@@ -119,12 +140,12 @@ export function releaseAllProcessLocks() {
 /**
  * Ownership-safe release of every currently-held lock, for the `process.on("exit")`
  * backstop (signal handler / budget watchdog paths that skip the normal finally).
- * Uses `releaseLockIfOwned` so a lock another PID legitimately re-acquired after a
- * stale recovery is never deleted. Does NOT clear the Set (the process is exiting).
+ * Uses exact ownership handles so a lock legitimately re-acquired after stale
+ * recovery is never deleted. Does NOT clear the Set (the process is exiting).
  */
-export function releaseHeldLocksIfOwned(pid) {
-    for (const p of heldProcessLocks) {
-        releaseLockIfOwned(p, pid);
+export function releaseHeldLocksIfOwned() {
+    for (const ownership of heldProcessLocks) {
+        releaseLock(ownership);
     }
 }
 /**
@@ -136,19 +157,19 @@ export function releaseHeldLocksIfOwned(pid) {
  * Behaviour matches the hand-rolled `acquired = tryAcquire(...) === "acquired";
  * …run stage…; if (acquired) release` idiom it replaces:
  *   - When the lock is held and `skipIfLocked` is set, `tryAcquireProcessLock`
- *     returns "skipped" → the stage still runs (unlocked), nothing to release.
+ *     returns `state: "skipped"` → the stage still runs (unlocked), nothing to release.
  *   - When the lock is held and `skipIfLocked` is NOT set, `tryAcquireProcessLock`
  *     throws (propagated here before `body` runs; nothing acquired, nothing released).
  *   - The process-exit backstop (`releaseHeldLocksIfOwned`) still covers a
  *     `process.exit` that skips this `finally`.
  */
 export async function withOptionalProcessLock(opts, body) {
-    const acquired = tryAcquireProcessLock(opts.lockPath, opts.staleAfterMs, opts.skipIfLocked, opts.label) === "acquired";
+    const acquisition = tryAcquireProcessLock(opts.lockPath, opts.staleAfterMs, opts.skipIfLocked, opts.label);
     try {
         return await body();
     }
     finally {
-        if (acquired)
-            releaseProcessLock(opts.lockPath);
+        if (acquisition.state === "acquired")
+            releaseProcessLock(acquisition.ownership);
     }
 }