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

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/commands/models-cli.js

@@ -4,7 +4,7 @@
 import { isDeepStrictEqual } from "node:util";
 import { defineGroupCommand, defineJsonCommand, output } from "../cli/shared.js";
 import { loadConfig } from "../core/config/config.js";
-import { copyDefaultModelMap, loadModelMapLayers, mergedModelMapProfiles, mergeModelMapLayers, } from "../integrations/agent/model-map.js";
+import { copyDefaultModelMap, loadModelMapLayers, mergedModelMapProfiles, mergeModelMapLayers, WILDCARD_ENGINE_KEY, } from "../integrations/agent/model-map.js";
 /**
  * Compute the effective alias table (#946): every (alias, column) pair from
  * the fully resolved map, labeled with where its value came from.
@@ -25,6 +25,11 @@ function modelsListRows() {
     const rows = [];
     for (const [alias, columns] of Object.entries(resolved.aliases)) {
         for (const [column, profile] of Object.entries(columns)) {
+            // The wildcard default (#946) is an alias-wide fallback, not a real
+            // platform column an operator would dispatch to; report it folded into
+            // the real per-platform rows above instead of as its own row.
+            if (column === WILDCARD_ENGINE_KEY)
+                continue;
             const raw = rawProfiles[alias]?.[column];
             const via = raw?.engine !== undefined ? "engine" : "literal";
             const defaultProfile = defaultsOnly.aliases[alias]?.[column];

package/dist/commands/read/curate.js

@@ -25,6 +25,8 @@ import { copySearchHitAttribution, getSearchHitAttribution, usageEventAttributio
 import { findSourceForPath, resolveSourceEntries } from "../../indexer/search/search-source.js";
 import { insertUsageEvent } from "../../indexer/usage/usage-events.js";
 import { estimateTokenCount } from "../../llm/embedders/remote.js";
+import { tryLlmFeature } from "../../llm/feature-gate.js";
+import { rerankDocuments } from "../../llm/rerank-client.js";
 import { truncateDescription } from "../../output/shapes/helpers.js";
 import { TELEMETRY_BUSY_TIMEOUT_MS, withIndexDb } from "../../storage/repositories/index-db.js";
 import { findEntryIdByRef, getItemRefById } from "../../storage/repositories/index-entries-repository.js";
@@ -145,7 +147,7 @@ export async function curateSearchResults(query, result, limit, selectedType, ev
     // fixtures) with a `SearchResponse` that was never type-filtered.
     const stashHits = selectedType && selectedType !== "any" ? allStashHits.filter((hit) => hit.type === selectedType) : allStashHits;
     const selected = selectCuratedStashHits(query, stashHits, limit);
-    const selectedStashHits = selected.selected;
+    const selectedStashHits = await maybeRerankCuratedStashHits(query, selected.selected);
     const supportRefsByRef = selected.supportRefsByRef;
     // F4/R-019: respect `--limit` for registry fill instead of hard-capping it
     // at a bare literal 2 — the remaining slots after stash hits ARE the cap.
@@ -594,6 +596,37 @@ function appendCurateSupportRef(supportRefsByRef, ownerRef, supportRef) {
         return;
     supportRefsByRef.set(ownerRef, [...existing, supportRef]);
 }
+/** Default number of `selectCuratedStashHits` candidates sent to the reranker when `search.curateRerank.topN` isn't set. */
+const DEFAULT_CURATE_RERANK_TOP_N = 8;
+/**
+ * Optional cross-encoder rerank pass over curate's already-selected, already-
+ * ranked candidates (#951). Disabled by default (`search.curateRerank.enabled`
+ * is falsy) and, when enabled, best-effort: any failure (misconfigured
+ * endpoint, network error, timeout, malformed response) falls back to
+ * `selectCuratedStashHits`'s own ranking unchanged — a reranker outage must
+ * never turn into a curate failure.
+ *
+ * Only the top `topN` (default {@link DEFAULT_CURATE_RERANK_TOP_N}) already-
+ * selected hits are sent (bounded request size); anything past that keeps its
+ * original position appended after the reranked prefix.
+ */
+async function maybeRerankCuratedStashHits(query, hits) {
+    if (hits.length <= 1)
+        return hits;
+    const config = loadConfig();
+    const rerankConfig = config.search?.curateRerank;
+    return tryLlmFeature("curate_rerank", config, async () => {
+        const topN = rerankConfig?.topN ?? DEFAULT_CURATE_RERANK_TOP_N;
+        const head = hits.slice(0, topN);
+        const tail = hits.slice(topN);
+        const documents = head.map((hit) => [hit.name, hit.description].filter(Boolean).join(" — "));
+        const ranked = await rerankDocuments(rerankConfig ?? {}, query, documents);
+        const rerankedHead = ranked
+            .map(({ index }) => head[index])
+            .filter((hit) => hit !== undefined);
+        return [...rerankedHead, ...tail];
+    }, hits, { timeoutMs: rerankConfig?.timeoutMs ?? null });
+}
 function selectCuratedStashHits(query, hits, limit) {
     const intent = parseCurateIntent(query);
     const collapsed = collapseCurateFamilies(query, hits);

package/dist/core/config/schema/search.js

@@ -6,7 +6,7 @@
  * former `config-schema.ts` monolith — no behavior change.
  */
 import { z } from "zod";
-import { nonEmptyString, nonNegativeNumber, positiveInt } from "./primitives.js";
+import { httpUrl, nonEmptyString, nonNegativeNumber, positiveInt, symbolicOrWarnApiKey } from "./primitives.js";
 // ── Search ──────────────────────────────────────────────────────────────────
 const SearchGraphBoostSchema = z
     .object({
@@ -22,10 +22,41 @@ const SearchGraphBoostSchema = z
     confidenceWeight: z.number().finite().min(0).max(1).default(0.2).optional(),
 })
     .passthrough();
+/**
+ * `search.curateRerank` (#951) — an optional cross-encoder rerank pass over
+ * `akm curate`'s already-selected candidates.
+ *
+ * Deliberately its own small config arm rather than a third member of the
+ * `engines` map (`EngineConfigSchema` in ./engines.ts): that union's "llm" /
+ * "agent" kinds are load-bearing all the way through execution-lowering,
+ * runner dispatch, and the harness model map (100+ call sites narrow on
+ * `engine.kind`). A reranker is neither — it never dispatches an agent or
+ * lowers to a chat-completions call — so folding it into that union would
+ * force every one of those call sites to account for a kind they can't do
+ * anything with. `endpoint` + `model` (+ optional `apiKey`) is the same
+ * connection shape as an LLM engine without inheriting that machinery.
+ *
+ * `curate_rerank` was removed as a dead `llm.features.*` key in 0.8.0 (no
+ * implementation ever sent a request); this is a new, real implementation,
+ * disabled by default.
+ */
+export const CurateRerankConfigSchema = z
+    .object({
+    enabled: z.boolean().optional(),
+    /** Full URL of the reranker's rerank endpoint, e.g. `http://host:port/rerank`. */
+    endpoint: httpUrl.optional(),
+    model: nonEmptyString.optional(),
+    apiKey: symbolicOrWarnApiKey("search.curateRerank.apiKey").optional(),
+    timeoutMs: positiveInt.optional(),
+    /** How many of curate's already-ranked candidates to send to the reranker. Default 8. */
+    topN: positiveInt.max(50).optional(),
+})
+    .passthrough();
 export const SearchConfigSchema = z
     .object({
     minScore: nonNegativeNumber.optional(),
     defaultExcludeTypes: z.array(nonEmptyString).optional(),
     graphBoost: SearchGraphBoostSchema.optional(),
+    curateRerank: CurateRerankConfigSchema.optional(),
 })
     .passthrough();

package/dist/core/errors.js

@@ -83,6 +83,8 @@ 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.",
+    IMPROVE_LOCK_HELD: "Another akm improve run holds the whole-run lock right now. Wait for it to finish and retry, or pass --skip-if-locked on scheduled 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/indexer/index-db-contention.js

@@ -0,0 +1,56 @@
+// 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/.
+/**
+ * Shared index.db contention reclassification (field follow-up to #956).
+ *
+ * Extracted out of `indexer.ts` so both `akmIndex`'s outer catch AND
+ * `generateEmbeddingsForDb`'s own catch (`materialize-embeddings.ts`) can
+ * reuse the ONE classifier instead of each building a raw
+ * `Semantic search verification failed: <driver message>` string. Living in
+ * its own module (rather than one importing the other) avoids the import
+ * cycle `indexer.ts` <-> `materialize-embeddings.ts` would otherwise form.
+ */
+import { AkmError, TransientError } from "../core/errors.js";
+import { probeLock } from "../core/file-lock.js";
+import { formatLockHolderPid } from "../core/run-lock.js";
+import { isSqliteContentionError } from "../core/state-db.js";
+import { indexRebuildLockPath } from "./index-rebuild-lock.js";
+/**
+ * Read-only description of the rebuild lock's current holder, appended to a
+ * reclassified index.db contention message when known (field follow-up to
+ * #956). `probeLock` only inspects the sentinel — it never acquires or
+ * mutates it — so this is safe to call from inside an error path.
+ */
+function describeIndexRebuildLockHolder() {
+    const probe = probeLock(indexRebuildLockPath());
+    if (probe.state !== "held")
+        return "";
+    return ` The rebuild lock is currently held by pid ${formatLockHolderPid({
+        pid: probe.holderPid,
+        launcherPid: probe.launcherPid ?? null,
+    })}.`;
+}
+/**
+ * Reclassify a contention-shaped error escaping the walk, index, or
+ * embedding phase into a retryable-shortly `TransientError` (field
+ * follow-up to #956, dev-team field review 2026-09-10): a concurrent writer
+ * (another `akm index`, a source-update embedding pass, the per-command
+ * background reindex) can make index.db busy, and the raw SQLite driver
+ * error ("database is locked") used to escape as exit 70
+ * (internal/unclassified) instead of the "retry shortly" contract exit 75
+ * gives a scheduler to branch on — mirroring `STATE_DB_CONTENDED`'s
+ * precedent for state.db (`core/state-db.ts`). Reuses the ONE shared
+ * classifier, `isSqliteContentionError`, rather than a second one. An error
+ * that is already a classified akm error (e.g. a `STATE_DB_CONTENDED`
+ * TransientError from an inner state.db write) is never re-wrapped — only a
+ * raw, unclassified error matching the shared contention shape is
+ * reclassified. Every other error is rethrown unchanged.
+ */
+export function reclassifyIndexDbContention(error) {
+    if (error instanceof AkmError || !isSqliteContentionError(error))
+        return error;
+    const contended = new TransientError(`akm's index database is busy (another akm process is writing it); retry shortly.${describeIndexRebuildLockHolder()}`, "INDEX_DB_CONTENDED");
+    contended.cause = error;
+    return contended;
+}

package/dist/indexer/indexer.js

@@ -7,14 +7,12 @@ import { detectAdapterId } from "../core/adapter/detect-adapter.js";
 import { adapterForId } from "../core/adapter/registry.js";
 import { isHttpUrl, toErrorMessage } from "../core/common.js";
 import { concurrentMap } from "../core/concurrent.js";
-import { AkmError, ConfigError, TransientError } from "../core/errors.js";
-import { probeLock } from "../core/file-lock.js";
+import { ConfigError } from "../core/errors.js";
 import { defaultConcurrencyForEndpoint } from "../core/loopback.js";
 import { classifyPathAccess, describeInaccessiblePath } from "../core/path-access.js";
 import { getDbPath } from "../core/paths.js";
 import { SCRIPT_EXTENSIONS } from "../core/recognition-util.js";
-import { formatLockHolderPid } from "../core/run-lock.js";
-import { isSqliteContentionError, withStateDb } from "../core/state-db.js";
+import { withStateDb } from "../core/state-db.js";
 import { isVerbose, warn, warnOnce, warnVerbose } from "../core/warn.js";
 import { disposeLoweredExecutionDispatchLease, } from "../integrations/agent/execution-lowering.js";
 import { isLlmFeatureEnabled } from "../llm/feature-gate.js";
@@ -30,7 +28,7 @@ import { upsertUtilityScore } from "../storage/repositories/index-utility-reposi
 import { getEmbeddingCount, isVecAvailable, isVecFastPathReady, warnIfVecMissing, } from "../storage/repositories/index-vec-repository.js";
 import { assertIndexedWorkflowSourceIdentity, WorkflowSourceIdentityError } from "../workflows/source-files.js";
 import { deleteStoredGraph } from "./db/graph-db.js";
-import { indexRebuildLockPath } from "./index-rebuild-lock.js";
+import { reclassifyIndexDbContention } from "./index-db-contention.js";
 import { deriveEntryProvenance, deriveInstallations } from "./installations.js";
 import { indexedPathMatchesOwner, resolveAdapterConceptOwner, } from "./lookup/adapter-concept-owner.js";
 import { generateEmbeddingsForDb } from "./materialize-embeddings.js";
@@ -374,44 +372,13 @@ let akmIndexOverride;
 export function _setAkmIndexForTests(fake) {
     akmIndexOverride = fake;
 }
-/**
- * Read-only description of the rebuild lock's current holder, appended to a
- * reclassified index.db contention message when known (field follow-up to
- * #956). `probeLock` only inspects the sentinel — it never acquires or
- * mutates it — so this is safe to call from inside an error path.
- */
-function describeIndexRebuildLockHolder() {
-    const probe = probeLock(indexRebuildLockPath());
-    if (probe.state !== "held")
-        return "";
-    return ` The rebuild lock is currently held by pid ${formatLockHolderPid({
-        pid: probe.holderPid,
-        launcherPid: probe.launcherPid ?? null,
-    })}.`;
-}
-/**
- * Reclassify a contention-shaped error escaping the walk, index, or
- * embedding phase into a retryable-shortly `TransientError` (field
- * follow-up to #956, dev-team field review 2026-09-10): a concurrent writer
- * (another `akm index`, a source-update embedding pass, the per-command
- * background reindex) can make index.db busy, and the raw SQLite driver
- * error ("database is locked") used to escape as exit 70
- * (internal/unclassified) instead of the "retry shortly" contract exit 75
- * gives a scheduler to branch on — mirroring `STATE_DB_CONTENDED`'s
- * precedent for state.db (`core/state-db.ts`). Reuses the ONE shared
- * classifier, `isSqliteContentionError`, rather than a second one. An error
- * that is already a classified akm error (e.g. a `STATE_DB_CONTENDED`
- * TransientError from an inner state.db write) is never re-wrapped — only a
- * raw, unclassified error matching the shared contention shape is
- * reclassified. Every other error is rethrown unchanged.
- */
-export function reclassifyIndexDbContention(error) {
-    if (error instanceof AkmError || !isSqliteContentionError(error))
-        return error;
-    const contended = new TransientError(`akm's index database is busy (another akm process is writing it); retry shortly.${describeIndexRebuildLockHolder()}`, "INDEX_DB_CONTENDED");
-    contended.cause = error;
-    return contended;
-}
+// Moved to its own module (field follow-up to #956) so
+// `generateEmbeddingsForDb` (materialize-embeddings.ts) can reuse the same
+// classifier without an indexer.ts <-> materialize-embeddings.ts import
+// cycle. Re-exported here for back-compat with existing call sites/tests
+// that import it from `./indexer`. See index-db-contention.ts for the full
+// rationale.
+export { reclassifyIndexDbContention };
 export async function akmIndex(options) {
     try {
         const override = akmIndexOverride;