akm-cli 0.7.5 → 0.8.0-rc.6

package/dist/commands/improve.js

@@ -0,0 +1,2175 @@
+// 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 fs from "node:fs";
+import path from "node:path";
+import { makeAssetRef, parseAssetRef } from "../core/asset-ref";
+import { daysToMs, isAssetType } from "../core/common";
+import { getDefaultLlmConfig, loadConfig } from "../core/config";
+import { ConfigError, NotFoundError, rethrowIfTestIsolationError, UsageError } from "../core/errors";
+import { appendEvent, readEvents } from "../core/events";
+import { probeLock, releaseLock, tryAcquireLockSync } from "../core/file-lock";
+import { parseFrontmatter } from "../core/frontmatter";
+import { detectAndWriteContradictions } from "../core/memory-contradiction-detect";
+import { analyzeMemoryCleanup, applyMemoryCleanup, } from "../core/memory-improve";
+import { getDbPath } from "../core/paths";
+import { createProposal, expireStaleProposals, isProposalSkipped, listProposals, promoteProposal, purgeOrphanProposals, } from "../core/proposals";
+import { openStateDatabase, purgeOldEvents, purgeOldImproveRuns } from "../core/state-db";
+import { info, warn } from "../core/warn";
+import { closeDatabase, getAllEntries, getEntryCount, getRetrievalCounts, getUtilityScoresByIds, getZeroResultSearches, openDatabase, openExistingDatabase, } from "../indexer/db";
+import { ensureIndex } from "../indexer/ensure-index";
+import { runGraphExtractionPass } from "../indexer/graph-extraction";
+import { akmIndex } from "../indexer/indexer";
+import { runMemoryInferencePass, } from "../indexer/memory-inference";
+import { resolveAssetPath } from "../indexer/path-resolver";
+import { getWritableStashDirs, resolveSourceEntries } from "../indexer/search-source";
+import { runStalenessDetectionPass } from "../indexer/staleness-detect";
+import { resolveImproveProcessRunnerFromProfile } from "../integrations/agent/runner";
+import { getExecutionLogCandidates } from "../integrations/session-logs";
+import { isProcessEnabled } from "../llm/feature-gate";
+import { akmConsolidate } from "./consolidate";
+import { akmDistill, deriveLessonRef, isDistillRefusedInputType } from "./distill";
+import { deriveKnowledgeRef } from "./distill-promotion-policy";
+import { countEvalCases, writeEvalCase } from "./eval-cases";
+import { resolveImproveProfile, shouldSkipRef } from "./improve-profiles";
+import { akmLint } from "./lint/index";
+import { akmReflect } from "./reflect";
+import { runSchemaRepairPass } from "./schema-repair";
+import { checkDeadUrls } from "./url-checker";
+function resolveImproveScope(scope) {
+    const trimmed = scope?.trim();
+    if (!trimmed)
+        return { mode: "all" };
+    try {
+        parseAssetRef(trimmed);
+        return { mode: "ref", value: trimmed };
+    }
+    catch {
+        if (!isAssetType(trimmed)) {
+            throw new UsageError(`Unknown asset type: "${trimmed}". Valid types: memory, knowledge, skill, lesson, workflow, agent, command, script, wiki, vault, task.\n` +
+                `If you passed --format to akm improve, that flag is not supported — use it with akm search or akm show instead.`, "INVALID_FLAG_VALUE");
+        }
+        return { mode: "type", value: trimmed };
+    }
+}
+async function collectEligibleRefs(scope, stashDir) {
+    if (scope.mode === "ref" && scope.value) {
+        const parsed = parseAssetRef(scope.value);
+        const writableDirs = new Set(getWritableStashDirs(stashDir).map((dir) => path.resolve(dir)));
+        const filePath = await findAssetFilePath(scope.value, stashDir, writableDirs);
+        if (!filePath) {
+            return {
+                plannedRefs: [],
+                memorySummary: { eligible: 0, derived: 0 },
+            };
+        }
+        return {
+            plannedRefs: [{ ref: scope.value, reason: "scope-ref" }],
+            memorySummary: {
+                eligible: parsed.type === "memory" ? 1 : 0,
+                derived: parsed.type === "memory" && parsed.name.endsWith(".derived") ? 1 : 0,
+            },
+        };
+    }
+    let sources;
+    try {
+        sources = resolveSourceEntries(stashDir);
+    }
+    catch {
+        return { plannedRefs: [], memorySummary: { eligible: 0, derived: 0 } };
+    }
+    if (sources.length === 0) {
+        return { plannedRefs: [], memorySummary: { eligible: 0, derived: 0 } };
+    }
+    // Only operate on writable sources — never mutate read-only registry caches
+    // or remote stashes that the user did not mark writable.
+    let writableDirs;
+    try {
+        writableDirs = getWritableStashDirs(stashDir);
+    }
+    catch {
+        writableDirs = sources.slice(0, 1).map((s) => s.path); // fallback: primary only
+    }
+    const writableDirSet = new Set(writableDirs.map((d) => path.resolve(d)));
+    let db;
+    try {
+        db = openExistingDatabase();
+        const entries = getAllEntries(db, scope.mode === "type" ? scope.value : undefined).filter((indexed) => {
+            // First apply the existing stashDir-scope filter (no-op when stashDir is unset).
+            if (!isEntryInScope(indexed.stashDir, indexed.filePath, stashDir))
+                return false;
+            // Then restrict to writable sources only.
+            return isEntryInWritableSource(indexed.stashDir, indexed.filePath, writableDirSet);
+        });
+        const planned = new Map();
+        let memoryEligible = 0;
+        let memoryDerived = 0;
+        for (const indexed of entries) {
+            const ref = makeAssetRef(indexed.entry.type, indexed.entry.name);
+            const isDerived = indexed.entry.name.endsWith(".derived");
+            // `.derived` memories are LLM-inferred and intentionally skip reflect
+            // (see the synthetic `derived-memory-reflect-skipped` branch in the
+            // improve loop). Enqueueing them here just produced one synthetic skip
+            // per derived memory per hour with no real work — pure churn observed
+            // 2026-05-21: 11 derived refs re-planned every hour during idle periods.
+            // The cleanup phase (analyzeMemoryCleanup) inspects derived memories
+            // independently of `plannedRefs`, so dropping them here loses nothing.
+            if (!isDerived && !planned.has(ref)) {
+                planned.set(ref, {
+                    ref,
+                    reason: scope.mode === "type" ? "scope-type" : indexed.entry.type === "memory" ? "memory-cleanup" : "scope-type",
+                });
+            }
+            if (indexed.entry.type === "memory") {
+                memoryEligible += 1;
+                if (isDerived)
+                    memoryDerived += 1;
+            }
+        }
+        return {
+            plannedRefs: [...planned.values()],
+            memorySummary: { eligible: memoryEligible, derived: memoryDerived },
+        };
+    }
+    catch (error) {
+        // The bun-test isolation guard must never be downgraded to "empty plan".
+        rethrowIfTestIsolationError(error);
+        if (error instanceof NotFoundError || error instanceof Error) {
+            return { plannedRefs: [], memorySummary: { eligible: 0, derived: 0 } };
+        }
+        throw error;
+    }
+    finally {
+        if (db)
+            closeDatabase(db);
+    }
+}
+function isEntryInScope(entryStashDir, filePath, stashDir) {
+    if (!stashDir)
+        return true;
+    const resolvedEntryStashDir = path.resolve(entryStashDir);
+    const resolvedFilePath = path.resolve(filePath);
+    const resolvedScopeStashDir = path.resolve(stashDir);
+    return (resolvedEntryStashDir === resolvedScopeStashDir ||
+        resolvedEntryStashDir.startsWith(`${resolvedScopeStashDir}${path.sep}`) ||
+        resolvedFilePath.startsWith(`${resolvedScopeStashDir}${path.sep}`));
+}
+/**
+ * Return true when the indexed entry belongs to one of the writable source
+ * directories. Entries from read-only registry caches or remote stashes that
+ * the user has not marked writable must never enter the improve/distill loop.
+ */
+function isEntryInWritableSource(entryStashDir, filePath, writableDirSet) {
+    const resolvedEntryStashDir = path.resolve(entryStashDir);
+    const resolvedFilePath = path.resolve(filePath);
+    for (const writableDir of writableDirSet) {
+        if (resolvedEntryStashDir === writableDir ||
+            resolvedEntryStashDir.startsWith(`${writableDir}${path.sep}`) ||
+            resolvedFilePath.startsWith(`${writableDir}${path.sep}`)) {
+            return true;
+        }
+    }
+    return false;
+}
+function memoryCleanupParentRef(scope, stashDir) {
+    if (scope.mode !== "ref" || !scope.value)
+        return undefined;
+    const parsed = parseAssetRef(scope.value);
+    if (parsed.type !== "memory")
+        return undefined;
+    if (!parsed.name.endsWith(".derived"))
+        return scope.value;
+    const sources = resolveSourceEntries(stashDir);
+    for (const source of sources) {
+        const candidate = path.join(source.path, "memories", `${parsed.name}.md`);
+        if (!fs.existsSync(candidate))
+            continue;
+        const raw = fs.readFileSync(candidate, "utf8");
+        const fm = parseFrontmatter(raw).data;
+        const sourceRef = typeof fm.source === "string" ? fm.source : undefined;
+        if (sourceRef) {
+            try {
+                const parent = parseAssetRef(sourceRef.trim());
+                if (parent.type === "memory")
+                    return makeAssetRef(parent.type, parent.name);
+            }
+            catch { }
+        }
+    }
+    return makeAssetRef("memory", parsed.name.slice(0, -".derived".length));
+}
+function isLessonCandidate(ref) {
+    // Only lesson assets need lesson-schema validation (description + when_to_use).
+    // Memories have their own distill path via shouldDistillMemoryRef.
+    // All other types go through reflect, not distill.
+    return parseAssetRef(ref).type === "lesson";
+}
+/**
+ * Planner-side check: should this ref enter the distill queue?
+ *
+ * Distill produces lessons from non-lesson sources. Two cases are eligible:
+ *
+ *   1. Memory refs that pass {@link shouldDistillMemoryRef} (the existing
+ *      memory→lesson/knowledge promotion path).
+ *
+ * Refs whose `type` is in {@link DISTILL_REFUSED_INPUT_TYPES} (currently
+ * `lesson:*`) are explicitly excluded — distill refuses them at runtime and
+ * queuing them just produces a no-op `skipped` outcome per ref per hour. That
+ * planner waste was the bug fixed in commit
+ * fix(improve): drop distill-refused types from planner.
+ *
+ * Note: prior to this fix the gate used `isLessonCandidate(ref)` directly,
+ * which was true *only* for `lesson:*` refs — exactly the set distill refuses.
+ * The result: every hourly run re-queued the same lesson refs, the same skip
+ * message returned, and no work was ever done. See
+ * `tests/commands/improve-distill-planner-skip-lessons.test.ts`.
+ */
+function isDistillCandidateRef(ref, stashDir) {
+    const parsed = parseAssetRef(ref);
+    if (isDistillRefusedInputType(parsed.type))
+        return false;
+    return shouldDistillMemoryRef(ref, stashDir);
+}
+function shouldDistillMemoryRef(ref, stashDir) {
+    const parsed = parseAssetRef(ref);
+    if (parsed.type !== "memory")
+        return false;
+    const sources = resolveSourceEntries(stashDir);
+    for (const source of sources) {
+        const candidate = `${source.path}/memories/${parsed.name}.md`;
+        if (!fs.existsSync(candidate))
+            continue;
+        const raw = fs.readFileSync(candidate, "utf8");
+        const fm = parseFrontmatter(raw).data;
+        const quality = typeof fm.quality === "string" ? fm.quality : undefined;
+        if (quality === "proposed")
+            return false;
+        return !parsed.name.endsWith(".derived");
+    }
+    return !parsed.name.endsWith(".derived");
+}
+export async function akmImprove(options = {}) {
+    const scope = resolveImproveScope(options.scope);
+    const reflectFn = options.reflectFn ?? akmReflect;
+    const distillFn = options.distillFn ?? akmDistill;
+    const ensureIndexFn = options.ensureIndexFn ?? ensureIndex;
+    const reindexFn = options.reindexFn ?? akmIndex;
+    // Resolve the improve profile for this run. Profile drives type filtering,
+    // process gating, and default autoAccept/limit values.
+    const _earlyConfig = options.config ?? loadConfig();
+    const improveProfile = resolveImproveProfile(options.profile, _earlyConfig);
+    // Apply profile defaults — CLI flags take precedence over profile defaults.
+    // Rebuild options with effective values so all downstream stage functions
+    // automatically pick up the profile-driven defaults.
+    options = {
+        ...options,
+        autoAccept: options.autoAccept ?? improveProfile.autoAccept,
+        limit: options.limit ?? improveProfile.limit,
+    };
+    let primaryStashDir;
+    try {
+        primaryStashDir = resolveSourceEntries(options.stashDir)[0]?.path;
+    }
+    catch {
+        primaryStashDir = undefined;
+    }
+    // #339 fix: ensureIndex MUST run BEFORE collectEligibleRefs. The eligible-ref
+    // query reads the `entries` table; if a DB version upgrade just dropped that
+    // table (or the index is otherwise empty), the prior run order silently
+    // returned plannedRefs=[] and the improve loop no-op'd. Hoisting the call
+    // here repopulates the index first so the subsequent query sees fresh data.
+    const preEnsureCleanupWarnings = [];
+    if (primaryStashDir) {
+        // Probe pre-ensureIndex entry count to drive the loud-fail warning below.
+        // Best-effort: a missing DB / unreadable schema is the fresh-install case
+        // and not a bug — we silently skip the probe.
+        let preEnsureEntryCount;
+        try {
+            const dbPath = getDbPath();
+            if (fs.existsSync(dbPath)) {
+                const probeDb = openExistingDatabase();
+                try {
+                    preEnsureEntryCount = getEntryCount(probeDb);
+                }
+                finally {
+                    closeDatabase(probeDb);
+                }
+            }
+        }
+        catch (err) {
+            rethrowIfTestIsolationError(err);
+            // best-effort; leave preEnsureEntryCount undefined
+        }
+        try {
+            await ensureIndexFn(primaryStashDir);
+        }
+        catch (err) {
+            preEnsureCleanupWarnings.push(`ensureIndex failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        // #339 loud-fail: if the index was empty pre-ensureIndex but is now
+        // populated, a version-upgrade-triggered rebuild just happened. Surface
+        // that on stderr so the improve run is not silently masked by stale
+        // index state. Zero-before AND zero-after is the empty-stash case and
+        // is intentionally not warned (not a bug).
+        if (preEnsureEntryCount === 0) {
+            try {
+                const probeDb = openExistingDatabase();
+                let postCount = 0;
+                try {
+                    postCount = getEntryCount(probeDb);
+                }
+                finally {
+                    closeDatabase(probeDb);
+                }
+                if (postCount > 0) {
+                    warn("[improve] index was empty after DB version upgrade — repopulating before continuing");
+                }
+            }
+            catch (err) {
+                rethrowIfTestIsolationError(err);
+                // best-effort
+            }
+        }
+    }
+    const { plannedRefs, memorySummary } = await collectEligibleRefs(scope, options.stashDir);
+    const cleanupParentRef = memoryCleanupParentRef(scope, options.stashDir);
+    // M-1 (#367): Run contradiction-detection BEFORE analyzeMemoryCleanup so
+    // the SCC resolver in resolveFamilyContradictions has edges to work on.
+    // Best-effort: failures are warnings, never fatal.
+    if (primaryStashDir && shouldAnalyzeMemoryCleanup(scope, memorySummary.eligible, primaryStashDir)) {
+        try {
+            const config = options.config ?? loadConfig();
+            await detectAndWriteContradictions(primaryStashDir, config);
+        }
+        catch (err) {
+            // Non-fatal: contradiction detection is a best-effort pass.
+            warn(`[improve] contradiction detection failed (non-fatal): ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    const memoryCleanupPlan = shouldAnalyzeMemoryCleanup(scope, memorySummary.eligible, primaryStashDir)
+        ? analyzeMemoryCleanup(primaryStashDir, cleanupParentRef ? { parentRef: cleanupParentRef } : undefined)
+        : undefined;
+    const guidance = memorySummary.eligible > 0
+        ? "Improve folds memory cleanup into the same proposal queue: speculative promotions still go through reflect/distill proposals, while high-confidence redundant derived memories are moved into a recoverable cleanup archive instead of being left active in the stash."
+        : undefined;
+    if (options.dryRun) {
+        const result = {
+            schemaVersion: 1,
+            ok: true,
+            scope,
+            dryRun: true,
+            ...(guidance ? { guidance } : {}),
+            memorySummary,
+            ...(memoryCleanupPlan ? { memoryCleanup: shapeMemoryCleanup(memoryCleanupPlan) } : {}),
+            plannedRefs,
+        };
+        return result;
+    }
+    const resolvedLockPath = primaryStashDir
+        ? path.join(primaryStashDir, ".akm", "improve.lock")
+        : path.join(options.stashDir ?? ".", ".akm", "improve.lock");
+    const MAX_LOCK_AGE_MS = 4 * 60 * 60 * 1000; // 4 hours
+    fs.mkdirSync(path.dirname(resolvedLockPath), { recursive: true });
+    const lockPayload = () => JSON.stringify({ pid: process.pid, startedAt: new Date().toISOString() });
+    const acquireLock = () => {
+        if (tryAcquireLockSync(resolvedLockPath, lockPayload()))
+            return;
+        // Lock file already exists — probe to determine whether it's still held
+        // or whether the prior run died without cleaning up.
+        const probe = probeLock(resolvedLockPath, { staleAfterMs: MAX_LOCK_AGE_MS });
+        const rawContent = probe.state === "absent" ? undefined : probe.rawContent;
+        const lock = rawContent
+            ? (() => {
+                try {
+                    return JSON.parse(rawContent);
+                }
+                catch {
+                    return null;
+                }
+            })()
+            : null;
+        if (probe.state === "stale") {
+            // O-7 / #394: Emit improve_lock_recovered event before recovery so the
+            // audit trail records the abnormal prior-run exit (Temporal/Airflow pattern).
+            try {
+                appendEvent({
+                    eventType: "improve_lock_recovered",
+                    metadata: {
+                        stalePid: lock?.pid ?? null,
+                        lockedAt: lock?.startedAt ?? null,
+                        recoveredAt: new Date().toISOString(),
+                        lockAgeMs: probe.ageMs ?? null,
+                        reason: probe.reason === "pid_dead" ? "pid_not_alive" : probe.reason,
+                    },
+                });
+            }
+            catch {
+                /* event emission is best-effort; never block lock recovery */
+            }
+            releaseLock(resolvedLockPath);
+            if (tryAcquireLockSync(resolvedLockPath, lockPayload()))
+                return;
+            throw new ConfigError(`akm improve is already running. Delete ${resolvedLockPath} to force.`, "INVALID_CONFIG_FILE");
+        }
+        throw new ConfigError(`akm improve is already running (PID ${lock?.pid}, started ${lock?.startedAt}). Delete ${resolvedLockPath} to force.`, "INVALID_CONFIG_FILE");
+    };
+    acquireLock();
+    const budgetMs = options.timeoutMs ?? 2 * 60 * 60 * 1000; // default 2 hours
+    const startMs = Date.now();
+    // O-1 (#364): Create a shared AbortController derived from startMs + budgetMs.
+    // Every async seam receives this signal so a hung sub-call cannot extend the
+    // run past the declared budget.
+    // References: Anthropic *Building Effective Agents* (2024); CoALA §5 (arXiv:2309.02427).
+    const budgetAbortController = new AbortController();
+    const budgetTimer = setTimeout(() => budgetAbortController.abort("improve budget exhausted"), budgetMs);
+    // Clear the timer when the run ends to avoid keeping the event loop alive.
+    const clearBudgetTimer = () => clearTimeout(budgetTimer);
+    // I1: open a single state.db connection for the entire improve run so all
+    // appendEvent calls reuse one handle instead of open/migrate/close per call.
+    let eventsDb;
+    let eventsCtx;
+    try {
+        eventsDb = openStateDatabase();
+        eventsCtx = { db: eventsDb };
+    }
+    catch (err) {
+        rethrowIfTestIsolationError(err);
+        // If we cannot open state.db up-front, fall back to per-call opens.
+        eventsCtx = {};
+    }
+    try {
+        const preparation = await runImprovePreparationStage({
+            scope,
+            options,
+            plannedRefs,
+            memoryCleanupPlan,
+            primaryStashDir,
+            memorySummary,
+            reindexFn,
+            startMs,
+            budgetMs,
+            eventsCtx,
+            initialCleanupWarnings: preEnsureCleanupWarnings,
+            improveProfile,
+        });
+        // D6: pre-load all proposal_rejected events from the last 30 days once,
+        // so the per-asset loop can use a Map lookup instead of N DB round trips.
+        const REJECTED_PROPOSAL_WINDOW_MS = daysToMs(30);
+        const rejectedProposalSince = new Date(Date.now() - REJECTED_PROPOSAL_WINDOW_MS).toISOString();
+        const allRejectedProposalEvents = readEvents({ type: "proposal_rejected", since: rejectedProposalSince }).events;
+        const rejectedProposalsByRef = new Map();
+        for (const e of allRejectedProposalEvents) {
+            if (e.ref && (!rejectedProposalsByRef.has(e.ref) || e.ts > (rejectedProposalsByRef.get(e.ref)?.ts ?? ""))) {
+                rejectedProposalsByRef.set(e.ref, e);
+            }
+        }
+        const { reflectsWithErrorContext, memoryRefsForInference } = await runImproveLoopStage({
+            scope,
+            options,
+            primaryStashDir,
+            reflectFn,
+            distillFn,
+            loopRefs: preparation.loopRefs,
+            actions: preparation.actions,
+            signalBearingSet: preparation.signalBearingSet,
+            distillCooledRefs: preparation.distillCooledRefs,
+            distillOnlyRefs: preparation.distillOnlyRefs,
+            recentErrors: preparation.recentErrors,
+            rejectedProposalsByRef,
+            utilityMap: preparation.utilityMap,
+            startMs,
+            budgetMs,
+            eventsCtx,
+            improveProfile,
+        });
+        const { allWarnings, consolidation, deadUrls, memoryInference, graphExtraction, stalenessDetection, maintenanceActions, memoryInferenceDurationMs, graphExtractionDurationMs, orphansPurged, proposalsExpired, } = await runImprovePostLoopStage({
+            scope,
+            options,
+            primaryStashDir,
+            actionableRefs: preparation.actionableRefs,
+            appliedCleanup: preparation.appliedCleanup,
+            cleanupWarnings: preparation.cleanupWarnings,
+            memorySummary,
+            memoryRefsForInference,
+            reindexFn,
+            eventsCtx,
+            // O-1 (#364): propagate wall-clock budget signal to post-loop maintenance.
+            budgetSignal: budgetAbortController.signal,
+            improveProfile,
+        });
+        const finalActions = maintenanceActions && maintenanceActions.length > 0
+            ? [...preparation.actions, ...maintenanceActions]
+            : preparation.actions;
+        const result = {
+            schemaVersion: 1,
+            ok: true,
+            scope,
+            dryRun: false,
+            ...(guidance ? { guidance } : {}),
+            memorySummary,
+            ...(memoryCleanupPlan
+                ? {
+                    memoryCleanup: {
+                        ...shapeMemoryCleanup(memoryCleanupPlan),
+                        ...(preparation.appliedCleanup
+                            ? {
+                                archived: preparation.appliedCleanup.archived,
+                                ...(preparation.appliedCleanup.transitionLogPath
+                                    ? { transitionLogPath: preparation.appliedCleanup.transitionLogPath }
+                                    : {}),
+                                ...(preparation.appliedCleanup.transitionLogEntries !== undefined
+                                    ? { transitionLogEntries: preparation.appliedCleanup.transitionLogEntries }
+                                    : {}),
+                                ...(allWarnings.length > 0 ? { warnings: allWarnings } : {}),
+                            }
+                            : preparation.cleanupWarnings.length > 0
+                                ? { warnings: preparation.cleanupWarnings }
+                                : {}),
+                    },
+                }
+                : {}),
+            plannedRefs: preparation.actionableRefs,
+            actions: finalActions,
+            ...(preparation.validationFailures.length > 0 ? { validationFailures: preparation.validationFailures } : {}),
+            ...(preparation.schemaRepairs.length > 0 ? { schemaRepairs: preparation.schemaRepairs } : {}),
+            ...(consolidation.processed > 0 || consolidation.warnings.length > 0 ? { consolidation } : {}),
+            ...(preparation.lintSummary !== undefined ? { lintSummary: preparation.lintSummary } : {}),
+            ...(preparation.memoryIndexHealth !== undefined ? { memoryIndexHealth: preparation.memoryIndexHealth } : {}),
+            ...(preparation.coverageGaps.length > 0 ? { coverageGaps: preparation.coverageGaps } : {}),
+            ...(preparation.executionLogCandidates.length > 0
+                ? { executionLogCandidates: preparation.executionLogCandidates }
+                : {}),
+            ...(primaryStashDir !== undefined ? { evalCasesWritten: countEvalCases(primaryStashDir) } : {}),
+            ...(deadUrls !== undefined && deadUrls.length > 0 ? { deadUrls } : {}),
+            ...(reflectsWithErrorContext > 0 ? { reflectsWithErrorContext } : {}),
+            ...(memoryInference ? { memoryInference } : {}),
+            ...(graphExtraction ? { graphExtraction } : {}),
+            ...(stalenessDetection ? { stalenessDetection } : {}),
+            ...(orphansPurged !== undefined ? { orphansPurged } : {}),
+            ...(proposalsExpired !== undefined && proposalsExpired > 0 ? { proposalsExpired } : {}),
+            reflectCooldownActions: finalActions.filter((a) => a.mode === "reflect-cooldown").length,
+            reflectSkippedActions: finalActions.filter((a) => a.mode === "reflect-skipped").length,
+        };
+        if (!result.dryRun)
+            emitImproveCompletedEvent(result, {
+                memoryInferenceDurationMs,
+                graphExtractionDurationMs,
+                totalDurationMs: Date.now() - startMs,
+                warningCount: allWarnings.length,
+                orphansPurged: orphansPurged ?? 0,
+            }, eventsCtx);
+        return result;
+    }
+    catch (err) {
+        // D3: emit improve_failed on unexpected crash so dashboards can detect failures.
+        appendEvent({
+            eventType: "improve_failed",
+            ref: scope.mode === "ref" ? scope.value : `improve:${scope.mode}:${scope.value ?? "all"}`,
+            metadata: {
+                error: err instanceof Error ? err.message : String(err),
+                durationMs: Date.now() - startMs,
+            },
+        }, eventsCtx);
+        throw err;
+    }
+    finally {
+        // O-1 (#364): Clear the budget abort timer so it does not keep the event
+        // loop alive after the run completes.
+        clearBudgetTimer();
+        try {
+            fs.unlinkSync(resolvedLockPath);
+        }
+        catch {
+            // ignore
+        }
+        // I1: close the long-lived state.db connection opened at the top of the run.
+        try {
+            eventsDb?.close();
+        }
+        catch {
+            // ignore — DB may already be closed
+        }
+    }
+}
+function emitImproveCompletedEvent(result, durations, eventsCtx) {
+    const actionCounts = {
+        reflect: 0,
+        reflectFailed: 0,
+        reflectCooldown: 0,
+        reflectSkipped: 0,
+        distill: 0,
+        distillSkipped: 0,
+        memoryPrune: 0,
+        memoryInference: 0,
+        graphExtraction: 0,
+        error: 0,
+    };
+    for (const action of result.actions ?? []) {
+        switch (action.mode) {
+            case "reflect":
+                actionCounts.reflect += 1;
+                break;
+            case "reflect-failed":
+                actionCounts.reflectFailed += 1;
+                break;
+            case "reflect-cooldown":
+                actionCounts.reflectCooldown += 1;
+                break;
+            case "reflect-skipped":
+                actionCounts.reflectSkipped += 1;
+                break;
+            case "distill":
+                actionCounts.distill += 1;
+                break;
+            case "distill-skipped":
+                actionCounts.distillSkipped += 1;
+                break;
+            case "memory-prune":
+                actionCounts.memoryPrune += 1;
+                break;
+            case "memory-inference":
+                actionCounts.memoryInference += 1;
+                break;
+            case "graph-extraction":
+                actionCounts.graphExtraction += 1;
+                break;
+            case "error":
+                actionCounts.error += 1;
+                break;
+        }
+    }
+    appendEvent({
+        eventType: "improve_completed",
+        ref: result.scope.mode === "ref"
+            ? result.scope.value
+            : `improve:${result.scope.mode}:${result.scope.value ?? "all"}`,
+        metadata: {
+            plannedRefs: result.plannedRefs.length,
+            reflectActions: actionCounts.reflect,
+            distillActions: actionCounts.distill,
+            distillSkippedActions: actionCounts.distillSkipped,
+            memoryPruneActions: actionCounts.memoryPrune,
+            memoryInferenceActions: actionCounts.memoryInference,
+            graphExtractionActions: actionCounts.graphExtraction,
+            errorActions: actionCounts.error,
+            reflectFailedActions: actionCounts.reflectFailed,
+            reflectCooldownActions: actionCounts.reflectCooldown,
+            reflectSkippedActions: actionCounts.reflectSkipped,
+            reflectsWithErrorContext: result.reflectsWithErrorContext ?? 0,
+            coverageGapCount: result.coverageGaps?.length ?? 0,
+            executionLogCandidateCount: result.executionLogCandidates?.length ?? 0,
+            evalCasesWritten: result.evalCasesWritten ?? 0,
+            deadUrlCount: result.deadUrls?.length ?? 0,
+            memoryEligible: result.memorySummary.eligible,
+            memoryDerived: result.memorySummary.derived,
+            memoryCleanupPruneCandidates: result.memoryCleanup?.pruneCandidates.length ?? 0,
+            memoryCleanupContradictionCandidates: result.memoryCleanup?.contradictionCandidates.length ?? 0,
+            memoryCleanupBeliefStateTransitions: result.memoryCleanup?.beliefStateTransitions.length ?? 0,
+            memoryCleanupConsolidationCandidates: result.memoryCleanup?.consolidationCandidates.length ?? 0,
+            memoryCleanupArchived: result.memoryCleanup?.archived?.length ?? 0,
+            memoryCleanupWarnings: result.memoryCleanup?.warnings?.length ?? 0,
+            consolidationProcessed: result.consolidation?.processed ?? 0,
+            consolidationDurationMs: result.consolidation?.durationMs ?? 0,
+            memoryInferenceWrites: result.memoryInference?.writtenFacts ?? 0,
+            memoryInferenceDurationMs: durations.memoryInferenceDurationMs,
+            graphExtractionExtractedFiles: result.graphExtraction?.quality.extractedFiles ?? 0,
+            graphExtractionDurationMs: durations.graphExtractionDurationMs,
+            // New metrics for tuning the improve loop.
+            ...(durations.totalDurationMs !== undefined ? { durationMs: durations.totalDurationMs } : {}),
+            ...(durations.warningCount !== undefined ? { warningCount: durations.warningCount } : {}),
+            ...(durations.orphansPurged !== undefined ? { orphansPurged: durations.orphansPurged } : {}),
+            ...(result.graphExtraction?.quality
+                ? {
+                    graphCoverage: result.graphExtraction.quality.extractionCoverage,
+                    graphDensity: result.graphExtraction.quality.density,
+                    graphEntities: result.graphExtraction.quality.entityCount,
+                }
+                : {}),
+        },
+    }, eventsCtx);
+}
+async function runImprovePreparationStage(args) {
+    const { scope, options, plannedRefs, memoryCleanupPlan, primaryStashDir, reindexFn, startMs, budgetMs, eventsCtx, initialCleanupWarnings, improveProfile, } = args;
+    const actions = [];
+    const cleanupWarnings = initialCleanupWarnings ? [...initialCleanupWarnings] : [];
+    // Phase 0 — MEMORY.md budget check (200-line cap; warn at 180)
+    let memoryIndexHealth;
+    if (primaryStashDir) {
+        const memoryMdPath = path.join(primaryStashDir, "memories", "MEMORY.md");
+        if (fs.existsSync(memoryMdPath)) {
+            try {
+                const lines = fs.readFileSync(memoryMdPath, "utf8").split("\n").length;
+                const overBudget = lines >= 180;
+                memoryIndexHealth = { lineCount: lines, overBudget };
+                if (overBudget) {
+                    cleanupWarnings.push(`MEMORY.md has ${lines} lines (budget: 200). Consolidation strongly recommended.`);
+                }
+            }
+            catch {
+                // best-effort
+            }
+        }
+    }
+    // Phase 0 — execution log synthesis
+    let executionLogCandidates = [];
+    try {
+        const logEntries = getExecutionLogCandidates(7);
+        executionLogCandidates = logEntries.filter((e) => e.isFailurePattern).map((e) => e.topic);
+    }
+    catch {
+        // best-effort
+    }
+    // eligibleCount = raw pre-filter count (before cooldown/signal/cleanup filters).
+    // improve_completed.plannedRefs = post-filter count of refs that actually entered the loop.
+    appendEvent({
+        eventType: "improve_invoked",
+        ref: scope.mode === "ref" ? scope.value : `improve:${scope.mode}:${scope.value ?? "all"}`,
+        metadata: { scope, dryRun: options.dryRun ?? false, eligibleCount: plannedRefs.length },
+    }, eventsCtx);
+    // ensureIndex now runs in akmImprove() BEFORE collectEligibleRefs so the
+    // eligible-ref query sees a populated `entries` table on the very first
+    // pass after a DB version upgrade (#339). Any failure messages from that
+    // earlier call were threaded in via args.initialCleanupWarnings.
+    let appliedCleanup;
+    try {
+        appliedCleanup =
+            primaryStashDir && memoryCleanupPlan ? applyMemoryCleanup(primaryStashDir, memoryCleanupPlan) : undefined;
+    }
+    catch (err) {
+        cleanupWarnings.push(`applyMemoryCleanup failed: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    const archivedRefs = appliedCleanup?.archived.map((record) => record.ref) ?? [];
+    const removed = new Set(archivedRefs);
+    const postCleanupRefs = archivedRefs.length === 0 ? plannedRefs : plannedRefs.filter((r) => !removed.has(r.ref));
+    // ── Phase 1: validation pass + schema repair (run on full postCleanupRefs) ──
+    // Identifies refs whose on-disk asset has structural problems. Validation
+    // failures are excluded from every downstream bucket. Run early so the
+    // cooldown partition operates on a clean set.
+    if (appliedCleanup) {
+        for (const candidate of memoryCleanupPlan?.pruneCandidates ?? []) {
+            const archived = appliedCleanup.archived.find((record) => record.ref === candidate.ref);
+            if (!archived)
+                continue;
+            actions.push({
+                ref: candidate.ref,
+                mode: "memory-prune",
+                result: { ok: true, pruned: true, reason: candidate.reason },
+            });
+        }
+        if ((appliedCleanup.archived.length > 0 || appliedCleanup.beliefStateTransitions.length > 0) && primaryStashDir) {
+            try {
+                await reindexFn({ stashDir: primaryStashDir });
+            }
+            catch (err) {
+                cleanupWarnings.push(`reindex after cleanup failed: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+    }
+    const validationFailures = [];
+    for (const candidate of postCleanupRefs) {
+        try {
+            const filePath = await findAssetFilePath(candidate.ref, options.stashDir);
+            if (!filePath) {
+                validationFailures.push({ ref: candidate.ref, reason: "file not found on disk" });
+                continue;
+            }
+            if (path.extname(filePath).toLowerCase() !== ".md") {
+                continue;
+            }
+            if (isLessonCandidate(candidate.ref)) {
+                const raw = fs.readFileSync(filePath, "utf8");
+                const fm = parseFrontmatter(raw).data;
+                if (!fm.description)
+                    validationFailures.push({ ref: candidate.ref, reason: "missing description" });
+            }
+        }
+        catch (e) {
+            validationFailures.push({ ref: candidate.ref, reason: String(e) });
+        }
+    }
+    if (validationFailures.length > 0) {
+        info(`[improve] ${validationFailures.length} assets have validation issues (will attempt schema repair):`);
+        for (const f of validationFailures)
+            info(`  ${f.ref}: ${f.reason}`);
+    }
+    let schemaRepairs = [];
+    let repairedRefs = new Set();
+    // Schema repair pass: attempt to fix validation failures via LLM before skipping.
+    if (validationFailures.length > 0 && options.repairValidationFailures !== false) {
+        const baseConfigForRepair = options.config ?? loadConfig();
+        const llmCfg = getDefaultLlmConfig(baseConfigForRepair);
+        if (llmCfg) {
+            const result = await runSchemaRepairPass(validationFailures, {
+                startMs,
+                budgetMs,
+                llmConfig: llmCfg,
+                stashDir: options.stashDir,
+                findFilePath: findAssetFilePath,
+                isLessonCandidateFn: isLessonCandidate,
+            });
+            schemaRepairs = result.repairs;
+            repairedRefs = result.repairedRefs;
+        }
+    }
+    const validationFailureRefs = new Set(validationFailures.filter((f) => !repairedRefs.has(f.ref)).map((f) => f.ref));
+    if (repairedRefs.size > 0) {
+        info(`[improve] schema repair fixed ${repairedRefs.size}/${validationFailures.length} validation failures; ${validationFailureRefs.size} remain`);
+    }
+    // Phase 0.5 — structural hygiene pass
+    let lintSummary;
+    if (primaryStashDir) {
+        try {
+            const lintResult = akmLint({ fix: true, dir: primaryStashDir });
+            lintSummary = { fixed: lintResult.summary.fixed, flagged: lintResult.summary.flagged };
+        }
+        catch {
+            // lint is best-effort; never block improve
+        }
+    }
+    // O-5 / #378: Per-originator rolling error windows.
+    // Reflexion (arXiv:2303.11366) warns that cross-task verbal critique
+    // contamination degrades below single-shot baseline. Each originator key
+    // ("schema-repair", "reflect") maintains its own rolling window so that
+    // schema-repair failures are not injected as avoidPatterns into reflect calls.
+    const recentErrors = {};
+    const RECENT_ERRORS_CAP = 3;
+    // Helper: push an error onto an originator's rolling window.
+    function pushRecentError(originator, msg) {
+        if (!recentErrors[originator])
+            recentErrors[originator] = [];
+        recentErrors[originator].push(msg);
+        if (recentErrors[originator].length > RECENT_ERRORS_CAP)
+            recentErrors[originator].shift();
+    }
+    // Seed schema-repair originator window from any schema-repair errors.
+    for (const repair of schemaRepairs) {
+        if (repair.outcome === "error") {
+            const errMsg = repair.error ?? `schema repair error: ${repair.reason}`;
+            pushRecentError("schema-repair", errMsg);
+        }
+    }
+    // ── Phase 2: cooldown sets built EARLY ────────────────────────────────────
+    // Read all cooldown-relevant events in 4 bulk queries and materialise two
+    // Sets used by the partition (next phase). Doing this before signal/feedback/
+    // utility/sort means the expensive ranking work only runs on refs that can
+    // actually be processed this run.
+    //
+    // SM-2 tier for reflect uses promoted/rejected events (recorded by
+    // `akm proposal accept/reject`) rather than the per-ref listProposals()
+    // filesystem scan, giving identical tier logic without touching the disk.
+    // Built-in per-type reflect cooldown defaults. Higher-churn types get shorter
+    // windows; stable reference material gets longer ones.
+    // Overridable via profiles.improve[name].processes.reflect.cooldownByType,
+    // or globally via --reflect-cooldown-days (CLI flag, highest priority).
+    const REFLECT_COOLDOWN_BUILTIN = {
+        memory: 2,
+        lesson: 7,
+        workflow: 30,
+        skill: 30,
+        agent: 30,
+        command: 30,
+        knowledge: 30,
+        script: 30,
+        wiki: 30,
+        task: 60,
+    };
+    const REFLECT_COOLDOWN_FALLBACK = 30;
+    const profileCooldownByType = Object.fromEntries(Object.entries(improveProfile.processes?.reflect?.cooldownByType ?? {}).filter((entry) => entry[1] !== undefined));
+    const REFLECT_COOLDOWN_BY_TYPE = {
+        ...REFLECT_COOLDOWN_BUILTIN,
+        ...profileCooldownByType,
+    };
+    const profileCooldownDays = improveProfile.processes?.reflect?.cooldownDays;
+    const reflectCooldownForRef = (ref) => {
+        if (options.reflectCooldownDays !== undefined)
+            return options.reflectCooldownDays;
+        const type = ref.split(":")[0] ?? "";
+        return REFLECT_COOLDOWN_BY_TYPE[type] ?? profileCooldownDays ?? REFLECT_COOLDOWN_FALLBACK;
+    };
+    const DISTILL_COOLDOWN_DAYS = options.distillCooldownDays ?? 1;
+    const reflectCooledRefs = new Set();
+    const distillCooledRefs = new Set();
+    // Use the largest possible reflect window when querying bulk events so we
+    // don't miss cooldown records for long-window types (e.g. lesson = 90 days).
+    const maxReflectCooldownDays = options.reflectCooldownDays !== undefined
+        ? options.reflectCooldownDays
+        : Math.max(...Object.values(REFLECT_COOLDOWN_BY_TYPE));
+    const effectiveDistillCooldown = DISTILL_COOLDOWN_DAYS;
+    const reflectCooldownActive = options.reflectCooldownDays !== 0;
+    if (reflectCooldownActive || effectiveDistillCooldown > 0) {
+        const bulkWindowMs = daysToMs(Math.max(maxReflectCooldownDays, effectiveDistillCooldown));
+        const bulkSince = new Date(Date.now() - bulkWindowMs).toISOString();
+        // TODO(refactor): 4 separate readEvents calls with same time bound — could be one WHERE type IN (...) query if readEvents grew a `types?: string[]` option. Marginal win with WAL+long-lived connection, defer.
+        const bulkReflects = readEvents({ type: "reflect_invoked", since: bulkSince }).events;
+        const bulkDistills = readEvents({ type: "distill_invoked", since: bulkSince }).events;
+        const bulkPromoted = readEvents({ type: "promoted", since: bulkSince }).events;
+        const bulkRejected = readEvents({ type: "rejected", since: bulkSince }).events;
+        const promotedTs = new Map();
+        for (const e of bulkPromoted) {
+            if (e.ref && (e.ts ?? "") > (promotedTs.get(e.ref) ?? ""))
+                promotedTs.set(e.ref, e.ts ?? "");
+        }
+        const rejectedTs = new Map();
+        for (const e of bulkRejected) {
+            if (e.ref && (e.ts ?? "") > (rejectedTs.get(e.ref) ?? ""))
+                rejectedTs.set(e.ref, e.ts ?? "");
+        }
+        if (reflectCooldownActive) {
+            const latestReflect = new Map();
+            for (const e of bulkReflects) {
+                if (e.ref && (e.ts ?? "") > (latestReflect.get(e.ref) ?? ""))
+                    latestReflect.set(e.ref, e.ts ?? "");
+            }
+            for (const [ref, lastTs] of latestReflect) {
+                if (!lastTs)
+                    continue;
+                const hasAccepted = (promotedTs.get(ref) ?? "") > lastTs;
+                const hasRejected = (rejectedTs.get(ref) ?? "") > lastTs;
+                if (hasAccepted)
+                    continue;
+                const typeCooldown = reflectCooldownForRef(ref);
+                const effectiveCooldownDays = hasRejected ? Math.min(typeCooldown, 3) : typeCooldown;
+                if (Date.now() - new Date(lastTs).getTime() < daysToMs(effectiveCooldownDays)) {
+                    reflectCooledRefs.add(ref);
+                }
+            }
+        }
+        if (DISTILL_COOLDOWN_DAYS > 0) {
+            const distillCooldownMs = daysToMs(DISTILL_COOLDOWN_DAYS);
+            // B5: track both queued and validation_failed outcomes for cooldown.
+            // validation_failed assets previously were never cooled so they re-distilled on every run.
+            const validationFailedCooldownMs = daysToMs(Math.ceil(DISTILL_COOLDOWN_DAYS / 2));
+            const latestQueuedDistill = new Map();
+            const latestValidationFailed = new Map();
+            for (const e of bulkDistills) {
+                if (e.ref && e.metadata?.outcome === "queued" && (e.ts ?? "") > (latestQueuedDistill.get(e.ref) ?? "")) {
+                    latestQueuedDistill.set(e.ref, e.ts ?? "");
+                }
+                if (e.ref &&
+                    e.metadata?.outcome === "validation_failed" &&
+                    (e.ts ?? "") > (latestValidationFailed.get(e.ref) ?? "")) {
+                    latestValidationFailed.set(e.ref, e.ts ?? "");
+                }
+            }
+            for (const [ref, lastTs] of latestQueuedDistill) {
+                if (lastTs && Date.now() - new Date(lastTs).getTime() < distillCooldownMs) {
+                    distillCooledRefs.add(ref);
+                }
+            }
+            for (const [ref, lastTs] of latestValidationFailed) {
+                if (lastTs && Date.now() - new Date(lastTs).getTime() < validationFailedCooldownMs) {
+                    distillCooledRefs.add(ref);
+                }
+            }
+        }
+    }
+    // ── Phase 3: partition postCleanupRefs by cooldown BEFORE signal/sort ─────
+    // Three buckets (validation failures are excluded entirely):
+    //   eligibleRefs        — not reflect-cooled (normal reflect path; distill
+    //                         guard remains in the loop for distill-cooled refs).
+    //   distillOnlyRefs     — reflect-cooled, distill-cooldown expired, is a distill
+    //                         candidate → skip reflect but allow distill (Bug D2).
+    //   fullySkippedCount   — reflect-cooled AND (distill-cooled OR not a candidate)
+    //                         → emit synthetic skip action and exclude from further
+    //                         processing (signal/sort never sees these).
+    //
+    // Bug D1: distill-cooled distill-candidates that are NOT reflect-cooled have their
+    // synthetic distill-skipped action emitted here before any LLM call or budget check.
+    // Bug B1: synthetic skip emissions for the fully-skipped bucket happen here so
+    // telemetry (improve_skipped events with reason=reflect_cooldown/distill_cooldown)
+    // remains accurate even though these refs do not enter ranking.
+    const DISTILL_COOLDOWN_DAYS_PREFILT = options.distillCooldownDays ?? 1;
+    const eligibleRefs = [];
+    const distillOnlyRefs = [];
+    let fullySkippedCount = 0;
+    const preCooldownCount = postCleanupRefs.length;
+    // O-2 (#365): When the user explicitly targets a single ref via `--scope`,
+    // their intent is unambiguous — they want a fresh evaluation now. Cooldown
+    // policies are designed for unattended nightly runs; silently blocking an
+    // explicit retry violates the principle of least surprise (Sagas, 1987).
+    const scopeRefBypass = scope.mode === "ref";
+    for (const r of postCleanupRefs) {
+        if (validationFailureRefs.has(r.ref))
+            continue;
+        // When --scope <ref> is active, bypass all cooldown checks for this ref.
+        if (scopeRefBypass) {
+            eligibleRefs.push(r);
+            continue;
+        }
+        const onReflectCooldown = reflectCooledRefs.has(r.ref);
+        const onDistillCooldown = DISTILL_COOLDOWN_DAYS_PREFILT > 0 && distillCooledRefs.has(r.ref);
+        // Pre-fix this read `isLessonCandidate(r.ref) || shouldDistillMemoryRef(...)`,
+        // which queued `lesson:*` refs into the distill path even though distill
+        // refuses them at runtime (DISTILL_REFUSED_INPUT_TYPES). That was pure
+        // planner waste — observed re-queuing the same 19 lessons every hourly run.
+        const isDistillCandidate = isDistillCandidateRef(r.ref, options.stashDir);
+        if (!onReflectCooldown) {
+            if (onDistillCooldown && isDistillCandidate) {
+                // Bug D1: pre-emit synthetic distill-skipped action before any LLM call.
+                actions.push({ ref: r.ref, mode: "distill-skipped", result: { ok: true, reason: "distill cooldown" } });
+                // TODO(refactor): 7 inline appendEvent calls with eventType "improve_skipped". A helper emitImproveSkipped(ref, reason, extra?) would consolidate them, but each site has slightly different metadata shape — defer until shapes converge.
+                appendEvent({
+                    eventType: "improve_skipped",
+                    ref: r.ref,
+                    metadata: { reason: "distill_cooldown", cooldownDays: DISTILL_COOLDOWN_DAYS_PREFILT },
+                }, eventsCtx);
+            }
+            // Asset is not on reflect cooldown — allow reflect (distill-cooled path
+            // already emitted its synthetic action above; the loop's distillCooledRefs
+            // guard prevents the actual distill call).
+            eligibleRefs.push(r);
+        }
+        else {
+            if (!onDistillCooldown && isDistillCandidate) {
+                // Bug D2: reflect-cooled but distill cooldown expired and is a distill candidate.
+                distillOnlyRefs.push(r);
+            }
+            else {
+                // Fully cooled or not a distill candidate — emit synthetic skip and exclude.
+                fullySkippedCount++;
+                actions.push({
+                    ref: r.ref,
+                    mode: "distill-skipped",
+                    result: { ok: true, reason: "reflect cooldown (pre-filtered)" },
+                });
+                appendEvent({ eventType: "improve_skipped", ref: r.ref, metadata: { reason: "reflect_cooldown" } }, eventsCtx);
+            }
+        }
+    }
+    // ── Phase 4: signal/feedback/utility/sort on the reduced set ──────────────
+    // Everything from here works only on (eligibleRefs ∪ distillOnlyRefs). The
+    // fully-skipped bucket has already been routed and emitted; we deliberately
+    // avoid spending DB/CPU on refs that cannot enter the loop.
+    const processableRefs = [...eligibleRefs, ...distillOnlyRefs];
+    // Gap 6: only surface feedback signals from the last 30 days so that
+    // ancient one-off feedback events don't permanently lock an asset into
+    // every improve run. Assets with only stale signals fall through to the
+    // high-retrieval path (P0-A) or are skipped until new signals arrive.
+    const FEEDBACK_SIGNAL_WINDOW_DAYS = 30;
+    const feedbackSinceCutoff = new Date(Date.now() - daysToMs(FEEDBACK_SIGNAL_WINDOW_DAYS)).toISOString();
+    // Pre-compute feedback summary per ref in a single pass so we don't issue
+    // two readEvents({type:"feedback", ref}) per asset (one for signal filtering,
+    // one for ratio computation).
+    const feedbackSummary = new Map();
+    for (const candidate of processableRefs) {
+        const { events } = readEvents({ type: "feedback", ref: candidate.ref });
+        let hasSignal = false;
+        let positive = 0;
+        let negative = 0;
+        for (const e of events) {
+            if (!hasSignal &&
+                (e.ts ?? "") >= feedbackSinceCutoff &&
+                e.metadata !== undefined &&
+                (typeof e.metadata.signal === "string" || typeof e.metadata.note === "string")) {
+                hasSignal = true;
+            }
+            if (e.metadata?.signal === "positive")
+                positive++;
+            else if (e.metadata?.signal === "negative")
+                negative++;
+        }
+        feedbackSummary.set(candidate.ref, { hasSignal, positive, negative });
+    }
+    const signalFiltered = processableRefs.filter((candidate) => feedbackSummary.get(candidate.ref)?.hasSignal === true);
+    // P0-A: also surface zero-feedback assets that have been retrieved many times.
+    const RETRIEVAL_COUNT_THRESHOLD = options.minRetrievalCount ?? 5;
+    const signalBearingSet = new Set(signalFiltered.map((r) => r.ref));
+    const noFeedbackCandidates = processableRefs.filter((r) => !signalBearingSet.has(r.ref));
+    let highRetrievalRefs = [];
+    let dbForRetrieval;
+    try {
+        dbForRetrieval = openExistingDatabase();
+        const showEventCount = dbForRetrieval.prepare("SELECT COUNT(*) AS cnt FROM usage_events WHERE event_type = 'show'").get().cnt;
+        if (showEventCount === 0) {
+            warn("Warning: show events not yet in usage_events — zero-feedback fallback will match only search-retrieved assets.");
+        }
+        const retrievalCounts = getRetrievalCounts(dbForRetrieval, noFeedbackCandidates.map((r) => r.ref));
+        highRetrievalRefs = noFeedbackCandidates.filter((r) => (retrievalCounts.get(r.ref) ?? 0) >= RETRIEVAL_COUNT_THRESHOLD);
+    }
+    catch (err) {
+        rethrowIfTestIsolationError(err);
+        // best-effort: if DB unavailable, highRetrievalRefs stays empty
+    }
+    finally {
+        if (dbForRetrieval)
+            closeDatabase(dbForRetrieval);
+    }
+    // If the user explicitly scoped to a single ref, always act on it —
+    // skip the signal/retrieval filter entirely. The filter exists to avoid
+    // noisy "improve everything" runs; it should not gate an intentional
+    // per-ref invocation where the user's explicit choice is the signal.
+    //
+    // For type/all scope: only process refs with usage signals (recent feedback
+    // or sufficient retrievals). A stash with no signals has 0 eligible refs —
+    // usage is the gate. Run `akm feedback <ref> --positive` or retrieve assets
+    // to bring them into the eligible pool.
+    const signalAndRetrievalRefs = [...signalFiltered, ...highRetrievalRefs];
+    const mergedRefs = scope.mode === "ref" ? processableRefs : options.requireFeedbackSignal ? signalFiltered : signalAndRetrievalRefs;
+    const utilityMap = buildUtilityMap(mergedRefs);
+    // Load feedback ratio per ref from the pre-computed summary (no extra DB pass).
+    const feedbackRatios = new Map();
+    for (const ref of mergedRefs) {
+        const summary = feedbackSummary.get(ref.ref);
+        const positive = summary?.positive ?? 0;
+        const negative = summary?.negative ?? 0;
+        const total = positive + negative;
+        // ratio = negative proportion (high = needs more improvement)
+        feedbackRatios.set(ref.ref, total > 0 ? negative / total : 0);
+    }
+    // Sort: combine utility (desc) with feedback negativity (desc) — high-negative assets rank higher
+    const sorted = [...mergedRefs].sort((a, b) => {
+        const utilA = utilityMap.get(a.ref) ?? 0;
+        const utilB = utilityMap.get(b.ref) ?? 0;
+        const ratioA = feedbackRatios.get(a.ref) ?? 0;
+        const ratioB = feedbackRatios.get(b.ref) ?? 0;
+        // Combined score: 70% utility, 30% negative ratio
+        const scoreA = utilA * 0.7 + ratioA * 0.3;
+        const scoreB = utilB * 0.7 + ratioB * 0.3;
+        return scoreB - scoreA;
+    });
+    // Phase 0: surface coverage gaps from zero-result search queries
+    let coverageGaps = [];
+    try {
+        const dbForGaps = openExistingDatabase();
+        try {
+            coverageGaps = getZeroResultSearches(dbForGaps);
+        }
+        finally {
+            closeDatabase(dbForGaps);
+        }
+    }
+    catch (err) {
+        rethrowIfTestIsolationError(err);
+        // best-effort
+    }
+    // actionableRefs is the post-cooldown, post-validation, post-signal, post-sort
+    // set — i.e. the genuinely processable refs in priority order. Note: this is
+    // a semantic shift from earlier code where actionableRefs was the pre-cooldown
+    // sorted set; the new meaning matches reality and is documented on
+    // ImprovePreparationResult.actionableRefs.
+    //
+    // Final guard: drop any candidate whose backing file is no longer on disk.
+    // Phase 1 validation captures missing files at the start of preparation, but
+    // the gap between that check and dispatch can be minutes on large stashes —
+    // long enough for a checkpoint / git checkout / external cleanup to delete
+    // the asset. Empirically (improve-critical-review 2026-05-20) the single
+    // biggest reject category was "Asset no longer exists on disk" (604/1407 =
+    // 43%), meaning reflect/distill was producing proposals against deleted refs.
+    // A cheap existsSync per surviving candidate eliminates that wasted work.
+    const assetMissingOnDisk = [];
+    const existsCheckedActionable = [];
+    for (const candidate of sorted) {
+        const filePath = await findAssetFilePath(candidate.ref, options.stashDir);
+        if (filePath && fs.existsSync(filePath)) {
+            existsCheckedActionable.push(candidate);
+        }
+        else {
+            assetMissingOnDisk.push(candidate.ref);
+            appendEvent({ eventType: "improve_skipped", ref: candidate.ref, metadata: { reason: "asset_missing_on_disk" } }, eventsCtx);
+        }
+    }
+    const actionableRefs = existsCheckedActionable;
+    // Re-split actionableRefs (sorted) into reflect-path vs distill-only-path while
+    // preserving sort order. distillOnlyRefs participate in the sort so --limit
+    // picks them by score, not by arbitrary position.
+    const distillOnlyRefSetForSort = new Set(distillOnlyRefs.map((r) => r.ref));
+    const reflectAndDistillRefsAfterSort = [];
+    const distillOnlyRefsAfterSort = [];
+    for (const r of actionableRefs) {
+        if (distillOnlyRefSetForSort.has(r.ref)) {
+            distillOnlyRefsAfterSort.push(r);
+        }
+        else {
+            reflectAndDistillRefsAfterSort.push(r);
+        }
+    }
+    // ── Phase 5: --limit applies to the post-cooldown actionable set ──────────
+    const allLoopRefs = [...reflectAndDistillRefsAfterSort, ...distillOnlyRefsAfterSort];
+    const loopRefs = options.limit ? allLoopRefs.slice(0, options.limit) : allLoopRefs;
+    // Update the returned distillOnlyRefs to the sorted order so callers see the
+    // ranked view (loop stage uses it as a Set so order is irrelevant, but the
+    // shape change keeps downstream consumers consistent).
+    const distillOnlyRefsResult = distillOnlyRefsAfterSort;
+    const totalReflectCooled = fullySkippedCount + distillOnlyRefs.length;
+    if (totalReflectCooled > 0) {
+        info(`[improve] ${totalReflectCooled} of ${preCooldownCount} indexed refs on reflect cooldown ` +
+            `(${fullySkippedCount} fully skipped, ${distillOnlyRefs.length} routed to distill-only)`);
+    }
+    if (signalAndRetrievalRefs.length > 0) {
+        info(`[improve] ${signalAndRetrievalRefs.length} refs with usage signals (${signalFiltered.length} feedback, ${highRetrievalRefs.length} high-retrieval)`);
+    }
+    if (validationFailureRefs.size > 0) {
+        info(`[improve] ${validationFailureRefs.size} with validation failures excluded`);
+    }
+    if (assetMissingOnDisk.length > 0) {
+        info(`[improve] ${assetMissingOnDisk.length} candidates dropped — file not on disk`);
+    }
+    const deferredCount = actionableRefs.length - loopRefs.length;
+    info(`[improve] ${actionableRefs.length} actionable; ${loopRefs.length} will be processed` +
+        (options.limit && deferredCount > 0 ? ` (--limit ${options.limit} applied; ${deferredCount} deferred)` : ""));
+    return {
+        actions,
+        cleanupWarnings,
+        appliedCleanup,
+        memoryIndexHealth,
+        executionLogCandidates,
+        actionableRefs,
+        signalBearingSet,
+        validationFailures,
+        schemaRepairs,
+        lintSummary,
+        loopRefs,
+        distillCooledRefs,
+        distillOnlyRefs: distillOnlyRefsResult,
+        coverageGaps,
+        recentErrors,
+        utilityMap,
+    };
+}
+// TODO(refactor): 13 args including `actions`/`recentErrors` mutation channels. Restructure into immutable plan + mutable context objects — deferred to dedicated refactor with isolated testing.
+async function runImproveLoopStage(args) {
+    const { scope, options, primaryStashDir, reflectFn, distillFn, loopRefs, actions, signalBearingSet, distillCooledRefs, distillOnlyRefs, recentErrors, rejectedProposalsByRef, utilityMap, startMs, budgetMs, eventsCtx, improveProfile, } = args;
+    // O-1 (#364): compute remaining budget at call time so each sub-call
+    // receives only its fair share of the wall-clock budget.
+    const remainingBudgetMs = () => Math.max(0, budgetMs - (Date.now() - startMs));
+    const RECENT_ERRORS_CAP = 3;
+    // R-2 / #389: Self-Consistency multi-sample voting helpers.
+    // Wang et al. arXiv:2203.11171 — N=3 samples beat single-shot on reasoning tasks.
+    const SC_THRESHOLD = options.selfConsistencyThreshold ?? 0.7;
+    const SC_N = Math.min(Math.max(2, options.selfConsistencyN ?? 3), 5);
+    /**
+     * Compute Jaccard token overlap between two strings.
+     * Tokenizes by whitespace; returns 0 when both are empty.
+     */
+    function jaccardSimilarity(a, b) {
+        const tokensA = new Set(a.split(/\s+/).filter(Boolean));
+        const tokensB = new Set(b.split(/\s+/).filter(Boolean));
+        if (tokensA.size === 0 && tokensB.size === 0)
+            return 1;
+        let intersection = 0;
+        for (const t of tokensA) {
+            if (tokensB.has(t))
+                intersection++;
+        }
+        const union = tokensA.size + tokensB.size - intersection;
+        return union > 0 ? intersection / union : 0;
+    }
+    /**
+     * Given N reflect results, return the one with the highest average Jaccard
+     * similarity to all other successful results (majority-vote winner).
+     * Falls back to the first successful result when N < 2.
+     */
+    function pickMajorityVote(results) {
+        const successful = results.filter((r) => r.ok);
+        if (successful.length === 0)
+            return (results[0] ?? {
+                schemaVersion: 1,
+                ok: false,
+                reason: "non_zero_exit",
+                error: "all samples failed",
+                exitCode: null,
+            });
+        if (successful.length === 1)
+            return successful[0];
+        let bestIdx = 0;
+        let bestScore = -1;
+        for (let i = 0; i < successful.length; i++) {
+            let totalSim = 0;
+            for (let j = 0; j < successful.length; j++) {
+                if (i === j)
+                    continue;
+                totalSim += jaccardSimilarity(successful[i].proposal.payload.content ?? "", successful[j].proposal.payload.content ?? "");
+            }
+            const avgSim = totalSim / (successful.length - 1);
+            if (avgSim > bestScore) {
+                bestScore = avgSim;
+                bestIdx = i;
+            }
+        }
+        return successful[bestIdx] ?? successful[0];
+    }
+    // O-5 / #378: helper to push per-originator errors into the rolling window.
+    function pushRecentError(originator, msg) {
+        if (!recentErrors[originator])
+            recentErrors[originator] = [];
+        recentErrors[originator].push(msg);
+        if (recentErrors[originator].length > RECENT_ERRORS_CAP)
+            recentErrors[originator].shift();
+    }
+    // Build a Set for O(1) membership test — these refs skip the reflect call (Bug D2).
+    const distillOnlyRefSet = new Set(distillOnlyRefs.map((r) => r.ref));
+    let completedCount = 0;
+    let reflectsWithErrorContext = 0;
+    const memoryRefsForInference = new Set();
+    // Pre-load all pending proposals once instead of querying per asset in the loop.
+    const dedupeStashDirForProposals = primaryStashDir ?? options.stashDir;
+    const pendingProposalRefSet = new Set(dedupeStashDirForProposals
+        ? listProposals(dedupeStashDirForProposals, { status: "pending" }).map((p) => p.ref)
+        : []);
+    for (const planned of loopRefs) {
+        if (Date.now() - startMs >= budgetMs) {
+            const remaining = loopRefs.length - completedCount;
+            info(`[improve] budget exhausted after ${Math.round((Date.now() - startMs) / 60000)}min — ${remaining} assets skipped`);
+            appendEvent({
+                eventType: "improve_skipped",
+                ref: planned.ref,
+                metadata: {
+                    reason: "budget_exhausted",
+                    remaining,
+                },
+            }, eventsCtx);
+            // B11: Emit improve_skipped for all remaining assets that will not be processed.
+            for (const remainingRef of loopRefs.slice(completedCount + 1)) {
+                appendEvent({
+                    eventType: "improve_skipped",
+                    ref: remainingRef.ref,
+                    metadata: { reason: "budget_exhausted_batch", remaining: loopRefs.length - completedCount - 1 },
+                }, eventsCtx);
+            }
+            actions.push({
+                ref: planned.ref,
+                mode: "error",
+                result: { ok: false, error: "timeout: improve wall-clock budget exhausted" },
+            });
+            break;
+        }
+        try {
+            // Bug D2: distillOnlyRefs skip the reflect call but still run the distill path.
+            // Bug D1: in-loop distill-cooldown check removed — distill-cooled candidates
+            //         have their synthetic actions emitted in runImprovePreparationStage.
+            const isDistillOnly = distillOnlyRefSet.has(planned.ref);
+            const parsedPlannedRef = parseAssetRef(planned.ref);
+            // B6: derived memories are machine-generated; skip reflect to avoid noisy proposals.
+            // shouldDistillMemoryRef already returns false for .derived refs, so the distill
+            // path is also a no-op for them — we just avoid unnecessary agent spawns.
+            // D2: distillOnlyRefs also skip the reflect call (reflect-cooled, distill path only).
+            if (!isDistillOnly && !planned.ref.endsWith(".derived")) {
+                // Type guard: skip reflect for unsupported types (script, vault, task, etc.)
+                // and raw wiki directories, driven by the active improve profile.
+                const reflectSkip = shouldSkipRef(planned.ref, "reflect", improveProfile);
+                if (reflectSkip.skip) {
+                    actions.push({
+                        ref: planned.ref,
+                        mode: "reflect-skipped",
+                        result: { ok: true, reason: reflectSkip.reason },
+                    });
+                }
+                else {
+                    // O-5 / #378: only inject reflect-originator errors into the reflect call.
+                    // Cross-task errors (e.g. schema-repair) must NOT contaminate reflect prompts.
+                    const reflectErrors = recentErrors.reflect ?? [];
+                    if (reflectErrors.length > 0)
+                        reflectsWithErrorContext++;
+                    // O-1 (#364): pass remaining budget as timeoutMs so the agent spawn is
+                    // bounded by the wall-clock deadline rather than the default per-profile timeout.
+                    const reflectBudgetMs = remainingBudgetMs();
+                    // Wire profile.processes.reflect.{mode, profile, timeoutMs} into the reflect
+                    // dispatch when present. Falls back to akmReflect's own config-based resolution
+                    // (profiles.improve.<name>.processes.reflect → defaults.llm) when the profile
+                    // does not specify.
+                    const reflectProfileRunner = resolveImproveProcessRunnerFromProfile(improveProfile.processes?.reflect, options.config ?? loadConfig());
+                    const reflectCallArgs = {
+                        ref: planned.ref,
+                        task: options.task,
+                        ...(options.stashDir ? { stashDir: options.stashDir } : {}),
+                        ...(reflectErrors.length > 0 ? { avoidPatterns: [...reflectErrors] } : {}),
+                        agentProcess: options.agentProcess ?? "reflect",
+                        eventSource: "improve",
+                        ...(reflectBudgetMs > 0 ? { timeoutMs: reflectBudgetMs } : {}),
+                        ...(reflectProfileRunner ? { runner: reflectProfileRunner } : {}),
+                    };
+                    // R-2 / #389: Self-consistency multi-sample voting for high-utility refs.
+                    // Self-Consistency arXiv:2203.11171 — N=3 samples beat single-shot quality.
+                    const refUtility = utilityMap.get(planned.ref) ?? 0;
+                    const useConsistency = refUtility >= SC_THRESHOLD && SC_N >= 2;
+                    let reflectResult;
+                    if (useConsistency) {
+                        const samples = [];
+                        for (let s = 0; s < SC_N; s++) {
+                            if (remainingBudgetMs() <= 0)
+                                break;
+                            // draftMode: skip DB write so each sample doesn't create a proposal.
+                            samples.push(await reflectFn({ ...reflectCallArgs, draftMode: true }));
+                        }
+                        const winner = pickMajorityVote(samples.length > 0 ? samples : [await reflectFn({ ...reflectCallArgs, draftMode: true })]);
+                        // Persist only the majority-vote winner as a single real proposal.
+                        if (winner.ok && primaryStashDir) {
+                            const persistResult = createProposal(primaryStashDir, {
+                                ref: winner.proposal.ref,
+                                source: "reflect",
+                                sourceRun: `reflect-sc-${Date.now()}`,
+                                payload: winner.proposal.payload,
+                            });
+                            reflectResult = isProposalSkipped(persistResult)
+                                ? {
+                                    schemaVersion: 1,
+                                    ok: false,
+                                    reason: "cooldown",
+                                    error: `SC proposal skipped: ${persistResult.message}`,
+                                    ref: winner.ref,
+                                    exitCode: null,
+                                }
+                                : { ...winner, proposal: persistResult };
+                        }
+                        else {
+                            reflectResult = winner;
+                        }
+                    }
+                    else {
+                        reflectResult = await reflectFn(reflectCallArgs);
+                    }
+                    const isCooldown = !reflectResult.ok && reflectResult.reason === "cooldown";
+                    actions.push({
+                        ref: planned.ref,
+                        mode: reflectResult.ok ? "reflect" : isCooldown ? "reflect-cooldown" : "reflect-failed",
+                        result: reflectResult,
+                    });
+                    // Cooldown skips are not failures — do not pollute recentErrors with them
+                    // (those get injected as `avoidPatterns` into the next reflect prompt).
+                    if (!reflectResult.ok && !isCooldown) {
+                        const errMsg = reflectResult.error ?? reflectResult.reason ?? "unknown reflect error";
+                        pushRecentError("reflect", errMsg);
+                    }
+                    // improve_reflect_outcome — per-asset metric for tuning the reflect path.
+                    appendEvent({
+                        eventType: "improve_reflect_outcome",
+                        ref: planned.ref,
+                        metadata: {
+                            ok: reflectResult.ok,
+                            durationMs: reflectResult.ok ? reflectResult.durationMs : undefined,
+                            agentProfile: reflectResult.ok ? reflectResult.agentProfile : undefined,
+                            reason: reflectResult.ok ? undefined : reflectResult.reason,
+                        },
+                    }, eventsCtx);
+                    // Phase 6A (Advantage D6a): Confidence-driven auto-accept.
+                    //
+                    // The existing `--auto-accept` flag (commit 0c5eaa1) is a 0-100 integer
+                    // threshold; `undefined` means auto-accept is disabled. Until this
+                    // wave, the consolidate path treated any non-undefined value as a
+                    // whole-batch "safe" accept (see TODO in consolidate.ts). Now that
+                    // reflect proposals carry a self-reported `confidence` score in
+                    // [0, 1], we can compare per-proposal: confidence >= threshold/100
+                    // auto-accepts via the standard `promoteProposal` path; otherwise the
+                    // proposal waits in the pending queue for human review.
+                    //
+                    // Plan default is 0.8 (per `self-improvement-enhancements-plan.md`
+                    // line 184). We honour the existing CLI default (90 → 0.9) because
+                    // that is what users have been seeing since 0c5eaa1; the plan and the
+                    // existing default agree directionally that high-confidence-only is
+                    // the right policy. The CLI flag is the single knob.
+                    if (reflectResult.ok &&
+                        options.autoAccept !== undefined &&
+                        typeof reflectResult.proposal.confidence === "number" &&
+                        primaryStashDir) {
+                        const threshold = options.autoAccept / 100;
+                        const confidence = reflectResult.proposal.confidence;
+                        if (confidence >= threshold) {
+                            try {
+                                const cfg = options.config ?? loadConfig();
+                                const promotion = await promoteProposal(primaryStashDir, cfg, reflectResult.proposal.id, {}, undefined);
+                                appendEvent({
+                                    eventType: "promoted",
+                                    ref: promotion.ref,
+                                    metadata: {
+                                        proposalId: promotion.proposal.id,
+                                        source: promotion.proposal.source,
+                                        ...(promotion.proposal.sourceRun !== undefined
+                                            ? { sourceRun: promotion.proposal.sourceRun }
+                                            : {}),
+                                        assetPath: promotion.assetPath,
+                                        autoAccept: true,
+                                        confidence,
+                                        threshold,
+                                    },
+                                }, eventsCtx);
+                                info(`[improve] auto-accepted ${promotion.ref} (confidence=${confidence.toFixed(2)} >= threshold=${threshold.toFixed(2)})`);
+                            }
+                            catch (err) {
+                                // Auto-accept failures (validation, write error, etc.) must not
+                                // poison the loop — surface a warning and leave the proposal
+                                // pending so the reviewer can deal with it manually.
+                                warn(`[improve] auto-accept failed for ${reflectResult.proposal.ref}: ${err instanceof Error ? err.message : String(err)}`);
+                            }
+                        }
+                    }
+                } // end else (reflect type/profile check)
+            }
+            else if (!isDistillOnly && planned.ref.endsWith(".derived")) {
+                // B6: .derived refs skip reflect; record synthetic skip action.
+                actions.push({
+                    ref: planned.ref,
+                    mode: "distill-skipped",
+                    result: { ok: true, reason: "derived-memory-reflect-skipped" },
+                });
+                appendEvent({
+                    eventType: "improve_skipped",
+                    ref: planned.ref,
+                    metadata: { reason: "derived_memory_reflect_skipped" },
+                }, eventsCtx);
+            }
+            // isDistillOnly refs: no reflect action emitted — proceed directly to distill path below.
+            const hasRecentFeedbackSignal = signalBearingSet.has(planned.ref);
+            const explicitRefScope = scope.mode === "ref";
+            // Profile gate: apply the full type-filter / raw-wiki / disabled rules to
+            // distill so callers who configure `profile.processes.distill.allowedTypes`
+            // or land on raw-wiki refs get a recorded skip action instead of silently
+            // proceeding.
+            const distillSkip = shouldSkipRef(planned.ref, "distill", improveProfile);
+            if (distillSkip.skip) {
+                actions.push({
+                    ref: planned.ref,
+                    mode: "distill-skipped",
+                    result: { ok: true, reason: distillSkip.reason },
+                });
+                completedCount++;
+                info(`[improve] ${completedCount}/${loopRefs.length} ${planned.ref}`);
+                continue;
+            }
+            // See `isDistillCandidateRef` — excludes `lesson:*` (and anything else in
+            // DISTILL_REFUSED_INPUT_TYPES) so distill never gets queued for an input
+            // it will refuse.
+            const shouldAttemptDistill = isDistillCandidateRef(planned.ref, options.stashDir);
+            const skipMemoryDistillForWeakSignal = !isDistillOnly && parsedPlannedRef.type === "memory" && !hasRecentFeedbackSignal && !explicitRefScope;
+            // distillCooledRefs guard: pre-filter emitted synthetic actions for distill-candidate
+            // refs; non-candidate refs in the set are blocked here.
+            // O-2 (#365): bypass the distill cooldown when the user explicitly targeted
+            // this ref via --scope — their intent overrides unattended-run policies.
+            if (shouldAttemptDistill &&
+                !skipMemoryDistillForWeakSignal &&
+                (!distillCooledRefs.has(planned.ref) || explicitRefScope)) {
+                // TODO(refactor): single call site needs both lesson+knowledge refs for proposal dedup. If a third target ref type is added, extract deriveAllTargetRefs(inputRef): string[].
+                const lessonRef = deriveLessonRef(planned.ref);
+                const knowledgeRef = deriveKnowledgeRef(planned.ref);
+                const dedupeStashDir = primaryStashDir ?? options.stashDir;
+                if (dedupeStashDir) {
+                    // B2: check both lesson ref and knowledge ref since auto-promoted memories
+                    // create knowledge: proposals, not lesson: proposals.
+                    const hasExistingPending = pendingProposalRefSet.has(lessonRef) || pendingProposalRefSet.has(knowledgeRef);
+                    if (hasExistingPending) {
+                        actions.push({
+                            ref: planned.ref,
+                            mode: "distill-skipped",
+                            result: { ok: true, reason: "pending proposal exists" },
+                        });
+                        appendEvent({
+                            eventType: "improve_skipped",
+                            ref: planned.ref,
+                            metadata: { reason: "pending_proposal_exists" },
+                        }, eventsCtx);
+                        completedCount++;
+                        info(`[improve] ${completedCount}/${loopRefs.length} ${planned.ref}`);
+                        continue;
+                    }
+                    // D-2 (#370): reject-aware cooldown for distill. When the reviewer
+                    // recently rejected a distilled lesson or knowledge proposal for this
+                    // asset, skip re-distillation for DISTILL_REJECT_COOLDOWN_DAYS.
+                    // Prevents the same rejected proposal from returning the next day.
+                    // References: ExpeL arXiv:2308.10144, STaR arXiv:2203.14465.
+                    const DISTILL_REJECT_COOLDOWN_MS = daysToMs(options.distillCooldownDays ?? 1);
+                    const recentlyRejectedLesson = DISTILL_REJECT_COOLDOWN_MS > 0 &&
+                        !explicitRefScope && // O-2: bypass when --scope <ref> is explicit
+                        (rejectedProposalsByRef.has(lessonRef) || rejectedProposalsByRef.has(knowledgeRef));
+                    if (recentlyRejectedLesson) {
+                        const rejectedEntry = rejectedProposalsByRef.get(lessonRef) ?? rejectedProposalsByRef.get(knowledgeRef);
+                        const rejectedAgeMs = rejectedEntry ? Date.now() - new Date(rejectedEntry.ts).getTime() : 0;
+                        if (rejectedAgeMs < DISTILL_REJECT_COOLDOWN_MS) {
+                            actions.push({
+                                ref: planned.ref,
+                                mode: "distill-skipped",
+                                result: { ok: true, reason: "distill reject cooldown" },
+                            });
+                            appendEvent({
+                                eventType: "improve_skipped",
+                                ref: planned.ref,
+                                metadata: {
+                                    reason: "distill_reject_cooldown",
+                                    cooldownDays: options.distillCooldownDays ?? 1,
+                                },
+                            }, eventsCtx);
+                            completedCount++;
+                            info(`[improve] ${completedCount}/${loopRefs.length} ${planned.ref}`);
+                            continue;
+                        }
+                    }
+                }
+                const distillResult = await distillFn({
+                    ref: planned.ref,
+                    ...(parsedPlannedRef.type === "memory" ? { proposalKind: "auto" } : {}),
+                    ...(options.stashDir ? { stashDir: options.stashDir } : {}),
+                });
+                actions.push({ ref: planned.ref, mode: "distill", result: distillResult });
+                if (parsedPlannedRef.type === "memory") {
+                    const promotedToKnowledge = distillResult.outcome === "queued" && distillResult.proposalKind === "knowledge";
+                    if (!promotedToKnowledge)
+                        memoryRefsForInference.add(planned.ref);
+                }
+                if (distillResult.outcome === "quality_rejected" && primaryStashDir) {
+                    const slug = planned.ref
+                        .replace(/[^a-z0-9]/gi, "-")
+                        .toLowerCase()
+                        .slice(0, 60);
+                    writeEvalCase(primaryStashDir, {
+                        ref: planned.ref,
+                        failureReason: distillResult.reason ?? "quality gate rejected",
+                        assetType: parseAssetRef(planned.ref).type ?? "unknown",
+                        rejectedAt: Date.now(),
+                        source: "distill_quality_rejected",
+                        slug: `${slug}-${Date.now()}`,
+                    });
+                }
+                // D6: use pre-loaded map instead of per-iteration DB query
+                const rejectedProposalEvent = rejectedProposalsByRef.get(planned.ref);
+                if (rejectedProposalEvent && primaryStashDir) {
+                    const slug = planned.ref
+                        .replace(/[^a-z0-9]/gi, "-")
+                        .toLowerCase()
+                        .slice(0, 60);
+                    writeEvalCase(primaryStashDir, {
+                        ref: planned.ref,
+                        failureReason: rejectedProposalEvent.metadata?.reason ?? "proposal rejected",
+                        assetType: parseAssetRef(planned.ref).type ?? "unknown",
+                        rejectedAt: new Date(rejectedProposalEvent.ts).getTime(),
+                        source: "proposal_rejected",
+                        slug: `${slug}-rejected`,
+                    });
+                }
+            }
+            else if (skipMemoryDistillForWeakSignal) {
+                actions.push({
+                    ref: planned.ref,
+                    mode: "distill-skipped",
+                    result: { ok: true, reason: "memory requires recent feedback signal" },
+                });
+                appendEvent({
+                    eventType: "improve_skipped",
+                    ref: planned.ref,
+                    metadata: { reason: "memory_distill_requires_feedback" },
+                }, eventsCtx);
+            }
+        }
+        catch (err) {
+            // B7: UsageError thrown by akmDistill on validation_failed should be recorded
+            // as mode:"distill" with outcome:"validation_failed", NOT as a generic error.
+            // The distill_invoked event was already emitted inside akmDistill before the throw.
+            if (err instanceof UsageError) {
+                actions.push({
+                    ref: planned.ref,
+                    mode: "distill",
+                    result: { ok: false, outcome: "validation_failed", error: err.message },
+                });
+            }
+            else {
+                actions.push({
+                    ref: planned.ref,
+                    mode: "error",
+                    result: { ok: false, error: err instanceof Error ? err.message : String(err) },
+                });
+            }
+        }
+        completedCount++;
+        info(`[improve] ${completedCount}/${loopRefs.length} ${planned.ref}`);
+    }
+    return { reflectsWithErrorContext, memoryRefsForInference };
+}
+async function runImprovePostLoopStage(args) {
+    const { scope, options, primaryStashDir, actionableRefs, appliedCleanup, cleanupWarnings, memorySummary, memoryRefsForInference, reindexFn, eventsCtx, budgetSignal, improveProfile, } = args;
+    const allWarnings = [...cleanupWarnings, ...(appliedCleanup?.warnings ?? [])];
+    const baseConfig = options.config ?? loadConfig();
+    const MEMORY_VOLUME_THRESHOLD = options.memoryVolumeConsolidationThreshold ?? 100;
+    const hasLlm = !!(baseConfig.defaults?.llm || baseConfig.defaults?.agent);
+    const volumeTriggered = typeof memorySummary.eligible === "number" && memorySummary.eligible > MEMORY_VOLUME_THRESHOLD && hasLlm;
+    // When volume triggers a consolidation pass, force-enable the consolidate
+    // process on the default improve profile so the gate accepts the run even
+    // if the user's config disabled it. We synthesise a new profile override
+    // rather than mutating connection settings.
+    const consolidationConfig = volumeTriggered
+        ? {
+            ...baseConfig,
+            profiles: {
+                ...(baseConfig.profiles ?? {}),
+                improve: {
+                    ...(baseConfig.profiles?.improve ?? {}),
+                    default: {
+                        ...(baseConfig.profiles?.improve?.default ?? {}),
+                        processes: {
+                            ...(baseConfig.profiles?.improve?.default?.processes ?? {}),
+                            consolidate: {
+                                ...(baseConfig.profiles?.improve?.default?.processes?.consolidate ?? {}),
+                                enabled: true,
+                            },
+                        },
+                    },
+                },
+            },
+        }
+        : baseConfig;
+    // TODO(refactor): the reflect/distill cooldown above and this consolidation gate share the "is the most recent event of type X within window" pattern. Unifying would muddy the per-ref tier logic above — defer.
+    const consolidateCooldownDays = options.consolidateCooldownDays ?? 14;
+    const CONSOLIDATE_COOLDOWN_MS = daysToMs(consolidateCooldownDays);
+    const consolidationCutoff = new Date(Date.now() - CONSOLIDATE_COOLDOWN_MS).toISOString();
+    const recentConsolidations = readEvents({ type: "consolidate_completed", since: consolidationCutoff });
+    const lastConsolidation = recentConsolidations.events
+        .filter((e) => e.metadata?.processed && Number(e.metadata.processed) > 0)
+        .sort((a, b) => new Date(b.ts ?? 0).getTime() - new Date(a.ts ?? 0).getTime())[0];
+    const consolidationOnCooldown = !volumeTriggered &&
+        consolidateCooldownDays > 0 &&
+        lastConsolidation?.ts &&
+        Date.now() - new Date(lastConsolidation.ts).getTime() < CONSOLIDATE_COOLDOWN_MS;
+    // Profile gate: if profile explicitly disables consolidate, skip the entire pass.
+    const consolidateDisabledByProfile = improveProfile?.processes?.consolidate?.enabled === false;
+    let consolidation = {
+        schemaVersion: 1,
+        ok: true,
+        shape: "consolidate-result",
+        dryRun: false,
+        previewOnly: false,
+        target: "",
+        processed: 0,
+        merged: 0,
+        deleted: 0,
+        promoted: [],
+        contradicted: 0,
+        warnings: [],
+        durationMs: 0,
+    };
+    if (consolidateDisabledByProfile) {
+        info("[improve] consolidation skipped (disabled by improve profile)");
+    }
+    else if (!consolidationOnCooldown) {
+        consolidation = await akmConsolidate({
+            ...options.consolidateOptions,
+            config: consolidationConfig,
+            stashDir: options.stashDir,
+            autoTriggered: volumeTriggered,
+            // Honor profile.autoAccept (already merged into options.autoAccept at the
+            // top of akmImprove). The CLI parser always supplies 90 when --auto-accept
+            // is absent, so ?? 90 is not needed here and would prevent --auto-accept=false
+            // (which maps to undefined) from disabling consolidation auto-accept.
+            // options.consolidateOptions.autoAccept (if explicitly provided by caller)
+            // still wins because the spread above runs first.
+            autoAccept: options.consolidateOptions?.autoAccept ?? options.autoAccept,
+        });
+        if (consolidation.processed > 0) {
+            appendEvent({
+                eventType: "consolidate_completed",
+                ref: "memory:_consolidation",
+                metadata: { processed: consolidation.processed, merged: consolidation.merged },
+            }, eventsCtx);
+        }
+    }
+    else {
+        const daysAgo = Math.round((Date.now() - new Date(lastConsolidation?.ts ?? 0).getTime()) / 86400000);
+        appendEvent({
+            eventType: "improve_skipped",
+            ref: "memory:_consolidation",
+            metadata: {
+                reason: "consolidation_cooldown",
+                cooldownDays: consolidateCooldownDays,
+                lastEventTs: lastConsolidation?.ts ?? null,
+            },
+        }, eventsCtx);
+        info(`[improve] consolidation skipped (last ran ${daysAgo}d ago, cooldown ${consolidateCooldownDays}d)`);
+    }
+    // D9: track whether consolidation wrote any data so graph extraction can reindex if needed
+    const consolidationRan = !consolidateDisabledByProfile && !consolidationOnCooldown && consolidation.processed > 0;
+    info("[improve] post-loop maintenance starting");
+    const maintenanceResult = await runImproveMaintenancePasses({
+        options,
+        primaryStashDir,
+        actionableRefs,
+        memoryRefsForInference,
+        allWarnings,
+        reindexFn,
+        consolidationRan,
+        // O-1 (#364): forward the budget signal to memory inference + graph extraction.
+        budgetSignal,
+        eventsCtx,
+        improveProfile,
+    });
+    let deadUrls;
+    if (scope.mode === "all" && primaryStashDir && actionableRefs.length > 0) {
+        try {
+            const knowledgeEntries = actionableRefs
+                .filter((r) => {
+                try {
+                    return parseAssetRef(r.ref).type === "knowledge";
+                }
+                catch {
+                    return false;
+                }
+            })
+                .slice(0, 10)
+                .map((r) => ({ ref: r.ref, body: "" }));
+            if (knowledgeEntries.length > 0) {
+                info(`[improve] checking URLs in ${knowledgeEntries.length} knowledge refs`);
+                deadUrls = await checkDeadUrls(primaryStashDir, knowledgeEntries);
+                info(`[improve] URL check complete (${deadUrls.length} dead/timeout URLs)`);
+            }
+        }
+        catch {
+            // best-effort
+        }
+    }
+    return {
+        allWarnings,
+        consolidation,
+        deadUrls,
+        ...(maintenanceResult.memoryInference ? { memoryInference: maintenanceResult.memoryInference } : {}),
+        ...(maintenanceResult.graphExtraction ? { graphExtraction: maintenanceResult.graphExtraction } : {}),
+        ...(maintenanceResult.stalenessDetection ? { stalenessDetection: maintenanceResult.stalenessDetection } : {}),
+        ...(maintenanceResult.actions && maintenanceResult.actions.length > 0
+            ? { maintenanceActions: maintenanceResult.actions }
+            : {}),
+        memoryInferenceDurationMs: maintenanceResult.memoryInferenceDurationMs,
+        graphExtractionDurationMs: maintenanceResult.graphExtractionDurationMs,
+        orphansPurged: maintenanceResult.orphansPurged,
+        proposalsExpired: maintenanceResult.proposalsExpired,
+    };
+}
+// TODO(refactor): mutates the passed-in `allWarnings` array as a hidden side channel. Return warnings in ImproveMaintenanceResult and merge in caller — invasive signature change deferred to next refactor pass.
+async function runImproveMaintenancePasses(args) {
+    const { options, primaryStashDir, memoryRefsForInference, allWarnings, reindexFn, consolidationRan, budgetSignal, eventsCtx, improveProfile, } = args;
+    if (!primaryStashDir)
+        return { memoryInferenceDurationMs: 0, graphExtractionDurationMs: 0 };
+    const config = options.config ?? loadConfig();
+    const sources = resolveSourceEntries(options.stashDir, config);
+    const memoryInferenceFn = options.memoryInferenceFn ?? runMemoryInferencePass;
+    const graphExtractionFn = options.graphExtractionFn ?? runGraphExtractionPass;
+    const stalenessDetectionFn = options.stalenessDetectionFn ?? runStalenessDetectionPass;
+    let db;
+    let memoryInference;
+    let graphExtraction;
+    let stalenessDetection;
+    let reindexedAfterInference = false;
+    const actions = [];
+    let memoryInferenceDurationMs = 0;
+    let graphExtractionDurationMs = 0;
+    let orphansPurged = 0;
+    let proposalsExpired = 0;
+    try {
+        db = openDatabase(getDbPath(), config.embedding?.dimension ? { embeddingDim: config.embedding.dimension } : undefined);
+        // Memory inference candidate-discovery (post-Item 9 fix from
+        // memory:akm-improve-critical-review-2026-05-20). Previously this pass
+        // was gated on memoryRefsForInference.size > 0 AND passed those refs as a
+        // candidateRefs filter. But memoryRefsForInference is populated from refs
+        // distilled THIS RUN — by the time that happens, those parents are
+        // already split (`inferenceProcessed: true`) and `isPendingMemory` excludes
+        // them. The genuinely-pending parents in the stash never entered the
+        // filter. Result: 0/0/0 for 25 consecutive runs.
+        //
+        // Fix: always run the pass when the feature is enabled; let the pass's
+        // own `collectPendingMemories` + `isPendingMemory` predicate find
+        // candidates from the filesystem-of-truth. The this-run set is still
+        // logged as a hint but no longer used as a filter.
+        const memoryInferenceDisabledByProfile = improveProfile?.processes?.memoryInference?.enabled === false;
+        if (memoryInferenceDisabledByProfile) {
+            info("[improve] memory inference skipped (disabled by improve profile)");
+        }
+        else {
+            const hintRefs = memoryRefsForInference.size;
+            info(hintRefs > 0
+                ? `[improve] memory inference starting (${hintRefs} hint refs touched this run; pass discovers all pending)`
+                : "[improve] memory inference starting (discovering pending parents)");
+            const inferenceStart = Date.now();
+            try {
+                // O-1 (#364): pass budget signal so a hung inference call is cancelled.
+                memoryInference = await memoryInferenceFn(config, sources, budgetSignal, db, false, (event) => {
+                    const current = event.currentRef ? ` ${event.currentRef}` : "";
+                    info(`[improve] memory inference ${event.processed}/${event.total}${current} (written ${event.writtenFacts}, skipped ${event.skippedNoFacts})`);
+                });
+                memoryInferenceDurationMs = Date.now() - inferenceStart;
+                actions.push({ ref: "memory:_inference", mode: "memory-inference", result: memoryInference });
+                info(`[improve] memory inference complete (${memoryInference.writtenFacts} facts written from ${memoryInference.splitParents} parents)`);
+            }
+            catch (err) {
+                memoryInferenceDurationMs = Date.now() - inferenceStart;
+                allWarnings.push(`memory inference failed: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+        if (memoryInference && (memoryInference.splitParents > 0 || memoryInference.writtenFacts > 0)) {
+            info("[improve] reindexing after memory inference writes");
+            try {
+                await reindexFn({ stashDir: primaryStashDir });
+                reindexedAfterInference = true;
+                info("[improve] reindex after memory inference complete");
+            }
+            catch (err) {
+                allWarnings.push(`reindex after memory inference failed: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+        const graphEnabled = isProcessEnabled("index", "graph_extraction", config);
+        const graphExtractionDisabledByProfile = improveProfile?.processes?.graphExtraction?.enabled === false;
+        // Build the set of refs actually touched this run.
+        const touchedRefs = new Set();
+        for (const r of args.actionableRefs)
+            touchedRefs.add(r.ref);
+        for (const r of memoryRefsForInference)
+            touchedRefs.add(r);
+        // INVARIANT: graph extraction must never run on the full corpus from the
+        // improve post-loop. Full-corpus scans belong in `akm index`. We enforce
+        // this by ALWAYS passing `candidatePaths` (possibly an empty Set) to the
+        // extractor — never `undefined`. With an empty Set, the extractor's
+        // filter (graph-extraction.ts ~L452) rejects every file and returns the
+        // empty result without scanning. The pass is still invoked so that the
+        // action is recorded, the D9 post-consolidation reindex still fires, and
+        // mock injection (graphExtractionFn) used by tests stays exercised.
+        if (graphExtractionDisabledByProfile) {
+            info("[improve] graph extraction skipped (disabled by improve profile)");
+        }
+        else if (sources.length > 0 && graphEnabled) {
+            info("[improve] graph extraction starting");
+            const extractionStart = Date.now();
+            try {
+                // D9: if consolidation ran but memory inference did not reindex, force a reindex
+                // so graph extraction sees current DB state after consolidation writes.
+                if (consolidationRan && !reindexedAfterInference) {
+                    info("[improve] reindexing after consolidation (graph extraction needs current state)");
+                    try {
+                        await reindexFn({ stashDir: primaryStashDir });
+                        reindexedAfterInference = true;
+                        info("[improve] reindex after consolidation complete");
+                    }
+                    catch (err) {
+                        allWarnings.push(`reindex after consolidation failed: ${err instanceof Error ? err.message : String(err)}`);
+                    }
+                }
+                if (db && reindexedAfterInference) {
+                    closeDatabase(db);
+                    db = openDatabase(getDbPath(), config.embedding?.dimension ? { embeddingDim: config.embedding.dimension } : undefined);
+                }
+                // Resolve touched refs to absolute file paths. Empty Set is intentional
+                // when no refs were touched — see INVARIANT above.
+                const candidatePaths = new Set();
+                if (primaryStashDir && touchedRefs.size > 0) {
+                    const writableDirSet = new Set(getWritableStashDirs(primaryStashDir).map((d) => path.resolve(d)));
+                    const resolved = await Promise.all([...touchedRefs].map((ref) => findAssetFilePath(ref, primaryStashDir, writableDirSet).catch(() => null)));
+                    for (const p of resolved) {
+                        if (typeof p === "string" && p.length > 0)
+                            candidatePaths.add(p);
+                    }
+                }
+                const progressHandler = (event) => {
+                    const current = event.currentPath ? ` ${path.basename(event.currentPath)}` : "";
+                    info(`[improve] graph extraction ${event.processed}/${event.total}${current} (extracted ${event.extracted}, entities ${event.totalEntities}, relations ${event.totalRelations})`);
+                };
+                // O-1 (#364): pass budget signal so a hung graph extraction call is cancelled.
+                graphExtraction = await graphExtractionFn(config, sources, budgetSignal, db, false, progressHandler, {
+                    candidatePaths,
+                });
+                graphExtractionDurationMs = Date.now() - extractionStart;
+                actions.push({ ref: "graph:_artifact", mode: "graph-extraction", result: graphExtraction });
+                info(`[improve] graph extraction complete (${graphExtraction.quality.extractedFiles} files, ${graphExtraction.quality.entityCount} entities, ${graphExtraction.quality.relationCount} relations)`);
+            }
+            catch (err) {
+                graphExtractionDurationMs = Date.now() - extractionStart;
+                allWarnings.push(`graph extraction failed: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+        else if (sources.length > 0 && !graphEnabled) {
+            info("[improve] graph extraction skipped (features.index.graph_extraction is disabled)");
+        }
+        // Orphan proposal purge — reject pending reflect proposals whose target
+        // asset no longer exists on disk. Runs after graph extraction so newly
+        // promoted assets from accept flows during this run are already present.
+        if (primaryStashDir) {
+            try {
+                const purgeResult = purgeOrphanProposals(primaryStashDir, sources.map((s) => s.path));
+                orphansPurged = purgeResult.rejected;
+                if (purgeResult.rejected > 0) {
+                    info(`[improve] orphan purge: ${purgeResult.rejected}/${purgeResult.checked} orphaned proposals rejected (${purgeResult.durationMs}ms)`);
+                }
+                appendEvent({
+                    eventType: "proposal_orphan_purge",
+                    ref: "proposals:_orphan-purge",
+                    metadata: {
+                        checked: purgeResult.checked,
+                        rejected: purgeResult.rejected,
+                        durationMs: purgeResult.durationMs,
+                        byType: purgeResult.byType,
+                        orphans: purgeResult.orphans.map((o) => o.ref),
+                    },
+                }, eventsCtx);
+            }
+            catch (err) {
+                allWarnings.push(`orphan purge failed: ${err instanceof Error ? err.message : String(err)}`);
+            }
+            // Phase 6B (Advantage D6b): expire pending proposals that have aged past
+            // the retention window. Runs AFTER orphan purge so we never double-archive
+            // a proposal that orphan-purge already moved. `expireStaleProposals` emits
+            // its own per-proposal `proposal_expired` events; we additionally emit a
+            // single roll-up event here for parity with the orphan-purge surface.
+            try {
+                const expireResult = expireStaleProposals(primaryStashDir, config);
+                proposalsExpired = expireResult.expired;
+                if (expireResult.expired > 0) {
+                    info(`[improve] expiration: ${expireResult.expired}/${expireResult.checked} pending proposals expired ` +
+                        `(retention=${expireResult.retentionDays}d, ${expireResult.durationMs}ms)`);
+                }
+                appendEvent({
+                    eventType: "proposal_expiration_pass",
+                    ref: "proposals:_expiration",
+                    metadata: {
+                        checked: expireResult.checked,
+                        expired: expireResult.expired,
+                        durationMs: expireResult.durationMs,
+                        retentionDays: expireResult.retentionDays,
+                        expiredProposals: expireResult.expiredProposals,
+                    },
+                }, eventsCtx);
+            }
+            catch (err) {
+                allWarnings.push(`proposal expiration failed: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+        // Fix #2 (observability 0.8.0): trim the events table in state.db so it
+        // doesn't grow unbounded. `akm health` writes a `health_probe` row on every
+        // invocation, and every command surface emits at least one event besides —
+        // without this trim, state.db is a permanent append-only log. Config key
+        // `improve.eventRetentionDays` (default 90, set 0 to disable) controls the
+        // window. `purgeOldEvents()` opens its own state.db handle separate from
+        // the index `db` above (different SQLite file).
+        {
+            const retentionDays = typeof config.improve?.eventRetentionDays === "number" ? config.improve.eventRetentionDays : 90;
+            if (retentionDays > 0) {
+                let stateDb;
+                try {
+                    stateDb = openStateDatabase();
+                    const purgedCount = purgeOldEvents(stateDb, retentionDays);
+                    if (purgedCount > 0) {
+                        info(`[improve] events purge: ${purgedCount} event(s) older than ${retentionDays}d removed from state.db`);
+                    }
+                    appendEvent({
+                        eventType: "events_purged",
+                        ref: "events:_purge",
+                        metadata: { purgedCount, retentionDays },
+                    }, eventsCtx);
+                    // improve_runs uses the same retention window as events — both are
+                    // observability/audit data, both grow append-only, both have a
+                    // dedicated purge helper. Mirroring the events purge here means a
+                    // single retention knob (improve.eventRetentionDays) governs both.
+                    const improveRunsPurged = purgeOldImproveRuns(stateDb, retentionDays);
+                    if (improveRunsPurged > 0) {
+                        info(`[improve] improve_runs purge: ${improveRunsPurged} run(s) older than ${retentionDays}d removed from state.db`);
+                    }
+                    appendEvent({
+                        eventType: "improve_runs_purged",
+                        ref: "improve_runs:_purge",
+                        metadata: { purgedCount: improveRunsPurged, retentionDays },
+                    }, eventsCtx);
+                }
+                catch (err) {
+                    allWarnings.push(`events purge failed: ${err instanceof Error ? err.message : String(err)}`);
+                }
+                finally {
+                    if (stateDb) {
+                        try {
+                            stateDb.close();
+                        }
+                        catch {
+                            // best-effort
+                        }
+                    }
+                }
+            }
+        }
+        // Phase 4A (staleness detection). Activates the `deprecated` belief-state
+        // machinery shipped in Phase 1A. Default OFF — gated by
+        // `features.index.staleness_detection.enabled`. Runs after orphan purge
+        // and before the URL check (which lives in the outer caller).
+        if (sources.length > 0) {
+            try {
+                stalenessDetection = await stalenessDetectionFn(config, sources, budgetSignal, db);
+                if (stalenessDetection.considered > 0) {
+                    info(`[improve] staleness detection complete (considered ${stalenessDetection.considered}, ` +
+                        `deprecated ${stalenessDetection.deprecated}, confirmed ${stalenessDetection.confirmed}, ` +
+                        `skipped ${stalenessDetection.skipped}, ${stalenessDetection.durationMs}ms)`);
+                }
+                for (const w of stalenessDetection.warnings)
+                    allWarnings.push(`[improve] staleness detection: ${w}`);
+            }
+            catch (err) {
+                allWarnings.push(`staleness detection failed: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+    }
+    finally {
+        if (db)
+            closeDatabase(db);
+    }
+    return {
+        ...(memoryInference ? { memoryInference } : {}),
+        ...(graphExtraction ? { graphExtraction } : {}),
+        ...(stalenessDetection ? { stalenessDetection } : {}),
+        ...(actions.length > 0 ? { actions } : {}),
+        memoryInferenceDurationMs,
+        graphExtractionDurationMs,
+        orphansPurged,
+        proposalsExpired,
+    };
+}
+function shouldAnalyzeMemoryCleanup(scope, eligibleMemories, primaryStashDir) {
+    if (!primaryStashDir || eligibleMemories === 0)
+        return false;
+    if (scope.mode === "all")
+        return true;
+    if (scope.mode === "type")
+        return scope.value === "memory";
+    if (!scope.value)
+        return false;
+    return parseAssetRef(scope.value).type === "memory";
+}
+function shapeMemoryCleanup(plan) {
+    return {
+        analyzedDerived: plan.analyzedDerived,
+        pruneCandidates: plan.pruneCandidates,
+        contradictionCandidates: plan.contradictionCandidates,
+        beliefStateTransitions: plan.beliefStateTransitions,
+        consolidationCandidates: plan.consolidationCandidates,
+        ...(plan.relativeDateCandidates.length > 0 ? { relativeDateCandidates: plan.relativeDateCandidates } : {}),
+    };
+}
+function buildUtilityMap(refs) {
+    const map = new Map();
+    if (refs.length === 0)
+        return map;
+    const refSet = new Set(refs.map((r) => r.ref));
+    let db;
+    try {
+        db = openExistingDatabase();
+        const allDbEntries = getAllEntries(db);
+        const idToRef = new Map();
+        for (const indexed of allDbEntries) {
+            const ref = makeAssetRef(indexed.entry.type, indexed.entry.name);
+            if (refSet.has(ref))
+                idToRef.set(indexed.id, ref);
+        }
+        const ids = [...idToRef.keys()];
+        if (ids.length > 0) {
+            const { global: scores } = getUtilityScoresByIds(db, ids);
+            for (const [id, score] of scores) {
+                const ref = idToRef.get(id);
+                if (ref)
+                    map.set(ref, score.utility);
+            }
+        }
+    }
+    catch (err) {
+        rethrowIfTestIsolationError(err);
+        // best-effort: if DB unavailable, all utilities default to 0
+    }
+    finally {
+        if (db)
+            closeDatabase(db);
+    }
+    return map;
+}
+async function findAssetFilePath(ref, stashDir, writableDirSet) {
+    return resolveAssetPath(ref, {
+        stashDir,
+        mode: "disk-only",
+        writableDirSet,
+        directoryIndexNames: ["SKILL.md"],
+        preserveDirectNameFallback: true,
+        honorOrigin: false,
+    });
+}