akm-cli 0.9.0-beta.54 → 0.9.0-beta.56

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

@@ -0,0 +1,65 @@
+// 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/.
+/**
+ * Aggregate `llm_usage` events (#576) into the window total + per-stage
+ * breakdown reported by `akm health`.
+ */
+import { readEvents } from "../../core/events.js";
+import { LLM_USAGE_EVENT } from "../../llm/usage-persist.js";
+import { toFiniteNumber } from "./improve-metrics.js";
+/** Stage key used for `llm_usage` events recorded outside any stage scope. */
+const UNATTRIBUTED_STAGE = "unattributed";
+function emptyLlmUsageStageAggregate() {
+    return {
+        calls: 0,
+        totalDurationMs: 0,
+        promptTokens: 0,
+        completionTokens: 0,
+        totalTokens: 0,
+        reasoningTokens: 0,
+    };
+}
+function emptyLlmUsageAggregate() {
+    return { ...emptyLlmUsageStageAggregate(), byStage: {} };
+}
+/**
+ * Aggregate `llm_usage` events (#576) into a window total plus a per-stage
+ * breakdown of call count, wall-time, and token usage. Token fields absent from
+ * a best-effort record contribute 0. Calls with no `stage` land under
+ * {@link UNATTRIBUTED_STAGE}.
+ */
+export function summarizeLlmUsage(events) {
+    const aggregate = emptyLlmUsageAggregate();
+    for (const event of events) {
+        const meta = event.metadata ?? {};
+        const stageKey = typeof meta.stage === "string" && meta.stage ? meta.stage : UNATTRIBUTED_STAGE;
+        let stage = aggregate.byStage[stageKey];
+        if (!stage) {
+            stage = emptyLlmUsageStageAggregate();
+            aggregate.byStage[stageKey] = stage;
+        }
+        const durationMs = toFiniteNumber(meta.durationMs);
+        const promptTokens = toFiniteNumber(meta.promptTokens);
+        const completionTokens = toFiniteNumber(meta.completionTokens);
+        const totalTokens = toFiniteNumber(meta.totalTokens);
+        const reasoningTokens = toFiniteNumber(meta.reasoningTokens);
+        for (const target of [aggregate, stage]) {
+            target.calls += 1;
+            target.totalDurationMs += durationMs;
+            target.promptTokens += promptTokens;
+            target.completionTokens += completionTokens;
+            target.totalTokens += totalTokens;
+            target.reasoningTokens += reasoningTokens;
+        }
+    }
+    return aggregate;
+}
+export function readLlmUsageAggregate(stateDbPath, since, until) {
+    const events = readEvents({ since, type: LLM_USAGE_EVENT }, { dbPath: stateDbPath }).events.filter((event) => {
+        if (until === undefined)
+            return true;
+        return new Date(event.ts ?? since).getTime() < new Date(until).getTime();
+    });
+    return summarizeLlmUsage(events);
+}

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

