akm-cli 0.8.0-rc1 → 0.8.0

package/dist/commands/help/help-accept.md

@@ -1,9 +1,12 @@
 Usage:
-  akm accept <id>
+  akm proposal accept <id>
 
 Description:
   Accept a proposal and promote it into the stash.
 
+  (`akm accept` is a deprecated alias for `akm proposal accept`; it warns on
+  stderr and is removed in 0.9.0.)
+
 Examples:
-  akm accept proposal_123
-  akm accept proposal_123 --target team-stash
+  akm proposal accept proposal_123
+  akm proposal accept proposal_123 --target team-stash

package/dist/commands/help/help-improve.md

@@ -30,20 +30,44 @@ Options:
   --task <text>        Add extra guidance for this improvement pass
   --dry-run            Show planned actions without generating proposals
   --target <source>    Override the write target for accepted proposals
-  --auto-accept safe   Automatically accept low-risk proposals
-  --ignore-cooldown    Disable reflect/distill/consolidate cooldown checks for this run
-  --reflect-cooldown-days <n>
-                        Override reflect cooldown with a non-negative integer
-  --distill-cooldown-days <n>
-                        Override distill cooldown with a non-negative integer
-  --consolidate-cooldown-days <n>
-                        Override consolidate cooldown with a non-negative integer
+  --auto-accept[=<value>]
+                        Confidence threshold (0-100) for auto-accepting proposals.
+                        Default when flag is absent: ON at threshold 90 (all sub-processes).
+                        --auto-accept            same as --auto-accept=90
+                        --auto-accept=<N>        integer 0-100; accept proposals at or above N
+                        --auto-accept=safe       alias for 90 (back-compat, not deprecated)
+                        --auto-accept=false      disable auto-accept for all sub-processes;
+                                                 reflect/distill proposals go to the queue and
+                                                 consolidation will prompt interactively on HTTP paths
+                        Note: until proposals carry real confidence scores, any non-`false`
+                        value behaves like the legacy "safe" mode (whole-batch auto-accept).
+  --profile <name>     Improve profile to apply. Built-ins: default, quick,
+                        thorough, memory-focus. User-defined profiles under
+                        `profiles.improve.<name>` in config are also accepted.
+                        Profiles bundle process gating, type filters, and
+                        run-level autoAccept/limit defaults. Falls back to
+                        `defaults.improve` in config, then to "default".
+                        Unknown names fall back to default with a warning.
+                        Sync behavior by profile: default and thorough enable
+                        auto-commit + push; quick and memory-focus skip sync.
+  --sync               Commit (and optionally push) the git-backed primary
+                        stash when the run finishes. Use --no-sync to disable.
+                        Default: per profile config (enabled for default and
+                        thorough, disabled for quick and memory-focus).
+  --push               Push after the end-of-run sync commit when the stash
+                        is writable and has a remote configured. Use --no-push
+                        to commit only. Default: per profile config (true when
+                        sync is enabled).
   --consolidate-recovery <mode>
                         Recovery mode for stale consolidate journals: abort (default) or clean
   --require-feedback-signal
                         Only process refs with recent feedback signal events
   --min-retrieval-count <n>
                         Retrieval fallback threshold when no recent feedback exists (default: 5)
+  --json-to-stdout      Emit the full JSON result on stdout (legacy behaviour).
+                        (0.8.0+: full result is recorded in the improve_runs table of
+                        state.db and stdout is empty; use --json-to-stdout for the prior
+                        behaviour, e.g. `akm improve --json-to-stdout | jq`.)
 
 Examples:
   akm improve
@@ -51,3 +75,7 @@ Examples:
   akm improve skill
   akm improve skill:code-review
   akm improve workflow:incident-response --task "reduce duplication"
+  akm improve --profile quick
+  akm improve --profile memory-focus
+  akm improve --no-sync
+  akm improve --no-push

package/dist/commands/help/help-proposals.md

@@ -1,15 +1,18 @@
 Usage:
-  akm proposals
+  akm proposal list
 
 Description:
   List proposal queue entries.
 
+  (`akm proposals` is a deprecated alias for `akm proposal list`; it warns on
+  stderr and is removed in 0.9.0.)
+
 Options:
   --status <status>    Filter by pending, accepted, or rejected
   --type <type>        Filter by asset type
   --ref <ref>          Filter by exact asset ref
 
 Examples:
