akm-cli 0.9.14 → 0.9.15-beta.1

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

@@ -0,0 +1,154 @@
+// 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/.
+/**
+ * #944 Layer 2 — `akm improve report`. Reads one (or several, `--since`)
+ * `improve_runs` rows and returns the same `usageReport` shape
+ * `finalizeImproveResult` persists on a live run (`improve-usage-report.ts`),
+ * so the command and the end-of-run stderr table stay byte-identical in
+ * structure. A row with no persisted `usageReport` degrades rather than
+ * errors, per AGENTS.md's "reader must tolerate data older releases wrote":
+ * its cross-tab is recomputed from the run's own `llm_usage` events and a
+ * `notes` entry explains why — either the row predates #944, or (per
+ * `recordTerminatedImproveRun` in improve-result-file.ts) the run was
+ * terminated before it ever reached `finalizeImproveResult`. The `noCalls`
+ * half is never fabricated for either case.
+ */
+import { NotFoundError, UsageError } from "../../core/errors.js";
+import { readEvents } from "../../core/events.js";
+import { decodeImproveResult } from "../../core/improve-result.js";
+import { withStateDb } from "../../core/state-db.js";
+import { LLM_USAGE_EVENT } from "../../llm/usage-persist.js";
+import { getImproveRunById, getLatestImproveRun, queryImproveRuns, } from "../../storage/repositories/improve-runs-repository.js";
+import { parseHealthSince } from "../health.js";
+import { summarizeLlmUsageCrossTab } from "../health/llm-usage.js";
+const PRE_USAGE_REPORT_NOTE = "eligibility reasons unavailable for runs recorded before 0.9.15";
+const TERMINATED_RUN_NOTE = "run terminated before completion; no usage report was recorded";
+/**
+ * Recompute the cross-tab from this run's own `llm_usage` events (a pre-#944
+ * row has no persisted one). `eventsCtx` threads the state.db connection
+ * `runImproveReportQuery` already holds via `withStateDb`, so a `--since`
+ * window with several pre-0.9.15 or undecodable rows reads through that one
+ * open connection instead of each row opening and closing its own.
+ */
+function crossTabFromEvents(startedAt, completedAt, eventsCtx) {
+    const until = completedAt ?? new Date().toISOString();
+    const events = readEvents({ since: startedAt, type: LLM_USAGE_EVENT }, eventsCtx).events.filter((event) => new Date(event.ts ?? startedAt).getTime() < new Date(until).getTime());
+    return summarizeLlmUsageCrossTab(events);
+}
+/** One row's usage report — persisted (common case) or recomputed (pre-#944 row / terminated run / undecodable row). */
+function usageReportForRow(row, eventsCtx) {
+    try {
+        const decoded = decodeImproveResult(row.result_json);
+        if (decoded.envelope.usageReport) {
+            return {
+                usageReport: {
+                    byProcessEngineModel: [...decoded.envelope.usageReport.byProcessEngineModel],
+                    noCalls: [...decoded.envelope.usageReport.noCalls],
+                },
+                strategy: decoded.strategy,
+            };
+        }
+        return {
+            usageReport: {
+                byProcessEngineModel: crossTabFromEvents(row.started_at, row.completed_at, eventsCtx),
+                noCalls: [],
+            },
+            strategy: decoded.strategy,
+            note: decoded.envelope.terminated ? TERMINATED_RUN_NOTE : PRE_USAGE_REPORT_NOTE,
+        };
+    }
+    catch {
+        // A row whose result_json this build cannot decode still has real
+        // llm_usage events on state.db — degrade to the recomputed cross-tab
+        // rather than excluding the run entirely.
+        return {
+            usageReport: {
+                byProcessEngineModel: crossTabFromEvents(row.started_at, row.completed_at, eventsCtx),
+                noCalls: [],
+            },
+            note: PRE_USAGE_REPORT_NOTE,
+        };
+    }
+}
+function mergeCrossTabRow(merged, row) {
+    const key = `${row.process}:${row.engine}:${row.model}`;
+    const acc = merged.get(key);
+    if (!acc) {
+        merged.set(key, { ...row });
+        return;
+    }
+    acc.calls += row.calls;
+    acc.failures += row.failures;
+    acc.promptTokens += row.promptTokens;
+    acc.completionTokens += row.completionTokens;
+    acc.totalTokens += row.totalTokens;
+    acc.reasoningTokens += row.reasoningTokens;
+    acc.totalDurationMs += row.totalDurationMs;
+}
+/**
+ * Resolve `akm improve report`'s target run(s) and build its `usageReport`.
+ * `runId` and `since` are mutually exclusive; neither given selects the most
+ * recent non-dry-run.
+ */
+export function runImproveReportQuery(options) {
+    if (options.runId !== undefined && options.since !== undefined) {
+        throw new UsageError("akm improve report: --run and --since are mutually exclusive.", "INVALID_FLAG_VALUE");
+    }
+    return withStateDb((db) => {
+        // Thread this already-open connection into every reader below, so a
+        // `--since` window with several pre-0.9.15 or undecodable rows reads
+        // through it instead of each row opening and closing its own.
+        const eventsCtx = { db };
+        if (options.since !== undefined) {
+            const sinceIso = parseHealthSince(options.since);
+            const rows = queryImproveRuns(db, sinceIso);
+            const merged = new Map();
+            const calledEverByProcess = new Set();
+            const lastReasonByProcess = new Map();
+            const notes = new Set();
+            for (const row of rows) {
+                const { usageReport, note } = usageReportForRow(row, eventsCtx);
+                for (const crossTabRow of usageReport.byProcessEngineModel) {
+                    mergeCrossTabRow(merged, crossTabRow);
+                    if (crossTabRow.calls > 0)
+                        calledEverByProcess.add(crossTabRow.process);
+                }
+                for (const noCallRow of usageReport.noCalls) {
+                    // `rows` is newest-first (ORDER BY started_at DESC): keep only the
+                    // first (most recent) reason seen per process, never overwrite it
+                    // with an older run's reason.
+                    if (!lastReasonByProcess.has(noCallRow.process)) {
+                        lastReasonByProcess.set(noCallRow.process, { engine: noCallRow.engine, reason: noCallRow.reason });
+                    }
+                }
+                if (note)
+                    notes.add(note);
+            }
+            const noCalls = [...lastReasonByProcess.entries()]
+                .filter(([process]) => !calledEverByProcess.has(process))
+                .map(([process, { engine, reason }]) => ({ process, ...(engine ? { engine } : {}), reason }));
+            return {
+                mode: "since",
+                since: sinceIso,
+                runIds: rows.map((r) => r.id),
+                usageReport: { byProcessEngineModel: [...merged.values()], noCalls },
+                ...(notes.size > 0 ? { notes: [...notes] } : {}),
+            };
+        }
+        const row = options.runId !== undefined ? getImproveRunById(db, options.runId) : getLatestImproveRun(db);
+        if (!row) {
+            throw new NotFoundError(options.runId !== undefined
+                ? `akm improve report: no improve run found with id "${options.runId}".`
+                : "akm improve report: no improve runs recorded yet.", "IMPROVE_RUN_NOT_FOUND");
+        }
+        const { usageReport, strategy, note } = usageReportForRow(row, eventsCtx);
+        return {
+            mode: "run",
+            runId: row.id,
+            ...(strategy !== undefined ? { strategy } : {}),
+            usageReport,
+            ...(note ? { notes: [note] } : {}),
+        };
+    });
+}

