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

package/dist/commands/improve/improve.js

@@ -4,46 +4,47 @@
 import fs from "node:fs";
 import path from "node:path";
 import { assertNever } from "../../core/assert.js";
+import { parseRefInput } from "../../core/asset/resolve-ref.js";
 import { daysToMs } from "../../core/common.js";
-import { loadConfig } from "../../core/config/config.js";
-import { rethrowIfTestIsolationError } from "../../core/errors.js";
+import { bundlesToSourceEntries, loadConfig } from "../../core/config/config.js";
+import { ConfigError, rethrowIfTestIsolationError, UsageError } from "../../core/errors.js";
 import { appendEvent, readEvents } from "../../core/events.js";
 import { classifyImproveAction, foldDistillSkipped } from "../../core/improve-types.js";
+import { resolveMutationTarget } from "../../core/mutation-target.js";
 import { getDbPath, getStateDbPathInDataDir } from "../../core/paths.js";
+import { redactSensitiveText } from "../../core/redaction.js";
 import { openStateDatabase } from "../../core/state-db.js";
 import { info, warn } from "../../core/warn.js";
-import { closeDatabase, getEntryCount, openExistingDatabase } from "../../indexer/db/db.js";
+import { resolveWritable, resolveWriteTarget } from "../../core/write-source.js";
 import { ensureIndex } from "../../indexer/ensure-index.js";
 import { akmIndex } from "../../indexer/indexer.js";
-import { resolveSourceEntries } from "../../indexer/search/search-source.js";
-import { resolveTriageJudgmentRunner } from "../../integrations/agent/runner.js";
+import { resolveEntryContentDir, resolveSourceEntries } from "../../indexer/search/search-source.js";
+import { collectEngineCredentialValues } from "../../integrations/agent/engine-resolution.js";
+import { materializeLlmRunnerConnection } from "../../integrations/agent/runner.js";
 import { installLlmUsagePersistence } from "../../llm/usage-persist.js";
-import { withLlmStage } from "../../llm/usage-telemetry.js";
-import { isGitBackedStash, resolveWritableOverride, saveGitStash } from "../../sources/providers/git.js";
+import { isGitBackedStash, listGitChangedPaths, resolveWritableOverride, saveGitStash, } from "../../sources/providers/git.js";
+import { closeDatabase, openExistingDatabase } from "../../storage/repositories/index-connection.js";
+import { getEntryCount } from "../../storage/repositories/index-entries-repository.js";
 import { drainProposals } from "../proposal/drain.js";
 import { resolveDrainPolicy } from "../proposal/drain-policies.js";
+import { describeGatedLanes, isAutonomyLaneAllowed } from "./autonomy-gate.js";
 import { akmDistill } from "./distill.js";
 // Eligibility / candidate-selection predicates live in ./eligibility.
-import { buildLatestProposalTsMap, collectEligibleRefs, memoryCleanupParentRef, resolveImproveScope, shouldAnalyzeMemoryCleanup, } from "./eligibility.js";
+import { buildLatestProposalTsMap, collectEligibleRefs, collectEligibleRefsReadOnly, memoryCleanupParentRef, resolveImproveScope, shouldAnalyzeMemoryCleanup, } from "./eligibility.js";
 import { countEvalCases } from "./eval-cases.js";
-import { resolveImproveProfile, resolveProcessEnabled } from "./improve-profiles.js";
-// #607 per-process lock primitives live in ./locks. Imported for internal use;
-// resetHeldProcessLocks is re-exported (the test seam imports it from here).
-import { PROCESS_LOCK_DEFS, processLockPath, releaseAllProcessLocks, releaseHeldLocksIfOwned, releaseProcessLock, tryAcquireProcessLock, withOptionalProcessLock, } from "./locks.js";
+import { resolveImprovePlan } from "./improve-strategies.js";
+import { improveLockPath, MIN_IMPROVE_LOCK_STALE_MS, releaseImproveLock, tryAcquireImproveLock } from "./locks.js";
 // The cycle loop / post-loop / maintenance stages live in ./loop-stages.
 import { runImproveLoopStage, runImprovePostLoopStage } from "./loop-stages.js";
-import { detectAndWriteContradictions } from "./memory/memory-contradiction-detect.js";
 import { analyzeMemoryCleanup } from "./memory/memory-improve.js";
 // The pre-loop preparation pipeline lives in ./preparation.
 import { runImprovePreparationStage } from "./preparation.js";
 import { DEFAULT_DUE_DAYS, filterProactiveDue } from "./proactive-maintenance.js";
 import { akmReflect } from "./reflect.js";
+import { createRunContext } from "./run-context.js";
 import { errMessage } from "./shared.js";
-export { resetHeldProcessLocks } from "./locks.js";
 // Re-exported from ./loop-stages for test importers (improve-db-locking).
 export { runImproveMaintenancePasses } from "./loop-stages.js";
