akm-cli 0.9.4 → 0.9.6

package/dist/indexer/index-writer-lock.js

@@ -1,15 +1,36 @@
 // 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/.
+/**
+ * Asset-mutation lease — serializes writes to real, authored user content
+ * (source updates, `akm remember`, proposal apply, ...) so two concurrent
+ * writers cannot both pass a git exact-path preflight check before either
+ * commits.
+ *
+ * This module previously also gated full index REBUILDS behind the same
+ * lease with a 12-hour age-based stale-reclaim window (#872). That guard was
+ * removed: the index is a regenerable cache, concurrent rebuilds only waste
+ * work rather than corrupt anything, and a live-but-wedged holder passed the
+ * PID-liveness check forever, so only the 12h clock could ever free it —
+ * which cost one real install a half-day indexing outage. Index rebuilds no
+ * longer take any lease.
+ *
+ * What remains here guards actual data loss (a lost or conflicting git
+ * commit), so per AGENTS.md `## Defensive Code` it stays — but with the same
+ * fix applied: no age-based stale-reclaim. A holder is only ever reclaimed
+ * once its PID is verifiably dead; a live-but-wedged holder makes an
+ * acquisition attempt wait (bounded by `maxWaitMs`) or fail, never silently
+ * override a lease someone might still be using.
+ */
 import { AsyncLocalStorage } from "node:async_hooks";
 import fs from "node:fs";
 import path from "node:path";
 import { createLockPayload, probeLock, reclaimStaleLock, releaseLock, tryAcquireLockSync, } from "../core/file-lock.js";
 import { tryAcquireMaintenanceBarrier } from "../core/maintenance-barrier.js";
 import { getDbPath, getIndexWriterLockPath } from "../core/paths.js";
