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

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,91 @@ 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.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

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

@@ -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
@@ -258,8 +282,9 @@ advisory, never the blocking lock #872 removed (see
 the lock, it warns and proceeds anyway, contending with the existing run.
 `--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

package/docs/reference/configuration.md

@@ -396,21 +396,62 @@ unless a remote `embedding` config is provided.
 `akm improve`'s memory-inference/consolidate passes when they call an
 embedding model: `provider`, `endpoint`, `model`, `apiKey` (symbolic
 reference, same rules as engine `apiKey`), `dimension`, `localModel`,
-`maxTokens`, `batchSize`, `chunkSize`, `contextLength`, and
-`ollamaOptions.num_ctx`.
-
-`akm index` keeps a small, fixed number of `/v1/embeddings` requests in
-flight at once (a remote endpoint only; the local transformer path is
-unaffected): `1` for a loopback endpoint (`localhost`, `127.0.0.0/8`, etc. —
-a local model server serves one inference at a time, and parallel requests
-thrash it) and `2` for a remote one. This width is not configurable. The
-actual throughput knob is request SIZE, not request count: `embedding.batchSize`
-(a document-count cap, default 100) together with `embedding.maxTokens` /
-`embedding.contextLength` (an estimated token budget per request, default
-8000) control how many documents land in one request — a batch of 16-32
-documents takes about the same wall time as a single one against a healthy
-endpoint, so growing the batch is where most of the win is, not adding more
-concurrent requests.
+`maxInputTokens`, `maxTokens`, `batchSize`, `chunkSize`, `contextLength`,
+`timeoutMs`, `concurrency`, and `ollamaOptions.num_ctx`.
+
+The knobs that bound request/document size and rate, all optional (defaults
+apply when unset), for a remote endpoint (`src/llm/embedders/remote.ts`):
+
+| Key | Default | Bounds |
+| --- | --- | --- |
+| `embedding.maxInputTokens` | `512` | Per-DOCUMENT cap, applied before batching (#956). A document's embedded text is truncated to its head (unicode-safe) at this many estimated tokens instead of ever being skipped for size alone — a document is skipped only when its truncated head is empty. |
+| `embedding.maxTokens` | `8000` (`DEFAULT_TOKEN_BUDGET`) | Per-REQUEST token budget: how many (already-capped) documents' estimated tokens fit in one HTTP request. With the 512-token default document cap, a request carries about 16 documents by default. |
+| `embedding.batchSize` | `100` | Per-REQUEST document-COUNT safety cap, independent of the token budget — guards against many tiny documents packing an oversized request. |
+| `embedding.contextLength` | unset | Ollama's `num_ctx` ONLY, forwarded verbatim as `options.num_ctx` on the native `/api/embed` request. Does **not** feed the request token budget above (#956) — the two used to share this one field, so setting it for the server's context window silently changed request batching too. |
+| `embedding.timeoutMs` | `120000` (120s) | Per-request wall timeout — see below. |
+| `embedding.concurrency` | `1` loopback / `2` remote | In-flight request window — see below. |
+
+`embedding.timeoutMs` (positive integer, default `120000` — 120s) is the
+budget for a request at the FULL token budget (`embedding.maxTokens`); a
+local model server on a large, token-budget-bounded batch legitimately takes
+longer than the prior fixed 30s cut off. A smaller request gets a
+proportionally smaller timeout —
+`clamp(timeoutMs × requestTokens / tokenBudget, 30000, timeoutMs)` — so a
+dead endpoint is still detected in seconds on the common case of small
+documents. Set `embedding.timeoutMs` lower to fail fast against a
+known-fast endpoint, or higher for a slow local server on large batches.
+
+A request TIMEOUT (not a rejection for exceeding the context window) never
+drops its batch immediately: field confirmation showed that once akm
+abandons a timed-out request, the endpoint (e.g. llama-server) keeps
+computing it anyway, so dropping it right away just grows the provider's
+queue while every following batch dies the same way. Instead akm backs off
+(5s, doubling, capped at 60s) and retries the same request once; a second
+timeout splits it in half and retries each half the same way, down to
+individual documents, and a single document that still times out is finally
+skipped (logged at the default `warn` level). After 3 consecutive failures
+at single-document size (timeout or network error), or 3 consecutive
+network errors at any size, the embedding phase stops dispatching further
+requests and reports failure — batches already committed are kept; rerun
+`akm index` once the endpoint is healthy.
+
+`akm index` keeps a small number of `/v1/embeddings` requests in flight at
+once (a remote endpoint only; the local transformer path is unaffected):
+`1` for a loopback endpoint (`localhost`, `127.0.0.0/8`, etc. — a local
+model server serves one inference at a time, and parallel requests thrash
+it) and `2` for a remote one, unless `embedding.concurrency` (positive
+integer, 1-16) overrides it. This default holds for the overwhelming
+majority of setups; set the override only for an endpoint that genuinely
+serves parallel requests — a local server started with a multi-slot flag
+(llama.cpp's `--parallel N`, vLLM) — not to "speed up" an ordinary
+single-slot model server, which the default already protects from
+reload-thrash. Request SIZE remains the first throughput lever regardless:
+`embedding.batchSize` (a document-count cap, default 100) together with
+`embedding.maxTokens` (an estimated token budget per request, default 8000
+— NOT `embedding.contextLength`, see the table above) control how many
+documents land in one request — with the default 512-token
+`embedding.maxInputTokens` document cap, that is about 16-32 documents,
+taking about the same wall time as a single one against a healthy endpoint.
 
 ## Search tuning
 
@@ -674,6 +715,17 @@ embedding calls have since 0.9.13 (#917); resolution order for a single
 `apiKeyFile`, then `secret://<name>` — though in practice a config sets only
 one of the three per engine.
 
