akm-cli 0.9.11 → 0.9.12

package/dist/commands/health/checks.js

@@ -4,6 +4,7 @@
 import { spawnSync } from "node:child_process";
 import { loadConfig } from "../../core/config/config.js";
 import { ConfigError } from "../../core/errors.js";
+import { EXTRACT_INFRASTRUCTURE_SKIP_REASONS } from "../../core/improve-types.js";
 import { listPendingStateMigrations } from "../../core/state-db.js";
 import { withEngineFallback } from "../../integrations/agent/engine-fallback.js";
 import { lookupApiKeyFileValue, resolveEngine } from "../../integrations/agent/engine-resolution.js";
@@ -11,6 +12,37 @@ import { executionEngineDefinitionsFromConfig } from "../../integrations/agent/e
 import { loadModelMap, mergeModelMapLayers, parseModelMapLayer, readInstalledModelMapText, resolveModelMapAlias, userModelMapPath, } from "../../integrations/agent/model-map.js";
 import { resolveImprovePlan } from "../improve/improve-strategies.js";
 import { ACTIVE_RUN_WARN_MS, TASK_FAIL_RATE_WARN } from "./types.js";
+/** Probe one connection's reachability, once per endpoint; `undefined` when no probe seam is supplied. */
+function probeConnectionReachable(connection, deps, cache) {
+    if (!deps.probeReachable)
+        return Promise.resolve(undefined);
+    const key = connection.endpoint.replace(/\/+$/, "");
+    let pending = cache.get(key);
+    if (!pending) {
+        pending = deps.probeReachable(connection);
+        cache.set(key, pending);
+    }
+    return pending;
+}
+function reachabilityEvidence(reach) {
+    return reach
+        ? { probed: true, reachable: reach.reachable, ...(reach.error ? { error: reach.error } : {}) }
+        : { probed: false, reachable: null };
+}
+/**
+ * #914: an unreachable LLM engine is a hard `fail` when it is the resolved
+ * `default-llm-engine` (extraction and improve depend on it) but only a
+ * `warn` elsewhere. Only a reachability warn escalates; a credential warn
+ * stays a warn.
+ */
+function escalateDefaultLlmEngineFailure(result) {
+    if (result.status === "warn" && result.evidence?.reachable === false) {
+        return { ...result, status: "fail" };
+    }
+    return result;
+}
+/** Rolling window the `session-extraction` check reads from the extract ledger (#914). */
+export const SESSION_EXTRACTION_LEDGER_WINDOW_DAYS = 7;
 function credentialAvailable(credential, env, apiKeyFile) {
     if (credential?.required)
         return credential.names.some((name) => Boolean(env[name]?.trim()));
@@ -21,7 +53,7 @@ function credentialAvailable(credential, env, apiKeyFile) {
         return lookupApiKeyFileValue(apiKeyFile) !== undefined;
     return true;
 }
-function runConfiguredEngineProbe(checkName, engineName, config, deps) {
+async function runConfiguredEngineProbe(checkName, engineName, config, deps, reachabilityCache) {
     if (!engineName) {
         return {
             name: checkName,
@@ -102,52 +134,84 @@ function runConfiguredEngineProbe(checkName, engineName, config, deps) {
             fallbackEngine && !fallback ? "configured fallback LLM connection" : undefined,
             !fallbackCredentialAvailable ? "required fallback credential" : undefined,
         ].filter((value) => value !== undefined);
+        const sdkEvidence = {
+            engine: engineName,
+            platform: configuredEngine.platform,
+            runtimeKind: "sdk",
+            binary,
+            binaryAvailable,
+            package: "@opencode-ai/sdk",
+            packageAvailable,
+            model: effectiveModel ?? null,
+            configuredModel: configuredModel ?? null,
+            modelSource: configuredModel ? "sdk" : effectiveModel ? "fallback" : null,
+            fallbackEngine: fallbackEngine ?? null,
+            fallbackEndpoint: fallback?.connection.endpoint ?? null,
+            fallbackModel: fallback?.connection.model ?? null,
+            requiredCredentialAvailable: fallbackCredentialAvailable,
+        };
+        if (missing.length > 0) {
+            return {
+                name: checkName,
+                kind: "deterministic",
+                status: "warn",
+                confidence: "high",
+                message: `SDK engine "${engineName}" is incomplete: missing ${missing.join(", ")}.`,
+                evidence: sdkEvidence,
+            };
+        }
+        // The SDK's LLM fallback is the only endpoint this engine talks to;
+        // probe it once every local precondition above is satisfied (#914).
+        const reach = fallback ? await probeConnectionReachable(fallback.connection, deps, reachabilityCache) : undefined;
         return {
             name: checkName,
             kind: "deterministic",
-            status: missing.length === 0 ? "pass" : "warn",
+            status: reach && !reach.reachable ? "warn" : "pass",
             confidence: "high",
-            message: missing.length === 0
+            message: !fallback
                 ? `SDK engine "${engineName}" is available.`
-                : `SDK engine "${engineName}" is incomplete: missing ${missing.join(", ")}.`,
-            evidence: {
-                engine: engineName,
-                platform: configuredEngine.platform,
-                runtimeKind: "sdk",
-                binary,
-                binaryAvailable,
-                package: "@opencode-ai/sdk",
-                packageAvailable,
-                model: effectiveModel ?? null,
-                configuredModel: configuredModel ?? null,
-                modelSource: configuredModel ? "sdk" : effectiveModel ? "fallback" : null,
-                fallbackEngine: fallbackEngine ?? null,
-                fallbackEndpoint: fallback?.connection.endpoint ?? null,
-                fallbackModel: fallback?.connection.model ?? null,
-                requiredCredentialAvailable: fallbackCredentialAvailable,
-            },
+                : !reach
+                    ? `SDK engine "${engineName}" is available. Reachability was not probed.`
+                    : reach.reachable
+                        ? `SDK engine "${engineName}" is available and its LLM fallback is reachable.`
+                        : `SDK engine "${engineName}" is available, but its LLM fallback is not reachable: ${reach.error ?? "unknown error"}`,
+            evidence: fallback ? { ...sdkEvidence, ...reachabilityEvidence(reach) } : sdkEvidence,
         };
     }
     try {
         const runner = (deps.resolveEngine ?? resolveEngine)(engineName, config);
         if (runner.kind === "llm") {
             const requiredCredentialAvailable = credentialAvailable(runner.credential, env, runner.apiKeyFile);
+            const llmEvidence = {
+                engine: engineName,
+                platform: null,
+                runtimeKind: "llm",
+                model: runner.connection.model,
+                endpoint: runner.connection.endpoint,
+                requiredCredentialAvailable,
+            };
+            if (!requiredCredentialAvailable) {
+                return {
+                    name: checkName,
+                    kind: "deterministic",
+                    status: "warn",
+                    confidence: "high",
+                    message: `LLM engine "${engineName}" is configured, but its required credential is unavailable.`,
+                    evidence: llmEvidence,
+                };
+            }
+            const reach = await probeConnectionReachable(runner.connection, deps, reachabilityCache);
             return {
                 name: checkName,
                 kind: "deterministic",
-                status: requiredCredentialAvailable ? "pass" : "warn",
+                status: reach && !reach.reachable ? "warn" : "pass",
                 confidence: "high",
-                message: requiredCredentialAvailable
-                    ? `LLM engine "${engineName}" is configured.`
-                    : `LLM engine "${engineName}" is configured, but its required credential is unavailable.`,
-                evidence: {
-                    engine: engineName,
-                    platform: null,
-                    runtimeKind: "llm",
-                    model: runner.connection.model,
-                    endpoint: runner.connection.endpoint,
-                    requiredCredentialAvailable,
-                },
+                message: !reach
+                    ? `LLM engine "${engineName}" is configured. Reachability was not probed.`
+                    : reach.reachable
+                        ? `LLM engine "${engineName}" is configured and reachable.`
+                        : `LLM engine "${engineName}" is not reachable: ${reach.error ?? "unknown error"}`,
+                evidence: { ...llmEvidence, ...reachabilityEvidence(reach) },
             };
         }
         const profile = runner.profile;
@@ -198,8 +262,10 @@ function projectEngineProbe(result, name) {
 }
 function projectSelectedEngineProbe(availability, engineName, checkName) {
     const result = availability.get(engineName);
-    if (result)
-        return projectEngineProbe(result, checkName);
+    if (result) {
+        const projected = projectEngineProbe(result, checkName);
+        return checkName === "default-llm-engine" ? escalateDefaultLlmEngineFailure(projected) : projected;
+    }
     return {
         name: checkName,
         kind: "deterministic",
@@ -245,30 +311,36 @@ function configuredEnginesProjection(engineNames, availability) {
         evidence: { engines },
     };
 }
-export function runDefaultEngineProbe(deps = {}) {
+export async function runDefaultEngineProbe(deps = {}) {
     // Probe the effective view: an install with no `defaults.engine` but a usable
     // opencode binary DOES have a working default, and reporting otherwise would
     // contradict what `workflow run` / `task run` actually do.
     const { config } = withEngineFallback(deps.loadConfig?.() ?? loadConfig(), deps.which);
-    return runConfiguredEngineProbe("default-engine", config.defaults?.engine, config, deps);
+    return runConfiguredEngineProbe("default-engine", config.defaults?.engine, config, deps, new Map());
 }
-export function runDefaultLlmEngineProbe(deps = {}) {
+export async function runDefaultLlmEngineProbe(deps = {}) {
     const config = deps.loadConfig?.() ?? loadConfig();
-    return runConfiguredEngineProbe("default-llm-engine", config.defaults?.llmEngine, config, deps);
+    const engineName = config.defaults?.llmEngine;
+    if (!engineName)
+        return unconfiguredEngineProbe("default-llm-engine");
+    const result = await runConfiguredEngineProbe("configured-engine", engineName, config, deps, new Map());
+    return projectSelectedEngineProbe(new Map([[engineName, result]]), engineName, "default-llm-engine");
 }
 /** Probe every explicitly configured engine without exposing connection or model material. */
-export function runConfiguredEnginesProbe(deps = {}) {
+export async function runConfiguredEnginesProbe(deps = {}) {
     const config = deps.loadConfig?.() ?? loadConfig();
     const engineNames = Object.keys(config.engines ?? {}).sort();
-    const availability = new Map(engineNames.map((engine) => [engine, runConfiguredEngineProbe("configured-engine", engine, config, deps)]));
+    const cache = new Map();
+    const availability = new Map(await Promise.all(engineNames.map(async (engine) => [engine, await runConfiguredEngineProbe("configured-engine", engine, config, deps, cache)])));
     return configuredEnginesProjection(engineNames, availability);
 }
 /**
  * Build the per-health-run availability snapshot. Each distinct selected or
- * explicitly configured engine is probed once; the three public checks are
- * projections of that immutable result set.
+ * explicitly configured engine is probed once (reachability probes further
+ * de-duped by endpoint, see {@link ReachabilityCache}); the three public
+ * checks are projections of that immutable result set.
  */
-export function runHealthEngineProbes(deps = {}) {
+export async function runHealthEngineProbes(deps = {}) {
     const configured = deps.loadConfig?.() ?? loadConfig();
     const effective = withEngineFallback(configured, deps.which).config;
     const defaultEngineName = effective.defaults?.engine;
@@ -277,7 +349,8 @@ export function runHealthEngineProbes(deps = {}) {
     const probeNames = [...new Set([...explicitEngineNames, defaultEngineName, defaultLlmEngineName])]
         .filter((name) => name !== undefined)
         .sort();
-    const availability = new Map(probeNames.map((engine) => [engine, runConfiguredEngineProbe("configured-engine", engine, effective, deps)]));
+    const cache = new Map();
+    const availability = new Map(await Promise.all(probeNames.map(async (engine) => [engine, await runConfiguredEngineProbe("configured-engine", engine, effective, deps, cache)])));
     return Object.freeze({
         defaultEngine: defaultEngineName
             ? projectSelectedEngineProbe(availability, defaultEngineName, "default-engine")
@@ -314,17 +387,32 @@ export function runActiveImproveStrategyProbe(deps = {}) {
                 unavailableProcesses.push("triage.judgment");
             }
         }
+        // #913: name the engine each process actually resolved to, so a
+        // strategy-level `engine` pin that shadows `defaults.llmEngine` is
+        // visible on `akm health` instead of requiring config archaeology.
+        const engines = {};
+        for (const [name, process] of Object.entries(plan.processes)) {
+            if (process.enabled && process.runner)
+                engines[name] = process.runner.engine;
+        }
+        if (plan.triageJudgment)
+            engines["triage.judgment"] = plan.triageJudgment.engine;
+        const engineList = Object.entries(engines)
+            .sort(([a], [b]) => a.localeCompare(b))
+            .map(([process, engine]) => `${process}: "${engine}"`)
+            .join(", ");
         return {
             name: "active-improve-strategy",
             kind: "deterministic",
             status: unavailableProcesses.length === 0 ? "pass" : "warn",
             confidence: "high",
             message: unavailableProcesses.length === 0
-                ? `Active improve strategy "${plan.strategy.name}" has available process engines.`
-                : `Active improve strategy "${plan.strategy.name}" has unavailable required credentials for: ${unavailableProcesses.join(", ")}.`,
+                ? `Active improve strategy "${plan.strategy.name}" has available process engines${engineList ? ` (${engineList})` : ""}.`
+                : `Active improve strategy "${plan.strategy.name}" has unavailable required credentials for: ${unavailableProcesses.join(", ")}${engineList ? ` (engines: ${engineList})` : ""}.`,
             evidence: {
                 strategy: plan.strategy.name,
                 unavailableProcesses,
+                engines,
             },
         };
     }
@@ -437,8 +525,11 @@ export function runSelectedModelAliasesProbe(deps = {}) {
     const outcomes = selected.map(({ engine, alias, modelMapKey }) => {
         try {
             const resolution = resolveModelMapAlias(alias, modelMapKey, modelMap.map);
-            return resolution.interpretation === "alias"
-                ? { kind: "alias", evidence: { engine, alias, modelMapKey } }
+            if (resolution.interpretation === "alias") {
+                return { kind: "alias", evidence: { engine, alias, modelMapKey } };
+            }
+            return resolution.unmappedForEngine
+                ? { kind: "missing", evidence: { engine, alias, modelMapKey } }
                 : { kind: "exact" };
         }
         catch {
@@ -664,34 +755,58 @@ export const HEALTH_CHECKS = [
         },
     },
     {
+        // #914: derived from the `extract_sessions_seen` LEDGER, not
+        // `improve_runs.result_json` — the hook-driven `akm proposal extract
+        // --session-id ...` (the standard Claude Code plugin setup) never writes
+        // an `improve_runs` row, so the old improve_runs-only source reported
+        // "not active" as `pass` unconditionally on a plugin-driven machine, no
+        // matter how healthy or broken extraction actually was.
         name: "session-extraction",
         channel: "advisory",
         run: (ctx) => {
-            const sx = ctx.sessionExtraction;
-            const sxWarnReasons = [];
-            if (sx.warnings > 0)
-                sxWarnReasons.push(`${sx.warnings} harness error(s)`);
-            if (sx.ran && sx.sessionsScanned >= 5 && sx.proposalsCreated === 0)
-                sxWarnReasons.push("no proposals generated across scanned sessions");
-            return {
+            const { since: ledgerSince, rows } = ctx.sessionExtractionLedger;
+            const days = SESSION_EXTRACTION_LEDGER_WINDOW_DAYS;
+            const base = {
                 name: "session-extraction",
                 kind: "heuristic",
-                status: sxWarnReasons.length > 0 ? "warn" : "pass",
-                confidence: sx.ran ? "medium" : "low",
-                message: sx.ran
-                    ? sxWarnReasons.length > 0
-                        ? `Session extraction degraded: ${sxWarnReasons.join("; ")}.`
-                        : `Session extraction healthy: ${sx.sessionsScanned} scanned, ${sx.sessionsExtracted} extracted, ${sx.proposalsCreated} proposal(s) created.`
-                    : "Session extraction not active (feature disabled or no harness available).",
-                evidence: {
-                    ran: sx.ran,
-                    sessionsScanned: sx.sessionsScanned,
-                    sessionsExtracted: sx.sessionsExtracted,
-                    sessionsSkipped: sx.sessionsSkipped,
-                    proposalsCreated: sx.proposalsCreated,
-                    warnings: sx.warnings,
-                    durationMs: sx.durationMs,
-                },
+                confidence: "medium",
+                evidence: { ledgerSince, ledgerRows: rows },
+            };
+            const totalRows = rows.reduce((sum, row) => sum + row.count, 0);
+            if (totalRows === 0) {
+                return { ...base, status: "unknown", message: `No extraction recorded in the last ${days} days.` };
+            }
+            // `read_failed` / `exception` land in the ledger as `failed`, not `skipped`.
+            const nothingHarvested = rows.every((row) => row.outcome === "skipped" || row.outcome === "failed");
+            const knownSkipReasons = [...new Set(rows.flatMap((row) => (row.skipReason ? [row.skipReason] : [])))].sort();
+            const allKnownReasonsAreInfra = knownSkipReasons.every((reason) => EXTRACT_INFRASTRUCTURE_SKIP_REASONS.includes(reason));
+            if (nothingHarvested && allKnownReasonsAreInfra) {
+                const reasonClauses = knownSkipReasons.map((reason) => {
+                    const engines = [
+                        ...new Set(rows.flatMap((row) => (row.skipReason === reason && row.engine ? [row.engine] : []))),
+                    ].sort();
+                    return engines.length > 0 ? `${reason} (engine ${engines.map((e) => `"${e}"`).join(", ")})` : reason;
+                });
+                if (rows.some((row) => row.skipReason === null))
+                    reasonClauses.push("unknown reason");
+                const verb = rows.some((row) => row.outcome === "failed") ? "skipped or failed" : "skipped";
+                return {
+                    ...base,
+                    status: "warn",
+                    message: `${totalRows} of ${totalRows} sessions in the last ${days} days ${verb}: ${reasonClauses.join(", ")}.`,
+                };
+            }
+            const outcomeCounts = new Map();
+            for (const row of rows)
+                outcomeCounts.set(row.outcome, (outcomeCounts.get(row.outcome) ?? 0) + row.count);
+            const outcomeSummary = [...outcomeCounts.entries()]
+                .sort(([a], [b]) => a.localeCompare(b))
+                .map(([outcome, count]) => `${outcome}: ${count}`)
+                .join(", ");
+            return {
+                ...base,
+                status: "pass",
+                message: `Session extraction active in the last ${days} days (${outcomeSummary}).`,
             };
         },
     },

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

@@ -200,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)
@@ -219,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 };
     }
 }
 /**

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/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 };
 }