akm-cli 0.7.4 → 0.8.0-rc.10

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

@@ -0,0 +1,12 @@
+Usage:
+  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 proposal accept proposal_123
+  akm proposal accept proposal_123 --target team-stash

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

@@ -0,0 +1,69 @@
+Usage:
+  akm improve
+  akm improve <type>
+  akm improve <ref>
+
+Description:
+  Analyze existing AKM assets and generate improvement proposals.
+
+Modes:
+  akm improve
+      Improve all eligible assets in the current scope.
+
+  akm improve <type>
+      Improve all assets of a given type.
+      Example: akm improve memory
+
+  akm improve <ref>
+      Improve one specific asset.
+      Example: akm improve workflow:release-checklist
+
+What it does:
+  - reviews feedback and recent history
+  - proposes edits to existing assets
+  - distills lessons where useful
+  - promotes durable skill lessons into skill reference-doc proposals when justified
+  - cleans and consolidates memories
+  - writes results to the proposal queue
+
+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[=<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.
+  --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
+  akm improve memory
+  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

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

@@ -0,0 +1,18 @@
+Usage:
+  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 proposal list
+  akm proposal list --status pending
+  akm proposal list --type skill

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

@@ -0,0 +1,17 @@
+Usage:
+  akm propose <type> <name> --task "..."
+  akm propose <type> <name> --file <path>
+
+Description:
+  Create a proposal for a brand-new AKM asset.
+
+Input:
+  --task <text>        Inline task or prompt text
+  --file <path>        Read task or prompt text from a file
+
+Rules:
+  Exactly one of --task or --file is required.
+
+Examples:
+  akm propose skill release-auditor --task "review release artifacts before publish"
+  akm propose workflow hotfix-triage --file ./prompts/hotfix-triage.md

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

@@ -0,0 +1,11 @@
+Usage:
+  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 proposal reject proposal_123 --reason "duplicates existing workflow"

package/dist/commands/history.js

@@ -1,53 +1,15 @@
-/**
- * `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).
 const PROPOSAL_EVENT_TYPES = new Set(["promoted", "rejected"]);
 // ── Helpers ──────────────────────────────────────────────────────────────────
-function normalizeSince(since) {
-    // Accept "YYYY-MM-DD", "YYYY-MM-DDTHH:MM:SSZ", epoch ms, or anything Date can parse.
-    const trimmed = since.trim();
-    if (!trimmed) {
-        throw new UsageError("--since cannot be empty.", "INVALID_FLAG_VALUE");
-    }
-    // Pure-digit input → epoch milliseconds
-    if (/^\d+$/.test(trimmed)) {
-        const ms = Number.parseInt(trimmed, 10);
-        const d = new Date(ms);
-        if (Number.isNaN(d.getTime())) {
-            throw new UsageError(`Invalid --since value: ${since}`, "INVALID_FLAG_VALUE");
-        }
-        return d
-            .toISOString()
-            .replace("T", " ")
-            .replace(/\.\d+Z$/, "");
-    }
-    const parsed = new Date(trimmed);
-    if (Number.isNaN(parsed.getTime())) {
-        throw new UsageError(`Invalid --since value: ${since}. Expected ISO timestamp (e.g. 2026-04-01T00:00:00Z) or epoch ms.`, "INVALID_FLAG_VALUE");
-    }
-    // Match the "YYYY-MM-DD HH:MM:SS" format SQLite's datetime('now') stores.
-    return parsed
-        .toISOString()
-        .replace("T", " ")
-        .replace(/\.\d+Z$/, "");
-}
 function parseMetadata(raw) {
     if (!raw)
         return null;
@@ -66,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,
     };
@@ -104,7 +67,7 @@ export async function akmHistory(options = {}) {
         parseAssetRef(trimmed);
         normalizedRef = trimmed;
     }
-    const sinceNormalized = options.since !== undefined ? normalizeSince(options.since) : undefined;
+    const sinceNormalized = options.since !== undefined ? isoToSqlite(parseSinceToIso(options.since)) : undefined;
     const db = options.db ?? openExistingDatabase();
     const ownsDb = options.db === undefined;
     try {
@@ -118,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);
@@ -128,7 +95,7 @@ export async function akmHistory(options = {}) {
         const sources = ["usage_events"];
         const proposalEntries = [];
         if (options.includeProposals === true) {
-            sources.push("events.jsonl");
+            sources.push("state.db");
             // Convert sinceNormalized ("YYYY-MM-DD HH:MM:SS") to ISO for readEvents
             // which uses `ts >= since` where `ts` is ISO-8601.
             const sinceIso = sinceNormalized !== undefined ? `${sinceNormalized.replace(" ", "T")}Z` : undefined;
@@ -154,6 +121,7 @@ export async function akmHistory(options = {}) {
                     entryId: null,
                     query: null,
                     signal: null,
+                    source: null,
                     metadata: event.metadata ?? null,
                     createdAt,
                 });
@@ -169,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 } : {}),
@@ -176,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,217 @@
+// 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.",
+        },
+    },
+    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");
+            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 } : {}),
+                    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);
+        });
+    },
+});