akm-cli 0.9.15-beta.2 → 0.9.15-beta.4

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.2] - 2026-09-09
+## [0.9.15-beta.4] - 2026-09-10
 
 ### Added
 
@@ -250,8 +250,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`
@@ -268,6 +269,30 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
   apiKey`, or `none configured` — never the credential's value, so a field
   run can compare it directly against what the gateway actually logged.
   `--verbose` also names the config file the run loaded.
+- **`akm health` gains a `scheduler-binary` advisory for scheduler binary
+  drift (#953).** A field report found `akm task sync`'s recorded absolute
+  akm path can go stale after upgrading through a different installer (npm
+  global to a standalone download, or vice versa), leaving a scheduled run
+  invoking the old binary indefinitely with nothing surfacing it. The new
+  `--probe`-gated advisory reads the scheduler's recorded akm invocation —
+  the same binding `task sync`/`task doctor` already read, no crontab text
+  parsing — runs it with `--version`, and `warn`s naming both versions when
+  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
 
@@ -322,6 +347,17 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
   single document that still fails this way is skipped, as
   `context-window-exceeded`; every other failure (network error, 5xx, malformed
   response) keeps the prior skip-the-whole-batch behavior.
+- **The default per-request token budget is lower, and adapts mid-run after a
+  context-size rejection (#954, field report on beta.1).**
+  `embedding.maxTokens`'s default dropped from 8000 to 6000: the 4-chars-per-
+  token estimator undercounts dense technical text by 7-55%, so 8000 regularly
+  overshot a real 8192-token endpoint. On an `akm index` run's first
+  context-size rejection, the effective request budget additionally shrinks to
+  three quarters of its current value (floored at twice
+  `embedding.maxInputTokens`) for every request not yet sent, and one
+  default-level line reports the new value; it never shrinks a second time in
+  the same run. Users who set `embedding.maxTokens` explicitly keep it as the
+  starting point but still benefit from this same-run recovery.
 - **Embedding requests are dispatched through a small in-flight window instead of
   strictly sequentially (#954).** The window defaults to 1 request at a time for
   a loopback endpoint and 2 for a remote one; the actual throughput knob is
@@ -432,6 +468,12 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
   Source-cache hydration (which runs before `index.db` is even opened) now
   reports its own progress the same way: `Hydrating source i/n: <name>` per
   source, plus a 15s heartbeat while a sync is in flight.
+- **`embedding.chunkSize` is retired (#954).** Nothing under `src/` ever read
+  it; it was declared in the config schema but had no effect. It is removed
+  from `EmbeddingConnectionConfigSchema` and `schemas/akm-config.json`. The
+  `embedding` object stays `.passthrough()`, so a config that still sets
+  `embedding.chunkSize` keeps loading exactly as before — the key is simply
+  ignored, not rejected or warned about.
 
 ### Fixed
 
@@ -533,6 +575,14 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
   physical batch size", which the existing context-size pattern
   (`exceed_context_size_error`, "context size", …) did not match, so the
   whole batch was dropped instead of being split and retried like a 413.
+- **The end-of-run throughput line now sums the capped text actually sent to
+  the embedding provider (#954).** `storedTokens` accumulated
+  `estimateTokenCount(entry.searchText)` — the entry's pre-cap search text —
+  while the request `embedBatch` received held the text `capEmbeddingText`
+  had already truncated to `embedding.maxInputTokens`, so the reported
+  `tokens/s` figure overstated throughput for every entry over the cap. The
+  final line now sums the estimate of the capped text the batching loop
+  already built, matching what the provider was actually asked to embed.
 - **A `kill <launcher-pid>` no longer orphans the running `akm` process
   (#956).** The published launcher (`scripts/node-runtime/akm`/
   `akm-migrate`) now forwards SIGTERM/SIGINT/SIGHUP to its bun/node child
@@ -562,6 +612,69 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
   instead of reusing them. A plain `akm index` resume after an interruption
   now embeds only the entries still missing a vector, with no purge and no
   canary.
+- **A concurrent `akm index` without `--skip-if-locked` now fails with a
+  retryable-shortly exit code instead of a raw driver error (#956).**
+  Contention with another writer touching index.db (a second `akm index`, a
+  source add/update's embedding pass, the per-command background reindex)
+  used to exhaust the SQLite driver's retry window and surface as
+  `{"ok":false,"error":"database is locked"}` at exit 70
+  (internal/unclassified). It is now reclassified into a `TransientError`
+  with a dedicated `INDEX_DB_CONTENDED` code (exit 75), naming the rebuild
+  lock's live holder pid when known, mirroring `STATE_DB_CONTENDED`'s
+  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
+  `embedding.maxInputTokens` before ever calling the provider — so for any
+  entry whose search text exceeded the cap, the canary's freshly re-embedded
+  vector came from a different input than the one that produced the stored
+  vector, and the median cosine similarity could fall below the compatibility
+  threshold for reasons unrelated to the model, triggering a needless full
+  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/cli.js

@@ -295,8 +295,8 @@ const healthCommand = defineCommand({
         probe: {
             type: "boolean",
             default: true,
-            description: "Probe default-llm-engine / configured-engines reachability and check for a newer akm release (on by default).",
-            negativeDescription: "Skip the reachability probes and the update check (for an offline or air-gapped host).",
+            description: "Probe default-llm-engine / configured-engines reachability, check for a newer akm release, and check the scheduler's recorded akm binary version (on by default).",
+            negativeDescription: "Skip the reachability probes, the update check, and the scheduler-binary version check (for an offline or air-gapped host).",
         },
     },
     async run({ args }) {
@@ -556,7 +556,7 @@ export const main = defineCommand({
             "  2   usage error\n" +
             "  4   health warn (akm health only)\n" +
             "  70  internal / unclassified error\n" +
-            "  75  transient (retry shortly — another akm process holds a lock or is writing state.db)\n" +
+            "  75  transient (retry shortly — another akm process holds a lock or is writing state.db or index.db)\n" +
             "  78  config error",
     },
     args: {

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
@@ -1164,11 +1159,20 @@ export const HEALTH_CHECKS = [
         run: (ctx) => ctx.versionDrift,
     },
     {
-        // #950: registered last — order is load-bearing (see the HEALTH_CHECKS
-        // doc comment above). Advisory channel, `kind: "deterministic"` — same
+        // #950: advisory channel, `kind: "deterministic"` — same
         // exit-code-gating rationale as thinking-control above.
         name: "engine-last-used",
         channel: "advisory",
         run: (ctx) => projectEngineLastUsedCheck(ctx.activeImproveStrategyEngines, ctx.engineLastUsed, ctx.improveRunsInLookbackWindow, ENGINE_LAST_USED_LOOKBACK_DAYS),
     },
+    {
+        // #953: registered last — order is load-bearing (see the HEALTH_CHECKS
+        // doc comment above). Best-effort scheduler-binary-drift advisory, gated
+        // behind the same --probe/--no-probe flag as engine reachability and
+        // cli-version. Computed once in health.ts (process-spawn IO), projected
+        // here like versionDrift/engineProbes.
+        name: "scheduler-binary",
+        channel: "advisory",
+        run: (ctx) => ctx.schedulerBinaryDrift,
+    },
 ];

package/dist/commands/health/scheduler-binary.js

@@ -0,0 +1,120 @@
+// 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/.
+/**
+ * `scheduler-binary` advisory for `akm health` (#953).
+ *
+ * `akm task sync` records an absolute akm invocation path in the OS
+ * scheduler (`src/tasks/resolve-akm-bin.ts`) because cron/launchd/schtasks
+ * all run jobs with a minimal PATH. A field report showed that path going
+ * stale after upgrading akm through a different installer than the one
+ * active at the last `task sync` (e.g. npm-global to a standalone binary):
+ * the schedule kept invoking a version behind, with nothing in `akm health`
+ * surfacing it, until an unrelated failure (a rejected `secret://` engine
+ * key on the stale binary) surfaced the drift.
+ *
+ * Modelled 1:1 on `version-drift.ts`'s shape: an injectable seam,
+ * best-effort, `--probe`-gated so an air-gapped host's `--no-probe` habit
+ * suppresses this too, and `unknown` on any uncertainty rather than a false
+ * `pass`/`warn`. Reads the scheduler's recorded binding via
+ * `SchedulerBackend.list()` — the same reader `akm task doctor` uses — never
+ * a second crontab/launchd/schtasks text parser.
+ */
+import { spawnSync } from "node:child_process";
+import { selectBackend } from "../../tasks/backends/index.js";
+import { pkgVersion } from "../../version.js";
+/**
+ * Bound on the scheduler-recorded binary's `--version` probe. Matches the
+ * `--version` timeout the engine-reachability checks already use
+ * (checks.ts's `runConfiguredEngineProbe`), so a wedged or missing binary
+ * degrades this advisory to `unknown` in seconds rather than blocking
+ * `akm health --probe`.
+ */
+const SCHEDULER_BINARY_VERSION_PROBE_TIMEOUT_MS = 5_000;
+/**
+ * Build the `scheduler-binary` advisory. `probe` mirrors the
+ * engine-reachability and `cli-version` checks' `--probe`/`--no-probe`
+ * gating: only inspects the scheduler and spawns a process when `true`;
+ * otherwise `unknown` with "not probed", never touching the OS scheduler.
+ */
+export async function collectSchedulerBinaryAdvisory(probe, deps = {}) {
+    const cliVersion = deps.cliVersion ?? pkgVersion;
+    if (!probe) {
+        return {
+            name: "scheduler-binary",
+            kind: "deterministic",
+            status: "unknown",
+            confidence: "high",
+            message: "Scheduler binary version drift was not probed.",
+        };
+    }
+    let installed;
+    try {
+        installed = await (deps.backend ?? selectBackend()).list();
+    }
+    catch (error) {
+        return {
+            name: "scheduler-binary",
+            kind: "deterministic",
+            status: "unknown",
+            confidence: "high",
+            message: `Installed scheduled tasks could not be inspected: ${error instanceof Error ? error.message : String(error)}`,
+        };
+    }
+    // task sync rewrites every installed binding to the same current
+    // invocation atomically, so the first entry's binding represents the
+    // whole schedule under normal operation.
+    const [firstInstalled] = installed;
+    const [binaryPath, ...leadingArgs] = firstInstalled?.binding ?? [];
+    if (!firstInstalled || !binaryPath) {
+        return {
+            name: "scheduler-binary",
+            kind: "deterministic",
+            status: "unknown",
+            confidence: "high",
+            message: "No scheduled task is installed.",
+        };
+    }
+    const binding = firstInstalled.binding;
+    const run = deps.spawnSync ?? spawnSync;
+    let scheduledVersion;
+    try {
+        const result = run(binaryPath, [...leadingArgs, "--version"], {
+            encoding: "utf8",
+            timeout: SCHEDULER_BINARY_VERSION_PROBE_TIMEOUT_MS,
+        });
+        if ((result.status ?? 1) === 0)
+            scheduledVersion = result.stdout?.trim() || undefined;
+    }
+    catch {
+        scheduledVersion = undefined;
+    }
+    if (!scheduledVersion) {
+        return {
+            name: "scheduler-binary",
+            kind: "deterministic",
+            status: "unknown",
+            confidence: "high",
+            message: "The scheduler's recorded akm binary could not be executed.",
+            evidence: { binding },
+        };
+    }
+    if (scheduledVersion === cliVersion) {
+        return {
+            name: "scheduler-binary",
+            kind: "deterministic",
+            status: "pass",
+            confidence: "high",
+            message: `Scheduled tasks are bound to akm v${scheduledVersion}, matching the running CLI.`,
+            evidence: { binding, scheduledVersion, cliVersion },
+        };
+    }
+    return {
+        name: "scheduler-binary",
+        kind: "deterministic",
+        status: "warn",
+        confidence: "high",
+        message: `Scheduled tasks are bound to akm v${scheduledVersion}, but the running CLI is v${cliVersion} — run \`akm task sync\` to rebind the schedule.`,
+        evidence: { binding, scheduledVersion, cliVersion },
+    };
+}

package/dist/commands/health.js

@@ -27,6 +27,7 @@ import { buildImproveSkipSummary, computeWallTimeStats, countAgentFailureReasons
 import { emptyLlmUsageAggregate, readLlmUsageAggregate } from "./health/llm-usage.js";
 import { computeDegradationMetrics, computeDenominatorFixedCoverage, computeEnrichmentMintingRollup, probeStateDbRoundTrip, } from "./health/metrics.js";
 import { collectPluginStalenessAdvisories } from "./health/plugin-staleness.js";
+import { collectSchedulerBinaryAdvisory } from "./health/scheduler-binary.js";
 import { collectStashExposureAdvisory } from "./health/stash-exposure.js";
 import { collectSurfacesAdvisories } from "./health/surfaces.js";
 import { buildPerRunSummaries } from "./health/task-runs.js";
@@ -542,6 +543,12 @@ export async function akmHealth(options = {}) {
         // above — started here, alongside it, and awaited later.
         const versionDriftPromise = collectVersionDriftAdvisory(Boolean(options.probe), { cliVersion: pkgVersion });
         versionDriftPromise.catch(() => undefined);
+        // #953: same --probe-gated, best-effort discipline as versionDriftPromise
+        // above.
+        const schedulerBinaryDriftPromise = collectSchedulerBinaryAdvisory(Boolean(options.probe), {
+            cliVersion: pkgVersion,
+        });
+        schedulerBinaryDriftPromise.catch(() => undefined);
         const taskHistory = gatherTaskHistoryPhase(db, logsDb, since, stateDbPath, now);
         const { tableNames, missingTables, probe } = taskHistory;
         const { egressConfigView, thinkingOffEngines } = gatherEgressConfigPhase();
@@ -559,6 +566,7 @@ export async function akmHealth(options = {}) {
         const improveRunsInLookbackWindow = countImproveRunsSince(db, engineLastUsedSinceIso);
         const engineProbes = await engineProbesPromise;
         const versionDrift = await versionDriftPromise;
+        const schedulerBinaryDrift = await schedulerBinaryDriftPromise;
         // Read once, shared by the `thinking-control` check (#949) and the
         // `metrics.llmUsage` report field below — same window, same aggregate.
         const llmUsage = readLlmUsageAggregate(stateDbPath, since);
@@ -592,6 +600,7 @@ export async function akmHealth(options = {}) {
             activeImproveStrategyEngines,
             engineLastUsed,
             improveRunsInLookbackWindow,
+            schedulerBinaryDrift,
         };
         for (const check of HEALTH_CHECKS) {
             const result = check.run(checkContext);

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}.`);
     }