@@ -0,0 +1,103 @@
+// 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/.
+import { INTERESTING_DELTA_PATHS, readNumericPath } from "./windows.js";
+function padRight(s, width) {
+    return s.length >= width ? s : s + " ".repeat(width - s.length);
+}
+function renderTable(headers, rows) {
+    const widths = headers.map((h, i) => Math.max(h.length, ...rows.map((r) => (r[i] ?? "").length)));
+    const lines = [];
+    lines.push(headers.map((h, i) => padRight(h, widths[i] ?? 0)).join("  "));
+    for (const row of rows) {
+        lines.push(row.map((cell, i) => padRight(cell ?? "", widths[i] ?? 0)).join("  "));
+    }
+    return lines.join("\n");
+}
+/**
+ * Render `--detail per-run` rows as a TSV-ish aligned table. The column
+ * shape was originally inherited from the retired
+ * `scripts/improve-stats/runs-detail` bash helper; keep the same shape
+ * so operator muscle memory carries over.
+ *
+ * Columns: ts | ok | actions | refl_ok/fail/cd/skip |
+ *   distill_q/llm-fail/qrej/cfg/skip | cons_proc/promo/merge/del |
+ *   mem_cons/written/skip | graph_f/e/r | orphans | lint_f/fl
+ */
+export function renderRunsDetailMd(runs) {
+    const headers = [
+        "ts",
+        "ok",
+        "actions",
+        "refl_ok/fail/cd/skip",
+        "distill_q/llm-fail/qrej/cfg/skip",
+        "cons_proc/promo/merge/del",
+        "mem_cons/written/skip",
+        "graph_f/e/r",
+        "orphans",
+        "lint_f/fl",
+    ];
+    const rows = runs.map((r) => {
+        const totalActions = r.actions.reflect.ok +
+            r.actions.reflect.failed +
+            r.actions.reflect.cooldown +
+            r.actions.reflect.skipped +
+            r.actions.distill.queued +
+            r.actions.distill.llmFailed +
+            r.actions.distill.qualityRejected +
+            r.actions.distill.configDisabled +
+            r.actions.distill.skipped +
+            r.actions.memoryPrune +
+            r.actions.memoryInference +
+            r.actions.graphExtraction +
+            r.actions.error;
+        return [
+            r.startedAt,
+            String(r.ok),
+            String(totalActions),
+            `${r.actions.reflect.ok}/${r.actions.reflect.failed}/${r.actions.reflect.cooldown}/${r.actions.reflect.skipped}`,
+            `${r.actions.distill.queued}/${r.actions.distill.llmFailed}/${r.actions.distill.qualityRejected}/${r.actions.distill.configDisabled}/${r.actions.distill.skipped}`,
+            `${r.consolidation.processed}/${r.consolidation.promoted}/${r.consolidation.merged}/${r.consolidation.deleted}`,
+            `${r.memoryInference.considered}/${r.memoryInference.written}/${r.memoryInference.skippedNoFacts}`,
+            `${r.graphExtraction.extractedFiles}/${r.graphExtraction.entities}/${r.graphExtraction.relations}`,
+            String(r.orphansPurged),
+            `${r.lintFixed}/${r.lintFlagged}`,
+        ];
+    });
+    return renderTable(headers, rows);
+}
+/**
+ * Render a window-compare comparison as a side-by-side metric table with a
+ * delta column. Bad-direction deltas (e.g. +pct on failed counts) get a `!`
+ * marker prefix.
+ */
+export function renderWindowCompareMd(windows, deltas) {
+    if (windows.length === 0)
+        return "";
+    const headers = ["metric", ...windows.map((w) => w.name), "delta"];
+    const badIfPositive = new Set([
+        "improve.actions.reflect.failed",
+        "improve.actions.distill.llmFailed",
+        "improve.graphExtraction.failures",
+        "improve.graphExtraction.nonArrayBatchFailures",
+        "improve.wallTime.medianMs",
+        "improve.wallTime.p95Ms",
+        "improve.memoryInference.skippedNoFacts",
+    ]);
+    const rows = [];
+    for (const path of INTERESTING_DELTA_PATHS) {
+        const values = windows.map((w) => String(readNumericPath(w, path)));
+        const delta = deltas?.[path];
+        let deltaStr = "—";
+        if (delta) {
+            const pct = delta.pctChange;
+            const num = typeof pct === "number" ? pct : pct;
+            const sign = typeof num === "number" && num > 0 ? "+" : "";
+            const formatted = typeof num === "number" ? `${sign}${num}%` : String(num);
+            const marker = badIfPositive.has(path) && typeof num === "number" && num > 0 ? "!" : "";
+            deltaStr = marker + formatted;
+        }
+        rows.push([path, ...values, deltaStr]);
+    }
+    return renderTable(headers, rows);
+}

package/dist/commands/health/metrics.js