-  akm proposals
-  akm proposals --status pending
-  akm proposals --type skill
+  akm proposal list
+  akm proposal list --status pending
+  akm proposal list --type skill

package/dist/commands/help/help-reject.md

@@ -1,8 +1,11 @@
 Usage:
-  akm reject <id> --reason "..."
+  akm proposal reject <id> --reason "..."
 
 Description:
   Reject a proposal and record the reason.
 
+  (`akm reject` is a deprecated alias for `akm proposal reject`; it warns on
+  stderr and is removed in 0.9.0.)
+
 Examples:
-  akm reject proposal_123 --reason "duplicates existing workflow"
+  akm proposal reject proposal_123 --reason "duplicates existing workflow"

package/dist/commands/history.js

@@ -1,21 +1,10 @@
-/**
- * `akm history` — surfaces internal mutation/usage events for a single asset
- * (`--ref`) or stash-wide.
- *
- * Event sources:
- *   - `usage_events` SQLite table: search, show, and feedback events recorded
- *     by the local indexer during normal CLI use.
- *   - `events.jsonl` append-only stream (opt-in via `--include-proposals`):
- *     proposal lifecycle events (`promoted`, `rejected`) emitted by
- *     `akm proposal accept` / `akm proposal reject`. Use this flag to see
- *     the full proposal review trail alongside usage events.
- *
- * The two sources are merged and sorted chronologically (oldest first) so
- * consumers see a coherent lifecycle trail in a single output.
- */
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
 import { parseAssetRef } from "../core/asset-ref";
 import { UsageError } from "../core/errors";
 import { readEvents } from "../core/events";
+import { listProposals } from "../core/proposals";
 import { isoToSqlite, parseSinceToIso } from "../core/time";
 import { closeDatabase, openExistingDatabase } from "../indexer/db";
 // Proposal lifecycle event types emitted by the proposal substrate (#225).
@@ -39,6 +28,7 @@ function toEntry(row) {
         entryId: row.entry_id,
         query: row.query,
         signal: row.signal,
+        source: row.source,
         metadata: parseMetadata(row.metadata),
         createdAt: row.created_at,
     };
@@ -91,8 +81,12 @@ export async function akmHistory(options = {}) {
             conditions.push("created_at >= ?");
             params.push(sinceNormalized);
         }
+        if (options.source !== undefined) {
+            conditions.push("source = ?");
+            params.push(options.source);
+        }
         const where = conditions.length > 0 ? `WHERE ${conditions.join(" AND ")}` : "";
