akm-cli 0.9.14 → 0.9.15-beta.1

package/dist/core/improve-result.js

@@ -3,6 +3,7 @@
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
 import { cloneExecutionJsonObject } from "../execution/json.js";
 import { isRecord } from "./common.js";
+import { IMPROVE_PROCESS_ENGINE_CAPABILITIES } from "./config/engine-semantics.js";
 const COMMON_FIELDS = [
     "schemaVersion",
     "ok",
@@ -17,6 +18,7 @@ const COMMON_FIELDS = [
     "plannedRefs",
     "plan",
     "actions",
+    "skippedProcesses",
     "distillSkipped",
     "validationFailures",
     "schemaRepairs",
@@ -47,6 +49,7 @@ const COMMON_FIELDS = [
     "sync",
     "writtenPaths",
     "terminated",
+    "usageReport",
 ];
 const V2_FIELDS = new Set([...COMMON_FIELDS, "strategy", "strategyFilteredRefs"]);
 function fail(message) {
@@ -179,6 +182,50 @@ function validateProactivePlan(value) {
         fail("plan.proactive.selected must equal plan.proactive.selectedRefs.length");
     }
 }
+/** #947 — plan.processes: one row per IMPROVE_PROCESS_ENGINE_CAPABILITIES name, plus an optional "triage.judgment" row. */
+function validateProcessRoutingRows(value) {
+    if (!Array.isArray(value))
+        fail("plan.processes must be an array");
+    const canonicalNames = Object.keys(IMPROVE_PROCESS_ENGINE_CAPABILITIES);
+    const engineKinds = new Set(["llm", "agent", "sdk"]);
+    const seen = new Set();
+    for (const row of value) {
+        if (!isRecord(row))
+            fail("plan.processes entries must be objects");
+        requireExactFields(row, new Set(["process", "enabled", "engine", "model", "engineKind", "notices", "unavailable", "eligibleRefs"]));
+        if (typeof row.process !== "string" ||
+            !(canonicalNames.includes(row.process) || row.process === "triage.judgment")) {
+            fail("plan.processes.process is invalid");
+        }
+        if (seen.has(row.process))
+            fail(`plan.processes must not repeat "${row.process}"`);
+        seen.add(row.process);
+        if (typeof row.enabled !== "boolean")
+            fail("plan.processes.enabled must be a boolean");
+        if (row.engine !== undefined && typeof row.engine !== "string")
+            fail("plan.processes.engine must be a string");
+        if (row.model !== undefined && typeof row.model !== "string")
+            fail("plan.processes.model must be a string");
+        if (row.engineKind !== undefined && (typeof row.engineKind !== "string" || !engineKinds.has(row.engineKind))) {
+            fail("plan.processes.engineKind is invalid");
+        }
+        validateLoweringNotices(row.notices);
+        if (row.unavailable !== undefined) {
+            if (!isRecord(row.unavailable))
+                fail("plan.processes.unavailable must be an object");
+            requireExactFields(row.unavailable, new Set(["configKey", "reason"]));
+            if (typeof row.unavailable.configKey !== "string" || typeof row.unavailable.reason !== "string") {
+                fail("plan.processes.unavailable must contain string configKey and reason");
+            }
+        }
+        if (row.eligibleRefs !== undefined)
+            requireCount(row, "eligibleRefs", "plan.processes entry");
+    }
+    for (const name of canonicalNames) {
+        if (!seen.has(name))
+            fail(`plan.processes must contain exactly one "${name}" row`);
+    }
+}
 function validateImprovePlan(value, dryRun, plannedRefNames) {
     if (!isRecord(value))
         fail("plan must be an object");
@@ -190,6 +237,7 @@ function validateImprovePlan(value, dryRun, plannedRefNames) {
         "limits",
         "gates",
         "effectiveRefs",
+        "processes",
         "proactive",
         "consolidation",
         "stages",
@@ -328,6 +376,7 @@ function validateImprovePlan(value, dryRun, plannedRefNames) {
     if (value.limits.totalCeiling !== undefined && value.effectiveRefs.length > value.limits.totalCeiling) {
         fail("plan.effectiveRefs cannot exceed plan.limits.totalCeiling");
     }
+    validateProcessRoutingRows(value.processes);
     if (value.proactive !== undefined)
         validateProactivePlan(value.proactive);
     validateConsolidationPlan(value.consolidation);
@@ -392,6 +441,7 @@ function validateCommon(value) {
     }
     for (const field of [
         "actions",
+        "skippedProcesses",
         "validationFailures",
         "schemaRepairs",
         "extract",
@@ -442,6 +492,7 @@ function validateCommon(value) {
         "terminated",
         "plan",
         "deadUrlCoverage",
+        "usageReport",
     ]) {
         if (value[field] !== undefined && !isRecord(value[field]))
             fail(`${field} must be an object`);

package/dist/core/loopback.js

@@ -87,3 +87,20 @@ export function isLoopbackEndpoint(endpoint) {
         return true;
     }
 }
+/**
+ * The lowest-common-denominator concurrency default for an LLM/embedding
+ * endpoint: 1 for a loopback endpoint (a local model server serves one
+ * inference at a time; concurrent requests thrash it — reload thrash, HTTP
+ * 500 "Model reloaded"), 2 for a remote one (enough to overlap request
+ * latency without hammering a rate-limited API). A leaf helper so both
+ * callers — the indexer's LLM enrichment pool (`getDefaultLlmConcurrency`,
+ * `src/indexer/indexer.ts`) and the embedding pool
+ * (`resolveEmbeddingConcurrency`, `src/llm/embedders/remote.ts`) — share one
+ * definition instead of mirroring it; `src/llm/embedders/remote.ts` cannot
+ * import `getDefaultLlmConcurrency` directly (`src/indexer/indexer.ts`
+ * already depends on this module transitively through
+ * materialize-embeddings.ts).
+ */
+export function defaultConcurrencyForEndpoint(endpoint) {
+    return isLoopbackEndpoint(endpoint) ? 1 : 2;
+}

package/dist/core/paths.js

@@ -234,6 +234,17 @@ export function getDbPath(env = process.env) {
 export function getIndexWriterLockPath() {
     return path.join(getDataDir(), "index.db.write.lock");
 }
+/**
+ * Path to the opt-in, PID-liveness-only rebuild lock an explicit `akm index`
+ * run acquires (#956). Distinct from {@link getIndexWriterLockPath}'s
+ * `index.db.write.lock`, which is the asset-mutation lease and unrelated to
+ * indexing since #872 — this lock never blocks and is never required, it
+ * only lets a scheduled/opportunistic `akm index --skip-if-locked` step
+ * aside instead of contending with a run already in progress.
+ */
+export function getIndexRebuildLockPath() {
+    return path.join(getDataDir(), "index.rebuild.lock");
+}
 export function getMaintenanceBarrierPath() {
     return path.join(getDataDir(), "maintenance.barrier.lock");
 }

package/dist/core/run-lock.js

@@ -0,0 +1,96 @@
+// 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/.
+/**
+ * PID-liveness-only run lock — the shared mechanics behind `akm improve`'s
+ * whole-run lock (`commands/improve/locks.ts`) and the index rebuild lock
+ * (`indexer/index-rebuild-lock.ts`, #956).
+ *
+ * No `staleAfterMs`: only a verifiably dead holder is ever reclaimed. This is
+ * the #872 lesson encoded at the mechanics layer so every future caller gets
+ * it for free — an age-based stale window let a live-but-wedged holder's
+ * lease survive forever from the holder's own point of view while stranding
+ * every OTHER invocation once the clock passed, which cost one real install
+ * a half-day indexing outage. SQLite's own WAL + busy_timeout + BEGIN
+ * IMMEDIATE already serialize concurrent writers at the correctness layer —
+ * this lock only ever avoids duplicate LOGICAL work or lets a caller choose
+ * to skip instead of contend.
+ *
+ * This module performs exactly one create-or-probe attempt (with the same
+ * absent-race and stale-reclaim retries `improve` established) and reports
+ * whether the caller now owns the lock or, if not, who currently holds it.
+ * It does not decide what "held" means — skip, throw, or warn-and-proceed is
+ * entirely up to the caller — and it does not serialize the attempt itself:
+ * every caller must wrap the call in
+ * `withMaintenanceStartBarrier`/`tryWithMaintenanceStartBarrier`
+ * (`core/maintenance-barrier.ts`) so two racing processes never both create
+ * the sentinel in the same window.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { ConfigError } from "./errors.js";
+import { createLockPayload, probeLock, reclaimStaleLock, tryAcquireLockSync } from "./file-lock.js";
+import { describeInaccessiblePath } from "./path-access.js";
+function parseLockPayload(rawContent) {
+    if (!rawContent)
+        return null;
+    try {
+        return JSON.parse(rawContent);
+    }
+    catch {
+        return null;
+    }
+}
+function holderOf(lock) {
+    return { pid: lock?.pid ?? null, startedAt: lock?.startedAt ?? null };
+}
+/**
+ * Attempt to acquire `lockPath`. Returns `{ state: "acquired" }` with an
+ * ownership handle for {@link releaseLock}, or `{ state: "held", holder }`
+ * naming the current holder (best-effort; `pid`/`startedAt` are `null` when
+ * the holder identity could not be determined, e.g. a release-then-reacquire
+ * race). Throws {@link ConfigError} if the sentinel exists but cannot be read
+ * (#791: a lock we cannot see may be genuinely held — never a reclaim
+ * candidate).
+ */
+export function tryAcquireRunLock(lockPath, options) {
+    fs.mkdirSync(path.dirname(lockPath), { recursive: true });
+    const lockPayload = () => createLockPayload({ startedAt: new Date().toISOString(), ...options.payloadMetadata });
+    let ownership = tryAcquireLockSync(lockPath, lockPayload());
+    if (ownership)
+        return { state: "acquired", ownership };
+    const probe = probeLock(lockPath);
+    // Race: the holder released between the failed acquire above and this
+    // probe. Retry once rather than falling through with a null-PID "held"
+    // report for a lock nobody actually holds.
+    if (probe.state === "absent") {
+        ownership = tryAcquireLockSync(lockPath, lockPayload());
+        if (ownership)
+            return { state: "acquired", ownership };
+        // Re-grabbed by another racer in this exact window — no holder detail
+        // available without re-probing (which could itself race again).
+        return { state: "held", holder: { pid: null, startedAt: null } };
+    }
+    if (probe.state === "inaccessible") {
+        throw new ConfigError(`${options.label} lock exists but is not readable: ${describeInaccessiblePath(lockPath, probe.code)}.`, "DATA_DIR_UNREADABLE");
+    }
+    const lock = parseLockPayload(probe.rawContent);
+    if (probe.state === "stale") {
+        if (!reclaimStaleLock(lockPath, probe)) {
+            return { state: "held", holder: holderOf(lock) };
+        }
+        options.onReclaimed?.({
+            holderPid: lock?.pid ?? probe.holderPid ?? null,
+            lockedAt: lock?.startedAt ?? null,
+            ageMs: probe.ageMs ?? null,
+            reason: probe.reason === "pid_dead" ? "pid_not_alive" : probe.reason,
+        });
+        ownership = tryAcquireLockSync(lockPath, lockPayload());
+        if (ownership)
+            return { state: "acquired", ownership };
+        // Acquired by another racer during stale recovery.
+        return { state: "held", holder: holderOf(lock) };
+    }
+    // probe.state === "held"
+    return { state: "held", holder: holderOf(lock) };
+}

package/dist/core/sensitive-marker-path.js

@@ -0,0 +1,19 @@
+// 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/.
+/**
+ * Path to the sibling marker file that suppresses listing for a sensitive
+ * env/secret asset. Deliberately its own leaf module (no imports) rather than
+ * living on `core/env-secret-ref.ts` (#950 originally put it there): that
+ * module transitively imports the source providers via
+ * `indexer/search/search-source`, and `commands/env/env.ts` is imported back
+ * from `core/adapter/adapters/akm-metadata.ts` (for `scanEnvKeyNames`) — so an
+ * `env.ts` import of the heavier module closes a real cycle through the
+ * adapter registry (`core/adapter/adapters/index.ts`'s `BUILTIN_ADAPTERS`
+ * construction sees `akmAdapter` still TDZ). Keeping this helper leaf-only
+ * lets `commands/env/env.ts` and `core/env-secret-ref.ts` both depend on it
+ * without either pulling the other's heavier graph.
+ */
+export function sensitiveMarkerPath(assetPath, type) {
+    return type === "env" ? assetPath.replace(/\.env$/, ".sensitive") : `${assetPath}.sensitive`;
+}

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 { 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 } };
+        }
+        if (result.state === "acquired")
+            return result;
+        warn(`[index] another index run holds the lock (PID ${result.holder.pid}, 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 ${result.holder.pid}, 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,9 @@ 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 { 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 +55,29 @@ 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") {
+                warn(`index rebuild in progress (pid ${rebuildProbe.holderPid}); 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