akm-cli 0.9.14 → 0.9.15-beta.1

package/dist/commands/health/engine-usage.js

@@ -0,0 +1,45 @@
+// 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/.
+/**
+ * `engine-last-used` support for `akm health` (#950).
+ *
+ * An engine bound to an enabled improve process that has not actually been
+ * invoked in weeks looks identical to a healthy one on every existing check —
+ * `default-llm-engine`/`configured-engines` only probe availability/reachability,
+ * never USE. This module answers "when did this engine last run, and for
+ * whom" by folding `llm_usage` events over a fixed lookback window,
+ * independent of the report's `--since` (mirrors `session-extraction`'s
+ * independent `SESSION_EXTRACTION_LEDGER_WINDOW_DAYS` window in `checks.ts`).
+ */
+import { daysToMs } from "../../core/common.js";
+import { readEvents } from "../../core/events.js";
+import { LLM_USAGE_EVENT } from "../../llm/usage-persist.js";
+import { decodeLlmUsageRecord } from "../../llm/usage-telemetry.js";
+/** Rolling window `engine-last-used` reads over, independent of `--since`. */
+export const ENGINE_LAST_USED_LOOKBACK_DAYS = 30;
+/** ISO cutoff for the `ENGINE_LAST_USED_LOOKBACK_DAYS` window, ending at `now()`. */
+export function engineLastUsedSince(now) {
+    return new Date(now() - daysToMs(ENGINE_LAST_USED_LOOKBACK_DAYS)).toISOString();
+}
+/**
+ * Fold `llm_usage` events over the lookback window into the most recent call
+ * per engine. Best-effort like every other health probe: an event with no
+ * `engine` field (pre-#576 rows, or a call outside any resolved engine) is
+ * skipped rather than bucketed under a synthetic key.
+ */
+export function readLastEngineUsage(stateDbPath, now) {
+    const since = engineLastUsedSince(now);
+    const events = readEvents({ since, type: LLM_USAGE_EVENT }, { dbPath: stateDbPath }).events;
+    const lastUsed = new Map();
+    for (const event of events) {
+        const record = decodeLlmUsageRecord(event.metadata);
+        if (!record?.engine)
+            continue;
+        const existing = lastUsed.get(record.engine);
+        if (!existing || event.ts > existing.lastUsedAt) {
+            lastUsed.set(record.engine, { lastUsedAt: event.ts, process: record.process });
+        }
+    }
+    return lastUsed;
+}

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

