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

package/dist/cli.js

@@ -2,9 +2,10 @@
 // This Source Code Form is subject to the terms of the Mozilla Public
 // 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/.
-// Runtime guard: akm-cli 0.9 runs on Bun (primary) and Node.js >= 20 (#465,
-// #560). The runtime boundary (src/runtime.ts, src/storage/database.ts) makes
-// the Node path additive. Under Node the CLI must be launched via the
+// Runtime guard: the akm-cli npm package bootstraps with Node.js >= 20.12
+// (#465, #560), then its launcher prefers a working Bun >= 1.0 when available.
+// The runtime boundary (src/runtime.ts, src/storage/database.ts) supports both.
+// Under Node the CLI must be launched via the
 // `dist/cli-node.mjs` wrapper, which registers the text-import loader hook
 // before this module graph loads; running `node dist/cli.js` directly still
 // works for code paths that touch no embedded text asset, but the wrapper is
@@ -18,12 +19,11 @@
             .map((part) => Number.parseInt(part, 10) || 0);
         const nodeOk = major > 20 || (major === 20 && (minor > 12 || (minor === 12 && patch >= 0)));
         if (!nodeOk) {
-            console.error("\n  ERROR: akm-cli requires the Bun runtime (https://bun.sh) or Node.js >= 20.12.\n" +
+            console.error("\n  ERROR: the akm-cli npm package requires Node.js >= 20.12.\n" +
                 `  Detected Node.js ${process.versions.node ?? "unknown"}.\n` +
-                "  Install options:\n" +
-                "    1. Bun:    curl -fsSL https://bun.sh/install | bash  &&  bun install -g akm-cli\n" +
-                "    2. Node:   upgrade to Node.js 20.12 or newer (https://nodejs.org)\n" +
-                "    3. Binary: curl -fsSL https://github.com/itlackey/akm/releases/latest/download/install.sh | bash\n");
+                "  Bun >= 1.0 is optional for execution; it does not replace the Node.js bootstrap.\n" +
+                "  Upgrade Node.js (https://nodejs.org), or install the runtime-free standalone binary:\n" +
+                "    curl -fsSL https://github.com/itlackey/akm/releases/latest/download/install.sh | bash\n");
             process.exit(1);
         }
     }
