akm-cli 0.9.16 → 0.9.17-alpha.10

package/dist/commands/improve/feedback-valence.js

@@ -1,31 +1,6 @@
 // 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/.
-/**
- * Symmetric valence weighting for the improve eligibility sort (#614).
- *
- * BACKGROUND. The improve attention/eligibility ranking historically combined
- * utility with a NEGATIVE-ONLY feedback term: `negative / (positive + negative)`.
- * Under that formula a strong-positive asset contributes a feedback ratio of
- * `0` — i.e. positive feedback never drives attention. Only complaints could
- * lift an asset up the ranking, so a heavily-praised, heavily-used asset that
- * deserves REINFORCEMENT (distill / promote the win) is treated identically to
- * a never-rated one.
- *
- * FIX (gated, default-off). When symmetric valence is enabled we replace the
- * negative-only ratio with a |valence| MAGNITUDE term so that BOTH strong
- * positive and strong negative feedback drive attention. Utility remains the
- * dominant ordering factor — valence is a secondary attention nudge with a
- * small fixed weight, never a utility override.
- *
- * This module is intentionally pure and storage-free: it takes pre-aggregated
- * positive/negative counts plus a utility lookup and returns a deterministic
- * score and lane. All DB access stays in the caller.
- */
-/** Weight on utility in the combined eligibility score. Utility is dominant. */
-export const UTILITY_WEIGHT = 0.7;
-/** Weight on the feedback attention term in the combined eligibility score. */
-export const FEEDBACK_WEIGHT = 0.3;
 /**
  * Compute the symmetric-valence attention score for one asset's feedback.
  *

package/dist/commands/improve/improve-cli.js

@@ -14,6 +14,7 @@ import { getCacheDir } from "../../core/paths.js";
 import { redactSensitiveText } from "../../core/redaction.js";
 import { clearLogFile, setLogFile, warn } from "../../core/warn.js";
 import { resolveWriteTarget } from "../../core/write-source.js";
+import { DEFAULT_LLM_TIMEOUT_MS } from "../../integrations/agent/config.js";
 import { collectEngineCredentialValues } from "../../integrations/agent/engine-resolution.js";
 import { probeLlmReachable } from "../../llm/client.js";
 import { getOutputMode } from "../../output/context.js";
@@ -31,15 +32,9 @@ export function _setAkmImproveForTests(fake) {
     akmImproveForRun = fake ?? akmImprove;
 }
 /**
- * Handle the `--auto-accept` flag retired in 0.9.0, returning the scope the run
- * should actually use.
- *
- * citty is non-strict, so the removed flag is silently absorbed rather than
- * rejected — which is the dangerous case. The SPACE-separated spelling
- * (`--auto-accept 90`) leaves `90` sitting in the positional slot, where it is
- * read as the asset-type scope: the run then matches nothing and exits 0, so a
- * 0.8-era crontab goes dark with no error at all. Warn about the flag, and drop
- * the poisoned positional so the run behaves as an unscoped improve instead.
+ * `--auto-accept` (removed in 0.9): citty absorbs it silently, and
+ * `--auto-accept 90` would leave `90` as the scope — a 0.8-era crontab would
+ * match nothing and exit 0. Warn, and drop that positional.
  */
 function resolveScopeAfterRetiredAutoAccept(scopeArg) {
     const invocation = getParsedInvocation();
@@ -55,41 +50,22 @@ function resolveScopeAfterRetiredAutoAccept(scopeArg) {
     }
     return scopeArg;
 }
-/**
- * `akm improve canary` was removed in 0.9 (moved to
- * `scripts/refresh-canary-set.ts`). Without this check "canary" falls through
- * to the generic scope positional, where resolveImproveScope treats any bare
- * word as a type filter that matches zero entries — so an unmigrated caller
- * silently acquires the improve lock and exits 0 having done nothing, instead
- * of getting an error.
- */
+/** `akm improve canary` (removed in 0.9) would otherwise be a type scope matching nothing, exiting 0. */
 function rejectRetiredCanaryScope(scopeArg) {
     if (scopeArg !== "canary")
         return;
-    throw new UsageError('"akm improve canary" was removed in 0.9. Use `bun scripts/refresh-canary-set.ts [--refresh]` instead.', "INVALID_FLAG_VALUE");
+    throw new UsageError('"akm improve canary" was removed in 0.9; the collapse-detector canary set it managed no longer exists.', "INVALID_FLAG_VALUE");
 }