package/dist/commands/improve/improve-result-file.js

@@ -27,7 +27,7 @@
 import crypto from "node:crypto";
 import { decodeImproveResult } from "../../core/improve-result.js";
 import { redactSensitiveValue } from "../../core/redaction.js";
-import { withStateDb } from "../../core/state-db.js";
+import { withImmediateTransaction, withStateDb } from "../../core/state-db.js";
 import { recordImproveRun } from "../../storage/repositories/improve-runs-repository.js";
 /**
  * Build a stable run-id for a single improve invocation.
@@ -63,18 +63,25 @@ export function recordImproveRunResult(stashDir, runId, result, startedAt, sensi
         // so started_at != completed_at even on older call sites.
         const resolvedStartedAt = startedAt ??
             runId.slice(0, 24).replace(/^(\d{4}-\d{2}-\d{2}T)(\d{2})-(\d{2})-(\d{2})-(\d{3})Z$/, "$1$2:$3:$4.$5Z");
-        recordImproveRun(db, {
-            id: runId,
-            startedAt: resolvedStartedAt,
-            completedAt,
-            stashDir,
-            dryRun: Boolean(result.dryRun),
-            strategy: redactSensitiveValue(decoded.strategy, sensitiveValues),
-            scopeMode: result.scope?.mode ?? "all",
-            scopeValue: persistedResult.scope?.value ?? null,
-            guidance: persistedResult.guidance ?? null,
-            ok: Boolean(result.ok),
-            result: persistedResult,
+        // #948: route through the shared BEGIN IMMEDIATE retry/reclassify helper
+        // instead of a bare write — this INSERT used to rely solely on the
+        // connection's 30s busy_timeout, with no retry and no friendly
+        // reclassification on exhaustion, so a raw "database is locked" from
+        // improve's own ledger write could reach the CLI as exit 70.
+        withImmediateTransaction(db, () => {
+            recordImproveRun(db, {
+                id: runId,
+                startedAt: resolvedStartedAt,
+                completedAt,
+                stashDir,
+                dryRun: Boolean(result.dryRun),
+                strategy: redactSensitiveValue(decoded.strategy, sensitiveValues),
+                scopeMode: result.scope?.mode ?? "all",
+                scopeValue: persistedResult.scope?.value ?? null,
+                guidance: persistedResult.guidance ?? null,
+                ok: Boolean(result.ok),
+                result: persistedResult,
+            });
         });
     });
 }
@@ -116,27 +123,32 @@ export function recordTerminatedImproveRun(stashDir, runId, startedAt, reason, c
         },
     }, ctx.sensitiveValues ?? []);
     withStateDb((db) => {
-        recordImproveRun(db, {
-            id: runId,
-            startedAt,
-            completedAt,
-            stashDir,
-            dryRun: Boolean(ctx.dryRun),
-            strategy: persistedStrategy,
-            scopeMode: ctx.scopeMode ?? "all",
-            scopeValue: persistedScopeValue ?? null,
-            guidance: null,
-            ok: false,
-            result: minimalResult,
-            metadata: {
-                terminated: {
-                    reason: persistedReason,
-                    at: completedAt,
-                    ...(ctx.errorMessage
-                        ? { errorMessage: redactSensitiveValue(ctx.errorMessage, ctx.sensitiveValues ?? []) }
-                        : {}),
+        // #948: same rationale as recordImproveRunResult above — this is the
+        // signal-handler/terminated-run write path, which must not itself raise
+        // a raw "database is locked" while trying to record why the run ended.
+        withImmediateTransaction(db, () => {
+            recordImproveRun(db, {
+                id: runId,
+                startedAt,
+                completedAt,
+                stashDir,
+                dryRun: Boolean(ctx.dryRun),
+                strategy: persistedStrategy,
+                scopeMode: ctx.scopeMode ?? "all",
+                scopeValue: persistedScopeValue ?? null,
+                guidance: null,
+                ok: false,
+                result: minimalResult,
+                metadata: {
+                    terminated: {
+                        reason: persistedReason,
+                        at: completedAt,
+                        ...(ctx.errorMessage
+                            ? { errorMessage: redactSensitiveValue(ctx.errorMessage, ctx.sensitiveValues ?? []) }
+                            : {}),
+                    },
                 },
-            },
+            });
         });
     });
 }

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

@@ -14,6 +14,7 @@ import { ImproveProfileConfigSchema } from "../../core/config/config-schema.js";
 import { deepMergeConfig } from "../../core/config/deep-merge.js";
 import { BUILTIN_IMPROVE_STRATEGY_NAMES, IMPROVE_PROCESS_ENGINE_CAPABILITIES, } from "../../core/config/engine-semantics.js";
 import { ConfigError } from "../../core/errors.js";
+import { describeLlmCredentialAvailability } from "../../integrations/agent/engine-resolution.js";
 import { applyAutonomyGate } from "./autonomy-gate.js";
 import { resolveImproveExecution, resolveImproveLlmExecution } from "./execution.js";
 export const DEFAULT_ALLOWED_TYPES = {
@@ -64,6 +65,59 @@ export function resolveImproveStrategy(name, config) {
     const resolved = deepMergeConfig(baseStrategy, (userStrategies[selectedName] ?? {}));
     return { name: selectedName, config: ImproveProfileConfigSchema.parse(resolved) };
 }
+/**
+ * Project a resolved improve plan into one routing row per
+ * {@link IMPROVE_PROCESS_ENGINE_CAPABILITIES} name, plus a `"triage.judgment"`
+ * pseudo-row when the strategy configures a judgment engine. Pure — no I/O,
+ * no re-resolution. Shared by `improve --dry-run`'s `plan.processes` (#947)
+ * and `akm health`'s post-run reporting (#944); health's own
+ * `active-improve-strategy` check keeps its existing `engines` shape.
+ */
+export function projectResolvedProcessRouting(plan) {
+    const unavailableByProcess = new Map(plan.engineUnavailable.map((item) => [item.process, item]));
+    const rows = [];
+    for (const processName of Object.keys(IMPROVE_PROCESS_ENGINE_CAPABILITIES)) {
+        const process = plan.processes[processName];
+        const unavailable = unavailableByProcess.get(processName);
+        rows.push({
+            process: processName,
+            enabled: process.enabled,
+            ...(process.runner
+                ? { engine: process.runner.engine, model: process.runner.connection.model, engineKind: process.runner.kind }
+                : // #800/#957 round 3 — a credential-unavailable process never carries a
+                    // runner, but its structurally resolved engine/model is still worth
+                    // showing in the routing table (dry-run preview, health probe).
+                    unavailable?.engine
+                        ? {
+                            engine: unavailable.engine,
+                            ...(unavailable.model ? { model: unavailable.model } : {}),
+                            engineKind: "llm",
+                        }
+                        : {}),
+            notices: process.notices ?? [],
+            ...(unavailable ? { unavailable: { configKey: unavailable.configKey, reason: unavailable.reason } } : {}),
+        });
+    }
+    if (plan.strategy.config.processes?.triage?.judgment?.enabled === true) {
+        const judgmentUnavailable = unavailableByProcess.get("triage.judgment");
+        rows.push({
+            process: "triage.judgment",
+            enabled: plan.triageJudgment !== null,
+            ...(plan.triageJudgment
+                ? {
+                    engine: plan.triageJudgment.engine,
+                    engineKind: plan.triageJudgment.kind,
+                    ...(plan.triageJudgment.kind === "llm" ? { model: plan.triageJudgment.connection.model } : {}),
+                }
+                : {}),
+            notices: plan.triageJudgmentNotices ?? [],
+            ...(judgmentUnavailable
+                ? { unavailable: { configKey: judgmentUnavailable.configKey, reason: judgmentUnavailable.reason } }
+                : {}),
+        });
+    }
+    return rows;
+}
 function cloneAndFreeze(value) {
     const clone = structuredClone(value);
     const freeze = (item) => {
@@ -86,9 +140,23 @@ export function resolveImprovePlan(name, config, options = {}) {
     const strategy = { name: selected.name, config: gatedStrategyConfig };
     return { ...buildImprovePlan(strategy, config, options), autonomyGated: gated };
 }
+/** Describe why a resolved-but-uncredentialed runner belongs in `engineUnavailable` (#957). */
+function credentialUnavailableReason(engineName, status) {
+    return `requires a credential that is not available in this process's environment (engine "${engineName}": ${status.reason})`;
+}
 function buildImprovePlan(strategy, config, options) {
+    const env = options.env ?? process.env;
     const processes = {};
     const engineUnavailable = [];
+    // #957 round 2 — distinguishes "credential unavailable" (a working engine
+    // whose secret isn't in this environment) from "no engine selected at all"
+    // among the pushes below, so `allowAllDisabled` can bypass the ConfigError
+    // only for the former. The latter is the guard's original, pre-#957
+    // condition and must keep hard-aborting for every caller, including a
+    // health probe with `allowAllDisabled` set — a totally unconfigured
+    // install is not the credential-in-the-wrong-environment case this option
+    // exists for.
+    let anyEngineNotConfigured = false;
     for (const processName of Object.keys(IMPROVE_PROCESS_ENGINE_CAPABILITIES)) {
         const sourceProcessConfig = strategy.config.processes?.[processName] ?? {};
         const enabled = sourceProcessConfig.enabled === true;
@@ -101,6 +169,15 @@ function buildImprovePlan(strategy, config, options) {
         // Validation itself is structural and always runs. Only its optional repair
         // step needs a model, so disabling repair must not create an LLM preflight.
         const skipsRepairEngine = processName === "validation" && options.repairValidationFailures === false;
+        // #957: a resolved-but-uncredentialed runner is folded into the same
+        // "no engine" branch below — set here so the shared push/continue block
+        // can tell the two apart in its reason text.
+        let credentialUnavailableMessage;
+        // #800/#957 round 3 — the structurally resolved engine/model/contextLength
+        // for the credential-unavailable case only, so a dry-run preview can read
+        // what resolution decided (e.g. the consolidation chunk-size estimate)
+        // without the runner ever carrying a credential-less connection forward.
+        let credentialUnavailableRouting;
         if (!skipsRepairEngine) {
             const resolved = resolveImproveLlmExecution({
                 config,
@@ -110,13 +187,32 @@ function buildImprovePlan(strategy, config, options) {
             });
             runner = resolved?.runner ?? null;
             notices = resolved?.notices ?? [];
+            if (runner) {
+                const credentialStatus = describeLlmCredentialAvailability(runner, env);
+                if (!credentialStatus.available) {
+                    credentialUnavailableMessage = credentialUnavailableReason(runner.engine, credentialStatus);
+                    credentialUnavailableRouting = {
+                        engine: runner.engine,
+                        ...(runner.connection.model !== undefined ? { model: runner.connection.model } : {}),
+                        ...(runner.connection.contextLength !== undefined
+                            ? { contextLength: runner.connection.contextLength }
+                            : {}),
+                    };
+                    runner = null;
+                    notices = [];
+                }
+            }
         }
         if (!runner && !skipsRepairEngine) {
             const configKey = `improve.strategies.${strategy.name}.processes.${processName}.engine`;
+            if (!credentialUnavailableMessage)
+                anyEngineNotConfigured = true;
             engineUnavailable.push({
                 process: processName,
                 configKey,
-                reason: `requires an LLM engine that is not configured. Set defaults.llmEngine or ${configKey}`,
+                reason: credentialUnavailableMessage ??
+                    `requires an LLM engine that is not configured. Set defaults.llmEngine or ${configKey}`,
+                ...credentialUnavailableRouting,
             });
             processes[processName] = Object.freeze({
                 enabled: false,
@@ -134,7 +230,9 @@ function buildImprovePlan(strategy, config, options) {
             ...(notices.length > 0 ? { notices: cloneAndFreeze(notices) } : {}),
         });
     }
-    if (engineUnavailable.length > 0 && !Object.values(processes).some((process) => process.enabled)) {
+    if (engineUnavailable.length > 0 &&
+        !Object.values(processes).some((process) => process.enabled) &&
+        (!options.allowAllDisabled || anyEngineNotConfigured)) {
         const names = engineUnavailable.map((item) => `"${item.process}"`).join(", ");
         throw new ConfigError(`No improve process can run: ${names} ${engineUnavailable.length === 1 ? "requires" : "require"} an LLM engine that is not configured. Set defaults.llmEngine, or the per-process engine key named for each.`, "LLM_NOT_CONFIGURED");
     }
@@ -149,7 +247,7 @@ function buildImprovePlan(strategy, config, options) {
             processName: "triage-judgment",
         })
         : null;
-    const triageJudgment = triageJudgmentResolution?.runner ?? null;
+    let triageJudgment = triageJudgmentResolution?.runner ?? null;
     const effectiveJudgmentLlm = triage?.judgment?.llm ?? triage?.llm ?? strategy.config.llm;
     if (triageJudgment && triageJudgment.kind !== "llm" && effectiveJudgmentLlm) {
         throw new ConfigError(`Triage judgment engine "${triageJudgment.engine ?? "unknown"}" is an agent engine and cannot receive llm overrides.`, "INVALID_CONFIG_FILE");
@@ -157,6 +255,38 @@ function buildImprovePlan(strategy, config, options) {
     if (processes.triage.enabled && judgmentEnabled && !triageJudgment) {
         throw new ConfigError(`Enabled improve triage judgment requires an engine. Set defaults.llmEngine or improve.strategies.${strategy.name}.processes.triage.judgment.engine.`, "LLM_NOT_CONFIGURED");
     }
+    // #957: same credential-unavailable treatment as the main per-process loop
+    // above — a triage judgment engine that resolves structurally but whose
+    // credential (or, for an SDK judgment, its LLM fallback credential) is
+    // unavailable in this process's environment is folded into
+    // `engineUnavailable` under the reserved `"triage.judgment"` process name
+    // instead of silently reaching dispatch with a doomed credential.
+    if (triageJudgment) {
+        const judgmentCredentialFields = triageJudgment.kind === "llm"
+            ? {
+                credential: triageJudgment.credential,
+                apiKeyFile: triageJudgment.apiKeyFile,
+                apiKeySecretRef: triageJudgment.apiKeySecretRef,
+            }
+            : triageJudgment.kind === "sdk"
+                ? {
+                    credential: triageJudgment.fallbackCredential,
+                    apiKeyFile: triageJudgment.fallbackApiKeyFile,
+                    apiKeySecretRef: triageJudgment.fallbackApiKeySecretRef,
+                }
+                : undefined;
+        if (judgmentCredentialFields) {
+            const credentialStatus = describeLlmCredentialAvailability(judgmentCredentialFields, env);
+            if (!credentialStatus.available) {
+                engineUnavailable.push({
+                    process: "triage.judgment",
+                    configKey: `improve.strategies.${strategy.name}.processes.triage.judgment.engine`,
+                    reason: credentialUnavailableReason(triageJudgment.engine, credentialStatus),
+                });
+                triageJudgment = null;
+            }
+        }
+    }
     const frozenProcesses = Object.freeze(processes);
     const frozenStrategy = Object.freeze({
         name: strategy.name,

package/dist/commands/improve/improve-usage-report.js

@@ -0,0 +1,182 @@
+// 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/.
+/**
+ * #944 — per-run LLM usage reporting: fold the process x engine x model
+ * cross-tab (`summarizeLlmUsageCrossTab`, `health/llm-usage.ts`) together with
+ * the resolved process routing table (`projectResolvedProcessRouting`, #947)
+ * into the `usageReport` field `finalizeImproveResult` persists, and render
+ * both halves as one fixed-width table shared by the end-of-run stderr
+ * summary (`improve-cli.ts`) and `akm improve report`'s text output
+ * (`src/output/text/improve-report.ts`).
+ */
+import { IMPROVE_PROCESS_ENGINE_CAPABILITIES } from "../../core/config/engine-semantics.js";
+import { projectResolvedProcessRouting, shouldSkipRef, } from "./improve-strategies.js";
+/**
+ * The processes this report covers — only the ones {@link IMPROVE_PROCESS_ENGINE_CAPABILITIES}
+ * marks `"llm"`. `triage` ("runner" kind — its LLM cost, if any, is
+ * attributed to the separate `"triage.judgment"` pseudo-row, itself excluded
+ * below) and `proactiveMaintenance` (no engine at all) never make an
+ * attributable LLM call, so listing them as "zero calls" would always be a
+ * false positive, not a real finding.
+ */
+const LLM_BACKED_PROCESSES = new Set(Object.keys(IMPROVE_PROCESS_ENGINE_CAPABILITIES).filter((name) => IMPROVE_PROCESS_ENGINE_CAPABILITIES[name] === "llm"));
+/** Ref-scoped processes `shouldSkipRef` understands — the only ones an eligible-ref count is meaningful for. */
+const REF_SCOPED_PROCESSES = new Set(["reflect", "distill", "consolidate"]);
+/** The autonomy lane (if any) gating each LLM-backed process, per `autonomy-gate.ts`'s `AUTONOMY_LANES`. */
+const AUTONOMY_LANE_BY_PROCESS = {
+    memoryInference: "memoryInference",
+};
+/** `{reason -> count}` for the dominant-reason lookup in {@link deriveNoCallReason}. */
+function dominantReason(counts) {
+    let best;
+    let bestCount = 0;
+    for (const [reason, count] of Object.entries(counts)) {
+        if (count > bestCount) {
+            best = reason;
+            bestCount = count;
+        }
+    }
+    return best;
+}
+/**
+ * The single decision point for why an LLM-backed process made zero LLM
+ * calls this run — every case `buildImproveUsageReport` needs to report,
+ * decided in one place instead of split between this function and its
+ * caller. Priority order: `"engine_unavailable"` (the row's engine or
+ * credential could not be resolved) beats everything else, including a
+ * process that also happens to be autonomy-gated; then, for a disabled row
+ * that IS resolvable, `"autonomy_gated"` when its lane was gated, else
+ * `undefined` (a `false`-in-config process never reached the routing table
+ * in the first place, so a disabled-and-not-gated row has no other
+ * explanation to report); for an enabled row, `"strategy_filtered_all_passes"`
+ * when every ref got filtered out, then the process's own dominant skip
+ * reason, else the `"no_signal"` fallback.
+ *
+ * Reuses the SAME reason strings already emitted elsewhere
+ * (`improve_skipped` events, reflect's `AkmReflectFailure.reason`, distill's
+ * `distillSkipped.byReason` keys) rather than inventing a translation layer —
+ * per the brief, never a fabricated category like `"limit_reached"`.
+ */
+export function deriveNoCallReason(args) {
+    const { row } = args;
+    if (row.unavailable)
+        return "engine_unavailable";
+    const lane = AUTONOMY_LANE_BY_PROCESS[row.process];
+    const laneGated = lane !== undefined && args.autonomyGated.some((gated) => gated.lane === lane);
+    if (!row.enabled)
+        return laneGated ? "autonomy_gated" : undefined;
+    if (args.eligibleRefs === 0 && args.strategyFilteredRefsCount > 0)
+        return "strategy_filtered_all_passes";
+    const dominant = args.skipReasonCounts ? dominantReason(args.skipReasonCounts) : undefined;
+    if (dominant)
+        return dominant;
+    return "no_signal";
+}
+/** Reflect's per-ref skip reason, read off `AkmReflectFailure.reason` for both cooldown and skipped actions. */
+function countReflectSkipReasons(actions) {
+    const counts = {};
+    for (const action of actions) {
+        if (action.mode !== "reflect-cooldown" && action.mode !== "reflect-skipped")
+            continue;
+        const result = action.result;
+        const reason = typeof result?.reason === "string" && result.reason.trim() ? result.reason : "unknown";
+        counts[reason] = (counts[reason] ?? 0) + 1;
+    }
+    return counts;
+}
+/**
+ * Assemble this run's `usageReport` (#944): the process x engine x model
+ * cross-tab plus which enabled processes made zero calls and why. Pure — no
+ * I/O; the caller (`finalizeImproveResult`) supplies the cross-tab (already
+ * computed from this run's `llm_usage` events) and every other input from
+ * data it already has in scope.
+ *
+ * Returns `undefined` when both halves would be empty (e.g. a run whose
+ * active strategy enables no LLM-backed process), matching the envelope's
+ * existing convention of omitting empty optional sections.
+ */
+export function buildImproveUsageReport(args) {
+    // Only the LLM-backed processes (see LLM_BACKED_PROCESSES) — this also
+    // drops the "triage.judgment" pseudo-row (#947): judgment dispatch does
+    // not route through `withLlmStage`, so its calls (if any) are never
+    // attributable to a "triage.judgment" process in the cross-tab, and
+    // reporting it here would always read as a false "zero calls".
+    const routing = projectResolvedProcessRouting(args.resolvedPlan).filter((row) => row.process !== "triage.judgment" && LLM_BACKED_PROCESSES.has(row.process));
+    const calledProcesses = new Set(args.byProcessEngineModel.filter((row) => row.calls > 0).map((row) => row.process));
+    const reflectSkipCounts = countReflectSkipReasons(args.persistedActions);
+    const noCalls = [];
+    for (const row of routing) {
+        if (calledProcesses.has(row.process))
+            continue;
+        const eligibleRefs = REF_SCOPED_PROCESSES.has(row.process)
+            ? args.loopRefs.filter((entry) => !shouldSkipRef(entry.ref, row.process, args.resolvedPlan.strategy.config).skip).length
+            : undefined;
+        const reason = deriveNoCallReason({
+            row,
+            autonomyGated: args.resolvedPlan.autonomyGated,
+            strategyFilteredRefsCount: args.strategyFilteredRefsCount,
+            eligibleRefs,
+            skipReasonCounts: row.process === "reflect"
+                ? reflectSkipCounts
+                : row.process === "distill"
+                    ? args.distillSkippedAggregate?.byReason
+                    : undefined,
+        });
+        if (reason === undefined)
+            continue;
+        noCalls.push({ process: row.process, ...(row.engine ? { engine: row.engine } : {}), reason });
+    }
+    if (args.byProcessEngineModel.length === 0 && noCalls.length === 0)
+        return undefined;
+    return { byProcessEngineModel: args.byProcessEngineModel, noCalls };
+}
+// ── Shared fixed-width text rendering ────────────────────────────────────────
+function renderFixedWidthTable(headers, rows) {
+    const widths = headers.map((header, index) => Math.max(header.length, ...rows.map((row) => row[index]?.length ?? 0)));
+    const renderRow = (cells) => cells
+        .map((cell, index) => cell.padEnd(widths[index] ?? 0))
+        .join("  ")
+        .trimEnd();
+    return [renderRow(headers), ...rows.map(renderRow)];
+}
+/**
+ * Render a `usageReport` as fixed-width plain text — the ONE formatter shared
+ * by the end-of-run `[improve] ...` stderr table (`improve-cli.ts`) and `akm
+ * improve report`'s `--format text` output
+ * (`src/output/text/improve-report.ts`), per the brief. `notes` surfaces
+ * degraded-precision caveats (e.g. a pre-0.9.15 run recomputed from raw
+ * events, per `improve-report.ts`).
+ */
+export function formatUsageReportTable(usageReport, notes) {
+    const lines = ["[improve] usage report (process x engine x model):"];
+    if (usageReport.byProcessEngineModel.length === 0) {
+        lines.push("  (no LLM calls recorded)");
+    }
+    else {
+        const headers = ["process", "engine", "model", "calls", "failures", "promptTok", "complTok", "totalTok", "ms"];
+        const rows = usageReport.byProcessEngineModel.map((row) => [
+            row.process,
+            row.engine,
+            row.model,
+            String(row.calls),
+            String(row.failures),
+            String(row.promptTokens),
+            String(row.completionTokens),
+            String(row.totalTokens),
+            String(row.totalDurationMs),
+        ]);
+        for (const line of renderFixedWidthTable(headers, rows))
+            lines.push(`  ${line}`);
+    }
+    if (usageReport.noCalls.length > 0) {
+        lines.push("[improve] enabled processes with zero calls:");
+        const headers = ["process", "engine", "reason"];
+        const rows = usageReport.noCalls.map((row) => [row.process, row.engine ?? "-", row.reason]);
+        for (const line of renderFixedWidthTable(headers, rows))
+            lines.push(`  ${line}`);
+    }
+    for (const note of notes ?? [])
+        lines.push(`  note: ${note}`);
+    return lines.join("\n");
+}