@@ -60,7 +60,7 @@ process.on("uncaughtException", (err) => {
 import fs from "node:fs";
 import path from "node:path";
 import { defineCommand, runMain } from "citty";
-import { findCittyTopLevelCommand } from "./cli/parse-args.js";
+import { findCittyTopLevelCommand, findCittyTopLevelCommandIndex } from "./cli/parse-args.js";
 import { EXIT_CODES, emitJsonError, output, parseAllFlagValues, runWithJsonErrors } from "./cli/shared.js";
 import { agentCommand, lintCommand, proposeCommand } from "./commands/agent/contribute-cli.js";
 import { backupCommand } from "./commands/backup-cli.js";
@@ -75,6 +75,7 @@ import { renderRunsDetailMd, renderWindowCompareMd } from "./commands/health/md-
 import { parseWindowSpec } from "./commands/health/windows.js";
 import { extractCommand } from "./commands/improve/extract-cli.js";
 import { improveCommand } from "./commands/improve/improve-cli.js";
+import { migrateCommand } from "./commands/migrate-cli.js";
 import { mvCommand } from "./commands/mv-cli.js";
 import { hintsCommand, lessonsCommand, logCommand } from "./commands/observability-cli.js";
 import { proposalCommand } from "./commands/proposal/proposal-cli.js";
@@ -92,6 +93,7 @@ import { workflowCommand } from "./commands/workflow-cli.js";
 import { bestEffort } from "./core/best-effort.js";
 import { DEFAULT_CONFIG, loadConfig } from "./core/config/config.js";
 import { UsageError } from "./core/errors.js";
+import { assertNoPendingMigrationOperation } from "./core/migration-operation.js";
 import { getCacheDir, getConfigPath, getDbPath } from "./core/paths.js";
 import { plainize } from "./core/tty.js";
 import { info, isQuiet, setQuiet, setVerbose, warn } from "./core/warn.js";
@@ -517,6 +519,7 @@ export const main = defineCommand({
         clone: cloneCommand,
         mv: mvCommand,
         registry: registryCommand,
+        migrate: migrateCommand,
         backup: backupCommand,
         config: configCommand,
         feedback: feedbackCommand,
@@ -539,13 +542,25 @@ export const main = defineCommand({
     },
 });
 const MAIN_TOP_LEVEL_ARGS = main.args;
+function isTaskRunWithId(argv) {
+    const args = argv.slice(2);
+    const commandIndex = findCittyTopLevelCommandIndex(args, MAIN_TOP_LEVEL_ARGS);
+    const command = commandIndex >= 0 ? args[commandIndex] : undefined;
+    if (command !== "tasks" && command !== "task")
+        return false;
+    const taskArgs = args.slice(commandIndex + 1);
+    return taskArgs[0] === "run" && typeof taskArgs[1] === "string" && !taskArgs[1].startsWith("-");
+}
 /** Recovery/setup surfaces must remain reachable when config.json is invalid. */
 export function shouldBypassConfigStartup(argv) {
     const args = argv.slice(2);
     if (args.includes("--help") || args.includes("-h") || args.includes("--version") || args.includes("-v"))
         return true;
-    const command = findCittyTopLevelCommand([...args], MAIN_TOP_LEVEL_ARGS);
-    if (command === "setup" || command === "backup")
+    const commandIndex = findCittyTopLevelCommandIndex(args, MAIN_TOP_LEVEL_ARGS);
+    const command = commandIndex >= 0 ? args[commandIndex] : undefined;
+    if (command === "setup" || command === "backup" || command === "migrate")
+        return true;
+    if (isTaskRunWithId(argv))
         return true;
     if (command !== "config")
         return false;
@@ -582,6 +597,8 @@ if (import.meta.main || process.env.AKM_NODE_ENTRY === "1") {
     // rather than letting the raw exception escape with a stack trace.
     try {
         applyEarlyStderrFlags(process.argv);
+        if (isTaskRunWithId(process.argv))
+            assertNoPendingMigrationOperation();
         const bypassConfig = shouldBypassConfigStartup(process.argv);
         initOutputMode(process.argv, bypassConfig ? (DEFAULT_CONFIG.output ?? {}) : (loadConfig().output ?? {}));
     }

package/dist/commands/backup-cli.js

@@ -10,10 +10,10 @@ function requireVersion(value) {
     }
 }
 export const backupCommand = defineGroupCommand({
-    meta: { name: "backup", description: "Create or restore a versioned migration recovery bundle" },
+    meta: { name: "backup", description: "Create or restore a verified migration recovery run" },
     subCommands: {
         create: defineJsonCommand({
-            meta: { name: "create", description: "Create the immutable pre-0.9 migration recovery bundle" },
+            meta: { name: "create", description: "Create a unique installation-scoped migration recovery run" },
             args: {
                 for: { type: "string", required: true, description: "Migration target version (0.9.0)" },
             },
@@ -30,19 +30,21 @@ export const backupCommand = defineGroupCommand({
             },
         }),
         restore: defineJsonCommand({
-            meta: { name: "restore", description: "Restore the pre-0.9 config and durable databases" },
+            meta: { name: "restore", description: "Restore a recovery run after preserving a rescue snapshot" },
             args: {
                 for: { type: "string", required: true, description: "Migration target version (0.9.0)" },
+                run: { type: "string", description: "Backup run ID (defaults to the newest applicable run)" },
                 confirm: { type: "boolean", default: false, description: "Confirm destructive restoration" },
             },
             run({ args }) {
                 requireVersion(args.for);
-                const result = restoreMigrationBackup(args.confirm);
+                const result = restoreMigrationBackup(args.confirm, args.run);
                 output("backup", {
                     action: "restore",
                     for: MIGRATION_BACKUP_VERSION,
                     path: result.path,
                     restored: true,
+                    rescuePath: result.rescuePath,
                     manifest: result.manifest,
                 });
             },

package/dist/commands/config-cli.js

@@ -242,11 +242,18 @@ export const configCommand = defineGroupCommand({
         migrate: defineJsonCommand({
             meta: {
                 name: "migrate",
-                description: "Diagnose whether the user config is already in the current schema. Never writes or translates config.",
+                description: "Compatibility alias for the canonical top-level migrate status/apply coordinator.",
             },
-            async run() {
+            args: {
+                config: {
+                    type: "string",
+                    description: "Path to an operator-prepared current-version config to validate and install",
+                },
+                dryRun: { type: "boolean", default: false, description: "Validate and report without changing files" },
+            },
+            async run({ args }) {
                 const { runConfigMigrate } = await import("../cli/config-migrate.js");
-                await runConfigMigrate();
+                await runConfigMigrate({ preparedConfigPath: args.config, dryRun: args.dryRun });
             },
         }),
         enable: defineJsonCommand({

package/dist/commands/feedback-cli.js

@@ -3,7 +3,7 @@
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
 import fs from "node:fs";
 import { defineJsonCommand, output, parseAllFlagValues } from "../cli/shared.js";
-import { parseAssetRef } from "../core/asset/asset-ref.js";
+import { parseAssetRef, refToString } from "../core/asset/asset-ref.js";
 import { assembleAsset } from "../core/asset/asset-serialize.js";
 import { parseFrontmatter, parseFrontmatterBlock } from "../core/asset/frontmatter.js";
 import { writeFileAtomic } from "../core/common.js";
@@ -12,7 +12,8 @@ import { UsageError } from "../core/errors.js";
 import { appendEvent } from "../core/events.js";
 import { getDbPath } from "../core/paths.js";
 import { warn } from "../core/warn.js";
-import { applyFeedbackToUtilityScore, closeDatabase, findEntryIdByRef, getEntryFilePathById, openExistingDatabase, } from "../indexer/db/db.js";
+import { applyFeedbackToUtilityScore, closeDatabase, findEntryIdByRef, getEntryById, getEntryFilePathById, openExistingDatabase, } from "../indexer/db/db.js";
+import { resolveSourceEntries } from "../indexer/search/search-source.js";
 import { countFeedbackSignals, insertUsageEvent } from "../indexer/usage/usage-events.js";
 // ── Tag validation ────────────────────────────────────────────────────────────
 const TAG_KEY_RE = /^[a-z_][a-z0-9_]*$/;
@@ -156,7 +157,7 @@ export const feedbackCommand = defineJsonCommand({
         if (!ref) {
             throw new UsageError("Asset ref is required. Usage: akm feedback <ref> --positive|--negative", "MISSING_REQUIRED_ARGUMENT", "Pass a ref like `skill:deploy` and either --positive or --negative.");
         }
-        parseAssetRef(ref);
+        const parsedRef = parseAssetRef(ref);
         if (args.positive && args.negative) {
             throw new UsageError("Specify either --positive or --negative, not both.");
         }
@@ -216,9 +217,19 @@ export const feedbackCommand = defineJsonCommand({
         // background reindex it spawned — now that ensureIndex is removed, holding
         // the lock only causes feedback to block for the full improve run duration.
         let utilityResult;
+        let durableRef = ref;
         const db = openExistingDatabase();
         try {
-            const entryId = findEntryIdByRef(db, ref);
+            const config = loadConfig();
+            const sources = resolveSourceEntries(undefined, config);
+            const requestedSource = parsedRef.origin
+                ? sources.find((source) => source.registryId === parsedRef.origin ||
+                    ((parsedRef.origin === "local" || parsedRef.origin === "stash") && source === sources[0]))
+                : undefined;
+            if (parsedRef.origin && !requestedSource) {
+                throw new UsageError(`Source "${parsedRef.origin}" is not configured.`, "INVALID_FLAG_VALUE");
+            }
+            const entryId = findEntryIdByRef(db, ref, requestedSource?.path);
             if (entryId === undefined) {
                 throw new UsageError(`Ref "${ref}" is not in the index. ` +
                     "Run 'akm search' to verify the asset exists, then 'akm index' if it was recently added.");
@@ -228,9 +239,15 @@ export const feedbackCommand = defineJsonCommand({
             // For negative signals, the score is adjusted the next time `akm index`
             // runs — the signal is durable in the DB but does NOT suppress ranking
             // in search results until after reindexing.
+            const indexedEntry = getEntryById(db, entryId);
+            const source = sources.find((candidate) => candidate.path === indexedEntry?.stashDir);
+            durableRef = refToString({
+                ...parsedRef,
+                origin: parsedRef.origin ?? source?.registryId ?? "stash",
+            });
             insertUsageEvent(db, {
                 event_type: "feedback",
-                entry_ref: ref,
+                entry_ref: durableRef,
                 entry_id: entryId,
                 signal,
                 metadata: metadataStr,
@@ -253,7 +270,7 @@ export const feedbackCommand = defineJsonCommand({
         }
         appendEvent({
             eventType: "feedback",
-            ref,
+            ref: durableRef,
             metadata: metadataObj,
         });
         // F-5 / #386: When a high-utility asset crosses below the review threshold,
@@ -268,7 +285,7 @@ export const feedbackCommand = defineJsonCommand({
             try {
                 appendEvent({
                     eventType: "improve_review_needed",
-                    ref,
+                    ref: durableRef,
                     metadata: {
                         previousUtility: utilityResult.previousUtility,
                         nextUtility: utilityResult.nextUtility,

package/dist/commands/health/checks.js

@@ -6,20 +6,25 @@ import { createRequire } from "node:module";
 import { loadConfig } from "../../core/config/config.js";
 import { resolveEngine } from "../../integrations/agent/engine-resolution.js";
 import { resolveModel } from "../../integrations/agent/model-aliases.js";
+import { resolveImprovePlan } from "../improve/improve-strategies.js";
 import { TASK_FAIL_RATE_WARN, } from "./types.js";
 const ACTIVE_RUN_WARN_MS = 15 * 60 * 1000;
-export function runDefaultEngineProbe(deps = {}) {
-    const config = deps.loadConfig?.() ?? loadConfig();
-    const engineName = config.defaults?.engine ?? config.defaults?.llmEngine;
+function credentialAvailable(credential, env) {
+    return !credential?.required || credential.names.some((name) => Boolean(env[name]?.trim()));
+}
+function runConfiguredEngineProbe(checkName, engineName, config, deps) {
     if (!engineName) {
         return {
-            name: "default-engine",
+            name: checkName,
             kind: "deterministic",
             status: "unknown",
             confidence: "high",
-            message: "No default engine is configured.",
+            message: checkName === "default-llm-engine"
+                ? "No default LLM engine is configured."
+                : "No default engine is configured.",
         };
     }
+    const env = deps.env ?? process.env;
     const configuredEngine = config.engines?.[engineName];
     if (configuredEngine?.kind === "agent" && configuredEngine.platform === "opencode-sdk") {
         let packageAvailable = false;
@@ -36,6 +41,7 @@ export function runDefaultEngineProbe(deps = {}) {
         const binaryAvailable = (version.status ?? 1) === 0;
         const fallbackEngine = configuredEngine.llmEngine ?? config.defaults?.llmEngine;
         let fallback;
+        let fallbackCredential;
         let sdkRunner;
         const resolve = deps.resolveEngine ?? resolveEngine;
         try {
@@ -48,12 +54,15 @@ export function runDefaultEngineProbe(deps = {}) {
         }
         if (sdkRunner?.fallbackConnection) {
             fallback = { kind: "llm", connection: sdkRunner.fallbackConnection };
+            fallbackCredential = sdkRunner.fallbackCredential;
         }
         else if (fallbackEngine) {
             try {
                 const resolved = resolve(fallbackEngine, config);
-                if (resolved.kind === "llm")
+                if (resolved.kind === "llm") {
                     fallback = resolved;
+                    fallbackCredential = resolved.credential;
+                }
             }
             catch {
                 fallback = undefined;
@@ -63,14 +72,15 @@ export function runDefaultEngineProbe(deps = {}) {
             ? resolveModel(configuredEngine.model, "opencode-sdk", configuredEngine.modelAliases, config.modelAliases)
             : undefined;
         const effectiveModel = sdkRunner?.profile.model ?? configuredModel ?? fallback?.connection.model;
+        const fallbackCredentialAvailable = credentialAvailable(fallbackCredential, env);
         const missing = [
             !packageAvailable ? "@opencode-ai/sdk package" : undefined,
             !binaryAvailable ? `${binary} binary` : undefined,
-            !fallback ? "fallback LLM connection" : undefined,
-            !effectiveModel ? "effective SDK model" : undefined,
+            fallbackEngine && !fallback ? "configured fallback LLM connection" : undefined,
+            !fallbackCredentialAvailable ? "required fallback credential" : undefined,
         ].filter((value) => value !== undefined);
         return {
-            name: "default-engine",
+            name: checkName,
             kind: "deterministic",
             status: missing.length === 0 ? "pass" : "warn",
             confidence: "high",
@@ -91,24 +101,29 @@ export function runDefaultEngineProbe(deps = {}) {
                 fallbackEngine: fallbackEngine ?? null,
                 fallbackEndpoint: fallback?.connection.endpoint ?? null,
                 fallbackModel: fallback?.connection.model ?? null,
+                requiredCredentialAvailable: fallbackCredentialAvailable,
             },
         };
     }
     try {
         const runner = (deps.resolveEngine ?? resolveEngine)(engineName, config);
         if (runner.kind === "llm") {
+            const requiredCredentialAvailable = credentialAvailable(runner.credential, env);
             return {
-                name: "default-engine",
+                name: checkName,
                 kind: "deterministic",
-                status: "pass",
+                status: requiredCredentialAvailable ? "pass" : "warn",
                 confidence: "high",
-                message: `LLM engine "${engineName}" is configured.`,
+                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,
                 },
             };
         }
@@ -118,7 +133,7 @@ export function runDefaultEngineProbe(deps = {}) {
         const version = (deps.spawnSync ?? spawnSync)(profile.bin, ["--version"], { encoding: "utf8", timeout: 5_000 });
         if ((version.status ?? 1) !== 0) {
             return {
-                name: "default-engine",
+                name: checkName,
                 kind: "deterministic",
                 status: "warn",
                 confidence: "medium",
@@ -132,7 +147,7 @@ export function runDefaultEngineProbe(deps = {}) {
             };
         }
         return {
-            name: "default-engine",
+            name: checkName,
             kind: "deterministic",
             status: "pass",
             confidence: "high",
@@ -147,7 +162,7 @@ export function runDefaultEngineProbe(deps = {}) {
     }
     catch (error) {
         return {
-            name: "default-engine",
+            name: checkName,
             kind: "deterministic",
             status: "warn",
             confidence: "high",
@@ -155,6 +170,60 @@ export function runDefaultEngineProbe(deps = {}) {
         };
     }
 }
+export function runDefaultEngineProbe(deps = {}) {
+    const config = deps.loadConfig?.() ?? loadConfig();
+    return runConfiguredEngineProbe("default-engine", config.defaults?.engine, config, deps);
+}
+export function runDefaultLlmEngineProbe(deps = {}) {
+    const config = deps.loadConfig?.() ?? loadConfig();
+    return runConfiguredEngineProbe("default-llm-engine", config.defaults?.llmEngine, config, deps);
+}
+export function runActiveImproveStrategyProbe(deps = {}) {
+    const config = deps.loadConfig?.() ?? loadConfig();
+    const strategyName = config.defaults?.improveStrategy ?? "default";
+    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) ? [] : [name];
+        });
+        if (plan.triageJudgment) {
+            const judgmentCredential = plan.triageJudgment.kind === "llm"
+                ? plan.triageJudgment.credential
+                : plan.triageJudgment.kind === "sdk"
+                    ? plan.triageJudgment.fallbackCredential
+                    : undefined;
+            if (!credentialAvailable(judgmentCredential, env))
+                unavailableProcesses.push("triage.judgment");
+        }
+        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(", ")}.`,
+            evidence: {
+                strategy: plan.strategy.name,
+                unavailableProcesses,
+            },
+        };
+    }
+    catch (error) {
+        const explicitlyConfigured = config.defaults?.improveStrategy !== undefined || Object.keys(config.improve?.strategies ?? {}).length > 0;
+        return {
+            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: [] },
+        };
+    }
+}
 /**
  * The ordered health-check registry. ORDER IS LOAD-BEARING: `akmHealth`
  * iterates this array and appends to hardChecks/advisories in sequence, so the
@@ -236,6 +305,16 @@ export const HEALTH_CHECKS = [
         channel: "hard",
         run: () => runDefaultEngineProbe(),
     },
+    {
+        name: "default-llm-engine",
+        channel: "hard",
+        run: () => runDefaultLlmEngineProbe(),
+    },
+    {
+        name: "active-improve-strategy",
+        channel: "hard",
+        run: () => runActiveImproveStrategyProbe(),
+    },
     {
         // C2 (13-bus-factor): the cron task-failure rate was computed and rendered
         // in the HTML report but never surfaced as an advisory, so a sustained

package/dist/commands/health/html-report.js

@@ -92,6 +92,8 @@ function reshapeRun(r) {
     const geMs = ge.durationMs || 0;
     return {
         id: r.id,
+        resultStatus: r.resultStatus ?? "valid",
+        resultComplete: r.resultComplete ?? (r.resultStatus === undefined || r.resultStatus === "valid"),
         taskId: r.taskId ?? "manual",
         strategy: r.strategy,
         legacyProfile: r.legacyProfile,
@@ -262,7 +264,10 @@ function buildEchartsTag(opts) {
  */
 export function buildHealthHtmlReplacements(result, opts) {
     const deltas = opts.deltas ?? {};
-    const runs = (result.runs ?? []).map(reshapeRun).sort((a, b) => a.startedAt.localeCompare(b.startedAt));
+    const compareRuns = (a, b) => a.startedAt.localeCompare(b.startedAt) || a.completedAt.localeCompare(b.completedAt) || a.id.localeCompare(b.id);
+    const allRuns = (result.runs ?? []).map(reshapeRun).sort(compareRuns);
+    const invalidRuns = allRuns.filter((run) => run.resultStatus === "invalid");
+    const runs = allRuns.filter((run) => run.resultStatus !== "invalid");
     const improve = result.improve;
     const proposals = opts.proposals;
     const sem = readSemSearch(result.advisories);
@@ -320,7 +325,10 @@ export function buildHealthHtmlReplacements(result, opts) {
     const reportTitle = reportDate ? `AKM Health Report — ${reportDate}` : "AKM Health Report";
     const lastRun = runs[runs.length - 1];
     const generatedAt = lastRun ? lastRun.completedAt || lastRun.startedAt || sinceIso : sinceIso;
-    const latest = [...runs].reverse().find((r) => r.ok) ?? lastRun;
+    const latest = [...runs]
+        .filter((run) => run.resultComplete)
+        .sort(compareRuns)
+        .at(-1);
     // Freshness: surface the newest run's timestamp + the generated-at anchor in
     // the exec card. Staleness is computed deterministically (no Date.now()) from
     // the gap between the window start (`since`) and the newest run we have: if no
@@ -389,6 +397,9 @@ export function buildHealthHtmlReplacements(result, opts) {
         li("Report window", esc(opts.window)),
         li("Compare window", esc(opts.compare)),
         li("Runs", `${num(totalRuns)} (${failedRuns} failed)`),
+        li("Included result rows", num(improve.resultRows?.included ?? totalRuns)),
+        li("Normalized result rows", num(improve.resultRows?.normalized ?? 0)),
+        li("Invalid result rows skipped", num(improve.resultRows?.skipped.invalid ?? invalidRuns.length)),
         li("Stash derived", `<abbr title="Whole-stash recount of derived assets at report time — not a per-run sum.">${num(improve.memorySummary.derived)}</abbr>`),
         li("Stash eligible", `<abbr title="Whole-stash recount of eligible assets at report time — not a per-run sum.">${num(improve.memorySummary.eligible)}</abbr>`),
         li("Pending proposals", String(proposals.length)),
@@ -655,6 +666,16 @@ export function buildHealthHtmlReplacements(result, opts) {
         seen.add(item.key);
         items.push(item);
     };
+    if (invalidRuns.length > 0) {
+        pushItem({
+            key: "invalid-improve-result-rows",
+            prio: "P2",
+            cls: "warn",
+            title: `${invalidRuns.length} invalid improve result row${invalidRuns.length === 1 ? "" : "s"} skipped`,
+            descHtml: `Excluded from result-derived metrics: ${invalidRuns.map((run) => `<code>${esc(run.id)}</code>`).join(", ")}.`,
+            remedy: `akm health --since=${opts.window} --group-by run`,
+        });
+    }
     // Hard advisories from the health check engine (own remediation in message).
     for (const a of result.advisories) {
         if (a.status !== "warn" && a.status !== "fail")

package/dist/commands/health/improve-metrics.js

@@ -25,6 +25,7 @@ function createUnknownImproveMetrics() {
         completed: 0,
         skipped: 0,
         skipReasons: {},
+        resultRows: { total: 0, included: 0, normalized: 0, skipped: { invalid: 0 } },
         plannedRefs: 0,
         strategyFilteredRefs: 0,
         actions: {
@@ -605,6 +606,15 @@ function mergeImproveMetrics(dst, src) {
     // totalAssets is intentionally NOT merged here — set from the most recent run in summarizeImproveRuns.
     dst.coverage.acceptedProposals += src.coverage.acceptedProposals;
 }
+function compareImproveRunRecency(a, b) {
+    const started = a.started_at.localeCompare(b.started_at);
+    if (started !== 0)
+        return started;
+    const completed = (a.completed_at ?? "").localeCompare(b.completed_at ?? "");
+    if (completed !== 0)
+        return completed;
+    return a.id.localeCompare(b.id);
+}
 export function summarizeImproveRuns(db, since, until) {
     const accum = createUnknownImproveMetrics();
     const rows = queryImproveRuns(db, since, until);
@@ -618,16 +628,33 @@ export function summarizeImproveRuns(db, since, until) {
     };
     // memorySummary is a whole-stash snapshot per run, so the window value is the
     // MOST RECENT run's snapshot (current state) — not a sum across runs.
-    let latestStartMs = Number.NEGATIVE_INFINITY;
+    let latestCompleteRow;
     let latestMemorySummary;
     let latestStrategyFilteredRefs = 0;
+    if (!accum.resultRows)
+        throw new Error("invariant: improve result-row accounting was not initialized");
+    accum.resultRows.total = rows.length;
     for (const row of rows) {
-        const result = decodeImproveResult(row.result_json).envelope;
+        let decoded;
+        try {
+            decoded = decodeImproveResult(row.result_json);
+        }
+        catch {
+            accum.resultRows.skipped.invalid += 1;
+            continue;
+        }
+        accum.resultRows.included += 1;
+        if (decoded.normalizedLegacyPartial)
+            accum.resultRows.normalized += 1;
+        const result = decoded.envelope;
         const perRow = projectRunMetrics(result);
         mergeImproveMetrics(accum, perRow);
         const startMs = new Date(row.started_at).getTime();
-        if (Number.isFinite(startMs) && startMs >= latestStartMs) {
-            latestStartMs = startMs;
+        if (!decoded.normalizedLegacyPartial &&
+            result.terminated === undefined &&
+            Number.isFinite(startMs) &&
+            (latestCompleteRow === undefined || compareImproveRunRecency(row, latestCompleteRow) > 0)) {
+            latestCompleteRow = row;
             latestMemorySummary = perRow.memorySummary;
             latestStrategyFilteredRefs = perRow.strategyFilteredRefs;
         }
@@ -681,8 +708,18 @@ export function summarizePhaseDurations(samples) {
  * Used by `akm health --detail per-run`.
  */
 export function projectImproveRunSummary(row, wallTimeMs, taskId) {
-    const decoded = decodeImproveResult(row.result_json);
-    const result = decoded.envelope;
+    let result = {};
+    let resultStatus = "invalid";
+    try {
+        const decoded = decodeImproveResult(row.result_json);
+        result = decoded.envelope;
+        resultStatus = decoded.normalizedLegacyPartial ? "normalized" : "valid";
+    }
+    catch {
+        // Keep the persisted row visible in per-run output, but do not project its
+        // unknown payload or admit its duration to result-derived denominators.
+        wallTimeMs = 0;
+    }
     const perRow = projectRunMetrics(result);
     finalizeImproveMetrics(perRow);
     const orphansPurged = toFiniteNumber(result.orphansPurged);
@@ -695,6 +732,8 @@ export function projectImproveRunSummary(row, wallTimeMs, taskId) {
         completedAt: row.completed_at,
         wallTimeMs,
         ok: row.ok === 1,
+        resultStatus,
+        resultComplete: resultStatus === "valid" && result.terminated === undefined,
         strategy: row.strategy,
         legacyProfile: row.legacyProfile,
         scope: {

package/dist/commands/health/md-report.js

@@ -38,6 +38,7 @@ export function renderRunsDetailMd(runs) {
         "graph_f/e/r",
         "orphans",
         "lint_f/fl",
+        "result_status",
     ];
     const rows = runs.map((r) => {
         const totalActions = r.actions.reflect.ok +
@@ -66,6 +67,7 @@ export function renderRunsDetailMd(runs) {
             `${r.graphExtraction.extractedFiles}/${r.graphExtraction.entities}/${r.graphExtraction.relations}`,
             String(r.orphansPurged),
             `${r.lintFixed}/${r.lintFlagged}`,
+            r.resultStatus ?? "valid",
         ];
     });
     return renderTable(headers, rows);
@@ -89,7 +91,14 @@ export function renderWindowCompareMd(windows, deltas) {
         "improve.memoryInference.skippedNoFacts",
     ]);
     const rows = [];
-    for (const path of INTERESTING_DELTA_PATHS) {
+    const paths = [
+        "runs",
+        "improve.resultRows.included",
+        "improve.resultRows.normalized",
+        "improve.resultRows.skipped.invalid",
+        ...INTERESTING_DELTA_PATHS,
+    ];
+    for (const path of paths) {
         const values = windows.map((w) => String(readNumericPath(w, path)));
         const delta = deltas?.[path];
         let deltaStr = "—";

package/dist/commands/health/surfaces.js

@@ -18,6 +18,7 @@
  */
 import fs from "node:fs";
 import path from "node:path";
+import { MAX_CONFIG_FILE_BYTES, readTextFileWithLimit } from "../../core/common.js";
 import { CURRENT_CONFIG_VERSION } from "../../core/config/config-schema.js";
 import { compareConfigVersion } from "../../core/config/config-version.js";
 const GROUP_OTHER_BITS = 0o077;
@@ -98,7 +99,7 @@ export function collectSecretPermsAdvisory(input, platform = process.platform) {
 export function collectConfigSkewAdvisory(configPath) {
     let raw;
     try {
-        raw = JSON.parse(fs.readFileSync(configPath, "utf8"));
+        raw = JSON.parse(readTextFileWithLimit(configPath, MAX_CONFIG_FILE_BYTES, "Config file"));
     }
     catch {
         return undefined;