-/**
- * `--target` was renamed to `--bundle` on `improve` in 0.9 (S8). citty is
- * non-strict, so the retired spelling is silently absorbed rather than
- * rejected — accepted proposals then write into the default bundle instead
- * of the one the caller named, with exit 0 and no error. Reject it
- * explicitly instead.
- */
+/** `--target` (renamed `--bundle` in 0.9) would otherwise be absorbed and write to the default bundle. */
 function rejectRetiredImproveTargetFlag() {
     if (!getParsedInvocation().hasFlag("--target"))
         return;
     throw new UsageError("`akm improve --target` was renamed to `--bundle` in 0.9. Use `--bundle <name>` instead.", "INVALID_FLAG_VALUE");
 }
 /**
- * `--require-engines` (#957): abort before any lock, log, or index side
- * effect when the resolved plan already knows a process the active strategy
- * would enable cannot run. Without this flag improve degrades gracefully —
- * it skips the affected processes and reports them in `skippedProcesses` —
- * which is right for an interactive run but wrong for a scheduled one that
- * would rather fail loudly than burn its budget re-indexing and then skip
- * everything. Names the unresolved credential reference per process (not
- * just the process name) so an operator whose own shell passes config
- * validation can see exactly what the scheduler's environment is missing.
+ * `--require-engines` (#957): fail before any side effect when an enabled
+ * process cannot run, naming what each is missing — a scheduled run would
+ * rather fail loudly than index and then skip everything.
  */
 function assertRequiredEnginesAvailable(plan) {
     if (plan.engineUnavailable.length === 0)
@@ -97,66 +73,81 @@ function assertRequiredEnginesAvailable(plan) {
     const lines = plan.engineUnavailable.map((item) => `  - ${item.process} (${item.configKey}): ${item.reason}`);
     throw new ConfigError(`--require-engines: ${plan.engineUnavailable.length} improve process${plan.engineUnavailable.length === 1 ? "" : "es"} cannot run because ${plan.engineUnavailable.length === 1 ? "its" : "their"} engine is unavailable:\n${lines.join("\n")}`, "LLM_NOT_CONFIGURED");
 }
-/**
- * Every distinct `kind: "llm"` connection the active strategy's plan would
- * actually dispatch against — the main per-process runners plus triage's own
- * judgment engine, which is resolved separately (#957).
- */
+/** Every LLM connection the plan would dispatch to, triage's judgment engine included. */
 function collectRequiredEngineTargets(plan) {
     const targets = [];
     for (const [processName, process] of Object.entries(plan.processes)) {
         if (process.runner) {
-            targets.push({ process: processName, engine: process.runner.engine, connection: process.runner.connection });
+            targets.push({
+                process: processName,
+                engine: process.runner.engine,
+                connection: probeConnection(process.runner),
+            });
         }
     }
     if (plan.triageJudgment?.kind === "llm") {
         targets.push({
             process: "triage.judgment",
             engine: plan.triageJudgment.engine,
-            connection: plan.triageJudgment.connection,
+            connection: probeConnection(plan.triageJudgment),
         });
     }
     return targets;
 }
+/** The resolved engine keeps its request timeout beside the connection (the runtime merges it in); the probe needs it on the connection. */
+function probeConnection(runner) {
+    return runner.timeoutMs !== undefined ? { ...runner.connection, timeoutMs: runner.timeoutMs } : runner.connection;
+}
+/**
+ * The bound on `--require-engines`' probe: the connection's own request
+ * timeout, at most two minutes. A local server busy with another job queues
+ * the probe behind that job, and a fixed 3s bound failed every scheduled
+ * improve run on 2026-09-27 against a reachable endpoint; the cap still ends a
+ * hung endpoint (#957) long before a run's own multi-minute calls would.
+ */
+export function requiredEngineProbeTimeoutMs(connection) {
+    return Math.min(connection.timeoutMs ?? DEFAULT_LLM_TIMEOUT_MS, REQUIRED_ENGINE_PROBE_MAX_MS);
+}
+const REQUIRED_ENGINE_PROBE_MAX_MS = 120_000;
 /**
- * `--require-engines` field re-test (#957): the static check above only
- * proves an engine is configured and credentialed — it cannot see a dead
- * endpoint. A field run against an unreachable engine sat silent for
- * minutes instead of hitting the documented exit-78 path. Exercise the real
- * model completion path with a tiny response and a three-second bound. The
- * `/models` endpoint used by the lightweight health check is deliberately
- * insufficient here: a gateway can list a model while its upstream completion
- * route is dead (#980). Deduplicate by endpoint + model, not endpoint alone,
- * because model backends behind one gateway can fail independently.
+ * `--require-engines`, live: probe each connection's real completion path
+ * (a gateway can list a model whose completion route is dead, #980), once per
+ * endpoint + model, within {@link requiredEngineProbeTimeoutMs}. Returns each
+ * target's latency for the run result (R17); an unreachable one fails the run.
  */
-async function assertRequiredEnginesReachable(plan, probeReachable = (connection) => probeLlmReachable(connection, 3_000)) {
+export async function assertRequiredEnginesReachable(plan, probeReachable = (connection) => probeLlmReachable(connection, requiredEngineProbeTimeoutMs(connection))) {
     const targets = collectRequiredEngineTargets(plan);
     if (targets.length === 0)
-        return;
+        return [];
     const probesByConnection = new Map();
     const probed = await Promise.all(targets.map(async (target) => {
         const key = `${target.connection.endpoint.replace(/\/+$/, "")}|${target.connection.model}`;
         let pending = probesByConnection.get(key);
         if (!pending) {
-            pending = probeReachable(target.connection);
+            const probeStartedAt = Date.now();
+            pending = probeReachable(target.connection).then((reach) => ({
+                reach,
+                latencyMs: Date.now() - probeStartedAt,
+            }));
             probesByConnection.set(key, pending);
         }
-        return { ...target, reach: await pending };
+        const { reach, latencyMs } = await pending;
+        return { ...target, reach, latencyMs };
     }));
     const unreachable = probed.filter((item) => !item.reach.reachable);
-    if (unreachable.length === 0)
-        return;
-    const lines = unreachable.map((item) => `  - ${item.process} (engine "${item.engine}", ${item.connection.endpoint}): ${item.reach.error ?? "did not respond"}`);
-    throw new ConfigError(`--require-engines: ${unreachable.length} improve process${unreachable.length === 1 ? "" : "es"} cannot run because ${unreachable.length === 1 ? "its" : "their"} engine completion path is not reachable:\n${lines.join("\n")}`, "LLM_NOT_CONFIGURED");
+    if (unreachable.length > 0) {
+        const lines = unreachable.map((item) => `  - ${item.process} (engine "${item.engine}", ${item.connection.endpoint}): ${item.reach.error ?? "did not respond"}`);
+        throw new ConfigError(`--require-engines: ${unreachable.length} improve process${unreachable.length === 1 ? "" : "es"} cannot run because ${unreachable.length === 1 ? "its" : "their"} engine completion path is not reachable:\n${lines.join("\n")}`, "LLM_NOT_CONFIGURED", "Check that each listed endpoint is up and serves its model. The probe is one short completion, bounded by the engine's timeoutMs (at most two minutes).");
+    }
+    return probed.map((item) => ({
+        process: item.process,
+        engine: item.engine,
+        endpoint: item.connection.endpoint,
+        reachable: item.reach.reachable,
+        latencyMs: item.latencyMs,
+    }));
 }
-/**
- * `--show-prompt` (#952): render the composed reflect prompt for one asset ref
- * and exit, before any lock, log, index write, or engine dispatch — the field
- * had no cheap way to confirm the #952 prompt fix (unverified-feedback framing,
- * no-truncation-marker instruction) without running a full improve cycle.
- * Reuses `renderReflectPromptPreview` (reflect.ts), which stops before the
- * dispatch lease reflect would otherwise acquire, so this never calls an engine.
- */
+/** `--show-prompt` (#952): print reflect's composed prompt for one ref — no lock, write or dispatch. */
 async function runShowPromptCli(refArg, parsedRef, taskArg, targetArg, resolvedPlan) {
     const readSource = resolveImproveReadSource(resolvedPlan.config, parsedRef, targetArg);
     const preview = await renderReflectPromptPreview({
@@ -180,30 +171,14 @@ async function runShowPromptCli(refArg, parsedRef, taskArg, targetArg, resolvedP
         prompt: preview.prompt,
     });
 }
-/**
- * `akm improve report` (#944): a scope value that dispatches to the per-run
- * LLM usage/routing report instead of a real improve run — "report" is not,
- * and will never be, a real asset type (`DEFAULT_ALLOWED_TYPES` in
- * improve-strategies.ts), so this already matched zero assets before this
- * flag existed, matching the precedent `rejectRetiredCanaryScope` set for
- * intercepting a special scope word ahead of any lock/log/index side effect.
- */
+/** `akm improve report` (#944): the per-run LLM usage/routing report ("report" is no asset type). */
 function runImproveReportCli(args) {
     const runIdArg = getStringArg(args, "run");
     const sinceArg = getStringArg(args, "since");
     const result = runImproveReportQuery({ runId: runIdArg, since: sinceArg });
     output("improve-report", { ok: true, ...result });
 }
-/**
- * `--run`/`--since` only mean anything with the "report" scope, which
- * intercepts before this point in the `run` handler below. citty is
- * non-strict, so passing either with a real scope (or no scope at all) used
- * to be silently ignored — the flag's value was read nowhere else, and the
- * run proceeded as an ordinary improve run with no error, discarding the
- * operator's intent. Reject explicitly instead, matching the precedent
- * `rejectRetiredCanaryScope`/`rejectRetiredImproveTargetFlag` set for other
- * flag misuse on this command.
- */
+/** `--run`/`--since` belong to `improve report`; elsewhere citty would silently ignore them. */
 function rejectReportOnlyFlags(args) {
     const flag = getStringArg(args, "run") !== undefined
         ? "--run"
@@ -219,9 +194,7 @@ export const improveCommand = defineCommand({
         name: "improve",
         description: "Analyze existing AKM assets and generate improvement proposals; also consolidates memories when the selected strategy enables consolidate.",
     },
-    // Raw defineCommand, so the global output flags are declared here explicitly.
-    // Without them citty treats `--format` as a boolean and its space-separated
-    // value falls through to the `scope` positional.
+    // Declared explicitly: otherwise citty takes `--format`'s value as the scope.
     args: {
         ...GLOBAL_OUTPUT_ARGS,
         scope: {
@@ -277,7 +250,7 @@ export const improveCommand = defineCommand({
         },
         strategy: {
             type: "string",
-            description: "Named improve strategy from improve.strategies or built-in strategies (catchup, consolidate, default, graph-refresh, proactive-maintenance, quick, reflect-distill, thorough). Controls which sub-processes run and which asset types are processed.",
+            description: "Named improve strategy from improve.strategies or built-in strategies (catchup, consolidate, default, proactive-maintenance, quick, reflect-distill, thorough). Controls which sub-processes run and which asset types are processed.",
         },
         sync: {
             type: "boolean",
@@ -290,27 +263,16 @@ export const improveCommand = defineCommand({
     },
     async run({ args }) {
         await runWithJsonErrors(async () => {
-            // #944 — dispatch before any lock/log/index side effect, same
-            // interception point as rejectRetiredCanaryScope below.
             if (getStringArg(args, "scope") === "report") {
                 runImproveReportCli(args);
                 return;
             }
             rejectReportOnlyFlags(args);
             rejectRetiredImproveTargetFlag();
-            // D7 — `--format` used to be rejected here outright. It is a global flag on
-            // a command that does emit an envelope through `output()` (always on
-            // `--dry-run`, otherwise with `--json-to-stdout`), so rejecting it made
-            // improve a fourth inconsistent format behaviour rather than a documented
-            // exemption. It now applies to that envelope; progress output stays on
-            // stderr regardless.
             const jsonToStdout = args["json-to-stdout"];
             const targetArg = getStringArg(args, "bundle");
             const taskArg = getStringArg(args, "task");
-            // #947 — `--plan` is a zero-logic discoverability alias for `--dry-run`;
-            // it must never fork the computation, only set the same flag. #952 —
-            // `--show-prompt` implies the same read-only posture (it never reaches
-            // akmImprove at all, but keeps writeTarget/resolvedPlan unset the same way).
+            // `--plan` is an alias for `--dry-run`; `--show-prompt` is read-only too.
             const dryRun = args["dry-run"] || args.plan || args["show-prompt"];
             const limitRaw = parsePositiveIntFlag(args.limit ?? undefined);
             const timeoutMs = parsePositiveIntFlag(args["timeout-ms"], "--timeout-ms");
@@ -326,16 +288,9 @@ export const improveCommand = defineCommand({
                 : scopeRef
                     ? resolveMutationTarget(effectiveConfig, scopeRef, targetArg).target
                     : resolveWriteTarget(effectiveConfig, targetArg);
-            // Resolve every enabled model-backed process before logging, signal
-            // lifecycle setup, or any filesystem/database side effect.
-            // #800/#957 round 3 — `--dry-run`/`--plan` never dispatches, so the
-            // "no improve process can run" guard must not throw when every process
-            // is disabled purely by an unreachable credential; a live run keeps
-            // throwing (allowAllDisabled unset).
+            // Every model-backed process resolves before any side effect; a dry run
+            // never dispatches, so it tolerates every process being disabled.
             const resolvedPlan = resolveImprovePlan(strategyArg, effectiveConfig, { allowAllDisabled: Boolean(dryRun) });
-            // #952 — same interception point as the `report` scope above: before any
-            // lock, log, or index side effect. Requires a single fully-qualified
-            // asset ref (not a type or whole-bundle scope).
             if (args["show-prompt"]) {
                 if (!scopeArg || !scopeRef) {
                     throw new UsageError("`--show-prompt` requires a fully-qualified asset ref as the scope (e.g. `akm improve lessons/my-lesson --show-prompt`).", "INVALID_FLAG_VALUE");
@@ -343,15 +298,14 @@ export const improveCommand = defineCommand({
                 await runShowPromptCli(scopeArg, scopeRef, taskArg, targetArg, resolvedPlan);
                 return;
             }
+            let engineProbe;
             if (args["require-engines"]) {
                 assertRequiredEnginesAvailable(resolvedPlan);
-                await assertRequiredEnginesReachable(resolvedPlan);
+                engineProbe = await assertRequiredEnginesReachable(resolvedPlan);
             }
             const selectedStrategyName = resolvedPlan.strategy.name;
             const sensitiveValues = collectEngineCredentialValues(effectiveConfig);
-            // 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.
+            // Only flags actually passed override the strategy's `sync` block.
             const syncFlag = args.sync;
             const pushFlag = args.push;
             const syncOverride = {};
@@ -365,16 +319,10 @@ export const improveCommand = defineCommand({
             }
             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`.
+            // The run id is minted up front so a killed run still leaves an improve_runs row.
             const runId = buildImproveRunId();
             const primaryStashDir = writeTarget?.source.path;
             const inferredScopeMode = scopeRef ? "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 (dryRun)
@@ -398,14 +346,7 @@ export const improveCommand = defineCommand({
                     process.stderr.write(`warning: failed to persist terminated improve run ${runId}: ${err instanceof Error ? err.message : String(err)}\n`);
                 }
             };
-            // R8: the signal table / handlers / watchdog / persist-before-exit
-            // choreography lives in `runImproveSession`. It registers the
-            // SIGTERM/SIGINT/SIGHUP handlers (each persists the terminated-run row
-            // BEFORE process.exit so a SIGTERM'd run — e.g. cron timeout — always
-            // leaves a row in improve_runs), awaits the work, then removes the
-            // handlers on the way out. `onTerminate` persists synchronously
-            // (recordTerminatedImproveRun -> bun:sqlite writes are sync), and the
-            // 2000ms watchdog inside the session force-exits if that ever hangs.
+            // The session persists the terminated-run row before exiting on a signal.
             let improveResult;
             try {
                 improveResult = await runImproveSession({
@@ -422,12 +363,8 @@ export const improveCommand = defineCommand({
                         ...(requireFeedbackSignal ? { requireFeedbackSignal } : {}),
                         ...(skipIfLocked ? { skipIfLocked } : {}),
                         ...(strategyArg !== undefined ? { strategy: strategyArg } : {}),
+                        ...(engineProbe !== undefined ? { engineProbe } : {}),
                         ...(Object.keys(syncOverride).length > 0 ? { sync: syncOverride } : {}),
-                        consolidateOptions: {
-                            target: targetArg,
-                            dryRun,
-                            task: taskArg,
-                        },
                     }),
                 }, {
                     signalSource: process,
@@ -439,10 +376,6 @@ export const improveCommand = defineCommand({
                 });
             }
             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;
             }
@@ -450,57 +383,30 @@ export const improveCommand = defineCommand({
                 clearLogFile();
             }
             if (dryRun) {
-                // A dry-run never persists its result, so stdout is its only result
-                // channel. F4: was `process.exit(0)`, which terminates synchronously
-                // and skips pending cleanup (e.g. the `finally { clearLogFile(); }`
-                // above already ran, but any citty/runWithJsonErrors-level cleanup
-                // on the way out would not). Exit code is 0 either way — `return`
-                // alone is sufficient since success is the default `process.exitCode`.
+                // A dry run persists nothing: stdout is its only result channel.
                 output("improve", improveResult);
                 return;
             }
-            // 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 — the
-            // usage-report table below (#944) follows that same convention
-            // (stderr, `[improve]`-prefixed), it is not new stdout noise.
-            //
-            // 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.
-            runRecorded = true; // Suppress any late signal-handler write — the success path owns the row now.
+            // A live run's result goes to state.db's improve_runs, not stdout
+            // (progress stays on stderr). The success path owns the row now.
+            runRecorded = true;
             if (primaryStashDir) {
                 try {
                     recordImproveRunResult(primaryStashDir, runId, improveResult, startedAtIso, sensitiveValues);
                 }
                 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 ${runId}: ${err instanceof Error ? err.message : String(err)}\n`);
                 }
             }
             else {
                 process.stderr.write(`warning: no writable bundle directory resolved; improve result not persisted to state.db (use --json-to-stdout to capture)\n`);
             }
-            // #944 — same table `akm improve report` renders, appended to every
-            // real (non-dry-run) run so an operator sees the routing/cost split
-            // without a separate command. Omitted when the run made no LLM calls
-            // and skipped no enabled process (nothing to report).
+            // The `akm improve report` table, on stderr, when there is anything to report (#944).
             if (improveResult.usageReport) {
                 process.stderr.write(`${formatUsageReportTable(improveResult.usageReport)}\n`);
             }
             if (jsonToStdout)
                 output("improve", improveResult);
-            // F4: was `process.exit(0)` — the run has already been fully recorded
-            // above (recordImproveRunResult / the warning path), so nothing here
-            // depends on an immediate synchronous exit. This is the last statement
-            // in the handler, so a plain fall-through is equivalent.
         });
     },
 });

package/dist/commands/improve/improve-result-file.js

@@ -2,72 +2,31 @@
 // 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/.
 /**
- * Helpers for persisting the `akm improve` result envelope.
- *
- * v0.8.0 behavioural default change:
- *   - Default: the full result is recorded as a single row in the
- *     `improve_runs` table of `state.db` (migration 003). Stdout is empty.
- *     The existing `[improve] ...` progress log lines on stderr remain the
- *     canonical console UX.
- *   - `--json-to-stdout` additionally emits the persisted result as JSON.
- *
- * v0.8.0 storage change (this module): the previous on-disk artifact at
- * `<stash>/.akm/runs/<runId>/improve-result.json` is no longer written. The
- * canonical record now lives in `improve_runs` (see
- * `src/core/state-db.ts`). Pre-existing files from older runs are not
- * deleted by this change — they become historical artifacts. Zero current
- * code paths read them, so no consumers needed to update.
- *
- * Run-id format: ISO-8601 timestamp (colons/dots replaced by `-`) plus an
- * 8-char hex random suffix. There is no existing canonical run-id helper for
- * persistent per-command artefacts on disk — the `workflow_runs` table uses
- * `randomUUID()` but is database-scoped, and `consolidate-journal.json` is a
- * single-slot artefact. We mint a fresh timestamped id for each improve run.
+ * Persist an `akm improve` result as one `improve_runs` row in state.db (since
+ * 0.8.0 stdout stays empty unless `--json-to-stdout`). A run that did not
+ * complete still gets a row.
  */
 import crypto from "node:crypto";
 import { decodeImproveResult } from "../../core/improve-result.js";
 import { redactSensitiveValue } from "../../core/redaction.js";
 import { withImmediateTransaction, withStateDb } from "../../core/state-db.js";
 import { recordImproveRun } from "../../storage/repositories/improve-runs-repository.js";
-/**
- * Build a stable run-id for a single improve invocation.
- *
- * Shape: `<iso-8601-utc-with-dashes>-<8 hex chars>`, e.g.
- *   `2026-05-19T17-30-22-123Z-a1b2c3d4`.
- *
- * The hex suffix protects against same-millisecond collisions when multiple
- * runs happen back-to-back in tests or scripts.
- */
+/** `<iso-8601 with dashes>-<8 hex>`, e.g. `2026-05-19T17-30-22-123Z-a1b2c3d4` (the suffix breaks same-ms ties). */
 export function buildImproveRunId(now = new Date()) {
     const iso = now.toISOString().replace(/[:.]/g, "-");
     const rand = crypto.randomBytes(4).toString("hex");
     return `${iso}-${rand}`;
 }
-/**
- * Persist the full improve result into the `improve_runs` table of state.db.
- *
- * The state.db row carries the scope and dry-run flag from `result.scope`
- * and `result.dryRun`, plus the full result JSON for full fidelity. The
- * dry-run column is indexed so productivity audits can filter cleanly
- * (closes the dry-run/real-run artifact-trap recorded in MEMORY.md
- * `feedback_akm_dryrun_artifact_trap`).
- *
- */
+/** Record a finished run (the full result, redacted; dry runs stay filterable). */
 export function recordImproveRunResult(stashDir, runId, result, startedAt, sensitiveValues = []) {
     const decoded = decodeImproveResult(result);
     const persistedResult = redactSensitiveValue(result, sensitiveValues);
     withStateDb((db) => {
         const completedAt = new Date().toISOString();
-        // startedAt is the ISO timestamp captured at process launch (passed from the
-        // CLI entry point). If omitted, fall back to the run-id's embedded timestamp
-        // so started_at != completed_at even on older call sites.
+        // Without a launch timestamp, the one embedded in the run id.
         const resolvedStartedAt = startedAt ??
             runId.slice(0, 24).replace(/^(\d{4}-\d{2}-\d{2}T)(\d{2})-(\d{2})-(\d{2})-(\d{3})Z$/, "$1$2:$3:$4.$5Z");
-        // #948: route through the shared BEGIN IMMEDIATE retry/reclassify helper
-        // instead of a bare write — this INSERT used to rely solely on the
-        // connection's 30s busy_timeout, with no retry and no friendly
-        // reclassification on exhaustion, so a raw "database is locked" from
-        // improve's own ledger write could reach the CLI as exit 70.
+        // BEGIN IMMEDIATE with retry: a bare write surfaced "database is locked" (#948).
         withImmediateTransaction(db, () => {
             recordImproveRun(db, {
                 id: runId,
@@ -86,21 +45,9 @@ export function recordImproveRunResult(stashDir, runId, result, startedAt, sensi
     });
 }
 /**
- * Persist an improve_runs row for a run that did NOT complete normally.
- * 2026-05-26 incident: the cron's `timeout_ms: 1800000` SIGTERM'd an
- * akm-improve invocation at 30:00 with 54 actionable refs in-flight. No
- * `improve_runs` row was written because the writer only fired at successful
- * end-of-run, so the run vanished from `akm health --detail per-run` even
- * though it had consumed 30 min of LLM time and produced 29 ref-level
- * proposals. This helper closes that gap: signal handlers and the CLI
- * try/catch wrapper call it on the abnormal-exit paths so the row exists
- * with `ok: false` and `metadata.terminated.reason` set.
- *
- * The persisted result envelope is minimal — we don't try to reconstruct
- * the in-flight `actions[]` because that state lives inside `akmImprove`
- * and is gone by the time the signal handler runs. The row captures
- * enough to know: a run started, was scoped to X, did NOT complete, and
- * why.
+ * Record a run that did not complete (a signal, e.g. a cron timeout, or an
+ * exception) so it does not vanish from `akm health`: `ok: false` with the
+ * reason. The in-flight actions are gone by then, so the envelope is minimal.
  */
 export function recordTerminatedImproveRun(stashDir, runId, startedAt, reason, ctx) {
     const completedAt = new Date().toISOString();
@@ -123,9 +70,6 @@ export function recordTerminatedImproveRun(stashDir, runId, startedAt, reason, c
         },
     }, ctx.sensitiveValues ?? []);
     withStateDb((db) => {
-        // #948: same rationale as recordImproveRunResult above — this is the
-        // signal-handler/terminated-run write path, which must not itself raise
-        // a raw "database is locked" while trying to record why the run ended.
         withImmediateTransaction(db, () => {
             recordImproveRun(db, {
                 id: runId,