akm-cli 0.9.15-beta.1 → 0.9.15-beta.3

package/dist/storage/repositories/embedding-salvage-repository.js

@@ -0,0 +1,184 @@
+// 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/.
+/**
+ * `index.db` embedding salvage (#955) — a transient, self-emptying table
+ * that lets a full rebuild or an index-generation bump reuse vectors instead
+ * of re-embedding a corpus whose content did not change.
+ *
+ * Zero steady-state cost by design: this is NOT a second embedding cache.
+ * Rows are copied aside only at the moment they would otherwise be discarded
+ * wholesale — a full-index wipe (`persistDirRecords`) or a generation bump
+ * (`rebuildIncompatibleIndexGeneration`) — and are consumed by the very next
+ * embedding pass (`generateEmbeddingsForDb`). A pass that completes without
+ * abort or circuit-break purges whatever is left; an interrupted pass leaves
+ * the table for the next attempt to pick up.
+ *
+ * Reuse is keyed on `sha256(search_text)` plus the fingerprint the vector was
+ * generated under — a fingerprint mismatch or a single-byte content change
+ * both correctly fall through to a real provider call. `content_hash` is the
+ * PRIMARY KEY (not `(content_hash, fingerprint)`) so relabeling a whole
+ * generation's fingerprint after a canary "keep" verdict is one UPDATE, and a
+ * hash colliding across two discards simply keeps the most recent copy —
+ * salvage is a best-effort optimization, not a durable multi-generation
+ * archive.
+ */
+import { createHash } from "node:crypto";
+import { blobToEmbedding } from "./embeddings-repository.js";
+import { getMeta } from "./index-meta-repository.js";
+import { SQLITE_CHUNK_SIZE } from "./index-sql.js";
+/**
+ * Create the salvage table. Additive-only DDL: it carries no bearing on the
+ * `entries` generation fingerprint (`hasCanonicalEntrySchema`), so adding it
+ * does not require an index-generation bump.
+ */
+export function ensureEmbeddingSalvageTable(db) {
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS embedding_salvage (
+      content_hash TEXT PRIMARY KEY,
+      fingerprint  TEXT NOT NULL,
+      embedding    BLOB NOT NULL,
+      salvaged_at  TEXT NOT NULL
+    );
+  `);
+}
+/** The one hash function salvage writes and reuse lookups must agree on. */
+export function hashEmbeddableText(searchText) {
+    return createHash("sha256").update(searchText, "utf8").digest("hex");
+}
+function tableExists(db, name) {
+    return db.prepare("SELECT 1 FROM sqlite_master WHERE type='table' AND name=?").get(name) != null;
+}
+function tableHasColumn(db, table, column) {
+    const columns = db.prepare(`PRAGMA table_info(${table})`).all();
+    return columns.some((c) => c.name === column);
+}
+/**
+ * Copy every (hash of search_text, embedding) pair about to be discarded
+ * wholesale into `embedding_salvage`, tagged with the `embeddingFingerprint`
+ * the discarded vectors were generated under. The caller MUST run this
+ * inside the same transaction as the discard that follows it, so the copy
+ * and the delete commit or roll back together.
+ *
+ * Streams `entries JOIN embeddings` in id-ordered pages of
+ * {@link SQLITE_CHUNK_SIZE} instead of loading every row into memory before
+ * hashing anything — a full rebuild of a large stash otherwise held the
+ * entire corpus's search text and vectors in memory at once just to copy
+ * them aside (#955, field-report follow-up).
+ *
+ * A no-op (returns 0) when there is no stored `embeddingFingerprint` to tag
+ * rows with (nothing was ever verified against a provider, so there is
+ * nothing worth reusing later) or the generation being discarded predates
+ * the `entries.search_text` column or has no `embeddings` table at all — an
+ * older generation than that has nothing this can safely read.
+ */
+export function salvageEmbeddingsBeforeDiscard(db) {
+    const fingerprint = getMeta(db, "embeddingFingerprint");
+    if (!fingerprint)
+        return 0;
+    if (!tableExists(db, "entries") || !tableExists(db, "embeddings"))
+        return 0;
+    if (!tableHasColumn(db, "entries", "search_text"))
+        return 0;
+    const page = db.prepare("SELECT e.id AS id, e.search_text AS searchText, em.embedding AS embedding " +
+        "FROM entries e JOIN embeddings em ON em.id = e.id WHERE e.id > ? ORDER BY e.id LIMIT ?");
+    const insert = db.prepare("INSERT OR REPLACE INTO embedding_salvage (content_hash, fingerprint, embedding, salvaged_at) VALUES (?, ?, ?, ?)");
+    const salvagedAt = new Date().toISOString();
+    let lastId = 0;
+    let total = 0;
+    for (;;) {
+        const rows = page.all(lastId, SQLITE_CHUNK_SIZE);
+        if (rows.length === 0)
+            break;
+        for (const row of rows) {
+            insert.run(hashEmbeddableText(row.searchText), fingerprint, row.embedding, salvagedAt);
+        }
+        total += rows.length;
+        lastId = rows[rows.length - 1]?.id ?? lastId;
+        if (rows.length < SQLITE_CHUNK_SIZE)
+            break;
+    }
+    return total;
+}
+/**
+ * Remove every salvage row. Called after an embedding pass completes without
+ * abort or circuit-break (the salvaged generation has now either been reused
+ * or superseded), and by `--reembed` / a canary "rebuild" verdict (the
+ * salvaged vectors belong to a different model and are never reusable).
+ */
+export function purgeEmbeddingSalvage(db) {
+    db.exec("DELETE FROM embedding_salvage");
+}
+/**
+ * A canary "keep" verdict means the model did not actually change — only its
+ * fingerprint STRING did (e.g. a gateway rename). Salvage rows tagged with
+ * the old string are still valid vectors; rewrite them to the new string so
+ * they remain reusable instead of silently going stale.
+ */
+export function relabelEmbeddingSalvageFingerprint(db, fromFingerprint, toFingerprint) {
+    db.prepare("UPDATE embedding_salvage SET fingerprint = ? WHERE fingerprint = ?").run(toFingerprint, fromFingerprint);
+}
+/**
+ * Reuse salvaged vectors for `entries` whose `searchText` hash matches a
+ * salvage row tagged with the CURRENT `fingerprint` — never across
+ * fingerprints, and never when `search_text` differs by even one byte (the
+ * hash is exact-match only, by design). Matches are written via
+ * `writeReused` in chunks of {@link SQLITE_CHUNK_SIZE}, each its own
+ * transaction, mirroring the main pass's per-batch commit (#955) so an
+ * interruption partway through the reuse step keeps whatever already wrote.
+ *
+ * The steady state of every ordinary run is an EMPTY salvage table (nothing
+ * was just discarded), so this checks that first with one indexed lookup —
+ * `SELECT 1 ... LIMIT 1` — before hashing a single pending entry. Hashing
+ * every entry up front to look up a table that is empty 100% of the time
+ * outside a rebuild was pure wasted work on the common path (#955,
+ * field-report follow-up).
+ */
+export function reuseSalvagedEmbeddings(db, entries, fingerprint, writeReused) {
+    if (entries.length === 0)
+        return { reusedCount: 0, remaining: [] };
+    const anySalvageForFingerprint = db
+        .prepare("SELECT 1 FROM embedding_salvage WHERE fingerprint = ? LIMIT 1")
+        .get(fingerprint);
+    if (!anySalvageForFingerprint)
+        return { reusedCount: 0, remaining: [...entries] };
+    const hashes = entries.map((entry) => hashEmbeddableText(entry.searchText));
+    const salvageByHash = new Map();
+    const uniqueHashes = [...new Set(hashes)];
+    for (let offset = 0; offset < uniqueHashes.length; offset += SQLITE_CHUNK_SIZE) {
+        const chunk = uniqueHashes.slice(offset, offset + SQLITE_CHUNK_SIZE);
+        const placeholders = chunk.map(() => "?").join(",");
+        const rows = db
+            .prepare(`SELECT content_hash AS contentHash, embedding FROM embedding_salvage WHERE fingerprint = ? AND content_hash IN (${placeholders})`)
+            .all(fingerprint, ...chunk);
+        for (const row of rows)
+            salvageByHash.set(row.contentHash, row.embedding);
+    }
+    if (salvageByHash.size === 0)
+        return { reusedCount: 0, remaining: [...entries] };
+    let reusedCount = 0;
+    const remaining = [];
+    for (let offset = 0; offset < entries.length; offset += SQLITE_CHUNK_SIZE) {
+        const end = Math.min(offset + SQLITE_CHUNK_SIZE, entries.length);
+        const chunkMatches = [];
+        for (let i = offset; i < end; i++) {
+            const entry = entries[i];
+            const blob = salvageByHash.get(hashes[i]);
+            if (blob)
+                chunkMatches.push({ entry, blob });
+            else
+                remaining.push(entry);
+        }
+        if (chunkMatches.length === 0)
+            continue;
+        db.transaction(() => {
+            for (const { entry, blob } of chunkMatches) {
+                if (writeReused(entry, blobToEmbedding(blob)))
+                    reusedCount++;
+                else
+                    remaining.push(entry);
+            }
+        })();
+    }
+    return { reusedCount, remaining };
+}

package/dist/storage/repositories/index-schema.js

@@ -12,6 +12,7 @@
  */
 import { ConfigError } from "../../core/errors.js";
 import { warn } from "../../core/warn.js";
+import { ensureEmbeddingSalvageTable, salvageEmbeddingsBeforeDiscard } from "./embedding-salvage-repository.js";
 import { CANONICAL_ENTRY_SCHEMA_SQL, CANONICAL_INDEX_DB_VERSION, classifyIndexGeneration, isCanonicalIndexGeneration, } from "./index-entry-schema.js";
 import { getMeta, setMeta } from "./index-meta-repository.js";
 import { isVecAvailable, purgeEmbeddings } from "./index-vec-repository.js";
@@ -196,6 +197,13 @@ function rebuildIncompatibleIndexGeneration(db) {
         vecResetPending = true;
     }
     db.transaction(() => {
+        // #955: copy embeddings about to be discarded wholesale into
+        // `embedding_salvage` (keyed by content hash + the fingerprint they were
+        // generated under) BEFORE dropping `embeddings`, in the same transaction
+        // as the drop, so the copy and the discard commit or roll back together.
+        // The next embedding pass hands salvaged vectors back to unchanged
+        // content instead of re-embedding the whole corpus after this bump.
+        salvageEmbeddingsBeforeDiscard(db);
         db.exec("DROP TABLE IF EXISTS graph_file_relations");
         db.exec("DROP TABLE IF EXISTS graph_file_entities");
         db.exec("DROP TABLE IF EXISTS graph_files");
@@ -212,6 +220,9 @@ function rebuildIncompatibleIndexGeneration(db) {
         db.exec("DROP TABLE IF EXISTS index_dir_state");
         db.exec("DROP TABLE IF EXISTS entries");
         db.exec("DELETE FROM index_meta");
+        // embedding_salvage is deliberately absent from the drop list above —
+        // it is the ONE piece of derived state a generation rebuild must not
+        // discard.
     })();
     if (vecResetPending)
         setMeta(db, "vecResetPending", "1");
@@ -224,6 +235,11 @@ export function ensureSchema(db, embeddingDim) {
       value TEXT NOT NULL
     );
   `);
