akm-cli 0.9.11 → 0.9.13

package/dist/commands/improve/extract.js

@@ -31,6 +31,7 @@ import { getImproveProcessConfig, loadConfig } from "../../core/config/config.js
 import { ConfigError, UsageError } from "../../core/errors.js";
 import { appendEvent } from "../../core/events.js";
 import { createLockPayload, probeLock, reclaimStaleLock, releaseLock, tryAcquireLockSync, } from "../../core/file-lock.js";
+import { EXTRACT_INFRASTRUCTURE_SKIP_REASONS } from "../../core/improve-types.js";
 import { tryAcquireMaintenanceBarrier } from "../../core/maintenance-barrier.js";
 import { redactErrorBody } from "../../core/redaction.js";
 import { resolveStashStandards } from "../../core/standards/resolve-stash-standards.js";
@@ -214,6 +215,24 @@ export function resolveStandaloneExtractPlan(config, selection) {
     });
 }
 // ── Helpers ──────────────────────────────────────────────────────────────────
+/** An extract envelope for a run that processed no sessions; `engine`/`engineKind` only once a runner is resolved. */
+function emptyExtractResult(args) {
+    return {
+        schemaVersion: 1,
+        ok: args.ok,
+        shape: "extract-result",
+        dryRun: args.dryRun,
+        type: args.type,
+        sessionsProcessed: 0,
+        sessionsSkipped: 0,
+        candidatesCreated: 0,
+        proposals: [],
+        sessions: [],
+        warnings: [args.warning],
+        durationMs: Date.now() - args.startMs,
+        ...(args.llmRunner ? { engine: args.llmRunner.engine, engineKind: args.llmRunner.kind } : {}),
+    };
+}
 /**
  * Parse a since-string into an absolute ms-epoch cutoff. Accepts:
  *   - ISO timestamps (parsed via Date.parse)
@@ -853,6 +872,7 @@ function recordExtractSessionOutcome(args) {
                 preFilterInputCount: result.preFilter.inputCount,
                 preFilterOutputCount: result.preFilter.outputCount,
                 preFilterTruncatedCount: result.preFilter.truncatedCount,
+                engine: result.engine,
                 ...(result.skipReason ? { skipReason: result.skipReason } : {}),
                 ...(result.sessionLogPath ? { logPath: result.sessionLogPath } : {}),
                 ...(result.sessionAssetRef ? { sessionAssetRef: result.sessionAssetRef } : {}),
@@ -864,7 +884,8 @@ function recordExtractSessionOutcome(args) {
     }
 }
 function accountExtractSessionResult(result, triageEnabled, output) {
-    output.sessions.push(result);
+    const stamped = { ...result, engine: output.engine };
+    output.sessions.push(stamped);
     if (triageEnabled) {
         const preempted = result.skipReason === "read_failed" ||
             result.skipReason === "too_short" ||
@@ -883,6 +904,7 @@ function accountExtractSessionResult(result, triageEnabled, output) {
     else
         output.processedCount += 1;
     output.allProposalIds.push(...result.proposalIds);
+    return stamped;
 }
 /**
  * Iterate the discovered candidate sessions: enforce the per-run cap, take the
@@ -913,6 +935,7 @@ async function runExtractSessionLoop(args) {
         standardsContext: extractStandardsContext,
     };
     const output = {
+        engine: llmRunner.engine,
         sessions: [],
         processedCount: 0,
         skippedCount: 0,
@@ -947,14 +970,14 @@ async function runExtractSessionLoop(args) {
             break;
         const { summary } = plan;
         if (plan.kind === "skip") {
-            accountExtractSessionResult(plan.result, triage.enabled, output);
+            const accounted = accountExtractSessionResult(plan.result, triage.enabled, output);
             recordExtractSessionOutcome({
                 stateDb,
                 trackingEnabled,
                 dryRun,
                 harness: harness.name,
                 summary,
-                result: plan.result,
+                result: accounted,
                 sourceRun,
             });
             continue;
@@ -988,14 +1011,14 @@ async function runExtractSessionLoop(args) {
                 triage,
             });
             if ("skip" in executionGate) {
-                accountExtractSessionResult(executionGate.skip, triage.enabled, output);
+                const accounted = accountExtractSessionResult(executionGate.skip, triage.enabled, output);
                 recordExtractSessionOutcome({
                     stateDb,
                     trackingEnabled,
                     dryRun,
                     harness: harness.name,
                     summary,
-                    result: executionGate.skip,
+                    result: accounted,
                     sourceRun,
                 });
                 refillModelSlot();
@@ -1009,14 +1032,14 @@ async function runExtractSessionLoop(args) {
                 for (const warning of result.warnings)
                     topLevelWarnings.push(`session ${summary.sessionId}: ${warning}`);
             }
-            accountExtractSessionResult(result, triage.enabled, output);
+            const accounted = accountExtractSessionResult(result, triage.enabled, output);
             recordExtractSessionOutcome({
                 stateDb,
                 trackingEnabled,
                 dryRun,
                 harness: harness.name,
                 summary,
-                result,
+                result: accounted,
                 sourceRun,
             });
         }
@@ -1098,9 +1121,11 @@ function resolveExtractRunConfig(options, config, extractProcess, activeProfile)
     // Cap on NEW sessions LLM-processed per run; 0 disables. Absent = default.
     // Bounds per-run wall time / LLM cost so a backlog can't push a run past its
     // task timeout — the overflow stays unseen and is picked up by later runs.
-    const maxSessionsPerRun = typeof extractProcess?.maxSessionsPerRun === "number"
-        ? extractProcess.maxSessionsPerRun
-        : DEFAULT_MAX_SESSIONS_PER_RUN;
+    const maxSessionsPerRun = options.since
+        ? 0
+        : typeof extractProcess?.maxSessionsPerRun === "number"
+            ? extractProcess.maxSessionsPerRun
+            : DEFAULT_MAX_SESSIONS_PER_RUN;
     // Default discovery window — process config can override the built-in 24h.
     const effectiveSince = options.since ?? extractProcess?.defaultSince;
     // #626 — resolve the triage gate config once per run. Default-off → the
@@ -1166,7 +1191,7 @@ function resolveExtractRunConfig(options, config, extractProcess, activeProfile)
  * not-found envelope) or the discovery-window listing. Extracted verbatim from
  * `akmExtract`; the 48h default-since floor and location filter are unchanged.
  */
