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

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/config/schema/embedding.js

@@ -45,13 +45,12 @@ export const EmbeddingConnectionConfigSchema = z
     maxInputTokens: positiveInt.optional(),
     /**
      * Client-side per-request token budget — how many documents' estimated
-     * tokens fit in one HTTP request (default `DEFAULT_TOKEN_BUDGET` = 8000
+     * tokens fit in one HTTP request (default `DEFAULT_TOKEN_BUDGET` = 6000
      * in `src/llm/embedders/remote.ts`). With the 512-token `maxInputTokens`
-     * cap above, a request carries about 16 documents by default.
+     * cap above, a request carries about 11 documents by default.
      */
     maxTokens: positiveInt.optional(),
     batchSize: positiveInt.optional(),
-    chunkSize: positiveInt.optional(),
     /**
      * Ollama's `num_ctx` ONLY (#956) — sent verbatim as
      * `options.num_ctx` on the native `/api/embed` request. It no longer also

package/dist/core/errors.js

@@ -82,6 +82,8 @@ const USAGE_HINTS = {
 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/indexer/indexer.js

@@ -7,12 +7,14 @@ 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 { ConfigError } from "../core/errors.js";
+import { AkmError, ConfigError, TransientError } from "../core/errors.js";
+import { probeLock } from "../core/file-lock.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 { withStateDb } from "../core/state-db.js";
+import { formatLockHolderPid } from "../core/run-lock.js";
+import { isSqliteContentionError, 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";
@@ -28,6 +30,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 { deriveEntryProvenance, deriveInstallations } from "./installations.js";
 import { indexedPathMatchesOwner, resolveAdapterConceptOwner, } from "./lookup/adapter-concept-owner.js";
 import { generateEmbeddingsForDb } from "./materialize-embeddings.js";
@@ -371,6 +374,44 @@ 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;
+}
 export async function akmIndex(options) {
     try {
         const override = akmIndexOverride;
@@ -387,7 +428,7 @@ export async function akmIndex(options) {
                 // rollback before closing its borrowed unified handle.
             }
         }
-        throw error;
+        throw reclassifyIndexDbContention(error);
     }
 }
 let indexTransactionHookForTests;

package/dist/indexer/materialize-embeddings.js

@@ -136,8 +136,14 @@ function deriveObservedEmbeddingIdentity(embedding, observedModel, observedVecto
  * direct `RemoteEmbedder`) so every embedder branch — remote, local,
  * deterministic, and test overrides via `_setEmbedderForTests` — is
  * exercised identically to the main embedding pass.
+ *
+ * `maxInputTokens` must be the SAME cap the main pass below applies via
+ * {@link capEmbeddingText} — the stored vector for each sampled entry was
+ * produced from its capped text, so comparing against a fresh vector of the
+ * uncapped text would compare unlike inputs for any entry over the cap
+ * (#955).
  */