+`embedding.apiKey` accepts the same three forms and resolves `secret://` the
+same way, on every path that sends an embedding request: `akm index`
+(including its `bundle update` post-commit embedding pass and the targeted
+re-embed a write command like `akm remember` triggers), `akm improve`'s
+consolidate pass (memory dedup and similarity clustering), and the
+fingerprint-rename canary `akm index` runs when the embedding config
+changes. All of them build the
+provider request through the same `RemoteEmbedder`/`resolveSecret` boundary,
+so a `secret://` reference resolves identically regardless of which command
+triggered the request (#953).
+
 Use `AKM_SQLITE_JOURNAL_MODE=DELETE` or `TRUNCATE` when WAL is unavailable,
 such as on some NFS/SMB mounts. With the default `WAL` setting, AKM detects a
 network filesystem for the data directory and falls back to `DELETE`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akm-cli",
-  "version": "0.9.15-beta.1",
+  "version": "0.9.15-beta.2",
   "type": "module",
   "description": "akm (Agent Knowledge Manager) — a portable, local-first capability library for AI agents. Discover, load, share, and improve reusable skills, scripts, workflows, and knowledge across any shell-capable coding agent, including Claude Code, OpenCode, and Cursor.",
   "keywords": [

package/schemas/akm-config.json

@@ -211,6 +211,10 @@
           "type": "string",
           "minLength": 1
         },
+        "maxInputTokens": {
+          "type": "integer",
+          "exclusiveMinimum": 0
+        },
         "maxTokens": {
           "type": "integer",
           "exclusiveMinimum": 0
@@ -236,6 +240,15 @@
             }
           },
           "additionalProperties": true
+        },
+        "timeoutMs": {
+          "type": "integer",
+          "exclusiveMinimum": 0
+        },
+        "concurrency": {
+          "type": "integer",
+          "exclusiveMinimum": 0,
+          "maximum": 16
         }
       },
       "additionalProperties": true
@@ -1902,6 +1915,10 @@
               "type": "string",
               "minLength": 1
             },
+            "maxInputTokens": {
+              "type": "integer",
+              "exclusiveMinimum": 0
+            },
             "maxTokens": {
               "type": "integer",
               "exclusiveMinimum": 0
@@ -1927,6 +1944,15 @@
                 }
               },
               "additionalProperties": true
+            },
+            "timeoutMs": {
+              "type": "integer",
+              "exclusiveMinimum": 0
+            },
+            "concurrency": {
+              "type": "integer",
+              "exclusiveMinimum": 0,
+              "maximum": 16
             }
           },
           "additionalProperties": true
@@ -3471,6 +3497,10 @@
           "type": "string",
           "minLength": 1
         },
+        "maxInputTokens": {
+          "type": "integer",
+          "exclusiveMinimum": 0
+        },
         "maxTokens": {
           "type": "integer",
           "exclusiveMinimum": 0
@@ -3496,6 +3526,15 @@
             }
           },
           "additionalProperties": true
+        },
+        "timeoutMs": {
+          "type": "integer",
+          "exclusiveMinimum": 0
+        },
+        "concurrency": {
+          "type": "integer",
+          "exclusiveMinimum": 0,
+          "maximum": 16
         }
       },
       "additionalProperties": true