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

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.3] - 2026-09-10
 
 ### 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,82 @@ 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.
+- **`akm health` gains a `scheduler-binary` advisory for scheduler binary
+  drift (#953).** A field report found `akm task sync`'s recorded absolute
+  akm path can go stale after upgrading through a different installer (npm
+  global to a standalone download, or vice versa), leaving a scheduled run
+  invoking the old binary indefinitely with nothing surfacing it. The new
+  `--probe`-gated advisory reads the scheduler's recorded akm invocation —
+  the same binding `task sync`/`task doctor` already read, no crontab text
+  parsing — runs it with `--version`, and `warn`s naming both versions when
+  it differs from the running CLI, pointing at `akm task sync` as the
+  remedy. `unknown` when not probed, no task is installed, or the recorded
+  binary cannot be executed.
 
 ### Changed
 
@@ -245,7 +323,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 +333,34 @@ 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.
+- **The default per-request token budget is lower, and adapts mid-run after a
+  context-size rejection (#954, field report on beta.1).**
+  `embedding.maxTokens`'s default dropped from 8000 to 6000: the 4-chars-per-
+  token estimator undercounts dense technical text by 7-55%, so 8000 regularly
+  overshot a real 8192-token endpoint. On an `akm index` run's first
+  context-size rejection, the effective request budget additionally shrinks to
+  three quarters of its current value (floored at twice
+  `embedding.maxInputTokens`) for every request not yet sent, and one
+  default-level line reports the new value; it never shrinks a second time in
+  the same run. Users who set `embedding.maxTokens` explicitly keep it as the
+  starting point but still benefit from this same-run recovery.
+- **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 +387,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 +441,25 @@ 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.
+- **`embedding.chunkSize` is retired (#954).** Nothing under `src/` ever read
+  it; it was declared in the config schema but had no effect. It is removed
+  from `EmbeddingConnectionConfigSchema` and `schemas/akm-config.json`. The
+  `embedding` object stays `.passthrough()`, so a config that still sets
+  `embedding.chunkSize` keeps loading exactly as before — the key is simply
+  ignored, not rejected or warned about.
 
 ### Fixed
 
@@ -400,6 +539,88 @@ 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.
+- **The end-of-run throughput line now sums the capped text actually sent to
+  the embedding provider (#954).** `storedTokens` accumulated
+  `estimateTokenCount(entry.searchText)` — the entry's pre-cap search text —
+  while the request `embedBatch` received held the text `capEmbeddingText`
+  had already truncated to `embedding.maxInputTokens`, so the reported
+  `tokens/s` figure overstated throughput for every entry over the cap. The
+  final line now sums the estimate of the capped text the batching loop
+  already built, matching what the provider was actually asked to embed.
+- **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.
+- **A concurrent `akm index` without `--skip-if-locked` now fails with a
+  retryable-shortly exit code instead of a raw driver error (#956).**
+  Contention with another writer touching index.db (a second `akm index`, a
+  source add/update's embedding pass, the per-command background reindex)
+  used to exhaust the SQLite driver's retry window and surface as
+  `{"ok":false,"error":"database is locked"}` at exit 70
+  (internal/unclassified). It is now reclassified into a `TransientError`
+  with a dedicated `INDEX_DB_CONTENDED` code (exit 75), naming the rebuild
+  lock's live holder pid when known, mirroring `STATE_DB_CONTENDED`'s
+  precedent (#948) for state.db; the original driver text survives as
+  `cause`. `--skip-if-locked` is unaffected — it already skips gracefully
+  before ever attempting the write.
+- **The fingerprint-rename canary embeds the exact text the stored vector was
+  generated from (#955).** `sampleEmbeddedEntriesForCanary` handed the canary
+  the entry's raw `search_text`, while the main embedding pass caps it to
+  `embedding.maxInputTokens` before ever calling the provider — so for any
+  entry whose search text exceeded the cap, the canary's freshly re-embedded
+  vector came from a different input than the one that produced the stored
+  vector, and the median cosine similarity could fall below the compatibility
+  threshold for reasons unrelated to the model, triggering a needless full
+  purge and rebuild on a same-model rename. The canary now caps each sampled
+  entry's search text the same way, through the same `capEmbeddingText`
+  helper, before requesting its vector.
 
 ## [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";
@@ -293,8 +295,8 @@ const healthCommand = defineCommand({
         probe: {
             type: "boolean",
             default: true,
-            description: "Probe default-llm-engine / configured-engines reachability and check for a newer akm release (on by default).",
-            negativeDescription: "Skip the reachability probes and the update check (for an offline or air-gapped host).",
+            description: "Probe default-llm-engine / configured-engines reachability, check for a newer akm release, and check the scheduler's recorded akm binary version (on by default).",
+            negativeDescription: "Skip the reachability probes, the update check, and the scheduler-binary version check (for an offline or air-gapped host).",
         },
     },
     async run({ args }) {
@@ -554,7 +556,7 @@ export const main = defineCommand({
             "  2   usage error\n" +
             "  4   health warn (akm health only)\n" +
             "  70  internal / unclassified error\n" +
-            "  75  transient (retry shortly — another akm process holds a lock or is writing state.db)\n" +
+            "  75  transient (retry shortly — another akm process holds a lock or is writing state.db or index.db)\n" +
             "  78  config error",
     },
     args: {
@@ -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/health/checks.js

@@ -1164,11 +1164,20 @@ export const HEALTH_CHECKS = [
         run: (ctx) => ctx.versionDrift,
     },
     {
-        // #950: registered last — order is load-bearing (see the HEALTH_CHECKS
-        // doc comment above). Advisory channel, `kind: "deterministic"` — same
+        // #950: advisory channel, `kind: "deterministic"` — same
         // exit-code-gating rationale as thinking-control above.
         name: "engine-last-used",
         channel: "advisory",
         run: (ctx) => projectEngineLastUsedCheck(ctx.activeImproveStrategyEngines, ctx.engineLastUsed, ctx.improveRunsInLookbackWindow, ENGINE_LAST_USED_LOOKBACK_DAYS),
     },
+    {
+        // #953: registered last — order is load-bearing (see the HEALTH_CHECKS
+        // doc comment above). Best-effort scheduler-binary-drift advisory, gated
+        // behind the same --probe/--no-probe flag as engine reachability and
+        // cli-version. Computed once in health.ts (process-spawn IO), projected
+        // here like versionDrift/engineProbes.
+        name: "scheduler-binary",
+        channel: "advisory",
+        run: (ctx) => ctx.schedulerBinaryDrift,
+    },
 ];

package/dist/commands/health/scheduler-binary.js

@@ -0,0 +1,120 @@
+// 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/.
+/**
+ * `scheduler-binary` advisory for `akm health` (#953).
+ *
+ * `akm task sync` records an absolute akm invocation path in the OS
+ * scheduler (`src/tasks/resolve-akm-bin.ts`) because cron/launchd/schtasks
+ * all run jobs with a minimal PATH. A field report showed that path going
+ * stale after upgrading akm through a different installer than the one
+ * active at the last `task sync` (e.g. npm-global to a standalone binary):
+ * the schedule kept invoking a version behind, with nothing in `akm health`
+ * surfacing it, until an unrelated failure (a rejected `secret://` engine
+ * key on the stale binary) surfaced the drift.
+ *
+ * Modelled 1:1 on `version-drift.ts`'s shape: an injectable seam,
+ * best-effort, `--probe`-gated so an air-gapped host's `--no-probe` habit
+ * suppresses this too, and `unknown` on any uncertainty rather than a false
+ * `pass`/`warn`. Reads the scheduler's recorded binding via
+ * `SchedulerBackend.list()` — the same reader `akm task doctor` uses — never
+ * a second crontab/launchd/schtasks text parser.
+ */
+import { spawnSync } from "node:child_process";
+import { selectBackend } from "../../tasks/backends/index.js";
+import { pkgVersion } from "../../version.js";
+/**
+ * Bound on the scheduler-recorded binary's `--version` probe. Matches the
+ * `--version` timeout the engine-reachability checks already use
+ * (checks.ts's `runConfiguredEngineProbe`), so a wedged or missing binary
+ * degrades this advisory to `unknown` in seconds rather than blocking
+ * `akm health --probe`.
+ */
+const SCHEDULER_BINARY_VERSION_PROBE_TIMEOUT_MS = 5_000;
+/**
+ * Build the `scheduler-binary` advisory. `probe` mirrors the
+ * engine-reachability and `cli-version` checks' `--probe`/`--no-probe`
+ * gating: only inspects the scheduler and spawns a process when `true`;
+ * otherwise `unknown` with "not probed", never touching the OS scheduler.
+ */
+export async function collectSchedulerBinaryAdvisory(probe, deps = {}) {
+    const cliVersion = deps.cliVersion ?? pkgVersion;
+    if (!probe) {
+        return {
+            name: "scheduler-binary",
+            kind: "deterministic",
+            status: "unknown",
+            confidence: "high",
+            message: "Scheduler binary version drift was not probed.",
+        };
+    }
+    let installed;
+    try {
+        installed = await (deps.backend ?? selectBackend()).list();
+    }
+    catch (error) {
+        return {
+            name: "scheduler-binary",
+            kind: "deterministic",
+            status: "unknown",
+            confidence: "high",
+            message: `Installed scheduled tasks could not be inspected: ${error instanceof Error ? error.message : String(error)}`,
+        };
+    }
+    // task sync rewrites every installed binding to the same current
+    // invocation atomically, so the first entry's binding represents the
+    // whole schedule under normal operation.
+    const [firstInstalled] = installed;
+    const [binaryPath, ...leadingArgs] = firstInstalled?.binding ?? [];
+    if (!firstInstalled || !binaryPath) {
+        return {
+            name: "scheduler-binary",
+            kind: "deterministic",
+            status: "unknown",
+            confidence: "high",
+            message: "No scheduled task is installed.",
+        };
+    }
+    const binding = firstInstalled.binding;
+    const run = deps.spawnSync ?? spawnSync;
+    let scheduledVersion;
+    try {
+        const result = run(binaryPath, [...leadingArgs, "--version"], {
+            encoding: "utf8",
+            timeout: SCHEDULER_BINARY_VERSION_PROBE_TIMEOUT_MS,
+        });
+        if ((result.status ?? 1) === 0)
+            scheduledVersion = result.stdout?.trim() || undefined;
+    }
+    catch {
+        scheduledVersion = undefined;
+    }
+    if (!scheduledVersion) {
+        return {
+            name: "scheduler-binary",
+            kind: "deterministic",
+            status: "unknown",
+            confidence: "high",
+            message: "The scheduler's recorded akm binary could not be executed.",
+            evidence: { binding },
+        };
+    }
+    if (scheduledVersion === cliVersion) {
+        return {
+            name: "scheduler-binary",
+            kind: "deterministic",
+            status: "pass",
+            confidence: "high",
+            message: `Scheduled tasks are bound to akm v${scheduledVersion}, matching the running CLI.`,
+            evidence: { binding, scheduledVersion, cliVersion },
+        };
+    }
+    return {
+        name: "scheduler-binary",
+        kind: "deterministic",
+        status: "warn",
+        confidence: "high",
+        message: `Scheduled tasks are bound to akm v${scheduledVersion}, but the running CLI is v${cliVersion} — run \`akm task sync\` to rebind the schedule.`,
+        evidence: { binding, scheduledVersion, cliVersion },
+    };
+}