akm-cli 0.9.15-beta.3 → 0.9.15-beta.5

package/CHANGELOG.md

@@ -4,7 +4,7 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
-## [0.9.15-beta.3] - 2026-09-10
+## [0.9.15-beta.5] - 2026-09-10
 
 ### Added
 
@@ -159,6 +159,32 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
   (#951).** These are akm's resolved data/config/cache/state directories, so a
   script can read `akm info --format json | jq -r .dataDir` instead of hardcoding
   a path that differs between a host install and a container.
+- **A real `curate_rerank` implementation: `search.curateRerank`, a cross-
+  encoder rerank pass over `akm curate`'s already-selected candidates (#951).**
+  `curate_rerank` was a dead `llm.features.*` key removed in 0.8.0 with no wire
+  call ever implemented under it. `search.curateRerank.{enabled, endpoint,
+  model, apiKey, timeoutMs, topN}` configures a standalone `/rerank`-style
+  endpoint (`src/llm/rerank-client.ts`, `POST {model, query, documents}` →
+  `{results: [{index, relevance_score}]}`); when enabled, curate sends its top
+  `topN` (default 8) already-ranked candidates and reorders them by the
+  endpoint's scores. Disabled by default, and best-effort like every other
+  bounded LLM feature: a misconfigured endpoint, network failure, timeout, or
+  malformed response falls back to curate's own ranking unchanged rather than
+  failing the command. Deliberately its own config arm rather than a third
+  `engines` kind alongside `"llm"`/`"agent"` — that union's kinds are
+  load-bearing through execution-lowering, runner dispatch, and the harness
+  model map, none of which a reranker touches.
+- **Per-run task log files are purged past the retention window (#951).**
+  `tasks/logs/<taskId>/<timestamp>.log` (the per-run human-readable tail;
+  `logs.db` is the durable, already-purged record) had file separation but no
+  cleanup, so old run files accumulated forever. `akm improve`'s existing
+  retention pass now also deletes `.log` files under `getTaskLogDir()` older
+  than the same `improve.eventRetentionDays` window (default 90d, `0` disables
+  it) it already uses for `task_logs`/events/`improve_runs` — bounded to that
+  one directory, one level of `<taskId>` subdirectories, `.log` files only.
+  Path-agnostic bundled scripts and the `akm show env/<name>`/`akm task list`
+  items from the same review were previously confirmed shipped and are
+  unchanged here.
 - **`akm index --reembed` forces a full re-embed (#955).** Bypasses the
   compatibility check above entirely and purges + regenerates every stored
   embedding, for the rare case where the check's verdict should not be trusted. A
@@ -250,8 +276,9 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
   `embedding.contextLength` is Ollama's `num_ctx` only now — it used to also
   silently set the per-request token budget (`embedding.maxTokens`), so
   setting it for the server's context window changed request batching too.
-  The request budget is `embedding.maxTokens` (default 8000), so a request
-  carries about 16 documents alongside the new per-document cap by default.
+  The request budget is `embedding.maxTokens` (default 6000, see #954
+  below), so a request carries about 11 documents alongside the new
+  per-document cap by default.
 - **`akm index` reports where its embedding credential came from, before the
   first provider request (#953).** A field report suspected a gateway was
   receiving unauthenticated embedding requests despite `embedding.apiKey`
@@ -279,6 +306,19 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
   it differs from the running CLI, pointing at `akm task sync` as the
   remedy. `unknown` when not probed, no task is installed, or the recorded
   binary cannot be executed.
+- **`akm improve <ref> --show-prompt` prints the composed reflect prompt for
+  one asset and exits (#952).** A beta.3 field round confirmed the #952 prompt
+  fix by reading source, but no live `akm improve` completed across three
+  attempts, leaving no cheap way to see the prompt in practice. `--show-prompt`
+  reuses every read-only step `akm improve`'s live reflect step already
+  performs (source resolution, runner selection, feedback/schema-hint/
+  related-lesson/rejected-proposal gathering) and stops before the dispatch
+  lease reflect would otherwise acquire — no lock, index write, or engine call,
+  same as `--dry-run`. Requires a fully-qualified asset ref as the scope; JSON/
+  yaml output carries the prompt as a `prompt` field, text output prints it
+  directly so the #952 framing (feedback shown as an unverified report, and
+  the instruction never to emit the truncation marker or out-of-asset content)
+  can be checked by eye.
 
 ### Changed
 
@@ -463,6 +503,32 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ### Fixed
 
+- **An alias-level `engine` binding in `models.json` is honoured on every
+  platform column (#946).** The per-platform nested form
+  (`"fast": {"opencode": {"engine": "local-fast"}}`) already worked, but the
+  flat shorthand from this issue's own acceptance criteria
+  (`"fast": {"engine": "local-fast"}`) did not: `parseModelMapLayer` treated
+  every key under an alias as a platform-column name, so `engine` was parsed
+  as a fourth platform holding the model string, the three real columns kept
+  their hardcoded cloud defaults, and `akm agent --model fast` silently
+  dispatched to a cloud model instead of the configured local engine. The
+  flat `model`/`inference`/`engine` keys are now a wildcard default merged
+  onto every column, a same-alias per-platform entry still overrides it, and
+  an alias naming an unknown engine fails with a `ConfigError` rather than
+  falling back.
+- **Two `improve` runs colliding on the lock is transient, not a broken
+  config (#948).** The lock-held path threw a `ConfigError`, surfacing as
+  exit 78 (`INVALID_CONFIG_FILE`) and telling a supervisor to stop retrying
+  an ordinary collision. It is now a `TransientError`/`IMPROVE_LOCK_HELD` at
+  exit 75, matching the `MAINTENANCE_BARRIER_BUSY`/`INDEX_DB_CONTENDED`
+  treatment the index rebuild lock already had.
+- **The embedding path no longer leaks a raw `database is locked` (#956).**
+  `reclassifyIndexDbContention` moved out of `indexer.ts` into a shared
+  module and `materialize-embeddings.ts`'s embedding-generation catch now
+  routes through it, so contention produces the same "index database is
+  busy" wording as every other path instead of the raw driver string.
+  Control flow is unchanged: this was always non-fatal.
+
 - **Starting a workflow ref that already has an active run in a different scope
   now warns instead of silently duplicating it (#942).** `akm workflow run
   <ref>`'s per-scope concurrency guard is unchanged by design — two unrelated
@@ -610,6 +676,18 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
   precedent (#948) for state.db; the original driver text survives as
   `cause`. `--skip-if-locked` is unaffected — it already skips gracefully
   before ever attempting the write.
+- **A concurrent plain `akm index` (no `--skip-if-locked`) could still exit
+  78 instead of 75, a 2026-09-10 field re-test found (#956).** Two `akm
+  index` runs colliding on the short internal barrier that registers the
+  opt-in rebuild lock (shared with every other akm lock/lease) threw
+  `ConfigError("INVALID_CONFIG_FILE")` — a config-error exit that tells a
+  supervisor to stop retrying, when this is ordinary contention between two
+  legitimate runs. The barrier is meant to be held only milliseconds, so it
+  now retries briefly (a bounded, jittered backoff) before giving up, letting
+  an ordinary collision succeed instead of erroring at all; if it is still
+  busy after that, it raises `TransientError` with a dedicated
+  `MAINTENANCE_BARRIER_BUSY` code (exit 75) instead of the config error. The
+  rebuild lock itself is unaffected and still never blocks (#872).
 - **The fingerprint-rename canary embeds the exact text the stored vector was
   generated from (#955).** `sampleEmbeddedEntriesForCanary` handed the canary
   the entry's raw `search_text`, while the main embedding pass caps it to
@@ -621,6 +699,34 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
   purge and rebuild on a same-model rename. The canary now caps each sampled
   entry's search text the same way, through the same `capEmbeddingText`
   helper, before requesting its vector.
+- **`akm improve --require-engines` now probes reachability instead of only
+  checking config/credentials, and a dead engine can no longer hang a run
+  past its timeout or a signal (#957).** Field, beta.3: engines pointed at a
+  dead endpoint, then `akm improve --require-engines` ran ~4 minutes with
+  zero output, ignoring an external `timeout 30` (SIGTERM) and akm's own
+  `--timeout-ms` — the documented exit-78 "required engines unavailable"
+  path could never be observed, because `--require-engines` only checked
+  that an engine was configured and credentialed, never whether it actually
+  answered. It now also runs the same bounded reachability probe `akm
+  health`'s `default-llm-engine`/`configured-engines` checks already use
+  (one `/models` request per distinct endpoint), before any lock, log, or
+  index side effect, and aborts at exit 78 naming the unreachable engine and
+  endpoint. Separately, a live run now prints one default-level line if it
+  has waited more than a few seconds on its first engine response, so a
+  scheduled run's log is never silently empty while an engine is slow or
+  dead — `--timeout-ms` and an engine's own configured timeout already
+  aborted the in-flight request correctly (confirmed by this investigation,
+  not changed), and SIGTERM/SIGINT already ended the process within its
+  documented grace period.
+- **`akm improve --show-prompt` now includes `avoidPatterns` when a live
+  improve loop has set them (#952).** The preview built its own second copy
+  of reflect's prompt-source gathering and `ReflectPromptInput` assembly,
+  which had already drifted from the real dispatch path: it never read
+  `avoidPatterns` (recent-error context from earlier assets in the same
+  run), so the preview was not always the prompt a live iteration would
+  actually send. Both the preview and the real dispatch path (`akmReflect`,
+  `runReflectRefineIterations`) now gather sources and assemble the prompt
+  input through the same two shared helpers, so this cannot drift again.
 
 ## [0.9.14] - 2026-09-04
 

package/dist/commands/health/checks.js

@@ -12,6 +12,7 @@ import { withEngineFallback } from "../../integrations/agent/engine-fallback.js"
 import { isLlmCredentialAvailable, resolveEngine, } from "../../integrations/agent/engine-resolution.js";
 import { executionEngineDefinitionsFromConfig } from "../../integrations/agent/execution-definitions.js";
 import { loadModelMap, mergeModelMapLayers, parseModelMapLayer, readInstalledModelMapText, resolveModelMapAlias, userModelMapPath, } from "../../integrations/agent/model-map.js";
+import { probeEndpointOnce } from "../../llm/client.js";
 import { listKeys } from "../env/env.js";
 import { resolveImprovePlan } from "../improve/improve-strategies.js";
 import { ENGINE_LAST_USED_LOOKBACK_DAYS } from "./engine-usage.js";
@@ -20,13 +21,7 @@ import { ACTIVE_RUN_WARN_MS, TASK_FAIL_RATE_WARN, } from "./types.js";
 function probeConnectionReachable(connection, deps, cache) {
     if (!deps.probeReachable)
         return Promise.resolve(undefined);
-    const key = connection.endpoint.replace(/\/+$/, "");
-    let pending = cache.get(key);
-    if (!pending) {
-        pending = deps.probeReachable(connection);
-        cache.set(key, pending);
-    }
-    return pending;
+    return probeEndpointOnce(connection, cache, deps.probeReachable);
 }
 function reachabilityEvidence(reach) {
     return reach

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

@@ -15,12 +15,16 @@ import { redactSensitiveText } from "../../core/redaction.js";
 import { clearLogFile, setLogFile, warn } from "../../core/warn.js";
 import { resolveWriteTarget } from "../../core/write-source.js";
 import { collectEngineCredentialValues } from "../../integrations/agent/engine-resolution.js";
-import { akmImprove } from "./improve.js";
+import { probeEndpointOnce, probeLlmEndpoint } from "../../llm/client.js";
+import { getOutputMode } from "../../output/context.js";
+import { deliverRendered } from "../../output/html-render.js";
+import { akmImprove, resolveImproveReadSource } from "./improve.js";
 import { runImproveReportQuery } from "./improve-report.js";
 import { buildImproveRunId, recordImproveRunResult, recordTerminatedImproveRun, } from "./improve-result-file.js";
 import { runImproveSession } from "./improve-session.js";
-import { resolveImprovePlan } from "./improve-strategies.js";
+import { resolveImprovePlan, } from "./improve-strategies.js";
 import { formatUsageReportTable } from "./improve-usage-report.js";
+import { renderReflectPromptPreview } from "./reflect.js";
 let akmImproveForRun = akmImprove;
 /** Swap the CLI's improve work implementation in deterministic subprocess tests. */
 export function _setAkmImproveForTests(fake) {
@@ -93,6 +97,84 @@ 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).
+ */
+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 });
+        }
+    }
+    if (plan.triageJudgment?.kind === "llm") {
+        targets.push({
+            process: "triage.judgment",
+            engine: plan.triageJudgment.engine,
+            connection: plan.triageJudgment.connection,
+        });
+    }
+    return targets;
+}
+/**
+ * `--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. Reuse the SAME
+ * bounded reachability probe `akm health`'s `default-llm-engine` /
+ * `configured-engines` checks already run (`probeLlmEndpoint`, a single
+ * `/models` GET bounded by its own default timeout) once per distinct
+ * endpoint (via the shared `probeEndpointOnce` memoization health/checks.ts
+ * also uses), so a dead engine is caught here instead of during dispatch.
+ */
+async function assertRequiredEnginesReachable(plan, probeReachable = probeLlmEndpoint) {
+    const targets = collectRequiredEngineTargets(plan);
+    if (targets.length === 0)
+        return;
+    const probesByEndpoint = new Map();
+    const probed = await Promise.all(targets.map(async (target) => ({
+        ...target,
+        reach: await probeEndpointOnce(target.connection, probesByEndpoint, probeReachable),
+    })));
+    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 endpoint is not reachable:\n${lines.join("\n")}`, "LLM_NOT_CONFIGURED");
+}
+/**
+ * `--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.
+ */
+async function runShowPromptCli(refArg, parsedRef, taskArg, targetArg, resolvedPlan) {
+    const readSource = resolveImproveReadSource(resolvedPlan.config, parsedRef, targetArg);
+    const preview = await renderReflectPromptPreview({
+        ref: refArg,
+        ...(taskArg ? { task: taskArg } : {}),
+        improveProfile: resolvedPlan.strategy.config,
+        config: resolvedPlan.config,
+        stashDir: readSource.source.path,
+    });
+    const outputMode = getOutputMode();
+    if (outputMode.format === "text") {
+        deliverRendered(preview.prompt, outputMode.outputPath);
+        return;
+    }
+    output("improve", {
+        schemaVersion: 2,
+        ok: true,
+        ref: preview.ref,
+        engine: preview.engine,
+        engineKind: preview.engineKind,
+        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,
@@ -172,7 +254,12 @@ export const improveCommand = defineCommand({
         },
         "require-engines": {
             type: "boolean",
-            description: "Abort before any indexing, lock, or log side effect (exit 78) if the active strategy would enable a process whose engine or credential cannot be resolved in this process's environment. Without this flag, improve degrades gracefully instead: it skips the affected processes and reports them in the result's skippedProcesses. Recommended alongside --skip-if-locked for scheduled runs.",
+            description: "Abort before any indexing, lock, or log side effect (exit 78) if the active strategy would enable a process whose engine or credential cannot be resolved in this process's environment, OR whose endpoint fails a bounded reachability probe (the same probe akm health runs). Without this flag, improve degrades gracefully instead: it skips the affected processes and reports them in the result's skippedProcesses. Recommended alongside --skip-if-locked for scheduled runs.",
+            default: false,
+        },
+        "show-prompt": {
+            type: "boolean",
+            description: "Print the composed reflect prompt for one asset ref and exit — no lock, index write, or engine dispatch (#952). Requires a fully-qualified asset ref as the scope positional (e.g. `akm improve lessons/my-lesson --show-prompt`). JSON/yaml format carries the prompt as a `prompt` field; text format prints it directly.",
             default: false,
         },
         run: {
@@ -216,8 +303,10 @@ export const improveCommand = defineCommand({
             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.
-            const dryRun = args["dry-run"] || args.plan;
+            // 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).
+            const dryRun = args["dry-run"] || args.plan || args["show-prompt"];
             const limitRaw = parsePositiveIntFlag(args.limit ?? undefined);
             const timeoutMs = parsePositiveIntFlag(args["timeout-ms"], "--timeout-ms");
             const requireFeedbackSignal = args["require-feedback-signal"];
@@ -239,8 +328,20 @@ export const improveCommand = defineCommand({
             // is disabled purely by an unreachable credential; a live run keeps
             // throwing (allowAllDisabled unset).
             const resolvedPlan = resolveImprovePlan(strategyArg, effectiveConfig, { allowAllDisabled: Boolean(dryRun) });
-            if (args["require-engines"])
+            // #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");
+                }
+                await runShowPromptCli(scopeArg, scopeRef, taskArg, targetArg, resolvedPlan);
+                return;
+            }
+            if (args["require-engines"]) {
                 assertRequiredEnginesAvailable(resolvedPlan);
+                await assertRequiredEnginesReachable(resolvedPlan);
+            }
             const selectedStrategyName = resolvedPlan.strategy.name;
             const sensitiveValues = collectEngineCredentialValues(effectiveConfig);
             // Only set the keys the user actually passed (citty leaves the flag

package/dist/commands/improve/improve.js

@@ -65,6 +65,19 @@ export function renderSyncCommitMessage(template, result, nowMs) {
     };
     return template.replace(/\{(\w+)\}/g, (match, key) => tokens[key] ?? match);
 }
+/**
+ * How long the improve loop waits for its FIRST engine response (success or
+ * error — any terminal record proves the run is not silent) before printing
+ * one default-level line. The timer is armed once the triage/index prepass
+ * finishes and the loop is about to start dispatching engine requests — not
+ * at run start — so it measures engine latency, not prepass time. Field
+ * re-test (#957): an engine pointed at a dead endpoint produced zero output
+ * for minutes, so a genuine hang looked identical to a normal-but-slow run.
+ * A few seconds is short enough that an operator watching a scheduled run's
+ * live log sees something promptly, long enough that an ordinary fast
+ * response never prints it.
+ */
+export const FIRST_ENGINE_RESPONSE_HEARTBEAT_MS = 5_000;
 export function armBudgetWatchdog(budgetMs, controller, deps) {
     const setTimeoutFn = deps?.setTimeoutFn ?? setTimeout;
     const clearTimeoutFn = deps?.clearTimeoutFn ?? clearTimeout;
@@ -119,6 +132,12 @@ export async function akmImprove(options = {}) {
     options = setup.options;
     const { budgetMs, budgetAbortController, scope, selectedStrategy, syncRepoDir, resolvedStateDbPath, resolvedLockPath, } = setup;
     let clearBudgetTimer = () => { };
+    let clearFirstResponseHeartbeat = () => { };
+    // #957: set by the usage sink's onRecord callback the moment any engine
+    // call terminates (success or error), including one issued by the prepass
+    // itself — makes arming the heartbeat below a no-op when the run is
+    // already known not to be silent.
+    let firstEngineResponseSeen = false;
     let initialGitPaths = new Set();
     const runJournal = createRunWriteJournal();
     const preEnsureCleanupWarnings = [];
@@ -175,7 +194,10 @@ export async function akmImprove(options = {}) {
                 return buildLockSkippedResult(selectedStrategy.name, scope, options.runId);
             }
             improveLockOwnership = acquisition.ownership;
-            disposeLlmUsageSink = installLlmUsagePersistence(() => eventsCtx);
+            disposeLlmUsageSink = installLlmUsagePersistence(() => eventsCtx, () => {
+                firstEngineResponseSeen = true;
+                clearFirstResponseHeartbeat();
+            });
             exitBackstop = releaseRunLock;
             process.on("exit", exitBackstop);
             initialGitPaths =
@@ -215,6 +237,7 @@ export async function akmImprove(options = {}) {
         // If the live prepass fails, emit its summary and clear the owning sink
         // before any run teardown. The disposer is idempotent with the main finalizer.
         disposeLlmUsageSink();
+        clearFirstResponseHeartbeat();
         clearBudgetTimer();
         if (exitBackstop) {
             process.removeListener("exit", exitBackstop);
@@ -233,6 +256,20 @@ export async function akmImprove(options = {}) {
         // are all in hand. See buildImproveRunContext for exactly which
         // already-resolved values back each field.
         const ctx = buildImproveRunContext(setup, eventsCtx);
+        // #957: arm the heartbeat here, immediately before the improve loop
+        // starts dispatching engine requests — not at run start, where its timer
+        // would measure the triage/index prepass instead of engine latency. A
+        // no-op when the prepass already produced a terminal LLM record (the
+        // onRecord callback above already saw it). Cleared the moment any call
+        // terminates (success or error) — never rearmed, so this prints at most
+        // once per run.
+        if (!firstEngineResponseSeen) {
+            const firstResponseTimer = setTimeout(() => {
+                warn("[improve] Still waiting for the first engine response...");
+            }, FIRST_ENGINE_RESPONSE_HEARTBEAT_MS);
+            firstResponseTimer.unref?.();
+            clearFirstResponseHeartbeat = () => clearTimeout(firstResponseTimer);
+        }
         const seq = await runImproveStageSequence({
             run: setup,
             strategyFilteredRefs,
@@ -292,6 +329,8 @@ export async function akmImprove(options = {}) {
         // #576: clear the per-run LLM usage sink BEFORE closing `eventsDb` below, so
         // no late sink invocation can write through a closed handle.
         disposeLlmUsageSink();
+        // #957: never leave the first-response heartbeat timer pending past the run.
+        clearFirstResponseHeartbeat();
         // O-1 (#364): Clear the budget abort timer so it does not keep the event
         // loop alive after the run completes.
         clearBudgetTimer();
@@ -345,8 +384,13 @@ function describeRunWrittenPaths(setup, writtenPaths) {
     }
     return [...described].sort();
 }
-/** Resolve a dry-run inspection source without adapting it into a write target. */
-function resolveImproveReadSource(config, scopedRef, explicitTarget, fallbackStashDir) {
+/**
+ * Resolve a dry-run inspection source without adapting it into a write target.
+ * Exported so `improve-cli.ts`'s `--show-prompt` (#952) can resolve the same
+ * read-only bundle a plain `--dry-run` would, without duplicating this
+ * selector/target/fallback precedence.
+ */
+export function resolveImproveReadSource(config, scopedRef, explicitTarget, fallbackStashDir) {
     if (scopedRef?.origin && explicitTarget && scopedRef.origin !== explicitTarget) {
         throw new UsageError(`Qualified ref bundle "${scopedRef.origin}" conflicts with --target "${explicitTarget}".`, "INVALID_FLAG_VALUE", `Drop --target or use --target ${scopedRef.origin}.`);
     }

package/dist/commands/improve/locks.js

@@ -2,7 +2,7 @@
 // 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 { ConfigError } from "../../core/errors.js";
+import { TransientError } from "../../core/errors.js";
 import { appendEvent } from "../../core/events.js";
 import { releaseLock } from "../../core/file-lock.js";
 import { tryWithMaintenanceStartBarrier, withMaintenanceStartBarrier } from "../../core/maintenance-barrier.js";
@@ -65,7 +65,14 @@ function tryAcquireImproveLockUnlocked(lockPath, skipIfLocked, onRecovered) {
         warn(`[improve] another improve run holds the lock (PID ${pid}, started ${startedAt}); skipping (--skip-if-locked)`);
         return { state: "skipped" };
     }
-    throw new ConfigError(`akm improve is already running (PID ${pid}, started ${startedAt}). Delete ${lockPath} to force.`, "INVALID_CONFIG_FILE");
+    // #948 field follow-up: two legitimate `improve` invocations colliding on
+    // this lock is ordinary, retryable contention — not a broken config file.
+    // A `ConfigError` here surfaced as exit 78 (INVALID_CONFIG_FILE) and told
+    // a supervisor to stop retrying a normal lock collision. Reclassified to
+    // `TransientError`/`IMPROVE_LOCK_HELD` (exit 75), mirroring the
+    // `MAINTENANCE_BARRIER_BUSY`/`INDEX_DB_CONTENDED` treatment #956 already
+    // applied to the index rebuild lock and the maintenance-start barrier.
+    throw new TransientError(`akm improve is already running (PID ${pid}, started ${startedAt}). Delete ${lockPath} to force.`, "IMPROVE_LOCK_HELD");
 }
 export function releaseImproveLock(ownership) {
     releaseLock(ownership);

package/dist/commands/improve/loop-stages.js

@@ -9,7 +9,7 @@ import { DEFAULT_GRAPH_EXTRACTION_BATCH_SIZE, loadConfig } from "../../core/conf
 import { UsageError } from "../../core/errors.js";
 import { appendEvent } from "../../core/events.js";
 import { openLogsDatabase, purgeOldTaskLogs } from "../../core/logs-db.js";
-import { getDbPath } from "../../core/paths.js";
+import { getDbPath, getTaskLogDir } from "../../core/paths.js";
 import { withStateDb } from "../../core/state-db.js";
 import { info } from "../../core/warn.js";
 import { DEFAULT_GRAPH_EXTRACTION_INCLUDE_TYPES, runGraphExtractionPass, } from "../../indexer/graph/graph-extraction.js";
@@ -25,6 +25,7 @@ import { closeDatabase, openIndexDatabase } from "../../storage/repositories/ind
 import { getEntryByRef } from "../../storage/repositories/index-entries-repository.js";
 import { clearAssetOutcomeMissing, countAssetOutcomeMissing, deleteAssetOutcomeMissingBefore, listAssetOutcomeMissingState, stampAssetOutcomeMissing, } from "../../storage/repositories/outcome-repository.js";
 import { clearAssetSalienceMissing, countAssetSalienceMissing, deleteAssetSalienceMissingBefore, listAssetSalienceMissingState, stampAssetSalienceMissing, } from "../../storage/repositories/salience-repository.js";
+import { purgeOldTaskLogFiles } from "../../tasks/run/task-log.js";
 import { expireStaleProposals, listProposals, purgeOrphanProposals } from "../proposal/repository.js";
 import { checkDeadUrls } from "../url-checker.js";
 import { DEFAULT_RETENTION_DAYS as CYCLE_METRICS_RETENTION_DAYS, runCollapseDetector } from "./collapse-detector.js";
@@ -1124,6 +1125,25 @@ export function runRetentionPurgePass(ctx) {
                 }
             }
         }
+        // Per-run flat log files under getTaskLogDir() (#951): logs.db above is
+        // the durable record and already retention-purged, so the transitional
+        // `<taskId>/<timestamp>.log` tail files can be deleted on the same
+        // window without losing anything. A separate try/catch — a filesystem
+        // problem here must not block the DB purges above.
+        try {
+            const taskLogFilesPurged = purgeOldTaskLogFiles(undefined, retentionDays);
+            if (taskLogFilesPurged > 0) {
+                info(`[improve] task log files purge: ${taskLogFilesPurged} file(s) older than ${retentionDays}d removed from ${getTaskLogDir()}`);
+            }
+            appendEvent({
+                eventType: "task_log_files_purged",
+                ref: "task_log_files/_purge",
+                metadata: { purgedCount: taskLogFilesPurged, retentionDays },
+            }, eventsCtx);
+        }
+        catch (err) {
+            warnings.push(`task log files purge failed: ${errMessage(err)}`);
+        }
     }
     return { warnings };
 }