-const INDEX_WRITER_LOCK_STALE_AFTER_MS = 12 * 60 * 60 * 1000;
-const INDEX_WRITER_WAIT_MS = 100;
-const DEFAULT_INDEX_WRITER_MAX_WAIT_MS = 10 * 60 * 1000;
+import { sleepSync } from "../runtime.js";
+const ASSET_MUTATION_WAIT_MS = 100;
+const DEFAULT_ASSET_MUTATION_MAX_WAIT_MS = 10 * 60 * 1000;
 const leaseContext = new AsyncLocalStorage();
 function buildPayload(purpose) {
     return createLockPayload({
@@ -24,7 +45,7 @@ function delay(ms) {
 function throwIfAborted(signal) {
     if (!signal?.aborted)
         return;
-    throw signal.reason instanceof Error ? signal.reason : new Error("index writer wait aborted");
+    throw signal.reason instanceof Error ? signal.reason : new Error("asset mutation lease wait aborted");
 }
 function createLease(lockPath, ownership) {
     const exitHandler = () => releaseLock(ownership);
@@ -41,7 +62,7 @@ function createLease(lockPath, ownership) {
         },
     };
 }
-function tryAcquireIndexWriterLease(lockPath, purpose) {
+function tryAcquireAssetMutationLease(lockPath, purpose) {
     while (true) {
         const releaseBarrier = tryAcquireMaintenanceBarrier();
         if (!releaseBarrier)
@@ -50,7 +71,8 @@ function tryAcquireIndexWriterLease(lockPath, purpose) {
             const ownership = tryAcquireLockSync(lockPath, buildPayload(purpose));
             if (ownership)
                 return createLease(lockPath, ownership);
-            const probe = probeLock(lockPath, { staleAfterMs: INDEX_WRITER_LOCK_STALE_AFTER_MS });
+            // No `staleAfterMs`: only a verifiably dead holder is ever reclaimed.
+            const probe = probeLock(lockPath);
             if (probe.state !== "stale" || !reclaimStaleLock(lockPath, probe))
                 return undefined;
         }
@@ -59,16 +81,16 @@ function tryAcquireIndexWriterLease(lockPath, purpose) {
         }
     }
 }
-export async function acquireIndexWriterLease(options) {
+export async function acquireAssetMutationLease(options) {
     const mode = options.mode ?? "wait";
     const lockPath = getIndexWriterLockPath();
     const startedAt = Date.now();
-    const maxWaitMs = options.maxWaitMs ?? DEFAULT_INDEX_WRITER_MAX_WAIT_MS;
+    const maxWaitMs = options.maxWaitMs ?? DEFAULT_ASSET_MUTATION_MAX_WAIT_MS;
     fs.mkdirSync(path.dirname(lockPath), { recursive: true });
     let lastWaitNoticeMs = 0;
     while (true) {
         throwIfAborted(options.signal);
-        const lease = tryAcquireIndexWriterLease(lockPath, options.purpose);
+        const lease = tryAcquireAssetMutationLease(lockPath, options.purpose);
         if (lease) {
             options.onAcquired?.({ waitedMs: Date.now() - startedAt });
             return lease;
@@ -79,26 +101,27 @@ export async function acquireIndexWriterLease(options) {
         // attempt, so a caller with maxWaitMs:0 still gets one chance at a free lock
         // instead of throwing before it ever tries.
         if (maxWaitMs >= 0 && Date.now() - startedAt >= maxWaitMs) {
-            throw new Error(`timed out waiting for index writer lease for ${options.purpose}`);
+            throw new Error(`timed out waiting for asset mutation lease for ${options.purpose}`);
         }
         const waitedMs = Date.now() - startedAt;
         if (waitedMs - lastWaitNoticeMs >= 15000) {
             options.onWait?.({ waitedMs });
             lastWaitNoticeMs = waitedMs;
         }
-        await delay(INDEX_WRITER_WAIT_MS);
+        await delay(ASSET_MUTATION_WAIT_MS);
     }
 }
-export async function withIndexWriterLease(options, run) {
+/** Asset writes share one lease so two concurrent writers cannot both pass preflight before either commits. */
+export async function withAssetMutationLease(purpose, run) {
     const lockPath = getIndexWriterLockPath();
     const inherited = leaseContext.getStore();
     if (inherited?.has(lockPath))
         return run();
     const context = inherited ?? new Set();
     const execute = async () => {
-        const lease = await acquireIndexWriterLease(options);
+        const lease = await acquireAssetMutationLease({ purpose });
         if (!lease)
-            throw new Error(`index writer lease unavailable for ${options.purpose}`);
+            throw new Error(`asset mutation lease unavailable for ${purpose}`);
         context.add(lockPath);
         try {
             return await run();
@@ -110,10 +133,6 @@ export async function withIndexWriterLease(options, run) {
     };
     return inherited ? execute() : leaseContext.run(context, execute);
 }
-/** Asset writes and index rebuilds share one lease so scans cannot publish stale snapshots. */
-export function withAssetMutationLease(purpose, run) {
-    return withIndexWriterLease({ purpose }, run);
-}
 /** Synchronous asset-write boundary over the same interprocess lease. */
 export function withAssetMutationLeaseSync(purpose, run) {
     const lockPath = getIndexWriterLockPath();
@@ -126,12 +145,12 @@ export function withAssetMutationLeaseSync(purpose, run) {
         fs.mkdirSync(path.dirname(lockPath), { recursive: true });
         let lease;
         while (!lease) {
-            lease = tryAcquireIndexWriterLease(lockPath, purpose);
+            lease = tryAcquireAssetMutationLease(lockPath, purpose);
             if (!lease) {
-                if (Date.now() - startedAt >= DEFAULT_INDEX_WRITER_MAX_WAIT_MS) {
-                    throw new Error(`timed out waiting for index writer lease for ${purpose}`);
+                if (Date.now() - startedAt >= DEFAULT_ASSET_MUTATION_MAX_WAIT_MS) {
+                    throw new Error(`timed out waiting for asset mutation lease for ${purpose}`);
                 }
-                Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, INDEX_WRITER_WAIT_MS);
+                sleepSync(ASSET_MUTATION_WAIT_MS);
             }
         }
         context.add(lockPath);
@@ -145,6 +164,6 @@ export function withAssetMutationLeaseSync(purpose, run) {
     };
     return inherited ? execute() : leaseContext.run(context, execute);
 }
-export function probeIndexWriterLease() {
-    return probeLock(getIndexWriterLockPath(), { staleAfterMs: INDEX_WRITER_LOCK_STALE_AFTER_MS });
+export function probeAssetMutationLease() {
+    return probeLock(getIndexWriterLockPath());
 }

package/dist/indexer/index-written-assets.js

@@ -29,9 +29,8 @@ import { getDbPath } from "../core/paths.js";
 import { warn, warnVerbose } from "../core/warn.js";
 import { closeDatabase, openExistingDatabase } from "../storage/repositories/index-connection.js";
 import { deleteEntriesByIds, getEntryCount, upsertEntry } from "../storage/repositories/index-entries-repository.js";
-import { withIndexWriterLease } from "./index-writer-lock.js";
 import { deriveEntryProvenance, deriveInstallations } from "./installations.js";
-import { generateEmbeddingsForDb, publishTargetedSemanticStatus } from "./materialize-embeddings.js";
+import { generateEmbeddingsForDb, publishTargetedEmbeddingMeta } from "./materialize-embeddings.js";
 import { drainDirDocuments } from "./scan/drain-dir.js";
 import { buildSearchText } from "./search/search-fields.js";
 import { buildFileContext } from "./walk/file-context.js";
@@ -57,7 +56,7 @@ export const WRITE_PATH_INDEX_BUSY_TIMEOUT_MS = 5_000;
  */
 export async function indexWrittenAssets(stashDir, filePaths, options = {}) {
     try {
-        return await withIndexWriterLease({ purpose: "index-written-assets" }, async () => {
+        return await (async () => {
             const dbPath = getDbPath();
             // `true` here means "the index is in the state the caller expects" — and
             // `acceptProposal` advances its journal to `index-finalized` on the
@@ -181,15 +180,15 @@ export async function indexWrittenAssets(stashDir, filePaths, options = {}) {
                 })();
                 if (mutated) {
                     const config = loadConfig();
-                    const embeddingResult = await generateEmbeddingsForDb(db, config, () => { }, undefined, [...targetEntryIds]);
-                    publishTargetedSemanticStatus(db, config, embeddingResult);
+                    await generateEmbeddingsForDb(db, config, () => { }, undefined, [...targetEntryIds]);
+                    publishTargetedEmbeddingMeta(db, config);
                 }
             }
             finally {
                 closeDatabase(db);
             }
             return true;
-        });
+        })();
     }
     catch (error) {
         // A permission fault is the one failure the next full index will NOT heal,

package/dist/indexer/indexer.js

@@ -27,7 +27,6 @@ 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 { withIndexWriterLease } from "./index-writer-lock.js";
 import { deriveEntryProvenance, deriveInstallations } from "./installations.js";
 import { indexedPathMatchesOwner, resolveAdapterConceptOwner, } from "./lookup/adapter-concept-owner.js";
 import { generateEmbeddingsForDb } from "./materialize-embeddings.js";
@@ -35,7 +34,6 @@ import { canUseIncrementalSkip, computeDirFingerprint, getCachedZeroRowDirState,
 import { isEnrichmentComplete, isWorkflowSkipWarning } from "./passes/metadata.js";
 import { drainDirDocuments } from "./scan/drain-dir.js";
 import { buildSearchText } from "./search/search-fields.js";
-import { clearSemanticStatus, deriveSemanticProviderFingerprint, writeSemanticStatus } from "./search/semantic-status.js";
 import { purgeOldUsageEvents } from "./usage/usage-events.js";
 import { walkStashFlatWithStatus } from "./walk/walker.js";
 function collectLoweringNotices(target, notices) {
@@ -265,27 +263,6 @@ async function runFinalizePhase(ctx, deferredUpdateTransaction) {
     const semanticEntryCount = getEmbeddableEntryCount(db);
     onProgress({ phase: "finalize", message: "Verifying semantic search state." });
     const verification = verifyIndexState(db, config, semanticEntryCount, embeddingResult);
-    const persistSemanticStatus = () => {
-        if (config.semanticSearchMode === "off") {
-            clearSemanticStatus();
-            return;
-        }
-        writeSemanticStatus({
-            status: verification.semanticStatus === "disabled" ? "pending" : verification.semanticStatus,
-            ...(embeddingResult.reason ? { reason: embeddingResult.reason } : {}),
-            ...(embeddingResult.message ? { message: embeddingResult.message } : {}),
-            providerFingerprint: deriveSemanticProviderFingerprint(config.embedding),
-            lastCheckedAt: new Date().toISOString(),
-            entryCount: verification.entryCount,
-            embeddingCount: verification.embeddingCount,
-        });
-    };
-    if (deferredUpdateTransaction) {
-        deferredUpdateTransaction.afterCommit = persistSemanticStatus;
-    }
-    else {
-        persistSemanticStatus();
-    }
     onProgress({ phase: "verify", message: verification.message });
     // Store verification result and totalEntries on ctx for the caller to use
     ctx.verification = verification;
@@ -492,20 +469,7 @@ async function akmIndexReal(options) {
             "Pass `akm index --clean --dry-run`, or drop `--dry-run` to run a real index.", "INVALID_FLAG_VALUE", "Run `akm index --clean --dry-run` to preview, or `akm index --clean` to apply.");
     }
     const requestedAt = Date.now();
-    let acquiredAt = requestedAt;
-    return withIndexWriterLease({
-        purpose: "akm-index",
-        signal: options?.signal,
-        onWait: ({ waitedMs }) => {
-            options?.onProgress?.({
-                phase: "preflight",
-                message: `Waiting for index writer lease (${Math.round(waitedMs / 1000)}s elapsed).`,
-            });
-        },
-        onAcquired: ({ waitedMs }) => {
-            acquiredAt = requestedAt + waitedMs;
-        },
-    }, async () => {
+    return (async () => {
         const stashDir = options.stashDir;
         const onProgress = options?.onProgress ?? (() => { });
         const signal = options?.signal;
@@ -644,7 +608,6 @@ async function akmIndexReal(options) {
                     finalizeMs: timing.tFinalizeEnd - timing.tFinalizeStart,
                     cleanMs: clean ? cleanEnd - cleanStart : 0,
                     preflightMs: timing.t0 - requestedAt,
-                    leaseWaitMs: acquiredAt - requestedAt,
                     sourceCacheMs: sourceCacheEnd - sourceCacheStart,
                     endToEndMs: Date.now() - requestedAt,
                 },
@@ -658,7 +621,7 @@ async function akmIndexReal(options) {
             if (!borrowedUpdateDb)
                 closeDatabase(db);
         }
-    });
+    })();
 }
 function buildIndexedSourceOwners(sources) {
     const installations = deriveInstallations([...sources]);

package/dist/indexer/materialize-embeddings.js

@@ -3,11 +3,25 @@
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
 import { isVerbose, warn, warnVerbose } from "../core/warn.js";
 import { embedBatch } from "../llm/embedder.js";
-import { estimateTokenCount } from "../llm/embedders/remote.js";
+import { DETERMINISTIC_EMBED_MODEL_ID, isDeterministicEmbedEnabled } from "../llm/embedders/deterministic.js";
+import { DEFAULT_LOCAL_MODEL } from "../llm/embedders/local.js";
+import { buildTokenBoundedBatches, DEFAULT_REMOTE_BATCH_SIZE, DEFAULT_TOKEN_BUDGET, estimateTokenCount, hasRemoteEndpoint, } from "../llm/embedders/remote.js";
 import { getEmbeddableEntryCount } from "../storage/repositories/index-entries-repository.js";
 import { deleteMeta, getMeta, setMeta } from "../storage/repositories/index-meta-repository.js";
-import { getAllEntriesForEmbedding, getEmbeddingCount, isVecAvailable, isVecFastPathComplete, isVecFastPathReady, purgeEmbeddings, setVecFastPathReady, upsertEmbedding, } from "../storage/repositories/index-vec-repository.js";
-import { classifySemanticFailure, clearSemanticStatus, deriveSemanticProviderFingerprint, writeSemanticStatus, } from "./search/semantic-status.js";
+import { getAllEntriesForEmbedding, getEmbeddingCount, isVecFastPathComplete, isVecFastPathReady, purgeEmbeddings, setVecFastPathReady, upsertEmbedding, } from "../storage/repositories/index-vec-repository.js";
+/** Identifies the embedding provider+model+dimension a stored vector was generated with. */
+export function deriveSemanticProviderFingerprint(embedding) {
+    if (isDeterministicEmbedEnabled()) {
+        return `deterministic:${DETERMINISTIC_EMBED_MODEL_ID}`;
+    }
+    if (embedding?.endpoint) {
+        // Fingerprint keys on vector identity only (model + dimension). The endpoint
+        // is transport/routing and has no bearing on vector compatibility, so moving
+        // the same model+dimension to a different host must not force a full re-embed.
+        return `remote:${embedding.model}|${embedding.dimension ?? "default"}`;
+    }
+    return `local:${embedding?.localModel ?? DEFAULT_LOCAL_MODEL}`;
+}
 function throwIfAborted(signal) {
     if (signal?.aborted) {
         throw signal.reason instanceof Error ? signal.reason : new Error("index interrupted");
@@ -17,7 +31,7 @@ export async function generateEmbeddingsForDb(db, config, onProgress, signal, en
     throwIfAborted(signal);
     if (config.semanticSearchMode === "off") {
         onProgress({ phase: "embeddings", message: "Semantic search disabled; skipping embeddings." });
-        return { success: false, reason: "index-missing", message: "Semantic search is disabled." };
+        return { success: false, message: "Semantic search is disabled." };
     }
     // A targeted call starts from an already-published generation. Preserve its
     // trust decision in O(1): successful writes for the changed IDs keep a
@@ -48,14 +62,35 @@ export async function generateEmbeddingsForDb(db, config, onProgress, signal, en
         });
         const texts = allEntries.map((entry) => entry.searchText);
         if (isVerbose()) {
-            const EMBED_BATCH_SIZE = 100;
-            const totalBatches = Math.ceil(texts.length / EMBED_BATCH_SIZE);
-            for (const [i, entry] of allEntries.entries()) {
-                const batchNum = Math.floor(i / EMBED_BATCH_SIZE) + 1;
-                const chars = entry.searchText.length;
-                const tokens = estimateTokenCount(entry.searchText);
-                const ref = entry.itemRef;
-                warnVerbose(`[embed] ${ref} (${chars} chars, est. ${tokens} tokens) → batch ${batchNum}/${totalBatches}`);
+            // Mirror RemoteEmbedder's actual token-bounded batching (#874) so this
+            // log reflects the real request grouping rather than a fixed count of
+            // 100 that no longer matches what gets sent over the wire. Local runs
+            // don't batch by size at all (LocalEmbedder chunks by a fixed count
+            // for inference throughput only, never fails/skips), so there's
+            // nothing meaningful to report per-batch for them.
+            if (hasRemoteEndpoint(config.embedding ?? {})) {
+                const tokenBudget = config.embedding?.maxTokens ?? config.embedding?.contextLength ?? DEFAULT_TOKEN_BUDGET;
+                const maxCount = config.embedding?.batchSize ?? DEFAULT_REMOTE_BATCH_SIZE;
+                const batches = buildTokenBoundedBatches(texts, tokenBudget, maxCount);
+                const batchNumberByIndex = new Map();
+                batches.forEach((batch, batchIdx) => {
+                    for (const i of batch.indices)
+                        batchNumberByIndex.set(i, batchIdx + 1);
+                });
+                for (const [i, entry] of allEntries.entries()) {
+                    const chars = entry.searchText.length;
+                    const tokens = estimateTokenCount(entry.searchText);
+                    const batch = batches[batchNumberByIndex.get(i) - 1];
+                    const label = batch?.oversized
+                        ? "oversized (skipped)"
+                        : `batch ${batchNumberByIndex.get(i)}/${batches.length}`;
+                    warnVerbose(`[embed] ${entry.itemRef} (${chars} chars, est. ${tokens} tokens) → ${label}`);
+                }
+            }
+            else {
+                for (const entry of allEntries) {
+                    warnVerbose(`[embed] ${entry.itemRef} (${entry.searchText.length} chars, est. ${estimateTokenCount(entry.searchText)} tokens)`);
+                }
             }
         }
         let heartbeatTimer;
@@ -66,17 +101,24 @@ export async function generateEmbeddingsForDb(db, config, onProgress, signal, en
                     message: `Still generating embeddings for ${allEntries.length} entr${allEntries.length === 1 ? "y" : "ies"}; waiting on embedding provider.`,
                 });
             }, 15000);
-            const embeddings = await embedBatch(texts, config.embedding, signal);
+            // A failing sub-batch or an oversized document is SKIPPED by embedBatch,
+            // not thrown (#874) — collect what couldn't be embedded and why, so a
+            // few bad documents don't discard every other entry's embedding.
+            const skips = [];
+            const embeddings = await embedBatch(texts, config.embedding, signal, (skip) => skips.push(skip));
             throwIfAborted(signal);
             let storedCount = 0;
             let skippedCount = 0;
+            let embedFailedCount = 0;
             let vecFailedCount = 0;
             let vecUnavailableCount = 0;
             db.transaction(() => {
                 for (const [i, entry] of allEntries.entries()) {
                     const embedding = embeddings[i];
-                    if (!embedding)
-                        throw new Error(`Embedding provider returned no vector for ${entry.itemRef}.`);
+                    if (!embedding) {
+                        embedFailedCount++;
+                        continue;
+                    }
                     const result = upsertEmbedding(db, entry.id, embedding);
                     if (result.stored)
                         storedCount++;
@@ -91,6 +133,14 @@ export async function generateEmbeddingsForDb(db, config, onProgress, signal, en
             if (skippedCount > 0) {
                 warn(`[embed] ${skippedCount} embedding${skippedCount === 1 ? "" : "s"} skipped (entry deleted between queue and write)`);
             }
+            if (embedFailedCount > 0) {
+                const detail = skips
+                    .slice(0, 20)
+                    .map((skip) => `  - ${allEntries[skip.index]?.itemRef ?? skip.index} (${skip.reason}): ${skip.message}`)
+                    .join("\n");
+                const more = skips.length > 20 ? `\n  ...and ${skips.length - 20} more` : "";
+                warn(`[embed] ${embedFailedCount} embedding${embedFailedCount === 1 ? "" : "s"} could not be generated and ${embedFailedCount === 1 ? "was" : "were"} skipped:\n${detail}${more}`);
+            }
             const vecGenerationComplete = targetEntryIds === undefined ? isVecFastPathComplete(db) : vecFastPathWasReady;
             setVecFastPathReady(db, vecFailedCount === 0 && vecUnavailableCount === 0 && vecGenerationComplete);
             if (vecFailedCount > 0) {
@@ -103,6 +153,19 @@ export async function generateEmbeddingsForDb(db, config, onProgress, signal, en
                 message: `Stored ${storedCount} embedding${storedCount === 1 ? "" : "s"}.`,
             });
             setMeta(db, "embeddingFingerprint", currentFingerprint);
+            // Only a total failure (nothing at all embedded, despite having entries
+            // to embed) turns into a phase failure. Any partial success — the vast
+            // majority of a large bundle embedding fine around a handful of skips —
+            // must not discard what DID get stored (#874).
+            if (storedCount === 0 && embedFailedCount > 0) {
+                const firstMessage = skips[0]?.message ?? "All embeddings failed.";
+                // #873 removed the persisted semantic verdict, so there is no failure
+                // class to record — just report what happened on this run.
+                return {
+                    success: false,
+                    message: `All ${embedFailedCount} embedding batch(es) failed: ${firstMessage}`,
+                };
+            }
             return { success: true, vecInsertFailures: vecFailedCount };
         }
         finally {
@@ -116,40 +179,21 @@ export async function generateEmbeddingsForDb(db, config, onProgress, signal, en
         onProgress({ phase: "embeddings", message: `Embedding generation failed: ${message}` });
         return {
             success: false,
-            reason: classifySemanticFailure(message),
             message: `Semantic search verification failed: ${message}`,
         };
     }
 }
-/** Publish the canonical semantic health snapshot after a targeted mutation. */
-export function publishTargetedSemanticStatus(db, config, result) {
+/**
+ * Update the `hasEmbeddings` DB fact after a targeted mutation, from the
+ * index's actual current embedding coverage — read fresh, not cached.
+ */
+export function publishTargetedEmbeddingMeta(db, config) {
     if (config.semanticSearchMode === "off") {
-        clearSemanticStatus();
         setMeta(db, "hasEmbeddings", "0");
         return;
     }
     const entryCount = getEmbeddableEntryCount(db);
     const embeddingCount = getEmbeddingCount(db);
-    let status;
-    if (entryCount === 0)
-        status = "pending";
-    else if (embeddingCount >= entryCount)
-        status = isVecAvailable(db) && isVecFastPathReady(db) ? "ready-vec" : "ready-js";
-    else
-        status = "blocked";
-    setMeta(db, "hasEmbeddings", status === "ready-js" || status === "ready-vec" ? "1" : "0");
-    writeSemanticStatus({
-        status,
-        ...(status === "blocked" ? { reason: result.reason ?? "index-failed" } : {}),
-        ...(status === "blocked"
-            ? {
-                message: result.message ??
-                    `Semantic search verification failed (${embeddingCount}/${entryCount} embeddings available).`,
-            }
-            : {}),
-        providerFingerprint: deriveSemanticProviderFingerprint(config.embedding),
-        lastCheckedAt: new Date().toISOString(),
-        entryCount,
-        embeddingCount,
-    });
+    const ready = entryCount > 0 && embeddingCount >= entryCount;
+    setMeta(db, "hasEmbeddings", ready ? "1" : "0");
 }

package/dist/indexer/passes/metadata.js

@@ -6,7 +6,7 @@ import path from "node:path";
 import { parseBundleRef } from "../../core/asset/asset-ref.js";
 import { parseFrontmatter } from "../../core/asset/frontmatter.js";
 import { asNonEmptyString } from "../../core/common.js";
-import { isVerbose, warn } from "../../core/warn.js";
+import { isVerbose, warn, warnVerbose } from "../../core/warn.js";
 export const SCOPE_KEYS = ["user", "agent", "run", "channel"];
 // ── Quality semantics (v1 spec §4.2) ────────────────────────────────────────
 /**
@@ -1119,7 +1119,7 @@ function stripMarkdownLinkDestinations(text, nesting = 0) {
  * secret/env/session bytes; that policy is enforced at the adapter metadata
  * boundary below.
  */
-export function projectMarkdownContent(body) {
+export function projectMarkdownContent(body, truncationInfo) {
     const lines = body.split(/\r?\n/);
     const innerBlock = findInnerFrontmatterBlock(lines);
     const start = innerBlock && isFrontmatterShaped(lines, innerBlock) ? innerBlock.close + 1 : 0;
@@ -1168,6 +1168,8 @@ export function projectMarkdownContent(body) {
     const text = projected.join(" ").replace(/\s+/g, " ").trim();
     if (!text)
         return undefined;
+    if (truncationInfo)
+        truncationInfo.truncated = text.length > MARKDOWN_CONTENT_MAX_CHARS;
     return truncateUnicodeSafe(text, MARKDOWN_CONTENT_MAX_CHARS);
 }
 // ── Metadata Generation ─────────────────────────────────────────────────────
@@ -1212,9 +1214,15 @@ export function applyPreContributorFields(entry, file, ctx, pkgMeta) {
         // Native Markdown has one bounded low-weight body projection. Sensitive
         // types and raw session/checkpoint material never cross this boundary.
         if (entry.type !== "env" && entry.type !== "session" && !hasSessionMemoryMarker(parsed.data, parsed.content)) {
-            const contentProjection = projectMarkdownContent(parsed.content);
-            if (contentProjection)
+            const truncationInfo = { truncated: false };
+            const contentProjection = projectMarkdownContent(parsed.content, truncationInfo);
+            if (contentProjection) {
                 entry.content = contentProjection;
+                if (truncationInfo.truncated) {
+                    entry.contentTruncated = true;
+                    warnVerbose(`${file}: indexed content truncated to ${MARKDOWN_CONTENT_MAX_CHARS} chars`);
+                }
+            }
         }
         // Extract parameters from template placeholders ($1, $ARGUMENTS, {{named}})
         if (entry.type === "command") {

package/dist/indexer/scan/doc-to-entry.js

@@ -58,6 +58,8 @@ export function indexDocumentToStashEntry(doc) {
         entry.tags = doc.tags;
     if (doc.content !== undefined)
         entry.content = doc.content;
+    if (doc.contentTruncated !== undefined)
+        entry.contentTruncated = doc.contentTruncated;
     if (doc.ownsPresentation !== undefined)
         entry.ownsPresentation = doc.ownsPresentation;
     if (doc.updated !== undefined)

package/dist/indexer/search/db-search.js

@@ -26,7 +26,7 @@ import { assertIndexPathReadable, closeDatabase, openExistingDatabase, } from ".
 import { getAllEntries, getBaseBeliefStatesForDerivedTwins, getEntryById, getEntryCount, getPositiveFeedbackCountsByIds, } from "../../storage/repositories/index-entries-repository.js";
 import { searchFts } from "../../storage/repositories/index-fts-repository.js";
 import { getMeta } from "../../storage/repositories/index-meta-repository.js";
-import { searchVec } from "../../storage/repositories/index-vec-repository.js";
+import { getEmbeddingCount, searchVec } from "../../storage/repositories/index-vec-repository.js";
 import { getCurrentWorkflowScopeKey } from "../../workflows/authoring/scope-key.js";
 import { ensureIndex } from "../ensure-index.js";
 import { collectGraphRelatedHit, loadGraphBoostContext } from "../graph/graph-boost.js";
@@ -38,7 +38,6 @@ import { typeBoostFor } from "./ranking-contributors.js";
 import { attachSearchHitAttribution, copySearchHitAttribution, getSearchHitAttribution } from "./search-attribution.js";
 import { enrichSearchHit } from "./search-hit-enrichers.js";
 import { buildEditHint, findSourceForPath, isEditable } from "./search-source.js";
-import { deriveSemanticProviderFingerprint, getEffectiveSemanticStatus, isSemanticRuntimeReady, readSemanticStatus, } from "./semantic-status.js";
 /**
  * Age past which search surfaces a "run akm index" hint. Reads serve the
  * existing index as-is (freshness is the writers' job — `indexWrittenAssets`
@@ -126,49 +125,14 @@ export async function searchLocal(input) {
     const disableScopedUtility = input.disableScopedUtility === true;
     const rendererRegistry = input.rendererRegistry ?? defaultRendererRegistry;
     const allSourceDirs = sources.map((s) => s.path);
-    const rawStatus = readSemanticStatus();
-    const semanticStatus = getEffectiveSemanticStatus(config, rawStatus);
     const warnings = [];
-    if (config.semanticSearchMode === "auto" && semanticStatus === "pending") {
-        const currentFingerprint = deriveSemanticProviderFingerprint(config.embedding);
-        if (rawStatus && rawStatus.providerFingerprint !== currentFingerprint) {
-            warnings.push("Embedding config changed. Run 'akm index --full' to rebuild the semantic index with the new provider.");
-        }
-        else if (!hasConfiguredEmbeddingProvider(config)) {
-            // #480: when semantic mode is `auto` but no embedding provider is
-            // configured (e.g. `akm setup --yes` ran without picking one), telling
-            // the user to "run akm setup" is misleading — they just did. Surface
-            // the actual remediation: configure an embedding endpoint OR switch
-            // semanticSearchMode to `off` to silence the warning.
-            warnings.push("Semantic search is enabled (semanticSearchMode='auto') but no embedding provider is configured. " +
-                'Either: (a) `akm config set embedding \'{"endpoint":"...","model":"..."}\'`, or ' +
-                "(b) `akm config set semanticSearchMode off` to use keyword-only search.");
-        }
-        else {
-            warnings.push("Semantic search is pending verification. Run 'akm index --full' to build the semantic index now, or wait for the next background index pass.");
-        }
-    }
-    if (config.semanticSearchMode === "auto" && semanticStatus === "blocked") {
-        if (!hasConfiguredEmbeddingProvider(config)) {
-            // F7/A2: same predicate as the `pending` branch above (#480) — a
-            // `blocked` status can outlive the provider config that produced it
-            // (e.g. the embedding config was later unset). This is not a fault;
-            // there is simply nothing configured to use.
-            warnings.push("Semantic search is enabled (semanticSearchMode='auto') but no embedding provider is configured. " +
-                'Either: (a) `akm config set embedding \'{"endpoint":"...","model":"..."}\'`, or ' +
-                "(b) `akm config set semanticSearchMode off` to use keyword-only search.");
-        }
-        else {
-            // F7/A2: surface the ACTUAL diagnostic instead of one fixed generic
-            // string. `rawStatus.reason`/`rawStatus.message` record why the
-            // semantic backend failed (auth, network, a stuck local-model
-            // download, …) — read at `readSemanticStatus()` above and, before
-            // this fix, discarded here in favor of a message that never varied.
-            const detail = rawStatus?.message ?? (rawStatus?.reason ? `reason: ${rawStatus.reason}` : undefined);
-            warnings.push(`Semantic search is blocked${detail ? ` (${detail})` : ""}. Using keyword search until the semantic ` +
-                "backend is healthy again. Run 'akm index --full' to retry, or " +
-                "`akm config set semanticSearchMode off` to silence this warning.");
-        }
+    // Semantic search is attempted fresh on every query (see `tryVecScores`);
+    // there is no cached readiness verdict to consult here. The only thing
+    // worth flagging ahead of the attempt is a config that can never succeed.
+    if (config.semanticSearchMode === "auto" && !hasConfiguredEmbeddingProvider(config)) {
+        warnings.push("Semantic search is enabled (semanticSearchMode='auto') but no embedding provider is configured. " +
+            'Either: (a) `akm config set embedding \'{"endpoint":"...","model":"..."}\'`, or ' +
+            "(b) `akm config set semanticSearchMode off` to use keyword-only search.");
     }
     // Bootstrap-only: builds the index inline when it cannot serve this stash.
     // Content freshness is the writers' job (indexWrittenAssets + full runs);
@@ -662,11 +626,14 @@ function matchBeliefFilter(beliefState, filter) {
 }
 // ── Vector scorer ───────────────────────────────────────────────────────────
 async function tryVecScores(db, query, k, config) {
-    const semanticStatus = getEffectiveSemanticStatus(config, readSemanticStatus());
-    if (!isSemanticRuntimeReady(semanticStatus))
+    if (config.semanticSearchMode === "off")
         return { scores: null };
-    const hasEmbeddings = getMeta(db, "hasEmbeddings");
-    if (hasEmbeddings !== "1")
+    // A real-time completeness fact, not a cached verdict: skip the network
+    // round trip only when the index has never embedded anything. A PARTIAL
+    // failure (some entries embedded, one write degraded) still attempts —
+    // and if the endpoint is genuinely down, the failure surfaces as a live
+    // `semanticWarning` below instead of silently skipping with no signal.
+    if (getEmbeddingCount(db) === 0)
         return { scores: null };
     try {
         const { embed } = await import("../../llm/embedder.js");