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

package/dist/commands/improve/consolidate.js

@@ -29,12 +29,13 @@ import { openStateDatabase, withStateDb } from "../../core/state-db.js";
 import { warn } from "../../core/warn.js";
 import { commitWriteTargetBoundary, deleteAssetFromSource, resolveWriteTarget, writeAssetToSource, } from "../../core/write-source.js";
 import { closeDatabase, findEntryIdByRef, getAllEntries, getEntryById, getNeighborsByEntryId, openExistingDatabase, } from "../../indexer/db/db.js";
-import { resolveImproveProcessRunnerFromProfile, runnerIsLlm } from "../../integrations/agent/runner.js";
+import { materializeLlmRunnerConnection, resolveImproveProcessRunner } from "../../integrations/agent/runner.js";
 import { chatCompletion } from "../../llm/client.js";
 import { cosineSimilarity, embedBatch, resolveEmbeddingModelId } from "../../llm/embedder.js";
-import { isLlmFeatureEnabled, tryLlmFeature } from "../../llm/feature-gate.js";
+import { tryLlmFeature } from "../../llm/feature-gate.js";
 import { getConsolidationJudgedMap, upsertConsolidationJudged, } from "../../storage/repositories/consolidation-repository.js";
 import { getBodyEmbeddings, upsertBodyEmbeddings } from "../../storage/repositories/embeddings-repository.js";
+import { resolveImproveStrategy, resolveProcessEnabled } from "./improve-strategies.js";
 // Chunk sizing + per-chunk prompt assembly live in ./consolidate/chunking.
 // Imported for internal use by the orchestrator and re-exported for importers.
 import { buildChunkPrompt, computeSafeChunkSize, DEFAULT_CONTEXT_LENGTH_TOKENS } from "./consolidate/chunking.js";
@@ -493,13 +494,13 @@ function archiveMemory(filePath, stashDir, ref, reason, opIndex, supersededBy, w
  *
  * Priority order (mirrors extract / reflect / distill — see
  * `src/commands/extract.ts:421-438` and the canonical
- * `resolveImproveProcessRunnerFromProfile` pattern):
+ * `resolveImproveProcessRunner` pattern):
  *
- *   1. `profiles.improve.default.processes.consolidate.profile` (or `mode`)
- *      via {@link resolveImproveProcessRunnerFromProfile}. Lets the user pin
+ *   1. `improve.strategies.<name>.processes.consolidate.engine`
+ *      via {@link resolveImproveProcessRunner}. Lets the user pin
  *      a dedicated model (e.g. `ministral-3b`) for consolidation instead of
- *      whatever `defaults.llm` happens to be.
- *   2. `getDefaultLlmConfig(config)` — the baseline default LLM profile.
+ *      whatever `defaults.llmEngine` happens to be.
+ *   2. `getDefaultLlmConfig(config)` — the baseline default LLM engine.
  *
  * Regression guard (2026-05-26): before this resolver, `akmConsolidate`
  * called `getDefaultLlmConfig` directly and silently ignored a configured