@@ -0,0 +1,278 @@
+// 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/.
+/**
+ * State.db-backed health metrics for `akm health`: the round-trip probe,
+ * auto-accept calibration, denominator-fixed coverage, the enrichment-vs-
+ * minting rollup, and the WS-5 per-run degradation metrics.
+ */
+import { appendEvent, readEvents } from "../../core/events.js";
+import { queryImproveRuns } from "../../storage/repositories/improve-runs-repository.js";
+import { listProposalGateDecisions, listStateProposals } from "../../storage/repositories/proposals-repository.js";
+import { gateDecisionsToSamples, summarizeCalibration } from "../improve/calibration.js";
+import { roundRate, toFiniteNumber } from "./improve-metrics.js";
+import { ENRICHMENT_LANES, } from "./types.js";
+/** Event type appended + read back by the state.db round-trip probe. */
+const HEALTH_PROBE_EVENT = "health_probe";
+export function probeStateDbRoundTrip(stateDbPath) {
+    const before = readEvents({}, { dbPath: stateDbPath }).nextOffset;
+    const started = Date.now();
+    appendEvent({ eventType: HEALTH_PROBE_EVENT, ref: "health:probe", metadata: { source: "akm health" } }, { dbPath: stateDbPath });
+    const after = readEvents({ sinceOffset: before, type: HEALTH_PROBE_EVENT, ref: "health:probe" }, { dbPath: stateDbPath });
+    const durationMs = Date.now() - started;
+    if (after.events.length === 0 || after.nextOffset <= before) {
+        return { ok: false, durationMs, error: "probe event was not readable after append" };
+    }
+    return { ok: true, durationMs };
+}
+/**
+ * Read the auto-accept gate calibration summary (#612) over `[since, until)`.
+ * Reads every proposal's `gateDecision` from the open state.db, projects the
+ * acted-on (auto-accepted / auto-rejected) decisions into calibration samples
+ * within the window, and aggregates them deterministically.
+ */
+export function readCalibration(db, since, until) {
+    const decisions = listProposalGateDecisions(db);
+    const samples = gateDecisionsToSamples(decisions, { since, ...(until !== undefined ? { until } : {}) });
+    return summarizeCalibration(samples);
+}
+// ── WS-5 Observability helpers ───────────────────────────────────────────────
+/**
+ * Compute WS-5 denominator-fixed coverage metrics.
+ *
+ * `coverage = accepted_proposals / total_assets` (Part V §3).
+ * The denominator is the TOTAL stash size (not the moving eligible set) so
+ * more-inclusive WS-1 ranking cannot spuriously inflate coverage.
+ * `eligibleFraction = eligible_assets / total_assets` is reported separately.
+ *
+ * Proposals are counted only when their `updatedAt` falls within `[since, until)`
+ * so the rate is genuinely window-scoped (matching the JSDoc on the type).
+ *
+ * @param db - Open state.db connection.
+ * @param totalAssets - Total stash asset count (eligible + derived) from the
+ *   most recent run's memorySummary. 0 = denominator unknown, returns NaN rates.
+ * @param eligibleAssets - Eligible (non-derived) asset count from the most recent run.
+ * @param since - Window start (ISO-8601). Proposals accepted before this are excluded.
+ * @param until - Window end (ISO-8601, exclusive). Absent = open-ended (up to now).
+ * @param stashDir - Optional: scope accepted proposals to one stash. Absent = all stashes.
+ */
+export function computeDenominatorFixedCoverage(db, totalAssets, eligibleAssets, since, until, stashDir) {
+    let acceptedProposals = 0;
+    let distinctRefs = 0;
+    try {
+        const proposals = listStateProposals(db, {
+            status: "accepted",
+            ...(stashDir ? { stashDir } : {}),
+        }).filter((p) => {
+            const updatedAt = p.updatedAt ?? "";
+            if (updatedAt < since)
+                return false;
+            if (until !== undefined && updatedAt >= until)
+                return false;
+            return true;
+        });
+        acceptedProposals = proposals.length;
+        // Coverage counts DISTINCT refs: N accepted rewrites of one asset are
+        // churn, not coverage. The raw proposal count is kept alongside so the
+        // churn ratio (proposals ÷ distinct refs) stays visible.
+        distinctRefs = new Set(proposals.map((p) => p.ref)).size;
+    }
+    catch {
+        // Fail open: table may not exist on older installs.
+    }
+    const churnRatio = distinctRefs > 0 ? roundRate(acceptedProposals / distinctRefs) : Number.NaN;
+    if (totalAssets === 0) {
+        return {
+            rate: Number.NaN,
+            eligibleFraction: Number.NaN,
+            acceptedProposals,
+            distinctRefs,
+            churnRatio,
+            totalAssets: 0,
+        };
+    }
+    return {
+        rate: roundRate(distinctRefs / totalAssets),
+        eligibleFraction: roundRate(eligibleAssets / totalAssets),
+        acceptedProposals,
+        distinctRefs,
+        churnRatio,
+        totalAssets,
+    };
+}
+/**
+ * Compute the enrichment-vs-minting rollup over the window's accepted,
+ * lane-attributed proposals (reporting-only; see {@link EnrichmentMintingRollup}).
+ *
+ * SQL-side `json_extract` keeps the (potentially large) `backupContent` blobs
+ * out of process memory. Pre-Phase-6C rows without an `eligibilitySource`
+ * cannot be lane-classified and are excluded. Fails open (undefined) when the
+ * proposals table is absent.
+ */
+export function computeEnrichmentMintingRollup(db, since, until) {
+    try {
+        const rows = db
+            .prepare(`SELECT
+           json_extract(metadata_json, '$.eligibilitySource') AS lane,
+           CASE WHEN json_extract(metadata_json, '$.backupContent') IS NULL THEN 1 ELSE 0 END AS is_minted,
+           COUNT(*) AS cnt
+         FROM proposals
+         WHERE status = 'accepted'
+           AND updated_at >= ?
+           AND (? IS NULL OR updated_at < ?)
+           AND json_extract(metadata_json, '$.eligibilitySource') IS NOT NULL
+           AND json_extract(metadata_json, '$.eligibilitySource') != ''
+         GROUP BY lane, is_minted`)
+            .all(since, until ?? null, until ?? null);
+        if (rows.length === 0)
+            return undefined;
+        const byLane = {};
+        for (const row of rows) {
+            byLane[row.lane] ??= { minted: 0, updated: 0 };
+            const entry = byLane[row.lane];
+            if (row.is_minted === 1)
+                entry.minted += row.cnt;
+            else
+                entry.updated += row.cnt;
+        }
+        let minted = 0;
+        let updated = 0;
+        for (const lane of ENRICHMENT_LANES) {
+            const entry = byLane[lane];
+            if (!entry)
+                continue;
+            minted += entry.minted;
+            updated += entry.updated;
+        }
+        const decided = minted + updated;
+        return {
+            minted,
+            updated,
+            share: decided > 0 ? roundRate(minted / decided) : Number.NaN,
+            byLane,
+        };
+    }
+    catch {
+        // Fail open: proposals table may not exist on older installs.
+        return undefined;
+    }
+}
+/**
+ * Compute WS-5 per-run degradation metrics (Part V §4).
+ *
+ * Health VIEWS only — reads from state.db tables populated by prior improve
+ * runs. Gracefully returns partial data when tables are absent (pre-WS-1/2).
+ *
+ * @param db - Open state.db connection.
+ * @param since - Window start (ISO-8601).
+ * @param until - Window end (ISO-8601).
+ */
+export function computeDegradationMetrics(db, since, until) {
+    // (a) Corpus diversity — salience rank distribution of the top-100 assets.
+    // We use the Gini coefficient of retrieval_salience scores as an intra-corpus
+    // diversity proxy. A Gini close to 1 = highly concentrated (entrenched top
+    // assets), Gini near 0 = flat/diverse. This is a single-snapshot metric;
+    // consecutive-run centroid distance requires cross-run history not yet stored.
+    let corpusCentroidDistance = Number.NaN;
+    let entrenchmentFlagged;
+    let salienceUniformityFlagged;
+    try {
+        const rows = db
+            .prepare(`SELECT retrieval_salience FROM asset_salience
+         ORDER BY rank_score DESC LIMIT 100`)
+            .all();
+        if (rows.length >= 5) {
+            const vals = rows.map((r) => r.retrieval_salience).sort((a, b) => a - b);
+            const n = vals.length;
+            const sumAbsDiff = vals.reduce((acc, xi, i) => {
+                return acc + vals.slice(i + 1).reduce((a, xj) => a + Math.abs(xi - xj), 0);
+            }, 0);
+            const mean = vals.reduce((a, b) => a + b, 0) / n;
+            // Gini = (sum |xi - xj|) / (2 n^2 mean); 0 = perfect equality, 1 = perfect inequality.
+            const gini = mean > 0 ? sumAbsDiff / (2 * n * n * mean) : 0;
+            // Re-express as a diversity proxy in [0,1]: high gini = low diversity.
+            // corpusCentroidDistance approximation: gini is "distance from uniform".
+            // Note: retrieval_salience values are in [0,1], so the max achievable Gini
+            // with this formula is ~0.5 (when one asset dominates and others are near 0).
+            // Two-tailed: >0.35 flags entrenchment (robustly above the ~0.1 uniform
+            // baseline); <0.08 flags uniformity collapse — the distribution no longer
+            // discriminates between assets (live 2026-07 value 0.040 sat unflagged
+            // in this tail under the old one-tailed check).
+            corpusCentroidDistance = roundRate(gini);
+            entrenchmentFlagged = gini > 0.35;
+            salienceUniformityFlagged = gini < 0.08;
+        }
+    }
+    catch {
+        // Table not present (pre-WS-1 install) — leave NaN.
+    }
+    // (b) Merge fidelity — fraction of consolidate accepted proposals in the window
+    // whose ref also has a consolidate skip-reason of "contradict_target_missing"
+    // or an event indicating contradiction. Uses the improve_runs result_json
+    // consolidation.contradicted count as a proxy.
+    // Simple implementation: contradictionRate = total_contradicted / max(1, total_processed)
+    // sourced from the window's consolidation envelope.
+    // (The full "merge proposal → later contradiction" correlation requires cross-run
+    // history; this is the available proxy.)
+    let mergeFidelityContradictionRate = 0;
+    try {
+        const runs = queryImproveRuns(db, since, until);
+        let totalContradicted = 0;
+        let totalProcessed = 0;
+        for (const row of runs) {
+            try {
+                const result = JSON.parse(row.result_json);
+                const cons = result.consolidation;
+                if (cons) {
+                    totalContradicted += toFiniteNumber(cons.contradicted);
+                    totalProcessed += toFiniteNumber(cons.processed);
+                }
+            }
+            catch {
+                // Skip malformed rows.
+            }
+        }
+        if (totalProcessed > 0) {
+            mergeFidelityContradictionRate = roundRate(totalContradicted / totalProcessed);
+        }
+    }
+    catch {
+        // Fail open.
+    }
+    // (c) highGenerationFraction was DELETED (meta-review 05 DRIFT-3): it
+    // approximated "LLM-merge generations" from consecutive_no_ops — which counts
+    // the opposite condition (cycles where nothing was changed) — and its own
+    // in-code TODO admitted the proxy. Display-only, never actionable; removed
+    // rather than instrumented.
+    // (d) Oracle spot-check — up to 5 recently accepted proposals in the window.
+    const oracleSpotCheck = [];
+    try {
+        const accepted = listStateProposals(db, { status: "accepted" }).filter((p) => {
+            const updatedAt = p.updatedAt ?? "";
+            return updatedAt >= since && updatedAt < until;
+        });
+        // Sample up to 5: pick evenly spaced (not just the first 5).
+        const step = Math.max(1, Math.floor(accepted.length / 5));
+        for (let i = 0; i < accepted.length && oracleSpotCheck.length < 5; i += step) {
+            const p = accepted[i];
+            if (p) {
+                oracleSpotCheck.push({
+                    proposalId: p.id,
+                    ref: p.ref,
+                    source: p.source ?? "unknown",
+                    acceptedAt: p.updatedAt ?? p.createdAt ?? "",
+                });
+            }
+        }
+    }
+    catch {
+        // Fail open.
+    }
+    return {
+        corpusCentroidDistance,
+        entrenchmentFlagged,
+        salienceUniformityFlagged,
+        mergeFidelityContradictionRate,
+        oracleSpotCheck,
+    };
+}

