akm-cli 0.9.14 → 0.9.15-beta.2

package/dist/core/state-db.js

@@ -60,6 +60,22 @@
  * of events.jsonl is replaced by WAL-mode serialised writes — acceptable because
  * CLI commands are almost always single-writer.
  *
+ * ## Writer contention (#948)
+ *
+ * Every open already carries a 30s `busy_timeout` (`sqlite-pragmas.ts`), so a
+ * single blocked statement waits before failing. `withImmediateTransaction`
+ * additionally retries `BEGIN IMMEDIATE` itself
+ * ({@link WITH_IMMEDIATE_TX_MAX_ATTEMPTS} attempts) for the rarer case of two
+ * writers racing the BEGIN statement back-to-back. If every attempt is still
+ * contention-shaped ({@link isSqliteContentionError} — SQLITE_BUSY/LOCKED, the
+ * matching message text, or the phantom-BEGIN marker), the exhaustion throw is
+ * reclassified into `TransientError("STATE_DB_CONTENDED")` (exit 75, #948
+ * addendum) instead of surfacing the raw driver text: another akm process (an
+ * unrelated `improve`, `workflow run`, or task run — not necessarily
+ * contending for the same row) is writing state.db right now. A genuinely
+ * unrelated error (real corruption, a body-thrown failure) is never
+ * reclassified and rethrows exactly as raised.
+ *
  * @module state-db
  */
 import { randomUUID } from "node:crypto";
@@ -70,6 +86,7 @@ import { openDatabase } from "../storage/database.js";
 import { assertMigrationLedger } from "../storage/engines/sqlite-migrations.js";
 import { openManagedDatabase, withManagedDb } from "../storage/managed-db.js";
 import { pkgVersion } from "../version.js";
+import { TransientError } from "./errors.js";
 import { acquireMaintenanceActivitySync } from "./maintenance-barrier.js";
 import { getDataDir } from "./paths.js";
 import { runMigrations, STATE_MIGRATIONS } from "./state/migrations.js";