@@ -509,13 +510,9 @@ function archiveMemory(filePath, stashDir, ref, reason, opIndex, supersededBy, w
  * `/tmp/akm-health-investigations/consolidation-no-op.md`.
  */
 function resolveConsolidateLlmConfig(config, activeProfile) {
-    const consolidateProcess = getImproveProcessConfig(config, "consolidate", activeProfile);
-    const runnerSpec = resolveImproveProcessRunnerFromProfile(consolidateProcess, config);
-    if (runnerSpec && runnerIsLlm(runnerSpec)) {
-        return runnerSpec.connection;
-    }
-    // Non-LLM runner modes (agent/sdk) don't apply to consolidate's HTTP path;
-    // fall back to the default LLM profile rather than disabling the pass.
+    const runnerSpec = resolveImproveProcessRunner(activeProfile, "consolidate", config);
+    if (runnerSpec)
+        return materializeLlmRunnerConnection(runnerSpec);
     return getDefaultLlmConfig(config);
 }
 // ── Judged-state cache (#581) ────────────────────────────────────────────────
@@ -578,8 +575,9 @@ export async function akmConsolidate(opts = {}) {
     // standalone `akm consolidate` gets a self-contained token.
     const sourceRun = opts.sourceRun ?? `consolidate-${startMs}`;
     const config = opts.config ?? loadConfig();
+    opts = { ...opts, improveProfile: opts.improveProfile ?? resolveImproveStrategy(undefined, config).config };
     const stashDir = opts.stashDir ?? resolveStashDir();
-    if (!isLlmFeatureEnabled(config, "memory_consolidation")) {
+    if (!resolveProcessEnabled("consolidate", opts.improveProfile ?? resolveImproveStrategy(undefined, config).config)) {
         return makeConsolidateResult({
             dryRun: opts.dryRun ?? false,
             target: opts.target ?? stashDir,
@@ -868,9 +866,11 @@ async function planConsolidation(opts, config, stashDir, startMs, memories, warn
     // CLI. The agent CLI is for interactive agent sessions (reflect, propose);
     // structured JSON generation works better and faster via HTTP.
     //
-    // Honor `profiles.improve.default.processes.consolidate.profile` first; fall
-    // back to the default LLM. See {@link resolveConsolidateLlmConfig}.
-    const llmConfig = resolveConsolidateLlmConfig(config, opts.improveProfile);
+    // Improve supplies a frozen connection; standalone consolidate resolves its
+    // selected strategy/default engine here.
+    const llmConfig = Object.hasOwn(opts, "llmConfig")
+        ? (opts.llmConfig ?? undefined)
+        : resolveConsolidateLlmConfig(config, opts.improveProfile);
     const isHttpPath = !!llmConfig;
     // Chunk sizing: derive a safe chunk size from the configured model context
     // window so that the full prompt (system prompt + chunk user prompt) never
@@ -1087,7 +1087,7 @@ async function planConsolidation(opts, config, stashDir, startMs, memories, warn
             catch (e) {
                 return { ok: false, error: String(e) };
             }
-        }, { ok: false, error: fallbackError });
+        }, { ok: false, error: fallbackError }, { enabled: true });
         let raw = await callChunkLlm(`chunk ${chunkIdx + 1} failed`);
         if (!raw.ok) {
             // Single retry with 2s backoff before recording chunk as lost.
@@ -1230,7 +1230,7 @@ async function planConsolidation(opts, config, stashDir, startMs, memories, warn
  * the op-handlers' `pushSkipReason`. Behavior-identical to the former inlined
  * write block. Never invoked on the dry-run or aborted-confirm paths.
  */
-async function applyConsolidationPlan(config, stashDir, sourceRun, memories, warnings, allOps, accounting, dedupCollapsed, activeProfile) {
+async function applyConsolidationPlan(config, stashDir, sourceRun, memories, warnings, allOps, accounting, dedupCollapsed, activeProfile, llmConfig) {
     // -- Phase B + writes -------------------------------------------------------
     const target = resolveWriteTarget(config);
     const timestamp = timestampForFilename();
@@ -1258,6 +1258,7 @@ async function applyConsolidationPlan(config, stashDir, sourceRun, memories, war
     const opCtx = {
         config,
         improveProfile: activeProfile,
+        llmConfig: llmConfig ?? null,
         stashDir,
         sourceRun,
         target,
@@ -1380,7 +1381,9 @@ async function akmConsolidateInner(opts, config, stashDir, startMs, sourceRun, w
         }
     }
     // -- Pass 3: execute the plan against the filesystem ------------------------
-    const { merged, deleted, contradicted, mergeFloorViolations, mergedSecondaries, promoted } = await applyConsolidationPlan(config, stashDir, sourceRun, memories, warnings, allOps, accounting, dedupCollapsed, opts.improveProfile);
+    const { merged, deleted, contradicted, mergeFloorViolations, mergedSecondaries, promoted } = await applyConsolidationPlan(config, stashDir, sourceRun, memories, warnings, allOps, accounting, dedupCollapsed, opts.improveProfile, Object.hasOwn(opts, "llmConfig")
+        ? (opts.llmConfig ?? null)
+        : (resolveConsolidateLlmConfig(config, opts.improveProfile) ?? null));
     const runDurationMs = Date.now() - startMs;
     const budgetFraction = opts.runBudgetMs !== undefined && opts.runBudgetMs > 0 ? runDurationMs / opts.runBudgetMs : undefined;
     return {
@@ -1502,7 +1505,7 @@ export async function handleMergeOp(op, opIndex, ctx) {
         emitMergeFailureSkips("merge_read_failed");
         return;
     }
-    const mergeResult = await generateMergedContent(config, op.primary, primaryBody, op.secondaries, memoryByRef, ctx.improveProfile);
+    const mergeResult = await generateMergedContent(config, op.primary, primaryBody, op.secondaries, memoryByRef, ctx.improveProfile, ctx.llmConfig);
     if ("error" in mergeResult) {
         warnings.push(`Merge: ${mergeResult.error} for ${mergeResult.detail}.`);
         emitMergeFailureSkips(mergeResult.error);
@@ -2147,7 +2150,7 @@ function loadMemoriesForSource(source, stashDir, warnings) {
     }
     return memories;
 }
-async function generateMergedContent(config, primaryRef, primaryBody, secondaryRefs, memoryByRef, activeProfile) {
+async function generateMergedContent(config, primaryRef, primaryBody, secondaryRefs, memoryByRef, activeProfile, resolvedLlmConfig) {
     // Only handle single-secondary merges per design (one call per merge op)
     const secRef = secondaryRefs[0];
     const secEntry = memoryByRef.get(secRef);
@@ -2191,7 +2194,7 @@ async function generateMergedContent(config, primaryRef, primaryBody, secondaryR
         .join("\n");
     // Use the same per-process profile resolution as the chunk-plan call above
     // so the merge generation step doesn't silently revert to the default LLM.
-    const llmConfig = resolveConsolidateLlmConfig(config, activeProfile);
+    const llmConfig = resolvedLlmConfig === null ? undefined : (resolvedLlmConfig ?? resolveConsolidateLlmConfig(config, activeProfile));
     const result = await tryLlmFeature("memory_consolidation", config, async () => {
         if (!llmConfig)
             return { ok: false, error: "No LLM configured for consolidation" };
@@ -2204,7 +2207,7 @@ async function generateMergedContent(config, primaryRef, primaryBody, secondaryR
         catch (e) {
             return { ok: false, error: String(e) };
         }
-    }, { ok: false, error: `merge content generation failed for ${primaryRef}` });
+    }, { ok: false, error: `merge content generation failed for ${primaryRef}` }, { enabled: true });
     if (!result.ok) {
         return {
             error: "merge_transport_failed",

package/dist/commands/improve/distill/promote-memory.js

@@ -18,11 +18,8 @@
  */
 import fs from "node:fs";
 import { parseFrontmatter } from "../../../core/asset/frontmatter.js";
-import { getDefaultLlmConfig } from "../../../core/config/config.js";
-import { ConfigError } from "../../../core/errors.js";
 import { appendEvent } from "../../../core/events.js";
 import { parseEmbeddedJsonResponse } from "../../../llm/client.js";
-import { isLlmFeatureEnabled } from "../../../llm/feature-gate.js";
 import { createProposal, isProposalSkipped } from "../../proposal/repository.js";
 import { assessMemoryKnowledgePromotionCandidate } from "../distill-promotion-policy.js";
 import { persistOutputEncodingSalience, runLessonQualityJudge, writeQualityRejection } from "./quality-gate.js";
@@ -62,7 +59,7 @@ export async function promoteMemoryToKnowledge(ctx) {
             }
         })()
         : null;
-    if (existingKnowledgeContent && config && getDefaultLlmConfig(config)) {
+    if (existingKnowledgeContent && ctx.llmConfig) {
         // Existing content found: call LLM for contradiction-resolution merge.
         const mergePrompt = [
             "You are merging two versions of a knowledge document.",
@@ -81,11 +78,7 @@ export async function promoteMemoryToKnowledge(ctx) {
             "```",
         ].join("\n");
         try {
-            const mergeLlm = getDefaultLlmConfig(config);
-            if (!mergeLlm) {
-                throw new ConfigError("LLM is not configured for distillation merge.", "LLM_NOT_CONFIGURED");
-            }
-            const mergeResponse = await chat(mergeLlm, [
+            const mergeResponse = await chat(ctx.llmConfig, [
                 { role: "system", content: "Return only valid JSON. No prose." },
                 { role: "user", content: mergePrompt },
             ]);
@@ -122,7 +115,7 @@ export async function promoteMemoryToKnowledge(ctx) {
             // The reviewer will see both versions in the proposal diff.
         }
     }
-    else if (existingKnowledgeContent && config && !getDefaultLlmConfig(config)) {
+    else if (existingKnowledgeContent) {
         // No LLM configured: include existing content as context in the proposal
         // so the reviewer can do the contradiction resolution manually.
         resolvedPromotionContent = [
@@ -141,10 +134,10 @@ export async function promoteMemoryToKnowledge(ctx) {
     // D-5 / #388: Three-band system — review_needed band queues to proposal
     // queue with review_needed outcome rather than auto-rejecting.
     let knowledgeJudgeConfidence;
-    if (isLlmFeatureEnabled(config, "lesson_quality_gate")) {
+    if (ctx.strategy?.processes?.distill?.qualityGate?.enabled ?? true) {
         // D-4 / #390: retrieve top-3 similar lessons for dedup check in judge.
         const similarLessons = await fetchSimilarLessonsFn(resolvedPromotionContent.slice(0, 500), 3);
-        const judgeResult = await runLessonQualityJudge(config, resolvedPromotionContent, assetContent ?? "", chat, similarLessons.length > 0 ? similarLessons : undefined);
+        const judgeResult = await runLessonQualityJudge(config, resolvedPromotionContent, assetContent ?? "", chat, similarLessons.length > 0 ? similarLessons : undefined, ctx.llmConfig);
         if (!judgeResult.pass) {
             if (judgeResult.reviewNeeded) {
                 // Uncertainty band (2.5–3.5): queue as review_needed instead of rejecting.

package/dist/commands/improve/distill/quality-gate.js

@@ -102,10 +102,8 @@ export function buildJudgePrompt(lessonContent, sourceContent, similarLessons) {
  * Run the LLM-as-judge quality gate on a proposal's content.
  *
  * Exported so reflect.ts can apply the same gate to reflect proposals (R-5 / #374).
- * Gated by the flag name `lesson_quality_gate` (or its alias
- * `proposal_quality_gate`) via {@link isLlmFeatureEnabled} — which reads
- * `profiles.improve.default.processes.distill.qualityGate.enabled` (and the
- * corresponding `.reflect.qualityGate.enabled` for proposals).
+ * The selected strategy's distill/reflect quality-gate setting is resolved by
+ * the caller before this function runs.
  *
  * Fail-CLOSED (07 P0-2): returns `pass: false` (score -1) on timeout, parse
  * failure, or missing LLM. Minted content that cannot be judged is rejected,
@@ -114,12 +112,12 @@ export function buildJudgePrompt(lessonContent, sourceContent, similarLessons) {
  */
 export async function runLessonQualityJudge(config, lessonContent, sourceContent, chat, 
 /** D-4 / #390: top-3 similar existing lessons for dedup check. */
-similarLessons) {
-    const llmConfig = getDefaultLlmConfig(config);
+similarLessons, llmConfigOverride) {
+    const llmConfig = llmConfigOverride ?? getDefaultLlmConfig(config);
     if (!llmConfig) {
         return { pass: false, score: -1, reason: "no LLM configured — cannot judge, failing closed" };
     }
-    const judgeLlmConfig = llmConfig.judgeModel ? { ...llmConfig, model: llmConfig.judgeModel } : llmConfig;
+    const judgeLlmConfig = llmConfig;
     const JUDGE_TIMEOUT_MS = 8_000;
     try {
         const raw = await Promise.race([

package/dist/commands/improve/distill.js

@@ -69,8 +69,9 @@ import { withStateDb } from "../../core/state-db.js";
 import { warnVerbose } from "../../core/warn.js";
 import { closeDatabase, getAllEntries, openIndexDatabase } from "../../indexer/db/db.js";
 import { resolveAssetPath } from "../../indexer/walk/path-resolver.js";
+import { materializeLlmRunnerConnection, resolveImproveProcessRunner } from "../../integrations/agent/runner.js";
 import { chatCompletion, parseEmbeddedJsonResponse } from "../../llm/client.js";
-import { isLlmFeatureEnabled, tryLlmFeature } from "../../llm/feature-gate.js";
+import { tryLlmFeature } from "../../llm/feature-gate.js";
 import { createProposal, isProposalSkipped, listProposals, } from "../proposal/repository.js";
 import { stripFrontmatterBody as stripBodyForFidelity } from "./dedup.js";
 import { autoRepairLessonFrontmatter, autoSwapDescriptionWhenToUse, collectLessonQualityFindings, repairLessonDescriptionTruncation, } from "./distill/content-repair.js";
@@ -79,6 +80,7 @@ import { fetchTopSimilarLessons, persistOutputEncodingSalience, runLessonQuality
 import { buildClsContext, checkDistillFidelity } from "./distill-guards.js";
 import { deriveKnowledgeRef } from "./distill-promotion-policy.js";
 import { buildRefVocabulary, scoreEncodingSalience } from "./encoding-salience.js";
+import { resolveImproveStrategy, resolveProcessEnabled } from "./improve-strategies.js";
 import { computeSalience, upsertAssetSalience } from "./salience.js";
 // Re-exported for `reflect.ts`, which applies the same LLM-as-judge gate to
 // reflect proposals (R-5 / #374).
@@ -474,8 +476,15 @@ export async function akmDistill(options) {
         };
     }
     const config = options.config ?? loadConfig();
+    options = { ...options, improveProfile: options.improveProfile ?? resolveImproveStrategy(undefined, config).config };
     const stash = options.stashDir ?? resolveStashDir();
     const chat = options.chat ?? chatCompletion;
+    const distillLlm = Object.hasOwn(options, "llmConfig")
+        ? (options.llmConfig ?? undefined)
+        : (() => {
+            const runner = resolveImproveProcessRunner(options.improveProfile, "distill", config);
+            return runner ? materializeLlmRunnerConnection(runner) : getDefaultLlmConfig(config);
+        })();
     const lookup = options.lookupFn ?? defaultLookup;
     const readEventsImpl = options.readEventsFn ?? readEvents;
     // R1 opt-out must flow into every computeSalience call this command makes so
@@ -602,6 +611,8 @@ export async function akmDistill(options) {
         assetContent,
         filteredEvents,
         config,
+        strategy: options.improveProfile,
+        llmConfig: distillLlm,
         chat,
         stash,
         lookup,
@@ -684,12 +695,11 @@ export async function akmDistill(options) {
     const distillSchema = effectiveProposalKind === "knowledge" ? DISTILL_KNOWLEDGE_JSON_SCHEMA : DISTILL_LESSON_JSON_SCHEMA;
     let fallbackReason;
     const raw = await tryLlmFeature("distill", config, async () => {
-        const distillLlm = getDefaultLlmConfig(config);
         if (!distillLlm) {
             // No LLM connection configured — treat as gate-disabled. Throwing
             // here lets `tryLlmFeature` route us through the "error" fallback,
             // which is the same graceful skipped path.
-            throw new ConfigError("No LLM connection configured. Set `defaults.llm` and a profile under `profiles.llm`.", "LLM_NOT_CONFIGURED");
+            throw new ConfigError("No LLM engine configured. Set defaults.llmEngine or improve.strategies.<name>.processes.distill.engine.", "LLM_NOT_CONFIGURED");
         }
         // Production path: pass the JSON schema so providers that honour
         // `response_format: json_schema` enforce shape upstream. Providers that
@@ -701,6 +711,7 @@ export async function akmDistill(options) {
         // functions (which return markdown strings) continue to work.
         return chat(distillLlm, messages);
     }, null, {
+        enabled: resolveProcessEnabled("distill", options.improveProfile ?? resolveImproveStrategy(undefined, config).config),
         onFallback: (evt) => {
             fallbackReason = evt.reason;
             // Log the fallback reason; the caller (raw === null path) handles
@@ -822,10 +833,10 @@ export async function akmDistill(options) {
     // D-5 / #388: Three-band system — review_needed band queues a proposal
     // with review_needed outcome rather than auto-rejecting.
     let lessonJudgeConfidence;
-    if (isLlmFeatureEnabled(config, "lesson_quality_gate")) {
+    if (options.improveProfile?.processes?.distill?.qualityGate?.enabled ?? true) {
         // D-4 / #390: retrieve top-3 similar lessons for dedup check in judge.
         const similarLessons = await fetchSimilarLessonsFn(content.slice(0, 500), 3);
-        const judgeResult = await runLessonQualityJudge(config, content, assetContent ?? "", chat, similarLessons.length > 0 ? similarLessons : undefined);
+        const judgeResult = await runLessonQualityJudge(config, content, assetContent ?? "", chat, similarLessons.length > 0 ? similarLessons : undefined, distillLlm);
         if (!judgeResult.pass) {
             if (judgeResult.reviewNeeded) {
                 return writeQualityRejection(stash, inputRef, effectiveLessonRef, content, judgeResult.score, judgeResult.reason, {

package/dist/commands/improve/eligibility.js

@@ -8,11 +8,11 @@ import { parseFrontmatter } from "../../core/asset/frontmatter.js";
 import { isAssetType } from "../../core/common.js";
 import { NotFoundError, rethrowIfTestIsolationError, UsageError } from "../../core/errors.js";
 import { readEvents } from "../../core/events.js";
-import { closeDatabase, getAllEntries, getUtilityScoresByIds, openExistingDatabase } from "../../indexer/db/db.js";
+import { closeDatabase, getAllEntries, getUtilityScoresByIds, openExistingDatabase, openReadonlyExistingDatabase, } from "../../indexer/db/db.js";
 import { getWritableStashDirs, resolveSourceEntries } from "../../indexer/search/search-source.js";
 import { resolveAssetPath } from "../../indexer/walk/path-resolver.js";
 import { isDistillRefusedInputType } from "./distill.js";
-import { isProfileFilteredForAllPasses } from "./improve-profiles.js";
+import { isStrategyFilteredForAllPasses } from "./improve-strategies.js";
 // Eligibility / candidate-selection predicates for improve. Free functions
 // (no akmImprove closure state) extracted from improve.ts to shrink the
 // orchestrator and make candidate selection independently testable.
@@ -49,6 +49,13 @@ export function dedupeRefs(refs) {
     return out;
 }
 export async function collectEligibleRefs(scope, stashDir, improveProfile) {
+    return collectEligibleRefsFromIndex(scope, stashDir, improveProfile, false);
+}
+/** Dry-run planner path: query an existing index without creating or mutating it. */
+export async function collectEligibleRefsReadOnly(scope, stashDir, improveProfile) {
+    return collectEligibleRefsFromIndex(scope, stashDir, improveProfile, true);
+}
+async function collectEligibleRefsFromIndex(scope, stashDir, improveProfile, readOnly) {
     if (scope.mode === "ref" && scope.value) {
         const parsed = parseAssetRef(scope.value);
         const writableDirs = new Set(getWritableStashDirs(stashDir).map((dir) => path.resolve(dir)));
@@ -57,7 +64,7 @@ export async function collectEligibleRefs(scope, stashDir, improveProfile) {
             return {
                 plannedRefs: [],
                 memorySummary: { eligible: 0, derived: 0 },
-                profileFilteredRefs: [],
+                strategyFilteredRefs: [],
             };
         }
         return {
@@ -66,7 +73,7 @@ export async function collectEligibleRefs(scope, stashDir, improveProfile) {
                 eligible: parsed.type === "memory" ? 1 : 0,
                 derived: parsed.type === "memory" && parsed.name.endsWith(".derived") ? 1 : 0,
             },
-            profileFilteredRefs: [],
+            strategyFilteredRefs: [],
         };
     }
     let sources;
@@ -74,10 +81,10 @@ export async function collectEligibleRefs(scope, stashDir, improveProfile) {
         sources = resolveSourceEntries(stashDir);
     }
     catch {
-        return { plannedRefs: [], memorySummary: { eligible: 0, derived: 0 }, profileFilteredRefs: [] };
+        return { plannedRefs: [], memorySummary: { eligible: 0, derived: 0 }, strategyFilteredRefs: [] };
     }
     if (sources.length === 0) {
-        return { plannedRefs: [], memorySummary: { eligible: 0, derived: 0 }, profileFilteredRefs: [] };
+        return { plannedRefs: [], memorySummary: { eligible: 0, derived: 0 }, strategyFilteredRefs: [] };
     }
     // Only operate on writable sources — never mutate read-only registry caches
     // or remote stashes that the user did not mark writable.
@@ -91,7 +98,10 @@ export async function collectEligibleRefs(scope, stashDir, improveProfile) {
     const writableDirSet = new Set(writableDirs.map((d) => path.resolve(d)));
     let db;
     try {
-        db = openExistingDatabase();
+        db = readOnly ? openReadonlyExistingDatabase() : openExistingDatabase();
+        if (!db) {
+            return { plannedRefs: [], memorySummary: { eligible: 0, derived: 0 }, strategyFilteredRefs: [] };
+        }
         const entries = getAllEntries(db, scope.mode === "type" ? scope.value : undefined).filter((indexed) => {
             // First apply the existing stashDir-scope filter (no-op when stashDir is unset).
             if (!isEntryInScope(indexed.stashDir, indexed.filePath, stashDir))
@@ -117,14 +127,14 @@ export async function collectEligibleRefs(scope, stashDir, improveProfile) {
                 // 2026-05-27: extend the .derived precedent to profile-incompatible
                 // refs. If every per-ref pass (reflect + distill) on the active
                 // profile would refuse this ref, drop it from `plannedRefs`. The
-                // caller emits `improve_skipped { reason: profile_filtered_all_passes }`
+                // caller emits `improve_skipped { reason: strategy_filtered_all_passes }`
                 // once `eventsCtx` is available so the audit trail is preserved in a
                 // single event per ref instead of 2× synthetic actions per run.
                 // Background: see /tmp/akm-health-investigations/planner-profile-metrics-deep-analysis.md
-                if (improveProfile && isProfileFilteredForAllPasses(ref, improveProfile)) {
+                if (improveProfile && isStrategyFilteredForAllPasses(ref, improveProfile)) {
                     profileFiltered.set(ref, {
                         ref,
-                        reason: "profile_filtered_all_passes",
+                        reason: "strategy_filtered_all_passes",
                         filePath: indexed.filePath,
                     });
                 }
@@ -145,14 +155,14 @@ export async function collectEligibleRefs(scope, stashDir, improveProfile) {
         return {
             plannedRefs: [...planned.values()],
             memorySummary: { eligible: memoryEligible, derived: memoryDerived },
-            profileFilteredRefs: [...profileFiltered.values()],
+            strategyFilteredRefs: [...profileFiltered.values()],
         };
     }
     catch (error) {
         // The bun-test isolation guard must never be downgraded to "empty plan".
         rethrowIfTestIsolationError(error);
         if (error instanceof NotFoundError || error instanceof Error) {
-            return { plannedRefs: [], memorySummary: { eligible: 0, derived: 0 }, profileFilteredRefs: [] };
+            return { plannedRefs: [], memorySummary: { eligible: 0, derived: 0 }, strategyFilteredRefs: [] };
         }
         throw error;
     }

package/dist/commands/improve/extract-cli.js

@@ -18,9 +18,10 @@ import fs from "node:fs";
 import path from "node:path";
 import { getStringArg } from "../../cli/parse-args.js";
 import { defineJsonCommand, EXIT_CODES, output } from "../../cli/shared.js";
+import { loadConfig } from "../../core/config/config.js";
 import { UsageError } from "../../core/errors.js";
 import { getAvailableHarnesses, getWatchTargets } from "../../integrations/session-logs/index.js";
-import { akmExtract } from "./extract.js";
+import { akmExtract, resolveStandaloneExtractPlan, } from "./extract.js";
 import { akmExtractWatch } from "./extract-watch.js";
 export const extractCommand = defineJsonCommand({
     meta: {
@@ -61,7 +62,15 @@ export const extractCommand = defineJsonCommand({
         },
         "timeout-ms": {
             type: "string",
-            description: "Per-session LLM timeout in ms (default 60000).",
+            description: "Per-session LLM timeout in ms (default 600000).",
+        },
+        engine: {
+            type: "string",
+            description: "Named LLM engine for this invocation. Mutually exclusive with --strategy.",
+        },
+        strategy: {
+            type: "string",
+            description: "Improve strategy supplying extract behavior and engine. Mutually exclusive with --engine.",
         },
         watch: {
             type: "boolean",
@@ -81,12 +90,17 @@ export const extractCommand = defineJsonCommand({
         const auto = args.auto === true;
         const dryRun = args["dry-run"] === true;
         const force = args.force === true;
+        const engine = getStringArg(args, "engine");
+        const strategy = getStringArg(args, "strategy");
         const timeoutMs = typeof args["timeout-ms"] === "string" && args["timeout-ms"] !== ""
             ? Number.parseInt(args["timeout-ms"], 10)
             : undefined;
         if (timeoutMs !== undefined && (!Number.isFinite(timeoutMs) || timeoutMs <= 0)) {
             throw new UsageError(`--timeout-ms must be a positive integer (got "${args["timeout-ms"]}").`, "INVALID_FLAG_VALUE");
         }
+        if (engine && strategy) {
+            throw new UsageError("--engine and --strategy are mutually exclusive. Pick one.", "INVALID_FLAG_VALUE");
+        }
         const watch = args.watch === true;
         const debounceMs = typeof args["debounce-ms"] === "string" && args["debounce-ms"] !== ""
             ? Number.parseInt(args["debounce-ms"], 10)
@@ -94,24 +108,31 @@ export const extractCommand = defineJsonCommand({
         if (watch && (!Number.isFinite(debounceMs) || debounceMs <= 0)) {
             throw new UsageError(`--debounce-ms must be a positive integer (got "${args["debounce-ms"]}").`, "INVALID_FLAG_VALUE");
         }
-        if (watch) {
-            await runWatchMode({ debounceMs, dryRun, force, ...(since ? { since } : {}) });
-            return;
-        }
-        if (auto && type) {
+        if (!watch && auto && type) {
             throw new UsageError("--auto and --type are mutually exclusive. Pick one.", "INVALID_FLAG_VALUE");
         }
-        if (!auto && !type) {
+        if (!watch && !auto && !type) {
             throw new UsageError("--type is required (or pass --auto to try every available harness).", "MISSING_REQUIRED_ARGUMENT");
         }
-        const commonOptions = {
+        const config = loadConfig();
+        const resolvedPlan = resolveStandaloneExtractPlan(config, {
+            ...(engine ? { engine } : {}),
+            ...(strategy ? { strategy } : {}),
+            ...(timeoutMs !== undefined ? { timeoutMs } : {}),
+        });
+        if (watch) {
+            await runWatchMode({ debounceMs, dryRun, force, config, resolvedPlan, ...(since ? { since } : {}) });
+            return;
+        }
+        const commonOptions = Object.freeze({
             ...(sessionId ? { sessionId } : {}),
             ...(location ? { location } : {}),
             ...(since ? { since } : {}),
             dryRun,
             force,
-            ...(timeoutMs !== undefined ? { timeoutMs } : {}),
-        };
+            config,
+            resolvedPlan,
+        });
         if (auto) {
             const harnesses = getAvailableHarnesses();
             if (harnesses.length === 0) {
@@ -196,6 +217,13 @@ function createFsWatchEventSource(roots) {
         },
     };
 }
+/** Snapshot the CLI-resolved watch options once and reuse them for every debounced trigger. */
+export function createExtractWatchTrigger(options, extractFn = akmExtract) {
+    const snapshot = Object.freeze({ ...options });
+    return async (harnessName) => {
+        await extractFn({ type: harnessName, ...snapshot });
+    };
+}
 /**
  * Run `akm extract --watch`: watch every available harness's session-log
  * roots and run extract (debounced, per-harness) on change. Stays alive until
@@ -216,18 +244,18 @@ async function runWatchMode(opts) {
     }
     const allRoots = targets.flatMap((t) => t.roots);
     const eventSource = createFsWatchEventSource(allRoots);
+    const onTrigger = createExtractWatchTrigger({
+        dryRun: opts.dryRun,
+        force: opts.force,
+        config: opts.config,
+        resolvedPlan: opts.resolvedPlan,
+        ...(opts.since ? { since: opts.since } : {}),
+    });
     const handle = akmExtractWatch({
         roots: targets,
         eventSource,
         debounceMs: opts.debounceMs,
-        onTrigger: async (harnessName) => {
-            await akmExtract({
-                type: harnessName,
-                dryRun: opts.dryRun,
-                force: opts.force,
-                ...(opts.since ? { since: opts.since } : {}),
-            });
-        },
+        onTrigger,
     });
     output("extract", {
         schemaVersion: 1,