@@ -44,6 +44,24 @@ export function taskFailureDetail(row) {
 export function isAgentTaskHistoryRow(row) {
     return row.target_kind === "command";
 }
+/**
+ * #943: reason-value breakdown for a set of agent (command-kind) task
+ * failure rows — how much of the observed failures are `timeout` vs
+ * `non_zero_exit` vs `spawn_failed` etc., so `akm health`'s `task-fail-rate`
+ * advisory can say "timeout-dominant" from data rather than log grep. Keeps
+ * the existing `AgentFailureReason` vocabulary verbatim (spawn.ts) — a
+ * reason-per-row read failure (already warned by {@link taskFailureDetail})
+ * still counts under `"unknown"` rather than being dropped, so the total
+ * always equals `agentFailures.length`.
+ */
+export function countAgentFailureReasons(agentFailures) {
+    const counts = {};
+    for (const row of agentFailures) {
+        const reason = String(taskFailureDetail(row)?.reason ?? "unknown");
+        counts[reason] = (counts[reason] ?? 0) + 1;
+    }
+    return counts;
+}
 function createUnknownImproveMetrics() {
     return {
         invoked: 0,

package/dist/commands/health/llm-usage.js

@@ -8,7 +8,7 @@
 import { readEvents } from "../../core/events.js";
 import { LLM_USAGE_EVENT } from "../../llm/usage-persist.js";
 import { decodeLlmUsageRecord } from "../../llm/usage-telemetry.js";
-/** Stage key used for `llm_usage` events recorded outside any stage scope. */
+/** Stage/process/engine/model key used for `llm_usage` events recorded with no value for that dimension. */
 const UNATTRIBUTED_STAGE = "unattributed";
 function emptyLlmUsageStageAggregate() {
     return {
@@ -18,6 +18,7 @@ function emptyLlmUsageStageAggregate() {
         completionTokens: 0,
         totalTokens: 0,
         reasoningTokens: 0,
+        failures: 0,
     };
 }
 /** A zeroed aggregate — also the value health reports when it could not read state.db at all (#791). */
@@ -52,6 +53,8 @@ export function summarizeLlmUsage(events) {
             target.completionTokens += record.completionTokens ?? 0;
             target.totalTokens += record.totalTokens ?? 0;
             target.reasoningTokens += record.reasoningTokens ?? 0;
+            if (record.outcome === "error")
+                target.failures += 1;
         }
     }
     return aggregate;
@@ -64,3 +67,40 @@ export function readLlmUsageAggregate(stateDbPath, since, until) {
     });
     return summarizeLlmUsage(events);
 }
+/**
+ * Aggregate `llm_usage` events (#576) into a process x engine x model
+ * cross-tab (#944) — one row per distinct `(process, engine, model)` triple
+ * seen, each carrying the same call/failure/token/duration totals as
+ * {@link LlmUsageStageAggregate}. A call missing any one of the three
+ * dimensions is keyed under {@link UNATTRIBUTED_STAGE} for that dimension
+ * (never dropped). Does not fold into, or change the shape of,
+ * {@link summarizeLlmUsage}'s existing `byStage`/`byProcess`/`byEngine`
+ * breakdowns — `akm health`'s existing consumers of those stay untouched.
+ * Row order is insertion order (first `(process, engine, model)` triple seen).
+ */
+export function summarizeLlmUsageCrossTab(events) {
+    const rows = new Map();
+    for (const event of events) {
+        const record = decodeLlmUsageRecord(event.metadata);
+        if (!record)
+            continue;
+        const process = record.process ?? UNATTRIBUTED_STAGE;
+        const engine = record.engine ?? UNATTRIBUTED_STAGE;
+        const model = record.model ?? UNATTRIBUTED_STAGE;
+        const key = `${process}:${engine}:${model}`;
+        let row = rows.get(key);
+        if (!row) {
+            row = { process, engine, model, ...emptyLlmUsageStageAggregate() };
+            rows.set(key, row);
+        }
+        row.calls += 1;
+        row.totalDurationMs += record.durationMs;
+        row.promptTokens += record.promptTokens ?? 0;
+        row.completionTokens += record.completionTokens ?? 0;
+        row.totalTokens += record.totalTokens ?? 0;
+        row.reasoningTokens += record.reasoningTokens ?? 0;
+        if (record.outcome === "error")
+            row.failures += 1;
+    }
+    return [...rows.values()];
+}

package/dist/commands/health/plugin-staleness.js

@@ -29,15 +29,19 @@
  *      and there was previously no way to know that from the CLI side.
  *
  * Read-only: this never fetches, writes, or mutates the plugin cache or
- * marketplace clone. Check 2 is the one deliberate exception to "`akm
- * health` makes no network call" (see `./health-advisories.md`): a plugin's
+ * marketplace clone. Check 2 is one of two deliberate exceptions to "`akm
+ * health` makes no network call" (see `./health-advisories.md`; the other is
+ * the `cli-version` advisory in `./version-drift.ts`, #950): a plugin's
  * local marketplace clone is not proof of what is newest upstream — the
  * incident above involved a clone that hadn't seen the fix's tag at all — so
  * the only way to ever detect drift is to ask the remote what tags exist.
  * That query is a `git ls-remote --tags` (lists refs; fetches nothing,
  * writes nothing) with a short timeout, and any failure (offline, no
  * remote, timeout) degrades to "installed version reported, no staleness
- * claim" rather than a false positive or a hang.
+ * claim" rather than a false positive or a hang. Unlike `cli-version`, this
+ * check is NOT gated behind `--probe`/`--no-probe` — it predates that flag
+ * and stays unconditional; see `./version-drift.ts` for why the newer check
+ * chose the opposite default.
  *
  * Every collector here is best-effort and silent on missing/unreadable
  * input: no Claude plugin installed, no marketplace clone, an unreadable

package/dist/commands/health/version-drift.js

@@ -0,0 +1,93 @@
+// 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/.
+/**
+ * `cli-version` advisory for `akm health` (#950).
+ *
+ * A fleet running a mix of akm-cli versions can look healthy on every other
+ * check while quietly running stale code (the motivating case: a host on
+ * 0.9.12 next to four peers already on 0.9.14, with nothing in `akm health`
+ * calling that out). This closes that gap by reusing {@link checkForUpdate}
+ * — the exact "installed vs GitHub latest release" comparison `akm upgrade`
+ * already trusts — rather than adding a second, parallel "ask npm" query
+ * that could disagree with it during the gap between a GitHub release and
+ * its npm publish step.
+ *
+ * Modelled 1:1 on `plugin-staleness.ts`'s shape: an injectable network seam,
+ * best-effort, silent-on-failure (never a false positive, never a hang — the
+ * network call is bounded to {@link CLI_VERSION_CHECK_TIMEOUT_MS} with no
+ * retries, not `checkForUpdate`'s own 30s/3-retry defaults, which are tuned
+ * for the deliberate, explicit `akm upgrade` command rather than a
+ * `--probe`-default-on health check). This is the SECOND deliberate network
+ * exception in `akm health` (see
+ * `plugin-staleness.ts` and `docs/architecture/internals/health-advisories.md`)
+ * — unlike plugin-staleness's unconditional `git ls-remote`, this one is
+ * gated behind the same `--probe`/`--no-probe` flag the engine-reachability
+ * checks already use, so an air-gapped host's existing `--no-probe` habit
+ * suppresses it too, and offline/rate-limited failures degrade to `unknown`
+ * (never a false `warn`).
+ */
+import { pkgVersion } from "../../version.js";
+import { checkForUpdate } from "../sources/self-update.js";
+/**
+ * Bound on the `checkForUpdate` network call. `checkForUpdate`'s own
+ * defaults (30s timeout, up to 3 retries with exponential backoff) are
+ * tuned for `akm upgrade` — a deliberate, explicit human command where a
+ * long wait is acceptable. `akm health --probe` defaults to `true` and is
+ * not such a gate, so this advisory overrides both to match the bounded,
+ * single-attempt discipline every other network-touching health check uses
+ * (`plugin-staleness.ts`'s 5s `git ls-remote`, `probeLlmEndpoint`'s 3s
+ * `AbortSignal.timeout`): a stale or air-gapped host must degrade to
+ * `unknown` in seconds, never block `akm health` for minutes.
+ */
+const CLI_VERSION_CHECK_TIMEOUT_MS = 5_000;
+/**
+ * Build the `cli-version` advisory. `probe` mirrors the engine-reachability
+ * checks' `--probe`/`--no-probe` gating: only network when `true`; otherwise
+ * `unknown` with "not probed", matching the un-probed engine-reachability
+ * message shape rather than silently omitting the check.
+ */
+export async function collectVersionDriftAdvisory(probe, deps = {}) {
+    const cliVersion = deps.cliVersion ?? pkgVersion;
+    if (!probe) {
+        return {
+            name: "cli-version",
+            kind: "deterministic",
+            status: "unknown",
+            confidence: "high",
+            message: `akm v${cliVersion} is installed. Version-drift was not probed.`,
+            evidence: { installedVersion: cliVersion },
+        };
+    }
+    try {
+        const result = await (deps.checkForUpdate ?? checkForUpdate)(cliVersion, {
+            timeout: CLI_VERSION_CHECK_TIMEOUT_MS,
+            retries: 0,
+        });
+        return {
+            name: "cli-version",
+            kind: "deterministic",
+            status: result.updateAvailable ? "warn" : "pass",
+            confidence: "high",
+            message: result.updateAvailable
+                ? `akm v${cliVersion} is installed; v${result.latestVersion} is available — run 'akm upgrade'.`
+                : `akm v${cliVersion} is installed and up to date.`,
+            evidence: { installedVersion: cliVersion, latestVersion: result.latestVersion },
+        };
+    }
+    catch (error) {
+        // Offline, rate-limited, or a malformed release response — never a false
+        // "stale" or "up to date" claim, only "could not be checked".
+        return {
+            name: "cli-version",
+            kind: "deterministic",
+            status: "unknown",
+            confidence: "high",
+            message: `akm v${cliVersion} is installed; the update check could not reach the release source.`,
+            evidence: {
+                installedVersion: cliVersion,
+                error: error instanceof Error ? error.constructor.name : "UnknownError",
+            },
+        };
+    }
+}

package/dist/commands/health/windows.js

@@ -11,7 +11,7 @@ import { readEvents } from "../../core/events.js";
 import { buildTaskRunId, getLoggedRunIds } from "../../core/logs-db.js";
 import { DURATION_UNITS, parseDuration } from "../../core/time.js";
 import { queryTaskHistory } from "../../storage/repositories/task-history-repository.js";
-import { buildImproveSkipSummary, computeWallTimeStats, isAgentTaskHistoryRow, roundRate, summarizeImproveCompleted, summarizeImproveRuns, taskFailureDetail, } from "./improve-metrics.js";
+import { buildImproveSkipSummary, computeWallTimeStats, countAgentFailureReasons, isAgentTaskHistoryRow, roundRate, summarizeImproveCompleted, summarizeImproveRuns, taskFailureDetail, } from "./improve-metrics.js";
 import { readLlmUsageAggregate } from "./llm-usage.js";
 import { computeDegradationMetrics, computeDenominatorFixedCoverage } from "./metrics.js";
 import { buildPerRunSummaries } from "./task-runs.js";
@@ -156,6 +156,7 @@ export function buildWindowMetrics(db, stateDbPath, since, until, now = () => Da
     const logBackingRate = taskRowsWithLogs.length === 0 ? 1 : existingLogRows.length / taskRowsWithLogs.length;
     const taskFailRate = taskRows.length === 0 ? 0 : failedTaskRows.length / taskRows.length;
     const agentFailureRate = agentRows.length === 0 ? 0 : agentFailures.length / agentRows.length;
+    const agentFailureReasonCounts = countAgentFailureReasons(agentFailures);
     const improveInvoked = readEvents({ since, type: "improve_invoked" }, { dbPath: stateDbPath }).events.filter((event) => new Date(event.ts ?? since).getTime() < new Date(until).getTime()).length;
     const improveCompletedEvents = readEvents({ since, type: IMPROVE_COMPLETED_EVENT }, { dbPath: stateDbPath }).events.filter((event) => new Date(event.ts ?? since).getTime() < new Date(until).getTime());
     const improveSkippedEvents = readEvents({ since, type: "improve_skipped" }, { dbPath: stateDbPath }).events.filter((event) => new Date(event.ts ?? since).getTime() < new Date(until).getTime());
@@ -185,6 +186,7 @@ export function buildWindowMetrics(db, stateDbPath, since, until, now = () => Da
     const metrics = {
         taskFailRate: roundRate(taskFailRate),
         agentFailureRate: roundRate(agentFailureRate),
+        agentFailureReasonCounts,
         stuckActiveRuns,
         logBackingRate: roundRate(logBackingRate),
         probeRoundTripMs: null,

package/dist/commands/health.js

@@ -14,14 +14,16 @@ import { listExistingTableNames, listPendingStateMigrations, openStateDatabase }
 import { DURATION_UNITS, parseDuration, parseSinceToIso } from "../core/time.js";
 import { probeLlmEndpoint } from "../llm/client.js";
 import { getExtractOutcomeCountsSince } from "../storage/repositories/extract-sessions-repository.js";
+import { countImproveRunsSince } from "../storage/repositories/improve-runs-repository.js";
 import { closeDatabase, openReadonlyExistingDatabase } from "../storage/repositories/index-connection.js";
 import { getAllEntries } from "../storage/repositories/index-entries-repository.js";
 import { queryTaskHistory } from "../storage/repositories/task-history-repository.js";
 import { pkgVersion } from "../version.js";
 import { collectImproveAdvisories } from "./health/advisories.js";
-import { HEALTH_CHECKS, runHealthEngineProbes, runPendingStateMigrationsCheck, SESSION_EXTRACTION_LEDGER_WINDOW_DAYS, } from "./health/checks.js";
+import { HEALTH_CHECKS, probeActiveImproveStrategy, runHealthEngineProbes, runPendingStateMigrationsCheck, SESSION_EXTRACTION_LEDGER_WINDOW_DAYS, } from "./health/checks.js";
 import { collectDataDirUsageAdvisory } from "./health/data-dir-usage.js";
-import { buildImproveSkipSummary, computeWallTimeStats, isAgentTaskHistoryRow, roundRate, summarizeImproveCompleted, summarizeImproveRuns, taskFailureDetail, } from "./health/improve-metrics.js";
+import { engineLastUsedSince, readLastEngineUsage } from "./health/engine-usage.js";
+import { buildImproveSkipSummary, computeWallTimeStats, countAgentFailureReasons, isAgentTaskHistoryRow, roundRate, summarizeImproveCompleted, summarizeImproveRuns, taskFailureDetail, } from "./health/improve-metrics.js";
 import { emptyLlmUsageAggregate, readLlmUsageAggregate } from "./health/llm-usage.js";
 import { computeDegradationMetrics, computeDenominatorFixedCoverage, computeEnrichmentMintingRollup, probeStateDbRoundTrip, } from "./health/metrics.js";
 import { collectPluginStalenessAdvisories } from "./health/plugin-staleness.js";
@@ -30,6 +32,7 @@ import { collectSurfacesAdvisories } from "./health/surfaces.js";
 import { buildPerRunSummaries } from "./health/task-runs.js";
 import { buildTypeDirectoryAdvisory } from "./health/type-directory-check.js";
 import { ACTIVE_RUN_WARN_MS, IMPROVE_COMPLETED_EVENT, MIN_ROWS_FOR_WORST_TASK_FAIL_RATE, } from "./health/types.js";
+import { collectVersionDriftAdvisory } from "./health/version-drift.js";
 import { buildWindowMetrics, computeDeltas, partitionLogBackedRows, resolveWindowCompare } from "./health/windows.js";
 const DEFAULT_SINCE_MS = 24 * 60 * 60 * 1000;
 export function parseHealthSince(since) {
@@ -150,23 +153,28 @@ function gatherTaskHistoryPhase(db, logsDb, since, stateDbPath, now) {
         taskFailRate,
         worstTaskFailRate: computeWorstTaskFailRate(taskRows),
         agentFailureRate,
+        agentFailureReasonCounts: countAgentFailureReasons(agentFailures),
     };
 }
 /**
- * Config fields the surfaces advisory needs. Best-effort: an unloadable
- * config leaves the field undefined and the caller falls back to a generic
- * message.
+ * Config fields the surfaces advisory and (#949) the `thinking-control`
+ * check need. Best-effort: an unloadable config leaves both fields at their
+ * empty fallback and the callers degrade to their generic/unknown states.
  */
 function gatherEgressConfigPhase() {
     let egressConfigView;
+    let thinkingOffEngines = [];
     try {
         const config = loadConfig();
         egressConfigView = config;
+        thinkingOffEngines = Object.entries(config.engines ?? {})
+            .filter(([, engine]) => engine.kind === "llm" && engine.enableThinking === false)
+            .map(([name]) => name);
     }
     catch {
-        // fall through with undefined
+        // fall through with undefined/empty
     }
-    return { egressConfigView };
+    return { egressConfigView, thinkingOffEngines };
 }
 /** Extract-ledger outcome counts for the `session-extraction` check's window, independent of `--since`. */
 function gatherSessionExtractionLedgerPhase(db, now) {
@@ -451,6 +459,7 @@ function degradedStateDbReport(hardCheck, options) {
         metrics: {
             taskFailRate: 0,
             agentFailureRate: 0,
+            agentFailureReasonCounts: {},
             stuckActiveRuns: 0,
             logBackingRate: 0,
             // `null`, not 0: the round-trip probe did not run, which is not the same
@@ -529,13 +538,30 @@ export async function akmHealth(options = {}) {
         // Network probes overlap the local database phases below; awaited where consumed.
         const engineProbesPromise = runHealthEngineProbes({ probeReachable: options.probe ? probeLlmEndpoint : undefined });
         engineProbesPromise.catch(() => undefined);
+        // #950: same best-effort, --probe-gated discipline as engineProbesPromise
+        // above — started here, alongside it, and awaited later.
+        const versionDriftPromise = collectVersionDriftAdvisory(Boolean(options.probe), { cliVersion: pkgVersion });
+        versionDriftPromise.catch(() => undefined);
         const taskHistory = gatherTaskHistoryPhase(db, logsDb, since, stateDbPath, now);
         const { tableNames, missingTables, probe } = taskHistory;
-        const { egressConfigView } = gatherEgressConfigPhase();
+        const { egressConfigView, thinkingOffEngines } = gatherEgressConfigPhase();
         const { improveSummary } = gatherImproveSummaryPhase(db, stateDbPath, since, now);
         advisories.push(...gatherAncillaryAdvisories(db, stateDbPath, since, improveSummary, options, egressConfigView));
         const sessionExtractionLedger = gatherSessionExtractionLedgerPhase(db, now);
+        // #950: computed once (no IO beyond config/env, same as gatherEgressConfigPhase)
+        // so `active-improve-strategy` and `engine-last-used` project the same
+        // process→engine map instead of each resolving the strategy independently.
+        const { check: activeImproveStrategy, processEngines: activeImproveStrategyEngines } = probeActiveImproveStrategy();
+        // #950: `engine-last-used` reads a fixed lookback window independent of
+        // `--since` (mirrors sessionExtractionLedger's independent window above).
+        const engineLastUsedSinceIso = engineLastUsedSince(now);
+        const engineLastUsed = readLastEngineUsage(stateDbPath, now);
+        const improveRunsInLookbackWindow = countImproveRunsSince(db, engineLastUsedSinceIso);
         const engineProbes = await engineProbesPromise;
+        const versionDrift = await versionDriftPromise;
+        // Read once, shared by the `thinking-control` check (#949) and the
+        // `metrics.llmUsage` report field below — same window, same aggregate.
+        const llmUsage = readLlmUsageAggregate(stateDbPath, since);
         // Run the ordered health-check registry. Each check projects the shared
         // context computed above into one HealthCheckResult; `channel` routes it to
         // hardChecks or advisories. Declaration order in HEALTH_CHECKS is the
@@ -554,10 +580,18 @@ export async function akmHealth(options = {}) {
             stuckActiveRuns: taskHistory.stuckActiveRuns,
             stuckActiveTasks: taskHistory.stuckActiveTasks,
             worstTaskFailRate: taskHistory.worstTaskFailRate,
+            agentFailureReasonCounts: taskHistory.agentFailureReasonCounts,
             sessionExtraction: improveSummary.sessionExtraction,
             sessionExtractionLedger,
             autoAccept: improveSummary.autoAccept,
             engineProbes,
+            thinkingOffEngines,
+            llmUsage,
+            versionDrift,
+            activeImproveStrategy,
+            activeImproveStrategyEngines,
+            engineLastUsed,
+            improveRunsInLookbackWindow,
         };
         for (const check of HEALTH_CHECKS) {
             const result = check.run(checkContext);
@@ -569,10 +603,11 @@ export async function akmHealth(options = {}) {
         const metrics = {
             taskFailRate: roundRate(taskHistory.taskFailRate),
             agentFailureRate: roundRate(taskHistory.agentFailureRate),
+            agentFailureReasonCounts: taskHistory.agentFailureReasonCounts,
             stuckActiveRuns: taskHistory.stuckActiveRuns,
             logBackingRate: roundRate(taskHistory.logBackingRate),
             probeRoundTripMs: probe.durationMs,
-            llmUsage: readLlmUsageAggregate(stateDbPath, since),
+            llmUsage,
         };
         const hardFailure = hardChecks.some((check) => check.status === "fail");
         const deterministicWarnings = [...hardChecks, ...advisories].some((check) => check.status === "warn" && check.kind === "deterministic");

package/dist/commands/improve/consolidate/chunking.js

@@ -10,9 +10,11 @@ import { cacheHash } from "../content-hash.js";
 /**
  * Conservative chars-per-token estimate used when computing prompt budgets.
  * English text averages roughly 4 chars/token for most LLM tokenizers. We use
- * 3 to stay conservative (shorter tokens = more tokens per char).
+ * 3 to stay conservative (shorter tokens = more tokens per char). Exported so
+ * other context-length-driven budgets (e.g. reflect's direct-LLM content cap,
+ * #952) share this single estimate instead of redeclaring it.
  */
-const CHARS_PER_TOKEN = 3;
+export const CHARS_PER_TOKEN = 3;
 /**
  * Overhead budget reserved for the system prompt, chunk header lines, and per-
  * memory metadata lines (name, description, tags, separator). Measured at

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

@@ -8,7 +8,7 @@ import { getStringArg, parsePositiveIntFlag } from "../../cli/parse-args.js";
 import { GLOBAL_OUTPUT_ARGS, output, runWithJsonErrors } from "../../cli/shared.js";
 import { isFullRefInput, parseRefInput } from "../../core/asset/resolve-ref.js";
 import { loadConfig } from "../../core/config/config.js";
-import { UsageError } from "../../core/errors.js";
+import { ConfigError, UsageError } from "../../core/errors.js";
 import { resolveMutationTarget } from "../../core/mutation-target.js";
 import { getCacheDir } from "../../core/paths.js";
 import { redactSensitiveText } from "../../core/redaction.js";
@@ -16,9 +16,11 @@ import { clearLogFile, setLogFile, warn } from "../../core/warn.js";
 import { resolveWriteTarget } from "../../core/write-source.js";
 import { collectEngineCredentialValues } from "../../integrations/agent/engine-resolution.js";
 import { akmImprove } from "./improve.js";
+import { runImproveReportQuery } from "./improve-report.js";
 import { buildImproveRunId, recordImproveRunResult, recordTerminatedImproveRun, } from "./improve-result-file.js";
 import { runImproveSession } from "./improve-session.js";
 import { resolveImprovePlan } from "./improve-strategies.js";
+import { formatUsageReportTable } from "./improve-usage-report.js";
 let akmImproveForRun = akmImprove;
 /** Swap the CLI's improve work implementation in deterministic subprocess tests. */
 export function _setAkmImproveForTests(fake) {
@@ -74,6 +76,57 @@ function rejectRetiredImproveTargetFlag() {
         return;
     throw new UsageError("`akm improve --target` was renamed to `--bundle` in 0.9. Use `--bundle <name>` instead.", "INVALID_FLAG_VALUE");
 }
+/**
+ * `--require-engines` (#957): abort before any lock, log, or index side
+ * effect when the resolved plan already knows a process the active strategy
+ * would enable cannot run. Without this flag improve degrades gracefully —
+ * it skips the affected processes and reports them in `skippedProcesses` —
+ * which is right for an interactive run but wrong for a scheduled one that
+ * would rather fail loudly than burn its budget re-indexing and then skip
+ * everything. Names the unresolved credential reference per process (not
+ * just the process name) so an operator whose own shell passes config
+ * validation can see exactly what the scheduler's environment is missing.
+ */
+function assertRequiredEnginesAvailable(plan) {
+    if (plan.engineUnavailable.length === 0)
+        return;
+    const lines = plan.engineUnavailable.map((item) => `  - ${item.process} (${item.configKey}): ${item.reason}`);
+    throw new ConfigError(`--require-engines: ${plan.engineUnavailable.length} improve process${plan.engineUnavailable.length === 1 ? "" : "es"} cannot run because ${plan.engineUnavailable.length === 1 ? "its" : "their"} engine is unavailable:\n${lines.join("\n")}`, "LLM_NOT_CONFIGURED");
+}
+/**
+ * `akm improve report` (#944): a scope value that dispatches to the per-run
+ * LLM usage/routing report instead of a real improve run — "report" is not,
+ * and will never be, a real asset type (`DEFAULT_ALLOWED_TYPES` in
+ * improve-strategies.ts), so this already matched zero assets before this
+ * flag existed, matching the precedent `rejectRetiredCanaryScope` set for
+ * intercepting a special scope word ahead of any lock/log/index side effect.
+ */
+function runImproveReportCli(args) {
+    const runIdArg = getStringArg(args, "run");
+    const sinceArg = getStringArg(args, "since");
+    const result = runImproveReportQuery({ runId: runIdArg, since: sinceArg });
+    output("improve-report", { ok: true, ...result });
+}
+/**
+ * `--run`/`--since` only mean anything with the "report" scope, which
+ * intercepts before this point in the `run` handler below. citty is
+ * non-strict, so passing either with a real scope (or no scope at all) used
+ * to be silently ignored — the flag's value was read nowhere else, and the
+ * run proceeded as an ordinary improve run with no error, discarding the
+ * operator's intent. Reject explicitly instead, matching the precedent
+ * `rejectRetiredCanaryScope`/`rejectRetiredImproveTargetFlag` set for other
+ * flag misuse on this command.
+ */
+function rejectReportOnlyFlags(args) {
+    const flag = getStringArg(args, "run") !== undefined
+        ? "--run"
+        : getStringArg(args, "since") !== undefined
+            ? "--since"
+            : undefined;
+    if (flag === undefined)
+        return;
+    throw new UsageError(`\`${flag}\` only applies to \`akm improve report\`. Use \`akm improve report ${flag} <value>\` instead.`, "INVALID_FLAG_VALUE");
+}
 export const improveCommand = defineCommand({
     meta: {
         name: "improve",
@@ -91,6 +144,11 @@ export const improveCommand = defineCommand({
         },
         task: { type: "string", description: "Add extra guidance for this improvement pass" },
         "dry-run": { type: "boolean", description: "Show planned actions without writing", default: false },
+        plan: {
+            type: "boolean",
+            description: "Alias for --dry-run (#947). Sets the exact same internal flag; use it when previewing resolved process -> engine -> model routing (plan.processes) rather than checking what would write.",
+            default: false,
+        },
         bundle: { type: "string", description: "Override the write target for accepted proposals" },
         limit: { type: "string", description: "Maximum number of assets to process (highest utility first)" },
         "timeout-ms": {
@@ -112,6 +170,19 @@ export const improveCommand = defineCommand({
             description: "If another improve run already holds the lock, skip gracefully (exit 0) instead of failing with 'already running' (exit 78). Use for high-frequency scheduled runs so they don't pile up failures while a longer run is in progress.",
             default: false,
         },
+        "require-engines": {
+            type: "boolean",
+            description: "Abort before any indexing, lock, or log side effect (exit 78) if the active strategy would enable a process whose engine or credential cannot be resolved in this process's environment. Without this flag, improve degrades gracefully instead: it skips the affected processes and reports them in the result's skippedProcesses. Recommended alongside --skip-if-locked for scheduled runs.",
+            default: false,
+        },
+        run: {
+            type: "string",
+            description: 'Only with the "report" scope (`akm improve report --run <id>`): show the LLM usage/routing report for one specific improve_runs row instead of the most recent run. Mutually exclusive with --since.',
+        },
+        since: {
+            type: "string",
+            description: 'Only with the "report" scope (`akm improve report --since <window>`): aggregate the LLM usage/routing report over every real run started since <window> (a duration like "24h"/"7d", or an ISO timestamp) instead of showing one run. Mutually exclusive with --run.',
+        },
         strategy: {
             type: "string",
             description: "Named improve strategy from improve.strategies or built-in strategies (catchup, consolidate, default, graph-refresh, proactive-maintenance, quick, reflect-distill, thorough). Controls which sub-processes run and which asset types are processed.",
@@ -127,6 +198,13 @@ export const improveCommand = defineCommand({
     },
     async run({ args }) {
         await runWithJsonErrors(async () => {
+            // #944 — dispatch before any lock/log/index side effect, same
+            // interception point as rejectRetiredCanaryScope below.
+            if (getStringArg(args, "scope") === "report") {
+                runImproveReportCli(args);
+                return;
+            }
+            rejectReportOnlyFlags(args);
             rejectRetiredImproveTargetFlag();
             // D7 — `--format` used to be rejected here outright. It is a global flag on
             // a command that does emit an envelope through `output()` (always on
@@ -137,7 +215,9 @@ export const improveCommand = defineCommand({
             const jsonToStdout = args["json-to-stdout"];
             const targetArg = getStringArg(args, "bundle");
             const taskArg = getStringArg(args, "task");
-            const dryRun = args["dry-run"];
+            // #947 — `--plan` is a zero-logic discoverability alias for `--dry-run`;
+            // it must never fork the computation, only set the same flag.
+            const dryRun = args["dry-run"] || args.plan;
             const limitRaw = parsePositiveIntFlag(args.limit ?? undefined);
             const timeoutMs = parsePositiveIntFlag(args["timeout-ms"], "--timeout-ms");
             const requireFeedbackSignal = args["require-feedback-signal"];
@@ -154,7 +234,13 @@ export const improveCommand = defineCommand({
                     : resolveWriteTarget(effectiveConfig, targetArg);
             // Resolve every enabled model-backed process before logging, signal
             // lifecycle setup, or any filesystem/database side effect.
-            const resolvedPlan = resolveImprovePlan(strategyArg, effectiveConfig);
+            // #800/#957 round 3 — `--dry-run`/`--plan` never dispatches, so the
+            // "no improve process can run" guard must not throw when every process
+            // is disabled purely by an unreachable credential; a live run keeps
+            // throwing (allowAllDisabled unset).
+            const resolvedPlan = resolveImprovePlan(strategyArg, effectiveConfig, { allowAllDisabled: Boolean(dryRun) });
+            if (args["require-engines"])
+                assertRequiredEnginesAvailable(resolvedPlan);
             const selectedStrategyName = resolvedPlan.strategy.name;
             const sensitiveValues = collectEngineCredentialValues(effectiveConfig);
             // Only set the keys the user actually passed (citty leaves the flag
@@ -271,8 +357,9 @@ export const improveCommand = defineCommand({
             // `improve_runs` table of state.db (migration 003) and emit NOTHING
             // on stdout. The verbose JSON would otherwise scroll earlier progress
             // logs out of the terminal buffer. The existing `[improve] ...`
-            // progress log lines on stderr remain the canonical console UX —
-            // do NOT add any new console output here.
+            // progress log lines on stderr remain the canonical console UX — the
+            // usage-report table below (#944) follows that same convention
+            // (stderr, `[improve]`-prefixed), it is not new stdout noise.
             //
             // Pre-0.8.0 wrote `<stash>/.akm/runs/<run-id>/improve-result.json`;
             // those files are no longer authored. Query recent runs with:
@@ -295,6 +382,13 @@ export const improveCommand = defineCommand({
             else {
                 process.stderr.write(`warning: no writable bundle directory resolved; improve result not persisted to state.db (use --json-to-stdout to capture)\n`);
             }
+            // #944 — same table `akm improve report` renders, appended to every
+            // real (non-dry-run) run so an operator sees the routing/cost split
+            // without a separate command. Omitted when the run made no LLM calls
+            // and skipped no enabled process (nothing to report).
+            if (improveResult.usageReport) {
+                process.stderr.write(`${formatUsageReportTable(improveResult.usageReport)}\n`);
+            }
             if (jsonToStdout)
                 output("improve", improveResult);
             // F4: was `process.exit(0)` — the run has already been fully recorded