akm-cli 0.9.10 → 0.9.12

package/dist/commands/health.js

@@ -3,7 +3,7 @@
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
 import fs from "node:fs";
 import path from "node:path";
-import { resolveStashDir } from "../core/common.js";
+import { daysToMs, resolveStashDir } from "../core/common.js";
 import { loadConfig } from "../core/config/config.js";
 import { ConfigError, UsageError } from "../core/errors.js";
 import { readEvents } from "../core/events.js";
@@ -12,12 +12,14 @@ import { classifyPathAccess, describeInaccessiblePath } from "../core/path-acces
 import { getConfigPath, getDataDir, getDbPath, getStateDbPathInDataDir } from "../core/paths.js";
 import { listExistingTableNames, listPendingStateMigrations, openStateDatabase } from "../core/state-db.js";
 import { DURATION_UNITS, parseDuration, parseSinceToIso } from "../core/time.js";
+import { probeLlmEndpoint } from "../llm/client.js";
+import { getExtractOutcomeCountsSince } from "../storage/repositories/extract-sessions-repository.js";
 import { closeDatabase, openReadonlyExistingDatabase } from "../storage/repositories/index-connection.js";
 import { getAllEntries } from "../storage/repositories/index-entries-repository.js";
 import { queryTaskHistory } from "../storage/repositories/task-history-repository.js";
 import { pkgVersion } from "../version.js";
 import { collectImproveAdvisories } from "./health/advisories.js";
-import { HEALTH_CHECKS, runHealthEngineProbes, runPendingStateMigrationsCheck, } from "./health/checks.js";
+import { HEALTH_CHECKS, runHealthEngineProbes, runPendingStateMigrationsCheck, SESSION_EXTRACTION_LEDGER_WINDOW_DAYS, } from "./health/checks.js";
 import { collectDataDirUsageAdvisory } from "./health/data-dir-usage.js";
 import { buildImproveSkipSummary, computeWallTimeStats, isAgentTaskHistoryRow, roundRate, summarizeImproveCompleted, summarizeImproveRuns, taskFailureDetail, } from "./health/improve-metrics.js";
 import { emptyLlmUsageAggregate, readLlmUsageAggregate } from "./health/llm-usage.js";
@@ -166,6 +168,11 @@ function gatherEgressConfigPhase() {
     }
     return { egressConfigView };
 }
