akm-cli 0.9.10 → 0.9.12

package/dist/commands/config-cli.js

@@ -111,7 +111,10 @@ export const configCommand = defineGroupCommand({
             },
         }),
         set: defineJsonCommand({
-            meta: { name: "set", description: "Set a configuration value by key" },
+            meta: {
+                name: "set",
+                description: "Set a configuration value by key; prints the resulting config with ok: true",
+            },
             args: {
                 key: {
                     type: "positional",
@@ -124,7 +127,7 @@ export const configCommand = defineGroupCommand({
                 // writes don't pollute their host's output stream.
                 silent: {
                     type: "boolean",
-                    description: "Suppress the post-write config dump on stdout. Use from hooks and CI scripts; the write still happens and errors still print.",
+                    description: "Suppress the post-write config dump on stdout entirely (prints nothing; exit code is the status). Use from hooks and CI scripts; the write still happens and errors still print.",
                     default: false,
                 },
             },
@@ -136,12 +139,15 @@ export const configCommand = defineGroupCommand({
             },
         }),
         unset: defineJsonCommand({
-            meta: { name: "unset", description: "Unset an optional configuration key or whole embedding/engine section" },
+            meta: {
+                name: "unset",
+                description: "Unset an optional configuration key or whole embedding/engine section; prints the resulting config with ok: true",
+            },
             args: {
                 key: { type: "positional", required: true, description: "Config key to unset" },
                 silent: {
                     type: "boolean",
-                    description: "Suppress the post-write config dump on stdout.",
+                    description: "Suppress the post-write config dump on stdout entirely (prints nothing; exit code is the status).",
                     default: false,
                 },
             },

package/dist/commands/env/env-binding.js

@@ -84,13 +84,20 @@ export function resolveEnvBinding(target, options = {}) {
     const dangerous = keys.filter(isDangerousEnvKey);
     if (dangerous.length > 0) {
         const detail = `Env "${envRef}" injects process-hijacking variable(s): ${dangerous.join(", ")}.`;
-        const decision = decideDangerousEnvInjection({ dangerousKeys: dangerous, thirdParty: Boolean(source.registryId) });
+        const decision = decideDangerousEnvInjection({
+            dangerousKeys: dangerous,
+            thirdParty: Boolean(source.registryId),
+            allowInsecure: options.allowInsecure,
+        });
         if (decision === "block") {
             throw new UsageError(`Refusing to inject env from a third-party stash. ${detail}\n` +
-                `       Review the file, then copy the values into a first-party env if you trust them.`, "INVALID_FLAG_VALUE");
+                `       Review the file, then copy the values into a first-party env if you trust them, ` +
+                `or pass --allow-insecure once you have.`, "INVALID_FLAG_VALUE");
         }
         if (decision === "warn") {
-            warn(`${detail} Injecting anyway (first-party stash).`);
+            warn(options.allowInsecure && source.registryId
+                ? `${detail} Injecting anyway (--allow-insecure).`
+                : `${detail} Injecting anyway (first-party stash).`);
         }
     }
     // Audit trail: keys only, never values.

package/dist/commands/env/env-cli.js

@@ -255,6 +255,7 @@ async function runEnvInjected(target, opts) {
     const { values: envValues } = resolveEnvBinding(target, {
         only: opts.only,
         except: opts.except,
+        allowInsecure: opts.allowInsecure,
     });
     const mergedEnv = buildChildEnv(process.env, {
         clean: opts.clean === true,
@@ -323,6 +324,11 @@ const envRunCommand = defineJsonCommand({
             type: "string",
             description: "When used with --clean, also inherit these parent env vars (comma-separated). Ignored without --clean.",
         },
+        "allow-insecure": {
+            type: "boolean",
+            description: "Allow injecting a process-hijacking variable (e.g. LD_PRELOAD, GIT_SSH_COMMAND) from a third-party stash, which otherwise blocks. Use only after explicitly reviewing the env file.",
+            default: false,
+        },
     },
     async run({ args }) {
         await runEnvInjected(args.target, {
@@ -330,6 +336,7 @@ const envRunCommand = defineJsonCommand({
             except: parseKeyListFlag(args.except),
             clean: args.clean === true,
             inherit: parseKeyListFlag(args.inherit) ?? [],
+            allowInsecure: args["allow-insecure"] === true,
         });
     },
 });

package/dist/commands/env/secret-cli.js

@@ -32,11 +32,13 @@ import path from "node:path";
 import { getParsedInvocation } from "../../cli/invocation.js";
 import { getStringArg } from "../../cli/parse-args.js";
 import { defineGroupCommand, defineJsonCommand, output } from "../../cli/shared.js";
+import { decideDangerousEnvInjection } from "../../core/activation-policy.js";
 import { deriveCanonicalAssetName } from "../../core/asset/asset-placement.js";
 import { loadConfig } from "../../core/config/config.js";
 import { makeSecretRef, resolveSecretPath, resolveSecretWriteTarget, withEnvSecretWrite, } from "../../core/env-secret-ref.js";
 import { ConfigError, NotFoundError, UsageError } from "../../core/errors.js";
 import { appendEvent } from "../../core/events.js";
+import { warn } from "../../core/warn.js";
 import { resolveSourceEntries } from "../../indexer/search/search-source.js";
 import { readStdin } from "../../runtime.js";
 import { buildChildEnv } from "./child-env.js";
@@ -176,10 +178,6 @@ const secretRunCommand = defineJsonCommand({
         if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(varName)) {
             throw new UsageError(`"${varName}" is not a valid environment variable name.`, "INVALID_FLAG_VALUE");
         }
-        const { isDangerousEnvKey } = await import("../lint/env-key-rules.js");
-        if (isDangerousEnvKey(varName)) {
-            throw new UsageError(`Refusing to inject a secret into "${varName}": it is a known process-hijacking variable (e.g. LD_PRELOAD, PATH).`, "INVALID_FLAG_VALUE");
-        }
         const command = getParsedInvocation().passthroughArgs();
         if (command.length === 0) {
             throw new UsageError("Missing command. Usage: akm secret run <ref> <VAR> -- <command>");
@@ -188,6 +186,19 @@ const secretRunCommand = defineJsonCommand({
         if (!fs.existsSync(absPath)) {
             throw new NotFoundError(`Secret not found: ${makeSecretRef(name, source)}`);
         }
+        const { isDangerousEnvKey } = await import("../lint/env-key-rules.js");
+        if (isDangerousEnvKey(varName)) {
+            const detail = `"${varName}" is a known process-hijacking variable (e.g. LD_PRELOAD, PATH).`;
+            const decision = decideDangerousEnvInjection({
+                dangerousKeys: [varName],
+                thirdParty: Boolean(source.registryId),
+            });
+            if (decision === "block") {
+                throw new UsageError(`Refusing to inject a secret from a third-party stash into ${detail}\n` +
+                    "       Review the secret, then copy it into a first-party secret if you trust it.", "INVALID_FLAG_VALUE");
+            }
+            warn(`Injecting a secret into ${detail} Injecting anyway (first-party stash).`);
+        }
         const { readValue } = await import("./secret.js");
         const mergedEnv = buildChildEnv(process.env, {
             clean: args.clean === true,

package/dist/commands/health/checks.js

@@ -4,17 +4,56 @@
 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 { resolveEngine } from "../../integrations/agent/engine-resolution.js";
+import { lookupApiKeyFileValue, 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 { resolveImprovePlan } from "../improve/improve-strategies.js";
 import { ACTIVE_RUN_WARN_MS, TASK_FAIL_RATE_WARN } from "./types.js";
-function credentialAvailable(credential, env) {
-    return !credential?.required || credential.names.some((name) => Boolean(env[name]?.trim()));
+/** 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()));
+    // #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;
 }
-function runConfiguredEngineProbe(checkName, engineName, config, deps) {
+async function runConfiguredEngineProbe(checkName, engineName, config, deps, reachabilityCache) {
     if (!engineName) {
         return {
             name: checkName,
@@ -57,6 +96,7 @@ function runConfiguredEngineProbe(checkName, engineName, config, deps) {
         const fallbackEngine = configuredEngine.llmEngine ?? config.defaults?.llmEngine;
         let fallback;
         let fallbackCredential;
+        let fallbackApiKeyFile;
         let sdkRunner;
         const resolve = deps.resolveEngine ?? resolveEngine;
         try {
@@ -70,6 +110,7 @@ function runConfiguredEngineProbe(checkName, engineName, config, deps) {
         if (sdkRunner?.fallbackConnection && fallbackEngine) {
             fallback = { kind: "llm", engine: fallbackEngine, connection: sdkRunner.fallbackConnection };
             fallbackCredential = sdkRunner.fallbackCredential;
+            fallbackApiKeyFile = sdkRunner.fallbackApiKeyFile;
         }
         else if (fallbackEngine) {
             try {
@@ -77,6 +118,7 @@ function runConfiguredEngineProbe(checkName, engineName, config, deps) {
                 if (resolved.kind === "llm") {
                     fallback = resolved;
                     fallbackCredential = resolved.credential;
+                    fallbackApiKeyFile = resolved.apiKeyFile;
                 }
             }
             catch {
@@ -85,59 +127,91 @@ function runConfiguredEngineProbe(checkName, engineName, config, deps) {
         }
         const configuredModel = configuredEngine.model;
         const effectiveModel = sdkRunner?.profile.model ?? configuredModel ?? fallback?.connection.model;
-        const fallbackCredentialAvailable = credentialAvailable(fallbackCredential, env);
+        const fallbackCredentialAvailable = credentialAvailable(fallbackCredential, env, fallbackApiKeyFile);
         const missing = [
             !packageAvailable ? "@opencode-ai/sdk package" : undefined,
             !binaryAvailable ? `${binary} binary` : undefined,
             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);
+            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;
@@ -188,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",
@@ -235,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;
@@ -267,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")
@@ -287,7 +370,7 @@ export function runActiveImproveStrategyProbe(deps = {}) {
         const unavailableProcesses = Object.entries(plan.processes).flatMap(([name, process]) => {
             if (!process.enabled || !process.runner)
                 return [];
-            return credentialAvailable(process.runner.credential, env) ? [] : [name];
+            return credentialAvailable(process.runner.credential, env, process.runner.apiKeyFile) ? [] : [name];
         });
         if (plan.triageJudgment) {
             const judgmentCredential = plan.triageJudgment.kind === "llm"
@@ -295,20 +378,41 @@ export function runActiveImproveStrategyProbe(deps = {}) {
                 : plan.triageJudgment.kind === "sdk"
                     ? plan.triageJudgment.fallbackCredential
                     : undefined;
-            if (!credentialAvailable(judgmentCredential, env))
+            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");
+            }
         }
+        // #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,
             },
         };
     }
@@ -421,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 {
@@ -648,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/improve-metrics.js

@@ -76,6 +76,9 @@ function createUnknownImproveMetrics() {
         coverageGapCount: 0,
         evalCasesWritten: 0,
         deadUrlCount: 0,
+        deadUrlsChecked: 0,
+        deadUrlsTotal: 0,
+        deadUrlsSkipped: 0,
         memorySummary: { eligible: 0, derived: 0 },
         memoryCleanup: {
             pruneCandidates: 0,
@@ -333,6 +336,12 @@ function applyMiscCounters(metrics, result) {
     metrics.evalCasesWritten += toFiniteNumber(result.evalCasesWritten);
     if (Array.isArray(result.deadUrls))
         metrics.deadUrlCount += result.deadUrls.length;
+    const deadUrlCoverage = result.deadUrlCoverage;
+    if (deadUrlCoverage && typeof deadUrlCoverage === "object") {
+        metrics.deadUrlsChecked += toFiniteNumber(deadUrlCoverage.checked);
+        metrics.deadUrlsTotal += toFiniteNumber(deadUrlCoverage.total);
+        metrics.deadUrlsSkipped += toFiniteNumber(deadUrlCoverage.skipped);
+    }
 }
 function applyMemorySummary(metrics, result) {
     const memorySummary = result.memorySummary;
@@ -568,6 +577,9 @@ function mergeImproveMetrics(dst, src) {
     dst.coverageGapCount += src.coverageGapCount;
     dst.evalCasesWritten += src.evalCasesWritten;
     dst.deadUrlCount += src.deadUrlCount;
+    dst.deadUrlsChecked += src.deadUrlsChecked;
+    dst.deadUrlsTotal += src.deadUrlsTotal;
+    dst.deadUrlsSkipped += src.deadUrlsSkipped;
     // NOTE: memorySummary (derived/eligible) is a WHOLE-STASH snapshot recorded on
     // every run, NOT a per-run increment — summing it across the window inflates
     // it ~N× (the 1.2M-eligible bug). It is set from the most recent run in