akm-cli 0.9.0-beta.2 → 0.9.0-beta.3

package/dist/commands/improve/improve.js

@@ -12,6 +12,7 @@ import { ConfigError, NotFoundError, rethrowIfTestIsolationError, UsageError } f
 import { appendEvent, readEvents } from "../../core/events.js";
 import { probeLock, releaseLock, releaseLockIfOwned, tryAcquireLockSync } from "../../core/file-lock.js";
 import { classifyImproveAction } from "../../core/improve-types.js";
+import { openLogsDatabase, purgeOldTaskLogs } from "../../core/logs-db.js";
 import { getDbPath, getStateDbPathInDataDir } from "../../core/paths.js";
 import { openStateDatabase, purgeOldEvents, purgeOldImproveRuns } from "../../core/state-db.js";
 import { info, warn } from "../../core/warn.js";
@@ -27,6 +28,8 @@ import { resolveAssetPath } from "../../indexer/walk/path-resolver.js";
 import { resolveImproveProcessRunnerFromProfile, resolveTriageJudgmentRunner } from "../../integrations/agent/runner.js";
 import { getAvailableHarnesses } from "../../integrations/session-logs/index.js";
 import { isLlmFeatureEnabled, isProcessEnabled } from "../../llm/feature-gate.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 { akmLint } from "../lint/index.js";
 import { drainProposals } from "../proposal/drain.js";
