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

package/CHANGELOG.md

@@ -4,7 +4,7 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
-## [0.9.15-beta.1] - 2026-09-09
+## [0.9.15-beta.2] - 2026-09-09
 
 ### Added
 
@@ -173,8 +173,10 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
   held lock only warns and the run proceeds unlocked, exactly as before.
   `--skip-if-locked` mirrors `akm improve --skip-if-locked`: when the lock is
   already held by a live process it skips gracefully (exit 0, `{ ok: true,
-  skipped: { reason: "lock-held", pid, startedAt } }`) instead of piling up
-  behind the other run. The shipped `index-refresh` scheduled task now passes it.
+  skipped: { reason: "lock-held", pid, launcherPid, startedAt } }` —
+  `launcherPid` is the holder's launcher pid when known, `null` otherwise,
+  #956) instead of piling up behind the other run. The shipped
+  `index-refresh` scheduled task now passes it.
 - **`akm improve` reports which processes it skipped for an unavailable engine,
   instead of dispatching with a doomed credential (#957).** A process whose
   engine was configured but whose credential could not be resolved in this
@@ -201,6 +203,71 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
   reference — recommended alongside `--skip-if-locked` for scheduled runs, since
   the operator's own shell can pass config validation while a scheduler's
   stripped-down environment cannot.
+- **`embedding.timeoutMs` configures the per-request embedding timeout
+  (#954).** The prior fixed 30s timeout cut off a slow local model server on
+  a large token-budget-bounded batch mid-response. Default 120s, used by both
+  the single-text and batch embedding request paths; it scales down for a
+  smaller-than-budget request (`clamp(timeoutMs × requestTokens /
+  tokenBudget, 30s, timeoutMs)`), so a dead endpoint is detected in seconds
+  on the common case of small documents. A request timeout no longer drops
+  its batch immediately: field confirmation showed the endpoint keeps
+  computing an abandoned request regardless, so akm now backs off (5s,
+  doubling, capped at 60s) and retries the SAME request once before ever
+  splitting or skipping it; a second timeout splits the batch in half (like
+  a context-size rejection) and retries each half the same way, down to
+  individual documents, and a single document that times out twice is
+  finally skipped.
+- **`embedding.concurrency` overrides the fixed in-flight embedding request
+  window (#954).** Bounded 1-16; unset behavior is unchanged (1 for a
+  loopback endpoint, 2 for a remote one). 0.9.15-beta.1 shipped with no
+  config override for this window; the final release adds one after field
+  evidence that a multi-slot local server (llama.cpp `--parallel N`, vLLM)
+  sat idle behind the fixed default. Request size — `embedding.batchSize`
+  and `embedding.maxTokens` — remains the first throughput
+  lever; set this only for an endpoint that genuinely serves parallel
+  requests.
+- **The embedding phase stops after 3 consecutive transport failures instead
+  of grinding through every remaining batch (#954).** A dead or hung
+  provider used to burn hours on a large stash, one request timeout at a
+  time, with no signal until a single aggregate warning at the end and
+  `ok: true`, exit 0. The pass now stops dispatching further requests and
+  reports failure after 3 consecutive failures at single-document size
+  (timeout or network error — a multi-document timeout is retried and split
+  smaller before it can ever count, so it is not by itself evidence the
+  endpoint is dead) or 3 consecutive network errors at any size (never
+  retried, so trusted immediately); a `context-window-exceeded` skip never
+  counts and resets both streaks. The failure message names how many
+  embeddings were stored before it gave up. Batches already committed are
+  kept.
+- **`embedding.maxInputTokens` caps a single document's embedded text
+  instead of letting it fail a whole batch (#956).** llama.cpp rejects a
+  single sequence longer than its physical batch (`--ubatch-size`, default
+  512) with HTTP 500 "input is too large to process," and the only
+  per-entry cap before this was 1,000,000 characters. `akm index` now
+  truncates a document's embedded text to `embedding.maxInputTokens`
+  (default 512, head only, unicode-safe) before batching rather than
+  skipping it; a document is skipped only when its truncated head is empty.
+  `embedding.contextLength` is Ollama's `num_ctx` only now — it used to also
+  silently set the per-request token budget (`embedding.maxTokens`), so
+  setting it for the server's context window changed request batching too.
+  The request budget is `embedding.maxTokens` (default 8000), so a request
+  carries about 16 documents alongside the new per-document cap by default.
+- **`akm index` reports where its embedding credential came from, before the
+  first provider request (#953).** A field report suspected a gateway was
+  receiving unauthenticated embedding requests despite `embedding.apiKey`
+  being set to a `secret://` reference. Auditing and reproducing every path
+  that reaches `RemoteEmbedder` — plain `akm index`, the CLI as a real child
+  process, an `extends`-inherited config with adapter detection persisting
+  mid-run (#945), `akm bundle update`'s post-commit embedding pass, and the
+  `akm remember` write path's targeted re-embed — found every one already
+  resolves `secret://` through the same store lookup, now pinned by
+  integration and contract tests so a future config-flow change cannot drop
+  `apiKey` unnoticed. `akm index` now prints one default-level line before
+  its first provider request naming the endpoint, model, and credential
+  SOURCE — `secret://lab-api-key (store)`, `$LAB_API_KEY (env)`, `literal
+  apiKey`, or `none configured` — never the credential's value, so a field
+  run can compare it directly against what the gateway actually logged.
+  `--verbose` also names the config file the run loaded.
 
 ### Changed
 
@@ -245,7 +312,9 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
   so an interruption partway through (a competing indexer collision, a killed
   process, any thrown provider error) discarded every embedding already computed,
   not just the ones still in flight. Each request batch now commits inside its
-  own short transaction as it lands.
+  own short transaction as it lands. This holds on every path that embeds: plain
+  `akm index`, the implicit reindex, the write path (`akm remember`/`import`/
+  `proposal accept`/`source clone`), and `akm bundle update` (see below).
 - **A batch rejected for exceeding the endpoint's context window is split and
   retried instead of skipped outright (#954).** `akm index`'s embedding pass now
   recognizes HTTP 413 and known context-size error bodies and halves the failing
@@ -253,15 +322,23 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
   single document that still fails this way is skipped, as
   `context-window-exceeded`; every other failure (network error, 5xx, malformed
   response) keeps the prior skip-the-whole-batch behavior.
-- **Embedding requests are now dispatched through a small, fixed in-flight window
-  instead of strictly sequentially (#954).** The window is 1 request at a time
-  for a loopback endpoint and 2 for a remote one, and is not configurable — the
-  actual throughput knob is request size, via the existing `embedding.batchSize`
-  (document cap) and `embedding.maxTokens`/`contextLength` (token budget), since
-  a larger batch takes about the same wall time as a single one.
-- **`akm index` reports embedding progress and throughput as it runs (#954).** A
-  progress line is printed every 500 stored entries, and a final line reports
-  throughput (`entries/s`, `tokens/s`) once the embedding pass completes.
+- **Embedding requests are dispatched through a small in-flight window instead of
+  strictly sequentially (#954).** The window defaults to 1 request at a time for
+  a loopback endpoint and 2 for a remote one; the actual throughput knob is
+  request size, via the existing `embedding.batchSize` (document cap) and
+  `embedding.maxTokens` (token budget), since a larger batch
+  takes about the same wall time as a single one. `embedding.concurrency`
+  (see Added, above) overrides this default for a server that genuinely serves
+  parallel requests.
+- **`akm index` reports embedding progress and throughput in more detail as it
+  runs (#954).** A default-level line reports each provider batch as it
+  completes — document count, token count, elapsed time, and outcome
+  (`stored`/`failed: <reason>`/`retrying after <n> s`) — and a final line
+  reports total throughput (`entries/s`, `tokens/s`) plus every outcome: how
+  many embeddings were stored (and reused from a prior generation, when
+  salvage applied — see #955 below), oversized-skipped, timed out, and
+  failed, with the affected refs listed (first 20 by default, all of them
+  under `--verbose`).
 - **A rename of `embedding.model` no longer forces a full re-embed by itself
   (#955).** `akm index` used to purge and rebuild the entire vector index on any
   change to the fingerprint it derives from `embedding.model`, including a pure
@@ -288,6 +365,27 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
   The new fingerprint (and the observed identity) are now written in the same
   transaction as the purge, before any vectors are requested; a restart then sees
   a matching fingerprint and only re-embeds the entries still missing a vector.
+- **`akm index --full` and an index-generation bump no longer re-embed
+  unchanged content (#955).** A full rebuild deleted every embedding
+  unconditionally and re-inserted entries under new ids, and the v22→v23
+  generation bump did the same on first open under a new binary — both
+  forced a full re-embed of the whole corpus even when nothing changed, the
+  likely cause of the multi-hour post-upgrade run reported against 0.9.14.
+  Vectors about to be discarded are now copied into a transient
+  `embedding_salvage` table (keyed by a hash of `search_text` plus the
+  fingerprint they were generated under) in the same transaction as the
+  discard — read back in bounded chunks rather than loaded wholesale, so a
+  large corpus does not spike memory, and a run with nothing to reuse costs
+  a single indexed lookup — and handed back to unchanged entries at the
+  start of the next embedding pass with zero provider calls — a progress
+  line reports the split (`Reused N embeddings from the previous
+  generation; embedding M new.`). Content that changed by even one byte, or
+  a fingerprint that no longer matches, still goes through the provider
+  normally. `akm index --reembed` and a canary "rebuild" verdict purge the
+  salvage table along with the stored embeddings; a canary "keep" verdict (a
+  fingerprint-string rename resolving to the same model) relabels it instead
+  so it stays reusable. An interrupted pass leaves the table intact for the
+  next attempt.
 - **A write-path index update (`akm remember`, `akm import`, `akm proposal
   accept`, `akm source clone`, extract session assets) never contends with a full
   rebuild in progress; it skips and lets the rebuild heal the entry instead
@@ -321,6 +419,19 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
   `improve` itself now builds (see Added, above), rather than a separate
   re-derivation that could disagree with what a real run in the same environment
   would do.
+- **A failed embedding batch and `akm index`'s progress are visible without
+  `--verbose` (#954).** A failed provider batch used to log only under
+  `--verbose`; it now logs at the default `warn` level, naming the batch size
+  and reason. `akm index`'s `Embedded N/M entries.` line now fires after every
+  committed batch instead of every 500 stored entries, and the heartbeat names
+  the failed count too. In non-verbose JSON/yaml output mode, phase-start
+  messages and the heartbeat now reach stderr (via `info()`); text mode keeps
+  its spinner instead, and `--verbose` is unchanged. A silently grinding,
+  hours-long `akm index` run against a dead provider — with no output until
+  one aggregate warning at the very end — was the field report this fixes.
+  Source-cache hydration (which runs before `index.db` is even opened) now
+  reports its own progress the same way: `Hydrating source i/n: <name>` per
+  source, plus a 15s heartbeat while a sync is in flight.
 
 ### Fixed
 
@@ -400,6 +511,57 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 - **An unset or empty `$VAR` referenced by an engine's `apiKey` now warns once,
   naming the variable (#953).** Previously it silently sent an empty
   `Authorization` header instead of surfacing the misconfiguration.
+- **`akm bundle update` now commits its embedding pass durably instead of
+  nesting it inside its own transaction (#954).** Its coordinator called
+  `akm index` for its embedding phase too, INSIDE the same unified
+  `BEGIN IMMEDIATE` that covers content/lock/index/state — so every per-batch
+  commit (above) nested as an unobservable SAVEPOINT, and a SIGKILL mid-run
+  lost every embedding of the run rather than just the one in flight.
+  0.9.15-beta.1 shipped claiming per-batch commits held on this path; the
+  final release makes it true: `generateEmbeddingsForDb` now refuses to run
+  against a connection that already has a transaction open (an internal
+  contract error, not a user-facing one), and `akm bundle update` runs its
+  embedding phase on a fresh connection AFTER its own commit instead. A
+  failing post-commit pass (provider down) still leaves the update itself
+  successful — content, lock, and index generation are already durably
+  committed — with the response's `index.semanticStatus` (new field) the
+  only sign semantic search fell behind (`"blocked"`), exactly like a plain
+  `akm index` run today.
+- **A batch rejected by llama.cpp for exceeding its physical batch size is now
+  recognized as a context-size rejection (#954).** llama.cpp reports this as
+  an HTTP 500 with a body like "input is too large to process. increase the
+  physical batch size", which the existing context-size pattern
+  (`exceed_context_size_error`, "context size", …) did not match, so the
+  whole batch was dropped instead of being split and retried like a 413.
+- **A `kill <launcher-pid>` no longer orphans the running `akm` process
+  (#956).** The published launcher (`scripts/node-runtime/akm`/
+  `akm-migrate`) now forwards SIGTERM/SIGINT/SIGHUP to its bun/node child
+  and exits alongside it, instead of leaving the child running — one field
+  report found 40 orphaned `bun …/dist/cli.js` processes in a single day,
+  some hours old, still hammering the embedding endpoint and holding the
+  rebuild lock. Every command also polls for reparenting (a launcher that
+  dies without delivering a signal — SIGKILL, an out-of-memory kill) and
+  re-raises SIGTERM on itself the moment it notices, reusing the same abort
+  path a real signal already takes. Lock messages ("another index run is
+  active...", "akm improve is already running...") and `akm index
+  --skip-if-locked`'s JSON result now name the launcher pid alongside the
+  pid that actually holds the lock — `pid 4242 (launcher 4240)` — since
+  every process listing and task log shows the launcher pid, not the
+  child's.
+- **An index run interrupted before its first embedding pass ever completes
+  could force an unnecessary full re-embed on the next `akm index --full`
+  (#956).** A fingerprint-rename rebuild already wrote `embeddingFingerprint`
+  immediately, before any provider call, so an interruption right after that
+  decision still left a consistent record — but the common
+  first-pass/unchanged-fingerprint path deferred that write to a fully
+  successful run. A per-batch commit is durable the instant it lands
+  regardless, so an interrupted first-ever pass left real, already-embedded
+  vectors with no recorded fingerprint to tag them by, and a later full
+  rebuild's salvage-before-discard step (#955, above) treated the missing
+  fingerprint as "nothing was ever verified" and re-embedded everything
+  instead of reusing them. A plain `akm index` resume after an interruption
+  now embeds only the entries still missing a vector, with no purge and no
+  canary.
 
 ## [0.9.14] - 2026-09-04
 

package/dist/akm

@@ -117,6 +117,10 @@ if (contextIndex !== -1) {
 if (contextValid) {
   process.env.AKM_LAUNCHER_NODE = process.execPath;
   process.env.AKM_LAUNCHER_PATH = fileURLToPath(import.meta.url);
+  // #956: lets the child (and its lock payloads) name the launcher pid
+  // alongside its own, and lets the child's parent-death watchdog tell a
+  // real launcher-managed run apart from a direct `bun src/cli.ts` run.
+  process.env.AKM_LAUNCHER_PID = String(process.pid);
 
   if (!process.versions.bun) {
     const [major = 0, minor = 0] = process.versions.node.split(".").map(Number);
@@ -145,7 +149,56 @@ if (contextValid) {
     const entry = useBun ? bunEntry : nodeEntry;
     const runtime = useBun ? "Bun" : "Node.js";
     const result = await new Promise((resolve) => {
-      const child = spawn(command, [entry, ...process.argv.slice(2)], { stdio: "inherit", env: process.env });
+      const child = spawn(command, [entry, ...process.argv.slice(2)], {
+        stdio: "inherit",
+        env: process.env,
+        // #956: give the child its OWN process group on POSIX (`setsid()` —
+        // does not touch its inherited stdio; see `spawnsOwnProcessGroup` in
+        // src/core/subprocess.ts for the Windows caveat that rules this out
+        // there). Without this, a spawned child shares the launcher's
+        // process group by default, so a signal delivered to that GROUP (a
+        // terminal's Ctrl-C, or `kill -SIGINT -<pgid>`) reaches the child
+        // directly AND the launcher, which then also forwards it — a real
+        // second signal lands microseconds after the first. The child's
+        // `process.once(signal, ...)` handler has already unregistered
+        // itself for its first (direct) copy, so the second falls through
+        // to the runtime's default disposition (immediate termination) and
+        // the child's graceful shutdown (lock release, in-flight abort)
+        // never runs. Detaching the child's process group makes the
+        // launcher's forward below the SOLE delivery path to the child, so
+        // it is always exactly one signal.
+        detached: process.platform !== "win32",
+      });
+      // A `kill <launcher-pid>` (a scheduler timeout, a supervisor, an
+      // operator) used to end only this wrapper, orphaning the bun child —
+      // it kept running (and holding locks) for as long as its own work took.
+      // Forward the same signal so the child dies with its parent. Never
+      // forward once the child has already exited: forwarding to a
+      // dead/replaced pid would be at best a no-op and at worst a signal to
+      // an unrelated process that reused the pid.
+      let childExited = false;
+      child.once("exit", () => {
+        childExited = true;
+      });
+      const forwardSignal = (signal) => {
+        if (childExited) return;
+        try {
+          child.kill(signal);
+        } catch {
+          // Child exited in the race between the check above and here.
+        }
+      };
+      // `.once`, not `.on`: Node/Bun suppress a signal's default
+      // (process-terminating) disposition for as long as ANY listener stays
+      // registered for it. A persistent `.on` listener would still be
+      // registered when the `process.kill(process.pid, result.signal)`
+      // re-raise below runs at shutdown, swallowing it and leaving this
+      // launcher exiting 0 instead of reflecting the child's signal. `.once`
+      // consumes only the externally-delivered signal that triggers the
+      // forward, so the re-raise correctly falls through to the OS default.
+      for (const signal of ["SIGTERM", "SIGINT", "SIGHUP"]) {
+        process.once(signal, () => forwardSignal(signal));
+      }
       child.once("error", (error) => resolve({ error }));
       child.once("exit", (code, signal) => resolve({ code, signal }));
     });

package/dist/akm-migrate

@@ -27,10 +27,43 @@ const bunEntry = fileURLToPath(new URL("./scripts/akm-migrate.js", import.meta.u
 const nodeEntry = fileURLToPath(new URL("./scripts/akm-migrate-node.js", import.meta.url));
 
 {
+  // #956: same shape as scripts/node-runtime/akm — the child names the
+  // launcher pid, and a `kill <launcher-pid>` forwards to the child instead
+  // of orphaning it.
+  const env = { ...process.env, AKM_LAUNCHER_PID: String(process.pid) };
   const command = process.versions.bun ? process.execPath : useBun ? "bun" : process.execPath;
   const entry = process.versions.bun || useBun ? bunEntry : nodeEntry;
   const result = await new Promise((resolve) => {
-    const child = spawn(command, [entry, ...process.argv.slice(2)], { stdio: "inherit" });
+    const child = spawn(command, [entry, ...process.argv.slice(2)], {
+      stdio: "inherit",
+      env,
+      // #956: own process group on POSIX so the launcher's forward below is
+      // the SOLE delivery path to the child instead of a redundant second
+      // copy landing on top of a group-wide broadcast the child already got
+      // directly — see the matching comment in scripts/node-runtime/akm.
+      detached: process.platform !== "win32",
+    });
+    let childExited = false;
+    child.once("exit", () => {
+      childExited = true;
+    });
+    const forwardSignal = (signal) => {
+      if (childExited) return;
+      try {
+        child.kill(signal);
+      } catch {
+        // Child exited in the race between the check above and here.
+      }
+    };
+    // `.once`, not `.on`: see the matching comment in
+    // scripts/node-runtime/akm — a persistent `.on` listener would still be
+    // registered when the `process.kill(process.pid, result.signal)`
+    // re-raise below runs, suppressing the OS default disposition and
+    // leaving this launcher exiting 0 instead of reflecting the child's
+    // signal.
+    for (const signal of ["SIGTERM", "SIGINT", "SIGHUP"]) {
+      process.once(signal, () => forwardSignal(signal));
+    }
     child.once("error", (error) => resolve({ error }));
     child.once("exit", (code, signal) => resolve({ code, signal }));
   });

package/dist/cli.js

@@ -87,6 +87,8 @@ import { taskCommand } from "./commands/tasks/tasks-cli.js";
 import { workflowCommand } from "./commands/workflow-cli.js";
 import { DEFAULT_CONFIG, loadConfig } from "./core/config/config.js";
 import { UsageError } from "./core/errors.js";
+import { launcherPidFromEnv } from "./core/file-lock.js";
+import { startParentDeathWatchdog } from "./core/parent-watchdog.js";
 import { getConfigPath } from "./core/paths.js";
 import { DURATION_UNITS, parseDuration } from "./core/time.js";
 import { plainize } from "./core/tty.js";
@@ -1078,5 +1080,39 @@ async function runCli() {
 // sets `AKM_STANDALONE_ENTRY=1` before importing this file. The test harness
 // sets neither, so importing cli.ts under Bun stays inert as before.
 if (import.meta.main || process.env.AKM_NODE_ENTRY === "1" || process.env.AKM_STANDALONE_ENTRY === "1") {
-    await runCli();
+    // #956: a launcher that dies WITHOUT delivering a signal
+    // (SIGKILL, an OOM kill, a supervisor that force-removes the process)
+    // still reparents this process to init with nothing to catch — the field
+    // evidence was 40 orphaned `bun …/dist/cli.js` processes in one day, some
+    // from a curate hook killing its own launcher on timeout. Active for
+    // EVERY command (not only `index`), since a hook-invoked `curate`/`search`
+    // child is orphaned the same way. Inert when there is no launcher
+    // (AKM_LAUNCHER_PID unset — a direct `bun src/cli.ts` run, or any test
+    // harness that imports this module without setting it): only a real
+    // launcher-managed run has a parent worth watching.
+    const parentWatchdog = launcherPidFromEnv()
+        ? startParentDeathWatchdog({
+            initialPpid: process.ppid,
+            onOrphaned: () => {
+                // Self-delivers the same signal a real SIGTERM would be. `akm
+                // index`'s own AbortController listens for it
+                // (commands/sources/stash-cli.ts) and gets a graceful, in-process
+                // shutdown. Every other command has no SIGTERM listener of its
+                // own, so this self-signal terminates it directly via the
+                // runtime's default disposition WITHOUT running `exit` handlers
+                // (lock release included) — it stops the orphaned process, which
+                // is the goal here, but any lock it held is left for the next
+                // acquirer's dead-pid stale-reclaim (file-lock.ts) to clear, not
+                // released in-process. No second, parallel abort path to keep in
+                // sync either way.
+                process.kill(process.pid, "SIGTERM");
+            },
+        })
+        : undefined;
+    try {
+        await runCli();
+    }
+    finally {
+        parentWatchdog?.stop();
+    }
 }

package/dist/commands/improve/locks.js

@@ -6,7 +6,7 @@ import { ConfigError } from "../../core/errors.js";
 import { appendEvent } from "../../core/events.js";
 import { releaseLock } from "../../core/file-lock.js";
 import { tryWithMaintenanceStartBarrier, withMaintenanceStartBarrier } from "../../core/maintenance-barrier.js";
-import { tryAcquireRunLock } from "../../core/run-lock.js";
+import { formatLockHolderPid, tryAcquireRunLock } from "../../core/run-lock.js";
 import { warn } from "../../core/warn.js";
 export function improveLockPath(lockBaseDir) {
     return path.join(lockBaseDir, "improve.lock");
@@ -59,7 +59,8 @@ function tryAcquireImproveLockUnlocked(lockPath, skipIfLocked, onRecovered) {
     if (result.state === "acquired") {
         return { state: "acquired", ownership: result.ownership };
     }
-    const { pid, startedAt } = result.holder;
+    const { startedAt } = result.holder;
+    const pid = formatLockHolderPid(result.holder);
     if (skipIfLocked) {
         warn(`[improve] another improve run holds the lock (PID ${pid}, started ${startedAt}); skipping (--skip-if-locked)`);
         return { state: "skipped" };

package/dist/commands/sources/installed-stashes.js

@@ -26,7 +26,7 @@ import { beginImmediateTransaction, getStateDbPath, openStateDatabase } from "..
 import { warn } from "../../core/warn.js";
 import { resolveGitContentRoot } from "../../core/write-source.js";
 import { withAssetMutationLease } from "../../indexer/index-writer-lock.js";
-import { akmIndex } from "../../indexer/indexer.js";
+import { akmIndex, runEmbeddingPass } from "../../indexer/indexer.js";
 import { compareAndSwapLockfileSnapshot, publishLockfileUpdate, readLockfile, readLockfileForUpdate, } from "../../integrations/lockfile.js";
 import { parseRegistryRef } from "../../registry/resolve.js";
 import { sha256Hex } from "../../runtime.js";
@@ -350,11 +350,19 @@ export async function akmRemove(input) {
         },
     };
 }
-/** Read the current index generation without creating or hydrating anything. */
+/**
+ * Read the current index generation without creating or hydrating anything.
+ * This path never ran an embedding pass (#954, field-report follow-up), so it has no
+ * `verification` to report — {@link buildUpdateResponse} falls back to the
+ * two facts it can actually know (whether semantic search is configured on
+ * at all) rather than fabricating verification numbers (`entryCount: 0`,
+ * `ok: true`) for a run that never verified anything.
+ */
 function readCurrentIndexSummary() {
     const db = openReadonlyExistingDatabase(getDbPath());
-    if (!db)
+    if (!db) {
         return { mode: "incremental", totalEntries: 0, directoriesScanned: 0, directoriesSkipped: 0 };
+    }
     try {
         return {
             mode: "incremental",
@@ -388,6 +396,12 @@ function buildUpdateResponse(stashDir, target, all, processed, opts) {
             directoriesScanned: index.directoriesScanned,
             directoriesSkipped: index.directoriesSkipped,
             ...(index.scanComplete !== undefined ? { scanComplete: index.scanComplete } : {}),
+            // A real embedding pass (`akmIndex`/`runEmbeddingPass`) reports its own
+            // verified `semanticStatus`. When no pass ran this update (the
+            // no-op/nothing-configured fallback) the only two facts known without
+            // fabricating a verification are whether semantic search is off at all
+            // or, if not, that its state is simply unverified this run.
+            semanticStatus: index.verification?.semanticStatus ?? (finalConfig.semanticSearchMode === "off" ? "disabled" : "pending"),
         },
     };
 }
@@ -499,6 +513,45 @@ function closeUnifiedUpdateTransaction(transaction, committed) {
             : `[akm bundle update] rolled back, but closing its database handles failed: ${String(closeError)}`);
     }
 }
+/**
+ * Run the embedding phase AFTER the coordinator's atomic commit, on its own
+ * fresh connection (#954). Before this, `akmUpdate` called
+ * `akmIndex()` for its embedding phase too, INSIDE this same unified
+ * `BEGIN IMMEDIATE` — so every per-batch commit the materializer opened
+ * nested as an unobservable SAVEPOINT, and a SIGKILL mid-run lost every
+ * embedding of the run rather than just the one in flight. The
+ * ambient-transaction drift guard (#954) now rejects that outright, so
+ * `akmIndex`'s own embedding phase is skipped for a deferred update
+ * transaction and this runs instead, once content/lock/index/state are
+ * already durably committed.
+ *
+ * A failing pass (provider down, timeout) does NOT fail the update: the
+ * bundle content and index are already committed successfully, exactly like
+ * a plain `akm index` whose embedding phase fails — only the reported
+ * `verification` reflects the shortfall (`semanticStatus: "blocked"`).
+ */
+async function runPostCommitEmbeddingPass(index) {
+    const config = loadConfig();
+    let db;
+    try {
+        const embeddingDim = config.embedding?.dimension;
+        db = openIndexDatabase(getDbPath(), embeddingDim ? { embeddingDim } : undefined);
+        const { verification } = await runEmbeddingPass({ db, config, onProgress: () => { } });
+        return { ...index, verification };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        warn(`[akm bundle update] post-commit embedding pass failed: ${message}`);
+        return {
+            ...index,
+            verification: { ...index.verification, ok: false, semanticStatus: "blocked", message },
+        };
+    }
+    finally {
+        if (db)
+            closeDatabase(db);
+    }
+}
 function pathAtOrBelow(candidate, root) {
     const relative = path.relative(path.resolve(root), path.resolve(candidate));
     return relative === "" || (relative !== ".." && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative));
@@ -779,14 +832,8 @@ async function publishPreparedPlainUpdate(id, ref, prepared, stashDir, allowInse
                 updateTransactionHook("before-commit", id, { db: transaction.db });
                 commitUnifiedUpdateTransaction(transaction);
                 committed = true;
-                try {
-                    transaction.deferred.afterCommit?.();
-                }
-                catch (error) {
-                    warn(`[akm bundle update] committed, but semantic status refresh failed: ${String(error)}`);
-                }
                 prepared.publication?.commit();
-                return index;
+                return await runPostCommitEmbeddingPass(index);
             }
             catch (error) {
                 let recoveryError = transaction ? rollbackUnifiedUpdateTransaction(transaction) : undefined;
@@ -1093,12 +1140,6 @@ async function updateManagedInstall(managed, force, yes, stashDir, allowInsecure
                 updateTransactionHook("before-commit", managed.installId, { db: transaction.db });
                 commitUnifiedUpdateTransaction(transaction);
                 committed = true;
-                try {
-                    transaction.deferred.afterCommit?.();
-                }
-                catch (error) {
-                    warn(`[akm bundle update] committed, but semantic status refresh failed: ${String(error)}`);
-                }
             }
             catch (error) {
                 let recoveryError = transaction ? rollbackUnifiedUpdateTransaction(transaction) : undefined;
@@ -1146,6 +1187,7 @@ async function updateManagedInstall(managed, force, yes, stashDir, allowInsecure
                 }
             }
             prepared.publication?.commit();
+            index = await runPostCommitEmbeddingPass(index);
             if (movedRoot) {
                 const currentConfig = loadConfig();
                 const currentLocks = readLockfile();

package/dist/commands/sources/stash-cli.js

@@ -47,6 +47,8 @@ import { akmIndex } from "../../indexer/indexer.js";
 import { getHyphenatedBoolean, getOutputMode } from "../../output/context.js";
 import { inferAssetName, mergeXrefsIntoContent, readKnowledgeInput, resolveSupersedesForWrite, resolveSupersedesWriteTarget, resolveXrefsForWrite, writeMarkdownAsset, } from "../read/knowledge.js";
 import { assembleInfo } from "./info.js";
+/** Matches the high-frequency per-committed-batch progress line (#954), excluded from non-verbose JSON-mode stderr. */
+const EMBEDDED_BATCH_PROGRESS_PATTERN = /^Embedded \d+\/\d+ entries\.$/;
 export const indexCommand = defineCommand({
     meta: { name: "index", description: "Build search index (incremental by default; --full forces full reindex)" },
     args: {
@@ -98,6 +100,10 @@ export const indexCommand = defineCommand({
                     skipped: {
                         reason: "lock-held",
                         pid: lockAcquisition.holder.pid,
+                        // #956: the launcher pid (when known) alongside the pid that
+                        // actually holds the lock — every process listing and task log
+                        // shows the launcher pid, not the bun/node child's.
+                        launcherPid: lockAcquisition.holder.launcherPid,
                         startedAt: lockAcquisition.holder.startedAt,
                     },
                 });
@@ -137,6 +143,17 @@ export const indexCommand = defineCommand({
                             spin.stop(`${progressPrefix}${message}`);
                             spin.start(`${progressPrefix}${message}`);
                         }
+                        else if (!EMBEDDED_BATCH_PROGRESS_PATTERN.test(message)) {
+                            // Non-verbose, non-text (JSON/yaml/etc) mode: silence used to be
+                            // total until the run finished (#954) — a stalled
+                            // run looked identical to "nothing written". Phase-start
+                            // messages and the embedding heartbeat now reach stderr here
+                            // too; the high-frequency per-batch `Embedded N/M entries.`
+                            // line (emitted after every committed batch)
+                            // is deliberately excluded — that would be spam, not a
+                            // heartbeat.
+                            info(`[index:${phase}] ${progressPrefix}${message}`);
+                        }
                     },
                     signal: controller.signal,
                 });

package/dist/core/config/schema/embedding.js

@@ -33,10 +33,51 @@ export const EmbeddingConnectionConfigSchema = z
     // `akm index` when ensureSchema rejects it (§24.2 "Semantic" gate).
     dimension: positiveInt.max(4096).optional(),
     localModel: z.string().min(1).optional(),
+    /**
+     * Per-document token cap applied BEFORE batching (default 512,
+     * `DEFAULT_MAX_INPUT_TOKENS` in `src/llm/embedders/remote.ts`, #956).
+     * The materializer truncates a document's embedded text to
+     * this cap (head only, unicode-safe) instead of skipping it outright, so
+     * one oversized entry can no longer fail a whole batch. Distinct from
+     * `maxTokens` below, which bounds a whole HTTP REQUEST (many documents);
+     * this bounds one DOCUMENT.
+     */
+    maxInputTokens: positiveInt.optional(),
+    /**
+     * Client-side per-request token budget — how many documents' estimated
+     * tokens fit in one HTTP request (default `DEFAULT_TOKEN_BUDGET` = 8000
+     * in `src/llm/embedders/remote.ts`). With the 512-token `maxInputTokens`
+     * cap above, a request carries about 16 documents by default.
+     */
     maxTokens: positiveInt.optional(),
     batchSize: positiveInt.optional(),
     chunkSize: positiveInt.optional(),
+    /**
+     * Ollama's `num_ctx` ONLY (#956) — sent verbatim as
+     * `options.num_ctx` on the native `/api/embed` request. It no longer also
+     * feeds the client-side request token budget (`maxTokens` above): the two
+     * used to share this one field, so setting it for the server's context
+     * window silently changed request batching too.
+     */
     contextLength: positiveInt.optional(),
     ollamaOptions: EmbeddingOllamaOptionsSchema.optional(),
+    /**
+     * Per-request timeout in milliseconds for a remote embedding request
+     * (default 120_000, `DEFAULT_EMBEDDING_TIMEOUT_MS` in
+     * `src/llm/embedders/remote.ts`). The prior fixed 30s cut off a slow
+     * local model server on a large token-bounded batch mid-response, with
+     * no retry — every batch that hit it was silently dropped (#954).
+     */
+    timeoutMs: positiveInt.optional(),
+    /**
+     * Overrides the fixed in-flight request window (#954, added after field
+     * evidence from multi-slot local servers). Bounded 1-16. Unset keeps
+     * today's default: 1 for a loopback endpoint, 2 for a remote one
+     * (`resolveEmbeddingConcurrency`, `src/llm/embedders/remote.ts`). Set it
+     * only for an endpoint that genuinely serves parallel requests (llama.cpp
+     * `--parallel N`, vLLM) — request SIZE (`batchSize`, `maxTokens`/
+     * `contextLength`) remains the first throughput lever.
+     */
+    concurrency: positiveInt.max(16).optional(),
 })
     .passthrough();