+    // #955: created before the generation-rebuild check below so a discard
+    // has somewhere to copy vectors to. Additive-only — it carries no bearing
+    // on the `entries` generation fingerprint (`hasCanonicalEntrySchema`), so
+    // adding it does not require a `CANONICAL_INDEX_DB_VERSION` bump.
+    ensureEmbeddingSalvageTable(db);
     rebuildIncompatibleIndexGeneration(db);
     db.exec(CANONICAL_ENTRY_SCHEMA_SQL);
     // Workflow source is compiled directly into source IR at each command

package/dist/tasks/run/run-native-task.js

@@ -145,6 +145,23 @@ export async function runNativeTask(input) {
     const logLines = [header];
     const dbLines = [{ line: header }];
     let exitCode = null;
+    // #956: the task runner's OWN process (`akm task run`, launched by cron /
+    // launchd / schtasks, or forwarded a SIGTERM by the published launcher)
+    // had no way to end its detached, own-process-group
+    // child (spawned by `runManagedSubprocess` for the group-kill guarantee
+    // above) — a timeout or SIGTERM to the direct child would reap the whole
+    // group, but nothing tied THIS process's own termination to that same
+    // ladder, so a signal to the runner left its child running as an orphan.
+    // Aborting `runManagedSubprocess` here runs its normal SIGTERM→SIGKILL
+    // kill ladder against the child's process group.
+    const abortController = new AbortController();
+    const forwardTerminationSignal = (signal) => {
+        abortController.abort(new Error(`task runner received ${signal}`));
+    };
+    const onSigterm = () => forwardTerminationSignal("SIGTERM");
+    const onSigint = () => forwardTerminationSignal("SIGINT");
+    process.once("SIGTERM", onSigterm);
+    process.once("SIGINT", onSigint);
     try {
         // Re-resolve the authored root/cwd immediately before spawn so a
         // symlink, ancestor, bundle-root, or directory/file swap cannot redirect
@@ -159,7 +176,9 @@ export async function runNativeTask(input) {
         }
         // Managed spawn (src/core/subprocess.ts): process-GROUP kill so a timeout
         // reaps the whole command tree (no orphans), and a SIGTERM→SIGKILL ladder
-        // so a child that ignores SIGTERM can't wedge the run forever.
+        // so a child that ignores SIGTERM can't wedge the run forever. `signal`
+        // ties that same ladder to a termination signal received by this
+        // process itself (#956), not only to the timeout.
         const result = await runManagedSubprocess(cmd, {
             capture: true,
             cwd: task.cwd,
@@ -178,6 +197,7 @@ export async function runNativeTask(input) {
             // layer on top and break any resolved path containing a space.
             windowsVerbatimArguments: task.kind === "shell" && task.shell === "cmd",
             timeoutMs,
+            signal: abortController.signal,
             ...(input.spawnFn ? { spawnFn: input.spawnFn } : {}),
             ...(input.setTimeoutFn ? { setTimeoutFn: input.setTimeoutFn } : {}),
             ...(input.clearTimeoutFn ? { clearTimeoutFn: input.clearTimeoutFn } : {}),
@@ -221,6 +241,8 @@ export async function runNativeTask(input) {
         exitCode = 1;
     }
     finally {
+        process.off("SIGTERM", onSigterm);
+        process.off("SIGINT", onSigint);
         if (materialized)
             cleanupFrozenScript(materialized);
     }

package/docs/migration/release-notes/0.9.15.md

@@ -38,10 +38,102 @@ scheduled or opportunistic run step aside instead of contending with a rebuild
 already in progress; the shipped `index-refresh` scheduled task already passes
 it.
 
-There is no `embedding.concurrency` config field. Embedding throughput is
-tuned by `embedding.batchSize` (documents per request) and
-`embedding.maxTokens`/`contextLength` (token budget per request); the number of
-requests in flight is fixed (1 for a loopback endpoint, 2 for a remote one).
+`embedding.maxTokens`'s default (the per-request token budget) is now 6000,
+down from 8000: a field report on an 8192-token llama.cpp embedder showed the
+4-chars-per-token estimator undercounts dense technical text by 7-55%, so the
+old default regularly overshot the endpoint's real context window. If you
+already set `embedding.maxTokens` explicitly, this default change does not
+affect you — your configured value is unchanged. `akm index` also now
+recovers automatically within a run: on the first request rejected for
+exceeding the endpoint's context window, it lowers its effective budget for
+the rest of that run (reported with one line) rather than continuing to hit
+the same wall on every following batch.
+
+`embedding.concurrency` (positive integer, 1-16) overrides the number of
+embedding requests kept in flight at once, which otherwise defaults to 1 for
+a loopback endpoint and 2 for a remote one. Set it only for an endpoint that
+genuinely serves parallel requests — a local model server started with a
+multi-slot flag (llama.cpp's `--parallel N`, vLLM) — since the default
+already protects an ordinary single-slot server from reload-thrash.
+Embedding throughput is still tuned first by `embedding.batchSize`
+(documents per request) and `embedding.maxTokens` (token
+budget per request); the concurrency override is a second lever for a
+server that can actually use it.
+
+`embedding.timeoutMs` bounds each embedding request (default 120s, up from a
+prior fixed 30s that cut off a slow local model server mid-response). It is
+the budget for a request at the full token budget — a smaller request gets a
+proportionally smaller timeout, so a dead endpoint is still detected in
+seconds on the common case of small documents. A request TIMEOUT no longer
+drops its batch immediately: akm now backs off (5s, doubling, capped at 60s)
+and retries the same request once, since field evidence showed the endpoint
+keeps computing an abandoned request regardless of the client giving up; a
+second timeout splits the batch in half and retries each half the same way,
+down to individual documents, and a single document that still times out is
+finally skipped. After 3 consecutive failures at single-document size
+(timeout or network error), or 3 consecutive network errors at any size —
+never a batch rejected only for exceeding the endpoint's context window —
+`akm index`'s embedding phase stops dispatching further requests and reports
+failure instead of grinding through every remaining batch against a dead
+endpoint — batches already committed are kept, and a rerun picks up where it
+left off.
+
+`akm bundle update` now durably commits its embedding pass instead of
+nesting it inside its own transaction: earlier releases ran the embedding
+phase inside the same transaction as content/lock/index/state, so every
+per-batch commit landed as an unobservable SAVEPOINT and a SIGKILL mid-run
+lost every embedding of the update, not just the one in flight. The
+embedding phase now runs on its own connection after the update's own
+commit; a failing pass (provider down) still leaves the update itself
+successful, with the new `index.semanticStatus` field on `akm bundle
+update`'s response the only sign semantic search fell behind.
+
+The published `akm`/`akm-migrate` launchers now forward SIGTERM/SIGINT/
+SIGHUP to their child and exit alongside it, instead of leaving the child
+running as an orphan when only the launcher is signaled. No action needed —
+this is a drop-in fix for anyone running `akm` under a scheduler,
+supervisor, or hook that can time out or kill the launcher process
+directly.
+
+`embedding.maxInputTokens` (default 512) now caps how much of a single
+document's text is sent to the embedding provider, truncating to the head
+instead of ever failing a whole batch over one oversized document.
+
+- An existing install's already-stored vectors are untouched and stay
+  valid — this only changes what happens for entries embedded *after*
+  upgrading.
+- New embeddings (any entry indexed for the first time, or re-indexed after
+  a content change) go through the new 512-token cap by default. If you
+  were relying on documents longer than ~2000 characters being embedded in
+  full, set `embedding.maxInputTokens` higher in `config.json`.
+- `akm index --reembed` re-embeds every entry under the new cap — run it if
+  you want your entire existing index rebuilt against the new default (or a
+  custom `embedding.maxInputTokens` you've set).
+- `embedding.contextLength` is Ollama's `num_ctx` only now; it no longer
+  also sets the per-request token budget (`embedding.maxTokens`). If you had
+  set `contextLength` specifically to control request batching (not your
+  Ollama server's context window), set `embedding.maxTokens` instead.
+
+`akm index --full` and an index-generation bump no longer re-embed
+unchanged content: vectors about to be discarded are salvaged and handed
+back to unchanged entries at the start of the next embedding pass instead
+of every upgrade re-embedding the whole corpus once. No action needed —
+this is automatic; `akm index --reembed` still forces a full re-embed when
+you don't trust the salvaged vectors.
+
+A field report suspected `akm index` was sending embedding requests with no
+`Authorization` header despite `embedding.apiKey` being set to a
+`secret://` reference. Auditing every path that builds an embedding request
+found all of them already resolve `secret://` through the same store
+lookup, now pinned by integration and contract tests — this was not a bug
+in the code as it stands. `akm index` now prints one line before its first
+provider request naming the endpoint, model, and credential SOURCE (never
+the value), e.g. `[embed] endpoint http://.../v1/embeddings, model
+nomic-embed; credential: secret://lab-api-key (store)`. If you run an
+embedding gateway that enforces auth and still see unauthenticated requests
+after upgrading, compare this line's endpoint and credential source against
+what the gateway's own request log shows for the same request — a
+mismatch there (not in this line) is the next place to look.
 
 A config file can now inherit a shared base via `extends: <path|bundle//path>`,
 deep-merging under the local file so local keys always win. `akm config diff
@@ -50,3 +142,10 @@ effective config and another config file or bundle-relative file. `akm config
 unset` now refuses to unset a key whose value comes only from an
 `extends`-inherited base, naming the source, since there would be nothing local
 to remove.
+
+The scheduler runs the binary path `akm task sync` recorded at sync time, not
+whichever akm your shell now resolves to. After upgrading akm through a
+different installer than the one active at your last `task sync` (e.g.
+npm-global to a standalone download), run `akm task sync` again so the
+schedule points at the new binary; `akm health --probe` now warns via a new
+`scheduler-binary` advisory when the two diverge.

package/docs/migration/release-notes/README.md

@@ -9,8 +9,9 @@ live one level up in `docs/migration/`.
 
 - [0.9.15](0.9.15.md) — exit-code 75 for lease/state.db contention,
   `--require-engines` scheduled task templates, `--no-probe` cli-version
-  skip, thinking-control wire forms, embedding re-embed safety, and
-  `extends` config inheritance
+  skip, thinking-control wire forms, embedding re-embed safety and
+  cross-rebuild vector salvage, launcher signal forwarding, a default
+  per-document embedding cap, and `extends` config inheritance
 - [0.9.14](0.9.14.md) — index v22-to-v23 derived-cache rebuild, lexical
   fragments, and collapse-detector canary re-minting
 - [0.9.2](0.9.2.md) — task source v4 migration, workflow source IR v1 and

package/docs/reference/cli.md

@@ -117,7 +117,7 @@ Every command exits with one of the following codes:
 | 2 | Usage / bad input | `UsageError` |
 | 4 | Health warning (`akm health` only) | — |
 | 70 | Internal / unclassified error | unexpected throw |
-| 75 | Transient — retry shortly (sysexits `EX_TEMPFAIL`); another akm process holds a lock or is writing `state.db` right now, not a bad command line | `TransientError` |
+| 75 | Transient — retry shortly (sysexits `EX_TEMPFAIL`); another akm process holds a lock or is writing `state.db` or `index.db` right now, not a bad command line | `TransientError` |
 | 78 | Configuration error | `ConfigError` |
 
 Failures classified by akm emit a JSON error envelope on **stderr** before
@@ -219,7 +219,7 @@ Build or refresh the search index.
 
 ```sh
 akm index            # Incremental (only changed directories)
-akm index --full     # Full rebuild
+akm index --full     # Full rebuild (reuses unchanged embeddings — see below)
 akm index --verbose  # Print phase progress to stderr
 akm index --clean    # Normal index + remove stale entries from the DB
 akm index --clean --dry-run # Report stale entries without deleting
@@ -234,6 +234,18 @@ semantic-search settings, and phase-by-phase progress to stderr while the
 index is being built. Malformed workflow assets are skipped with file-path
 warnings instead of aborting the full run.
 
+**Progress in non-verbose JSON mode (default output format, #954):** even
+without `--verbose`, phase-start messages and the embedding heartbeat
+(`Still generating embeddings: X/N stored, F failed; waiting on embedding
+provider.`) are now written to stderr, and a failed embedding batch logs at
+the default level instead of `--verbose`-only — a long-running index build
+against a slow or unresponsive provider is no longer silent until the whole
+run finishes. Text-mode output keeps its spinner instead (no stderr line
+growth); JSON stdout output is unaffected either way. The high-frequency
+per-batch `Embedded N/M entries.` line stays out of non-verbose stderr (it
+fires after every committed batch) — pass `--verbose` for that level of
+detail.
+
 **`--clean` flag:** After indexing completes, verifies every indexed entry's source
 file still exists on disk. Removes any entries whose file is missing (for local
 bundle sources only; remote entries are skipped). Returns a `clean` block in the
@@ -242,6 +254,18 @@ Use `--clean` to resolve the edge case where a deleted file in an unchanged
 directory lingers in the index across incremental runs. With `--dry-run`, reports
 which entries would be removed without modifying the database.
 
+**`--full` no longer re-embeds unchanged content (#955):** a full rebuild
+(and an index-generation bump on first open under a new binary) used to
+delete every embedding unconditionally, forcing a full re-embed of the
+whole corpus even when nothing changed. Vectors about to be discarded are
+now salvaged (keyed by a hash of their content plus the fingerprint they
+were generated under) and handed straight back to unchanged entries at the
+start of the next embedding pass, with zero provider calls for them — a
+progress line reports the split (`Reused N embeddings from the previous
+generation; embedding M new.`). Content that changed even by one byte, or
+a fingerprint that no longer matches, still goes through the provider
+normally. `--reembed` is the way to force a full re-embed regardless.
+
 **`--reembed` flag:** Forces a full purge and re-embed of every entry,
 independent of the embedding-model-rename compatibility check described
 below. Ordinary indexing already tells a config-only rename of
@@ -255,11 +279,17 @@ opt-in, PID-liveness-only rebuild lock and releases it on exit — this is
 advisory, never the blocking lock #872 removed (see
 [Locks](https://github.com/itlackey/akm/blob/main/docs/architecture/internals/indexing.md#locks)). A human-typed
 `akm index` with no flag is never gated by it: if another run already holds
-the lock, it warns and proceeds anyway, contending with the existing run.
+the lock, it warns and proceeds anyway, contending with the existing run. If
+that contention makes index.db genuinely busy (SQLite `database is locked`)
+long enough to exhaust the driver's retry window, the run now fails with
+exit 75 (`TransientError`, code `INDEX_DB_CONTENDED`) instead of the raw
+driver error at exit 70 — the same retry-shortly contract as
+`STATE_DB_CONTENDED`, so a scheduler can branch on it instead of alerting.
 `--skip-if-locked` changes that only for the invocation that passes it: if
 the lock is already held by a live process, it skips gracefully (exit 0,
-`{ ok: true, skipped: { reason: "lock-held", pid, startedAt } }`) instead of
-contending. `akm index` and `akm curate` are both safe to call frequently —
+`{ ok: true, skipped: { reason: "lock-held", pid, launcherPid, startedAt } }`
+— `launcherPid` is the holder's launcher pid when known, `null` otherwise,
+#956) instead of contending. `akm index` and `akm curate` are both safe to call frequently —
 `curate` never blocks on a rebuild in progress ([read-path indexing stays
 non-blocking](#curate)) — but a hook, cron job, or scheduled task that
 invokes `akm index` directly should pass `--skip-if-locked` so it steps
@@ -333,15 +363,17 @@ akm health --report --window-compare 7d --format html
 | `--window-compare` | Compare the current window against the prior window of the same duration (e.g. `24h`, `7d`). With `--report`, overrides the default trend window. |
 | `--group-by` | Group rows by `run` (one row per `improve_runs` entry). Omit for the default summary. |
 | `--windows` | Explicit comparison window(s) as `name=...,since=ISO,until=ISO` (repeatable, up to 4). Mutually exclusive with `--window-compare`. |
-| `--no-probe` | Skip the `default-llm-engine` / `configured-engines` reachability probes and the `cli-version` update check (for an offline or air-gapped host). |
+| `--no-probe` | Skip the `default-llm-engine` / `configured-engines` reachability probes, the `cli-version` update check, and the `scheduler-binary` version check (for an offline or air-gapped host). |
 
 The command reads `state.db`, verifies that the required tables exist, performs a
 write-read probe against the events stream, inspects `task_history`, checks the
 default agent engine, and summarizes recent `improve_*` events. Unless
 `--no-probe` is given, it also sends a bounded (3s timeout) reachability probe
 to the `default-llm-engine` and every `configured-engines` LLM connection (and
-an SDK engine's LLM fallback), one probe per distinct endpoint, and checks the
-installed akm-cli version against the latest GitHub release (`cli-version`).
+an SDK engine's LLM fallback), one probe per distinct endpoint, checks the
+installed akm-cli version against the latest GitHub release (`cli-version`),
+and runs the scheduler's recorded akm binary with `--version` to check it
+against the running CLI (`scheduler-binary`).
 
 Primary result fields:
 
@@ -1214,6 +1246,14 @@ Shipping akm inside your own product (a Docker image, a plugin's own
 `node_modules`)? See [Bundling akm](../integration/bundling-akm.md) for the
 full boot contract, JSON shapes, and exit codes.
 
+`akm upgrade` replaces the binary in place for its own install method, but a
+scheduler binding recorded by an earlier `akm task sync` under a *different*
+install method is not repointed automatically — the scheduler runs the
+binary path recorded at sync time, not whichever akm `upgrade` just
+installed. Run `akm task sync` after switching installers so scheduled runs
+pick up the new binary; see [`task sync`](#task) and `akm health`'s
+`scheduler-binary` advisory.
+
 ### clone
 
 Copy an asset from any source into a managed writable bundle or an unmanaged
@@ -2847,6 +2887,13 @@ task template (both the core set and the improve-schedule set) and asks once
 before changing task files or scheduler state; non-interactive setup changes
 neither.
 
+Because the scheduler runs the exact binary path recorded at the last `task
+sync`, upgrading akm through a different installer than the one active at
+that sync (npm-global to a standalone download, or vice versa) leaves
+scheduled runs invoking the old, now-stale binary — `task sync` re-resolves
+the current path and repoints them. `akm health --probe`'s `scheduler-binary`
+advisory warns when the two diverge, naming both versions.
+
 Setup reconfiguration preserves existing scheduler runtime bindings. Changing
 the AKM storage path or installed runtime path therefore requires an explicit
 `akm task sync --rebind`; setup does not silently migrate those entries.