akm-cli 0.9.0-rc.0 → 0.9.0-rc.13

package/dist/commands/health.js

@@ -7,8 +7,9 @@ import { resolveStashDir } from "../core/common.js";
 import { loadConfig } from "../core/config/config.js";
 import { ConfigError, UsageError } from "../core/errors.js";
 import { readEvents } from "../core/events.js";
+import { listTxnJournalsTolerant, TXN_SWEEP_GRACE_MS } from "../core/fs-txn.js";
 import { openLogsDatabase } from "../core/logs-db.js";
-import { getCacheDir, getConfigDir, getConfigPath, getDataDir, getStateDbPathInDataDir } from "../core/paths.js";
+import { getCacheDir, getConfigPath, getDataDir, getStateDbPathInDataDir } from "../core/paths.js";
 import { listExistingTableNames, openStateDatabase } from "../core/state-db.js";
 import { DURATION_UNITS, parseDuration, parseSinceToIso } from "../core/time.js";
 import { readSemanticStatus } from "../indexer/search/semantic-status.js";
@@ -18,11 +19,11 @@ import { collectImproveAdvisories } from "./health/advisories.js";
 import { HEALTH_CHECKS } from "./health/checks.js";
 import { buildImproveSkipSummary, computeWallTimeStats, parseTaskMetadata, roundRate, summarizeImproveCompleted, summarizeImproveRuns, } from "./health/improve-metrics.js";
 import { readLlmUsageAggregate } from "./health/llm-usage.js";
-import { computeDegradationMetrics, computeDenominatorFixedCoverage, computeEnrichmentMintingRollup, probeStateDbRoundTrip, readCalibration, } from "./health/metrics.js";
+import { computeDegradationMetrics, computeDenominatorFixedCoverage, computeEnrichmentMintingRollup, probeStateDbRoundTrip, } from "./health/metrics.js";
 import { collectStashExposureAdvisory } from "./health/stash-exposure.js";
 import { collectSurfacesAdvisories } from "./health/surfaces.js";
 import { buildPerRunSummaries } from "./health/task-runs.js";
-import { ACTIVE_RUN_WARN_MS, IMPROVE_COMPLETED_EVENT, } from "./health/types.js";
+import { ACTIVE_RUN_WARN_MS, IMPROVE_COMPLETED_EVENT, MIN_ROWS_FOR_WORST_TASK_FAIL_RATE, } from "./health/types.js";
 import { buildWindowMetrics, computeDeltas, partitionLogBackedRows, resolveWindowCompare } from "./health/windows.js";
 const DEFAULT_SINCE_MS = 24 * 60 * 60 * 1000;
 export function parseHealthSince(since) {
@@ -60,6 +61,273 @@ function validateAkmHealthOptions(options) {
         }
     }
 }