@@ -621,20 +638,30 @@ export function withStateDbTelemetry(fn, busyTimeoutMs = 250) {
  * the live queue state rather than clobbering each other.
  */
 /**
- * Errors `BEGIN IMMEDIATE` can throw under concurrent-writer contention that are
- * transient (the statement did NOT start a usable transaction) and safe to
- * retry:
- *   - "database is locked" / SQLITE_BUSY — another writer holds the lock.
- * These are start-of-transaction failures only; an error thrown by `fn` is a
- * real failure and is NEVER retried.
+ * Whether `err` is one of the SQLite conditions a concurrent-writer race can
+ * throw that are transient — the statement did NOT corrupt anything, another
+ * writer just holds the lock right now — and therefore safe to retry or
+ * reclassify as ordinary contention rather than a genuine failure:
+ *   - `SQLITE_BUSY` / `SQLITE_LOCKED` (either driver's `.code`).
+ *   - "database is locked" / "database table is locked" message text.
+ *   - the phantom-BEGIN marker synthesized below when `BEGIN IMMEDIATE`
+ *     returns without actually opening a transaction.
  *
- * "cannot start a transaction within a transaction" is deliberately NOT
- * retryable: it means a transaction is already open on this connection (a
- * re-entrant call — handled by the entry guard in withImmediateTransaction),
- * and "retrying" it with a ROLLBACK would destroy the caller's transaction
- * (issue #686).
+ * This is the single shared classifier for "is this ordinary state.db
+ * contention" (#948) — `isRetryableBeginError` below delegates to it, and so
+ * does {@link WorkflowRunsRepository}'s lease-contention classifier (which
+ * additionally matches a couple of corruption-shaped texts specific to its
+ * own narrower cross-process race and keeps its own live-lease confirmation
+ * before reclassifying). Matching this set alone is never sufficient to
+ * declare something DEFINITELY contention when a caller needs corroborating
+ * evidence (see the lease path); for `beginImmediateTransaction`'s own
+ * exhaustion case there is no such evidence available, so the five 30s
+ * `busy_timeout` waits already spent stand as the evidence instead.
  */
-function isRetryableBeginError(err) {
+export function isSqliteContentionError(err) {
+    const code = err?.code;
+    if (code === "SQLITE_BUSY" || code === "SQLITE_LOCKED")
+        return true;
     const msg = (err instanceof Error ? err.message : String(err)).toLowerCase();
     return (msg.includes("database is locked") ||
         msg.includes("database table is locked") ||
@@ -642,6 +669,20 @@ function isRetryableBeginError(err) {
         // without opening a transaction. Safe to retry: fn() has not run.
         msg.includes("did not open a transaction"));
 }
+/**
+ * Errors `BEGIN IMMEDIATE` can throw under concurrent-writer contention that
+ * are transient (the statement did NOT start a usable transaction) and safe
+ * to retry. An error thrown by `fn` is a real failure and is NEVER retried.
+ *
+ * "cannot start a transaction within a transaction" is deliberately NOT
+ * retryable: it means a transaction is already open on this connection (a
+ * re-entrant call — handled by the entry guard in withImmediateTransaction),
+ * and "retrying" it with a ROLLBACK would destroy the caller's transaction
+ * (issue #686).
+ */
+function isRetryableBeginError(err) {
+    return isSqliteContentionError(err);
+}
 const WITH_IMMEDIATE_TX_MAX_ATTEMPTS = 5;
 /** Portable synchronous sleep (works under both Bun and Node). Delegates to the runtime boundary's `sleepSync`. */
 function sleepSyncMs(ms) {
@@ -658,6 +699,25 @@ function sleepSyncMs(ms) {
  * publication have all succeeded. The caller that asked for this split phase
  * owns the matching COMMIT/ROLLBACK.
  */
+/**
+ * Reclassify an exhausted-retry BEGIN failure that is still contention-shaped
+ * (#948) into a `TransientError("STATE_DB_CONTENDED")`, mirroring the
+ * RUN_LEASE_HELD precedent (`WorkflowRunsRepository.acquireEngineLease`): the
+ * driver text is accurate but unhelpful (`{"ok":false,"error":"database is
+ * locked"}`, exit 70/INTERNAL) — this instead reads as a retryable-shortly
+ * signal (exit 75, sysexits EX_TEMPFAIL — #948 addendum) with the original
+ * error preserved as `cause` for `--verbose`/debugging. A genuinely unrelated
+ * error (not contention-shaped) is rethrown exactly as raised, never
+ * reclassified.
+ */
+function throwBeginFailure(err) {
+    if (isSqliteContentionError(err)) {
+        const contended = new TransientError("akm's state database is busy (another akm process is writing it); retry shortly.", "STATE_DB_CONTENDED");
+        contended.cause = err;
+        throw contended;
+    }
+    throw err;
+}
 export function beginImmediateTransaction(db) {
     if (db.inTransaction) {
         throw new Error("beginImmediateTransaction requires a connection with no active transaction");
@@ -685,10 +745,10 @@ export function beginImmediateTransaction(db) {
                 sleepSyncMs(2 ** (attempt - 1));
                 continue;
             }
-            throw err;
+            throwBeginFailure(err);
         }
     }
-    throw lastBeginErr;
+    throwBeginFailure(lastBeginErr);
 }
 export function withImmediateTransaction(db, fn) {
     // Re-entrancy guard (issue #686): if a transaction is already open on this

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

@@ -0,0 +1,73 @@
+// 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/.
+/**
+ * Opt-in, non-blocking rebuild lock for `akm index` (#956).
+ *
+ * #872 removed the blocking index-rebuild lease: the index is a regenerable
+ * cache, so a concurrent rebuild only wastes work rather than corrupts
+ * anything, and a live-but-wedged holder passed a PID-liveness check forever
+ * — only an age-based clock could ever free it, which is exactly the hazard
+ * #872 deleted. This module does not reinstate that lock. It adds a
+ * PID-liveness-only sentinel an explicit `akm index` run acquires and
+ * releases on exit purely so a *scheduled or opportunistic* run
+ * (`--skip-if-locked`) can step aside instead of piling up behind a rebuild
+ * already in progress. A human-typed `akm index` with no flag is never
+ * gated: it warns and proceeds exactly as it did before this lock existed.
+ *
+ * Built on the shared PID-liveness mechanics in `core/run-lock.ts` (the same
+ * ones `akm improve`'s whole-run lock uses) — see that module's doc for the
+ * no-stale-age-window rationale.
+ */
+import { releaseLock } from "../core/file-lock.js";
+import { tryWithMaintenanceStartBarrier, withMaintenanceStartBarrier } from "../core/maintenance-barrier.js";
+import { getIndexRebuildLockPath } from "../core/paths.js";
+import { formatLockHolderPid, tryAcquireRunLock } from "../core/run-lock.js";
+import { warn, warnVerbose } from "../core/warn.js";
+export function indexRebuildLockPath() {
+    return getIndexRebuildLockPath();
+}
+/**
+ * Acquire the rebuild lock for the duration of one `akm index` run.
+ *
+ *  - Free: always returns `"acquired"`.
+ *  - Held, `skipIfLocked`: warns once (naming the holder) and returns
+ *    `"skipped"` — the caller must not run `akmIndex()` at all.
+ *  - Held, no flag: warns once and returns `"contended"` — the caller runs
+ *    `akmIndex()` unlocked, exactly as every `akm index` did before #956.
+ *
+ * A dead holder's lease is reclaimed silently (verbose-only log line, never
+ * a user-facing warning) — the operator did nothing wrong and nothing here
+ * requires their attention.
+ */
+export function tryAcquireIndexRebuildLock(skipIfLocked) {
+    const lockPath = indexRebuildLockPath();
+    const acquire = () => tryAcquireRunLock(lockPath, {
+        label: "index rebuild",
+        onReclaimed: (info) => {
+            warnVerbose(`[index] reclaimed a rebuild lock left by pid ${info.holderPid ?? "unknown"} ` +
+                `(${info.reason}); that process is no longer running.`);
+        },
+    });
+    if (skipIfLocked) {
+        const result = tryWithMaintenanceStartBarrier(acquire);
+        if (!result) {
+            warn("[index] maintenance barrier held; skipping (--skip-if-locked)");
+            return { state: "skipped", holder: { pid: null, startedAt: null, launcherPid: null } };
+        }
+        if (result.state === "acquired")
+            return result;
+        warn(`[index] another index run holds the lock (PID ${formatLockHolderPid(result.holder)}, started ${result.holder.startedAt}); ` +
+            "skipping (--skip-if-locked)");
+        return { state: "skipped", holder: result.holder };
+    }
+    const result = withMaintenanceStartBarrier(acquire);
+    if (result.state === "acquired")
+        return result;
+    warn(`[index] another index run is active (pid ${formatLockHolderPid(result.holder)}, started ${result.holder.startedAt}); ` +
+        "this run will contend with it — pass --skip-if-locked for scheduled runs");
+    return { state: "contended", holder: result.holder };
+}
+export function releaseIndexRebuildLock(ownership) {
+    releaseLock(ownership);
+}

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

@@ -28,9 +28,17 @@ 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";
+import { warn } from "../core/warn.js";
 import { sleepSync } from "../runtime.js";
 const ASSET_MUTATION_WAIT_MS = 100;
 const DEFAULT_ASSET_MUTATION_MAX_WAIT_MS = 10 * 60 * 1000;
+/** How often a blocked sync waiter re-announces that it is still waiting. Mirrors the async path's cadence. */
+const ASSET_MUTATION_WAIT_NOTICE_INTERVAL_MS = 15_000;
+/** TEST-ONLY. Shrinks the sync path's max-wait/notice-cadence so a test doesn't block for real minutes/seconds. */
+let syncTimingOverridesForTests;
+export function _setAssetMutationLeaseSyncTimingForTests(overrides) {
+    syncTimingOverridesForTests = overrides;
+}
 const leaseContext = new AsyncLocalStorage();
 function buildPayload(purpose) {
     return createLockPayload({
@@ -42,6 +50,26 @@ function buildPayload(purpose) {
 function delay(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
+/**
+ * Describe who currently holds `lockPath`, from `probeLock`'s own payload
+ * (the same `purpose`/`pid`/`startedAt` fields `buildPayload` writes) —
+ * never the waiting caller's own `purpose`, which names what SELF is trying
+ * to do, not who is in the way.
+ */
+function describeAssetMutationHolder(lockPath) {
+    const probe = probeLock(lockPath);
+    const rawContent = probe.state === "held" || probe.state === "stale" ? probe.rawContent : undefined;
+    if (!rawContent)
+        return "an asset write";
+    try {
+        const payload = JSON.parse(rawContent);
+        const who = payload.purpose ?? "an asset write";
+        return `${who} (pid ${payload.pid ?? "?"}, started ${payload.startedAt ?? "?"})`;
+    }
+    catch {
+        return "an asset write";
+    }
+}
 function throwIfAborted(signal) {
     if (!signal?.aborted)
         return;
@@ -142,14 +170,25 @@ export function withAssetMutationLeaseSync(purpose, run) {
     const context = inherited ?? new Set();
     const execute = () => {
         const startedAt = Date.now();
+        const maxWaitMs = syncTimingOverridesForTests?.maxWaitMs ?? DEFAULT_ASSET_MUTATION_MAX_WAIT_MS;
+        const waitNoticeIntervalMs = syncTimingOverridesForTests?.waitNoticeIntervalMs ?? ASSET_MUTATION_WAIT_NOTICE_INTERVAL_MS;
         fs.mkdirSync(path.dirname(lockPath), { recursive: true });
         let lease;
+        let lastWaitNoticeMs = 0;
         while (!lease) {
             lease = tryAcquireAssetMutationLease(lockPath, purpose);
             if (!lease) {
-                if (Date.now() - startedAt >= DEFAULT_ASSET_MUTATION_MAX_WAIT_MS) {
+                const waitedMs = Date.now() - startedAt;
+                if (waitedMs >= maxWaitMs) {
                     throw new Error(`timed out waiting for asset mutation lease for ${purpose}`);
                 }
+                // #956: the sync path used to wait up to 10 minutes with zero
+                // progress feedback. Mirror the async path's 15s onWait cadence, but
+                // actually warn by default — no caller wires onWait on this path.
+                if (waitedMs - lastWaitNoticeMs >= waitNoticeIntervalMs) {
+                    warn(`waiting for ${describeAssetMutationHolder(lockPath)} — ${Math.round(waitedMs / 1000)}s`);
+                    lastWaitNoticeMs = waitedMs;
+                }
                 sleepSync(ASSET_MUTATION_WAIT_MS);
             }
         }

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

@@ -24,8 +24,10 @@ import path from "node:path";
 import { akmAdapter } from "../core/adapter/adapters/akm-adapter.js";
 import { loadConfig } from "../core/config/config.js";
 import { isDataDirUnreadableError } from "../core/errors.js";
+import { probeLock } from "../core/file-lock.js";
 import { isPathAbsent } from "../core/path-access.js";
-import { getDbPath } from "../core/paths.js";
+import { getDbPath, getIndexRebuildLockPath } from "../core/paths.js";
+import { formatLockHolderPid } from "../core/run-lock.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";
@@ -54,10 +56,36 @@ export const WRITE_PATH_INDEX_BUSY_TIMEOUT_MS = 5_000;
  * An absent or empty index is skipped on purpose — bootstrap belongs to the
  * first read (`ensureIndex`) or an explicit `akm index`, which also cover
  * embeddings and the other passes this fast path skips.
+ *
+ * A live rebuild holding the rebuild lock is the SAME kind of skip, not a
+ * failure (#956 fix): a live `akm index` run owns bringing the index to the
+ * expected state on its own, so this call returns `true` on that skip
+ * exactly like the absent-index and empty-index cases above. Callers that
+ * gate their own success on this boolean (`acceptProposal`, `source clone`)
+ * must never fail or warn just because a concurrent rebuild is in progress.
  */
 export async function indexWrittenAssets(stashDir, filePaths, options = {}) {
     try {
         return await (async () => {
+            // #956: a live `akm index` rebuild holds index.db under one long
+            // transaction (persistDirRecords), which this fast path's own 5s
+            // busy_timeout would just contend with pointlessly. Interactive
+            // commands (remember, import, extract session assets) must never wait
+            // on it — skip the inline upsert/embedding entirely; the write itself
+            // (file + commit) has already succeeded by the time this runs, and the
+            // rebuild in progress will pick up the change on its own.
+            const rebuildProbe = probeLock(getIndexRebuildLockPath());
+            if (rebuildProbe.state === "held") {
+                // #956: name the launcher pid alongside the holder pid when known —
+                // every process listing and task log shows the launcher's pid, not
+                // the bun/node child's.
+                const holderLabel = formatLockHolderPid({
+                    pid: rebuildProbe.holderPid,
+                    launcherPid: rebuildProbe.launcherPid ?? null,
+                });
+                warn(`index rebuild in progress (pid ${holderLabel}); the next index pass will index ${filePaths.join(", ")}`);
+                return true;
+            }
             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

package/dist/indexer/indexer.js

@@ -8,7 +8,7 @@ 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 { isLoopbackEndpoint } from "../core/loopback.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";
@@ -19,6 +19,7 @@ import { isLlmFeatureEnabled } from "../llm/feature-gate.js";
 import { resolveIndexPassExecution } from "../llm/index-passes.js";
 import { preflightStructuredLlmRunner } from "../llm/structured-call.js";
 import { resolveSourcesForOrigin } from "../registry/origin-resolve.js";
+import { salvageEmbeddingsBeforeDiscard } from "../storage/repositories/embedding-salvage-repository.js";
 import { closeDatabase, openExistingDatabase, openIndexDatabase, openReadonlyExistingDatabase, } from "../storage/repositories/index-connection.js";
 import { deleteAllEntries, deleteEntriesByBundle, deleteEntriesByDirAndBundle, deleteEntriesByDirExceptRefs, deleteEntriesByIds, deleteUsageEventsByEntryIds, findEntryIdByRef, getAllEntries, getEmbeddableEntryCount, getEntryCount, getIndexedBundleIdsByDir, getIndexedDirPathsByBundleId, relinkUsageEvents, upsertEntry, } from "../storage/repositories/index-entries-repository.js";
 import { clearStaleCacheEntries, computeBodyHash, getLlmCacheEntry, } from "../storage/repositories/index-llm-cache-repository.js";
@@ -54,20 +55,17 @@ function throwIfAborted(signal) {
 export function getDefaultLlmConcurrency(llmConfig) {
     if (typeof llmConfig?.concurrency === "number")
         return llmConfig.concurrency;
-    // Local model servers stay at 1 (single loaded model; parallel requests
-    // trigger reload thrash); an absent or unparseable endpoint fails safe as
-    // local. ONE classifier decides what "local" means (`core/loopback.ts`,
-    // shared with the workflow engine's frozen concurrency default).
-    if (isLoopbackEndpoint(llmConfig?.endpoint))
-        return 1;
-    // Remote endpoints default to a modest 2-wide pool (owner ruling 2026-07-21):
-    // enough to overlap request latency without hammering rate-limited APIs.
-    // The explicit-override branch above only fires for
-    // callers that put `concurrency` on the connection themselves —
-    // `engines.<name>.concurrency` is a valid schema field but `resolveLlmEngineUse`
-    // does NOT copy it into the resolved connection, so on the enrichment path the
-    // auto-derived 1/2 is what runs (see docs/architecture/internals/indexing.md).
-    return 2;
+    // ONE classifier decides the local-vs-remote default (`core/loopback.ts`'s
+    // `defaultConcurrencyForEndpoint`), shared with the embedding pool
+    // (`resolveEmbeddingConcurrency`, `src/llm/embedders/remote.ts`) and the
+    // workflow engine's frozen concurrency default.
+    //
+    // The explicit-override branch above only fires for callers that put
+    // `concurrency` on the connection themselves — `engines.<name>.concurrency`
+    // is a valid schema field but `resolveLlmEngineUse` does NOT copy it into
+    // the resolved connection, so on the enrichment path the auto-derived 1/2
+    // is what runs (see docs/architecture/internals/indexing.md).
+    return defaultConcurrencyForEndpoint(llmConfig?.endpoint);
 }
 function sourceOwners(sources) {
     const installations = deriveInstallations([...sources]);
@@ -187,19 +185,54 @@ async function runWalkPhase(ctx) {
     });
     ctx.timing.tLlmEnd = Date.now();
 }
+/**
+ * The ONE embedding-phase implementation (#954): generate and
+ * store vectors for every entry missing one, then compute the `hasEmbeddings`
+ * fact and the semantic-search verification off the result. `akmIndex`'s own
+ * (non-deferred) run calls this from {@link runEmbeddingPhase} below; `akm
+ * bundle update`'s coordinator calls it directly on its own connection AFTER
+ * its unified update transaction commits, since the ambient-transaction drift
+ * guard (and the whole point of per-batch commit, #954) requires `db` to have
+ * no ambient transaction open.
+ */
+export async function runEmbeddingPass(params) {
+    const { db, config, onProgress, signal, reembed } = params;
+    const embeddingResult = await generateEmbeddingsForDb(db, config, onProgress, signal, undefined, {
+        forceReembed: reembed,
+    });
+    setMeta(db, "hasEmbeddings", embeddingResult.success ? "1" : "0");
+    const semanticEntryCount = getEmbeddableEntryCount(db);
+    onProgress({ phase: "finalize", message: "Verifying semantic search state." });
+    const verification = verifyIndexState(db, config, semanticEntryCount, embeddingResult);
+    onProgress({ phase: "verify", message: verification.message });
+    return { embeddingResult, verification };
+}
 /**
  * Embedding phase: generate and store vector embeddings for all unembedded
- * entries. Writes `ctx.embeddingResult` for the finalize phase.
+ * entries. Writes `ctx.embeddingResult` and `ctx.verification` for the
+ * finalize phase / caller.
  */
 async function runEmbeddingPhase(ctx) {
-    const { db, config, signal, onProgress } = ctx;
+    const { db, config, signal, onProgress, reembed, deferredUpdateTransaction } = ctx;
     throwIfAborted(signal);
+    if (deferredUpdateTransaction) {
+        // `akm bundle update`'s deferred pass (#954): the embedding
+        // phase runs AFTER the coordinator's own commit, on its own connection,
+        // via the coordinator's direct `runEmbeddingPass` call — never here,
+        // inside the borrowed transaction (the ambient-transaction drift guard
+        // would reject it anyway). `runFinalizePhase` records semantic state as
+        // "pending".
+        ctx.timing.tEmbedEnd = Date.now();
+        return;
+    }
     // Forward the signal. Without it generateEmbeddingsForDb's abort machinery was
     // inert — its throwIfAborted checks and the signal it threads into embedBatch
     // (which RemoteEmbedder passes to every fetch and LocalEmbedder honours between
     // chunks) never saw a controller. Ctrl-C and the improve budget abort could not
     // stop the embedding phase, the longest phase of an index run.
-    ctx.embeddingResult = await generateEmbeddingsForDb(db, config, onProgress, signal);
+    const { embeddingResult, verification } = await runEmbeddingPass({ db, config, onProgress, signal, reembed });
+    ctx.embeddingResult = embeddingResult;
+    ctx.verification = verification;
     ctx.timing.tEmbedEnd = Date.now();
 }
 /**
@@ -207,8 +240,8 @@ async function runEmbeddingPhase(ctx) {
  * usage events, recompute utility scores, update index metadata, and emit the
  * verify event.
  */
-async function runFinalizePhase(ctx, deferredUpdateTransaction) {
-    const { db, config, sources, sourceDirs, stashDir, signal, onProgress } = ctx;
+async function runFinalizePhase(ctx) {
+    const { db, config, sources, sourceDirs, stashDir, signal, onProgress, deferredUpdateTransaction } = ctx;
     ctx.timing.tFinalizeStart = Date.now();
     // `upsertEntry` and every canonical delete own their FTS projection. This is
     // an observation point, not a second materialization pass.
@@ -250,22 +283,37 @@ async function runFinalizePhase(ctx, deferredUpdateTransaction) {
     // An incomplete run preserves the prior freshness watermark. Advancing it
     // could make a recovered source look unchanged even though this run never
     // persisted its files.
-    const embeddingResult = ctx.embeddingResult ?? { success: false };
     if (ctx.scanComplete) {
         setMeta(db, "builtAt", new Date().toISOString());
         setMeta(db, "stashDir", stashDir);
         setMeta(db, "stashDirs", JSON.stringify(sourceDirs));
         setMeta(db, "sourceOwners", JSON.stringify(sourceOwners(sources)));
     }
-    setMeta(db, "hasEmbeddings", embeddingResult.success ? "1" : "0");
     warnIfVecMissing(db);
     const totalEntries = getEntryCount(db);
-    const semanticEntryCount = getEmbeddableEntryCount(db);
-    onProgress({ phase: "finalize", message: "Verifying semantic search state." });
-    const verification = verifyIndexState(db, config, semanticEntryCount, embeddingResult);
-    onProgress({ phase: "verify", message: verification.message });
-    // Store verification result and totalEntries on ctx for the caller to use
-    ctx.verification = verification;
+    if (deferredUpdateTransaction) {
+        // #954: the embedding phase was skipped for this borrowed
+        // transaction — record semantic state as pending, never ready, until the
+        // coordinator's own post-commit `runEmbeddingPass` call reports the
+        // truth on a fresh connection.
+        setMeta(db, "hasEmbeddings", "0");
+        const semanticEntryCount = getEmbeddableEntryCount(db);
+        const message = "Semantic index update deferred until after the source-update commit.";
+        onProgress({ phase: "verify", message });
+        ctx.verification = {
+            ok: true,
+            message,
+            semanticSearchEnabled: config.semanticSearchMode === "auto",
+            semanticSearchMode: config.semanticSearchMode,
+            semanticStatus: config.semanticSearchMode === "off" ? "disabled" : "pending",
+            embeddingProvider: getEmbeddingProvider(config.embedding),
+            entryCount: semanticEntryCount,
+            embeddingCount: getEmbeddingCount(db),
+            vecAvailable: isVecAvailable(db),
+        };
+    }
+    // Non-deferred: ctx.verification was already populated by runEmbeddingPhase
+    // (via the shared runEmbeddingPass).
     ctx.totalEntries = totalEntries;
     ctx.timing.tFinalizeEnd = Date.now();
     // suppress unused warning — sources was previously used inline
@@ -489,6 +537,7 @@ async function akmIndexReal(options) {
         const full = options?.full === true;
         const clean = options?.clean === true;
         const dryRun = options?.dryRun === true;
+        const reembed = options?.reembed === true;
         // Load config and resolve all stash sources
         const { loadConfig, mutateConfig } = await import("../core/config/config.js");
         let config = loadConfig();
@@ -513,6 +562,11 @@ async function akmIndexReal(options) {
             force: full,
             materialize: options.hydrateSources !== false,
             secrets: storeSecretResolver,
+            // Same progress channel as every other phase (#954) — a
+            // stalled clone/fetch here runs BEFORE index.db is even opened, so
+            // without this it looked identical to "no database open, nothing
+            // written".
+            onProgress: (message) => onProgress({ phase: "preflight", message }),
         });
         const sourceCacheEnd = Date.now();
         const allSourceEntries = resolveSourceEntries(stashDir, config);
@@ -548,10 +602,12 @@ async function akmIndexReal(options) {
                 sourceDirs: allSourceDirs,
                 full,
                 clean,
+                reembed,
                 stashDir,
                 onProgress,
                 signal,
                 t0,
+                deferredUpdateTransaction: options.deferredUpdateTransaction,
             });
             indexRunContext = ctx;
             onProgress({
@@ -591,7 +647,7 @@ async function akmIndexReal(options) {
             }
             cleanEnd = Date.now();
             await runEmbeddingPhase(ctx);
-            await runFinalizePhase(ctx, options.deferredUpdateTransaction);
+            await runFinalizePhase(ctx);
             // ────────────────────────────────────────────────────────────────────────
             // runFinalizePhase always populates these before returning.
             const verification = ctx.verification;
@@ -1158,6 +1214,14 @@ function persistDirRecords(db, dirRecords, doFullDelete, warnings, sourceRoots,
         // transaction so delete and re-insert are atomic — a concurrent reader
         // never observes an empty database between the two operations.
         if (fullDelete) {
+            // #955: copy every (search_text hash, embedding) pair about to be
+            // discarded wholesale into `embedding_salvage`, tagged with the
+            // fingerprint the discarded vectors were generated under, BEFORE the
+            // wipe below — inside the SAME transaction so the copy and the
+            // discard commit or roll back together. The embedding phase later in
+            // this run hands salvaged vectors back to unchanged content instead
+            // of re-embedding the whole corpus.
+            salvageEmbeddingsBeforeDiscard(db);
             // Entries and every child materialization share one deletion authority.
             // Usage events live in state.db and survive so finalize can relink them
             // to the replacement generation's row ids.