package/dist/commands/health/task-runs.js

@@ -0,0 +1,135 @@
+// 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/.
+import { queryImproveRuns } from "../../storage/repositories/improve-runs-repository.js";
+import { queryCompletedTaskIntervals, queryTaskHistory } from "../../storage/repositories/task-history-repository.js";
+import { projectImproveRunSummary } from "./improve-metrics.js";
+/**
+ * Load task_history intervals for `task_id='akm-improve'` in the window.
+ * Returned sorted by startMs ascending so containment lookups can use a
+ * linear scan (typical N is ~24/day; not worth a tree).
+ *
+ * The window filter is widened by 5 minutes on each side because the cron
+ * task wraps `akm improve` — the task `started_at` fires at e.g. :07:01
+ * while `recordImproveRun` writes the matching `improve_runs.started_at`
+ * later (after config load, planning, etc.), so the improve_runs row can
+ * be inside the window even when its enclosing task_history row started
+ * just before the window opened.
+ */
+function loadTaskIntervals(db, since, until) {
+    const sinceMs = new Date(since).getTime();
+    const untilMs = until ? new Date(until).getTime() : Number.POSITIVE_INFINITY;
+    const widenedSince = new Date(sinceMs - 5 * 60 * 1000).toISOString();
+    const widenedUntil = Number.isFinite(untilMs) ? new Date(untilMs + 5 * 60 * 1000).toISOString() : undefined;
+    const rows = queryCompletedTaskIntervals(db, widenedSince, widenedUntil);
+    const intervals = [];
+    for (const row of rows) {
+        const startMs = new Date(row.started_at).getTime();
+        const endMs = new Date(row.completed_at).getTime();
+        if (!Number.isFinite(startMs) || !Number.isFinite(endMs) || endMs < startMs)
+            continue;
+        intervals.push({ startMs, endMs, durationMs: endMs - startMs });
+    }
+    return intervals;
+}
+/**
+ * Find the task_history interval that contains the given timestamp. The
+ * task wraps `akm improve`, so `improve_runs.started_at` (when
+ * `recordImproveRun` writes) always falls inside the enclosing task's
+ * [started_at, completed_at]. Returns undefined when no interval
+ * contains the timestamp (which happens for manually-invoked improve
+ * runs not driven by the `akm-improve` task).
+ *
+ * Linear scan because N is small. We tolerate a 1s slop on the upper
+ * bound to handle clock skew between the wrapper's `completed_at` write
+ * and recordImproveRun's `started_at` write.
+ */
+function findContainingTaskInterval(timestampMs, intervals) {
+    const SLOP_MS = 1000;
+    for (const interval of intervals) {
+        if (timestampMs >= interval.startMs && timestampMs <= interval.endMs + SLOP_MS) {
+            return interval;
+        }
+    }
+    return undefined;
+}
+/**
+ * Load `task_history` rows whose `task_id` begins `akm-improve` (the scheduled
+ * improve tasks: `akm-improve-frequent`, `akm-improve-proactive-weekly`, …) in
+ * the window, widened ±5 min so a task that fired just before the window opened
+ * still matches a run inside it. Used to attribute each improve run to the task
+ * that launched it.
+ */
+function loadImproveTaskRuns(db, since, until) {
+    const sinceMs = new Date(since).getTime();
+    const untilMs = until ? new Date(until).getTime() : undefined;
+    const widenedSince = new Date(sinceMs - 5 * 60 * 1000).toISOString();
+    const widenedUntil = untilMs !== undefined ? new Date(untilMs + 5 * 60 * 1000).toISOString() : undefined;
+    const runs = [];
+    for (const row of queryTaskHistory(db, { since: widenedSince, until: widenedUntil })) {
+        if (!row.task_id.startsWith("akm-improve"))
+            continue;
+        const startMs = new Date(row.started_at).getTime();
+        if (!Number.isFinite(startMs))
+            continue;
+        const endIso = row.completed_at ?? row.failed_at;
+        const endMs = endIso ? new Date(endIso).getTime() : Number.NaN;
+        runs.push({ taskId: row.task_id, startMs, endMs });
+    }
+    return runs;
+}
+/**
+ * Attribute an improve run to the scheduled task that launched it by matching
+ * start times within ±5 min, scored by start delta (plus end delta when both
+ * ends are known). Port of the health-report skill's `match_task_id`. Returns
+ * `"manual"` when no scheduled improve task matches.
+ */
+export function matchImproveTaskId(startedAt, completedAt, taskRuns) {
+    const startMs = new Date(startedAt).getTime();
+    if (!Number.isFinite(startMs))
+        return "manual";
+    const endMs = completedAt ? new Date(completedAt).getTime() : Number.NaN;
+    let best;
+    let bestScore = Number.POSITIVE_INFINITY;
+    for (const task of taskRuns) {
+        const startDelta = Math.abs(task.startMs - startMs);
+        if (startDelta > 5 * 60 * 1000)
+            continue;
+        let score = startDelta;
+        if (Number.isFinite(endMs) && Number.isFinite(task.endMs))
+            score += Math.abs(task.endMs - endMs);
+        if (score < bestScore) {
+            bestScore = score;
+            best = task.taskId;
+        }
+    }
+    return best ?? "manual";
+}
+export function buildPerRunSummaries(db, since, until) {
+    const rows = queryImproveRuns(db, since, until);
+    const taskIntervals = loadTaskIntervals(db, since, until);
+    const improveTaskRuns = loadImproveTaskRuns(db, since, until);
+    const summaries = [];
+    for (const row of rows) {
+        const startMs = new Date(row.started_at).getTime();
+        const endMs = new Date(row.completed_at).getTime();
+        // Prefer the improve_runs row's own (completed_at - started_at) delta:
+        // recordImproveRun now persists distinct start/end timestamps, so the
+        // row's own delta is the authoritative per-run wall time even for
+        // manually-invoked `akm improve` runs with no enclosing task_history.
+        // Only fall back to the task_history containing-interval join for legacy/
+        // backfill rows where started_at == completed_at (row delta is 0).
+        const hasRowDelta = Number.isFinite(startMs) && Number.isFinite(endMs) && endMs > startMs;
+        let wallTimeMs;
+        if (hasRowDelta) {
+            wallTimeMs = endMs - startMs;
+        }
+        else {
+            const interval = Number.isFinite(startMs) ? findContainingTaskInterval(startMs, taskIntervals) : undefined;
+            wallTimeMs = interval?.durationMs ?? 0;
+        }
+        const taskId = matchImproveTaskId(row.started_at, row.completed_at, improveTaskRuns);
+        summaries.push(projectImproveRunSummary(row, wallTimeMs, taskId));
+    }
+    return summaries;
+}

package/dist/commands/health/types.js

@@ -0,0 +1,18 @@
+// 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/.
+/**
+ * Lanes ratified as ENRICHMENT-ONLY: they may propose edits to existing
+ * assets (metadata, relations, content refresh) but must not mint new ones.
+ * New-asset generation belongs to the signal-gated minting lanes
+ * (extract/distill/memory-inference/recombine).
+ */
+export const ENRICHMENT_LANES = ["proactive", "high-salience", "high-retrieval", "signal-delta"];
+/** Minted share of enrichment-lane accepts that triggers a WARN advisory. */
+export const ENRICHMENT_MINTED_WARN_SHARE = 0.05;
+/** Minted share of enrichment-lane accepts that triggers a FAIL advisory. */
+export const ENRICHMENT_MINTED_FAIL_SHARE = 0.15;
+/** Event type recorded on each completed improve run. */
+export const IMPROVE_COMPLETED_EVENT = "improve_completed";
+/** An active task older than this (ms) is treated as stuck. */
+export const ACTIVE_RUN_WARN_MS = 15 * 60 * 1000;