@@ -112,7 +115,7 @@ async function collectEligibleRefs(scope, stashDir, improveProfile) {
             };
         }
         return {
-            plannedRefs: [{ ref: scope.value, reason: "scope-ref" }],
+            plannedRefs: [{ ref: scope.value, reason: "scope-ref", filePath }],
             memorySummary: {
                 eligible: parsed.type === "memory" ? 1 : 0,
                 derived: parsed.type === "memory" && parsed.name.endsWith(".derived") ? 1 : 0,
@@ -176,12 +179,14 @@ async function collectEligibleRefs(scope, stashDir, improveProfile) {
                     profileFiltered.set(ref, {
                         ref,
                         reason: "profile_filtered_all_passes",
+                        filePath: indexed.filePath,
                     });
                 }
                 else {
                     planned.set(ref, {
                         ref,
                         reason: scope.mode === "type" ? "scope-type" : indexed.entry.type === "memory" ? "memory-cleanup" : "scope-type",
+                        filePath: indexed.filePath,
                     });
                 }
             }
@@ -717,7 +722,7 @@ export async function akmImprove(options = {}) {
         if (primaryStashDir && shouldAnalyzeMemoryCleanup(scope, memorySummary.eligible, primaryStashDir)) {
             try {
                 // Reuse the config resolved at the top of the run instead of a second load.
-                await detectAndWriteContradictions(primaryStashDir, _earlyConfig);
+                await withLlmStage("memory-contradiction", () => detectAndWriteContradictions(primaryStashDir, _earlyConfig));
             }
             catch (err) {
                 // Non-fatal: contradiction detection is a best-effort pass.
@@ -777,6 +782,9 @@ export async function akmImprove(options = {}) {
     // 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 = () => { };
     try {
         // H7 (#566): arm the budget watchdog. `armBudgetWatchdog` captures both the
         // budget timer and the hard-kill timer it schedules on exhaustion, returning
@@ -796,17 +804,26 @@ export async function akmImprove(options = {}) {
             // still pinned to the boundary-resolved path, never a live env re-read.
             eventsCtx = { dbPath: resolvedStateDbPath };
         }
-        // 2026-05-27: emit `improve_skipped` audit events for refs the planner
+        // #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). One event per ref so the existing improve_skipped histogram in
-        // `health.ts#improveSummary.skipReasons` accumulates the right count under
-        // the new `profile_filtered_all_passes` reason code. See
-        // `/tmp/akm-health-investigations/planner-profile-metrics-deep-analysis.md`.
-        for (const filtered of profileFilteredRefs) {
+        // 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: filtered.ref,
-                metadata: { reason: "profile_filtered_all_passes" },
+                ref: undefined,
+                metadata: {
+                    reason: "profile_filtered_all_passes",
+                    count: profileFilteredRefs.length,
+                },
             }, eventsCtx);
         }
         const preparation = await runImprovePreparationStage({
@@ -1031,6 +1048,9 @@ export async function akmImprove(options = {}) {
         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();
@@ -1357,7 +1377,7 @@ async function runConsolidationPass(args) {
         info(`[improve] consolidation skipped (pool ${eligiblePoolSize} < minPoolSize ${minPoolSize})`);
     }
     else if (!consolidationOnCooldown) {
-        consolidation = await akmConsolidate({
+        consolidation = await withLlmStage("consolidate", () => akmConsolidate({
             ...options.consolidateOptions,
             config: consolidationConfig,
             stashDir: options.stashDir,
@@ -1380,7 +1400,7 @@ async function runConsolidationPass(args) {
             // options.consolidateOptions.autoAccept (if explicitly provided by caller)
             // still wins because the spread above runs first.
             autoAccept: options.consolidateOptions?.autoAccept ?? options.autoAccept,
-        });
+        }));
         {
             const consolidateGr = await runAutoAcceptGate(consolidation.promoted.map((proposalId) => {
                 try {
@@ -1467,7 +1487,9 @@ async function runImprovePreparationStage(args) {
     // / `akm feedback` invocations. Replaces the akm-plugin session-checkpoint
     // hook with an on-demand pull pipeline.
     //
-    // Default-on; opt out via `profiles.improve.default.processes.extract.enabled: false`.
+    // Default-on; opt out via the ACTIVE profile's `processes.extract.enabled: false`
+    // (#593: the gate respects the resolved improve profile, not just the
+    // hardcoded `default` profile path the legacy feature flag reads).
     // Each available harness gets one call with the default --since window;
     // already-seen sessions (tracked in state.db.extract_sessions_seen) are
     // skipped automatically so re-runs don't burn LLM calls on unchanged data.
@@ -1501,7 +1523,13 @@ async function runImprovePreparationStage(args) {
     const EXTRACT_DEFAULT_MIN_NEW_SESSIONS = 0;
     const configuredMinNewSessions = extractConfig.profiles?.improve?.default?.processes?.extract?.minNewSessions;
     const minNewSessions = typeof configuredMinNewSessions === "number" ? configuredMinNewSessions : EXTRACT_DEFAULT_MIN_NEW_SESSIONS;
-    if (isLlmFeatureEnabled(extractConfig, "session_extraction")) {
+    // #593: gate on BOTH the legacy feature flag (which only reads
+    // `profiles.improve.default.processes.extract.enabled` — kept for back-compat
+    // with users who disable extract via the default-profile path) AND the active
+    // resolved profile. Without the second check a non-default profile setting
+    // `extract.enabled: false` (e.g. the built-in `quick`) was silently ignored
+    // and extract ran on every improve call regardless.
+    if (isLlmFeatureEnabled(extractConfig, "session_extraction") && resolveProcessEnabled("extract", improveProfile)) {
         const availableHarnesses = options.extractHarnesses ?? getAvailableHarnesses();
         // The guard engages only when minNewSessions > 0; 0 disables it entirely.
         let belowMinNewSessions = false;
@@ -1532,7 +1560,7 @@ async function runImprovePreparationStage(args) {
             extractResults = [];
             for (const h of availableHarnesses) {
                 try {
-                    const result = await akmExtract({
+                    const result = await withLlmStage("session-extraction", () => akmExtract({
                         type: h.name,
                         ...(primaryStashDir !== undefined ? { stashDir: primaryStashDir } : {}),
                         config: extractConfig,
@@ -1540,7 +1568,7 @@ async function runImprovePreparationStage(args) {
                         ...(options.extractHarnesses ? { harnesses: options.extractHarnesses } : {}),
                         // C2: pin extract's skip-tracking state.db open to the boundary path.
                         ...(eventsCtx?.dbPath ? { stateDbPath: eventsCtx.dbPath } : {}),
-                    });
+                    }));
                     extractResults.push(result);
                     {
                         const gr = await runAutoAcceptGate(primaryStashDir
@@ -1631,7 +1659,13 @@ async function runImprovePreparationStage(args) {
     const validationFailures = [];
     for (const candidate of postCleanupRefs) {
         try {
-            const filePath = await findAssetFilePath(candidate.ref, options.stashDir);
+            // #591: use the path pre-resolved at planning time when it is still on
+            // disk — a serial async DB lookup per ref cost ~500 s on a 9 000-ref
+            // stash. Fall back to findAssetFilePath only for refs that bypassed
+            // collectEligibleRefs' index scan or whose file moved since planning.
+            const filePath = candidate.filePath && fs.existsSync(candidate.filePath)
+                ? candidate.filePath
+                : await findAssetFilePath(candidate.ref, options.stashDir);
             if (!filePath) {
                 validationFailures.push({ ref: candidate.ref, reason: "file not found on disk" });
                 continue;
@@ -1939,15 +1973,32 @@ async function runImprovePreparationStage(args) {
     const assetMissingOnDisk = [];
     const existsCheckedActionable = [];
     for (const candidate of sorted) {
-        const filePath = await findAssetFilePath(candidate.ref, options.stashDir);
+        // #591: prefer the path pre-resolved at planning time (synchronous
+        // existsSync) over a serial async DB lookup per ref.
+        const filePath = candidate.filePath && fs.existsSync(candidate.filePath)
+            ? candidate.filePath
+            : await findAssetFilePath(candidate.ref, options.stashDir);
         if (filePath && fs.existsSync(filePath)) {
             existsCheckedActionable.push(candidate);
         }
         else {
             assetMissingOnDisk.push(candidate.ref);
-            appendEvent({ eventType: "improve_skipped", ref: candidate.ref, metadata: { reason: "asset_missing_on_disk" } }, eventsCtx);
         }
     }
+    // #592 audit: one summary event instead of one per missing ref. Normally
+    // tiny, but a stash deletion racing the run could make this O(n) sequential
+    // state.db writes. `refs` is capped so the metadata row stays bounded.
+    if (assetMissingOnDisk.length > 0) {
+        appendEvent({
+            eventType: "improve_skipped",
+            ref: undefined,
+            metadata: {
+                reason: "asset_missing_on_disk",
+                count: assetMissingOnDisk.length,
+                refs: assetMissingOnDisk.slice(0, 50),
+            },
+        }, eventsCtx);
+    }
     const actionableRefs = existsCheckedActionable;
     // Re-split actionableRefs (sorted) into reflect-path vs distill-only-path while
     // preserving sort order. distillOnlyRefs participate in the sort so --limit
@@ -2188,9 +2239,11 @@ async function runImproveLoopStage(args) {
                             if (remainingBudgetMs() <= 0)
                                 break;
                             // draftMode: skip DB write so each sample doesn't create a proposal.
-                            samples.push(await reflectFn({ ...reflectCallArgs, draftMode: true }));
+                            samples.push(await withLlmStage("reflect", () => reflectFn({ ...reflectCallArgs, draftMode: true })));
                         }
-                        const winner = pickMajorityVote(samples.length > 0 ? samples : [await reflectFn({ ...reflectCallArgs, draftMode: true })]);
+                        const winner = pickMajorityVote(samples.length > 0
+                            ? samples
+                            : [await withLlmStage("reflect", () => reflectFn({ ...reflectCallArgs, draftMode: true }))]);
                         // Persist only the majority-vote winner as a single real proposal.
                         if (winner.ok && primaryStashDir) {
                             const persistResult = createProposal(primaryStashDir, {
@@ -2215,7 +2268,7 @@ async function runImproveLoopStage(args) {
                         }
                     }
                     else {
-                        reflectResult = await reflectFn(reflectCallArgs);
+                        reflectResult = await withLlmStage("reflect", () => reflectFn(reflectCallArgs));
                     }
                     const isCooldown = !reflectResult.ok && reflectResult.reason === "cooldown";
                     // Content-policy guard hits (reflect size-rail rejections) are NOT
@@ -2232,6 +2285,12 @@ async function runImproveLoopStage(args) {
                     // user's stack were this case; see review §1a row "Reflect refused
                     // asset type".
                     const isTypeRefused = !reflectResult.ok && reflectResult.reason === "unsupported_type";
+                    // Noise-gate suppression (#580): the candidate edit was an empty
+                    // diff or a cosmetic-only reformat of the current asset. Like
+                    // `unsupported_type`, this is a deterministic skip — not an LLM
+                    // fault — so it routes to the `reflect-skipped` bucket and stays
+                    // out of recentErrors/avoidPatterns.
+                    const isNoChange = !reflectResult.ok && reflectResult.reason === "no_change";
                     actions.push({
                         ref: planned.ref,
                         mode: reflectResult.ok
@@ -2240,18 +2299,19 @@ async function runImproveLoopStage(args) {
                                 ? "reflect-cooldown"
                                 : isGuardReject
                                     ? "reflect-guard-rejected"
-                                    : isTypeRefused
+                                    : isTypeRefused || isNoChange
                                         ? "reflect-skipped"
                                         : "reflect-failed",
                         result: reflectResult,
                     });
-                    // Cooldown skips, guard rejects, and type-refused skips are not
-                    // failures — do not pollute recentErrors with them (those get
-                    // injected as `avoidPatterns` into the next reflect prompt). Guard
-                    // rejects ARE worth showing the LLM as a learn-signal so the next
-                    // iteration sees "your last expansion was too large"; type-refused
-                    // is deterministic and adds no learning signal.
-                    if (!reflectResult.ok && !isCooldown && !isTypeRefused) {
+                    // Cooldown skips, guard rejects, type-refused skips, and noise-gate
+                    // skips are not failures — do not pollute recentErrors with them
+                    // (those get injected as `avoidPatterns` into the next reflect
+                    // prompt). Guard rejects ARE worth showing the LLM as a learn-signal
+                    // so the next iteration sees "your last expansion was too large";
+                    // type-refused and no-change are deterministic and add no learning
+                    // signal.
+                    if (!reflectResult.ok && !isCooldown && !isTypeRefused && !isNoChange) {
                         const errMsg = reflectResult.error ?? reflectResult.reason ?? "unknown reflect error";
                         pushRecentError("reflect", errMsg);
                     }
@@ -2373,11 +2433,11 @@ async function runImproveLoopStage(args) {
                         }
                     }
                 }
-                const distillResult = await distillFn({
+                const distillResult = await withLlmStage("distill", () => distillFn({
                     ref: planned.ref,
                     ...(parsedPlannedRef.type === "memory" ? { proposalKind: "auto" } : {}),
                     ...(options.stashDir ? { stashDir: options.stashDir } : {}),
-                });
+                }));
                 actions.push({ ref: planned.ref, mode: "distill", result: distillResult });
                 if (distillResult.outcome === "queued" && distillResult.proposal) {
                     const distillGr = await runAutoAcceptGate([{ proposalId: distillResult.proposal.id, confidence: distillResult.proposal.confidence }], distillGateCfg);
@@ -2518,7 +2578,9 @@ async function runImprovePostLoopStage(args) {
     };
 }
 // TODO(refactor): mutates the passed-in `allWarnings` array as a hidden side channel. Return warnings in ImproveMaintenanceResult and merge in caller — invasive signature change deferred to next refactor pass.
-async function runImproveMaintenancePasses(args) {
+// Exported for tests (#584/#585 DB-locking regression coverage); production
+// callers reach it only through akmImprove → runImprovePostLoopStage.
+export async function runImproveMaintenancePasses(args) {
     const { options, primaryStashDir, memoryRefsForInference, allWarnings, reindexFn, consolidationRan, budgetSignal, eventsCtx, improveProfile, } = args;
     if (!primaryStashDir)
         return { memoryInferenceDurationMs: 0, graphExtractionDurationMs: 0 };
@@ -2537,8 +2599,27 @@ async function runImproveMaintenancePasses(args) {
     let graphExtractionDurationMs = 0;
     let orphansPurged = 0;
     let proposalsExpired = 0;
+    const openIndexDb = () => openDatabase(getDbPath(), config.embedding?.dimension ? { embeddingDim: config.embedding.dimension } : undefined);
+    // #584: reindexFn opens its own write handle on the same index.db WAL file.
+    // Holding our handle across that call produced SQLITE_BUSY / "database is
+    // locked" failures in production, so the handle is closed BEFORE every
+    // reindex and reopened after — the fresh handle also sees the post-reindex
+    // state that graph extraction and staleness detection below rely on. The
+    // reopen runs in `finally` so a failed reindex still leaves a usable handle.
+    const reindexWithIndexDbReleased = async (stashDir) => {
+        if (db) {
+            closeDatabase(db);
+            db = undefined;
+        }
+        try {
+            await reindexFn({ stashDir });
+        }
+        finally {
+            db = openIndexDb();
+        }
+    };
     try {
-        db = openDatabase(getDbPath(), config.embedding?.dimension ? { embeddingDim: config.embedding.dimension } : undefined);
+        db = openIndexDb();
         // Memory inference candidate-discovery (post-Item 9 fix from
         // memory:akm-improve-critical-review-2026-05-20). Previously this pass
         // was gated on memoryRefsForInference.size > 0 AND passed those refs as a
@@ -2564,7 +2645,7 @@ async function runImproveMaintenancePasses(args) {
             const inferenceStart = Date.now();
             try {
                 // O-1 (#364): pass budget signal so a hung inference call is cancelled.
-                memoryInference = await memoryInferenceFn({
+                memoryInference = await withLlmStage("memory-inference", () => memoryInferenceFn({
                     config,
                     sources,
                     signal: budgetSignal,
@@ -2574,7 +2655,7 @@ async function runImproveMaintenancePasses(args) {
                         const current = event.currentRef ? ` ${event.currentRef}` : "";
                         info(`[improve] memory inference ${event.processed}/${event.total}${current} (written ${event.writtenFacts}, skipped ${event.skippedNoFacts})`);
                     },
-                });
+                }));
                 memoryInferenceDurationMs = Date.now() - inferenceStart;
                 actions.push({ ref: "memory:_inference", mode: "memory-inference", result: memoryInference });
                 info(`[improve] memory inference complete (${memoryInference.writtenFacts} facts written from ${memoryInference.splitParents} parents)`);
@@ -2587,7 +2668,7 @@ async function runImproveMaintenancePasses(args) {
         if (memoryInference && (memoryInference.splitParents > 0 || memoryInference.writtenFacts > 0)) {
             info("[improve] reindexing after memory inference writes");
             try {
-                await reindexFn({ stashDir: primaryStashDir });
+                await reindexWithIndexDbReleased(primaryStashDir);
                 reindexedAfterInference = true;
                 info("[improve] reindex after memory inference complete");
             }
@@ -2623,7 +2704,7 @@ async function runImproveMaintenancePasses(args) {
                 if (consolidationRan && !reindexedAfterInference) {
                     info("[improve] reindexing after consolidation (graph extraction needs current state)");
                     try {
-                        await reindexFn({ stashDir: primaryStashDir });
+                        await reindexWithIndexDbReleased(primaryStashDir);
                         reindexedAfterInference = true;
                         info("[improve] reindex after consolidation complete");
                     }
@@ -2631,10 +2712,8 @@ async function runImproveMaintenancePasses(args) {
                         allWarnings.push(`reindex after consolidation failed: ${err instanceof Error ? err.message : String(err)}`);
                     }
                 }
-                if (db && reindexedAfterInference) {
-                    closeDatabase(db);
-                    db = openDatabase(getDbPath(), config.embedding?.dimension ? { embeddingDim: config.embedding.dimension } : undefined);
-                }
+                // #584: no close/reopen needed here — reindexWithIndexDbReleased
+                // already swapped in a fresh post-reindex handle.
                 // Resolve touched refs to absolute file paths. Skipped for fullScan
                 // (candidatePaths stays undefined → extractor processes all files).
                 let candidatePaths;
@@ -2654,7 +2733,7 @@ async function runImproveMaintenancePasses(args) {
                     info(`[improve] graph extraction ${event.processed}/${event.total}${current} (extracted ${event.extracted}, entities ${event.totalEntities}, relations ${event.totalRelations})`);
                 };
                 // O-1 (#364): pass budget signal so a hung graph extraction call is cancelled.
-                graphExtraction = await graphExtractionFn({
+                graphExtraction = await withLlmStage("graph-extraction", () => graphExtractionFn({
                     config,
                     sources,
                     signal: budgetSignal,
@@ -2662,7 +2741,7 @@ async function runImproveMaintenancePasses(args) {
                     reEnrich: false,
                     onProgress: progressHandler,
                     options: { candidatePaths },
-                });
+                }));
                 graphExtractionDurationMs = Date.now() - extractionStart;
                 actions.push({ ref: "graph:_artifact", mode: "graph-extraction", result: graphExtraction });
                 info(`[improve] graph extraction complete (${graphExtraction.quality.extractedFiles} files, ${graphExtraction.quality.entityCount} entities, ${graphExtraction.quality.relationCount} relations)`);
@@ -2733,18 +2812,22 @@ async function runImproveMaintenancePasses(args) {
         // invocation, and every command surface emits at least one event besides —
         // without this trim, state.db is a permanent append-only log. Config key
         // `improve.eventRetentionDays` (default 90, set 0 to disable) controls the
-        // window. `purgeOldEvents()` opens its own state.db handle separate from
-        // the index `db` above (different SQLite file).
+        // window. The purge runs against state.db (a different SQLite file from
+        // the index `db` above).
         {
             const retentionDays = typeof config.improve?.eventRetentionDays === "number" ? config.improve.eventRetentionDays : 90;
             if (retentionDays > 0) {
+                // #585: reuse the long-lived eventsCtx.db connection when akmImprove
+                // opened one — opening a second state.db write connection while
+                // eventsDb is still live made two simultaneous writers contend on the
+                // same WAL file ("database is locked"). Only the eventsCtx.dbPath
+                // fallback path (state.db failed to open up-front) opens — and then
+                // owns and closes — its own handle. C2 still holds: the fallback uses
+                // the boundary-pinned path, never a live `process.env` re-read.
+                const ownsStateDb = !eventsCtx?.db;
                 let stateDb;
                 try {
-                    // C2: reuse the boundary-pinned state.db path carried on eventsCtx so
-                    // this purge open never re-reads `process.env` live mid-run. The path
-                    // is always set by akmImprove; openStateDatabase() falls back to the
-                    // env-derived default only if a caller omitted it entirely.
-                    stateDb = openStateDatabase(eventsCtx?.dbPath);
+                    stateDb = eventsCtx?.db ?? openStateDatabase(eventsCtx?.dbPath);
                     const purgedCount = purgeOldEvents(stateDb, retentionDays);
                     if (purgedCount > 0) {
                         info(`[improve] events purge: ${purgedCount} event(s) older than ${retentionDays}d removed from state.db`);
@@ -2772,7 +2855,7 @@ async function runImproveMaintenancePasses(args) {
                     allWarnings.push(`events purge failed: ${err instanceof Error ? err.message : String(err)}`);
                 }
                 finally {
-                    if (stateDb) {
+                    if (ownsStateDb && stateDb) {
                         try {
                             stateDb.close();
                         }
@@ -2781,6 +2864,37 @@ async function runImproveMaintenancePasses(args) {
                         }
                     }
                 }
+                // task_logs in logs.db (#579) shares the same retention window as
+                // events/improve_runs — all three are observability data governed by
+                // the single improve.eventRetentionDays knob. Separate try/finally
+                // because logs.db is a different file: a locked/missing logs.db must
+                // not block the state.db purges above.
+                let logsDb;
+                try {
+                    logsDb = openLogsDatabase();
+                    const taskLogsPurged = purgeOldTaskLogs(logsDb, retentionDays);
+                    if (taskLogsPurged > 0) {
+                        info(`[improve] task_logs purge: ${taskLogsPurged} log line(s) older than ${retentionDays}d removed from logs.db`);
+                    }
+                    appendEvent({
+                        eventType: "task_logs_purged",
+                        ref: "task_logs:_purge",
+                        metadata: { purgedCount: taskLogsPurged, retentionDays },
+                    }, eventsCtx);
+                }
+                catch (err) {
+                    allWarnings.push(`task_logs purge failed: ${err instanceof Error ? err.message : String(err)}`);
+                }
+                finally {
+                    if (logsDb) {
+                        try {
+                            logsDb.close();
+                        }
+                        catch {
+                            // best-effort
+                        }
+                    }
+                }
             }
         }
         // Phase 4A (staleness detection). Activates the `deprecated` belief-state
@@ -2789,7 +2903,7 @@ async function runImproveMaintenancePasses(args) {
         // and before the URL check (which lives in the outer caller).
         if (sources.length > 0) {
             try {
-                stalenessDetection = await stalenessDetectionFn({ config, sources, signal: budgetSignal, db });
+                stalenessDetection = await withLlmStage("staleness-detection", () => stalenessDetectionFn({ config, sources, signal: budgetSignal, db }));
                 if (stalenessDetection.considered > 0) {
                     info(`[improve] staleness detection complete (considered ${stalenessDetection.considered}, ` +
                         `deprecated ${stalenessDetection.deprecated}, confirmed ${stalenessDetection.confirmed}, ` +

package/dist/commands/improve/reflect.js

@@ -46,6 +46,7 @@ import { baseFailureFields, enoentHintMessage, isEnoentFailure, loadAgentConfigF
 import { checkReflectSize } from "../proposal/validators/proposal-quality-validators.js";
 import { createProposal, isProposalSkipped, listProposals, } from "../proposal/validators/proposals.js";
 import { deriveLessonRef, runLessonQualityJudge } from "./distill.js";
+import { classifyReflectChange } from "./reflect-noise.js";
 const MAX_FEEDBACK_LINES = 10;
 const MAX_GLOBAL_FEEDBACK_LINES = 20;
 /**
@@ -1138,6 +1139,30 @@ export async function akmReflect(options = {}) {
         content: sanitizeOutcome.content,
         ...(sanitizeOutcome.frontmatter ? { frontmatter: sanitizeOutcome.frontmatter } : {}),
     };
+    // 7c. Noise gate (#580): never queue a proposal whose sanitized content is
+    // identical to the current asset (empty diff) or differs only cosmetically
+    // (whitespace reflow, code-fence language hints, YAML scalar re-folding).
+    // Pure deterministic text comparison — see `reflect-noise.ts`. Runs before
+    // the draftMode branch so self-consistency sampling never votes a no-op
+    // candidate into the queue either. Skipped when there is no source asset
+    // (new-asset proposals have nothing to diff against).
+    if (assetContent !== undefined) {
+        const changeKind = classifyReflectChange(assetContent, payload.content);
+        if (changeKind !== "substantive") {
+            const subreason = changeKind === "noop" ? "reflect_skipped_noop" : "reflect_skipped_cosmetic";
+            emitReflectFailed("no_change", subreason, options.ref, { changeKind });
+            return {
+                schemaVersion: 1,
+                ok: false,
+                reason: "no_change",
+                error: changeKind === "noop"
+                    ? `Reflect skipped: proposed content for ${payload.ref} is identical to the current asset (empty diff); no proposal created.`
+                    : `Reflect skipped: proposed content for ${payload.ref} is a cosmetic-only reformat of the current asset (whitespace/fence/YAML-folding changes); no proposal created.`,
+                ...(options.ref ? { ref: options.ref } : {}),
+                exitCode: result.exitCode,
+            };
+        }
+    }
     // 8. Create the proposal. The proposal queue is the ONLY thing reflect
     // writes — promotion to a real asset is gated by `akm proposal accept`.
     //