akm-cli 0.8.0-rc2 → 0.8.0

package/dist/commands/health.js

@@ -1,3 +1,6 @@
+// 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 { spawnSync } from "node:child_process";
 import fs from "node:fs";
 import { loadConfig } from "../core/config";
@@ -48,17 +51,27 @@ function createUnknownImproveMetrics() {
         skipped: 0,
         skipReasons: {},
         plannedRefs: 0,
+        profileFilteredRefs: 0,
         actions: {
-            reflect: 0,
-            distill: 0,
-            distillSkipped: 0,
+            reflect: { ok: 0, failed: 0, cooldown: 0, skipped: 0, guardRejected: 0, skippedByReason: {} },
+            distill: {
+                queued: 0,
+                llmFailed: 0,
+                qualityRejected: 0,
+                judgeRejected: 0,
+                validatorRejected: 0,
+                configDisabled: 0,
+                skipped: 0,
+                skippedByReason: {},
+                deferred: 0,
+                deferredByReason: {},
+            },
             memoryPrune: 0,
             memoryInference: 0,
             graphExtraction: 0,
             error: 0,
         },
-        crossStepErrorsInjected: 0,
-        feedbackRatioUsed: false,
+        reflectsWithErrorContext: 0,
         coverageGapCount: 0,
         executionLogCandidateCount: 0,
         evalCasesWritten: 0,
@@ -72,9 +85,63 @@ function createUnknownImproveMetrics() {
             archived: 0,
             warnings: 0,
         },
-        consolidation: { ran: false, processed: 0, durationMs: 0 },
-        memoryInference: { ran: false, writes: 0, durationMs: 0 },
-        graphExtraction: { ran: false, extractedFiles: 0, durationMs: 0 },
+        consolidation: {
+            ran: false,
+            processed: 0,
+            promoted: 0,
+            merged: 0,
+            deleted: 0,
+            contradicted: 0,
+            judgedNoAction: 0,
+            mergedSecondaries: 0,
+            failedChunkMemories: 0,
+            skipReasons: {},
+            failedChunks: 0,
+            totalChunks: 0,
+            durationMs: 0,
+        },
+        memoryInference: {
+            ran: false,
+            considered: 0,
+            cacheHits: 0,
+            freshAttempts: 0,
+            splitParents: 0,
+            written: 0,
+            skippedNoFacts: 0,
+            skippedChildExists: 0,
+            skippedAborted: 0,
+            unaccounted: 0,
+            yieldEligibleRuns: 0,
+            yieldEligibleConsidered: 0,
+            yieldEligibleWritten: 0,
+            yieldRate: 0,
+            durationMs: 0,
+            writes: 0,
+        },
+        graphExtraction: {
+            ran: false,
+            extractedFiles: 0,
+            entities: 0,
+            relations: 0,
+            cacheHits: 0,
+            cacheMisses: 0,
+            cacheHitRate: 0,
+            truncations: 0,
+            failures: 0,
+            durationMs: 0,
+        },
+        wallTime: {
+            count: 0,
+            medianMs: 0,
+            p95Ms: 0,
+            minMs: 0,
+            maxMs: 0,
+            byPhase: {
+                consolidation: { count: 0, totalMs: 0, medianMs: 0, p95Ms: 0 },
+                memoryInference: { count: 0, totalMs: 0, medianMs: 0, p95Ms: 0 },
+                graphExtraction: { count: 0, totalMs: 0, medianMs: 0, p95Ms: 0 },
+            },
+        },
     };
 }
 function toFiniteNumber(value) {
@@ -87,46 +154,558 @@ function toFiniteNumber(value) {
     }
     return 0;
 }
+/**
+ * Event-derived metrics. Only `completed` and skipReasons/invoked are sourced
+ * from events in v2 — the richer fields come from {@link summarizeImproveRuns}.
+ * The function still receives `improve_completed` events so that the completed
+ * count reflects the canonical event stream (it lines up 1:1 with improve_runs
+ * rows in practice, but the events table remains the system-of-record for the
+ * existence of a run).
+ */
 function summarizeImproveCompleted(events) {
     const metrics = createUnknownImproveMetrics();
     metrics.completed = events.length;
-    for (const event of events) {
-        const meta = event.metadata ?? {};
-        metrics.plannedRefs += toFiniteNumber(meta.plannedRefs);
-        metrics.actions.reflect += toFiniteNumber(meta.reflectActions);
-        metrics.actions.distill += toFiniteNumber(meta.distillActions);
-        metrics.actions.distillSkipped += toFiniteNumber(meta.distillSkippedActions);
-        metrics.actions.memoryPrune += toFiniteNumber(meta.memoryPruneActions);
-        metrics.actions.memoryInference += toFiniteNumber(meta.memoryInferenceActions);
-        metrics.actions.graphExtraction += toFiniteNumber(meta.graphExtractionActions);
-        metrics.actions.error += toFiniteNumber(meta.errorActions);
-        metrics.crossStepErrorsInjected += toFiniteNumber(meta.crossStepErrorsInjected);
-        metrics.coverageGapCount += toFiniteNumber(meta.coverageGapCount);
-        metrics.executionLogCandidateCount += toFiniteNumber(meta.executionLogCandidateCount);
-        metrics.evalCasesWritten += toFiniteNumber(meta.evalCasesWritten);
-        metrics.deadUrlCount += toFiniteNumber(meta.deadUrlCount);
-        metrics.memorySummary.eligible += toFiniteNumber(meta.memoryEligible);
-        metrics.memorySummary.derived += toFiniteNumber(meta.memoryDerived);
-        metrics.memoryCleanup.pruneCandidates += toFiniteNumber(meta.memoryCleanupPruneCandidates);
-        metrics.memoryCleanup.contradictionCandidates += toFiniteNumber(meta.memoryCleanupContradictionCandidates);
-        metrics.memoryCleanup.beliefStateTransitions += toFiniteNumber(meta.memoryCleanupBeliefStateTransitions);
-        metrics.memoryCleanup.consolidationCandidates += toFiniteNumber(meta.memoryCleanupConsolidationCandidates);
-        metrics.memoryCleanup.archived += toFiniteNumber(meta.memoryCleanupArchived);
-        metrics.memoryCleanup.warnings += toFiniteNumber(meta.memoryCleanupWarnings);
-        metrics.consolidation.processed += toFiniteNumber(meta.consolidationProcessed);
-        metrics.consolidation.durationMs += toFiniteNumber(meta.consolidationDurationMs);
-        metrics.memoryInference.writes += toFiniteNumber(meta.memoryInferenceWrites);
-        metrics.memoryInference.durationMs += toFiniteNumber(meta.memoryInferenceDurationMs);
-        metrics.graphExtraction.extractedFiles += toFiniteNumber(meta.graphExtractionExtractedFiles);
-        metrics.graphExtraction.durationMs += toFiniteNumber(meta.graphExtractionDurationMs);
-        if (meta.feedbackRatioUsed === true)
-            metrics.feedbackRatioUsed = true;
-    }
-    metrics.consolidation.ran = metrics.consolidation.processed > 0 || metrics.consolidation.durationMs > 0;
-    metrics.memoryInference.ran = metrics.memoryInference.writes > 0 || metrics.memoryInference.durationMs > 0;
-    metrics.graphExtraction.ran = metrics.graphExtraction.extractedFiles > 0 || metrics.graphExtraction.durationMs > 0;
     return metrics;
 }
