akm-cli 0.9.14 → 0.9.15-beta.1

package/dist/commands/health/checks.js

@@ -3,15 +3,19 @@
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
 import { spawnSync } from "node:child_process";
 import { loadConfig } from "../../core/config/config.js";
+import { IMPROVE_PROCESS_ENGINE_CAPABILITIES } from "../../core/config/engine-semantics.js";
+import { listEnvsRecursive } from "../../core/env-secret-ref.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";
+import { isLlmCredentialAvailable, resolveEngine, } from "../../integrations/agent/engine-resolution.js";
 import { executionEngineDefinitionsFromConfig } from "../../integrations/agent/execution-definitions.js";
 import { loadModelMap, mergeModelMapLayers, parseModelMapLayer, readInstalledModelMapText, resolveModelMapAlias, userModelMapPath, } from "../../integrations/agent/model-map.js";
+import { listKeys } from "../env/env.js";
 import { resolveImprovePlan } from "../improve/improve-strategies.js";
-import { ACTIVE_RUN_WARN_MS, TASK_FAIL_RATE_WARN } from "./types.js";
+import { ENGINE_LAST_USED_LOOKBACK_DAYS } from "./engine-usage.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)
@@ -43,15 +47,64 @@ function escalateDefaultLlmEngineFailure(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()));
-    // #905: an engine with no env descriptor may still require a file-backed
-    // credential — probe it too, rather than reporting an unreadable/empty
-    // apiKeyFile as available just because it carries no env var names.
-    if (apiKeyFile !== undefined)
-        return lookupApiKeyFileValue(apiKeyFile) !== undefined;
-    return true;
+/**
+ * Delegates to {@link isLlmCredentialAvailable} (#953) so `akm health` and the
+ * improve-strategy probe (#957 builds on this same helper) share one
+ * non-throwing "is a credential present" check with the real dispatch
+ * boundary — env value, file-backed (#905), or secret-store-backed (#953).
+ */
+function credentialAvailable(credential, env, apiKeyFile, apiKeySecretRef) {
+    return isLlmCredentialAvailable({ credential, apiKeyFile, apiKeySecretRef }, env);
+}
+/**
+ * #950: when a required `$VAR`-style credential is missing from the shell,
+ * find the env asset (if any) whose key names include one of
+ * `credential.names` — so the warn can say "run under env/lab" instead of a
+ * bare "unavailable". Returns the asset's ref, or `null` when no credential,
+ * no candidate names, or no matching env asset. Never returns or logs the
+ * variable name itself (only ref/path/keys ever leave `listEnvsRecursive`,
+ * and only the ref is read here) — `tests/health-engine-probe.test.ts` pins
+ * that a credential's env-var name never appears in health's JSON output.
+ * Best-effort: any failure walking env assets (unreadable stash, bad config)
+ * degrades to `null`, never a crash. `deps.listEnvAssets` is expected to
+ * already be normalised (see {@link withMemoizedEnvAssets}) by the time this
+ * runs, so the walk happens at most once per probe run — every caller of
+ * this function passes deps that have already gone through
+ * {@link withMemoizedEnvAssets}, so there is no separate default to fall
+ * back to here.
+ */
+function findSuppliedByEnvAsset(credential, deps) {
+    if (!credential || credential.names.length === 0)
+        return null;
+    try {
+        const envs = deps.listEnvAssets?.();
+        if (!envs)
+            return null;
+        for (const envAsset of envs) {
+            if (credential.names.some((name) => envAsset.keys.includes(name)))
+                return envAsset.ref;
+        }
+    }
+    catch {
+        // Best-effort — env-asset discovery must never break a health probe.
+    }
+    return null;
+}
+/**
+ * #950: normalise `deps.listEnvAssets` once per probe run so
+ * {@link findSuppliedByEnvAsset}'s env-asset walk happens at most once even
+ * when a run probes several engines with missing credentials — the walk is
+ * real IO (or config-injected IO in tests) with no reason to repeat per
+ * engine. Wraps whatever seam is already present (test-injected or the
+ * config-honouring default) in a memoising closure; called once by each of
+ * the four probe entry points that share {@link runConfiguredEngineProbe}
+ * (`runDefaultEngineProbe`, `runDefaultLlmEngineProbe`,
+ * `runConfiguredEnginesProbe`, `runHealthEngineProbes`).
+ */
+function withMemoizedEnvAssets(deps) {
+    const listEnvAssets = deps.listEnvAssets ?? (() => listEnvsRecursive(listKeys, (deps.loadConfig ?? loadConfig)()));
+    let cached;
+    return { ...deps, listEnvAssets: () => (cached ??= listEnvAssets()) };
 }
 async function runConfiguredEngineProbe(checkName, engineName, config, deps, reachabilityCache) {
     if (!engineName) {
@@ -97,6 +150,7 @@ async function runConfiguredEngineProbe(checkName, engineName, config, deps, rea
         let fallback;
         let fallbackCredential;
         let fallbackApiKeyFile;
+        let fallbackApiKeySecretRef;
         let sdkRunner;
         const resolve = deps.resolveEngine ?? resolveEngine;
         try {
@@ -111,6 +165,7 @@ async function runConfiguredEngineProbe(checkName, engineName, config, deps, rea
             fallback = { kind: "llm", engine: fallbackEngine, connection: sdkRunner.fallbackConnection };
             fallbackCredential = sdkRunner.fallbackCredential;
             fallbackApiKeyFile = sdkRunner.fallbackApiKeyFile;
+            fallbackApiKeySecretRef = sdkRunner.fallbackApiKeySecretRef;
         }
         else if (fallbackEngine) {
             try {
@@ -119,6 +174,7 @@ async function runConfiguredEngineProbe(checkName, engineName, config, deps, rea
                     fallback = resolved;
                     fallbackCredential = resolved.credential;
                     fallbackApiKeyFile = resolved.apiKeyFile;
+                    fallbackApiKeySecretRef = resolved.apiKeySecretRef;
                 }
             }
             catch {
@@ -127,12 +183,19 @@ async function runConfiguredEngineProbe(checkName, engineName, config, deps, rea
         }
         const configuredModel = configuredEngine.model;
         const effectiveModel = sdkRunner?.profile.model ?? configuredModel ?? fallback?.connection.model;
-        const fallbackCredentialAvailable = credentialAvailable(fallbackCredential, env, fallbackApiKeyFile);
+        const fallbackCredentialAvailable = credentialAvailable(fallbackCredential, env, fallbackApiKeyFile, fallbackApiKeySecretRef);
+        const fallbackSuppliedByEnvAsset = !fallbackCredentialAvailable
+            ? findSuppliedByEnvAsset(fallbackCredential, deps)
+            : null;
         const missing = [
             !packageAvailable ? "@opencode-ai/sdk package" : undefined,
             !binaryAvailable ? `${binary} binary` : undefined,
             fallbackEngine && !fallback ? "configured fallback LLM connection" : undefined,
-            !fallbackCredentialAvailable ? "required fallback credential" : undefined,
+            !fallbackCredentialAvailable
+                ? fallbackSuppliedByEnvAsset
+                    ? `required fallback credential (available via env asset ${fallbackSuppliedByEnvAsset}; run under it: akm env run ${fallbackSuppliedByEnvAsset} -- ...)`
+                    : "required fallback credential"
+                : undefined,
         ].filter((value) => value !== undefined);
         const sdkEvidence = {
             engine: engineName,
@@ -149,6 +212,7 @@ async function runConfiguredEngineProbe(checkName, engineName, config, deps, rea
             fallbackEndpoint: fallback?.connection.endpoint ?? null,
             fallbackModel: fallback?.connection.model ?? null,
             requiredCredentialAvailable: fallbackCredentialAvailable,
+            suppliedByEnvAsset: fallbackSuppliedByEnvAsset,
         };
         if (missing.length > 0) {
             return {
@@ -181,7 +245,7 @@ async function runConfiguredEngineProbe(checkName, engineName, config, deps, rea
     try {
         const runner = (deps.resolveEngine ?? resolveEngine)(engineName, config);
         if (runner.kind === "llm") {
-            const requiredCredentialAvailable = credentialAvailable(runner.credential, env, runner.apiKeyFile);
+            const requiredCredentialAvailable = credentialAvailable(runner.credential, env, runner.apiKeyFile, runner.apiKeySecretRef);
             const llmEvidence = {
                 engine: engineName,
                 platform: null,
@@ -191,13 +255,20 @@ async function runConfiguredEngineProbe(checkName, engineName, config, deps, rea
                 requiredCredentialAvailable,
             };
             if (!requiredCredentialAvailable) {
+                // #950: a missing-in-shell credential is common when the operator's
+                // real workflow is `akm env run env/lab -- akm improve` — name the env
+                // asset that supplies it (never the variable name) so the warn is
+                // actionable instead of looking like a broken engine.
+                const suppliedByEnvAsset = findSuppliedByEnvAsset(runner.credential, deps);
                 return {
                     name: checkName,
                     kind: "deterministic",
                     status: "warn",
                     confidence: "high",
-                    message: `LLM engine "${engineName}" is configured, but its required credential is unavailable.`,
-                    evidence: llmEvidence,
+                    message: suppliedByEnvAsset
+                        ? `LLM engine "${engineName}" is configured, but its required credential is not available in this shell; env asset ${suppliedByEnvAsset} supplies it — run under it (akm env run ${suppliedByEnvAsset} -- ...).`
+                        : `LLM engine "${engineName}" is configured, but its required credential is unavailable.`,
+                    evidence: { ...llmEvidence, suppliedByEnvAsset },
                 };
             }
             const reach = await probeConnectionReachable(runner.connection, deps, reachabilityCache);
@@ -284,6 +355,57 @@ function unconfiguredEngineProbe(name) {
         message: name === "default-llm-engine" ? "No default LLM engine is configured." : "No default engine is configured.",
     };
 }
+/**
+ * #949: `enableThinking: false` is a request an engine's endpoint (or a
+ * gateway in front of it) can silently ignore — `chatCompletionAttemptOnce`
+ * (src/llm/client.ts) already warns to stderr whenever a response reports
+ * reasoning tokens despite it. This makes that same signal visible in
+ * `akm health` as a structured finding, purely by re-reading the window's
+ * `llm_usage` aggregate already threaded into the context: no extra
+ * completion call, no live probe — a cold local model must not be woken just
+ * to run `akm health`.
+ */
+function projectThinkingControlCheck(thinkingOffEngines, llmUsage, since) {
+    if (thinkingOffEngines.length === 0) {
+        return {
+            name: "thinking-control",
+            kind: "deterministic",
+            status: "unknown",
+            confidence: "high",
+            message: "No configured engine sets enableThinking: false — nothing to verify.",
+            evidence: { engines: [] },
+        };
+    }
+    const engines = [...thinkingOffEngines].sort().map((engine) => {
+        const usage = llmUsage.byEngine[engine];
+        const calls = usage?.calls ?? 0;
+        const reasoningTokens = usage?.reasoningTokens ?? 0;
+        const status = calls === 0 ? "unknown" : reasoningTokens > 0 ? "warn" : "pass";
+        return { engine, status, calls, reasoningTokens };
+    });
+    const warning = engines.filter((e) => e.status === "warn");
+    const status = warning.length > 0 ? "warn" : engines.every((e) => e.status === "unknown") ? "unknown" : "pass";
+    let message;
+    if (warning.length > 0) {
+        message = warning
+            .map((e) => `LLM engine "${e.engine}" returned ${e.reasoningTokens} reasoning tokens since ${since} despite enableThinking: false — the endpoint (or a gateway in front of it) is not honouring the thinking-off control.`)
+            .join(" ");
+    }
+    else if (status === "unknown") {
+        message = `No calls were recorded for the engine(s) configured with enableThinking: false (${engines.map((e) => e.engine).join(", ")}) in the report window.`;
+    }
+    else {
+        message = `${engines.length} engine(s) configured with enableThinking: false (${engines.map((e) => e.engine).join(", ")}) returned no reasoning tokens in the report window.`;
+    }
+    return {
+        name: "thinking-control",
+        kind: "deterministic",
+        status,
+        confidence: "high",
+        message,
+        evidence: { engines },
+    };
+}
 function configuredEnginesProjection(engineNames, availability) {
     if (engineNames.length === 0) {
         return {
@@ -316,14 +438,14 @@ export async function runDefaultEngineProbe(deps = {}) {
     // 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, new Map());
+    return runConfiguredEngineProbe("default-engine", config.defaults?.engine, config, withMemoizedEnvAssets(deps), new Map());
 }
 export async function runDefaultLlmEngineProbe(deps = {}) {
     const config = deps.loadConfig?.() ?? loadConfig();
     const engineName = config.defaults?.llmEngine;
     if (!engineName)
         return unconfiguredEngineProbe("default-llm-engine");
-    const result = await runConfiguredEngineProbe("configured-engine", engineName, config, deps, new Map());
+    const result = await runConfiguredEngineProbe("configured-engine", engineName, config, withMemoizedEnvAssets(deps), new Map());
     return projectSelectedEngineProbe(new Map([[engineName, result]]), engineName, "default-llm-engine");
 }
 /** Probe every explicitly configured engine without exposing connection or model material. */
@@ -331,7 +453,8 @@ export async function runConfiguredEnginesProbe(deps = {}) {
     const config = deps.loadConfig?.() ?? loadConfig();
     const engineNames = Object.keys(config.engines ?? {}).sort();
     const cache = new Map();
-    const availability = new Map(await Promise.all(engineNames.map(async (engine) => [engine, await runConfiguredEngineProbe("configured-engine", engine, config, deps, cache)])));
+    const runDeps = withMemoizedEnvAssets(deps);
+    const availability = new Map(await Promise.all(engineNames.map(async (engine) => [engine, await runConfiguredEngineProbe("configured-engine", engine, config, runDeps, cache)])));
     return configuredEnginesProjection(engineNames, availability);
 }
 /**
@@ -350,7 +473,8 @@ export async function runHealthEngineProbes(deps = {}) {
         .filter((name) => name !== undefined)
         .sort();
     const cache = new Map();
-    const availability = new Map(await Promise.all(probeNames.map(async (engine) => [engine, await runConfiguredEngineProbe("configured-engine", engine, effective, deps, cache)])));
+    const runDeps = withMemoizedEnvAssets(deps);
+    const availability = new Map(await Promise.all(probeNames.map(async (engine) => [engine, await runConfiguredEngineProbe("configured-engine", engine, effective, runDeps, cache)])));
     return Object.freeze({
         defaultEngine: defaultEngineName
             ? projectSelectedEngineProbe(availability, defaultEngineName, "default-engine")
@@ -361,32 +485,34 @@ export async function runHealthEngineProbes(deps = {}) {
         configuredEngines: configuredEnginesProjection(explicitEngineNames, availability),
     });
 }
-export function runActiveImproveStrategyProbe(deps = {}) {
+/**
+ * #950: probes the active improve strategy and returns both its
+ * `HealthCheckResult` and the typed process→engine map, computed once. See
+ * {@link runActiveImproveStrategyProbe} for the plain-`HealthCheckResult`
+ * wrapper existing callers/tests use.
+ */
+export function probeActiveImproveStrategy(deps = {}) {
     const config = deps.loadConfig?.() ?? loadConfig();
     const strategyName = config.defaults?.improveStrategy ?? "default";
+    const env = deps.env ?? process.env;
     try {
-        const plan = resolveImprovePlan(strategyName, config);
-        const env = deps.env ?? process.env;
-        const unavailableProcesses = Object.entries(plan.processes).flatMap(([name, process]) => {
-            if (!process.enabled || !process.runner)
-                return [];
-            return credentialAvailable(process.runner.credential, env, process.runner.apiKeyFile) ? [] : [name];
-        });
-        if (plan.triageJudgment) {
-            const judgmentCredential = plan.triageJudgment.kind === "llm"
-                ? plan.triageJudgment.credential
-                : plan.triageJudgment.kind === "sdk"
-                    ? plan.triageJudgment.fallbackCredential
-                    : undefined;
-            const judgmentApiKeyFile = plan.triageJudgment.kind === "llm"
-                ? plan.triageJudgment.apiKeyFile
-                : plan.triageJudgment.kind === "sdk"
-                    ? plan.triageJudgment.fallbackApiKeyFile
-                    : undefined;
-            if (!credentialAvailable(judgmentCredential, env, judgmentApiKeyFile)) {
-                unavailableProcesses.push("triage.judgment");
-            }
-        }
+        // #957: credential availability (including the triage-judgment engine) is
+        // now derived once, inside `buildImprovePlan` itself — the same
+        // `plan.engineUnavailable` the real `improve` run reads to skip processes
+        // and populate `AkmImproveResult.skippedProcesses`. This check is a pure
+        // projection of that list rather than its own re-derivation.
+        //
+        // `allowAllDisabled: true` because a strategy left with every process
+        // disabled purely by credential unavailability must still come back as
+        // an inspectable plan here, not a thrown ConfigError — the
+        // `allRequiredUnavailable`/`fail` logic below needs `plan.engineUnavailable`
+        // to run this check's fail path instead of falling into the generic
+        // catch block's warn/unknown fallback (round 2 finding on #957). A
+        // strategy with no engine configured at all still throws (see
+        // `allowAllDisabled`'s doc comment) and keeps hitting that catch block,
+        // unchanged from before this fix.
+        const plan = resolveImprovePlan(strategyName, config, { env, allowAllDisabled: true });
+        const unavailableProcesses = plan.engineUnavailable.map((item) => item.process);
         // #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.
@@ -401,37 +527,133 @@ export function runActiveImproveStrategyProbe(deps = {}) {
             .sort(([a], [b]) => a.localeCompare(b))
             .map(([process, engine]) => `${process}: "${engine}"`)
             .join(", ");
+        // #957: fail only when the strategy's LLM-backed work would be a total
+        // no-op — every process the strategy actually enabled among the
+        // `capability: "llm"` set (see IMPROVE_PROCESS_ENGINE_CAPABILITIES) ended
+        // up unavailable. A partial failure (some processes still have a working
+        // engine) stays a `warn`, matching #914's "a credential warn stays a warn"
+        // policy for the general per-engine probes; this is the strategy-scoped
+        // "is the whole run a no-op" question instead.
+        const llmProcessNames = Object.keys(IMPROVE_PROCESS_ENGINE_CAPABILITIES).filter((name) => IMPROVE_PROCESS_ENGINE_CAPABILITIES[name] === "llm");
+        const requiredLlmProcessNames = llmProcessNames.filter((name) => plan.processes[name].enabled || plan.engineUnavailable.some((item) => item.process === name));
+        const availableLlmProcessNames = llmProcessNames.filter((name) => plan.processes[name].enabled);
+        const allRequiredUnavailable = requiredLlmProcessNames.length > 0 && availableLlmProcessNames.length === 0;
+        const status = unavailableProcesses.length === 0 ? "pass" : allRequiredUnavailable ? "fail" : "warn";
         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${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,
+            check: {
+                name: "active-improve-strategy",
+                kind: "deterministic",
+                status,
+                confidence: "high",
+                message: unavailableProcesses.length === 0
+                    ? `Active improve strategy "${plan.strategy.name}" has available process engines${engineList ? ` (${engineList})` : ""}.`
+                    : allRequiredUnavailable
+                        ? `Active improve strategy "${plan.strategy.name}" cannot run any LLM-backed process; the nightly run would be a no-op: ${unavailableProcesses.join(", ")}${engineList ? ` (engines: ${engineList})` : ""}.`
+                        : `Active improve strategy "${plan.strategy.name}" has unavailable required credentials for: ${unavailableProcesses.join(", ")}${engineList ? ` (engines: ${engineList})` : ""}.`,
+                evidence: {
+                    strategy: plan.strategy.name,
+                    unavailableProcesses,
+                    engines,
+                },
             },
+            processEngines: Object.freeze({ ...engines }),
         };
     }
     catch (error) {
         const explicitlyConfigured = config.defaults?.improveStrategy !== undefined || Object.keys(config.improve?.strategies ?? {}).length > 0;
         return {
-            name: "active-improve-strategy",
+            check: {
+                name: "active-improve-strategy",
+                kind: "deterministic",
+                status: explicitlyConfigured ? "warn" : "unknown",
+                confidence: "high",
+                message: `Active improve strategy "${strategyName}" is unavailable: ${error instanceof Error ? error.message : String(error)}`,
+                evidence: { strategy: strategyName, unavailableProcesses: [] },
+            },
+            processEngines: {},
+        };
+    }
+}
+/** Plain-`HealthCheckResult` wrapper around {@link probeActiveImproveStrategy} for existing callers/tests. */
+export function runActiveImproveStrategyProbe(deps = {}) {
+    return probeActiveImproveStrategy(deps).check;
+}
+/**
+ * #950: the `engine-last-used` advisory. Pure projection of context computed
+ * once in `health.ts` (`activeImproveStrategyEngines`, `engineLastUsed`,
+ * `improveRunsInLookbackWindow`) — no IO here, mirrors `thinking-control`.
+ *
+ * `unknown` (not a noisy `warn`) both when no engine is bound to an enabled
+ * process, AND when no improve run has been recorded (started) in the
+ * lookback window at all — a fresh install has never been given the chance
+ * to use its engines.
+ */
+function projectEngineLastUsedCheck(processEngineMap, lastUsed, improveRunsInLookbackWindow, lookbackDays) {
+    const engineProcesses = new Map();
+    for (const [process, engine] of Object.entries(processEngineMap)) {
+        const processes = engineProcesses.get(engine) ?? [];
+        processes.push(process);
+        engineProcesses.set(engine, processes);
+    }
+    const engines = [...engineProcesses.keys()].sort();
+    if (engines.length === 0) {
+        return {
+            name: "engine-last-used",
+            kind: "deterministic",
+            status: "unknown",
+            confidence: "high",
+            message: "No engine is bound to an enabled improve process.",
+            evidence: { engines: [] },
+        };
+    }
+    if (improveRunsInLookbackWindow === 0) {
+        return {
+            name: "engine-last-used",
             kind: "deterministic",
-            status: explicitlyConfigured ? "warn" : "unknown",
+            status: "unknown",
             confidence: "high",
-            message: `Active improve strategy "${strategyName}" is unavailable: ${error instanceof Error ? error.message : String(error)}`,
-            evidence: { strategy: strategyName, unavailableProcesses: [] },
+            message: `No improve runs in the last ${lookbackDays} days.`,
+            evidence: {
+                engines: engines.map((engine) => ({ engine, processes: (engineProcesses.get(engine) ?? []).sort() })),
+            },
         };
     }
+    const entries = engines.map((engine) => ({
+        engine,
+        processes: (engineProcesses.get(engine) ?? []).sort(),
+        lastUsedAt: lastUsed.get(engine)?.lastUsedAt ?? null,
+    }));
+    const idle = entries.filter((entry) => entry.lastUsedAt === null);
+    const status = idle.length > 0 ? "warn" : "pass";
+    const message = idle.length > 0
+        ? idle
+            .map((entry) => {
+            const quoted = entry.processes.map((process) => `"${process}"`).join(", ");
+            const noun = entry.processes.length === 1 ? "process" : "processes";
+            return `Engine "${entry.engine}" is bound to ${noun} ${quoted} but has not been used in the last ${lookbackDays} days.`;
+        })
+            .join(" ")
+        : entries
+            .map((entry) => {
+            const process = lastUsed.get(entry.engine)?.process ?? entry.processes.join(", ");
+            return `Engine "${entry.engine}" last used by "${process}" at ${entry.lastUsedAt}.`;
+        })
+            .join(" ");
+    return {
+        name: "engine-last-used",
+        kind: "deterministic",
+        status,
+        confidence: "high",
+        message,
+        evidence: { engines: entries },
+    };
 }
 /**
  * Validate the immutable installed model map and optional user overlay.
  * Installed corruption is a package defect (fail); a bad optional user file
- * is operator-fixable configuration (warn); absence is the normal state.
+ * (including an `engine`-backed profile referencing a missing/broken engine,
+ * once resolved against real `config.engines` — #946) is operator-fixable
+ * configuration (warn); absence is the normal state.
  */
 export function runModelMapProbe(options = {}) {
     let installedText;
@@ -449,8 +671,20 @@ export function runModelMapProbe(options = {}) {
             evidence: { installedSource: "package asset" },
         };
     }
+    // Load config OUTSIDE the models.json try/catch below: a broken
+    // config.json must surface as a config problem reported by the config
+    // checks, never get misreported as a models.json warning carrying the
+    // config error's own text. When config fails to load, validate the model
+    // map shape-only (no `engine` resolution), matching pre-#946 behavior.
+    let engines;
     try {
-        const loaded = loadModelMap({ ...options, installedText });
+        engines = (options.loadConfig?.() ?? loadConfig()).engines;
+    }
+    catch {
+        engines = undefined;
+    }
+    try {
+        const loaded = loadModelMap({ ...options, installedText, engines });
         return {
             name: "model-map-files",
             kind: "deterministic",
@@ -510,7 +744,11 @@ export function runSelectedModelAliasesProbe(deps = {}) {
     }
     let modelMap;
     try {
-        modelMap = (deps.loadModelMap ?? loadModelMap)({ env: deps.env, installedText: deps.installedText });
+        modelMap = (deps.loadModelMap ?? loadModelMap)({
+            env: deps.env,
+            installedText: deps.installedText,
+            engines: config.engines,
+        });
     }
     catch {
         return {
@@ -583,6 +821,22 @@ export function runPendingStateMigrationsCheck(stateDbPath, deps = {}) {
         evidence: { path: stateDbPath, pending },
     };
 }
+/**
+ * #943: name the dominant `detail.reason` behind `task-fail-rate`'s warning
+ * when one reason accounts for at least half of the window's command-task
+ * failures — e.g. "(timeout-dominant: 9/12 command-task failures)" — so an
+ * operator sees the shape of the failure from data instead of grepping task
+ * logs. Ties break on reason name for determinism. `undefined` when there are
+ * no counted failures or no single reason reaches the 50% floor.
+ */
+export function dominantAgentFailureReason(counts) {
+    const entries = Object.entries(counts);
+    const total = entries.reduce((sum, [, count]) => sum + count, 0);
+    if (total === 0)
+        return undefined;
+    const [reason, count] = entries.reduce((best, entry) => entry[1] > best[1] || (entry[1] === best[1] && entry[0] < best[0]) ? entry : best);
+    return count / total >= 0.5 ? { reason, count, total } : undefined;
+}
 /**
  * The ordered health-check registry. ORDER IS LOAD-BEARING: `akmHealth`
  * iterates this array and appends to hardChecks/advisories in sequence, so the
@@ -699,7 +953,10 @@ export const HEALTH_CHECKS = [
     {
         name: "active-improve-strategy",
         channel: "hard",
-        run: () => runActiveImproveStrategyProbe(),
+        // #950: projects the context field instead of recomputing, so
+        // `engine-last-used` below can reuse the same process→engine map without
+        // a second `runActiveImproveStrategyProbe()` call.
+        run: (ctx) => ctx.activeImproveStrategy,
     },
     {
         // C2 (13-bus-factor): the cron task-failure rate was computed and rendered
@@ -721,6 +978,14 @@ export const HEALTH_CHECKS = [
             const worst = ctx.worstTaskFailRate;
             const worstWarn = worst !== null && worst.rate >= TASK_FAIL_RATE_WARN;
             const warn = aggregateWarn || worstWarn;
+            // #943: name the dominant command-task failure reason (timeout,
+            // non_zero_exit, spawn_failed, …) when the check is already warning, so
+            // "timeout-dominant" is visible without grepping task logs.
+            const agentFailureReasonCounts = ctx.agentFailureReasonCounts ?? {};
+            const dominant = warn ? dominantAgentFailureReason(agentFailureReasonCounts) : undefined;
+            const dominantSuffix = dominant
+                ? ` (${dominant.reason}-dominant: ${dominant.count}/${dominant.total} command-task failures)`
+                : "";
             let message;
             if (ctx.taskRowCount === 0) {
                 message = `No cron tasks ran since ${ctx.since} — no task-fail-rate signal.`;
@@ -734,7 +999,7 @@ export const HEALTH_CHECKS = [
                     const worstPctStr = `${(worst.rate * 100).toFixed(1)}%`;
                     parts.push(`task "${worst.taskId}" fails ${worstPctStr} of its ${worst.rows} run(s) ≥ ${thresholdPct}`);
                 }
-                message = `Cron task fail rate warning: ${parts.join("; ")} — inspect failed runs (ok=false) for early-exit/harness errors.`;
+                message = `Cron task fail rate warning: ${parts.join("; ")}${dominantSuffix} — inspect failed runs (ok=false) for early-exit/harness errors.`;
             }
             else {
                 message = `Cron task fail rate ${pctStr} across ${ctx.taskRowCount} task(s) since ${ctx.since} (below ${thresholdPct} threshold).`;
@@ -750,6 +1015,9 @@ export const HEALTH_CHECKS = [
                     taskRowCount: ctx.taskRowCount,
                     threshold: TASK_FAIL_RATE_WARN,
                     worstTaskFailRate: worst,
+                    // #943: always present (even pass/empty) so scripts reading evidence
+                    // never need to branch on check status to find the breakdown.
+                    agentFailureReasonCounts,
                 },
             };
         },
@@ -877,4 +1145,30 @@ export const HEALTH_CHECKS = [
             };
         },
     },
+    {
+        // #949: advisory channel, but `kind: "deterministic"` (same as the
+        // pre-existing task-fail-rate advisory) — a warn here DOES flip
+        // AkmHealthResult.status to "warn" and akm health's exit code to
+        // EXIT_HEALTH_WARN, because the overall-status computation ORs
+        // deterministic warns across both hardChecks and advisories.
+        name: "thinking-control",
+        channel: "advisory",
+        run: (ctx) => projectThinkingControlCheck(ctx.thinkingOffEngines, ctx.llmUsage, ctx.since),
+    },
+    {
+        // #950: best-effort "installed vs latest release" advisory, gated behind
+        // the same --probe/--no-probe flag as engine reachability. Computed once
+        // in health.ts (network IO), projected here like engineProbes.
+        name: "cli-version",
+        channel: "advisory",
+        run: (ctx) => ctx.versionDrift,
+    },
+    {
+        // #950: registered last — order is load-bearing (see the HEALTH_CHECKS
+        // doc comment above). Advisory channel, `kind: "deterministic"` — same
+        // exit-code-gating rationale as thinking-control above.
+        name: "engine-last-used",
+        channel: "advisory",
+        run: (ctx) => projectEngineLastUsedCheck(ctx.activeImproveStrategyEngines, ctx.engineLastUsed, ctx.improveRunsInLookbackWindow, ENGINE_LAST_USED_LOOKBACK_DAYS),
+    },
 ];