-        const sql = `SELECT id, event_type, query, entry_id, entry_ref, signal, metadata, created_at
+        const sql = `SELECT id, event_type, query, entry_id, entry_ref, signal, metadata, source, created_at
                  FROM usage_events ${where}
                  ORDER BY id ASC`;
         const rows = db.prepare(sql).all(...params);
@@ -127,6 +121,7 @@ export async function akmHistory(options = {}) {
                     entryId: null,
                     query: null,
                     signal: null,
+                    source: null,
                     metadata: event.metadata ?? null,
                     createdAt,
                 });
@@ -142,6 +137,45 @@ export async function akmHistory(options = {}) {
                 return 1;
             return a.id - b.id;
         });
+        // ── Accept-rate-per-source (F-4 / #385) ─────────────────────────────────
+        let acceptRateBySource;
+        if (options.acceptRateBySource) {
+            const stashDir = options.stashDir;
+            if (stashDir) {
+                const bySource = new Map();
+                const countProposals = (statuses, includeArchive) => {
+                    for (const status of statuses) {
+                        const proposals = listProposals(stashDir, { status, includeArchive });
+                        for (const p of proposals) {
+                            const src = p.source || "(unknown)";
+                            const entry = bySource.get(src) ?? { accepted: 0, rejected: 0, pending: 0 };
+                            if (status === "accepted")
+                                entry.accepted++;
+                            else if (status === "rejected")
+                                entry.rejected++;
+                            else
+                                entry.pending++;
+                            bySource.set(src, entry);
+                        }
+                    }
+                };
+                countProposals(["pending"], false);
+                countProposals(["accepted", "rejected"], true);
+                acceptRateBySource = Array.from(bySource.entries())
+                    .map(([source, counts]) => {
+                    const decided = counts.accepted + counts.rejected;
+                    return {
+                        source,
+                        total: decided + counts.pending,
+                        accepted: counts.accepted,
+                        rejected: counts.rejected,
+                        pending: counts.pending,
+                        acceptRate: decided > 0 ? counts.accepted / decided : null,
+                    };
+                })
+                    .sort((a, b) => b.total - a.total); // Most active source first
+            }
+        }
         const response = {
             schemaVersion: 1,
             ...(normalizedRef !== undefined ? { ref: normalizedRef } : {}),
@@ -149,6 +183,7 @@ export async function akmHistory(options = {}) {
             totalCount: entries.length,
             entries,
             sources,
+            ...(acceptRateBySource !== undefined ? { acceptRateBySource } : {}),
         };
         return response;
     }

package/dist/commands/improve-auto-accept.js

@@ -0,0 +1,97 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+import { loadConfig } from "../core/config";
+import { appendEvent } from "../core/events";
+import { promoteProposal } from "../core/proposals";
+import { info, warn } from "../core/warn";
+// ---------------------------------------------------------------------------
+// Gate implementation
+// ---------------------------------------------------------------------------
+/**
+ * Attempt to auto-accept each candidate proposal whose confidence meets the
+ * effective threshold. Safe to call unconditionally — returns all-empty when
+ * the gate is disabled or the run is a dry-run.
+ *
+ * @param candidates  Proposals to evaluate, each with an optional confidence.
+ * @param cfg         Gate configuration (phase label, thresholds, context).
+ * @param promoteFn   Injectable override for `promoteProposal` (test seam).
+ */
+export async function runAutoAcceptGate(candidates, cfg, promoteFn = promoteProposal) {
+    const result = { promoted: [], skipped: [], failed: [] };
+    // --- Guard: gate is disabled or context is incomplete ---
+    if (cfg.dryRun || cfg.globalThreshold === undefined || !cfg.stashDir) {
+        result.skipped = candidates.map((c) => c.proposalId);
+        return result;
+    }
+    const effectiveThreshold = Math.max(cfg.globalThreshold, cfg.minimumThreshold ?? 0) / 100;
+    const resolvedConfig = typeof cfg.config === "function" ? cfg.config() : cfg.config;
+    for (const candidate of candidates) {
+        const { proposalId, confidence } = candidate;
+        if (confidence === undefined || confidence < effectiveThreshold) {
+            result.skipped.push(proposalId);
+            continue;
+        }
+        try {
+            const promotion = await promoteFn(cfg.stashDir, resolvedConfig, proposalId, {}, undefined);
+            appendEvent({
+                eventType: "promoted",
+                ref: promotion.ref,
+                metadata: {
+                    proposalId: promotion.proposal.id,
+                    source: promotion.proposal.source,
+                    ...(promotion.proposal.sourceRun !== undefined ? { sourceRun: promotion.proposal.sourceRun } : {}),
+                    assetPath: promotion.assetPath,
+                    autoAccept: true,
+                    confidence,
+                    threshold: effectiveThreshold,
+                    phase: cfg.phase,
+                },
+            }, cfg.eventsCtx ?? {});
+            info(`[improve] auto-accepted ${promotion.ref} (${cfg.phase}; confidence=${confidence.toFixed(2)} >= threshold=${effectiveThreshold.toFixed(2)})`);
+            result.promoted.push(proposalId);
+        }
+        catch (err) {
+            warn(`[improve] ${cfg.phase} auto-accept failed for ${proposalId}: ${err instanceof Error ? err.message : String(err)}`);
+            result.failed.push(proposalId);
+        }
+    }
+    return result;
+}
+// ---------------------------------------------------------------------------
+// Confidence resolvers
+// ---------------------------------------------------------------------------
+/**
+ * Read the confidence value for an extract proposal.
+ * Extract stores confidence at `payload.frontmatter.confidence` (set by
+ * extract.ts when the LLM response is parsed), not at the top-level field.
+ */
+export function resolveExtractConfidence(proposal) {
+    const fm = proposal.payload.frontmatter;
+    const fmConf = fm?.confidence;
+    if (typeof fmConf === "number")
+        return fmConf;
+    // Fall back to top-level in case a future extract version normalises the path
+    if (typeof proposal.confidence === "number")
+        return proposal.confidence;
+    return undefined;
+}
+// ---------------------------------------------------------------------------
+// Config builder helpers
+// ---------------------------------------------------------------------------
+/**
+ * Build a gate config for a phase, inheriting global settings from the
+ * improve options. Callers supply only the phase-specific overrides.
+ */
+export function makeGateConfig(phase, shared, overrides = {}) {
+    return {
+        phase,
+        globalThreshold: shared.globalThreshold,
+        dryRun: shared.dryRun,
+        stashDir: shared.stashDir,
+        config: shared.config,
+        eventsCtx: shared.eventsCtx,
+        ...overrides,
+    };
+}
+export { loadConfig };

package/dist/commands/improve-cli.js

@@ -0,0 +1,236 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+import path from "node:path";
+import { defineCommand } from "citty";
+import { getStringArg, parseAutoAcceptFlag, parseNonNegativeIntFlag, parsePositiveIntFlag } from "../cli/parse-args";
+import { output, runWithJsonErrors } from "../cli/shared";
+import { loadConfig } from "../core/config";
+import { UsageError } from "../core/errors";
+import { getCacheDir } from "../core/paths";
+import { clearLogFile, setLogFile } from "../core/warn";
+import { resolveSourceEntries } from "../indexer/search-source";
+import { getHyphenatedArg, getHyphenatedBoolean, parseFlagValue } from "../output/context";
+import { akmImprove } from "./improve";
+import { buildImproveRunId, recordTerminatedImproveRun, relativeImproveResultPath, writeImproveResultFile, } from "./improve-result-file";
+export const improveCommand = defineCommand({
+    meta: {
+        name: "improve",
+        description: "Analyze existing AKM assets and generate improvement proposals; also consolidates memories when profiles.improve.default.processes.consolidate.enabled is true",
+    },
+    args: {
+        scope: {
+            type: "positional",
+            description: "Optional asset type or asset ref to improve",
+            required: false,
+        },
+        task: { type: "string", description: "Add extra guidance for this improvement pass" },
+        "dry-run": { type: "boolean", description: "Show planned actions without writing", default: false },
+        target: { type: "string", description: "Override the write target for accepted proposals" },
+        "auto-accept": {
+            type: "string",
+            description: "Auto-accept proposals at or above this confidence threshold (0-100). Default: disabled. Pass a value 0-100 to enable. 'safe' is an alias for 90. Pass 'false' to be explicit.",
+        },
+        limit: { type: "string", description: "Maximum number of assets to process (highest utility first)" },
+        "timeout-ms": {
+            type: "string",
+            description: "Wall-clock budget for the entire run in milliseconds (default: 7200000 = 2 hours)",
+        },
+        "consolidate-recovery": {
+            type: "string",
+            description: "How to handle stale/incomplete consolidation journals: abort (default) or clean (remove stale journal artifacts)",
+        },
+        "require-feedback-signal": {
+            type: "boolean",
+            description: "Only process assets with recent feedback signals (disables retrieval fallback)",
+            default: false,
+        },
+        "min-retrieval-count": {
+            type: "string",
+            description: "Minimum retrieval count for zero-feedback fallback eligibility (default: 1, set 0 to include all assets regardless of retrieval history)",
+        },
+        "json-to-stdout": {
+            type: "boolean",
+            description: "Emit the full JSON result on stdout (legacy behaviour). (0.8.0+: full result is recorded in the improve_runs table of state.db and stdout is empty; use this flag for the prior behaviour, e.g. `akm improve --json-to-stdout | jq`.)",
+            default: false,
+        },
+        profile: {
+            type: "string",
+            description: "Named improve profile from profiles.improve or built-in profiles (default, quick, thorough, memory-focus). Controls which sub-processes run and which asset types are processed.",
+        },
+        sync: {
+            type: "boolean",
+            description: "Commit (and optionally push) the git-backed primary stash when the run finishes. Use --no-sync to disable. Default: on for git-backed stashes (per profile config).",
+        },
+        push: {
+            type: "boolean",
+            description: "Push after the end-of-run sync commit when writable + remote configured. Use --no-push to commit only. Default: per profile config (true).",
+        },
+    },
+    async run({ args }) {
+        await runWithJsonErrors(async () => {
+            const formatFlagValue = parseFlagValue(process.argv, "--format");
+            if (formatFlagValue !== undefined) {
+                throw new UsageError(`akm improve does not accept --format. That flag controls output formatting for other commands (search, show, etc.).\n` +
+                    `Did you mean: akm improve (no --format flag)?`, "INVALID_FLAG_VALUE");
+            }
+            const jsonToStdout = getHyphenatedBoolean(args, "json-to-stdout");
+            const autoAcceptRaw = getHyphenatedArg(args, "auto-accept");
+            const autoAccept = parseAutoAcceptFlag(autoAcceptRaw);
+            const targetArg = getStringArg(args, "target");
+            const taskArg = getStringArg(args, "task");
+            const dryRun = getHyphenatedBoolean(args, "dry-run");
+            const limitRaw = parsePositiveIntFlag(args.limit ?? undefined);
+            const timeoutMs = parsePositiveIntFlag(getHyphenatedArg(args, "timeout-ms"), "--timeout-ms");
+            const consolidateRecoveryRaw = getHyphenatedArg(args, "consolidate-recovery");
+            const consolidateRecovery = consolidateRecoveryRaw === undefined
+                ? undefined
+                : consolidateRecoveryRaw.trim().toLowerCase();
+            if (consolidateRecovery !== undefined && consolidateRecovery !== "abort" && consolidateRecovery !== "clean") {
+                throw new UsageError(`Invalid --consolidate-recovery value: "${consolidateRecoveryRaw}". Must be one of: abort, clean.`, "INVALID_FLAG_VALUE");
+            }
+            const minRetrievalCountRaw = getHyphenatedArg(args, "min-retrieval-count");
+            const minRetrievalCount = parseNonNegativeIntFlag(minRetrievalCountRaw, "--min-retrieval-count");
+            const requireFeedbackSignal = getHyphenatedBoolean(args, "require-feedback-signal");
+            const profileArg = getStringArg(args, "profile");
+            // Only set the keys the user actually passed (citty leaves the flag
+            // undefined unless `--sync`/`--no-sync` / `--push`/`--no-push` appears),
+            // so the resolved profile `sync` block wins by default.
+            const syncFlag = getHyphenatedArg(args, "sync");
+            const pushFlag = getHyphenatedArg(args, "push");
+            const syncOverride = {};
+            if (syncFlag !== undefined)
+                syncOverride.enabled = syncFlag;
+            if (pushFlag !== undefined)
+                syncOverride.push = pushFlag;
+            const improveLogFile = path.join(getCacheDir(), "logs", "improve", `${new Date().toISOString().replace(/[:.]/g, "-")}.log`);
+            setLogFile(improveLogFile);
+            const startedAtMs = Date.now();
+            const startedAtIso = new Date(startedAtMs).toISOString();
+            // Mint the run-id up front so signal handlers can persist a partial
+            // record if the process is killed mid-run. Pre-2026-05-26 the runId
+            // was minted at end-of-run, so SIGTERM'd runs (cron timeout) left no
+            // row in improve_runs and effectively disappeared from `akm health`.
+            const runId = buildImproveRunId();
+            const primaryStashDir = resolveSourceEntries(undefined, loadConfig())[0]?.path;
+            const scopeArg = getStringArg(args, "scope");
+            const inferredScopeMode = (scopeArg ?? "").includes(":") ? "ref" : scopeArg ? "type" : "all";
+            // Signal handler + exception path both flow through this helper so
+            // every abnormal termination produces a row with ok:false and a
+            // reason in metadata.terminated.
+            let runRecorded = false;
+            const persistTerminated = (reason, errorMessage) => {
+                if (runRecorded)
+                    return;
+                if (!primaryStashDir)
+                    return;
+                runRecorded = true;
+                try {
+                    recordTerminatedImproveRun(primaryStashDir, runId, startedAtIso, reason, {
+                        scopeMode: inferredScopeMode,
+                        scopeValue: scopeArg ?? null,
+                        dryRun: Boolean(dryRun),
+                        profile: profileArg ?? null,
+                        ...(errorMessage ? { errorMessage } : {}),
+                    });
+                }
+                catch (err) {
+                    process.stderr.write(`warning: failed to persist terminated improve run ${runId}: ${err instanceof Error ? err.message : String(err)}\n`);
+                }
+            };
+            const sigtermHandler = () => {
+                persistTerminated("SIGTERM");
+                process.stderr.write(`[improve] received SIGTERM; recorded terminated run ${runId}\n`);
+                process.exit(143);
+            };
+            const sigintHandler = () => {
+                persistTerminated("SIGINT");
+                process.stderr.write(`[improve] received SIGINT; recorded terminated run ${runId}\n`);
+                process.exit(130);
+            };
+            const sighupHandler = () => {
+                persistTerminated("SIGHUP");
+                process.exit(129);
+            };
+            process.once("SIGTERM", sigtermHandler);
+            process.once("SIGINT", sigintHandler);
+            process.once("SIGHUP", sighupHandler);
+            let improveResult;
+            try {
+                improveResult = await akmImprove({
+                    scope: scopeArg,
+                    task: taskArg,
+                    dryRun,
+                    target: targetArg,
+                    autoAccept,
+                    ...(limitRaw !== undefined ? { limit: limitRaw } : {}),
+                    ...(timeoutMs !== undefined ? { timeoutMs } : {}),
+                    ...(minRetrievalCount !== undefined ? { minRetrievalCount } : {}),
+                    ...(requireFeedbackSignal ? { requireFeedbackSignal } : {}),
+                    ...(profileArg !== undefined ? { profile: profileArg } : {}),
+                    ...(Object.keys(syncOverride).length > 0 ? { sync: syncOverride } : {}),
+                    consolidateOptions: {
+                        target: targetArg,
+                        dryRun,
+                        autoAccept,
+                        task: taskArg,
+                        ...(consolidateRecovery !== undefined ? { recoveryMode: consolidateRecovery } : {}),
+                    },
+                });
+            }
+            catch (err) {
+                // akmImprove threw — record the failure before letting runWithJsonErrors
+                // emit the standard JSON error envelope. Without this, exceptions in
+                // the main loop (LLM provider crash, OOM, etc.) leave no improve_runs
+                // row, matching the SIGTERM gap.
+                persistTerminated("exception", err instanceof Error ? err.message : String(err));
+                throw err;
+            }
+            finally {
+                process.removeListener("SIGTERM", sigtermHandler);
+                process.removeListener("SIGINT", sigintHandler);
+                process.removeListener("SIGHUP", sighupHandler);
+                clearLogFile();
+            }
+            const durationMs = Date.now() - startedAtMs;
+            if (jsonToStdout) {
+                // Legacy / escape-hatch mode: full JSON on stdout, no file write.
+                // Kept for scripts/agents that already pipe to jq.
+                output("improve", improveResult);
+                process.exit(0);
+            }
+            // Default mode (0.8.0+): persist the full result as a row in the
+            // `improve_runs` table of state.db (migration 003) and emit NOTHING
+            // on stdout. The verbose JSON would otherwise scroll earlier progress
+            // logs out of the terminal buffer. The existing `[improve] ...`
+            // progress log lines on stderr remain the canonical console UX —
+            // do NOT add any new console output here.
+            //
+            // Pre-0.8.0 wrote `<stash>/.akm/runs/<run-id>/improve-result.json`;
+            // those files are no longer authored. Query recent runs with:
+            //   sqlite3 "$AKM_DATA_DIR/state.db" \
+            //     "SELECT id, started_at, ok, dry_run FROM improve_runs \
+            //      ORDER BY started_at DESC LIMIT 10"
+            // runId + primaryStashDir minted up-top so signal handlers can record
+            // partial runs; reuse them here for the success path.
+            const resultRef = relativeImproveResultPath(runId);
+            runRecorded = true; // Suppress any late signal-handler write — the success path owns the row now.
+            if (primaryStashDir) {
+                try {
+                    writeImproveResultFile(primaryStashDir, runId, improveResult);
+                }
+                catch (err) {
+                    // Stderr warning on the failure path is preferable to crashing
+                    // the run after all the work has completed.
+                    process.stderr.write(`warning: failed to record improve run ${resultRef}: ${err instanceof Error ? err.message : String(err)}\n`);
+                }
+            }
+            else {
+                process.stderr.write(`warning: no writable stash directory resolved; improve result not persisted to state.db (use --json-to-stdout to capture)\n`);
+            }
+            // durationMs reserved for future use (no console emission today).
+            void durationMs;
+            process.exit(0);
+        });
+    },
+});