+/**
+ * Item 7: dedupe stuck-active rows by task_id (keeping the oldest/largest age
+ * per id) so the `active-runs` check can name WHICH tasks are stuck instead of
+ * just a count. No pid/liveness probing — purely a projection of the rows
+ * already read.
+ */
+function dedupeStuckActiveTasks(rows, now) {
+    const byTask = new Map();
+    for (const row of rows) {
+        const ageMs = now() - new Date(row.started_at).getTime();
+        const existing = byTask.get(row.task_id);
+        if (existing === undefined || ageMs > existing)
+            byTask.set(row.task_id, ageMs);
+    }
+    return [...byTask.entries()].map(([taskId, ageMs]) => ({ taskId, ageMs }));
+}
+/**
+ * Item 6: group task_history rows by task_id and return the one with the
+ * highest fail rate among tasks with at least MIN_ROWS_FOR_WORST_TASK_FAIL_RATE
+ * rows in the window — surfaces a consistently-failing task that a large,
+ * mostly-healthy population would otherwise hide behind the aggregate rate.
+ * `null` when no task_id meets the row-count floor. Ties break toward the
+ * task with more rows (a stronger signal), then by task_id for determinism.
+ */
+function computeWorstTaskFailRate(rows) {
+    const byTask = new Map();
+    for (const row of rows) {
+        const entry = byTask.get(row.task_id) ?? { total: 0, failed: 0 };
+        entry.total += 1;
+        if (row.status === "failed")
+            entry.failed += 1;
+        byTask.set(row.task_id, entry);
+    }
+    let worst = null;
+    for (const [taskId, { total, failed }] of byTask) {
+        if (total < MIN_ROWS_FOR_WORST_TASK_FAIL_RATE)
+            continue;
+        const rate = failed / total;
+        if (worst === null ||
+            rate > worst.rate ||
+            (rate === worst.rate && (total > worst.rows || (total === worst.rows && taskId < worst.taskId)))) {
+            worst = { taskId, rate, rows: total };
+        }
+    }
+    return worst;
+}
+/** Table presence, the state.db round-trip probe, and task_history-derived rates. */
+function gatherTaskHistoryPhase(db, logsDb, since, stateDbPath, now) {
+    const tables = listExistingTableNames(db, ["events", "task_history", "proposals", "schema_migrations"]);
+    const tableNames = tables.map((row) => row.name).sort();
+    const requiredTables = ["events", "proposals", "schema_migrations", "task_history"];
+    const missingTables = requiredTables.filter((name) => !tableNames.includes(name));
+    const probe = probeStateDbRoundTrip(stateDbPath);
+    const taskRows = queryTaskHistory(db, { since });
+    const { withLogs: taskRowsWithLogs, backed: existingLogRows } = partitionLogBackedRows(taskRows, logsDb);
+    const failedTaskRows = taskRows.filter((row) => row.status === "failed");
+    const activeRows = taskRows.filter((row) => row.status === "active" && row.completed_at === null);
+    const stuckActiveRows = activeRows.filter((row) => now() - new Date(row.started_at).getTime() > ACTIVE_RUN_WARN_MS);
+    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;
+    return {
+        tableNames,
+        missingTables,
+        probe,
+        taskRowCount: taskRows.length,
+        taskRowsWithLogsCount: taskRowsWithLogs.length,
+        existingLogRowsCount: existingLogRows.length,
+        stuckActiveRuns: stuckActiveRows.length,
+        stuckActiveTasks: dedupeStuckActiveTasks(stuckActiveRows, now),
+        logBackingRate,
+        taskFailRate,
+        worstTaskFailRate: computeWorstTaskFailRate(taskRows),
+        agentFailureRate,
+    };
+}
+/**
+ * Item 4: leftover durable-transaction journals under `$DATA/txn` (stranded
+ * recovery state seen twice in a real 0.9 migration) had zero health
+ * visibility. Uses the tolerant scan variant so one corrupt journal.json is
+ * counted rather than aborting the whole gather; a journal younger than
+ * {@link TXN_SWEEP_GRACE_MS} is presumed to belong to a currently-running
+ * operation and is not counted as stale. Best-effort: any unexpected error
+ * (e.g. a permissions issue under `$DATA/txn`) degrades to "no signal" rather
+ * than aborting the health report.
+ */
+function gatherStaleTxnJournalsPhase(now) {
+    const dir = path.join(getDataDir(), "txn");
+    try {
+        const { matches, unreadableMtimes } = listTxnJournalsTolerant(() => true);
+        const nowMs = now();
+        const staleAges = [
+            ...matches.map((m) => nowMs - m.mtimeMs),
+            ...unreadableMtimes.map((mtimeMs) => nowMs - mtimeMs),
+        ].filter((ageMs) => ageMs >= TXN_SWEEP_GRACE_MS);
+        const staleUnreadableCount = unreadableMtimes.filter((mtimeMs) => nowMs - mtimeMs >= TXN_SWEEP_GRACE_MS).length;
+        return {
+            dir,
+            count: staleAges.length,
+            oldestAgeMs: staleAges.length > 0 ? Math.max(...staleAges) : null,
+            unreadable: staleUnreadableCount,
+        };
+    }
+    catch {
+        return { dir, count: 0, oldestAgeMs: null, unreadable: 0 };
+    }
+}
+/**
+ * Semantic-search status + the config fields the embedding-endpoint and
+ * surfaces advisories need. Best-effort: an unloadable config leaves the
+ * config-derived fields undefined and callers fall back to generic messages.
+ */
+function gatherSemanticConfigPhase() {
+    const semanticStatus = readSemanticStatus();
+    let semanticSearchMode;
+    let embeddingEndpoint;
+    let egressConfigView;
+    try {
+        const config = loadConfig();
+        semanticSearchMode = config.semanticSearchMode;
+        embeddingEndpoint = config.embedding?.endpoint;
+        egressConfigView = config;
+    }
+    catch {
+        // fall through with undefined
+    }
+    return { semanticStatus, semanticSearchMode, embeddingEndpoint, egressConfigView };
+}
+/**
+ * Assemble the window's improve-pipeline summary: invoked/completed/skipped
+ * counts from events, the per-run result_json aggregate, wall-time stats, and
+ * the WS-5 coverage/degradation/enrichment-minting rollups.
+ */
+function gatherImproveSummaryPhase(db, stateDbPath, since, now) {
+    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 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);
+    // WS-5: Compute denominator-fixed coverage and per-run degradation metrics
+    // for the main health path (not just window-compare mode).
+    const until = new Date(now()).toISOString();
+    const totalAssetsMain = improveSummary.memorySummary.eligible + improveSummary.memorySummary.derived;
+    improveSummary.coverage = computeDenominatorFixedCoverage(db, totalAssetsMain, improveSummary.memorySummary.eligible, since, until);
+    const degradationMain = computeDegradationMetrics(db, since, until);
+    if (degradationMain) {
+        improveSummary.degradation = degradationMain;
+    }
+    improveSummary.enrichmentMinting = computeEnrichmentMintingRollup(db, since, until);
+    return { improveSummary, perRunSummaries };
+}
+/**
+ * The three best-effort advisory groups beyond the health-check registry:
+ * improve advisories, the `stash-git-exposure` probe, and the 08 surfaces
+ * group (secret-file-perms, binary-config-skew, egress-endpoints). Order
+ * matches emission order in the returned array. A
+ * probe/filesystem failure in either try/catch must not abort the health
+ * report — each group degrades to "no advisory" independently.
+ */
+function gatherAncillaryAdvisories(db, stateDbPath, since, improveSummary, options, egressConfigView) {
+    const advisories = [...collectImproveAdvisories(db, stateDbPath, since, improveSummary)];
+    // 08-F1: surface a `stash-git-exposure` advisory when env/secret assets are
+    // git-tracked AND a remote is configured (the leak moment). Best-effort.
+    // Cheap guard: only shell out to git when the stash has its OWN `.git` (or a
+    // test injected a fake seam), so the hot path never spawns for a non-git
+    // stash — the common unit-test case. Trade-off: a stash manually pointed at a
+    // bare subdirectory of a parent git repo (no `.git` of its own) is not
+    // checked. akm-init always creates `.git` at the stash root, so any
+    // akm-initialised stash is covered; this only skips hand-pointed nested ones.
+    try {
+        const exposureStashDir = options.stashDir ?? resolveStashDir();
+        if (options.stashExposureGit || fs.existsSync(path.join(exposureStashDir, ".git"))) {
+            const stashExposure = collectStashExposureAdvisory(exposureStashDir, options.stashExposureGit);
+            if (stashExposure)
+                advisories.push(stashExposure);
+        }
+    }
+    catch {
+        // Non-fatal — a git/probe failure must not abort the health report.
+    }
+    // 08 surfaces: the remaining read-only advisory group (secret-file-perms,
+    // binary-config-skew, egress-endpoints). Best-effort — a
+    // filesystem probe failure must not abort the health report.
+    try {
+        advisories.push(...collectSurfacesAdvisories({
+            stashDir: options.stashDir ?? resolveStashDir(),
+            cacheDir: getCacheDir(),
+            configPath: getConfigPath(),
+            config: egressConfigView,
+        }));
+    }
+    catch {
+        // Non-fatal.
+    }
+    return advisories;
+}
+/** Execution-log-derived session advisories. Best-effort: any failure yields an empty list. */
+function gatherSessionLogAdvisories(since, now, getExecutionLogCandidatesFn) {
+    try {
+        const sinceDays = Math.max(0, Math.ceil((now() - new Date(since).getTime()) / (24 * 60 * 60 * 1000)));
+        return getExecutionLogCandidatesFn(sinceDays).map((entry) => ({
+            topic: entry.topic,
+            frequency: entry.frequency,
+            source: entry.source,
+            isFailurePattern: entry.isFailurePattern,
+        }));
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Phase 3 — window-compare mode. Resolves `--window-compare`/`--windows` into
+ * per-window bundles and computes deltas between the earliest and latest
+ * window. Top-level metrics retain the primary `--since` query.
+ */
+function resolveWindowComparePhase(options, db, stateDbPath, now, logsDb) {
+    let windowSpecs;
+    if (options.windowCompare) {
+        windowSpecs = resolveWindowCompare(options.windowCompare, now);
+    }
+    else if (options.windows && options.windows.length > 0) {
+        windowSpecs = options.windows;
+    }
+    let windowResults;
+    let deltas;
+    if (windowSpecs) {
+        windowResults = windowSpecs.map((spec) => {
+            const winSince = parseHealthSince(spec.since);
+            const winUntil = spec.until ? parseHealthSince(spec.until) : new Date(now()).toISOString();
+            const bundle = buildWindowMetrics(db, stateDbPath, winSince, winUntil, now, logsDb);
+            return {
+                name: spec.name,
+                since: winSince,
+                until: winUntil,
+                runs: bundle.runs,
+                improve: bundle.improve,
+                metrics: bundle.metrics,
+            };
+        });
+        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]);
+        }
+    }
+    return { windowResults, deltas };
+}
 export function akmHealth(options = {}) {
     validateAkmHealthOptions(options);
     const now = options.now ?? (() => Date.now());
@@ -86,112 +354,13 @@ export function akmHealth(options = {}) {
         logsDb = undefined;
     }
     try {
-        const tables = listExistingTableNames(db, ["events", "task_history", "proposals", "schema_migrations"]);
-        const tableNames = tables.map((row) => row.name).sort();
-        const requiredTables = ["events", "proposals", "schema_migrations", "task_history"];
-        const missingTables = requiredTables.filter((name) => !tableNames.includes(name));
-        const probe = probeStateDbRoundTrip(stateDbPath);
-        const taskRows = queryTaskHistory(db, { since });
-        const { withLogs: taskRowsWithLogs, backed: existingLogRows } = partitionLogBackedRows(taskRows, logsDb);
-        const failedTaskRows = taskRows.filter((row) => row.status === "failed");
-        const activeRows = taskRows.filter((row) => row.status === "active");
-        const stuckActiveRuns = activeRows.filter((row) => 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 semanticStatus = readSemanticStatus();
-        // For the embedding-endpoint advisory. Best-effort: an unloadable config
-        // leaves both undefined and the check falls back to its generic message.
-        let semanticSearchMode;
-        let embeddingEndpoint;
-        let egressConfigView;
-        try {
-            const config = loadConfig();
-            semanticSearchMode = config.semanticSearchMode;
-            embeddingEndpoint = config.embedding?.endpoint;
-            egressConfigView = config;
-        }
-        catch {
-            // fall through with undefined
-        }
-        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 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);
-        improveSummary.calibration = readCalibration(db, since);
-        // WS-5: Compute denominator-fixed coverage and per-run degradation metrics
-        // for the main health path (not just window-compare mode).
-        const until = new Date(now()).toISOString();
-        const totalAssetsMain = improveSummary.memorySummary.eligible + improveSummary.memorySummary.derived;
-        improveSummary.coverage = computeDenominatorFixedCoverage(db, totalAssetsMain, improveSummary.memorySummary.eligible, since, until);
-        const degradationMain = computeDegradationMetrics(db, since, until);
-        if (degradationMain) {
-            improveSummary.degradation = degradationMain;
-        }
-        improveSummary.enrichmentMinting = computeEnrichmentMintingRollup(db, since, until);
-        advisories.push(...collectImproveAdvisories(db, stateDbPath, since, improveSummary));
-        // 08-F1: surface a `stash-git-exposure` advisory when env/secret assets are
-        // git-tracked AND a remote is configured (the leak moment). Best-effort.
-        // Cheap guard: only shell out to git when the stash has its OWN `.git` (or a
-        // test injected a fake seam), so the hot path never spawns for a non-git
-        // stash — the common unit-test case. Trade-off: a stash manually pointed at a
-        // bare subdirectory of a parent git repo (no `.git` of its own) is not
-        // checked. akm-init always creates `.git` at the stash root, so any
-        // akm-initialised stash is covered; this only skips hand-pointed nested ones.
-        try {
-            const exposureStashDir = options.stashDir ?? resolveStashDir();
-            if (options.stashExposureGit || fs.existsSync(path.join(exposureStashDir, ".git"))) {
-                const stashExposure = collectStashExposureAdvisory(exposureStashDir, options.stashExposureGit);
-                if (stashExposure)
-                    advisories.push(stashExposure);
-            }
-        }
-        catch {
-            // Non-fatal — a git/probe failure must not abort the health report.
-        }
-        // 08 surfaces: the remaining read-only advisory group (secret-file-perms,
-        // binary-config-skew, orphan-stores, egress-endpoints). Best-effort — a
-        // filesystem probe failure must not abort the health report.
-        try {
-            advisories.push(...collectSurfacesAdvisories({
-                stashDir: options.stashDir ?? resolveStashDir(),
-                cacheDir: getCacheDir(),
-                dataDir: getDataDir(),
-                configDir: getConfigDir(),
-                configPath: getConfigPath(),
-                config: egressConfigView,
-            }));
-        }
-        catch {
-            // Non-fatal.
-        }
-        let sessionLogEntries = [];
-        try {
-            const sinceDays = Math.max(0, Math.ceil((now() - new Date(since).getTime()) / (24 * 60 * 60 * 1000)));
-            sessionLogEntries = getExecutionLogCandidatesFn(sinceDays).map((entry) => ({
-                topic: entry.topic,
-                frequency: entry.frequency,
-                source: entry.source,
-                isFailurePattern: entry.isFailurePattern,
-            }));
-        }
-        catch {
-            sessionLogEntries = [];
-        }
+        const taskHistory = gatherTaskHistoryPhase(db, logsDb, since, stateDbPath, now);
+        const { tableNames, missingTables, probe } = taskHistory;
+        const staleTxnJournals = gatherStaleTxnJournalsPhase(now);
+        const { semanticStatus, semanticSearchMode, embeddingEndpoint, egressConfigView } = gatherSemanticConfigPhase();
+        const { improveSummary } = gatherImproveSummaryPhase(db, stateDbPath, since, now);
+        advisories.push(...gatherAncillaryAdvisories(db, stateDbPath, since, improveSummary, options, egressConfigView));
+        const sessionLogEntries = gatherSessionLogAdvisories(since, now, getExecutionLogCandidatesFn);
         // Run the ordered health-check registry. Each check projects the shared
         // context computed above into one HealthCheckResult; `channel` routes it to
         // hardChecks or advisories. Declaration order in HEALTH_CHECKS is the
@@ -202,12 +371,15 @@ export function akmHealth(options = {}) {
             tableNames,
             missingTables,
             probe,
-            taskRowCount: taskRows.length,
-            taskFailRate,
-            taskRowsWithLogsCount: taskRowsWithLogs.length,
-            existingLogRowsCount: existingLogRows.length,
-            logBackingRate,
-            stuckActiveRuns,
+            taskRowCount: taskHistory.taskRowCount,
+            taskFailRate: taskHistory.taskFailRate,
+            taskRowsWithLogsCount: taskHistory.taskRowsWithLogsCount,
+            existingLogRowsCount: taskHistory.existingLogRowsCount,
+            logBackingRate: taskHistory.logBackingRate,
+            stuckActiveRuns: taskHistory.stuckActiveRuns,
+            stuckActiveTasks: taskHistory.stuckActiveTasks,
+            worstTaskFailRate: taskHistory.worstTaskFailRate,
+            staleTxnJournals,
             semanticStatus,
             semanticSearchMode,
             embeddingEndpoint,
@@ -223,10 +395,10 @@ export function akmHealth(options = {}) {
                 advisories.push(result);
         }
         const metrics = {
-            taskFailRate: roundRate(taskFailRate),
-            agentFailureRate: roundRate(agentFailureRate),
-            stuckActiveRuns,
-            logBackingRate: roundRate(logBackingRate),
+            taskFailRate: roundRate(taskHistory.taskFailRate),
+            agentFailureRate: roundRate(taskHistory.agentFailureRate),
+            stuckActiveRuns: taskHistory.stuckActiveRuns,
+            logBackingRate: roundRate(taskHistory.logBackingRate),
             probeRoundTripMs: probe.durationMs,
             llmUsage: readLlmUsageAggregate(stateDbPath, since),
         };
@@ -234,64 +406,21 @@ export function akmHealth(options = {}) {
         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, now);
-        }
-        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(now()).toISOString();
-                const bundle = buildWindowMetrics(db, stateDbPath, winSince, winUntil, now, logsDb);
-                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]);
-            }
-        }
+        const { windowResults, deltas } = resolveWindowComparePhase(options, db, stateDbPath, now, logsDb);
         // ── Per-run mode (Phase 2) ────────────────────────────────────────────
         let runs;
         if (options.groupBy === "run") {
             runs = buildPerRunSummaries(db, since);
         }
         return {
-            schemaVersion: 2,
+            schemaVersion: 3,
             ok: !hardFailure,
             status,
-            since: topLevelSince,
+            since,
             hardChecks,
             advisories,
-            metrics: topLevelMetrics,
-            improve: topLevelImprove,
+            metrics,
+            improve: improveSummary,
             sessionLogAdvisories: sessionLogEntries,
             ...(runs ? { runs } : {}),
             ...(windowResults ? { windows: windowResults } : {}),

package/dist/commands/improve/anti-collapse.js

@@ -72,8 +72,8 @@ function distinctTokens(text) {
 }
 /**
  * A merge must strictly increase information (R5 §4.2):
- *  1. Provenance: the merged asset's `source_refs` must be a superset of the
- *     union of all participants' `source_refs` plus the participant refs
+ *  1. Provenance: the merged asset's `xrefs` must be a superset of the union of
+ *     all participants' `xrefs` plus the participant refs
  *     themselves — provenance never shrinks through a merge.
  *  2. Specificity: distinctTokens(mergedBody) ≥ minSpecificityRetention ×
  *     |union(distinctTokens(participant bodies))| — a merge that only
@@ -91,8 +91,8 @@ export function checkMergeInformationFloor(mergedBody, mergedSourceRefs, partici
     const required = new Set();
     for (const p of participants) {
         required.add(p.ref);
-        for (const sr of p.sourceRefs)
-            required.add(sr);
+        for (const xref of p.xrefs)
+            required.add(xref);
     }
     const after = new Set(mergedSourceRefs);
     const missing = [...required].filter((r) => !after.has(r));
@@ -111,7 +111,7 @@ export function checkMergeInformationFloor(mergedBody, mergedSourceRefs, partici
     const specificityOk = specificityRetention >= minRetention;
     const reasons = [];
     if (!provenanceOk) {
-        reasons.push(`provenance shrank: merged source_refs missing ${missing.length} ref(s) (e.g. ${missing[0]})`);
+        reasons.push(`provenance shrank: merged xrefs missing ${missing.length} ref(s) (e.g. ${missing[0]})`);
     }
     if (!specificityOk) {
         reasons.push(`specificity retention ${specificityRetention.toFixed(2)} < ${minRetention} (merge genericized/shortened)`);

package/dist/commands/improve/autonomy-gate.js

@@ -0,0 +1,68 @@
+// 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 { IMPROVE_AUTONOMY_CONFIG_KEY, isImproveAutonomyEnabled, } from "../../core/config/experimental.js";
+/** The lanes `experimental.improveAutonomy` gates. */
+export const AUTONOMY_LANES = ["memoryInference", "triagePromote", "memoryCleanup"];
+const LANE_REASONS = {
+    memoryInference: "writes derived memory children and rewrites parent frontmatter",
+    triagePromote: "auto-accepts queued proposals into the stash (downgraded to queue)",
+    memoryCleanup: "rewrites belief-state frontmatter and moves files into the cleanup archive",
+};
+/**
+ * The lanes that bypass the strategy config and ask the gate at their own call
+ * site. They have no `processes.<name>.enabled` flag to downgrade, so
+ * {@link applyAutonomyGate} cannot see them — anything reporting the full gated
+ * set has to add these.
+ */
+export const DIRECT_AUTONOMY_LANES = ["memoryCleanup"];
+function gatedLane(lane) {
+    return { lane, configKey: IMPROVE_AUTONOMY_CONFIG_KEY, reason: LANE_REASONS[lane] };
+}
+/**
+ * Describe lanes for reporting — the warning line, the `improve_skipped` event,
+ * and `akm task doctor` all render the same {@link GatedLane} shape, so the
+ * lane name, config key, and reason cannot drift between the three surfaces.
+ */
+export function describeGatedLanes(lanes) {
+    return lanes.map(gatedLane);
+}
+/** Configured capabilities that tasks doctor reports behind the autonomy gate. */
+export function configuredDirectAutonomyLanes() {
+    return ["memoryCleanup"];
+}
+/**
+ * True when a lane may mutate. Used by the lane that bypasses the strategy
+ * config; the other three are handled by {@link applyAutonomyGate}.
+ */
+export function isAutonomyLaneAllowed(_lane, config) {
+    // Every lane shares one opt-in today. The parameter is kept so a call site
+    // names the lane it is asking about — that name is what reaches the operator
+    // in the skip event — and so a future per-lane split does not have to revisit
+    // every caller.
+    return isImproveAutonomyEnabled(config);
+}
+/**
+ * Downgrade a strategy config to review-first unless autonomy is opted into.
+ *
+ * Returns the config to actually run plus every downgrade made. With autonomy on
+ * the input is returned untouched and `gated` is empty.
+ */
+export function applyAutonomyGate(strategy, config) {
+    if (isImproveAutonomyEnabled(config))
+        return { config: strategy, gated: [] };
+    const gated = [];
+    const processes = { ...(strategy.processes ?? {}) };
+    if (processes.memoryInference?.enabled === true) {
+        processes.memoryInference = { ...processes.memoryInference, enabled: false };
+        gated.push(gatedLane("memoryInference"));
+    }
+    // Triage stays ENABLED — queued proposals are still triaged, they just are not
+    // auto-accepted. Disabling it would remove review work the user asked for,
+    // which is the opposite of what a review-first default should do.
+    if (processes.triage?.applyMode === "promote") {
+        processes.triage = { ...processes.triage, applyMode: "queue" };
+        gated.push(gatedLane("triagePromote"));
+    }
+    return { config: { ...strategy, processes }, gated };
+}