akm-cli 0.9.15-beta.3 → 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.3] - 2026-09-10
+## [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`
@@ -279,6 +280,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
 
@@ -610,6 +624,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 +647,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/reflect.js

@@ -29,7 +29,7 @@ import { parseFrontmatter } from "../../core/asset/frontmatter.js";
 import { conceptIdFromTypeName, parseRefInput } from "../../core/asset/resolve-ref.js";
 import { DESCRIPTION_MAX_CHARS, requiresDescription } from "../../core/authoring-rules.js";
 import { loadConfig } from "../../core/config/config.js";
-import { ConfigError } from "../../core/errors.js";
+import { ConfigError, UsageError } from "../../core/errors.js";
 import { appendEvent, readEvents } from "../../core/events.js";
 import { lintLessonContent } from "../../core/lesson-lint.js";
 import { parseEmbeddedJsonResponse } from "../../core/parse.js";
@@ -1371,6 +1371,92 @@ async function resolveReflectSource(options, stash, emitReflectFailed) {
     }
     return { assetContent, parsedRef };
 }
+/**
+ * #952 — the flat REFLECT_CONTENT_CAP (12 000 chars) exists only to avoid
+ * E2BIG when the prompt travels through CLI argv (agent/SDK runners). The
+ * direct-LLM HTTP path never touches argv, so it can use the resolved
+ * engine's own context window instead. The reserve for "the rest of the
+ * prompt" is measured directly (not guessed): build the same prompt with
+ * the content cap forced to zero and use its length as the overhead, so
+ * feedback/standards/schema-hints/prior-draft size is accounted for
+ * exactly, per this call. A reflect rewrite returns a body roughly the
+ * size of the input, so the budget only spends HALF of the usable window
+ * on input content and reserves the other half for the model's own
+ * output — otherwise a full-context request leaves no room for a
+ * response. Never drops below the flat floor.
+ *
+ * Shared by the real dispatch path ({@link runReflectRefineIterations}) and
+ * `renderReflectPromptPreview`'s `--show-prompt` preview, so the preview
+ * renders the exact prompt reflect would actually send for LLM runners
+ * instead of always the flat-cap prompt.
+ */
+function computeReflectContentBudgetChars(promptInput, runnerSpec) {
+    return runnerIsLlm(runnerSpec) && promptInput.assetContent?.trim()
+        ? Math.max(REFLECT_CONTENT_CAP, Math.floor(((runnerSpec.connection.contextLength ?? DEFAULT_CONTEXT_LENGTH_TOKENS) * CHARS_PER_TOKEN -
+            buildReflectPrompt({ ...promptInput, contentBudgetChars: 0 }).prompt.length) /
+            2))
+        : undefined;
+}
+/**
+ * #952 — gather every read-only prompt-input source {@link buildReflectPromptInput}
+ * folds into a `ReflectPromptInput`: recent feedback, schema/lint hints, related
+ * lessons, previously-rejected proposals, and stash standards context.
+ *
+ * Shared by the real dispatch path (`akmReflect`'s step 4, via
+ * {@link runReflectRefineIterations}) and `renderReflectPromptPreview`'s
+ * `--show-prompt` preview, so both gather from exactly one definition instead
+ * of two copies that can drift out of agreement.
+ */
+async function gatherReflectPromptSources(options, stash, parsedRef, assetContent, assetCtx) {
+    const feedback = readRecentFeedback(options.ref ? (options.itemRef ?? durableImproveRef(options.ref)) : undefined, options.eventsCtx);
+    const schemaHints = buildSchemaHints(parsedRef?.type ?? "", assetContent);
+    const relatedLessons = options.ref && parsedRef ? await readRelatedLessons(assetCtx, stash, options.ref, parsedRef, options.itemRef) : [];
+    // Reflexion-style verbal-RL: inject rejected proposals so the agent avoids
+    // reproducing proposals that have already been reviewed and refused.
+    const rejectedProposals = readRejectedProposals(stash, options.ref, options.ctx);
+    // Standards "rulebook" for this target — stash convention/meta facts; empty
+    // when none fire.
+    const standardsContext = resolveStandardsContext(options.ref, stash);
+    return { feedback, schemaHints, relatedLessons, rejectedProposals, standardsContext };
+}
+/**
+ * #952 — assemble the `ReflectPromptInput` object literal reflect actually
+ * sends, from gathered sources plus the per-call values (draft path, prior
+ * draft). Shared by the real dispatch path ({@link runReflectRefineIterations})
+ * and `renderReflectPromptPreview`'s `--show-prompt` preview — including
+ * `avoidPatterns`, which the preview previously omitted even though a live
+ * improve loop passes it (recent-error context, O-5 / #378).
+ */
+function buildReflectPromptInput(args) {
+    const { options, parsedRef, assetContent, sources, runnerSpec, draftFilePath, priorDraft } = args;
+    const { feedback, schemaHints, relatedLessons, rejectedProposals, standardsContext } = sources;
+    const outputMode = runnerIsLlm(runnerSpec)
+        ? wantsJsonSchemaOutput(runnerSpec.connection)
+            ? "json_schema"
+            : "framed_markdown"
+        : undefined;
+    return {
+        ...(options.ref ? { ref: options.ref } : {}),
+        ...(parsedRef?.type ? { type: parsedRef.type } : {}),
+        ...(parsedRef?.name ? { name: parsedRef.name } : {}),
+        ...(assetContent !== undefined ? { assetContent } : {}),
+        ...(feedback.length > 0 ? { feedback } : {}),
+        ...(schemaHints.length > 0 ? { schemaHints } : {}),
+        ...(relatedLessons.length > 0 ? { relatedLessons } : {}),
+        ...(options.task ? { task: options.task } : {}),
+        ...(standardsContext.trim() ? { standardsContext } : {}),
+        ...(options.avoidPatterns && options.avoidPatterns.length > 0 ? { avoidPatterns: options.avoidPatterns } : {}),
+        ...(rejectedProposals.length > 0 ? { rejectedProposals } : {}),
+        // R-1: inject prior draft as self-critique target on iterations > 0
+        ...(priorDraft !== undefined ? { priorDraft } : {}),
+        // Issue A (#reflect-pipeline file-write contract): when the runner can
+        // touch the filesystem, instruct the agent to write the proposal body
+        // to a tmp file instead of inlining it in JSON. Avoids parse failures
+        // on long bodies (e.g. knowledge/systems/KOKORO_USAGE_GUIDE 8.4KB).
+        ...(draftFilePath ? { draftFilePath } : {}),
+        ...(outputMode ? { outputMode } : {}),
+    };
+}
 /**
  * Run the agent with the optional Self-Refine loop (R-1 / #372): up to
  * `maxRefineIters` invocations, each injecting the prior draft as self-critique
@@ -1379,17 +1465,12 @@ async function resolveReflectSource(options, stash, emitReflectFailed) {
  * result + last draft path. Extracted verbatim from `akmReflect`.
  */
 async function runReflectRefineIterations(args) {
-    const { options, parsedRef, assetContent, feedback, schemaHints, relatedLessons, rejectedProposals, standardsContext, runnerSpec, lease, agentEnv, draftPathsToCleanup, onNotices, } = args;
+    const { options, parsedRef, assetContent, sources, runnerSpec, lease, agentEnv, draftPathsToCleanup, onNotices } = args;
     const maxRefineIters = Math.max(1, options.maxRefineIters ?? 1);
     // Determine whether this dispatch can honour the file-write contract.
     // Agent CLI + OpenCode SDK runners both have filesystem access; the direct
     // LLM HTTP runner does NOT.
     const canRunnerWriteFile = runnerSupportsFileWrite(runnerSpec);
-    const outputMode = runnerIsLlm(runnerSpec)
-        ? wantsJsonSchemaOutput(runnerSpec.connection)
-            ? "json_schema"
-            : "framed_markdown"
-        : undefined;
     // Initialized to a sentinel; always overwritten in the first loop iteration
     // (maxRefineIters is clamped to >= 1 above).
     let result = {};
@@ -1404,44 +1485,16 @@ async function runReflectRefineIterations(args) {
             draftPathsToCleanup.push(iterDraftPath);
             lastDraftPath = iterDraftPath;
         }
-        const promptInput = {
-            ...(options.ref ? { ref: options.ref } : {}),
-            ...(parsedRef?.type ? { type: parsedRef.type } : {}),
-            ...(parsedRef?.name ? { name: parsedRef.name } : {}),
-            ...(assetContent !== undefined ? { assetContent } : {}),
-            ...(feedback.length > 0 ? { feedback } : {}),
-            ...(schemaHints.length > 0 ? { schemaHints } : {}),
-            ...(relatedLessons.length > 0 ? { relatedLessons } : {}),
-            ...(options.task ? { task: options.task } : {}),
-            ...(standardsContext.trim() ? { standardsContext } : {}),
-            ...(options.avoidPatterns && options.avoidPatterns.length > 0 ? { avoidPatterns: options.avoidPatterns } : {}),
-            ...(rejectedProposals.length > 0 ? { rejectedProposals } : {}),
-            // R-1: inject prior draft as self-critique target on iterations > 0
-            ...(priorDraft !== undefined ? { priorDraft } : {}),
-            // Issue A (#reflect-pipeline file-write contract): when the runner can
-            // touch the filesystem, instruct the agent to write the proposal body
-            // to a tmp file instead of inlining it in JSON. Avoids parse failures
-            // on long bodies (e.g. knowledge/systems/KOKORO_USAGE_GUIDE 8.4KB).
-            ...(iterDraftPath ? { draftFilePath: iterDraftPath } : {}),
-            ...(outputMode ? { outputMode } : {}),
-        };
-        // #952 — the flat REFLECT_CONTENT_CAP (12 000 chars) exists only to avoid
-        // E2BIG when the prompt travels through CLI argv (agent/SDK runners). The
-        // direct-LLM HTTP path never touches argv, so it can use the resolved
-        // engine's own context window instead. The reserve for "the rest of the
-        // prompt" is measured directly (not guessed): build the same prompt with
-        // the content cap forced to zero and use its length as the overhead, so
-        // feedback/standards/schema-hints/prior-draft size is accounted for
-        // exactly, per this call. A reflect rewrite returns a body roughly the
-        // size of the input, so the budget only spends HALF of the usable window
-        // on input content and reserves the other half for the model's own
-        // output — otherwise a full-context request leaves no room for a
-        // response. Never drops below the flat floor.
-        const contentBudgetChars = runnerIsLlm(runnerSpec) && assetContent?.trim()
-            ? Math.max(REFLECT_CONTENT_CAP, Math.floor(((runnerSpec.connection.contextLength ?? DEFAULT_CONTEXT_LENGTH_TOKENS) * CHARS_PER_TOKEN -
-                buildReflectPrompt({ ...promptInput, contentBudgetChars: 0 }).prompt.length) /
-                2))
-            : undefined;
+        const promptInput = buildReflectPromptInput({
+            options,
+            parsedRef,
+            assetContent,
+            sources,
+            runnerSpec,
+            draftFilePath: iterDraftPath,
+            priorDraft,
+        });
+        const contentBudgetChars = computeReflectContentBudgetChars(promptInput, runnerSpec);
         const { prompt } = buildReflectPrompt({
             ...promptInput,
             ...(contentBudgetChars !== undefined ? { contentBudgetChars } : {}),
@@ -1459,10 +1512,10 @@ async function runReflectRefineIterations(args) {
                 ...(options.signal ? { signal: options.signal } : {}),
                 priorDraft,
                 iteration: iter,
-                ...(outputMode === "json_schema"
+                ...(promptInput.outputMode === "json_schema"
                     ? { responseSchema: options.ref ? REFLECT_JSON_SCHEMA : REFLECT_UNSCOPED_JSON_SCHEMA }
                     : {}),
-                outputMode: outputMode ?? "framed_markdown",
+                outputMode: promptInput.outputMode ?? "framed_markdown",
                 ...(options.ref ? { targetRef: options.ref } : {}),
                 allowRepair: repairAttempts === 0,
                 ...(options.chat ? { chat: options.chat } : {}),
@@ -1650,6 +1703,62 @@ function validateReflectPayloadRef(args) {
         return undefined;
     }
 }
+/**
+ * #952 — render the composed reflect prompt for exactly one asset with no
+ * engine dispatch. Reuses every read-only step `akmReflect` performs before
+ * {@link buildReflectPrompt} (source resolution, runner resolution, feedback /
+ * schema-hint / related-lesson / rejected-proposal gathering) and stops right
+ * there: no dispatch lease is acquired, no request is sent, and — because the
+ * `emitReflectFailed` callback passed to {@link resolveReflectSource} here is
+ * a no-op — no `reflect_invoked`/`reflect_completed` event is appended either.
+ *
+ * `akm improve <ref> --show-prompt` (`improve-cli.ts`) is the CLI surface: a
+ * field operator uses it to see the exact prompt reflect would send, in
+ * seconds, without running a full improve cycle or needing a reachable
+ * engine.
+ */
+export async function renderReflectPromptPreview(options) {
+    if (!options.ref) {
+        throw new UsageError("renderReflectPromptPreview requires options.ref.", "INVALID_FLAG_VALUE");
+    }
+    const ref = options.ref;
+    const stash = resolveRunStashDir(options.stashDir);
+    const sourceResolved = await resolveReflectSource(options, stash, () => {
+        // No event emitted: this is a read-only preview, not a real invocation.
+    });
+    if ("failure" in sourceResolved) {
+        const { failure } = sourceResolved;
+        throw new UsageError((!failure.ok && failure.error) || `Reflect cannot preview ref "${ref}".`, "INVALID_FLAG_VALUE");
+    }
+    const { assetContent, parsedRef } = sourceResolved;
+    const { runnerSpec, engineName } = resolveReflectRunner(options);
+    const ctx = buildReflectRunContext({ options, stash, config: options.config ?? loadConfig(), runnerSpec });
+    const assetCtx = ctx.withFreshAssetMemo();
+    const sources = await gatherReflectPromptSources(options, stash, parsedRef, assetContent, assetCtx);
+    const canRunnerWriteFile = runnerSupportsFileWrite(runnerSpec);
+    // Same tmp-path synthesis a real dispatch would use (Issue A) — never
+    // written to, since this preview never runs the agent.
+    const draftFilePath = canRunnerWriteFile ? synthesizeReflectDraftPath(ref) : undefined;
+    const previewPromptInput = buildReflectPromptInput({
+        options,
+        parsedRef,
+        assetContent,
+        sources,
+        runnerSpec,
+        draftFilePath,
+        priorDraft: undefined,
+    });
+    // #952 — mirror the real dispatch path's context-aware content budget (see
+    // computeReflectContentBudgetChars) so the preview shows the exact prompt
+    // reflect would send: an LLM engine with a large context window gets the
+    // full asset with no truncation marker, not the flat 12 000-char cap.
+    const contentBudgetChars = computeReflectContentBudgetChars(previewPromptInput, runnerSpec);
+    const { prompt } = buildReflectPrompt({
+        ...previewPromptInput,
+        ...(contentBudgetChars !== undefined ? { contentBudgetChars } : {}),
+    });
+    return { ref, prompt, engine: engineName, engineKind: runnerSpec.kind };
+}
 export async function akmReflect(options = {}) {
     const stash = resolveRunStashDir(options.stashDir);
     // Build lazy event emitters. The invocation row is committed only after the
@@ -1695,17 +1804,7 @@ export async function akmReflect(options = {}) {
         // 4. Build the shared prompt inputs — feedback, hints, lessons, rejected
         // proposals. These are stable across refinement iterations; only the
         // `priorDraft` field changes per-iteration (R-1 / #372).
-        const feedback = readRecentFeedback(options.ref ? (options.itemRef ?? durableImproveRef(options.ref)) : undefined, options.eventsCtx);
-        const schemaHints = buildSchemaHints(parsedRef?.type ?? "", assetContent);
-        const relatedLessons = options.ref && parsedRef
-            ? await readRelatedLessons(assetCtx, stash, options.ref, parsedRef, options.itemRef)
-            : [];
-        // Reflexion-style verbal-RL: inject rejected proposals so the agent avoids
-        // reproducing proposals that have already been reviewed and refused.
-        const rejectedProposals = readRejectedProposals(stash, options.ref, options.ctx);
-        // Standards "rulebook" for this target — stash convention/meta facts; empty
-        // when none fire.
-        const standardsContext = resolveStandardsContext(options.ref, stash);
+        const sources = await gatherReflectPromptSources(options, stash, parsedRef, assetContent, assetCtx);
         // 5. Spawn the agent — with the optional Self-Refine loop (R-1 / #372),
         // extracted to {@link runReflectRefineIterations}.
         const agentEnv = options.eventSource === "improve" ? { AKM_EVENT_SOURCE: "improve" } : {};
@@ -1725,11 +1824,7 @@ export async function akmReflect(options = {}) {
                 options,
                 parsedRef,
                 assetContent,
-                feedback,
-                schemaHints,
-                relatedLessons,
-                rejectedProposals,
-                standardsContext,
+                sources,
                 runnerSpec,
                 lease: generationLease,
                 agentEnv,
@@ -1808,7 +1903,7 @@ export async function akmReflect(options = {}) {
             qualityGateSkippedNoJudge,
             qualityJudgeRunner,
             qualityJudgeLease,
-            feedback,
+            feedback: sources.feedback,
             stash,
             emitReflectFailed,
             onNotices: collectExecutionNotices,

package/dist/core/errors.js

@@ -83,6 +83,7 @@ const TRANSIENT_HINTS = {
     RUN_LEASE_HELD: "Wait for the named engine invocation to finish or for the lease to expire, then retry. `akm workflow status <id>` shows the current lease.",
     STATE_DB_CONTENDED: "Another akm process is writing state.db right now. Wait a few seconds and retry; commands that support --skip-if-locked can skip instead of failing.",
     INDEX_DB_CONTENDED: "Another akm process is writing index.db; retry shortly, or pass --skip-if-locked on scheduled runs.",
+    MAINTENANCE_BARRIER_BUSY: "Another akm process is registering a lock or lease right now. Retry shortly, or pass --skip-if-locked on scheduled index/improve/workflow runs.",
 };
 /** Default hint for each NotFoundError code. */
 const NOT_FOUND_HINTS = {

package/dist/core/maintenance-barrier.js

@@ -6,7 +6,8 @@ import { randomUUID } from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
 import { sleepSync } from "../runtime.js";
-import { ConfigError } from "./errors.js";
+import { backoffDelay } from "./common.js";
+import { ConfigError, TransientError } from "./errors.js";
 import { createLockPayload, probeLock, reclaimStaleLock, releaseLock, tryAcquireLockSync } from "./file-lock.js";
 import { getMaintenanceBarrierPath } from "./paths.js";
 const heldBarrierContext = new AsyncLocalStorage();
@@ -24,6 +25,26 @@ const heldBarrierContext = new AsyncLocalStorage();
  * (`commands/improve/extract.ts`).
  */
 const MAINTENANCE_BARRIER_STALE_AFTER_MS = 5 * 60 * 1000;
+/**
+ * The barrier normally holds for one lock-file write — sub-millisecond on
+ * any real filesystem. Two akm processes racing to register a lock in the
+ * very same instant (e.g. two `akm index` runs a scheduler launched back to
+ * back) can still collide on it; retrying briefly resolves that ordinary
+ * case instead of failing a legitimate concurrent invocation outright
+ * (field follow-up to #956, G1). Bounded short so a genuinely wedged holder
+ * still surfaces the busy error promptly rather than making a losing
+ * process hang — comfortably above the barrier's normal hold time, well
+ * below a length that would make this feel like the blocking lock #872
+ * removed. Never applies to the rebuild lock itself, which stays
+ * non-blocking (#872).
+ */
+const MAINTENANCE_BARRIER_BUSY_RETRY_BOUND_MS = 1_500;
+let busyRetryBoundMsForTests;
+/** Test-only override for {@link MAINTENANCE_BARRIER_BUSY_RETRY_BOUND_MS}, so a unit test can exercise the
+ * exhausted-retry throw without a real ~1.5s wait. Restored via tests/_helpers/seams.ts's resetAllSeams(). */
+export function _setMaintenanceBarrierBusyRetryBoundMsForTests(ms) {
+    busyRetryBoundMsForTests = ms;
+}
 /**
  * Serialize the short critical section that creates each long-lived AKM lock,
  * lease, or state activity. The operation keeps its own ownership record; this
@@ -44,11 +65,19 @@ export function tryAcquireMaintenanceBarrier() {
     return undefined;
 }
 export function acquireMaintenanceBarrier() {
-    const release = tryAcquireMaintenanceBarrier();
-    if (release)
-        return release;
-    throw new ConfigError(`AKM maintenance is in progress (barrier ${getMaintenanceBarrierPath()}); retry after it completes. ` +
-        `A sentinel older than ${MAINTENANCE_BARRIER_STALE_AFTER_MS / 60_000} minute(s) is reclaimed automatically on the next attempt.`, "INVALID_CONFIG_FILE");
+    const boundMs = busyRetryBoundMsForTests ?? MAINTENANCE_BARRIER_BUSY_RETRY_BOUND_MS;
+    const deadline = Date.now() + boundMs;
+    for (let attempt = 0;; attempt += 1) {
+        const release = tryAcquireMaintenanceBarrier();
+        if (release)
+            return release;
+        const remainingMs = deadline - Date.now();
+        if (remainingMs <= 0)
+            break;
+        sleepSync(Math.min(backoffDelay(attempt), remainingMs));
+    }
+    throw new TransientError(`AKM maintenance is in progress (barrier ${getMaintenanceBarrierPath()}); retry shortly. ` +
+        `A sentinel older than ${MAINTENANCE_BARRIER_STALE_AFTER_MS / 60_000} minute(s) is reclaimed automatically on the next attempt.`, "MAINTENANCE_BARRIER_BUSY");
 }
 export function withMaintenanceStartBarrier(run) {
     if (heldBarrierContext.getStore()?.active)

package/dist/llm/client.js

@@ -472,3 +472,21 @@ export async function probeLlmEndpoint(config, timeoutMs = 3_000) {
         return { reachable: false, error: err instanceof Error ? err.message : String(err) };
     }
 }
+/**
+ * Endpoint-keyed probe memoization (#957): every caller that probes several
+ * engine connections in one pass (`akm health`'s engine checks, `akm
+ * improve --require-engines`) shares one in-flight probe per distinct
+ * endpoint (trailing slashes normalized) instead of firing a duplicate probe
+ * when two engines point at the same server. `cache` must be scoped to one
+ * invocation and never shared across calls — a stale "reachable" surviving
+ * past the run that produced it is the failure mode this exists to avoid.
+ */
+export function probeEndpointOnce(connection, cache, probe) {
+    const key = connection.endpoint.replace(/\/+$/, "");
+    let pending = cache.get(key);
+    if (!pending) {
+        pending = probe(connection);
+        cache.set(key, pending);
+    }
+    return pending;
+}

package/dist/llm/usage-persist.js

@@ -67,12 +67,18 @@ function toEventMetadata(record) {
  * opened for its other events. A getter is resolved for every append so a
  * caller can replace its context binding without replacing this owning sink.
  * When omitted, `appendEvent` falls back to its default open-insert-close path.
+ *
+ * `onRecord`, when supplied, runs synchronously for every terminal record
+ * BEFORE persistence — improve's first-engine-response heartbeat (#957) uses
+ * it to know the run is no longer silent, without this module taking on any
+ * dependency of its own on improve's lifecycle.
  */
-export function installLlmUsagePersistence(ctx) {
+export function installLlmUsagePersistence(ctx, onRecord) {
     let expectedTerminalRecords = 0;
     let disposed = false;
     setLlmUsageSink((record) => {
         expectedTerminalRecords += 1;
+        onRecord?.(record);
         appendEvent({ eventType: LLM_USAGE_EVENT, metadata: toEventMetadata(record) }, typeof ctx === "function" ? ctx() : ctx);
     });
     return () => {

package/dist/scripts/akm-migrate-node.js

@@ -7071,7 +7071,8 @@ var init_errors = __esm(() => {
   TRANSIENT_HINTS = {
     RUN_LEASE_HELD: "Wait for the named engine invocation to finish or for the lease to expire, then retry. `akm workflow status <id>` shows the current lease.",
     STATE_DB_CONTENDED: "Another akm process is writing state.db right now. Wait a few seconds and retry; commands that support --skip-if-locked can skip instead of failing.",
-    INDEX_DB_CONTENDED: "Another akm process is writing index.db; retry shortly, or pass --skip-if-locked on scheduled runs."
+    INDEX_DB_CONTENDED: "Another akm process is writing index.db; retry shortly, or pass --skip-if-locked on scheduled runs.",
+    MAINTENANCE_BARRIER_BUSY: "Another akm process is registering a lock or lease right now. Retry shortly, or pass --skip-if-locked on scheduled index/improve/workflow runs."
   };
   NOT_FOUND_HINTS = {
     ASSET_NOT_FOUND: "Run `akm search <query>` or `akm index` to refresh the index.",
@@ -77923,10 +77924,13 @@ import { AsyncLocalStorage } from "node:async_hooks";
 import { randomUUID as randomUUID2 } from "node:crypto";
 import fs7 from "node:fs";
 import path12 from "node:path";
+init_common();
 init_errors();
 init_paths();
 var heldBarrierContext = new AsyncLocalStorage;
 var MAINTENANCE_BARRIER_STALE_AFTER_MS = 5 * 60 * 1000;
+var MAINTENANCE_BARRIER_BUSY_RETRY_BOUND_MS = 1500;
+var busyRetryBoundMsForTests;
 function tryAcquireMaintenanceBarrier() {
   const lockPath = getMaintenanceBarrierPath();
   fs7.mkdirSync(path12.dirname(lockPath), { recursive: true });
@@ -77942,10 +77946,18 @@ function tryAcquireMaintenanceBarrier() {
   return;
 }
 function acquireMaintenanceBarrier() {
-  const release = tryAcquireMaintenanceBarrier();
-  if (release)
-    return release;
-  throw new ConfigError(`AKM maintenance is in progress (barrier ${getMaintenanceBarrierPath()}); retry after it completes. ` + `A sentinel older than ${MAINTENANCE_BARRIER_STALE_AFTER_MS / 60000} minute(s) is reclaimed automatically on the next attempt.`, "INVALID_CONFIG_FILE");
+  const boundMs = busyRetryBoundMsForTests ?? MAINTENANCE_BARRIER_BUSY_RETRY_BOUND_MS;
+  const deadline = Date.now() + boundMs;
+  for (let attempt = 0;; attempt += 1) {
+    const release = tryAcquireMaintenanceBarrier();
+    if (release)
+      return release;
+    const remainingMs = deadline - Date.now();
+    if (remainingMs <= 0)
+      break;
+    sleepSync(Math.min(backoffDelay(attempt), remainingMs));
+  }
+  throw new TransientError(`AKM maintenance is in progress (barrier ${getMaintenanceBarrierPath()}); retry shortly. ` + `A sentinel older than ${MAINTENANCE_BARRIER_STALE_AFTER_MS / 60000} minute(s) is reclaimed automatically on the next attempt.`, "MAINTENANCE_BARRIER_BUSY");
 }
 function withMaintenanceStartBarrier(run) {
   if (heldBarrierContext.getStore()?.active)

package/dist/scripts/akm-migrate.js

@@ -7070,7 +7070,8 @@ var init_errors = __esm(() => {
   TRANSIENT_HINTS = {
     RUN_LEASE_HELD: "Wait for the named engine invocation to finish or for the lease to expire, then retry. `akm workflow status <id>` shows the current lease.",
     STATE_DB_CONTENDED: "Another akm process is writing state.db right now. Wait a few seconds and retry; commands that support --skip-if-locked can skip instead of failing.",
-    INDEX_DB_CONTENDED: "Another akm process is writing index.db; retry shortly, or pass --skip-if-locked on scheduled runs."
+    INDEX_DB_CONTENDED: "Another akm process is writing index.db; retry shortly, or pass --skip-if-locked on scheduled runs.",
+    MAINTENANCE_BARRIER_BUSY: "Another akm process is registering a lock or lease right now. Retry shortly, or pass --skip-if-locked on scheduled index/improve/workflow runs."
   };
   NOT_FOUND_HINTS = {
     ASSET_NOT_FOUND: "Run `akm search <query>` or `akm index` to refresh the index.",
@@ -77251,10 +77252,13 @@ import { AsyncLocalStorage } from "async_hooks";
 import { randomUUID as randomUUID2 } from "crypto";
 import fs7 from "fs";
 import path12 from "path";
+init_common();
 init_errors();
 init_paths();
 var heldBarrierContext = new AsyncLocalStorage;
 var MAINTENANCE_BARRIER_STALE_AFTER_MS = 5 * 60 * 1000;
+var MAINTENANCE_BARRIER_BUSY_RETRY_BOUND_MS = 1500;
+var busyRetryBoundMsForTests;
 function tryAcquireMaintenanceBarrier() {
   const lockPath = getMaintenanceBarrierPath();
   fs7.mkdirSync(path12.dirname(lockPath), { recursive: true });
@@ -77270,10 +77274,18 @@ function tryAcquireMaintenanceBarrier() {
   return;
 }
 function acquireMaintenanceBarrier() {
-  const release = tryAcquireMaintenanceBarrier();
-  if (release)
-    return release;
-  throw new ConfigError(`AKM maintenance is in progress (barrier ${getMaintenanceBarrierPath()}); retry after it completes. ` + `A sentinel older than ${MAINTENANCE_BARRIER_STALE_AFTER_MS / 60000} minute(s) is reclaimed automatically on the next attempt.`, "INVALID_CONFIG_FILE");
+  const boundMs = busyRetryBoundMsForTests ?? MAINTENANCE_BARRIER_BUSY_RETRY_BOUND_MS;
+  const deadline = Date.now() + boundMs;
+  for (let attempt = 0;; attempt += 1) {
+    const release = tryAcquireMaintenanceBarrier();
+    if (release)
+      return release;
+    const remainingMs = deadline - Date.now();
+    if (remainingMs <= 0)
+      break;
+    sleepSync(Math.min(backoffDelay(attempt), remainingMs));
+  }
+  throw new TransientError(`AKM maintenance is in progress (barrier ${getMaintenanceBarrierPath()}); retry shortly. ` + `A sentinel older than ${MAINTENANCE_BARRIER_STALE_AFTER_MS / 60000} minute(s) is reclaimed automatically on the next attempt.`, "MAINTENANCE_BARRIER_BUSY");
 }
 function withMaintenanceStartBarrier(run) {
   if (heldBarrierContext.getStore()?.active)

package/docs/migration/release-notes/0.9.15.md

@@ -8,6 +8,20 @@ now, retry shortly." If a script or scheduler wrapper special-cases exit 2 to
 detect a held lease, switch it to exit 75, or read the JSON envelope's `code`
 field instead.
 
+A concurrent `akm index` now also exits 75 instead of exit 78 or exit 70. A
+2026-09-10 field report found a second `akm index` (no `--skip-if-locked`)
+colliding on the short internal barrier that registers the opt-in rebuild
+lock could fail with `{"code":"INVALID_CONFIG_FILE"}` at exit 78 — a
+config-error exit that told a supervisor to stop retrying ordinary
+contention between two legitimate runs. That barrier now retries briefly
+before giving up, and a busy barrier is reclassified as `TransientError`
+code `MAINTENANCE_BARRIER_BUSY` (exit 75) instead. Contention on index.db
+itself was already reclassified from a raw `database is locked` error (exit
+70) to `TransientError` code `INDEX_DB_CONTENDED` (exit 75). Either way, the
+fix for a scheduled or opportunistic index run is the same:
+`akm index --skip-if-locked` steps aside (exit 0) instead of contending at
+all.
+
 The six shipped scheduled `improve` task templates now run with
 `--require-engines`, which aborts (exit 78) before any index work when a
 process's engine or credential cannot be resolved in the task's own
@@ -17,6 +31,23 @@ already-materialized task files are not rewritten. To get the same protection
 on an existing scheduled task, add `--require-engines` to its `run:` command
 yourself, then run `akm task sync`.
 
+`--require-engines` now also runs a bounded reachability probe against each
+distinct engine endpoint (the same probe `akm health` already uses), not
+only a config/credential check. A field re-test found the flag let a run
+through to a fully dead endpoint, which then sat silent for minutes making
+no progress and no exit — the flag's exit-78 abort now catches that case up
+front, naming the unreachable engine and endpoint, before any index work.
+If a scheduled `--require-engines` run starts failing at exit 78 after
+upgrading, check that the engine's endpoint actually answers — this is the
+flag doing its documented job on a condition it previously missed, not a
+new failure mode. Separately, `--timeout-ms` and an engine's own configured
+timeout already aborted an in-flight request correctly, and SIGTERM/SIGINT
+already ended a run within its documented grace period — both confirmed,
+not changed, by this investigation. A live run now also prints one
+default-level line if it waits more than a few seconds on its first engine
+response, so a slow-but-alive run and a dead one are never indistinguishable
+from silence alone.
+
 `akm health --no-probe` now also skips the `cli-version` update check (a GitHub
 release lookup), alongside the engine-reachability checks it already skipped.
 An air-gapped or offline host's existing `--no-probe` habit now suppresses both
@@ -114,6 +145,40 @@ instead of ever failing a whole batch over one oversized document.
   set `contextLength` specifically to control request batching (not your
   Ollama server's context window), set `embedding.maxTokens` instead.
 
+**Which token knob fixed the original 8k-context overflow.** A 0.9.15-beta
+field report described documents estimated under the request budget that
+still tokenized to 8.5k-12.4k real tokens against an 8192-token endpoint,
+because the 4-chars-per-token estimator undercounts dense technical text.
+`maxInputTokens`, `maxTokens`, and `contextLength` are easy to confuse, and
+only one of them makes that overflow structurally unreachable:
+
+- `embedding.maxInputTokens` (default `512`) is the per-DOCUMENT cap. It
+  truncates a document's embedded text to its head before the document is
+  ever counted toward a request, so no single document can contribute more
+  than 512 estimated tokens. This is the fix: it makes the original
+  single-document overflow structurally unreachable, independent of the
+  other two knobs.
+- `embedding.maxTokens` (default `6000`) is the per-REQUEST budget — how
+  many already-capped documents fit in one HTTP request — plus a same-run
+  adaptive shrink on the first context-size rejection. It reduces how often
+  a request lands near an endpoint's real limit, but a request-level budget
+  alone cannot stop one oversized document from overflowing a request.
+- `embedding.contextLength` sets Ollama's `num_ctx` only. It no longer feeds
+  the request token budget the way it used to (the two fields used to share
+  this one value), and it has no effect at all against a non-Ollama
+  endpoint.
+
+The field's exact 0.9.15-beta config — `contextLength: 8192` and
+`maxTokens: 8000` — produces no 400s on 0.9.15. `maxTokens` now defaults
+lower anyway (6000), but that is not why the overflow stopped: every
+document is truncated to `maxInputTokens` (512 tokens) before it is counted
+toward any request, so the 8.5k-12.4k-token documents that used to overflow
+an 8192-token endpoint can no longer reach the request budget in the first
+place. Set `embedding.maxInputTokens` higher only if you need documents
+longer than ~2000 characters embedded in full — for a corpus with such
+documents, size `embedding.maxTokens` to still fit the worst case, or the
+overflow risk returns.
+
 `akm index --full` and an index-generation bump no longer re-embed
 unchanged content: vectors about to be discarded are salvaged and handed
 back to unchanged entries at the start of the next embedding pass instead

package/docs/reference/cli.md

@@ -285,6 +285,13 @@ long enough to exhaust the driver's retry window, the run now fails with
 exit 75 (`TransientError`, code `INDEX_DB_CONTENDED`) instead of the raw
 driver error at exit 70 — the same retry-shortly contract as
 `STATE_DB_CONTENDED`, so a scheduler can branch on it instead of alerting.
+The rebuild lock itself is registered through a brief internal barrier
+(`getMaintenanceBarrierPath()`) shared with every other akm lock/lease; two
+`akm index` runs launched close enough together to collide on that
+registration step retry briefly and then, if it is still busy, also exit 75
+(code `MAINTENANCE_BARRIER_BUSY`) rather than the config-error exit 78 a
+2026-09-10 field report found — a busy registration barrier is ordinary
+contention between two legitimate runs, never a broken config file.
 `--skip-if-locked` changes that only for the invocation that passes it: if
 the lock is already held by a live process, it skips gracefully (exit 0,
 `{ ok: true, skipped: { reason: "lock-held", pid, launcherPid, startedAt } }`
@@ -2336,6 +2343,7 @@ akm improve --require-engines          # for scheduled runs: abort (exit 78) ins
 akm improve --no-sync                  # skip the end-of-run git commit entirely (default: on for git-backed bundles)
 akm improve --sync --no-push           # commit only, skip the push after it
 akm improve --plan --strategy thorough # preview thorough's resolved engine/model routing; nothing is dispatched
+akm improve lessons/my-lesson --show-prompt --format text # print the composed reflect prompt for one asset, unwrapped; no lock/index/engine call
 akm improve report                     # LLM usage/routing report for the most recent real run
 akm improve report --run <id>          # ...for one specific improve_runs id
 akm improve report --since 7d          # ...aggregated over every real run started in the last 7 days
@@ -2355,7 +2363,8 @@ akm improve report --since 7d          # ...aggregated over every real run start
 | `--strategy <name>` | Override the active improve strategy (a built-in or entry under `improve.strategies`) |
 | `--json-to-stdout` | Also emit the full persisted JSON result on stdout for a live run. Without this flag, stdout stays empty. Dry-runs always emit their result and are never persisted. |
 | `--skip-if-locked` | If another improve run already holds the lock, skip gracefully (exit 0) instead of failing with "already running" (exit 78). Use for high-frequency scheduled runs so they don't pile up failures while a longer run is in progress. |
-| `--require-engines` | Abort (exit 78, before any indexing, lock, or log side effect) 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: it skips the affected processes and reports them in the result's `skippedProcesses`. Recommended alongside `--skip-if-locked` for scheduled runs, since the operator's own shell can pass config validation while a scheduler's stripped-down environment (see #953) cannot. |
+| `--require-engines` | Abort (exit 78, before any indexing, lock, or log side effect) 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`'s `default-llm-engine`/`configured-engines` checks run, once per distinct endpoint. Without this flag, improve degrades gracefully: it skips the affected processes and reports them in the result's `skippedProcesses`. Recommended alongside `--skip-if-locked` for scheduled runs, since the operator's own shell can pass config validation while a scheduler's stripped-down environment (see #953) cannot. |
+| `--show-prompt` | Print the composed reflect prompt (#952) for one asset and exit — before any lock, index write, or engine dispatch. Requires a fully-qualified asset ref as the scope (`akm improve lessons/my-lesson --show-prompt`); rejected with a type or whole-bundle scope. The default output format is JSON, which carries the prompt as a `prompt` field (escaped into one line) alongside the resolved `engine`/`engineKind`; pass `--format text` to print the prompt itself, unwrapped and readable by eye. |
 | `--sync` / `--no-sync` | Commit (and optionally push) the git-backed primary bundle when the run finishes. Default: on for git-backed bundles (per profile config). |
 | `--push` / `--no-push` | Push after the end-of-run sync commit when writable with a remote configured. `--no-push` commits only, skipping the push. Default: per profile config (`true`). `sync.push` stays outside the autonomy gate — this is a per-run opt-out, not a default change. |
 
@@ -2411,6 +2420,18 @@ on an unavailable credential either — even a strategy left with every process
 disabled this way still returns its plan, with the affected processes in
 `skippedProcesses`.
 
+`--timeout-ms` is a run-wide wall-clock budget: when it expires, the run
+cooperatively aborts any in-flight engine request (the same `AbortSignal`
+every LLM call already honors) instead of waiting out the engine's own,
+much longer, per-call timeout — the run then finishes and reports normally
+rather than hanging past its budget. SIGTERM/SIGINT/SIGHUP end a live run
+the same way, within a short bounded grace period, and the process exits
+with a stable per-signal code (`143`/`130`/`129`) rather than needing a
+`kill -9`. If a live run has waited more than a few seconds without any
+engine response at all, one default-level line ("Still waiting for the
+first engine response...") is printed so a scheduled run's log is never
+silently empty while an engine is slow or dead.
+
 For dry runs, `plannedRefs` is the effective post-limit work set, not every
 ref in the requested scope. The `plan` object preserves both views: raw scope
 size and per-gate removals, configured and effective caps, final ranked refs
@@ -2452,6 +2473,17 @@ no model or per-process notices. Neither `--dry-run` nor `--plan` probes
 engine reachability over the network — pair with `akm health --probe` (or the
 default probe-on behavior) to check whether a named engine actually answers.
 
+`--show-prompt` (#952) is the cheapest way to exercise reflect alone: it
+builds the exact prompt reflect would send for one asset — the same source
+resolution, runner selection, feedback/schema-hint/related-lesson/rejected-
+proposal gathering `akm improve`'s live reflect step uses — and prints it
+without acquiring a dispatch lease, so it never calls an engine. Add
+`--format text` (the default JSON/yaml envelope escapes the prompt into one
+line, which defeats a by-eye read) to confirm by eye that recent feedback is
+framed as an unverified report to investigate (never a fact to insert
+verbatim) and that the response contract tells the model never to emit the
+truncation marker or any content from outside the shown asset.
+
 When reinforced facts need promotion, `knowledge` is the higher-authority
 destination than `memory`. The deterministic search ranking also prefers
 `knowledge` over `memory` hits, including inferred `.derived` memories, when

package/docs/reference/configuration.md

@@ -411,6 +411,40 @@ apply when unset), for a remote endpoint (`src/llm/embedders/remote.ts`):
 | `embedding.timeoutMs` | `120000` (120s) | Per-request wall timeout — see below. |
 | `embedding.concurrency` | `1` loopback / `2` remote | In-flight request window — see below. |
 
+**Which knob fixed the field's 8k-context overflow, worked examples.** A
+0.9.15-beta field report described documents estimated under the request
+budget that still tokenized to 8.5k-12.4k real tokens against an
+8192-token endpoint, because the 4-chars-per-token estimator undercounts
+dense technical text. Three knobs changed shape between beta and this
+release; only one of them makes that overflow structurally unreachable:
+
+- `embedding.maxInputTokens: 512` — per-DOCUMENT cap, applied before
+  batching. Example: a 6,000-character API reference page is truncated to
+  its first ~2,000 characters (512 estimated tokens) before it is ever
+  counted toward a request. This is the fix for the original overflow: no
+  single document can contribute more than 512 estimated tokens to a
+  request, no matter how `maxTokens` or `contextLength` are set.
+- `embedding.maxTokens: 6000` — per-REQUEST budget: how many already-capped
+  documents' estimated tokens fit in one HTTP request. Example: with the
+  default 512-token document cap, a request packs about 11 documents before
+  this budget is reached and the request is sent; if the run's first
+  request is still rejected for exceeding the endpoint's real context
+  window, akm shrinks this budget to three quarters of its value (floored
+  at twice `maxInputTokens`) for every later request in the same run. A
+  request-level budget alone cannot stop one oversized document from
+  overflowing a request — only the per-document cap above does that.
+- `embedding.contextLength: 8192` — Ollama's `num_ctx` only, forwarded
+  verbatim on a native `/api/embed` request. It has no effect on request or
+  document sizing, and no effect at all against a non-Ollama endpoint — see
+  below for why that used not to be true.
+
+A field config of `contextLength: 8192` + `maxTokens: 8000` (the exact
+0.9.15-beta values from the original report) produces no 400s on 0.9.15:
+`maxInputTokens` (512, new this release) caps every document before it is
+counted, so the original 8.5k-12.4k-token documents that overflowed the
+8192-token endpoint can never reach the request budget in the first place —
+independent of whatever `maxTokens` or `contextLength` are set to.
+
 `embedding.timeoutMs` (positive integer, default `120000` — 120s) is the
 budget for a request at the FULL token budget (`embedding.maxTokens`); a
 local model server on a large, token-budget-bounded batch legitimately takes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akm-cli",
-  "version": "0.9.15-beta.3",
+  "version": "0.9.15-beta.4",
   "type": "module",
   "description": "akm (Agent Knowledge Manager) — a portable, local-first capability library for AI agents. Discover, load, share, and improve reusable skills, scripts, workflows, and knowledge across any shell-capable coding agent, including Claude Code, OpenCode, and Cursor.",
   "keywords": [