akm-cli 0.9.16-alpha.1 → 0.9.16

package/dist/core/errors.js

@@ -18,7 +18,6 @@ const CONFIG_HINTS = {
     UNKNOWN_IMPROVE_STRATEGY: "Pass one of the listed strategy names to `--strategy`, or define it under `improve.strategies`. Names are case-sensitive.",
     EXECUTION_NOT_AUTHORIZED: "Change the selected tools or update the machine/user execution policy, then retry.",
     SECRET_REFERENCE_UNRESOLVED: "Check the secret exists (`akm secret list`) and the name after `secret://` matches, or run `akm secret set <name> <value>` to store it.",
-    EMBEDDING_VEC_UNAVAILABLE: "Install sqlite-vec for unit-level semantic search, or rely on lexical search until it is available.",
 };
 // Code-review finding: COMPOSITION_INVALID covers several unrelated causes
 // (a rejected with:, a multi-job source, a composition cycle/depth/size
@@ -83,10 +82,8 @@ const USAGE_HINTS = {
 const TRANSIENT_HINTS = {
     RUN_LEASE_HELD: "Wait for the named engine invocation to finish or for the lease to expire, then retry. `akm workflow status <id>` shows the current lease.",
     STATE_DB_CONTENDED: "Another akm process is writing state.db right now. Wait a few seconds and retry; commands that support --skip-if-locked can skip instead of failing.",
-    INDEX_DB_CONTENDED: "Another akm process is writing index.db right now. Wait a few seconds and retry — index runs take no rebuild " +
-        "lock, so this clears quickly; a scheduled run left alone will simply run again next time.",
-    MAINTENANCE_BARRIER_BUSY: "Another akm process is registering a lock or lease right now. Retry shortly, or pass --skip-if-locked on " +
-        "scheduled improve runs to skip gracefully instead — workflow run does not treat this code as skippable.",
+    INDEX_DB_CONTENDED: "Another akm process is writing index.db; retry shortly, or pass --skip-if-locked on scheduled runs.",
+    MAINTENANCE_BARRIER_BUSY: "Another akm process is registering a lock or lease right now. Retry shortly, or pass --skip-if-locked on scheduled index/improve/workflow runs.",
     IMPROVE_LOCK_HELD: "Another akm improve run holds the whole-run lock right now. Wait for it to finish and retry, or pass --skip-if-locked on scheduled runs.",
 };
 /** Default hint for each NotFoundError code. */

package/dist/core/maintenance-barrier.js

@@ -27,20 +27,18 @@ const heldBarrierContext = new AsyncLocalStorage();
 const MAINTENANCE_BARRIER_STALE_AFTER_MS = 5 * 60 * 1000;
 /**
  * The barrier normally holds for one lock-file write — sub-millisecond on
- * any real filesystem. Two akm processes racing to register a lock/lease/
- * activity in the very same instant (e.g. two `akm index` runs a scheduler
- * launched back to back, both opening canonical state.db) can still collide
- * on it; retrying briefly resolves that ordinary case instead of failing a
- * legitimate concurrent invocation outright
- * (field follow-up to #956, G1). Bounded short so a genuinely wedged holder
- * still surfaces the busy error promptly rather than making a losing
- * process hang — comfortably above the barrier's normal hold time, well
- * below a length that would make this feel like the blocking lock #872
- * removed. Never applies to whatever lock/lease/activity is registered
- * after the barrier releases — that thing's own held/skip/throw/wait
- * policy belongs to its caller, not to the barrier (#872).
+ * any real filesystem. Two akm processes racing to register a lock in the
+ * very same instant (e.g. two `akm index` runs a scheduler launched back to
+ * back) can still collide on it; retrying briefly resolves that ordinary
+ * case instead of failing a legitimate concurrent invocation outright
+ * (field follow-up to #956, G1). Five seconds matches the async and
+ * synchronous-activity registration paths below and tolerates a holder being
+ * descheduled under heavy process-shard load; the barrier's normal hold time
+ * remains sub-millisecond. The bound still surfaces a genuinely wedged holder
+ * promptly and never applies to the rebuild lock itself, which stays
+ * non-blocking (#872).
  */
-const MAINTENANCE_BARRIER_BUSY_RETRY_BOUND_MS = 1_500;
+const MAINTENANCE_BARRIER_BUSY_RETRY_BOUND_MS = 5_000;
 let busyRetryBoundMsForTests;
 /** Test-only override for {@link MAINTENANCE_BARRIER_BUSY_RETRY_BOUND_MS}, so a unit test can exercise the
  * exhausted-retry throw without a real ~1.5s wait. Restored via tests/_helpers/seams.ts's resetAllSeams(). */

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

@@ -3,11 +3,8 @@
 // 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`). Originally also backed the
- * index rebuild lock (`indexer/index-rebuild-lock.ts`, #956); index-redesign
- * deleted that consumer (every index write is now a short, idempotent,
- * content-addressed transaction, so there is no rebuild to serialize), and
- * `improve`'s lock is this module's only caller today.
+ * 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

package/dist/core/state/migrations.js

@@ -1200,33 +1200,12 @@ export function getStateMigrationSafety(migrationId) {
  * Delegates to the shared SQLite migration engine; state.db has no
  * pre-versioning bootstrap step, so no `bootstrap` hook is passed.
  *
- * `freshDatabase` is the one exception to "single transaction per migration":
- * the entire registry is locked through the final migration and applied as
- * ONE transaction (mirroring the existing-unversioned prefix lock below).
- * Two akm processes can race to create the same brand-new state.db
- * (`openStateDatabase`'s file-reservation only decides who creates the file,
- * not who finishes initializing it first); with per-migration commits, the
- * loser could open its own connection between two of the winner's commits,
- * see a real-but-incomplete ledger, and — correctly believing this is an
- * ordinary existing database needing to catch up on pending migrations —
- * refuse historical-destructive migration 018 with the same message a
- * genuine legacy database gets. Applying every migration for a fresh
- * database atomically removes that partially-migrated state from view
- * entirely: a concurrent opener now only ever observes "nothing committed
- * yet" (treated as fresh) or "fully current" (nothing left to apply), never
- * the in-between. Safe to lose on a crash mid-bootstrap: a fresh database
- * has no prior data to preserve, so rolling back to nothing and letting the
- * next open retry from scratch is strictly fine.
- *
  * Called automatically by `openStateDatabase()`.
  */
 export function runMigrations(db, options) {
     const initialMigration = STATE_MIGRATIONS[0];
     if (!initialMigration)
         throw new Error("State migration registry has no initial migration.");
-    const finalMigration = STATE_MIGRATIONS[STATE_MIGRATIONS.length - 1];
-    if (!finalMigration)
-        throw new Error("State migration registry has no final migration.");
     let existingUnversionedSnapshotPrepared = false;
     const prepareExistingUnversionedState = (lockedDb) => {
         if (existingUnversionedSnapshotPrepared)
@@ -1249,11 +1228,7 @@ export function runMigrations(db, options) {
         existingUnversionedSnapshotPrepared = true;
     };
     runSqliteMigrations(db, STATE_MIGRATIONS, {
-        lockInitialMigrationPrefixThrough: options?.existingUnversionedDatabase
-            ? "002-task-history-per-run"
-            : options?.freshDatabase
-                ? finalMigration.id
-                : undefined,
+        lockInitialMigrationPrefixThrough: options?.existingUnversionedDatabase ? "002-task-history-per-run" : undefined,
         beforeLedgerInitializationLocked(lockedDb) {
             if (options?.freshDatabase)
                 return;

package/dist/core/state-db.js

@@ -442,24 +442,10 @@ export function openStateDatabase(dbPath, options) {
             });
             try {
                 preflight.exec("PRAGMA busy_timeout = 30000");
-                // Both reads below must observe ONE WAL snapshot. Each is its own
-                // statement, and without an explicit transaction SQLite auto-commits
-                // each separately, so they can see two different snapshots. A sibling
-                // process's fresh bootstrap is now one all-or-nothing transaction, so
-                // a commit landing between the two reads showed an empty ledger to the
-                // first and the sibling's freshly created tables to the second — the
-                // signature of a genuine legacy unversioned database, which this
-                // preflight then refused. Pinned to one snapshot, either nothing the
-                // sibling did is visible (empty ledger AND no tables, correctly fresh)
-                // or all of it is (a current ledger, so the refusal is never reached).
-                // A real legacy database, racing no one, reads exactly as before.
-                const { ledger, hasNoOtherTables } = preflight.transaction(() => ({
-                    ledger: assertMigrationLedger(preflight, STATE_MIGRATIONS),
-                    hasNoOtherTables: unversionedDatabaseHasNoTables(preflight),
-                }))();
+                const ledger = assertMigrationLedger(preflight, STATE_MIGRATIONS);
                 warnNewerStateLedger(ledger);
                 existingUnversionedDatabase = ledger.migrationIds.length === 0;
-                if (existingUnversionedDatabase && hasNoOtherTables) {
+                if (existingUnversionedDatabase && unversionedDatabaseHasNoTables(preflight)) {
                     existingUnversionedDatabase = false;
                     treatUnversionedAsFresh = true;
                 }
@@ -553,21 +539,7 @@ export function openStateDatabase(dbPath, options) {
         if (freshReservation)
             closeFileIdentity(freshReservation);
         releaseActivity?.();
-        // The migration engine's own writer-lock retry (sqlite-migrations.ts's
-        // `withImmediateWriteLock`, used by every migration this open can run,
-        // including a from-empty first open) throws the raw driver error after
-        // its own retry budget, not a `TransientError` — only
-        // `beginImmediateTransaction` below does that reclassification, and nothing
-        // upstream of it re-wraps a raw SQLITE_BUSY/LOCKED that surfaces from
-        // deeper in the open/migrate sequence (field follow-up: a from-empty
-        // first open racing a concurrent opener can still hit this under load).
-        // Reclassify uniformly here so the contract this function promises --
-        // contention is reported as `STATE_DB_CONTENDED` (exit 75), never a raw
-        // driver message (exit 70) -- holds regardless of which internal step
-        // the contention was observed at. Anything not contention-shaped
-        // (a genuine legacy-database refusal, corruption, a real schema error)
-        // rethrows exactly as raised.
-        throwBeginFailure(error, "state");
+        throw error;
     }
 }
 /**
@@ -718,33 +690,6 @@ function sleepSyncMs(ms) {
         return;
     sleepSync(ms);
 }
-/**
- * Reclassify an exhausted-retry BEGIN failure that is still contention-shaped
- * (#948) into a `TransientError`, 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.
- *
- * `dbKind` (field follow-up to #956) picks the reported identity: `"state"`
- * (default, unchanged text) yields `STATE_DB_CONTENDED`; `"index"` yields
- * `INDEX_DB_CONTENDED` with index.db's own message, mirroring
- * `reclassifyIndexDbContention`'s text (`src/indexer/indexer.ts`) so a caller
- * that reaches this helper directly and one that only reclassifies a raw
- * driver error report the same thing.
- */
-function throwBeginFailure(err, dbKind) {
-    if (isSqliteContentionError(err)) {
-        const contended = dbKind === "index"
-            ? new TransientError("akm's index database is busy (another akm process is writing it); retry shortly.", "INDEX_DB_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;
-}
 /**
  * Open, but deliberately do not finish, an immediate transaction.
  *
@@ -754,7 +699,26 @@ function throwBeginFailure(err, dbKind) {
  * publication have all succeeded. The caller that asked for this split phase
  * owns the matching COMMIT/ROLLBACK.
  */
-export function beginImmediateTransaction(db, dbKind = "state") {
+/**
+ * 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");
     }
@@ -781,12 +745,12 @@ export function beginImmediateTransaction(db, dbKind = "state") {
                 sleepSyncMs(2 ** (attempt - 1));
                 continue;
             }
-            throwBeginFailure(err, dbKind);
+            throwBeginFailure(err);
         }
     }
-    throwBeginFailure(lastBeginErr, dbKind);
+    throwBeginFailure(lastBeginErr);
 }
-export function withImmediateTransaction(db, fn, dbKind = "state") {
+export function withImmediateTransaction(db, fn) {
     // Re-entrancy guard (issue #686): if a transaction is already open on this
     // connection (e.g. a nested withImmediateTransaction call inside an outer
     // frame's fn), join it — run fn directly with no BEGIN/COMMIT/ROLLBACK of
@@ -797,7 +761,7 @@ export function withImmediateTransaction(db, fn, dbKind = "state") {
     if (db.inTransaction) {
         return fn();
     }
-    beginImmediateTransaction(db, dbKind);
+    beginImmediateTransaction(db);
     try {
         const result = fn();
         if (!db.inTransaction) {

package/dist/core/type-presentation.js

@@ -105,7 +105,7 @@ export const TYPE_PRESENTATION = {
     task: {
         label: "Task",
         renderer: "task-yaml",
-        action: (ref) => `akm show ${ref} -> inspect; akm task run <id> -> run now; edit the file + akm task sync -> unschedule`,
+        action: (ref) => `akm show ${ref} -> inspect; akm task run <id> -> run now; akm task enable|disable ${ref} -> change local scheduling`,
         fragmentRef: false,
     },
     session: {

package/dist/core/write-source.js

@@ -34,7 +34,7 @@ import { assetPathForName, stashDirFor } from "./asset/asset-placement.js";
 import { conceptIdFromTypeName, displayRef } from "./asset/resolve-ref.js";
 import { deriveBundleId } from "./bundle-id.js";
 import { existingFileMode, isWithin, resolveStashDir, writeFileAtomic } from "./common.js";
-import { bundleContentRoot, resolveConfiguredSources } from "./config/config.js";
+import { bundleKeyForContentRoot, resolveActiveConfiguredSources, resolveConfiguredSources } from "./config/config.js";
 import { ConfigError, UsageError } from "./errors.js";
 import { sanitizeCommitMessage } from "./git-message.js";
 import { warn, warnOnce } from "./warn.js";
@@ -897,12 +897,16 @@ function gitTargetNotMaterialized(target, contentRoot) {
  * see plan §6 decision 3 for the rationale.
  */
 export function resolveWriteTarget(akmConfig, explicitTarget, options = {}) {
-    const configuredSources = resolveConfiguredSources(akmConfig);
+    const allConfiguredSources = resolveConfiguredSources(akmConfig);
+    const configuredSources = resolveActiveConfiguredSources(akmConfig);
     const requireWritable = options.requireWritable !== false;
     // 1. Explicit --target wins.
     if (explicitTarget) {
         const match = configuredSources.find((s) => s.name === explicitTarget);
         if (!match) {
+            if (allConfiguredSources.some((source) => source.name === explicitTarget)) {
+                throw new UsageError(`Bundle "${explicitTarget}" is disabled.`, "INVALID_FLAG_VALUE");
+            }
             throw new UsageError(`--target must reference a source name from your config. No source named "${explicitTarget}" is configured. Run \`akm bundle list\` to see available sources.`, "INVALID_FLAG_VALUE");
         }
         // Up-front writable check so an explicit --target fails fast with a
@@ -939,15 +943,13 @@ export function resolveWriteTarget(akmConfig, explicitTarget, options = {}) {
 }
 /** Resolve the implicit working stash without consulting `defaultWriteTarget`. */
 export function resolveWorkingStashTarget(akmConfig, options = {}) {
-    const configuredSources = resolveConfiguredSources(akmConfig);
+    const allConfiguredSources = resolveConfiguredSources(akmConfig);
+    const configuredSources = resolveActiveConfiguredSources(akmConfig);
     const requireWritable = options.requireWritable !== false;
     if (process.env.AKM_BUNDLE_DIR?.trim()) {
         const stashDir = resolveStashDir();
-        const resolvedStashDir = path.resolve(stashDir);
-        const configured = configuredSources.find((source) => {
-            const sourcePath = source.source.type === "filesystem" ? source.source.path : undefined;
-            return sourcePath !== undefined && bundleContentRoot(sourcePath, source.componentRoot) === resolvedStashDir;
-        });
+        const configuredBundleId = bundleKeyForContentRoot(akmConfig, stashDir);
+        const configured = configuredSources.find((source) => source.name === configuredBundleId);
         if (configured) {
             const target = adaptConfiguredSource(configured);
             if (requireWritable && !resolveWritable(target.config)) {
@@ -955,6 +957,9 @@ export function resolveWorkingStashTarget(akmConfig, options = {}) {
             }
             return { ...target, selector: undefined };
         }
+        if (allConfiguredSources.some((source) => source.name === configuredBundleId)) {
+            throw new ConfigError("The AKM_BUNDLE_DIR source is disabled in config.", "INVALID_CONFIG_FILE");
+        }
         const bundleId = deriveBundleId(undefined, stashDir, new Set(Object.keys(akmConfig.bundles ?? {})));
         return {
             source: { kind: "filesystem", name: bundleId, path: stashDir, adapterId: detectAdapterId(stashDir) },

package/dist/indexer/bundle-identity-guard.js

@@ -28,6 +28,7 @@
  * comparison over a non-empty index so the steady-state cost is a boolean check.
  */
 import fs from "node:fs";
+import path from "node:path";
 import { loadConfig } from "../core/config/config.js";
 import { rethrowIfTestIsolationError } from "../core/errors.js";
 import { getDbPath } from "../core/paths.js";
@@ -39,8 +40,8 @@ let guardSettled = false;
 export function resetBundleIdentityGuardForTests() {
     guardSettled = false;
 }
-/** Distinct non-empty `bundle_id` prefixes persisted in the index, or `undefined` when unreadable. */
-function indexBundlePrefixes(dbPath) {
+/** Bundle/path ownership persisted in the index, or `undefined` when unreadable. */
+function indexedBundlePaths(dbPath) {
     if (!fs.existsSync(dbPath))
         return undefined;
     let db;
@@ -51,8 +52,9 @@ function indexBundlePrefixes(dbPath) {
         if (!isCanonicalIndexGeneration(db))
             return undefined;
         return db
-            .prepare("SELECT DISTINCT bundle_id AS b FROM entries WHERE bundle_id IS NOT NULL AND bundle_id != ''")
-            .all().map((row) => row.b);
+            .prepare("SELECT DISTINCT bundle_id AS bundleId, file_path AS filePath FROM entries " +
+            "WHERE bundle_id IS NOT NULL AND bundle_id != '' AND file_path IS NOT NULL AND file_path != ''")
+            .all();
     }
     catch (error) {
         rethrowIfTestIsolationError(error);
@@ -80,20 +82,55 @@ export function warnOnBundleRenameDrift(config = loadConfig()) {
     const configIds = new Set(Object.keys(bundles));
     if (configIds.size === 0)
         return;
-    const indexIds = indexBundlePrefixes(getDbPath());
-    if (indexIds === undefined || indexIds.length === 0)
+    const indexedPaths = indexedBundlePaths(getDbPath());
+    if (indexedPaths === undefined || indexedPaths.length === 0)
         return; // nothing indexed yet — re-check later
     // A real comparison happened over a populated index: settle so the steady
     // state is one boolean check.
     guardSettled = true;
+    const indexIds = [...new Set(indexedPaths.map((row) => row.bundleId))];
     const indexIdSet = new Set(indexIds);
     const configuredMissingFromIndex = [...configIds].filter((id) => !indexIdSet.has(id));
     const indexedNotConfigured = indexIds.filter((id) => !configIds.has(id));
     if (configuredMissingFromIndex.length === 0 || indexedNotConfigured.length === 0)
         return;
+    // A mismatched id set alone is also the ordinary signature of adding a new
+    // bundle while stale rows from a removed bundle still exist. Treat it as a
+    // hand rename only when the old rows physically live beneath the newly named
+    // filesystem bundle's root. This keeps the guard useful without warning on
+    // unrelated new bundles (#971).
+    const renamedConfiguredIds = configuredMissingFromIndex.filter((configuredId) => {
+        const configuredPath = config.bundles?.[configuredId]?.path;
+        if (typeof configuredPath !== "string")
+            return false;
+        const root = path.resolve(configuredPath);
+        return indexedPaths.some((row) => {
+            if (!indexedNotConfigured.includes(row.bundleId))
+                return false;
+            const relative = path.relative(root, path.resolve(row.filePath));
+            return relative !== "" && !relative.startsWith("..") && !path.isAbsolute(relative);
+        });
+    });
+    if (renamedConfiguredIds.length === 0)
+        return;
+    const renamedOldIds = [
+        ...new Set(indexedPaths
+            .filter((row) => {
+            if (!indexedNotConfigured.includes(row.bundleId))
+                return false;
+            return renamedConfiguredIds.some((configuredId) => {
+                const configuredPath = config.bundles?.[configuredId]?.path;
+                if (typeof configuredPath !== "string")
+                    return false;
+                const relative = path.relative(path.resolve(configuredPath), path.resolve(row.filePath));
+                return relative !== "" && !relative.startsWith("..") && !path.isAbsolute(relative);
+            });
+        })
+            .map((row) => row.bundleId)),
+    ];
     warn("WARNING: bundle identity drift detected. " +
-        `Configured bundle(s) with no indexed content: ${configuredMissingFromIndex.map((id) => `"${id}"`).join(", ")}; ` +
-        `indexed content under unconfigured bundle id(s): ${indexedNotConfigured.map((id) => `"${id}"`).join(", ")}. ` +
+        `Configured bundle(s) with no indexed content: ${renamedConfiguredIds.map((id) => `"${id}"`).join(", ")}; ` +
+        `indexed content under unconfigured bundle id(s): ${renamedOldIds.map((id) => `"${id}"`).join(", ")}. ` +
         "This is the signature of a hand-renamed bundle id (spec §11.5). AKM will NOT silently re-mint fresh state " +
         "under the new id. There is no rekey command in 0.9.0: either restore the previous bundle id in config.json " +
         "to reattach the existing rows, or keep the new id and run `akm index --full` to re-mint under it, accepting " +

package/dist/indexer/ensure-index.js

@@ -193,11 +193,6 @@ function indexCanServeStash(stashDir) {
 }
 async function runInlineReindex(stashDir, options = {}) {
     const { akmIndex } = await import("./indexer.js");
-    // The embedding drain on this implicit path is bounded (see
-    // `IndexOptions.implicit`, src/indexer/indexer.ts): a read command's
-    // inline bootstrap embeds one provider request's worth of units and
-    // leaves the rest of the durable queue to a later drain, so a first
-    // `search`/`show` against a fresh index never blocks on the whole corpus.
     await akmIndex({
         stashDir,
         implicit: true,

package/dist/indexer/index-db-contention.js

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

package/dist/indexer/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);
+}