+/**
+ * Project a single `improve_runs.result_json` envelope into an accumulator-shaped
+ * ImproveHealthMetrics. The aggregator merges these per-row metrics into one
+ * window-level metric.
+ */
+function projectRunMetrics(result) {
+    const metrics = createUnknownImproveMetrics();
+    // plannedRefs (array of {ref, reason})
+    const plannedRefs = result.plannedRefs;
+    if (Array.isArray(plannedRefs))
+        metrics.plannedRefs += plannedRefs.length;
+    // profileFilteredRefs (array of {ref, reason}) — 2026-05-27: pre-filter
+    // bucket from `collectEligibleRefs` so the metric reflects work the
+    // planner dropped before signal-delta / per-pass dispatch.
+    const profileFilteredRefs = result.profileFilteredRefs;
+    if (Array.isArray(profileFilteredRefs))
+        metrics.profileFilteredRefs += profileFilteredRefs.length;
+    // actions: split reflect / distill by outcome, count others.
+    const actions = result.actions;
+    if (Array.isArray(actions)) {
+        for (const action of actions) {
+            const mode = typeof action.mode === "string" ? action.mode : "";
+            switch (mode) {
+                case "reflect":
+                    metrics.actions.reflect.ok += 1;
+                    break;
+                case "reflect-failed":
+                    metrics.actions.reflect.failed += 1;
+                    break;
+                case "reflect-cooldown":
+                    metrics.actions.reflect.cooldown += 1;
+                    break;
+                case "reflect-skipped": {
+                    metrics.actions.reflect.skipped += 1;
+                    const r = action.result;
+                    const reason = typeof r?.reason === "string" && r.reason.trim() ? r.reason : "unknown";
+                    metrics.actions.reflect.skippedByReason[reason] = (metrics.actions.reflect.skippedByReason[reason] ?? 0) + 1;
+                    break;
+                }
+                case "reflect-guard-rejected":
+                    metrics.actions.reflect.guardRejected += 1;
+                    break;
+                case "distill": {
+                    const r = action.result;
+                    const outcome = typeof r?.outcome === "string" ? r.outcome : "";
+                    switch (outcome) {
+                        case "queued":
+                            metrics.actions.distill.queued += 1;
+                            break;
+                        case "llm_failed":
+                            metrics.actions.distill.llmFailed += 1;
+                            break;
+                        case "quality_rejected":
+                        case "review_needed":
+                            metrics.actions.distill.qualityRejected += 1;
+                            metrics.actions.distill.judgeRejected += 1;
+                            break;
+                        case "validation_failed":
+                            metrics.actions.distill.qualityRejected += 1;
+                            metrics.actions.distill.validatorRejected += 1;
+                            break;
+                        case "config_disabled":
+                            metrics.actions.distill.configDisabled += 1;
+                            break;
+                        case "skipped": {
+                            // Previously dropped on the floor. The four sub-paths that emit
+                            // `outcome: "skipped"` (see distill.ts:893, 1024, 1120, 1576):
+                            //   - recursive_lesson_input (type guard refused a lesson input)
+                            //   - conflict_noop (LLM resolved destination conflict as NOOP)
+                            //   - proposal-skipped cooldown / dedup at persistence
+                            // 465 events/7d in the user's live stack. The result message
+                            // typically encodes the reason; we also accept an explicit
+                            // `skipReason` field when downstream code sets it.
+                            metrics.actions.distill.deferred += 1;
+                            const explicitReason = typeof r?.skipReason === "string" ? r.skipReason : undefined;
+                            const msg = typeof r?.message === "string" ? r.message : "";
+                            let reason = explicitReason ?? "unknown";
+                            if (!explicitReason) {
+                                if (/lesson inputs/i.test(msg))
+                                    reason = "recursive_lesson_input";
+                                else if (/NOOP/.test(msg))
+                                    reason = "conflict_noop";
+                                else if (/cooldown/i.test(msg))
+                                    reason = "proposal_cooldown";
+                                else if (/content[_ ]?hash/i.test(msg))
+                                    reason = "content_hash_match";
+                            }
+                            metrics.actions.distill.deferredByReason[reason] =
+                                (metrics.actions.distill.deferredByReason[reason] ?? 0) + 1;
+                            break;
+                        }
+                        default:
+                            break;
+                    }
+                    break;
+                }
+                case "distill-skipped": {
+                    metrics.actions.distill.skipped += 1;
+                    const r = action.result;
+                    const reason = typeof r?.reason === "string" && r.reason.trim() ? r.reason : "unknown";
+                    metrics.actions.distill.skippedByReason[reason] = (metrics.actions.distill.skippedByReason[reason] ?? 0) + 1;
+                    break;
+                }
+                case "memory-prune":
+                    metrics.actions.memoryPrune += 1;
+                    break;
+                case "memory-inference":
+                    metrics.actions.memoryInference += 1;
+                    break;
+                case "graph-extraction":
+                    metrics.actions.graphExtraction += 1;
+                    break;
+                case "error":
+                    metrics.actions.error += 1;
+                    break;
+            }
+        }
+    }
+    metrics.reflectsWithErrorContext += toFiniteNumber(result.reflectsWithErrorContext);
+    if (Array.isArray(result.coverageGaps))
+        metrics.coverageGapCount += result.coverageGaps.length;
+    if (Array.isArray(result.executionLogCandidates))
+        metrics.executionLogCandidateCount += result.executionLogCandidates.length;
+    metrics.evalCasesWritten += toFiniteNumber(result.evalCasesWritten);
+    if (Array.isArray(result.deadUrls))
+        metrics.deadUrlCount += result.deadUrls.length;
+    const memorySummary = result.memorySummary;
+    if (memorySummary) {
+        metrics.memorySummary.eligible += toFiniteNumber(memorySummary.eligible);
+        metrics.memorySummary.derived += toFiniteNumber(memorySummary.derived);
+    }
+    const memoryCleanup = result.memoryCleanup;
+    if (memoryCleanup) {
+        if (Array.isArray(memoryCleanup.pruneCandidates))
+            metrics.memoryCleanup.pruneCandidates += memoryCleanup.pruneCandidates.length;
+        if (Array.isArray(memoryCleanup.contradictionCandidates))
+            metrics.memoryCleanup.contradictionCandidates += memoryCleanup.contradictionCandidates.length;
+        if (Array.isArray(memoryCleanup.beliefStateTransitions))
+            metrics.memoryCleanup.beliefStateTransitions += memoryCleanup.beliefStateTransitions.length;
+        if (Array.isArray(memoryCleanup.consolidationCandidates))
+            metrics.memoryCleanup.consolidationCandidates += memoryCleanup.consolidationCandidates.length;
+        if (Array.isArray(memoryCleanup.archived))
+            metrics.memoryCleanup.archived += memoryCleanup.archived.length;
+        if (Array.isArray(memoryCleanup.warnings))
+            metrics.memoryCleanup.warnings += memoryCleanup.warnings.length;
+    }
+    const consolidation = result.consolidation;
+    if (consolidation) {
+        metrics.consolidation.processed += toFiniteNumber(consolidation.processed);
+        metrics.consolidation.merged += toFiniteNumber(consolidation.merged);
+        metrics.consolidation.deleted += toFiniteNumber(consolidation.deleted);
+        metrics.consolidation.contradicted += toFiniteNumber(consolidation.contradicted);
+        if (Array.isArray(consolidation.promoted))
+            metrics.consolidation.promoted += consolidation.promoted.length;
+        metrics.consolidation.failedChunks += toFiniteNumber(consolidation.failedChunks);
+        metrics.consolidation.totalChunks += toFiniteNumber(consolidation.totalChunks);
+        metrics.consolidation.durationMs += toFiniteNumber(consolidation.durationMs);
+        metrics.consolidation.judgedNoAction += toFiniteNumber(consolidation.judgedNoAction);
+        metrics.consolidation.mergedSecondaries += toFiniteNumber(consolidation.mergedSecondaries);
+        metrics.consolidation.failedChunkMemories += toFiniteNumber(consolidation.failedChunkMemories);
+        // Structured emitter (new on this branch): consolidate.ts now pushes
+        // `{op, ref, reason}` entries to `skipReasons` for every deterministic
+        // post-LLM rejection. Pre-fix envelopes have neither field, so be
+        // defensive.
+        const skipReasons = consolidation.skipReasons;
+        if (Array.isArray(skipReasons)) {
+            for (const entry of skipReasons) {
+                if (!entry || typeof entry !== "object")
+                    continue;
+                const reason = entry.reason;
+                if (typeof reason !== "string" || !reason.trim())
+                    continue;
+                metrics.consolidation.skipReasons[reason] = (metrics.consolidation.skipReasons[reason] ?? 0) + 1;
+            }
+        }
+    }
+    const memoryInference = result.memoryInference;
+    if (memoryInference) {
+        const considered = toFiniteNumber(memoryInference.considered);
+        const writtenFacts = toFiniteNumber(memoryInference.writtenFacts);
+        metrics.memoryInference.considered += considered;
+        metrics.memoryInference.cacheHits += toFiniteNumber(memoryInference.cacheHits);
+        metrics.memoryInference.splitParents += toFiniteNumber(memoryInference.splitParents);
+        metrics.memoryInference.written += writtenFacts;
+        metrics.memoryInference.skippedNoFacts += toFiniteNumber(memoryInference.skippedNoFacts);
+        metrics.memoryInference.skippedChildExists += toFiniteNumber(memoryInference.skippedChildExists);
+        metrics.memoryInference.skippedAborted += toFiniteNumber(memoryInference.skippedAborted);
+        metrics.memoryInference.unaccounted += toFiniteNumber(memoryInference.unaccounted);
+        // Yield-rate gating: pre-cache-feature envelopes lack the `cacheHits`
+        // field entirely. Treating their `considered` as freshAttempts (since
+        // cacheHits=0) is mathematically tempting but operationally wrong —
+        // historical runs with the legacy schema have no cache instrumentation
+        // and the SUM dragged the reported rate to ~14% in local data. Only
+        // contribute to the yield aggregate when the envelope actually carries
+        // the field. See investigation 2026-05-26.
+        if (Object.hasOwn(memoryInference, "cacheHits")) {
+            metrics.memoryInference.yieldEligibleRuns += 1;
+            metrics.memoryInference.yieldEligibleConsidered += considered;
+            metrics.memoryInference.yieldEligibleWritten += writtenFacts;
+        }
+    }
+    metrics.memoryInference.durationMs += toFiniteNumber(result.memoryInferenceDurationMs);
+    const graphExtraction = result.graphExtraction;
+    if (graphExtraction) {
+        const quality = graphExtraction.quality;
+        if (quality)
+            metrics.graphExtraction.extractedFiles += toFiniteNumber(quality.extractedFiles);
+        metrics.graphExtraction.entities += toFiniteNumber(graphExtraction.totalEntities);
+        metrics.graphExtraction.relations += toFiniteNumber(graphExtraction.totalRelations);
+        const telemetry = graphExtraction.telemetry;
+        if (telemetry) {
+            metrics.graphExtraction.cacheHits += toFiniteNumber(telemetry.cacheHits);
+            metrics.graphExtraction.cacheMisses += toFiniteNumber(telemetry.cacheMisses);
+            metrics.graphExtraction.truncations += toFiniteNumber(telemetry.truncationCount);
+            metrics.graphExtraction.failures += toFiniteNumber(telemetry.failureCount);
+        }
+    }
+    metrics.graphExtraction.durationMs += toFiniteNumber(result.graphExtractionDurationMs);
+    return metrics;
+}
+/**
+ * Finalize derived flags and rates on an accumulator. Used both for the
+ * window-level aggregate and for each per-run row in --detail per-run mode
+ * so the single-row metrics still expose `ran` / `yieldRate` / `cacheHitRate`.
+ */
+function finalizeImproveMetrics(metrics) {
+    metrics.consolidation.ran =
+        metrics.consolidation.processed > 0 ||
+            metrics.consolidation.durationMs > 0 ||
+            metrics.consolidation.promoted > 0 ||
+            metrics.consolidation.merged > 0 ||
+            metrics.consolidation.deleted > 0 ||
+            metrics.consolidation.contradicted > 0 ||
+            metrics.consolidation.totalChunks > 0;
+    metrics.memoryInference.ran =
+        metrics.memoryInference.considered > 0 ||
+            metrics.memoryInference.written > 0 ||
+            metrics.memoryInference.durationMs > 0;
+    metrics.memoryInference.writes = metrics.memoryInference.written;
+    // Yield denominator excludes cache hits AND legacy (pre-cacheHits-field)
+    // envelopes. Only runs whose envelope carries a `cacheHits` field
+    // contribute to freshAttempts/yieldRate; legacy rows remain in
+    // `considered`/`written` for totals but are excluded from the rate so
+    // they cannot drag it down. See ImproveHealthMetrics.memoryInference
+    // jsdoc for the rationale.
+    metrics.memoryInference.freshAttempts = Math.max(0, metrics.memoryInference.yieldEligibleConsidered - metrics.memoryInference.cacheHits);
+    metrics.memoryInference.yieldRate =
+        metrics.memoryInference.freshAttempts > 0
+            ? roundRate(metrics.memoryInference.yieldEligibleWritten / metrics.memoryInference.freshAttempts)
+            : 0;
+    metrics.graphExtraction.ran =
+        metrics.graphExtraction.extractedFiles > 0 ||
+            metrics.graphExtraction.entities > 0 ||
+            metrics.graphExtraction.durationMs > 0;
+    const cacheTotal = metrics.graphExtraction.cacheHits + metrics.graphExtraction.cacheMisses;
+    metrics.graphExtraction.cacheHitRate = cacheTotal > 0 ? roundRate(metrics.graphExtraction.cacheHits / cacheTotal) : 0;
+}
+/**
+ * Merge per-row metrics from `src` into accumulator `dst`. All numeric fields
+ * are additive; cumulative rates are recomputed by finalizeImproveMetrics.
+ */
+function mergeImproveMetrics(dst, src) {
+    dst.plannedRefs += src.plannedRefs;
+    dst.profileFilteredRefs += src.profileFilteredRefs;
+    dst.actions.reflect.ok += src.actions.reflect.ok;
+    dst.actions.reflect.failed += src.actions.reflect.failed;
+    dst.actions.reflect.cooldown += src.actions.reflect.cooldown;
+    dst.actions.reflect.skipped += src.actions.reflect.skipped;
+    dst.actions.reflect.guardRejected += src.actions.reflect.guardRejected;
+    for (const [reason, count] of Object.entries(src.actions.reflect.skippedByReason)) {
+        dst.actions.reflect.skippedByReason[reason] = (dst.actions.reflect.skippedByReason[reason] ?? 0) + count;
+    }
+    dst.actions.distill.queued += src.actions.distill.queued;
+    dst.actions.distill.llmFailed += src.actions.distill.llmFailed;
+    dst.actions.distill.qualityRejected += src.actions.distill.qualityRejected;
+    dst.actions.distill.judgeRejected += src.actions.distill.judgeRejected;
+    dst.actions.distill.validatorRejected += src.actions.distill.validatorRejected;
+    dst.actions.distill.configDisabled += src.actions.distill.configDisabled;
+    dst.actions.distill.skipped += src.actions.distill.skipped;
+    for (const [reason, count] of Object.entries(src.actions.distill.skippedByReason)) {
+        dst.actions.distill.skippedByReason[reason] = (dst.actions.distill.skippedByReason[reason] ?? 0) + count;
+    }
+    dst.actions.distill.deferred += src.actions.distill.deferred;
+    for (const [reason, count] of Object.entries(src.actions.distill.deferredByReason)) {
+        dst.actions.distill.deferredByReason[reason] = (dst.actions.distill.deferredByReason[reason] ?? 0) + count;
+    }
+    dst.actions.memoryPrune += src.actions.memoryPrune;
+    dst.actions.memoryInference += src.actions.memoryInference;
+    dst.actions.graphExtraction += src.actions.graphExtraction;
+    dst.actions.error += src.actions.error;
+    dst.reflectsWithErrorContext += src.reflectsWithErrorContext;
+    dst.coverageGapCount += src.coverageGapCount;
+    dst.executionLogCandidateCount += src.executionLogCandidateCount;
+    dst.evalCasesWritten += src.evalCasesWritten;
+    dst.deadUrlCount += src.deadUrlCount;
+    dst.memorySummary.eligible += src.memorySummary.eligible;
+    dst.memorySummary.derived += src.memorySummary.derived;
+    dst.memoryCleanup.pruneCandidates += src.memoryCleanup.pruneCandidates;
+    dst.memoryCleanup.contradictionCandidates += src.memoryCleanup.contradictionCandidates;
+    dst.memoryCleanup.beliefStateTransitions += src.memoryCleanup.beliefStateTransitions;
+    dst.memoryCleanup.consolidationCandidates += src.memoryCleanup.consolidationCandidates;
+    dst.memoryCleanup.archived += src.memoryCleanup.archived;
+    dst.memoryCleanup.warnings += src.memoryCleanup.warnings;
+    dst.consolidation.processed += src.consolidation.processed;
+    dst.consolidation.promoted += src.consolidation.promoted;
+    dst.consolidation.merged += src.consolidation.merged;
+    dst.consolidation.deleted += src.consolidation.deleted;
+    dst.consolidation.contradicted += src.consolidation.contradicted;
+    dst.consolidation.failedChunks += src.consolidation.failedChunks;
+    dst.consolidation.totalChunks += src.consolidation.totalChunks;
+    dst.consolidation.durationMs += src.consolidation.durationMs;
+    dst.consolidation.judgedNoAction += src.consolidation.judgedNoAction;
+    dst.consolidation.mergedSecondaries += src.consolidation.mergedSecondaries;
+    dst.consolidation.failedChunkMemories += src.consolidation.failedChunkMemories;
+    for (const [reason, count] of Object.entries(src.consolidation.skipReasons)) {
+        dst.consolidation.skipReasons[reason] = (dst.consolidation.skipReasons[reason] ?? 0) + count;
+    }
+    dst.memoryInference.considered += src.memoryInference.considered;
+    dst.memoryInference.cacheHits += src.memoryInference.cacheHits;
+    dst.memoryInference.splitParents += src.memoryInference.splitParents;
+    dst.memoryInference.written += src.memoryInference.written;
+    dst.memoryInference.skippedNoFacts += src.memoryInference.skippedNoFacts;
+    dst.memoryInference.skippedChildExists += src.memoryInference.skippedChildExists;
+    dst.memoryInference.skippedAborted += src.memoryInference.skippedAborted;
+    dst.memoryInference.unaccounted += src.memoryInference.unaccounted;
+    dst.memoryInference.yieldEligibleRuns += src.memoryInference.yieldEligibleRuns;
+    dst.memoryInference.yieldEligibleConsidered += src.memoryInference.yieldEligibleConsidered;
+    dst.memoryInference.yieldEligibleWritten += src.memoryInference.yieldEligibleWritten;
+    dst.memoryInference.durationMs += src.memoryInference.durationMs;
+    dst.graphExtraction.extractedFiles += src.graphExtraction.extractedFiles;
+    dst.graphExtraction.entities += src.graphExtraction.entities;
+    dst.graphExtraction.relations += src.graphExtraction.relations;
+    dst.graphExtraction.cacheHits += src.graphExtraction.cacheHits;
+    dst.graphExtraction.cacheMisses += src.graphExtraction.cacheMisses;
+    dst.graphExtraction.truncations += src.graphExtraction.truncations;
+    dst.graphExtraction.failures += src.graphExtraction.failures;
+    dst.graphExtraction.durationMs += src.graphExtraction.durationMs;
+}
+function loadImproveRunRows(db, since, until) {
+    const sql = until
+        ? "SELECT id, started_at, completed_at, ok, scope_mode, scope_value, result_json FROM improve_runs WHERE started_at >= ? AND started_at < ? AND dry_run = 0 ORDER BY started_at DESC"
+        : "SELECT id, started_at, completed_at, ok, scope_mode, scope_value, result_json FROM improve_runs WHERE started_at >= ? AND dry_run = 0 ORDER BY started_at DESC";
+    return (until ? db.prepare(sql).all(since, until) : db.prepare(sql).all(since));
+}
+function summarizeImproveRuns(db, since, until) {
+    const accum = createUnknownImproveMetrics();
+    const rows = loadImproveRunRows(db, since, until);
+    // Per-phase wall-time samples. Each entry is one envelope's durationMs for
+    // that phase. Phases that did not run on a given envelope are simply
+    // omitted (NOT counted as 0) so the median/p95 reflect actual phase work.
+    const phaseDurations = {
+        consolidation: [],
+        memoryInference: [],
+        graphExtraction: [],
+    };
+    for (const row of rows) {
+        let result;
+        try {
+            result = JSON.parse(row.result_json);
+        }
+        catch {
+            continue;
+        }
+        const perRow = projectRunMetrics(result);
+        mergeImproveMetrics(accum, perRow);
+        // Collect per-phase durations directly off the envelope. consolidation's
+        // duration lives inside the sub-object; memoryInference and graphExtraction
+        // expose top-level *DurationMs keys (`memoryInferenceDurationMs`,
+        // `graphExtractionDurationMs`) when they actually ran on that envelope.
+        const consol = result.consolidation;
+        const consolMs = toFiniteNumber(consol?.durationMs);
+        if (consolMs > 0)
+            phaseDurations.consolidation.push(consolMs);
+        const memMs = toFiniteNumber(result.memoryInferenceDurationMs);
+        if (memMs > 0)
+            phaseDurations.memoryInference.push(memMs);
+        const graphMs = toFiniteNumber(result.graphExtractionDurationMs);
+        if (graphMs > 0)
+            phaseDurations.graphExtraction.push(graphMs);
+    }
+    finalizeImproveMetrics(accum);
+    accum.wallTime.byPhase = {
+        consolidation: summarizePhaseDurations(phaseDurations.consolidation),
+        memoryInference: summarizePhaseDurations(phaseDurations.memoryInference),
+        graphExtraction: summarizePhaseDurations(phaseDurations.graphExtraction),
+    };
+    return { metrics: accum, runCount: rows.length };
+}
+/**
+ * Aggregate a list of per-envelope phase durations into the
+ * `wallTime.byPhase.*` shape: count, total, median, p95. Median/p95 use the
+ * same nearest-rank picker as the top-level wallTime stats so the two are
+ * comparable.
+ */
+function summarizePhaseDurations(samples) {
+    if (samples.length === 0)
+        return { count: 0, totalMs: 0, medianMs: 0, p95Ms: 0 };
+    const sorted = [...samples].sort((a, b) => a - b);
+    const pick = (q) => sorted[Math.min(sorted.length - 1, Math.floor(q * sorted.length))] ?? 0;
+    const totalMs = sorted.reduce((acc, n) => acc + n, 0);
+    return {
+        count: sorted.length,
+        totalMs,
+        medianMs: pick(0.5),
+        p95Ms: pick(0.95),
+    };
+}
+/**
+ * Project an improve_runs row + wall-time lookup into a single ImproveRunSummary.
+ * Used by `akm health --detail per-run`.
+ */
+function projectImproveRunSummary(row, wallTimeMs) {
+    let result = {};
+    try {
+        result = JSON.parse(row.result_json);
+    }
+    catch {
+        // fall through with empty result so per-stage rollups are zeros
+    }
+    const perRow = projectRunMetrics(result);
+    finalizeImproveMetrics(perRow);
+    const orphansPurged = toFiniteNumber(result.orphansPurged);
+    const lintSummary = result.lintSummary;
+    const lintFixed = lintSummary ? toFiniteNumber(lintSummary.fixed) : 0;
+    const lintFlagged = lintSummary ? toFiniteNumber(lintSummary.flagged) : 0;
+    return {
+        id: row.id,
+        startedAt: row.started_at,
+        completedAt: row.completed_at,
+        wallTimeMs,
+        ok: row.ok === 1,
+        scope: {
+            mode: row.scope_mode,
+            ...(row.scope_value ? { value: row.scope_value } : {}),
+        },
+        actions: perRow.actions,
+        memorySummary: perRow.memorySummary,
+        memoryCleanup: perRow.memoryCleanup,
+        consolidation: perRow.consolidation,
+        memoryInference: perRow.memoryInference,
+        graphExtraction: perRow.graphExtraction,
+        reflectsWithErrorContext: perRow.reflectsWithErrorContext,
+        evalCasesWritten: perRow.evalCasesWritten,
+        orphansPurged,
+        lintFixed,
+        lintFlagged,
+    };
+}
+/**
+ * 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 sql = widenedUntil
+        ? "SELECT started_at, completed_at FROM task_history WHERE task_id = 'akm-improve' AND started_at >= ? AND started_at < ? AND completed_at IS NOT NULL ORDER BY started_at"
+        : "SELECT started_at, completed_at FROM task_history WHERE task_id = 'akm-improve' AND started_at >= ? AND completed_at IS NOT NULL ORDER BY started_at";
+    const rows = (widenedUntil ? db.prepare(sql).all(widenedSince, widenedUntil) : db.prepare(sql).all(widenedSince));
+    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;
+}
+function buildPerRunSummaries(db, since, until) {
+    const rows = loadImproveRunRows(db, since, until);
+    const taskIntervals = loadTaskIntervals(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 task_history interval (which has distinct start/end timestamps).
+        // Fall back to the improve_runs row's own delta (usually 0 because
+        // recordImproveRun writes started_at == completed_at == end-of-run timestamp).
+        const fallbackWallMs = Number.isFinite(startMs) && Number.isFinite(endMs) && endMs >= startMs ? endMs - startMs : 0;
+        const interval = Number.isFinite(startMs) ? findContainingTaskInterval(startMs, taskIntervals) : undefined;
+        const wallTimeMs = interval?.durationMs ?? fallbackWallMs;
+        summaries.push(projectImproveRunSummary(row, wallTimeMs));
+    }
+    return summaries;
+}
+function emptyPhaseStats() {
+    return {
+        consolidation: { count: 0, totalMs: 0, medianMs: 0, p95Ms: 0 },
+        memoryInference: { count: 0, totalMs: 0, medianMs: 0, p95Ms: 0 },
+        graphExtraction: { count: 0, totalMs: 0, medianMs: 0, p95Ms: 0 },
+    };
+}
+function computeWallTimeStats(durationsMs, byPhase) {
+    const phase = byPhase ?? emptyPhaseStats();
+    if (durationsMs.length === 0)
+        return { count: 0, medianMs: 0, p95Ms: 0, minMs: 0, maxMs: 0, byPhase: phase };
+    const sorted = [...durationsMs].sort((a, b) => a - b);
+    const pick = (q) => sorted[Math.min(sorted.length - 1, Math.floor(q * sorted.length))] ?? 0;
+    return {
+        count: sorted.length,
+        medianMs: pick(0.5),
+        p95Ms: pick(0.95),
+        minMs: sorted[0] ?? 0,
+        maxMs: sorted[sorted.length - 1] ?? 0,
+        byPhase: phase,
+    };
+}
 function buildImproveSkipSummary(events) {
     const skipReasons = {};
     for (const event of events) {
@@ -148,7 +727,31 @@ function probeStateDbRoundTrip(stateDbPath) {
 }
 function runAgentProbe() {
     const config = loadConfig();
-    if (!config.agent) {
+    // v2: check profiles.agent first
+    if (config.profiles?.agent) {
+        const defaultName = config.defaults?.agent;
+        const profileCount = Object.keys(config.profiles.agent).length;
+        if (profileCount === 0) {
+            return {
+                name: "agent-profile",
+                kind: "deterministic",
+                status: "unknown",
+                confidence: "high",
+                message: "No agent profiles configured in profiles.agent.",
+            };
+        }
+        const profileName = defaultName ?? Object.keys(config.profiles.agent)[0];
+        const profile = config.profiles.agent[profileName];
+        return {
+            name: "agent-profile",
+            kind: "deterministic",
+            status: "pass",
+            confidence: "high",
+            message: `v2 agent profile "${profileName}" configured (platform: ${profile?.platform ?? "unknown"}).`,
+            evidence: { profile: profileName, platform: profile?.platform, profileCount },
+        };
+    }
+    if (!config.profiles?.agent && !config.defaults?.agent) {
         return {
             name: "agent-profile",
             kind: "deterministic",
@@ -159,7 +762,7 @@ function runAgentProbe() {
     }
     let profile;
     try {
-        profile = requireAgentProfile(config.agent);
+        profile = requireAgentProfile(config);
     }
     catch (error) {
         return {
@@ -182,7 +785,7 @@ function runAgentProbe() {
             evidence: { profile: profile.name, sdkMode: true, model: profile.model ?? null },
         };
     }
-    const detections = detectAgentCliProfiles(config.agent);
+    const detections = detectAgentCliProfiles(config);
     const detection = detections.find((entry) => entry.name === profile.name);
     if (!detection?.available) {
         return {
@@ -219,7 +822,173 @@ function runAgentProbe() {
         evidence: { profile: profile.name, bin: profile.bin, version: (version.stdout ?? "").trim() },
     };
 }
+/**
+ * Parse a `--window-compare <duration>` shorthand into two adjacent windows
+ * (current, prior). Duration syntax matches {@link parseHealthSince}.
+ */
+function resolveWindowCompare(duration) {
+    const trimmed = duration.trim();
+    const durationMatch = trimmed.match(/^(\d+)([dhm])$/i);
+    if (!durationMatch) {
+        throw new UsageError("--window-compare must be a duration like '24h', '7d', or '30m'.", "INVALID_FLAG_VALUE");
+    }
+    const amount = Number.parseInt(durationMatch[1] ?? "0", 10);
+    const unit = (durationMatch[2] ?? "h").toLowerCase();
+    if (!Number.isFinite(amount) || amount <= 0) {
+        throw new UsageError("--window-compare must be a positive duration.", "INVALID_FLAG_VALUE");
+    }
+    const multiplier = unit === "h" ? 60 * 60 * 1000 : unit === "m" ? 60 * 1000 : 24 * 60 * 60 * 1000;
+    const ms = amount * multiplier;
+    const now = Date.now();
+    const currentSince = new Date(now - ms).toISOString();
+    const currentUntil = new Date(now).toISOString();
+    const priorSince = new Date(now - 2 * ms).toISOString();
+    const priorUntil = currentSince;
+    return [
+        { name: "current", since: currentSince, until: currentUntil },
+        { name: "prior", since: priorSince, until: priorUntil },
+    ];
+}
+/**
+ * Parse a single repeatable `--windows` value of the form
+ * `name=...,since=...,until=...`. All keys are optional EXCEPT name and since.
+ */
+export function parseWindowSpec(raw) {
+    const fields = {};
+    for (const part of raw.split(",")) {
+        const trimmed = part.trim();
+        if (!trimmed)
+            continue;
+        const eq = trimmed.indexOf("=");
+        if (eq < 0) {
+            throw new UsageError(`--windows entry must be a comma-separated list of key=value pairs: ${raw}`, "INVALID_FLAG_VALUE");
+        }
+        const key = trimmed.slice(0, eq).trim();
+        const value = trimmed.slice(eq + 1).trim();
+        fields[key] = value;
+    }
+    if (!fields.name) {
+        throw new UsageError(`--windows entry is missing required 'name': ${raw}`, "INVALID_FLAG_VALUE");
+    }
+    if (!fields.since) {
+        throw new UsageError(`--windows entry is missing required 'since': ${raw}`, "INVALID_FLAG_VALUE");
+    }
+    return {
+        name: fields.name,
+        since: fields.since,
+        ...(fields.until ? { until: fields.until } : {}),
+    };
+}
+/** Hard-coded list of "interesting" metric paths for window-compare deltas. */
+const INTERESTING_DELTA_PATHS = [
+    "improve.actions.reflect.failed",
+    "improve.actions.reflect.guardRejected",
+    "improve.actions.distill.llmFailed",
+    "improve.actions.distill.queued",
+    "improve.actions.distill.deferred",
+    "improve.consolidation.promoted",
+    "improve.memoryInference.written",
+    "improve.memoryInference.yieldRate",
+    "improve.memoryInference.skippedNoFacts",
+    "improve.graphExtraction.cacheHitRate",
+    "improve.graphExtraction.failures",
+    "improve.wallTime.medianMs",
+    "improve.wallTime.p95Ms",
+];
+function readNumericPath(obj, path) {
+    const parts = path.split(".");
+    let cursor = obj;
+    for (const part of parts) {
+        if (typeof cursor !== "object" || cursor === null)
+            return 0;
+        cursor = cursor[part];
+    }
+    return typeof cursor === "number" && Number.isFinite(cursor) ? cursor : 0;
+}
+function computeDeltas(first, last) {
+    const out = {};
+    for (const path of INTERESTING_DELTA_PATHS) {
+        const from = readNumericPath(first, path);
+        const to = readNumericPath(last, path);
+        if (from === 0 && to === 0)
+            continue;
+        let pctChange;
+        if (from === 0) {
+            pctChange = to === 0 ? 0 : "+inf";
+        }
+        else {
+            pctChange = Number((((to - from) / from) * 100).toFixed(2));
+        }
+        out[path] = { from, to, pctChange };
+    }
+    return out;
+}
+function buildWindowMetrics(db, stateDbPath, since, until) {
+    const taskRows = queryTaskHistory(db, { since }).filter((row) => {
+        const startMs = new Date(row.started_at).getTime();
+        const untilMs = new Date(until).getTime();
+        return !Number.isFinite(untilMs) || startMs < untilMs;
+    });
+    const taskRowsWithLogs = taskRows.filter((row) => row.log_path !== null);
+    const existingLogRows = taskRowsWithLogs.filter((row) => row.log_path && fs.existsSync(row.log_path));
+    const failedTaskRows = taskRows.filter((row) => row.status === "failed");
+    const activeRows = taskRows.filter((row) => row.status === "active");
+    const stuckActiveRuns = activeRows.filter((row) => Date.now() - new Date(row.started_at).getTime() > ACTIVE_RUN_WARN_MS).length;
+    const promptRows = taskRows.filter((row) => row.target_kind === "prompt");
+    const promptFailures = promptRows.filter((row) => {
+        const detail = parseTaskMetadata(row).detail;
+        return typeof detail?.reason === "string" && detail.reason.length > 0;
+    });
+    const logBackingRate = taskRowsWithLogs.length === 0 ? 1 : existingLogRows.length / taskRowsWithLogs.length;
+    const taskFailRate = taskRows.length === 0 ? 0 : failedTaskRows.length / taskRows.length;
+    const agentFailureRate = promptRows.length === 0 ? 0 : promptFailures.length / promptRows.length;
+    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());
+    const eventsMetrics = summarizeImproveCompleted(improveCompletedEvents);
+    const { metrics: improveSummary, runCount } = summarizeImproveRuns(db, since, until);
+    improveSummary.invoked = improveInvoked;
+    improveSummary.completed = eventsMetrics.completed;
+    const skipSummary = buildImproveSkipSummary(improveSkippedEvents);
+    improveSummary.skipped = skipSummary.skipped;
+    improveSummary.skipReasons = skipSummary.skipReasons;
+    // Preserve the per-phase aggregation computed by summarizeImproveRuns and
+    // derive top-level wall times from the same improve-runs window so counts
+    // and percentiles stay aligned with per-run reporting.
+    const perRunSummaries = buildPerRunSummaries(db, since, until);
+    const wallTimes = perRunSummaries.map((run) => run.wallTimeMs).filter((ms) => Number.isFinite(ms) && ms > 0);
+    improveSummary.wallTime = computeWallTimeStats(wallTimes, improveSummary.wallTime.byPhase);
+    const metrics = {
+        taskFailRate: roundRate(taskFailRate),
+        agentFailureRate: roundRate(agentFailureRate),
+        stuckActiveRuns,
+        logBackingRate: roundRate(logBackingRate),
+        probeRoundTripMs: null,
+    };
+    return { improve: improveSummary, metrics, runs: runCount };
+}
+function validateAkmHealthOptions(options) {
+    if (options.groupBy !== undefined && options.groupBy !== "run") {
+        throw new UsageError(`Invalid value for --group-by: ${options.groupBy}. Expected: run`, "INVALID_FLAG_VALUE");
+    }
+    if (options.windowCompare !== undefined && options.windows !== undefined && options.windows.length > 0) {
+        throw new UsageError("--window-compare and --windows are mutually exclusive.", "INVALID_FLAG_VALUE");
+    }
+    if (options.windows) {
+        if (options.windows.length > 4) {
+            throw new UsageError("--windows accepts at most 4 entries.", "INVALID_FLAG_VALUE");
+        }
+        const seen = new Set();
+        for (const spec of options.windows) {
+            if (seen.has(spec.name)) {
+                throw new UsageError(`--windows has duplicate name: ${spec.name}`, "INVALID_FLAG_VALUE");
+            }
+            seen.add(spec.name);
+        }
+    }
+}
 export function akmHealth(options = {}) {
+    validateAkmHealthOptions(options);
     const since = parseHealthSince(options.since);
     const stateDbPath = getStateDbPathInDataDir();
     const hardChecks = [];
@@ -320,11 +1089,16 @@ export function akmHealth(options = {}) {
         const improveInvoked = readEvents({ since, type: "improve_invoked" }, { dbPath: stateDbPath }).events.length;
         const improveCompletedEvents = readEvents({ since, type: IMPROVE_COMPLETED_EVENT }, { dbPath: stateDbPath }).events;
         const improveSkippedEvents = readEvents({ since, type: "improve_skipped" }, { dbPath: stateDbPath }).events;
-        const improveSummary = summarizeImproveCompleted(improveCompletedEvents);
+        const eventsMetrics = summarizeImproveCompleted(improveCompletedEvents);
+        const { metrics: improveSummary } = summarizeImproveRuns(db, since);
         improveSummary.invoked = improveInvoked;
+        improveSummary.completed = eventsMetrics.completed;
         const skipSummary = buildImproveSkipSummary(improveSkippedEvents);
         improveSummary.skipped = skipSummary.skipped;
         improveSummary.skipReasons = skipSummary.skipReasons;
+        const perRunSummaries = buildPerRunSummaries(db, since);
+        const wallTimes = perRunSummaries.map((run) => run.wallTimeMs).filter((ms) => Number.isFinite(ms) && ms > 0);
+        improveSummary.wallTime = computeWallTimeStats(wallTimes, improveSummary.wallTime.byPhase);
         let sessionLogEntries = [];
         try {
             const sinceDays = Math.max(0, Math.ceil((Date.now() - new Date(since).getTime()) / (24 * 60 * 60 * 1000)));
@@ -358,19 +1132,171 @@ export function akmHealth(options = {}) {
         const hardFailure = hardChecks.some((check) => check.status === "fail");
         const deterministicWarnings = [...hardChecks, ...advisories].some((check) => check.status === "warn" && check.kind === "deterministic");
         const status = hardFailure ? "fail" : deterministicWarnings ? "warn" : "pass";
+        // ── Window-compare mode (Phase 3) ─────────────────────────────────────
+        let windowSpecs;
+        if (options.windowCompare) {
+            windowSpecs = resolveWindowCompare(options.windowCompare);
+        }
+        else if (options.windows && options.windows.length > 0) {
+            windowSpecs = options.windows;
+        }
+        let windowResults;
+        let deltas;
+        let topLevelImprove = improveSummary;
+        let topLevelMetrics = metrics;
+        let topLevelSince = since;
+        if (windowSpecs && db) {
+            windowResults = windowSpecs.map((spec) => {
+                const winSince = parseHealthSince(spec.since);
+                const winUntil = spec.until ? parseHealthSince(spec.until) : new Date().toISOString();
+                const bundle = buildWindowMetrics(db, stateDbPath, winSince, winUntil);
+                return {
+                    name: spec.name,
+                    since: winSince,
+                    until: winUntil,
+                    runs: bundle.runs,
+                    improve: bundle.improve,
+                    metrics: bundle.metrics,
+                };
+            });
+            // Preserve backward compat: top-level improve/metrics reflect window 0.
+            if (windowResults.length > 0) {
+                topLevelImprove = windowResults[0].improve;
+                topLevelMetrics = { ...windowResults[0].metrics, probeRoundTripMs: probe.durationMs };
+                topLevelSince = windowResults[0].since;
+            }
+            if (windowResults.length >= 2) {
+                // Deltas always read chronologically: `from` = earliest window,
+                // `to` = latest. Positive pctChange on a failure metric (e.g.
+                // distill.llmFailed) means things got WORSE going forward in
+                // time; negative means improvement. Window 0 in the output
+                // array is whatever the user specified first (typically
+                // `current` for --window-compare), but the delta direction is
+                // independent of that array order.
+                const sorted = [...windowResults].sort((a, b) => new Date(a.since).getTime() - new Date(b.since).getTime());
+                deltas = computeDeltas(sorted[0], sorted[sorted.length - 1]);
+            }
+        }
+        // ── Per-run mode (Phase 2) ────────────────────────────────────────────
+        let runs;
+        if (options.groupBy === "run") {
+            runs = buildPerRunSummaries(db, since);
+        }
         return {
-            schemaVersion: 1,
+            schemaVersion: 2,
             ok: !hardFailure,
             status,
-            since,
+            since: topLevelSince,
             hardChecks,
             advisories,
-            metrics,
-            improve: improveSummary,
+            metrics: topLevelMetrics,
+            improve: topLevelImprove,
             sessionLogAdvisories: sessionLogEntries,
+            ...(runs ? { runs } : {}),
+            ...(windowResults ? { windows: windowResults } : {}),
+            ...(deltas ? { deltas } : {}),
         };
     }
     finally {
         db.close();
     }
 }
+// ── Markdown renderers ───────────────────────────────────────────────────────
+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.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);
+}