-function discoverExtractCandidates(options, harness, effectiveSince, startMs, dryRun) {
+function discoverExtractCandidates(options, harness, effectiveSince, startMs, dryRun, llmRunner) {
     if (options.sessionId) {
         const all = harness.listSessions({
             ...(options.location ? { location: options.location } : {}),
@@ -1174,20 +1199,14 @@ function discoverExtractCandidates(options, harness, effectiveSince, startMs, dr
         const target = all.find((s) => s.sessionId === options.sessionId);
         if (!target) {
             return {
-                notFound: {
-                    schemaVersion: 1,
+                notFound: emptyExtractResult({
                     ok: false,
-                    shape: "extract-result",
                     dryRun,
                     type: options.type,
-                    sessionsProcessed: 0,
-                    sessionsSkipped: 0,
-                    candidatesCreated: 0,
-                    proposals: [],
-                    sessions: [],
-                    warnings: [`session ${options.sessionId} not found for harness ${options.type}`],
-                    durationMs: Date.now() - startMs,
-                },
+                    warning: `session ${options.sessionId} not found for harness ${options.type}`,
+                    startMs,
+                    llmRunner,
+                }),
             };
         }
         return { candidates: [target] };
@@ -1286,6 +1305,28 @@ function emitExtractTriageEvent(args) {
         },
     }, eventsCtx);
 }
+/**
+ * Count every session's `skipReason` (#912) and push one warning line per
+ * infrastructure reason in {@link EXTRACT_INFRASTRUCTURE_SKIP_REASONS}.
+ * `undefined` when nothing was skipped, so the envelope carries no key.
+ */
+function buildExtractSkipAggregate(sessions, engine, warnings) {
+    const counts = {};
+    for (const session of sessions) {
+        if (!session.skipReason)
+            continue;
+        counts[session.skipReason] = (counts[session.skipReason] ?? 0) + 1;
+    }
+    if (Object.keys(counts).length === 0)
+        return undefined;
+    const total = sessions.length;
+    for (const reason of EXTRACT_INFRASTRUCTURE_SKIP_REASONS) {
+        const n = counts[reason];
+        if (n)
+            warnings.push(`${n} of ${total} sessions skipped: ${reason} (engine "${engine}")`);
+    }
+    return counts;
+}
 export async function akmExtract(options) {
     const startMs = Date.now();
     if (!options.type || options.type.trim() === "") {
@@ -1310,20 +1351,13 @@ export async function akmExtract(options) {
         (options.improveProfile ? resolveProcessEnabled("extract", options.improveProfile) : true);
     // Feature-gate early so we get a clean "skipped because disabled" envelope.
     if (!extractEnabled) {
-        return {
-            schemaVersion: 1,
+        return emptyExtractResult({
             ok: true,
-            shape: "extract-result",
             dryRun,
             type: options.type,
-            sessionsProcessed: 0,
-            sessionsSkipped: 0,
-            candidatesCreated: 0,
-            proposals: [],
-            sessions: [],
-            warnings: ["extract is disabled by the selected improve strategy"],
-            durationMs: Date.now() - startMs,
-        };
+            warning: "extract is disabled by the selected improve strategy",
+            startMs,
+        });
     }
     const { timeoutMs, llmRunner, onNotices, getNotices, maxTotalChars, minContentChars, maxSessionsPerRun, effectiveSince, triage, sessionIndexing, } = resolveExtractRunConfig(options, config, extractProcess, activeProfile);
     // WI-9.10: construct this run's RunContext (extracted to
@@ -1331,39 +1365,27 @@ export async function akmExtract(options) {
     const ctx = buildExtractRunContext({ options, config, stashDir, dryRun, sourceRun, llmRunner });
     const harness = resolveHarness(options.type, options.harnesses);
     if (!harness) {
-        return {
-            schemaVersion: 1,
+        return emptyExtractResult({
             ok: false,
-            shape: "extract-result",
             dryRun,
             type: options.type,
-            sessionsProcessed: 0,
-            sessionsSkipped: 0,
-            candidatesCreated: 0,
-            proposals: [],
-            sessions: [],
-            warnings: [`no available harness matches type "${options.type}" (check that the platform is installed)`],
-            durationMs: Date.now() - startMs,
-        };
+            warning: `no available harness matches type "${options.type}" (check that the platform is installed)`,
+            startMs,
+            llmRunner,
+        });
     }
     if (!harness.isAvailable()) {
-        return {
-            schemaVersion: 1,
+        return emptyExtractResult({
             ok: false,
-            shape: "extract-result",
             dryRun,
             type: options.type,
-            sessionsProcessed: 0,
-            sessionsSkipped: 0,
-            candidatesCreated: 0,
-            proposals: [],
-            sessions: [],
-            warnings: [`harness ${options.type} is registered but reports not-available (no session data on this machine)`],
-            durationMs: Date.now() - startMs,
-        };
+            warning: `harness ${options.type} is registered but reports not-available (no session data on this machine)`,
+            startMs,
+            llmRunner,
+        });
     }
     // Decide which sessions to process: explicit sessionId OR discovery via since.
-    const discovery = discoverExtractCandidates(options, harness, effectiveSince, startMs, dryRun);
+    const discovery = discoverExtractCandidates(options, harness, effectiveSince, startMs, dryRun, llmRunner);
     if ("notFound" in discovery)
         return discovery.notFound;
     const candidates = discovery.candidates;
@@ -1449,6 +1471,7 @@ export async function akmExtract(options) {
     if (loopResult.deferred > 0) {
         topLevelWarnings.push(`Reached maxSessionsPerRun=${maxSessionsPerRun}; ${loopResult.deferred} session(s) deferred to a later run.`);
     }
+    const skipReasons = buildExtractSkipAggregate(sessions, llmRunner.engine, topLevelWarnings);
     emitExtractTriageEvent({
         modelPlanCount,
         triageEnabled: triage.enabled,
@@ -1475,6 +1498,9 @@ export async function akmExtract(options) {
         warnings: topLevelWarnings,
         durationMs: Date.now() - startMs,
         ...(getNotices().length > 0 ? { notices: getNotices() } : {}),
+        ...(skipReasons ? { skipReasons } : {}),
+        engine: llmRunner.engine,
+        engineKind: llmRunner.kind,
     };
 }
 /**

package/dist/commands/improve/improve-strategies.js

@@ -88,39 +88,56 @@ export function resolveImprovePlan(name, config, options = {}) {
 }
 function buildImprovePlan(strategy, config, options) {
     const processes = {};
+    const engineUnavailable = [];
     for (const processName of Object.keys(IMPROVE_PROCESS_ENGINE_CAPABILITIES)) {
-        const processConfig = cloneAndFreeze(strategy.config.processes?.[processName] ?? {});
-        const enabled = processConfig.enabled === true;
+        const sourceProcessConfig = strategy.config.processes?.[processName] ?? {};
+        const enabled = sourceProcessConfig.enabled === true;
         let runner = null;
         let notices = [];
         if (IMPROVE_PROCESS_ENGINE_CAPABILITIES[processName] !== "llm" || !enabled) {
-            processes[processName] = Object.freeze({ enabled, config: processConfig, runner });
+            processes[processName] = Object.freeze({ enabled, config: cloneAndFreeze(sourceProcessConfig), runner });
             continue;
         }
         // Validation itself is structural and always runs. Only its optional repair
         // step needs a model, so disabling repair must not create an LLM preflight.
-        if (processName !== "validation" || options.repairValidationFailures !== false) {
+        const skipsRepairEngine = processName === "validation" && options.repairValidationFailures === false;
+        if (!skipsRepairEngine) {
             const resolved = resolveImproveLlmExecution({
                 config,
                 profile: strategy.config,
-                process: processConfig,
+                process: sourceProcessConfig,
                 processName,
             });
             runner = resolved?.runner ?? null;
             notices = resolved?.notices ?? [];
         }
-        if (!runner && !(processName === "validation" && options.repairValidationFailures === false)) {
-            throw new ConfigError(`Enabled improve process "${processName}" requires an LLM engine. Set defaults.llmEngine or improve.strategies.${strategy.name}.processes.${processName}.engine.`, "LLM_NOT_CONFIGURED");
+        if (!runner && !skipsRepairEngine) {
+            const configKey = `improve.strategies.${strategy.name}.processes.${processName}.engine`;
+            engineUnavailable.push({
+                process: processName,
+                configKey,
+                reason: `requires an LLM engine that is not configured. Set defaults.llmEngine or ${configKey}`,
+            });
+            processes[processName] = Object.freeze({
+                enabled: false,
+                config: cloneAndFreeze({ ...sourceProcessConfig, enabled: false }),
+                runner: null,
+            });
+            continue;
         }
         if (runner)
             runner = cloneAndFreeze(runner);
         processes[processName] = Object.freeze({
             enabled,
-            config: processConfig,
+            config: cloneAndFreeze(sourceProcessConfig),
             runner,
             ...(notices.length > 0 ? { notices: cloneAndFreeze(notices) } : {}),
         });
     }
+    if (engineUnavailable.length > 0 && !Object.values(processes).some((process) => process.enabled)) {
+        const names = engineUnavailable.map((item) => `"${item.process}"`).join(", ");
+        throw new ConfigError(`No improve process can run: ${names} ${engineUnavailable.length === 1 ? "requires" : "require"} an LLM engine that is not configured. Set defaults.llmEngine, or the per-process engine key named for each.`, "LLM_NOT_CONFIGURED");
+    }
     const triage = strategy.config.processes?.triage;
     const judgmentEnabled = triage?.judgment?.enabled === true;
     const triageJudgmentResolution = processes.triage.enabled && judgmentEnabled
@@ -156,5 +173,6 @@ function buildImprovePlan(strategy, config, options) {
         ...(triageJudgmentResolution?.notices.length
             ? { triageJudgmentNotices: cloneAndFreeze(triageJudgmentResolution.notices) }
             : {}),
+        engineUnavailable: Object.freeze(engineUnavailable),
     });
 }

package/dist/commands/improve/improve.js

@@ -1132,6 +1132,19 @@ async function runImproveStageSequence(args) {
             },
         }, eventsCtx);
     }
+    for (const item of resolvedPlan.engineUnavailable) {
+        warn(`[improve] ${item.process} skipped — it ${item.reason}.`);
+        appendEvent({
+            eventType: "improve_skipped",
+            ref: undefined,
+            metadata: {
+                strategy: selectedStrategy.name,
+                reason: "engine_unavailable",
+                process: item.process,
+                configKey: item.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;
@@ -1367,6 +1380,7 @@ function finalizeImproveResult(args) {
                     promoted: triageDrain.promoted.length,
                     rejected: triageDrain.rejected.length,
                     deferred: triageDrain.deferred.length,
+                    failed: triageDrain.failed.length,
                     skippedByCap: triageDrain.skippedByCap.length,
                 },
             }

package/dist/commands/improve/preparation.js

@@ -25,7 +25,7 @@ import { isAutonomyLaneAllowed } from "./autonomy-gate.js";
 import { akmConsolidate, inspectConsolidationPool } from "./consolidate.js";
 import { computeSafeChunkSize, DEFAULT_CONTEXT_LENGTH_TOKENS } from "./consolidate/chunking.js";
 // Eligibility / candidate-selection predicates live in ./eligibility.
-import { buildLatestFeedbackTsMap, buildLatestProposalTsMap, buildUtilityMap, dedupeRefs, findAssetFilePath, isDistillCandidateRef, isLessonCandidate, isSignalDeltaEligible, } from "./eligibility.js";
+import { buildLatestFeedbackTsMap, buildLatestProposalTsMap, buildUtilityMap, dedupeRefs, findAssetFilePath, isDistillCandidateRef, isLessonCandidate, isSignalDeltaEligible, resolveImproveScope, } from "./eligibility.js";
 import { akmExtract, countNewExtractCandidates } from "./extract.js";
 import { computeValenceScore, FEEDBACK_WEIGHT, UTILITY_WEIGHT } from "./feedback-valence.js";
 import { applyMemoryCleanup } from "./memory/memory-improve.js";
@@ -178,17 +178,20 @@ function evaluateConsolidationEligibility(args) {
     // #553 minPoolSize guard: skip consolidation when the eligible memory pool is
     // below a minimum size, rather than spending an LLM pass on a handful of
     // memories. This is an INDEPENDENT skip condition from #551's mtime pool-delta
-    // gate — either can skip. Default 500; `minPoolSize: 0` disables the guard.
-    // Evaluated against the eligible-pool count BEFORE entering the LLM loop so a
-    // skip costs ZERO LLM calls.
-    const CONSOLIDATE_DEFAULT_MIN_POOL_SIZE = 500;
+    // gate — either can skip. Default 0 (disabled) — every built-in strategy
+    // used to ship 500, which meant `akm improve --strategy consolidate`, typed
+    // by a human, silently did nothing on almost every real install. Evaluated
+    // against the eligible-pool count BEFORE entering the LLM loop so a skip
+    // costs ZERO LLM calls when an operator opts back into a floor.
+    const CONSOLIDATE_DEFAULT_MIN_POOL_SIZE = 0;
     const configuredMinPoolSize = improveProfile?.processes?.consolidate?.minPoolSize;
     const minPoolSize = typeof configuredMinPoolSize === "number" ? configuredMinPoolSize : CONSOLIDATE_DEFAULT_MIN_POOL_SIZE;
     const eligiblePoolSize = typeof memorySummary.eligible === "number" ? memorySummary.eligible : 0;
+    const userNamedStrategyOrScope = options.strategy !== undefined || resolveImproveScope(options.scope).mode === "ref";
     // volumeTriggered means the pool already exceeds the volume threshold (100),
     // so a force-triggered run never trips the pool-size guard. The guard only
     // engages when minPoolSize > 0 and the eligible pool is strictly below it.
-    const poolBelowMinSize = !volumeTriggered && minPoolSize > 0 && eligiblePoolSize < minPoolSize;
+    const poolBelowMinSize = !volumeTriggered && !userNamedStrategyOrScope && minPoolSize > 0 && eligiblePoolSize < minPoolSize;
     return {
         volumeTriggered,
         consolidationOnCooldown,