+/** Extract-ledger outcome counts for the `session-extraction` check's window, independent of `--since`. */
+function gatherSessionExtractionLedgerPhase(db, now) {
+    const since = new Date(now() - daysToMs(SESSION_EXTRACTION_LEDGER_WINDOW_DAYS)).toISOString();
+    return { since, rows: getExtractOutcomeCountsSince(db, since) };
+}
 /**
  * Assemble the window's improve-pipeline summary: invoked/completed/skipped
  * counts from events, the per-run result_json aggregate, wall-time stats, and
@@ -466,7 +473,7 @@ function unreadableStateDbCheck(detail) {
         evidence: { detail },
     };
 }
-export function akmHealth(options = {}) {
+export async function akmHealth(options = {}) {
     validateAkmHealthOptions(options);
     const now = options.now ?? (() => Date.now());
     const since = parseHealthSince(options.since);
@@ -519,12 +526,16 @@ export function akmHealth(options = {}) {
         logsDb = undefined;
     }
     try {
+        // Network probes overlap the local database phases below; awaited where consumed.
+        const engineProbesPromise = runHealthEngineProbes({ probeReachable: options.probe ? probeLlmEndpoint : undefined });
+        engineProbesPromise.catch(() => undefined);
         const taskHistory = gatherTaskHistoryPhase(db, logsDb, since, stateDbPath, now);
         const { tableNames, missingTables, probe } = taskHistory;
         const { egressConfigView } = gatherEgressConfigPhase();
         const { improveSummary } = gatherImproveSummaryPhase(db, stateDbPath, since, now);
         advisories.push(...gatherAncillaryAdvisories(db, stateDbPath, since, improveSummary, options, egressConfigView));
-        const engineProbes = runHealthEngineProbes();
+        const sessionExtractionLedger = gatherSessionExtractionLedgerPhase(db, now);
+        const engineProbes = await engineProbesPromise;
         // Run the ordered health-check registry. Each check projects the shared
         // context computed above into one HealthCheckResult; `channel` routes it to
         // hardChecks or advisories. Declaration order in HEALTH_CHECKS is the
@@ -544,6 +555,7 @@ export function akmHealth(options = {}) {
             stuckActiveTasks: taskHistory.stuckActiveTasks,
             worstTaskFailRate: taskHistory.worstTaskFailRate,
             sessionExtraction: improveSummary.sessionExtraction,
+            sessionExtractionLedger,
             autoAccept: improveSummary.autoAccept,
             engineProbes,
         };

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

@@ -15,6 +15,7 @@ import { timestampForFilename } from "../../../core/common.js";
 import { ConfigError } from "../../../core/errors.js";
 import { appendEvent } from "../../../core/events.js";
 import { parseEmbeddedJsonResponse } from "../../../core/parse.js";
+import { getDistillRejectedDir } from "../../../core/paths.js";
 import { withStateDb } from "../../../core/state-db.js";
 import { recordWrittenPath } from "../../../core/write-provenance.js";
 import { callStructured } from "../../../llm/structured-call.js";
@@ -199,7 +200,7 @@ async function runQualityJudge(feature, config, prompt, chat, options = {}) {
             parsed.score < 1 ||
             parsed.score > 5 ||
             typeof parsed.reason !== "string") {
-            return { pass: false, score: -1, reason: "judge parse failed — cannot judge, failing closed" };
+            return { pass: false, score: -1, reason: "judge parse failed — routed to review", reviewNeeded: true };
         }
         // D-5 / #388: Three-band system (MT-Bench arXiv:2306.05685 — ~±0.5 judge variance).
         //   >= 3.5: auto-queue as pending (pass: true)
@@ -218,7 +219,7 @@ async function runQualityJudge(feature, config, prompt, chat, options = {}) {
         // content verdict. Provider/runtime failures retain the fail-closed result.
         if (error instanceof ConfigError)
             throw error;
-        return { pass: false, score: -1, reason: "judge timeout/error — cannot judge, failing closed" };
+        return { pass: false, score: -1, reason: "judge timeout/error — routed to review", reviewNeeded: true };
     }
 }
 /**
@@ -242,8 +243,9 @@ export async function runReflectQualityJudge(config, candidateContent, sourceCon
 }
 // ── Quality-rejection helper ─────────────────────────────────────────────────
 /**
- * Write a rejected lesson to `.akm/distill-rejected/`, append a `distill_invoked`
- * quality-rejected event, and return the `quality_rejected` envelope.
+ * Write a rejected lesson to `$STATE/improve/distill-rejected/<stash>/`
+ * (itlackey/akm#890), append a `distill_invoked` quality-rejected event, and
+ * return the `quality_rejected` envelope.
  *
  * @param stash     - Root stash directory.
  * @param inputRef  - The original input ref (for the event).
@@ -257,13 +259,19 @@ export async function runReflectQualityJudge(config, candidateContent, sourceCon
 export function writeQualityRejection(stash, inputRef, proposalRef, content, score, reason, extraMeta = {}, eligibilitySource, eventsCtx) {
     // D-5 / #388: reviewNeeded flag selects "review_needed" vs "quality_rejected" outcome.
     const outcome = extraMeta.reviewNeeded ? "review_needed" : "quality_rejected";
-    const rejectDir = path.join(stash, ".akm", "distill-rejected");
+    const rejectDir = getDistillRejectedDir(stash);
     fs.mkdirSync(rejectDir, { recursive: true });
     const ts = timestampForFilename();
     const rejectPath = path.join(rejectDir, `${ts}-${proposalRef.replace(/[:/\\]/g, "-")}.md`);
     fs.writeFileSync(rejectPath, `---\nscore: ${score}\nreason: ${reason}\noutcome: ${outcome}\n---\n\n${content}`, "utf8");
-    // #652: the rejection envelope lands under the managed `.akm/` tree, which
-    // the pre-provenance sync swept up by pathspec — journal it explicitly.
+    // #652 / itlackey/akm#890: journal it even though it now lands under
+    // `$STATE`, outside the stash's git repo — `result.writtenPaths` reports
+    // every path a run touched, in or out of the stash (describeRunWrittenPaths
+    // in improve.ts falls back to the absolute path for anything outside the
+    // stash root), and the auto-sync commit's own containment check
+    // (resolveSyncPathSet's `relativeWrittenPath`) already drops anything
+    // outside `repoDir` from what gets staged — recording it here cannot cause
+    // it to be committed.
     recordWrittenPath(rejectPath);
     appendEvent({
         eventType: "distill_invoked",

package/dist/commands/improve/distill.js

@@ -778,7 +778,7 @@ export async function akmDistill(options) {
                 eventsCtx: options.eventsCtx,
             }));
         }
-        const { content, descriptionSwapped } = assembleAndValidateDistillContent({
+        const assembled = assembleAndValidateDistillContent({
             raw,
             effectiveProposalKind,
             inputRef,
@@ -789,7 +789,11 @@ export async function akmDistill(options) {
             filteredFeedbackCount,
             eligMeta,
             eventsCtx: options.eventsCtx,
+            stash,
         });
+        if ("rejection" in assembled)
+            return withNotices(assembled.rejection);
+        const { content, descriptionSwapped } = assembled;
         const gate = await applyDistillQualityGate({
             config,
             options,
@@ -968,7 +972,7 @@ async function emitDistillLessonProposal(args) {
  * throwing a `UsageError` on any finding. Extracted verbatim from `akmDistill`.
  */
 function assembleAndValidateDistillContent(args) {
-    const { raw, effectiveProposalKind, inputRef, durableInputRef, itemRef, effectiveLessonRef, exclusionSet, filteredFeedbackCount, eligMeta, eventsCtx, } = args;
+    const { raw, effectiveProposalKind, inputRef, durableInputRef, itemRef, effectiveLessonRef, exclusionSet, filteredFeedbackCount, eligMeta, eventsCtx, stash, } = args;
     // Structured-output path: when the provider honoured the JSON schema, `raw`
     // is a JSON object string (not a markdown blob). Try to parse it and assemble
     // the canonical `---\nfm\n---\n\nbody` form before using the markdown
@@ -1003,18 +1007,19 @@ function assembleAndValidateDistillContent(args) {
         content = repairLessonDescriptionTruncation(content);
     }
     // Parse + lint the lesson before creating the proposal. The lint is the
-    // canonical gate for required frontmatter (v1 spec §13). On failure we
-    // surface a structured error and exit non-zero — but still emit
-    // `distill_invoked` so the failure is observable.
-    const findings = effectiveProposalKind === "knowledge"
+    // canonical gate for required frontmatter (v1 spec §13): a field that is
+    // genuinely missing or empty means there is no valid asset to write, so
+    // that failure stays a hard reject — but still emit `distill_invoked` so
+    // the failure is observable.
+    const structuralFindings = effectiveProposalKind === "knowledge"
         ? validateKnowledgeContent(content, inputRef)
         : lintLessonContent(content, `distill:${inputRef}`).findings;
     // Additional lesson-only quality validators — reject the systematic failure
     // modes seen across 323 archived rejected proposals (see distill/content-repair).
-    if (effectiveProposalKind !== "knowledge" && findings.length === 0) {
-        findings.push(...collectLessonQualityFindings(content, inputRef));
-    }
-    if (findings.length > 0) {
+    const qualityFindings = effectiveProposalKind !== "knowledge" && structuralFindings.length === 0
+        ? collectLessonQualityFindings(content, inputRef)
+        : [];
+    if (structuralFindings.length > 0) {
         appendEvent({
             eventType: "distill_invoked",
             // Use item_ref when resolved, otherwise the input conceptId.
@@ -1023,16 +1028,27 @@ function assembleAndValidateDistillContent(args) {
                 outcome: "validation_failed",
                 proposalRef: effectiveLessonRef,
                 proposalKind: effectiveProposalKind,
-                findingKinds: findings.map((f) => f.kind),
+                findingKinds: structuralFindings.map((f) => f.kind),
                 ...(exclusionSet.size > 0 ? { filteredFeedbackCount } : {}),
                 ...eligMeta,
             },
         }, eventsCtx);
-        const message = findings.map((f) => f.message).join("\n");
+        const message = structuralFindings.map((f) => f.message).join("\n");
         throw new UsageError(`Distilled ${effectiveProposalKind} failed validation:\n${message}`, "MISSING_REQUIRED_ARGUMENT", effectiveProposalKind === "knowledge"
             ? "Knowledge proposals require a non-empty markdown body."
             : "Lessons require non-empty `description` and `when_to_use` frontmatter fields. See v1 spec §13.");
     }
+    if (qualityFindings.length > 0) {
+        return {
+            rejection: writeQualityRejection(stash, inputRef, effectiveLessonRef, content, 2.0, // below auto-accept threshold, signals review needed — no judge score exists for a structural/heuristic finding
+            qualityFindings.map((f) => f.message).join("\n"), {
+                reviewNeeded: true,
+                proposalKind: effectiveProposalKind,
+                findingKinds: qualityFindings.map((f) => f.kind),
+                ...(exclusionSet.size > 0 ? { filteredFeedbackCount } : {}),
+            }, eligMeta.eligibilitySource, eventsCtx),
+        };
+    }
     return { content, descriptionSwapped };
 }
 /**

package/dist/commands/improve/eval-cases.js

@@ -4,9 +4,10 @@
 import fs from "node:fs";
 import path from "node:path";
 import { writeFileAtomic } from "../../core/common.js";
+import { getEvalCasesDir } from "../../core/paths.js";
 import { recordWrittenPath } from "../../core/write-provenance.js";
 export function writeEvalCase(stashDir, evalCase) {
-    const evalDir = path.join(stashDir, ".akm", "eval-cases");
+    const evalDir = getEvalCasesDir(stashDir);
     fs.mkdirSync(evalDir, { recursive: true });
     const fileName = `${evalCase.slug}.md`;
     const filePath = path.join(evalDir, fileName);
@@ -29,11 +30,17 @@ Use it as a regression test: future improve runs on this ref should not produce
 output that would be rejected for the same reason.
 `;
     writeFileAtomic(filePath, content);
+    // itlackey/akm#890: journal it even though it now lands under `$STATE`,
+    // outside the stash's git repo — `result.writtenPaths` still reports it
+    // (as an absolute path; see describeRunWrittenPaths in improve.ts), and
+    // the auto-sync commit's own containment check already excludes anything
+    // outside the stash from what gets staged, so recording it here cannot
+    // cause it to be committed.
     recordWrittenPath(filePath);
     return filePath;
 }
 export function countEvalCases(stashDir) {
-    const evalDir = path.join(stashDir, ".akm", "eval-cases");
+    const evalDir = getEvalCasesDir(stashDir);
     if (!fs.existsSync(evalDir))
         return 0;
     try {

package/dist/commands/improve/execution.js

@@ -2,7 +2,6 @@
 // License, v. 2.0. If a copy of the MPL was not distributed with this
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
 import { deepMergeConfig } from "../../core/config/deep-merge.js";
-import { ConfigError } from "../../core/errors.js";
 import { lowerResolvedExecutionRequest } from "../../integrations/agent/execution-lowering.js";
 import { prepareInlineExecution } from "../../integrations/agent/inline-execution.js";
 function own(value, key) {
@@ -51,7 +50,7 @@ export function resolveImproveLlmExecution(options) {
     if (!resolved)
         return null;
     if (resolved.runner.kind !== "llm") {
-        throw new ConfigError(`Engine ${JSON.stringify(resolved.runner.engine ?? "unknown")} is not an LLM engine.`, "INVALID_CONFIG_FILE");
+        return null;
     }
     return { runner: resolved.runner, notices: resolved.notices };
 }

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),
     });
 }