-async function runEmbeddingCanary(db, config, signal) {
+async function runEmbeddingCanary(db, config, signal, maxInputTokens) {
     const samples = sampleEmbeddedEntriesForCanary(db, CANARY_SAMPLE_SIZE);
     if (samples.length === 0) {
         return { outcome: "keep", verified: false, viaIdentityMatch: false };
@@ -146,7 +152,15 @@ async function runEmbeddingCanary(db, config, signal) {
     const skips = [];
     let canaryVectors;
     try {
-        canaryVectors = await embedBatch(samples.map((sample) => sample.searchText), config.embedding, signal, (skip) => skips.push(skip), (_indices, _embeddings, model) => {
+        canaryVectors = await embedBatch(
+        // #955: the stored vector for each sample was produced from
+        // capEmbeddingText(searchText, maxInputTokens) — the main pass below
+        // caps every document before embedding it. The canary must re-embed
+        // the SAME capped text, or an entry over the cap compares a fresh
+        // vector of a different input against a stored vector of the capped
+        // one, and a genuine model match can read as a rebuild-worthy
+        // mismatch for reasons unrelated to the model.
+        samples.map((sample) => capEmbeddingText(sample.searchText, maxInputTokens).text), config.embedding, signal, (skip) => skips.push(skip), (_indices, _embeddings, model) => {
             if (model)
                 observedModel = model;
         });
@@ -252,6 +266,10 @@ export async function generateEmbeddingsForDb(db, config, onProgress, signal, en
     let targetEntryIds = entryIds;
     /** Set only on an actual rebuild, so the up-front "Re-embedding N entries" line names why. */
     let rebuildReason;
+    // Resolved once and reused by both the canary (below) and the main pass's
+    // cap loop (further down) — the same cap must apply to both, or the canary
+    // compares a differently-capped text against the stored vector (#955).
+    const maxInputTokens = config.embedding?.maxInputTokens ?? DEFAULT_MAX_INPUT_TOKENS;
     if (opts?.forceReembed) {
         // `akm index --reembed`: an explicit operator override, skips the canary
         // entirely. The new fingerprint (and identity, now stale/unknown until
@@ -272,7 +290,7 @@ export async function generateEmbeddingsForDb(db, config, onProgress, signal, en
         rebuildReason = "forced by --reembed";
     }
     else if (storedFingerprint && storedFingerprint !== currentFingerprint) {
-        const decision = await runEmbeddingCanary(db, config, signal);
+        const decision = await runEmbeddingCanary(db, config, signal, maxInputTokens);
         if (decision.outcome === "unverifiable") {
             // Destroying a good index because the server happens to be down right
             // now is worse than leaving a rename unverified until the next run —
@@ -377,12 +395,12 @@ export async function generateEmbeddingsForDb(db, config, onProgress, signal, en
             return reusedCount > 0 ? { success: true, vecInsertFailures: vecFailedCount } : { success: true };
         }
         // Cap each document's embedded text at
-        // embedding.maxInputTokens (default DEFAULT_MAX_INPUT_TOKENS) instead of
-        // ever failing a whole batch over one oversized entry — truncation keeps
-        // the head of the text, unicode-safe. A document is skipped only when its
+        // embedding.maxInputTokens (default DEFAULT_MAX_INPUT_TOKENS, resolved
+        // once above so the canary uses the identical cap) instead of ever
+        // failing a whole batch over one oversized entry — truncation keeps the
+        // head of the text, unicode-safe. A document is skipped only when its
         // head is empty (the impossible case: nothing left to embed), never
         // merely for being long.
-        const maxInputTokens = config.embedding?.maxInputTokens ?? DEFAULT_MAX_INPUT_TOKENS;
         let truncatedCount = 0;
         const texts = [];
         const pendingEntries = [];
@@ -529,6 +547,23 @@ export async function generateEmbeddingsForDb(db, config, onProgress, signal, en
                     }
                     return;
                 }
+                // #954: a "budget-lowered" event is the same kind of notice as
+                // "retrying" above — the run's first context-size rejection just
+                // shrank the request budget for everything not yet dispatched, but
+                // THIS rejected batch's own indices are still being split and
+                // retried by the embedder (their real stored/failed outcome lands in
+                // a later onBatch call). Nothing here has settled, so it must never
+                // touch storage, only report the notice — one line, at most once per
+                // run.
+                if (outcome?.outcome === "budget-lowered") {
+                    if (reportPerBatchLine) {
+                        onProgress({
+                            phase: "embeddings",
+                            message: `[embed] batch ${outcome.batchIndex}/${outcome.batchCount}: ${outcome.docCount} docs, ${outcome.requestTokens.toLocaleString()} tokens → ${outcome.reason}`,
+                        });
+                    }
+                    return;
+                }
                 if (model)
                     observedModel = model;
                 // A batch that delivered at least one real embedding proves the
@@ -542,7 +577,8 @@ export async function generateEmbeddingsForDb(db, config, onProgress, signal, en
                 }
                 db.transaction(() => {
                     for (let k = 0; k < indices.length; k++) {
-                        const entry = pendingEntries[indices[k]];
+                        const index = indices[k];
+                        const entry = pendingEntries[index];
                         if (!entry)
                             continue;
                         const embedding = batchEmbeddings[k];
@@ -555,7 +591,13 @@ export async function generateEmbeddingsForDb(db, config, onProgress, signal, en
                         const result = upsertEmbedding(db, entry.id, embedding);
                         if (result.stored) {
                             storedCount++;
-                            storedTokens += estimateTokenCount(entry.searchText);
+                            // #954: sum the estimate of the text actually sent —
+                            // `texts[index]` is the capped string `embedBatch` was handed,
+                            // parallel to `pendingEntries` by construction above (the
+                            // `entry` guard covers both) — not `entry.searchText`, which is
+                            // the pre-cap original and overstates throughput for every
+                            // entry over the cap.
+                            storedTokens += estimateTokenCount(texts[index]);
                         }
                         else {
                             skippedCount++;

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;
+}