-// Re-exported from ./preparation so existing importers (tests, callers) resolve.
-export { maybeAutoTuneThreshold } from "./preparation.js";
 export function renderSyncCommitMessage(template, result, nowMs) {
     const iso = new Date(nowMs).toISOString();
     const tokens = {
@@ -57,7 +58,7 @@ export function renderSyncCommitMessage(template, result, nowMs) {
         triage_rejected: String(result.triage?.rejected ?? 0),
         runId: result.runId ?? "",
     };
-    return template.replace(/\{(\w+)\}/g, (match, key) => (Object.hasOwn(tokens, key) ? tokens[key] : match));
+    return template.replace(/\{(\w+)\}/g, (match, key) => tokens[key] ?? match);
 }
 export function armBudgetWatchdog(budgetMs, controller, deps) {
     const setTimeoutFn = deps?.setTimeoutFn ?? setTimeout;
@@ -84,6 +85,234 @@ export function armBudgetWatchdog(budgetMs, controller, deps) {
     };
 }
 export async function akmImprove(options = {}) {
+    const setup = resolveImproveRunSetup(options);
+    options = setup.options;
+    const { budgetMs, budgetAbortController, scope, selectedStrategy, syncRepoDir, resolvedStateDbPath, resolvedLockPath, lockStaleAfterMs, } = setup;
+    let clearBudgetTimer = () => { };
+    let initialGitPaths = new Set();
+    const preEnsureCleanupWarnings = [];
+    // Assigned by runIndexAndCollect() (closure) so TS cannot prove definite
+    // assignment — seed with empty values; the runIndexAndCollect() call below
+    // always overwrites them before any read.
+    let plannedRefs = [];
+    let memorySummary = { eligible: 0, derived: 0 };
+    let strategyFilteredRefs = [];
+    let memoryCleanupPlan;
+    let autonomyGatedDirectLanes = [];
+    let guidance;
+    let triageDrain;
+    let improveLockOwnership;
+    let exitBackstop;
+    // I1: open a single state.db connection for the main improve run so all
+    // appendEvent calls reuse one handle instead of open/migrate/close per call.
+    let eventsDb;
+    // Start boundary-pinned for prepass telemetry, then replace this binding with
+    // the long-lived handle after the prepass. The usage sink resolves it per
+    // append, so one owner and counter span both lifecycle phases.
+    let eventsCtx = { dbPath: resolvedStateDbPath };
+    let disposeLlmUsageSink = () => { };
+    const releaseRunLock = () => {
+        const ownership = improveLockOwnership;
+        if (!ownership)
+            return;
+        improveLockOwnership = undefined;
+        try {
+            releaseImproveLock(ownership);
+        }
+        catch {
+            // Best-effort cleanup. Exact ownership prevents deleting a successor.
+        }
+    };
+    const commitStashBatch = makeCommitStashBatch({
+        run: setup,
+        getInitialGitPaths: () => initialGitPaths,
+        // Captured via getter: the live `eventsCtx` binding is reassigned after the
+        // prepass, and the catch-path sync must write through the current context.
+        getEventsCtx: () => eventsCtx,
+    });
+    if (!options.dryRun) {
+        const remainingBudget = budgetAbortController.signal.remainingBudgetMs;
+        clearBudgetTimer = armBudgetWatchdog(Math.max(1, remainingBudget ?? budgetMs), budgetAbortController);
+    }
+    try {
+        if (!options.dryRun) {
+            const acquisition = tryAcquireImproveLock(resolvedLockPath, lockStaleAfterMs, options.skipIfLocked, {
+                // R25: C2 boundary-pinned path — the long-lived handle doesn't exist yet.
+                dbPath: resolvedStateDbPath,
+            });
+            if (acquisition.state === "skipped") {
+                clearBudgetTimer();
+                return buildLockSkippedResult(selectedStrategy.name, scope, options.runId);
+            }
+            improveLockOwnership = acquisition.ownership;
+            disposeLlmUsageSink = installLlmUsagePersistence(() => eventsCtx);
+            exitBackstop = releaseRunLock;
+            process.on("exit", exitBackstop);
+            initialGitPaths =
+                syncRepoDir && isGitBackedStash(syncRepoDir) ? new Set(listGitChangedPaths(syncRepoDir)) : new Set();
+            // Drain the standing proposal backlog before indexing so fresh proposal
+            // generation sees promotions from this same serialized run.
+            triageDrain = await runTriagePrePass(setup);
+        }
+        // #339 fix: ensureIndex MUST run BEFORE collectEligibleRefs (inside the
+        // indexAndCollect helper).
+        const collected = await indexAndCollect({ run: setup, signal: budgetAbortController.signal });
+        plannedRefs = collected.plannedRefs;
+        memorySummary = collected.memorySummary;
+        strategyFilteredRefs = collected.strategyFilteredRefs;
+        memoryCleanupPlan = collected.memoryCleanupPlan;
+        autonomyGatedDirectLanes = collected.autonomyGatedDirectLanes;
+        guidance = collected.guidance;
+        preEnsureCleanupWarnings.push(...collected.warnings);
+        if (options.dryRun) {
+            const result = buildDryRunResult(setup, collected);
+            clearBudgetTimer();
+            return result;
+        }
+    }
+    catch (err) {
+        // If the live prepass fails, emit its summary and clear the owning sink
+        // before any run teardown. The disposer is idempotent with the main finalizer.
+        disposeLlmUsageSink();
+        clearBudgetTimer();
+        if (exitBackstop) {
+            process.removeListener("exit", exitBackstop);
+            exitBackstop = undefined;
+        }
+        releaseRunLock();
+        throw err;
+    }
+    try {
+        try {
+            eventsDb = openStateDatabase(resolvedStateDbPath);
+            eventsCtx = { db: eventsDb };
+        }
+        catch (err) {
+            rethrowIfTestIsolationError(err);
+            // If we cannot open state.db up-front, fall back to per-call opens — but
+            // still pinned to the boundary-resolved path, never a live env re-read.
+            eventsCtx = { dbPath: resolvedStateDbPath };
+        }
+        // WI-9.10: construct the run's RunContext here — the first point after
+        // run-setup where config/stashDir/eventsCtx/proposalsCtx/sourceRun/dryRun
+        // are all in hand. See buildImproveRunContext for exactly which
+        // already-resolved values back each field.
+        const ctx = buildImproveRunContext(setup, eventsCtx);
+        const seq = await runImproveStageSequence({
+            run: setup,
+            strategyFilteredRefs,
+            plannedRefs,
+            memoryCleanupPlan,
+            autonomyGatedDirectLanes,
+            memorySummary,
+            preEnsureCleanupWarnings,
+            eventsCtx,
+            ctx,
+        });
+        const result = finalizeImproveResult({
+            run: setup,
+            seq,
+            guidance,
+            memorySummary,
+            memoryCleanupPlan,
+            strategyFilteredRefs,
+            triageDrain,
+            eventsCtx,
+        });
+        // End-of-run BATCH auto-sync — the converged commit. Recognition is
+        // decoupled from the per-write path (see write-source.ts case-3): the primary
+        // stash writes as a filesystem source during the run, then is committed via
+        // the same `saveGitStash` that `akm sync` calls. The gating (git-backed
+        // primary stash, sync not disabled) and the NON-FATAL guarantee now live in
+        // `commitStashBatch` (#662); the inter-cycle and catch-path calls reuse it.
+        // dry-run already returned above, so this always runs on a completed live
+        // run. `result.sync` reflects this final commit (for a one-cycle run it is
+        // the only commit; for a multi-cycle run the earlier cycles were banked by
+        // the inter-cycle calls and this records the last batch). `result` carries
+        // the full `{accepted}`/`{refs}`/`{triage_*}` token data for the message.
+        result.sync = commitStashBatch(result);
+        return result;
+    }
+    catch (err) {
+        recordImproveFailure(err, setup, eventsCtx);
+        // #662 crash/abort safety net: commit whatever this run already wrote to the
+        // primary stash BEFORE rethrowing, so an interrupted run (mid-cycle crash or
+        // a cooperative budget abort that surfaces as a throw) does not leave its
+        // writes uncommitted until a later clean run sweeps them up. Best-effort —
+        // `commitStashBatch` swallows its own errors and no-ops a clean tree, so this
+        // never masks or supersedes the original failure being rethrown below.
+        commitStashBatch({ scope, plannedRefs, runId: options.runId });
+        throw err;
+    }
+    finally {
+        // #576: clear the per-run LLM usage sink BEFORE closing `eventsDb` below, so
+        // no late sink invocation can write through a closed handle.
+        disposeLlmUsageSink();
+        // O-1 (#364): Clear the budget abort timer so it does not keep the event
+        // loop alive after the run completes.
+        clearBudgetTimer();
+        // Drop ONLY our own process.exit backstop so it does not fire later (or
+        // accumulate across repeated in-process calls). Must NOT use
+        // removeAllListeners("exit") here: in the in-process model (tests and
+        // programmatic callers import cli.ts) that would silently destroy exit
+        // handlers owned by the host or other commands.
+        if (exitBackstop) {
+            process.removeListener("exit", exitBackstop);
+            exitBackstop = undefined;
+        }
+        releaseRunLock();
+        // 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
+        }
+    }
+}
+/** Resolve a dry-run inspection source without adapting it into a write target. */
+function resolveImproveReadSource(config, scopedRef, explicitTarget, fallbackStashDir) {
+    if (scopedRef?.origin && explicitTarget && scopedRef.origin !== explicitTarget) {
+        throw new UsageError(`Qualified ref bundle "${scopedRef.origin}" conflicts with --target "${explicitTarget}".`, "INVALID_FLAG_VALUE", `Drop --target or use --target ${scopedRef.origin}.`);
+    }
+    const selector = scopedRef?.origin ?? explicitTarget ?? config.defaultWriteTarget;
+    if (!selector && fallbackStashDir) {
+        return { source: { name: "stash", path: fallbackStashDir } };
+    }
+    const configuredSelector = selector ?? config.defaultBundle;
+    if (configuredSelector) {
+        const entry = bundlesToSourceEntries(config)?.find((source) => source.name === configuredSelector);
+        if (!entry) {
+            throw new UsageError(`No source named "${configuredSelector}" is configured. Run \`akm bundle list\` to see available sources.`, "INVALID_FLAG_VALUE");
+        }
+        const sourcePath = resolveEntryContentDir(entry);
+        if (!sourcePath) {
+            throw new ConfigError(`Source "${configuredSelector}" has no resolvable on-disk path; improve cannot inspect this entry.`, "INVALID_CONFIG_FILE");
+        }
+        return { selector: configuredSelector, source: { name: configuredSelector, path: sourcePath } };
+    }
+    const implicit = resolveSourceEntries(undefined, config)[0];
+    if (!implicit) {
+        throw new ConfigError("no source configured; run `akm bundle create`", "STASH_DIR_NOT_FOUND");
+    }
+    return { source: { name: implicit.registryId ?? "stash", path: implicit.path } };
+}
+/**
+ * Run-setup: budget/watchdog plumbing, scope + seam resolution, the invocation
+ * plan, write-target resolution, the profile-defaulted options rebuild, and
+ * the boundary-pinned state.db/lock paths. Fully SYNCHRONOUS — the C2 boundary
+ * snapshot (resolvedStateDbPath) must be taken before the first await of the
+ * run.
+ */
+function resolveImproveRunSetup(options) {
+    const startMs = Date.now();
+    const budgetMs = options.timeoutMs ?? 2 * 60 * 60 * 1000;
+    const budgetAbortController = new AbortController();
+    Object.defineProperty(budgetAbortController.signal, "remainingBudgetMs", {
+        get: () => Math.max(0, budgetMs - (Date.now() - startMs)),
+        enumerable: false,
+        configurable: true,
+    });
     const scope = resolveImproveScope(options.scope);
     const reflectFn = options.reflectFn ?? akmReflect;
     const distillFn = options.distillFn ?? akmDistill;
@@ -91,27 +320,67 @@ export async function akmImprove(options = {}) {
     const reindexFn = options.reindexFn ?? akmIndex;
     const drainProposalsFn = options.drainProposalsFn ?? drainProposals;
     // #616 multi-cycle test seams. Default to the real module-local fns.
-    const collectEligibleRefsImpl = options.collectEligibleRefsFn ?? collectEligibleRefs;
+    const collectEligibleRefsImpl = options.collectEligibleRefsFn ?? (options.dryRun ? collectEligibleRefsReadOnly : collectEligibleRefs);
     const runImprovePreparationStageImpl = options.runImprovePreparationStageFn ?? runImprovePreparationStage;
     const runImproveLoopStageImpl = options.runImproveLoopStageFn ?? runImproveLoopStage;
     const runImprovePostLoopStageImpl = options.runImprovePostLoopStageFn ?? runImprovePostLoopStage;
     // Resolve the improve profile for this run. Profile drives type filtering,
-    // process gating, and default autoAccept/limit values.
+    // process gating, and the default limit value.
     const _earlyConfig = options.config ?? loadConfig();
-    const improveProfile = resolveImproveProfile(options.profile, _earlyConfig);
+    const resolvedPlan = options.resolvedPlan ??
+        resolveImprovePlan(options.strategy, _earlyConfig, {
+            repairValidationFailures: options.repairValidationFailures,
+        });
+    const selectedStrategy = resolvedPlan.strategy;
+    const improveSensitiveValues = collectEngineCredentialValues(_earlyConfig);
+    const improveProfile = selectedStrategy.config;
+    const scopedRef = scope.mode === "ref" && scope.value ? parseRefInput(scope.value) : undefined;
+    const readSource = options.dryRun
+        ? options.writeTarget
+            ? { selector: options.writeTarget.selector, source: options.writeTarget.source }
+            : resolveImproveReadSource(_earlyConfig, scopedRef, options.target, options.stashDir)
+        : undefined;
+    const writeTarget = options.dryRun
+        ? undefined
+        : scopedRef?.origin
+            ? resolveMutationTarget(_earlyConfig, scopedRef, options.writeTarget?.source.name ?? options.target).target
+            : (options.writeTarget ??
+                (options.target || _earlyConfig.defaultWriteTarget || !options.stashDir
+                    ? resolveWriteTarget(_earlyConfig, options.target)
+                    : {
+                        source: { kind: "filesystem", name: "stash", path: options.stashDir },
+                        config: {
+                            type: "filesystem",
+                            name: "stash",
+                            path: options.stashDir,
+                            writable: true,
+                        },
+                    }));
+    const selectedSource = writeTarget?.source ?? readSource?.source;
+    if (!selectedSource)
+        throw new ConfigError("improve could not resolve a source", "STASH_DIR_NOT_FOUND");
+    const selectedSelector = writeTarget?.selector ?? readSource?.selector;
     // 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,
+        // Pin nested calls and quality gates to the same config snapshot as the
+        // invocation plan. They must never reload a changed config mid-run.
+        config: _earlyConfig,
+        target: selectedSelector,
+        sourceName: selectedSource.name,
+        ...(writeTarget ? { writeTarget } : {}),
+        stashDir: selectedSource.path,
+        consolidateOptions: {
+            ...options.consolidateOptions,
+            target: selectedSelector,
+            ...(writeTarget ? { writeTarget } : {}),
+        },
         // Profile-level limit, then process-level reflect.limit as fallback.
         // CLI --limit takes precedence over both.
         limit: options.limit ?? improveProfile?.processes?.reflect?.limit ?? improveProfile.limit,
     };
-    // #616 — bounded multi-cycle phasing. CLI/programmatic override wins over
-    // profile.maxCycles; default 1 => single pass (byte-identical to pre-#616).
-    const maxCycles = Math.max(1, Math.trunc(options.maxCycles ?? improveProfile.maxCycles ?? 1));
     let primaryStashDir;
     try {
         primaryStashDir = resolveSourceEntries(options.stashDir)[0]?.path;
@@ -119,6 +388,7 @@ export async function akmImprove(options = {}) {
     catch {
         primaryStashDir = undefined;
     }
+    const syncRepoDir = writeTarget?.source.repoPath ?? primaryStashDir;
     // C2 (#553/#554/#499): resolve the state.db path ONCE, synchronously, at the
     // command boundary — before the first `await` below. Every state.db open in
     // this run (`openStateDatabase`, every default-path `appendEvent`) is pinned
@@ -128,281 +398,303 @@ export async function akmImprove(options = {}) {
     // timeout root cause). Because beforeEach runs synchronously, env is still the
     // calling test's own at this point; we capture it before yielding the loop.
     const resolvedStateDbPath = getStateDbPathInDataDir();
-    // #612 / WS-4 — bounded, OPT-IN per-phase auto-accept threshold auto-tune.
-    // DEFAULT OFF: `autoTune: false` (or absent) is a complete no-op.
-    //
-    // WS-4 change: thresholds are now PER PHASE. The old single global mutation
-    // of `options.autoAccept` is retired — it caused every phase to share one
-    // calibration signal, so a reflect-dominated run could tighten the consolidate
-    // gate (or vice-versa). Instead:
-    //   - Each `makeGateConfig` call reads the phase's stored threshold from
-    //     state.db (Migration 012) and uses it as `phaseThreshold`, overriding
-    //     the `globalThreshold` (= options.autoAccept) for that phase.
-    //   - Per-phase `maybeAutoTuneThreshold` calls fire AFTER each phase's gate
-    //     has run and persist the new threshold to state.db for the NEXT run.
-    //   - `options.autoAccept` stays unchanged (it is the operator-supplied
-    //     baseline, not a mutable run-time state).
-    //
-    // The global tune call is intentionally removed here. See per-phase calls
-    // below (near each makeGateConfig / runAutoAcceptGate block).
-    // #607 Lock decomposition: three per-process locks replace the single
-    // `improve.lock`. Each process acquires only the lock(s) it needs, so
-    // quick-shredder consolidate can run alongside daily reflect+distill.
-    //
-    //   consolidate.lock     — protects consolidate + memoryInference + graphExtraction (index.db writers)
-    //   reflect-distill.lock — protects reflect + distill (state.db proposal writers)
-    //   triage.lock          — protects triage pre-pass (state.db proposal promotions)
-    //
-    // Lock base directory — same `.akm/` under the primary stash dir.
+    // One conservative run lock protects the complete mutation window, including
+    // triage, indexing, proposal work, maintenance, and final stash sync.
     const lockBaseDir = primaryStashDir ? path.join(primaryStashDir, ".akm") : path.join(options.stashDir ?? ".", ".akm");
-    const preEnsureCleanupWarnings = [];
-    // #616: assigned by runIndexAndCollect() (closure) so TS cannot prove definite
-    // assignment — seed with empty values; the first runIndexAndCollect() call
-    // (cycle 1, in the first try) always overwrites them before any read.
+    const resolvedLockPath = improveLockPath(lockBaseDir);
+    const lockStaleAfterMs = Math.max(MIN_IMPROVE_LOCK_STALE_MS, budgetMs + 10 * 60 * 1000);
+    const effectiveSync = { ...improveProfile.sync, ...options.sync };
+    return {
+        startMs,
+        budgetMs,
+        budgetAbortController,
+        scope,
+        reflectFn,
+        distillFn,
+        ensureIndexFn,
+        reindexFn,
+        drainProposalsFn,
+        collectEligibleRefsImpl,
+        runImprovePreparationStageImpl,
+        runImproveLoopStageImpl,
+        runImprovePostLoopStageImpl,
+        _earlyConfig,
+        resolvedPlan,
+        selectedStrategy,
+        improveSensitiveValues,
+        improveProfile,
+        writeTarget,
+        options,
+        primaryStashDir,
+        syncRepoDir,
+        resolvedStateDbPath,
+        resolvedLockPath,
+        lockStaleAfterMs,
+        effectiveSync,
+    };
+}
+/**
+ * WI-9.10: build the run's {@link RunContext} purely from values
+ * `resolveImproveRunSetup` and the long-lived state.db open already
+ * resolved — no second config load, no new db handle. Called once, right
+ * after `eventsCtx` is resolved (the last of {config, stashDir, eventsCtx,
+ * proposalsCtx, sourceRun, dryRun} to become available in `akmImprove`).
+ */
+function buildImproveRunContext(run, eventsCtx) {
+    return createRunContext({
+        config: run._earlyConfig,
+        // primaryStashDir can fail to resolve (rare); "." mirrors the existing
+        // lockBaseDir fallback in resolveImproveRunSetup for the same case. This
+        // is a BEST-EFFORT value for the required RunContext field only — the
+        // loop stage reads `ImproveLoopState.primaryStashDir` (the honest
+        // optional), so its `if (primaryStashDir)` guards still skip on the
+        // unresolvable path; no RunContext consumer reads `ctx.stashDir` there.
+        stashDir: run.primaryStashDir ?? run.options.stashDir ?? ".",
+        eventsCtx,
+        // ProposalsContext threads only a dbPath seam (D14: no db handle is
+        // threaded in), mirroring eventsCtx's own dbPath-only fallback shape.
+        // Not yet wired into any proposal call site this stage — verb-level
+        // RunContext adoption (reflect/distill/extract/consolidate) is later.
+        proposalsCtx: { dbPath: run.resolvedStateDbPath },
+        // Representative connection for this run: reflect is the loop's primary
+        // LLM-driving process. Mirrors the existing
+        // `runner ? materializeLlmRunnerConnection(runner) : null` pattern
+        // already used for the consolidate process elsewhere (contradiction pass).
+        getLlmConfig: () => {
+            const runner = run.resolvedPlan.processes.reflect.runner;
+            return runner ? materializeLlmRunnerConnection(runner) : null;
+        },
+        sourceRun: run.options.runId ?? `improve-${run.startMs}`,
+        // Always false here: callers only reach this point past the dry-run
+        // early return in akmImprove.
+        dryRun: run.options.dryRun ?? false,
+        // Same AbortSignal instance armBudgetWatchdog stamped a live
+        // `remainingBudgetMs` getter onto (#616) — identity preserved so
+        // `ctx.signal.remainingBudgetMs` resolves correctly for every consumer.
+        signal: run.budgetAbortController.signal,
+    });
+}
+/** The catch-path improve_failed audit event (D3), redacted. */
+function recordImproveFailure(err, run, eventsCtx) {
+    const { scope, selectedStrategy, improveSensitiveValues, startMs } = run;
+    // 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: {
+            strategy: selectedStrategy.name,
+            error: redactSensitiveText(errMessage(err), improveSensitiveValues),
+            durationMs: Date.now() - startMs,
+        },
+    }, eventsCtx);
+}
+/**
+ * ensureIndex + collectEligibleRefs + the contradiction pre-pass + the
+ * memory-cleanup recompute (#339 ordering). Formerly the runIndexAndCollect
+ * closure mutating outer `let`s; now a pure pass returning its results.
+ */
+async function indexAndCollect(args) {
+    const { signal } = args;
+    const { scope, options, primaryStashDir, improveProfile, _earlyConfig, ensureIndexFn, collectEligibleRefsImpl } = args.run;
+    const warnings = [];
     let plannedRefs = [];
     let memorySummary = { eligible: 0, derived: 0 };
-    let profileFilteredRefs = [];
-    let memoryCleanupPlan;
-    let guidance;
-    let triageDrain;
-    // #616 — ensureIndex + collectEligibleRefs + memory-cleanup recompute, lifted
-    // into a helper so the SAME sequence runs once for cycle 1 (below, in the
-    // first try) and is re-run at the top of each subsequent multi-cycle cycle.
-    // Re-running ensureIndex between cycles makes cycle N's gate-promoted
-    // proposals visible to cycle N+1's collectEligibleRefs. Mutates the
-    // outer-scope plannedRefs/memorySummary/profileFilteredRefs/memoryCleanupPlan/
-    // guidance so for maxCycles:1 the body is byte-identical to pre-#616.
-    const runIndexAndCollect = async () => {
-        // #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.
-        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, { mode: "blocking" });
-            }
-            catch (err) {
-                preEnsureCleanupWarnings.push(`ensureIndex failed: ${errMessage(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) {
+    let strategyFilteredRefs = [];
+    // #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.
+    if (primaryStashDir && !options.dryRun) {
+        // 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 {
-                    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");
-                    }
+                    preEnsureEntryCount = getEntryCount(probeDb);
                 }
-                catch (err) {
-                    rethrowIfTestIsolationError(err);
-                    // best-effort
+                finally {
+                    closeDatabase(probeDb);
                 }
             }
         }
-        ({ plannedRefs, memorySummary, profileFilteredRefs } = await collectEligibleRefsImpl(scope, options.stashDir, improveProfile));
-        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)) {
+        catch (err) {
+            rethrowIfTestIsolationError(err);
+            // best-effort; leave preEnsureEntryCount undefined
+        }
+        try {
+            await ensureIndexFn(primaryStashDir, { mode: "blocking", signal: signal });
+        }
+        catch (err) {
+            if (signal.aborted)
+                throw err;
+            warnings.push(`ensureIndex failed: ${errMessage(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 {
-                // Reuse the config resolved at the top of the run instead of a second load.
-                await withLlmStage("memory-contradiction", () => detectAndWriteContradictions(primaryStashDir, _earlyConfig));
+                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) {
-                // Non-fatal: contradiction detection is a best-effort pass.
-                warn(`[improve] contradiction detection failed (non-fatal): ${errMessage(err)}`);
+                rethrowIfTestIsolationError(err);
+                // best-effort
             }
         }
-        memoryCleanupPlan = shouldAnalyzeMemoryCleanup(scope, memorySummary.eligible, primaryStashDir)
-            ? analyzeMemoryCleanup(primaryStashDir, cleanupParentRef ? { parentRef: cleanupParentRef } : undefined)
-            : undefined;
-        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;
+    }
+    ({
+        plannedRefs,
+        memorySummary,
+        strategyFilteredRefs = [],
+    } = await collectEligibleRefsImpl(scope, options.stashDir, improveProfile, _earlyConfig));
+    const cleanupParentRef = memoryCleanupParentRef(scope, options.stashDir);
+    // D8 — the two direct lanes share one eligibility predicate, which reads scope
+    // and eligible-memory count and no strategy flag at all. Compute it once: it
+    // decides whether each lane would have run, which is also what decides whether
+    // a gated lane is worth REPORTING. A lane that was never eligible was not
+    // suppressed by the gate, so claiming it was would be noise.
+    const cleanupEligible = shouldAnalyzeMemoryCleanup(scope, memorySummary.eligible, primaryStashDir);
+    // Cleanup remains independent of the disabled contradiction writer.
+    const memoryCleanupPlan = cleanupEligible
+        ? analyzeMemoryCleanup(primaryStashDir, cleanupParentRef ? { parentRef: cleanupParentRef } : undefined)
+        : undefined;
+    const cleanupWouldMutate = Boolean(memoryCleanupPlan &&
+        (memoryCleanupPlan.pruneCandidates.length > 0 ||
+            memoryCleanupPlan.beliefStateTransitions.length > 0 ||
+            memoryCleanupPlan.relativeDateCandidates.length > 0));
+    const autonomyGatedDirectLanes = cleanupWouldMutate && !isAutonomyLaneAllowed("memoryCleanup", _earlyConfig) ? ["memoryCleanup"] : [];
+    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;
+    return {
+        plannedRefs,
+        memorySummary,
+        strategyFilteredRefs: strategyFilteredRefs ?? [],
+        memoryCleanupPlan,
+        autonomyGatedDirectLanes,
+        guidance,
+        warnings,
     };
-    // Holds our own process.on("exit") backstop so the finally can remove EXACTLY
-    // that handler (not every exit listener in the process). Declared in the scope
-    // shared by the try and its finally; assigned when the backstop is registered.
-    let exitBackstop;
-    try {
-        // #607: Per-process lock acquisition. Each process acquires only the lock(s)
-        // it needs. The dry-run branch produces plannedRefs/memorySummary WITHOUT any
-        // locks (decision: dry-run never mutates the queue).
-        if (!options.dryRun) {
-            // Backstop release on process.exit() (signal handler / budget watchdog),
-            // which skips the finally below. Removed in that finally on the normal path.
-            const releaseAllOnExit = () => releaseHeldLocksIfOwned(process.pid);
-            exitBackstop = releaseAllOnExit;
-            process.on("exit", releaseAllOnExit);
-            // #607 triage pre-pass: acquire triage.lock, drain the standing pending
-            // backlog BEFORE ensureIndex so improve generates fresh proposals against
-            // a cleared queue (no `duplicate_pending` collisions) and ensureIndex
-            // absorbs triage's promotions for free. Release immediately after —
-            // triage.lock is not needed again until the next improve run.
-            if (primaryStashDir && resolveProcessEnabled("triage", improveProfile)) {
-                if (scope.mode === "ref") {
-                    warn("[improve] triage pre-pass skipped (single-ref scope never drains the whole queue)");
-                }
-                else {
-                    const triageLPath = processLockPath(lockBaseDir, "triage");
-                    const triageResult = tryAcquireProcessLock(triageLPath, PROCESS_LOCK_DEFS.triage.staleAfterMs, options.skipIfLocked, "triage");
-                    if (triageResult === "skipped") {
-                        triageDrain = undefined;
-                    }
-                    else {
-                        try {
-                            const triageConfig = improveProfile.processes?.triage;
-                            const policy = resolveDrainPolicy(triageConfig?.policy);
-                            const applyMode = triageConfig?.applyMode ?? "queue";
-                            const maxAccepts = triageConfig?.maxAcceptsPerRun ?? 25;
-                            const judgment = triageConfig?.judgment
-                                ? resolveTriageJudgmentRunner(triageConfig.judgment, _earlyConfig)
-                                : null;
-                            triageDrain = await drainProposalsFn({
-                                stashDir: primaryStashDir,
-                                policy,
-                                applyMode,
-                                maxAccepts,
-                                dryRun: false,
-                                excludeIds: new Set(),
-                                ...(triageConfig?.maxDiffLines !== undefined ? { maxDiffLines: triageConfig.maxDiffLines } : {}),
-                                judgment,
-                            });
-                        }
-                        catch (err) {
-                            warn(`[improve] triage pre-pass failed (non-fatal): ${errMessage(err)}`);
-                        }
-                        finally {
-                            releaseProcessLock(triageLPath);
-                        }
-                    }
-                }
-            }
+}
+/** The P2 lock-skipped envelope (graceful `skipIfLocked` early return). Exported for unit tests. */
+export function buildLockSkippedResult(strategyName, scope, runId) {
+    return {
+        schemaVersion: 2,
+        ok: true,
+        strategy: strategyName,
+        scope,
+        dryRun: false,
+        skipped: { reason: "lock-held" },
+        memorySummary: { eligible: 0, derived: 0 },
+        plannedRefs: [],
+        actions: [],
+        ...(runId !== undefined ? { runId } : {}),
+    };
+}
+/** The P3 dry-run envelope (plan-only early return). Exported for unit tests. */
+export function buildDryRunResult(run, collected) {
+    const { selectedStrategy, scope } = run;
+    const { guidance, memorySummary, memoryCleanupPlan, plannedRefs, strategyFilteredRefs } = collected;
+    return {
+        schemaVersion: 2,
+        ok: true,
+        strategy: selectedStrategy.name,
+        scope,
+        dryRun: true,
+        ...(guidance ? { guidance } : {}),
+        memorySummary,
+        ...(memoryCleanupPlan ? { memoryCleanup: shapeMemoryCleanup(memoryCleanupPlan) } : {}),
+        plannedRefs,
+        ...(strategyFilteredRefs.length > 0 ? { strategyFilteredRefs } : {}),
+    };
+}
+/** The triage drain pre-pass (non-fatal; single-ref scope never drains). */
+async function runTriagePrePass(run) {
+    const { primaryStashDir, resolvedPlan, scope, options, improveProfile, drainProposalsFn } = run;
+    let triageDrain;
+    if (primaryStashDir && resolvedPlan.processes.triage.enabled) {
+        if (scope.mode === "ref") {
+            warn("[improve] triage pre-pass skipped (single-ref scope never drains the whole queue)");
         }
-        // #339 fix: ensureIndex MUST run BEFORE collectEligibleRefs (now inside the
-        // helper). Cycle 1 runs it here; subsequent multi-cycle cycles re-run it via
-        // the same helper at the top of each cycle below.
-        await runIndexAndCollect();
-        if (options.dryRun) {
-            const result = {
-                schemaVersion: 1,
-                ok: true,
-                scope,
-                dryRun: true,
-                ...(guidance ? { guidance } : {}),
-                memorySummary,
-                ...(memoryCleanupPlan ? { memoryCleanup: shapeMemoryCleanup(memoryCleanupPlan) } : {}),
-                plannedRefs,
-                ...(profileFilteredRefs.length > 0 ? { profileFilteredRefs } : {}),
-            };
-            return result;
+        else {
+            try {
+                const triageConfig = improveProfile.processes?.triage;
+                const policy = resolveDrainPolicy(triageConfig?.policy);
+                const applyMode = triageConfig?.applyMode ?? "queue";
+                const maxAccepts = triageConfig?.maxAcceptsPerRun ?? 25;
+                triageDrain = await drainProposalsFn({
+                    stashDir: primaryStashDir,
+                    ...(options.target ? { target: options.target } : {}),
+                    config: options.config,
+                    policy,
+                    applyMode,
+                    maxAccepts,
+                    dryRun: false,
+                    excludeIds: new Set(),
+                    ...(triageConfig?.maxDiffLines !== undefined ? { maxDiffLines: triageConfig.maxDiffLines } : {}),
+                    judgment: resolvedPlan.triageJudgment,
+                });
+            }
+            catch (err) {
+                warn(`[improve] triage pre-pass failed (non-fatal): ${errMessage(err)}`);
+            }
         }
     }
-    catch (err) {
-        releaseAllProcessLocks();
-        throw err;
-    }
-    // #607: per-process locks are acquired/released around each stage below.
-    // The triage pre-pass already ran under triage.lock (released). The
-    // preparation stage runs under consolidate.lock, the loop stage under
-    // reflect-distill.lock, and the post-loop stage under consolidate.lock again.
-    // Each stage acquires its lock just before starting and releases in finally.
-    // best-effort `unlinkSync` is a no-op when no lock file exists.
-    const startMs = Date.now();
-    const budgetMs = options.timeoutMs ?? 2 * 60 * 60 * 1000; // default 2 hours
-    // 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();
-    // Attach a live `remainingBudgetMs` getter to the signal so sub-callers
-    // (e.g. consolidate.ts cold-start budget estimation) can read the remaining
-    // wall-clock budget without needing an extra plumbing parameter. The property
-    // is computed at access time via a getter so it always reflects the actual
-    // elapsed time rather than a stale snapshot taken at arm time.
-    Object.defineProperty(budgetAbortController.signal, "remainingBudgetMs", {
-        get: () => Math.max(0, budgetMs - (Date.now() - startMs)),
-        enumerable: false,
-        configurable: true,
-    });
-    // Declared in the outer scope so the `finally` can clear the timer even if a
-    // throw occurs before/after it is armed. Defaults to a no-op until armed.
-    let clearBudgetTimer = () => { };
-    // 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;
-    // `eventsCtx` is read by the main catch (improve_failed) and finally, so it
-    // lives in the outer scope. It is always assigned at the top of the try.
-    // Pinned to the boundary snapshot so the fallback per-call `appendEvent`
-    // opens (when the long-lived handle below fails to open) never re-read env.
-    let eventsCtx = { dbPath: resolvedStateDbPath };
-    // #576: clears the per-run LLM usage sink. Defaults to a no-op until the sink
-    // is installed inside the try; the `finally` always calls it.
-    let disposeLlmUsageSink = () => { };
-    // ── Crash-safe / incremental stash sync (#662) ──────────────────────────────
-    // The primary stash writes as a filesystem source DURING the run
-    // (write-source.ts case-3); those writes become a git commit only when this
-    // closure runs. Historically the only call site was a single BATCH commit at
-    // the very end of the happy path, so a run interrupted AFTER writing but
-    // BEFORE finishing — a mid-cycle crash, a budget abort, or an external
-    // SIGTERM/`process.exit` — left every write uncommitted until some LATER run
-    // happened to finish cleanly and swept the whole backlog up. We now call this
-    // from THREE places: between cycles (bank each completed cycle), at end-of-run
-    // (the converged commit), and from the catch path (commit what was written
-    // before the crash). That shrinks the worst-case loss from "the entire run" to
-    // "the in-flight cycle".
-    //
-    // Declared in the OUTER scope (not inside the try) so the catch block can reach
-    // it. Idempotent + NON-FATAL: `saveGitStash` short-circuits a clean working
-    // tree ("nothing to commit") and a thrown sync error is swallowed here, so a
-    // repeat call after a no-op cycle is cheap and a failed push never fails the
-    // run. Gated identically to the original end-of-run block (git-backed primary
-    // stash, sync not disabled). `eventsCtx` is captured by reference, so calls
-    // after the db-backed context is installed inside the try use the live handle.
-    const effectiveSync = { ...improveProfile.sync, ...options.sync };
-    const commitStashBatch = (messageContext) => {
-        if (!primaryStashDir || effectiveSync.enabled === false || !isGitBackedStash(primaryStashDir)) {
+    return triageDrain;
+}
+/**
+ * Crash-safe / incremental stash sync (#662) — see the factory-returned
+ * closure's original doc block: the primary stash writes as a filesystem
+ * source DURING the run; this commits them at end-of-run AND from the catch
+ * path. Idempotent + NON-FATAL. `getEventsCtx`/`getInitialGitPaths` are
+ * getters because both outer bindings are (re)assigned after this factory
+ * runs — the returned closure must observe the live values.
+ */
+function makeCommitStashBatch(deps) {
+    const { writeTarget, primaryStashDir, effectiveSync, options, _earlyConfig, improveProfile } = deps.run;
+    return (messageContext) => {
+        const eventsCtx = deps.getEventsCtx();
+        const initialGitPaths = deps.getInitialGitPaths();
+        const repoDir = writeTarget?.source.repoPath ?? primaryStashDir;
+        if (!primaryStashDir || !repoDir || effectiveSync.enabled === false || !isGitBackedStash(repoDir)) {
             return undefined;
         }
         const saveGitStashFn = options.saveGitStashFn ?? saveGitStash;
-        const writableOverride = resolveWritableOverride(_earlyConfig);
-        const push = effectiveSync.push !== false;
+        const writableOverride = writeTarget ? resolveWritable(writeTarget.config) : resolveWritableOverride(_earlyConfig);
+        const push = options.sync?.push ?? improveProfile.sync?.push ?? true;
         const message = renderSyncCommitMessage(effectiveSync.message ?? "akm improve auto-sync", messageContext, Date.now());
         try {
-            const syncResult = saveGitStashFn(undefined, message, writableOverride, { push, repoDir: primaryStashDir });
+            const assetRoot = writeTarget?.source.path ?? primaryStashDir;
+            const assetPrefix = assetRoot ? path.relative(repoDir, assetRoot).replaceAll(path.sep, "/") : "";
+            const paths = listGitChangedPaths(repoDir).filter((changedPath) => {
+                if (initialGitPaths.has(changedPath))
+                    return false;
+                if (path.basename(changedPath).includes(".lock"))
+                    return false;
+                return !assetPrefix || changedPath === assetPrefix || changedPath.startsWith(`${assetPrefix}/`);
+            });
+            const syncResult = saveGitStashFn(undefined, message, writableOverride, {
+                push,
+                repoDir,
+                paths,
+            });
             appendEvent({
                 eventType: "stash_synced",
                 metadata: {
@@ -429,443 +721,353 @@ export async function akmImprove(options = {}) {
             return { committed: false, pushed: false, skipped: true, reason };
         }
     };
-    try {
-        // H7 (#566): arm the budget watchdog. `armBudgetWatchdog` captures both the
-        // budget timer and the hard-kill timer it schedules on exhaustion, returning
-        // a single dispose() that clears whichever are still pending. The `finally`
-        // calls dispose() via `clearBudgetTimer` (RAII), so a clean cooperative
-        // drain cancels the pending hard-kill before it can fire — the process then
-        // exits naturally instead of being force-`exit(0)`-ed mid-flush, which could
-        // truncate an in-flight log or `state.db` transaction.
-        clearBudgetTimer = armBudgetWatchdog(budgetMs, budgetAbortController);
-        try {
-            eventsDb = openStateDatabase(resolvedStateDbPath);
-            eventsCtx = { db: eventsDb };
-        }
-        catch (err) {
-            rethrowIfTestIsolationError(err);
-            // If we cannot open state.db up-front, fall back to per-call opens — but
-            // still pinned to the boundary-resolved path, never a live env re-read.
-            eventsCtx = { dbPath: resolvedStateDbPath };
+}
+/** D6: pre-load the last 30 days of proposal_rejected events once per run. */
+function preloadRejectedProposals() {
+    // 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);
         }
-        // #576: persist per-call LLM usage telemetry for this run as `llm_usage`
-        // events, reusing the same boundary-pinned events context (and long-lived
-        // handle when available). Disposed in `finally` so the sink never leaks
-        // across runs. Wrapping is best-effort end to end — see usage-telemetry.ts.
-        disposeLlmUsageSink = installLlmUsagePersistence(eventsCtx);
-        // 2026-05-27: emit an `improve_skipped` audit event for refs the planner
-        // pre-filtered (reflect AND distill both refuse them under the active
-        // profile). Emitted as a single summary event (count only) rather than one
-        // event per ref (#592) — the per-ref loop caused O(n) sequential state.db
-        // writes that consumed ~500 s on a 9 000-ref stash. No downstream consumer
-        // needs the per-ref audit trail: health's skip histogram reads the
-        // `profile_filtered_all_passes` counters from `improve_completed` metadata.
-        if (profileFilteredRefs.length > 0) {
-            appendEvent({
-                eventType: "improve_skipped",
-                ref: undefined,
-                metadata: {
-                    reason: "profile_filtered_all_passes",
-                    count: profileFilteredRefs.length,
-                },
-            }, eventsCtx);
+    }
+    return rejectedProposalsByRef;
+}
+/**
+ * Post-lock proactive cooldown re-filter: re-read cooldown timestamps
+ * immediately before the loop so external proposal writes that occurred
+ * before this run acquired its lock are visible.
+ */
+export function refilterProactiveLoopRefs(loopRefs, improveProfile) {
+    // Re-read cooldown timestamps immediately before execution so external
+    // proposal writes that occurred before this run acquired its lock are visible.
+    const proactiveLoopRefs = loopRefs.filter((r) => r.eligibilitySource === "proactive");
+    let postLockLoopRefs = loopRefs;
+    if (proactiveLoopRefs.length > 0) {
+        const proactiveRefStrs = proactiveLoopRefs.map((r) => r.ref);
+        // Correlate proposal timestamps on each candidate's durable key.
+        const proactiveItemRefByRef = new Map(proactiveLoopRefs.map((r) => [r.ref, r.itemRef]));
+        const freshReflectTs = buildLatestProposalTsMap(proactiveRefStrs, "reflect", proactiveItemRefByRef);
+        const freshDistillTs = buildLatestProposalTsMap(proactiveRefStrs, "distill", proactiveItemRefByRef);
+        const pmDueDays = improveProfile.processes?.proactiveMaintenance?.dueDays ?? DEFAULT_DUE_DAYS;
+        const stillDue = new Set(filterProactiveDue(proactiveLoopRefs, freshReflectTs, freshDistillTs, pmDueDays, Date.now()).map((r) => r.ref));
+        const dropped = proactiveLoopRefs.filter((r) => !stillDue.has(r.ref));
+        if (dropped.length > 0) {
+            info(`[improve] post-lock cooldown re-filter: dropped ${dropped.length} proactive ref(s) claimed by concurrent run (${dropped.map((r) => r.ref).join(", ")})`);
+            postLockLoopRefs = loopRefs.filter((r) => r.eligibilitySource !== "proactive" || stillDue.has(r.ref));
         }
-        // #616 — bounded multi-cycle phasing. The prep->loop->post-loop sequence is
-        // wrapped in an N-cycle loop. Each cycle re-runs ensureIndex +
-        // collectEligibleRefs (via runIndexAndCollect) so gate-accepted output of
-        // cycle N becomes selectable input to cycle N+1. The per-stage process locks
-        // (consolidate / reflect-distill) are acquired+released INSIDE each cycle,
-        // exactly as the single-pass path did. For maxCycles:1 the loop runs once and
-        // every accumulator below collapses to the single-cycle value (sum-of-one,
-        // concat-of-one, last==only) => BYTE-IDENTICAL to pre-#616.
-        //
-        // Accumulators (see CONSTRAINTS / aggregation plan in #616): SUM the count
-        // fields and durations; CONCAT the array fields; LAST-WINS for point-in-time
-        // objects (the final cycle's value reflects the converged state).
-        let cyclesRun = 0;
-        // Last-wins point-in-time values (assigned every cycle; the final cycle wins).
-        let preparation;
-        let memoryRefsForInference = new Set();
-        let consolidation;
-        let memoryInference;
-        let graphExtraction;
-        let recombination;
-        let proceduralCompilation;
-        let cycleMetrics;
-        // Summed counters/durations.
-        let prepGateCount = 0;
-        let prepGateFailedCount = 0;
-        let reflectsWithErrorContext = 0;
-        let loopGateCount = 0;
-        let loopGateFailedCount = 0;
-        let postLoopGateCount = 0;
-        let postLoopGateFailedCount = 0;
-        let memoryInferenceDurationMs = 0;
-        let graphExtractionDurationMs = 0;
-        let orphansPurged;
-        let proposalsExpired;
-        // Concatenated arrays.
-        const allWarnings = [];
-        let deadUrls;
-        const finalActions = [];
-        for (let cycleIndex = 0; cycleIndex < maxCycles; cycleIndex++) {
-            // #616 budget gate: never start a NEW cycle once the run's wall-clock
-            // budget is exhausted (or the run was aborted). Cycle 0 ALWAYS runs so
-            // maxCycles:1 is byte-identical regardless of budget.
-            if (cycleIndex > 0) {
-                const remaining = budgetAbortController.signal.remainingBudgetMs;
-                if (budgetAbortController.signal.aborted || (remaining !== undefined && remaining <= 0)) {
-                    break;
-                }
-            }
-            // #662 incremental sync: bank the PREVIOUS cycle's writes before starting a
-            // new one, so a crash/abort/timeout mid-run loses at most the in-flight
-            // cycle rather than the whole run. Guarded on `cycleIndex > 0`, so the
-            // common maxCycles:1 path never calls this — its single end-of-run commit
-            // below stays the only sync and the serialized envelope is byte-identical
-            // to pre-#662. `saveGitStash` no-ops a clean tree, so a cycle that wrote
-            // nothing costs only a `git status`.
-            if (cycleIndex > 0) {
-                commitStashBatch({ scope, plannedRefs, runId: options.runId });
-            }
-            // Re-run ensureIndex + collectEligibleRefs + memory-cleanup recompute for
-            // cycles 2+ (cycle 1 already ran them in the first try above). This makes
-            // cycle N's gate-promoted proposals visible to this cycle's ref selection.
-            if (cycleIndex > 0) {
-                await runIndexAndCollect();
-                // Re-emit the profile-filtered audit summary for this cycle's selection.
-                if (profileFilteredRefs.length > 0) {
-                    appendEvent({
-                        eventType: "improve_skipped",
-                        ref: undefined,
-                        metadata: { reason: "profile_filtered_all_passes", count: profileFilteredRefs.length },
-                    }, eventsCtx);
-                }
-            }
-            // #607: acquire consolidate.lock for the preparation stage (consolidate,
-            // ensureIndex, extract all write index.db). Released immediately after.
-            const consolidateLPath = processLockPath(lockBaseDir, "consolidate");
-            preparation = await withOptionalProcessLock({
-                lockPath: consolidateLPath,
-                staleAfterMs: PROCESS_LOCK_DEFS.consolidate.staleAfterMs,
-                skipIfLocked: options.skipIfLocked,
-                label: "consolidate",
-            }, () => runImprovePreparationStageImpl({
+    }
+    return postLockLoopRefs;
+}
+/**
+ * Post-loop stage, or a no-op skip when the shared wall-clock budget is
+ * already exhausted. The result still finalizes normally on skip, so
+ * scheduled budget exhaustion exits 0 (extracted verbatim from
+ * `runImproveStageSequence` — fn-size decomposition, no logic change).
+ */
+async function runPostLoopStageOrSkip(args) {
+    const { budgetAbortController, scope, options, primaryStashDir, preparation, memoryRefsForInference, reindexFn, eventsCtx, improveProfile, resolvedPlan, runImprovePostLoopStageImpl, } = args;
+    // Do not start new post-loop work after the shared wall-clock budget. The
+    // result still finalizes normally, so scheduled budget exhaustion exits 0.
+    const emptyPostLoopResult = {
+        allWarnings: [],
+        memoryInferenceDurationMs: 0,
+        graphExtractionDurationMs: 0,
+    };
+    const remainingBudget = budgetAbortController.signal.remainingBudgetMs;
+    if (budgetAbortController.signal.aborted || (remainingBudget !== undefined && remainingBudget <= 0)) {
+        info("[improve] post-loop maintenance skipped (wall-clock budget exhausted)");
+        return emptyPostLoopResult;
+    }
+    return runImprovePostLoopStageImpl({
+        scope,
+        options,
+        primaryStashDir,
+        actionableRefs: preparation.actionableRefs,
+        appliedCleanup: preparation.appliedCleanup,
+        cleanupWarnings: preparation.cleanupWarnings,
+        memoryRefsForInference,
+        reindexFn,
+        eventsCtx,
+        budgetSignal: budgetAbortController.signal,
+        improveProfile,
+        resolvedPlan,
+        consolidationRan: preparation.consolidationRan,
+        // R5: floor violations from this run's consolidate pass, for the collapse
+        // detector's merge-floor advisory.
+        consolidationMergeFloorViolations: preparation.consolidation.mergeFloorViolations ?? 0,
+    });
+}
+/**
+ * Stage-sequencing: the strategy-filtered audit event, then the single
+ * prep → loop → post-loop pass via the #616 seams (D12). Returns every
+ * accumulator the result assembly reads — the old closure-scoped `let`s.
+ */
+async function runImproveStageSequence(args) {
+    const { strategyFilteredRefs, plannedRefs, memoryCleanupPlan, memorySummary, preEnsureCleanupWarnings, eventsCtx, ctx, } = args;
+    const { scope, options, primaryStashDir, startMs, budgetMs, improveProfile, resolvedPlan, budgetAbortController, selectedStrategy, reflectFn, distillFn, reindexFn, runImprovePreparationStageImpl, runImproveLoopStageImpl, runImprovePostLoopStageImpl, } = args.run;
+    // 2026-05-27: one summary `improve_skipped` audit event (count only) for
+    // planner-pre-filtered refs — never per-ref (#592: O(n) sequential state.db
+    // writes cost ~500 s on a 9 000-ref stash; health reads the counters).
+    if (strategyFilteredRefs.length > 0) {
+        appendEvent({
+            eventType: "improve_skipped",
+            ref: undefined,
+            metadata: {
+                strategy: selectedStrategy.name,
+                reason: "strategy_filtered_all_passes",
+                count: strategyFilteredRefs.length,
+            },
+        }, eventsCtx);
+    }
+    // D8 — one event per lane the autonomy gate downgraded, naming the lane AND
+    // the config key that would enable it. This is the difference between a gate
+    // and a silent no-op: whatever the user would have seen happen, they now see
+    // explained. `health` already aggregates `improve_skipped` by reason
+    // (buildImproveSkipSummary), so these surface there without new machinery.
+    for (const lane of [...args.run.resolvedPlan.autonomyGated, ...describeGatedLanes(args.autonomyGatedDirectLanes)]) {
+        warn(`[improve] ${lane.lane} skipped — it ${lane.reason}. Set \`${lane.configKey}: true\` to enable it.`);
+        appendEvent({
+            eventType: "improve_skipped",
+            ref: undefined,
+            metadata: {
+                strategy: selectedStrategy.name,
+                reason: "autonomy_gated",
+                lane: lane.lane,
+                configKey: lane.configKey,
+            },
+        }, eventsCtx);
+    }
+    // Single prep->loop->post-loop pass, run under the invocation's lock.
+    // Accumulators are direct assignments from the single pass's results.
+    let preparation;
+    let memoryRefsForInference = new Set();
+    let consolidation;
+    let memoryInference;
+    let graphExtraction;
+    let cycleMetrics;
+    // Summed counters/durations.
+    let reflectsWithErrorContext = 0;
+    let memoryInferenceDurationMs = 0;
+    let graphExtractionDurationMs = 0;
+    let orphansPurged;
+    let proposalsExpired;
+    // Concatenated arrays.
+    const allWarnings = [];
+    let deadUrls;
+    const finalActions = [];
+    {
+        const runPreparation = () => runImprovePreparationStageImpl({
+            scope,
+            options,
+            plannedRefs,
+            memoryCleanupPlan,
+            primaryStashDir,
+            memorySummary,
+            reindexFn,
+            startMs,
+            budgetMs,
+            eventsCtx,
+            initialCleanupWarnings: preEnsureCleanupWarnings,
+            improveProfile,
+            resolvedPlan,
+            strategyName: selectedStrategy.name,
+            budgetSignal: budgetAbortController.signal,
+        });
+        preparation = await runPreparation();
+        const rejectedProposalsByRef = preloadRejectedProposals();
+        const runLoop = () => {
+            const postLockLoopRefs = refilterProactiveLoopRefs(preparation.loopRefs, improveProfile);
+            return runImproveLoopStageImpl({
+                ctx,
+                primaryStashDir,
                 scope,
                 options,
-                plannedRefs,
-                memoryCleanupPlan,
-                primaryStashDir,
-                memorySummary,
-                reindexFn,
+                reflectFn,
+                distillFn,
+                loopRefs: postLockLoopRefs,
+                actions: preparation.actions,
+                signalBearingSet: preparation.signalBearingSet,
+                distillCooledRefs: preparation.distillCooledRefs,
+                distillOnlyRefs: preparation.distillOnlyRefs,
+                recentErrors: preparation.recentErrors,
+                rejectedProposalsByRef,
+                utilityMap: preparation.utilityMap,
                 startMs,
                 budgetMs,
-                eventsCtx,
-                initialCleanupWarnings: preEnsureCleanupWarnings,
                 improveProfile,
-                budgetSignal: budgetAbortController.signal,
-            }));
-            prepGateCount += preparation.gateAutoAcceptedCount;
-            prepGateFailedCount += preparation.gateAutoAcceptFailedCount;
-            // 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);
-                }
-            }
-            // #607: acquire reflect-distill.lock for the loop stage (reflect + distill
-            // both write proposals to state.db). Released immediately after.
-            const reflectDistillLPath = processLockPath(lockBaseDir, "reflectDistill");
-            const loopResult = await withOptionalProcessLock({
-                lockPath: reflectDistillLPath,
-                staleAfterMs: PROCESS_LOCK_DEFS.reflectDistill.staleAfterMs,
-                skipIfLocked: options.skipIfLocked,
-                label: "reflect-distill",
-            }, () => {
-                // Post-lock cooldown re-filter for proactive refs (#SELECT-TIME-LEAK).
-                // Planning built `lastReflectProposalTs` BEFORE acquiring this lock, so a
-                // concurrent run's `reflect_invoked` writes are invisible to it. Now that
-                // we hold the lock, re-read fresh timestamp maps for the proactive subset
-                // and drop any ref whose cooldown has been consumed by the concurrent run.
-                const proactiveLoopRefs = preparation.loopRefs.filter((r) => r.eligibilitySource === "proactive");
-                let postLockLoopRefs = preparation.loopRefs;
-                if (proactiveLoopRefs.length > 0) {
-                    const proactiveRefStrs = proactiveLoopRefs.map((r) => r.ref);
-                    const freshReflectTs = buildLatestProposalTsMap(proactiveRefStrs, "reflect");
-                    const freshDistillTs = buildLatestProposalTsMap(proactiveRefStrs, "distill");
-                    const pmDueDays = improveProfile.processes?.proactiveMaintenance?.dueDays ?? DEFAULT_DUE_DAYS;
-                    const stillDue = new Set(filterProactiveDue(proactiveLoopRefs, freshReflectTs, freshDistillTs, pmDueDays, Date.now()).map((r) => r.ref));
-                    const dropped = proactiveLoopRefs.filter((r) => !stillDue.has(r.ref));
-                    if (dropped.length > 0) {
-                        info(`[improve] post-lock cooldown re-filter: dropped ${dropped.length} proactive ref(s) claimed by concurrent run (${dropped.map((r) => r.ref).join(", ")})`);
-                        postLockLoopRefs = preparation.loopRefs.filter((r) => r.eligibilitySource !== "proactive" || stillDue.has(r.ref));
-                    }
-                }
-                return runImproveLoopStageImpl({
-                    scope,
-                    options,
-                    primaryStashDir,
-                    reflectFn,
-                    distillFn,
-                    loopRefs: postLockLoopRefs,
-                    actions: preparation.actions,
-                    signalBearingSet: preparation.signalBearingSet,
-                    distillCooledRefs: preparation.distillCooledRefs,
-                    distillOnlyRefs: preparation.distillOnlyRefs,
-                    recentErrors: preparation.recentErrors,
-                    rejectedProposalsByRef,
-                    utilityMap: preparation.utilityMap,
-                    startMs,
-                    budgetMs,
-                    eventsCtx,
-                    improveProfile,
-                    budgetSignal: budgetAbortController.signal,
-                });
+                resolvedPlan,
             });
-            const loopGateCountThisCycle = loopResult.gateAutoAcceptedCount;
-            reflectsWithErrorContext += loopResult.reflectsWithErrorContext;
-            loopGateCount += loopResult.gateAutoAcceptedCount;
-            loopGateFailedCount += loopResult.gateAutoAcceptFailedCount;
-            memoryRefsForInference = loopResult.memoryRefsForInference;
-            // #551: consolidation now runs in the preparation stage (before extract);
-            // its result and run-flag are read from `preparation`, not the post-loop.
-            consolidation = preparation.consolidation;
-            // #607: acquire consolidate.lock for the post-loop stage (memoryInference +
-            // graphExtraction both write index.db). Released immediately after.
-            const consolidatePostLPath = processLockPath(lockBaseDir, "consolidate");
-            const postLoopResult = await withOptionalProcessLock({
-                lockPath: consolidatePostLPath,
-                staleAfterMs: PROCESS_LOCK_DEFS.consolidate.staleAfterMs,
-                skipIfLocked: options.skipIfLocked,
-                label: "consolidate",
-            }, () => runImprovePostLoopStageImpl({
-                scope,
-                options,
-                primaryStashDir,
-                actionableRefs: preparation.actionableRefs,
-                appliedCleanup: preparation.appliedCleanup,
-                cleanupWarnings: preparation.cleanupWarnings,
-                memoryRefsForInference,
-                reindexFn,
-                eventsCtx,
-                budgetSignal: budgetAbortController.signal,
-                improveProfile,
-                consolidationRan: preparation.consolidationRan,
-                // R5: floor violations from this run's consolidate pass + the
-                // auto-accepted volume so far (prep + loop gates) for churn detection.
-                consolidationMergeFloorViolations: preparation.consolidation.mergeFloorViolations ?? 0,
-                acceptedActions: preparation.gateAutoAcceptedCount + loopGateCountThisCycle,
-            }));
-            const postLoopGateCountThisCycle = postLoopResult.gateAutoAcceptedCount;
-            // Last-wins point-in-time objects.
-            memoryInference = postLoopResult.memoryInference;
-            graphExtraction = postLoopResult.graphExtraction;
-            recombination = postLoopResult.recombination;
-            proceduralCompilation = postLoopResult.proceduralCompilation;
-            // Keep the last QUALIFYING cycle's snapshot — a later non-qualifying
-            // cycle in a maxCycles>1 run must not clobber it with undefined.
-            if (postLoopResult.cycleMetrics)
-                cycleMetrics = postLoopResult.cycleMetrics;
-            // Summed counters/durations.
-            postLoopGateCount += postLoopResult.gateAutoAcceptedCount;
-            postLoopGateFailedCount += postLoopResult.gateAutoAcceptFailedCount;
-            memoryInferenceDurationMs += postLoopResult.memoryInferenceDurationMs;
-            graphExtractionDurationMs += postLoopResult.graphExtractionDurationMs;
-            if (postLoopResult.orphansPurged !== undefined) {
-                orphansPurged = (orphansPurged ?? 0) + postLoopResult.orphansPurged;
-            }
-            if (postLoopResult.proposalsExpired !== undefined) {
-                proposalsExpired = (proposalsExpired ?? 0) + postLoopResult.proposalsExpired;
-            }
-            // Concatenated arrays.
-            allWarnings.push(...postLoopResult.allWarnings);
-            if (postLoopResult.deadUrls !== undefined) {
-                deadUrls = [...(deadUrls ?? []), ...postLoopResult.deadUrls];
-            }
-            const maintenanceActions = postLoopResult.maintenanceActions;
-            if (maintenanceActions && maintenanceActions.length > 0) {
-                finalActions.push(...preparation.actions, ...maintenanceActions);
-            }
-            else {
-                finalActions.push(...preparation.actions);
-            }
-            cyclesRun++;
-            // #616 fixed-point stop: a cycle that produced ZERO gate-accepted proposals
-            // (summed across prep + loop + post-loop) would feed cycle N+1 an identical
-            // ref set, so end the loop here rather than spin a pointless next cycle.
-            const gateAcceptedThisCycle = preparation.gateAutoAcceptedCount + loopGateCountThisCycle + postLoopGateCountThisCycle;
-            if (gateAcceptedThisCycle === 0)
-                break;
-        }
-        // C1 (13-bus-factor): fold the per-ref `distill-skipped` rows (~13k/run,
-        // ~91% of result_json bytes) into a bounded aggregate BEFORE persistence.
-        // The metric total + per-reason breakdown are preserved on `distillSkipped`;
-        // the unbounded row list never reaches result_json. Reflect skip counters
-        // below still read `finalActions` (reflect skips are not folded).
-        const { actions: persistedActions, aggregate: distillSkippedAggregate } = foldDistillSkipped(finalActions);
-        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,
-            ...(profileFilteredRefs.length > 0 ? { profileFilteredRefs } : {}),
-            actions: persistedActions,
-            ...(distillSkippedAggregate ? { distillSkipped: distillSkippedAggregate } : {}),
-            ...(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.extract && preparation.extract.length > 0 ? { extract: preparation.extract } : {}),
-            ...(primaryStashDir !== undefined ? { evalCasesWritten: countEvalCases(primaryStashDir) } : {}),
-            ...(deadUrls !== undefined && deadUrls.length > 0 ? { deadUrls } : {}),
-            ...(reflectsWithErrorContext > 0 ? { reflectsWithErrorContext } : {}),
-            ...(memoryInference ? { memoryInference } : {}),
-            ...(graphExtraction ? { graphExtraction } : {}),
-            // Per-phase wall-clock durations. Surfaced at the top level of the
-            // envelope (not nested) because `health.ts`'s `wallTime.byPhase`
-            // aggregator and the existing `memoryInference.durationMs` /
-            // `graphExtraction.durationMs` health buckets all read
-            // `result.{memoryInferenceDurationMs,graphExtractionDurationMs}`
-            // directly. Mirrors how `consolidation.durationMs` is surfaced inside
-            // the consolidation sub-object (different convention because the
-            // consolidation result type already owns that field). Phases that did
-            // not run (zero duration) are omitted so the aggregator's
-            // "phase actually ran" filter (`> 0`) excludes them from the median/p95
-            // sample. Plumbed in d1273d0's follow-up — see
-            // `/tmp/akm-health-investigations/metrics-taxonomy-review.md` §1k / §3.
-            ...(memoryInferenceDurationMs > 0 ? { memoryInferenceDurationMs } : {}),
-            ...(graphExtractionDurationMs > 0 ? { graphExtractionDurationMs } : {}),
-            ...(recombination ? { recombination } : {}),
-            ...(proceduralCompilation ? { proceduralCompilation } : {}),
-            ...(cycleMetrics ? { cycleMetrics } : {}),
-            ...(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,
-            reflectGuardRejectedActions: finalActions.filter((a) => a.mode === "reflect-guard-rejected").length,
-            ...(() => {
-                const t = prepGateCount + loopGateCount + postLoopGateCount;
-                return t > 0 ? { gateAutoAcceptedCount: t } : {};
-            })(),
-            ...(() => {
-                const f = prepGateFailedCount + loopGateFailedCount + postLoopGateFailedCount;
-                return f > 0 ? { gateAutoAcceptFailedCount: f } : {};
-            })(),
-            ...(triageDrain
-                ? {
-                    triage: {
-                        promoted: triageDrain.promoted.length,
-                        rejected: triageDrain.rejected.length,
-                        deferred: triageDrain.deferred.length,
-                        skippedByCap: triageDrain.skippedByCap.length,
-                    },
-                }
-                : {}),
-            ...(preparation.proactiveMaintenance ? { proactiveMaintenance: preparation.proactiveMaintenance } : {}),
-            // #616 — report cycles run only when >1 so the default single-pass
-            // serialized envelope stays byte-identical to pre-#616 (AC1).
-            ...(cyclesRun > 1 ? { cyclesRun } : {}),
-            ...(options.runId !== undefined ? { runId: options.runId } : {}),
         };
-        if (!result.dryRun)
-            emitImproveCompletedEvent(result, {
-                memoryInferenceDurationMs,
-                graphExtractionDurationMs,
-                totalDurationMs: Date.now() - startMs,
-                warningCount: allWarnings.length,
-                orphansPurged: orphansPurged ?? 0,
-            }, eventsCtx);
-        // End-of-run BATCH auto-sync — the converged commit. Recognition is
-        // decoupled from the per-write path (see write-source.ts case-3): the primary
-        // stash writes as a filesystem source during the run, then is committed via
-        // the same `saveGitStash` that `akm sync` calls. The gating (git-backed
-        // primary stash, sync not disabled) and the NON-FATAL guarantee now live in
-        // `commitStashBatch` (#662); the inter-cycle and catch-path calls reuse it.
-        // dry-run already returned above, so this always runs on a completed live
-        // run. `result.sync` reflects this final commit (for a one-cycle run it is
-        // the only commit; for a multi-cycle run the earlier cycles were banked by
-        // the inter-cycle calls and this records the last batch). `result` carries
-        // the full `{accepted}`/`{refs}`/`{triage_*}` token data for the message.
-        result.sync = commitStashBatch(result);
-        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: errMessage(err),
-                durationMs: Date.now() - startMs,
-            },
-        }, eventsCtx);
-        // #662 crash/abort safety net: commit whatever this run already wrote to the
-        // primary stash BEFORE rethrowing, so an interrupted run (mid-cycle crash or
-        // a cooperative budget abort that surfaces as a throw) does not leave its
-        // writes uncommitted until a later clean run sweeps them up. Best-effort —
-        // `commitStashBatch` swallows its own errors and no-ops a clean tree, so this
-        // never masks or supersedes the original failure being rethrown below.
-        commitStashBatch({ scope, plannedRefs, runId: options.runId });
-        throw err;
-    }
-    finally {
-        // #576: clear the per-run LLM usage sink BEFORE closing `eventsDb` below, so
-        // no late sink invocation can write through a closed handle.
-        disposeLlmUsageSink();
-        // O-1 (#364): Clear the budget abort timer so it does not keep the event
-        // loop alive after the run completes.
-        clearBudgetTimer();
-        // #607: release any per-process locks still held (backstop for error paths;
-        // the normal path already released each lock after its stage completed).
-        releaseAllProcessLocks();
-        // Drop ONLY our own process.exit backstop so it does not fire later (or
-        // accumulate across repeated in-process calls). Must NOT use
-        // removeAllListeners("exit") here: in the in-process model (tests and
-        // programmatic callers import cli.ts) that would silently destroy exit
-        // handlers owned by the host or other commands.
-        if (exitBackstop) {
-            process.removeListener("exit", exitBackstop);
-            exitBackstop = undefined;
+        const loopResult = await runLoop();
+        reflectsWithErrorContext += loopResult.reflectsWithErrorContext;
+        memoryRefsForInference = loopResult.memoryRefsForInference;
+        // #551: consolidation now runs in the preparation stage (before extract);
+        // its result and run-flag are read from `preparation`, not the post-loop.
+        consolidation = preparation.consolidation;
+        const postLoopResult = await runPostLoopStageOrSkip({
+            budgetAbortController,
+            scope,
+            options,
+            primaryStashDir,
+            preparation,
+            memoryRefsForInference,
+            reindexFn,
+            eventsCtx,
+            improveProfile,
+            resolvedPlan,
+            runImprovePostLoopStageImpl,
+        });
+        // Result objects (single pass — no cycle accumulation).
+        memoryInference = postLoopResult.memoryInference;
+        graphExtraction = postLoopResult.graphExtraction;
+        if (postLoopResult.cycleMetrics)
+            cycleMetrics = postLoopResult.cycleMetrics;
+        // Summed counters/durations.
+        memoryInferenceDurationMs += postLoopResult.memoryInferenceDurationMs;
+        graphExtractionDurationMs += postLoopResult.graphExtractionDurationMs;
+        if (postLoopResult.orphansPurged !== undefined) {
+            orphansPurged = (orphansPurged ?? 0) + postLoopResult.orphansPurged;
         }
-        // I1: close the long-lived state.db connection opened at the top of the run.
-        try {
-            eventsDb?.close();
+        if (postLoopResult.proposalsExpired !== undefined) {
+            proposalsExpired = (proposalsExpired ?? 0) + postLoopResult.proposalsExpired;
         }
-        catch {
-            // ignore — DB may already be closed
+        // Concatenated arrays.
+        allWarnings.push(...postLoopResult.allWarnings);
+        if (postLoopResult.deadUrls !== undefined) {
+            deadUrls = [...(deadUrls ?? []), ...postLoopResult.deadUrls];
+        }
+        const maintenanceActions = postLoopResult.maintenanceActions;
+        if (maintenanceActions && maintenanceActions.length > 0) {
+            finalActions.push(...preparation.actions, ...maintenanceActions);
+        }
+        else {
+            finalActions.push(...preparation.actions);
         }
     }
+    return {
+        preparation,
+        memoryRefsForInference,
+        consolidation,
+        memoryInference,
+        graphExtraction,
+        cycleMetrics,
+        reflectsWithErrorContext,
+        memoryInferenceDurationMs,
+        graphExtractionDurationMs,
+        orphansPurged,
+        proposalsExpired,
+        allWarnings,
+        deadUrls,
+        finalActions,
+    };
+}
+/**
+ * Run-teardown, result half: assemble the AkmImproveResult envelope and emit
+ * the improve_completed event (same adjacency as the old inline code — no
+ * side effects run between assembly and emit).
+ */
+function finalizeImproveResult(args) {
+    const { guidance, memorySummary, memoryCleanupPlan, strategyFilteredRefs, triageDrain, eventsCtx } = args;
+    const { selectedStrategy, scope, options, primaryStashDir, startMs } = args.run;
+    const { preparation, consolidation, memoryInference, graphExtraction, cycleMetrics, reflectsWithErrorContext, memoryInferenceDurationMs, graphExtractionDurationMs, orphansPurged, proposalsExpired, allWarnings, deadUrls, finalActions, } = args.seq;
+    // C1 (13-bus-factor): fold the per-ref `distill-skipped` rows (~13k/run,
+    // ~91% of result_json bytes) into a bounded aggregate BEFORE persistence.
+    // The metric total + per-reason breakdown are preserved on `distillSkipped`;
+    // the unbounded row list never reaches result_json. Reflect skip counters
+    // below still read `finalActions` (reflect skips are not folded).
+    const { actions: persistedActions, aggregate: distillSkippedAggregate } = foldDistillSkipped(finalActions);
+    const result = {
+        schemaVersion: 2,
+        ok: true,
+        strategy: selectedStrategy.name,
+        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,
+        ...(strategyFilteredRefs.length > 0 ? { strategyFilteredRefs } : {}),
+        actions: persistedActions,
+        ...(distillSkippedAggregate ? { distillSkipped: distillSkippedAggregate } : {}),
+        ...(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.extract && preparation.extract.length > 0 ? { extract: preparation.extract } : {}),
+        ...(primaryStashDir !== undefined ? { evalCasesWritten: countEvalCases(primaryStashDir) } : {}),
+        ...(deadUrls !== undefined && deadUrls.length > 0 ? { deadUrls } : {}),
+        ...(reflectsWithErrorContext > 0 ? { reflectsWithErrorContext } : {}),
+        ...(memoryInference ? { memoryInference } : {}),
+        ...(graphExtraction ? { graphExtraction } : {}),
+        // Per-phase wall-clock durations. Surfaced at the top level of the
+        // envelope (not nested) because `health.ts`'s `wallTime.byPhase`
+        // aggregator and the existing `memoryInference.durationMs` /
+        // `graphExtraction.durationMs` health buckets all read
+        // `result.{memoryInferenceDurationMs,graphExtractionDurationMs}`
+        // directly. Mirrors how `consolidation.durationMs` is surfaced inside
+        // the consolidation sub-object (different convention because the
+        // consolidation result type already owns that field). Phases that did
+        // not run (zero duration) are omitted so the aggregator's
+        // "phase actually ran" filter (`> 0`) excludes them from the median/p95
+        // sample. Plumbed in d1273d0's follow-up — see
+        // `/tmp/akm-health-investigations/metrics-taxonomy-review.md` §1k / §3.
+        ...(memoryInferenceDurationMs > 0 ? { memoryInferenceDurationMs } : {}),
+        ...(graphExtractionDurationMs > 0 ? { graphExtractionDurationMs } : {}),
+        ...(cycleMetrics ? { cycleMetrics } : {}),
+        ...(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,
+        reflectGuardRejectedActions: finalActions.filter((a) => a.mode === "reflect-guard-rejected").length,
+        ...(triageDrain
+            ? {
+                triage: {
+                    promoted: triageDrain.promoted.length,
+                    rejected: triageDrain.rejected.length,
+                    deferred: triageDrain.deferred.length,
+                    skippedByCap: triageDrain.skippedByCap.length,
+                },
+            }
+            : {}),
+        ...(preparation.proactiveMaintenance ? { proactiveMaintenance: preparation.proactiveMaintenance } : {}),
+        ...(options.runId !== undefined ? { runId: options.runId } : {}),
+    };
+    if (!result.dryRun)
+        emitImproveCompletedEvent(result, {
+            memoryInferenceDurationMs,
+            graphExtractionDurationMs,
+            totalDurationMs: Date.now() - startMs,
+            warningCount: allWarnings.length,
+            orphansPurged: orphansPurged ?? 0,
+        }, eventsCtx);
+    return result;
 }
 function emitImproveCompletedEvent(result, durations, eventsCtx) {
     const actionCounts = {
@@ -942,6 +1144,7 @@ function emitImproveCompletedEvent(result, durations, eventsCtx) {
             ? result.scope.value
             : `improve:${result.scope.mode}:${result.scope.value ?? "all"}`,
         metadata: {
+            strategy: result.strategy,
             plannedRefs: result.plannedRefs.length,
             reflectActions: actionCounts.reflect,
             distillActions: actionCounts.distill,