akm-cli 0.9.15-beta.2 → 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.2] - 2026-09-09
+## [0.9.15-beta.3] - 2026-09-10
 
 ### Added
 
@@ -268,6 +268,17 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
   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
 
@@ -322,6 +333,17 @@ 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.
+- **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
@@ -432,6 +454,12 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
   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
 
@@ -533,6 +561,14 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
   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
@@ -562,6 +598,29 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
   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/cli.js

@@ -295,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 }) {
@@ -556,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: {

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 },
+    };
+}

package/dist/commands/health.js

@@ -27,6 +27,7 @@ import { buildImproveSkipSummary, computeWallTimeStats, countAgentFailureReasons
 import { emptyLlmUsageAggregate, readLlmUsageAggregate } from "./health/llm-usage.js";
 import { computeDegradationMetrics, computeDenominatorFixedCoverage, computeEnrichmentMintingRollup, probeStateDbRoundTrip, } from "./health/metrics.js";
 import { collectPluginStalenessAdvisories } from "./health/plugin-staleness.js";
+import { collectSchedulerBinaryAdvisory } from "./health/scheduler-binary.js";
 import { collectStashExposureAdvisory } from "./health/stash-exposure.js";
 import { collectSurfacesAdvisories } from "./health/surfaces.js";
 import { buildPerRunSummaries } from "./health/task-runs.js";
@@ -542,6 +543,12 @@ export async function akmHealth(options = {}) {
         // above — started here, alongside it, and awaited later.
         const versionDriftPromise = collectVersionDriftAdvisory(Boolean(options.probe), { cliVersion: pkgVersion });
         versionDriftPromise.catch(() => undefined);
+        // #953: same --probe-gated, best-effort discipline as versionDriftPromise
+        // above.
+        const schedulerBinaryDriftPromise = collectSchedulerBinaryAdvisory(Boolean(options.probe), {
+            cliVersion: pkgVersion,
+        });
+        schedulerBinaryDriftPromise.catch(() => undefined);
         const taskHistory = gatherTaskHistoryPhase(db, logsDb, since, stateDbPath, now);
         const { tableNames, missingTables, probe } = taskHistory;
         const { egressConfigView, thinkingOffEngines } = gatherEgressConfigPhase();
@@ -559,6 +566,7 @@ export async function akmHealth(options = {}) {
         const improveRunsInLookbackWindow = countImproveRunsSince(db, engineLastUsedSinceIso);
         const engineProbes = await engineProbesPromise;
         const versionDrift = await versionDriftPromise;
+        const schedulerBinaryDrift = await schedulerBinaryDriftPromise;
         // Read once, shared by the `thinking-control` check (#949) and the
         // `metrics.llmUsage` report field below — same window, same aggregate.
         const llmUsage = readLlmUsageAggregate(stateDbPath, since);
@@ -592,6 +600,7 @@ export async function akmHealth(options = {}) {
             activeImproveStrategyEngines,
             engineLastUsed,
             improveRunsInLookbackWindow,
+            schedulerBinaryDrift,
         };
         for (const check of HEALTH_CHECKS) {
             const result = check.run(checkContext);

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

@@ -45,13 +45,12 @@ export const EmbeddingConnectionConfigSchema = z
     maxInputTokens: positiveInt.optional(),
     /**
      * Client-side per-request token budget — how many documents' estimated
-     * tokens fit in one HTTP request (default `DEFAULT_TOKEN_BUDGET` = 8000
+     * tokens fit in one HTTP request (default `DEFAULT_TOKEN_BUDGET` = 6000
      * in `src/llm/embedders/remote.ts`). With the 512-token `maxInputTokens`
-     * cap above, a request carries about 16 documents by default.
+     * cap above, a request carries about 11 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

package/dist/core/errors.js

@@ -82,6 +82,7 @@ const USAGE_HINTS = {
 const TRANSIENT_HINTS = {
     RUN_LEASE_HELD: "Wait for the named engine invocation to finish or for the lease to expire, then retry. `akm workflow status <id>` shows the current lease.",
     STATE_DB_CONTENDED: "Another akm process is writing state.db right now. Wait a few seconds and retry; commands that support --skip-if-locked can skip instead of failing.",
+    INDEX_DB_CONTENDED: "Another akm process is writing index.db; retry shortly, or pass --skip-if-locked on scheduled runs.",
 };
 /** Default hint for each NotFoundError code. */
 const NOT_FOUND_HINTS = {

package/dist/indexer/indexer.js

@@ -7,12 +7,14 @@ import { detectAdapterId } from "../core/adapter/detect-adapter.js";
 import { adapterForId } from "../core/adapter/registry.js";
 import { isHttpUrl, toErrorMessage } from "../core/common.js";
 import { concurrentMap } from "../core/concurrent.js";
-import { ConfigError } from "../core/errors.js";
+import { AkmError, ConfigError, TransientError } from "../core/errors.js";
+import { probeLock } from "../core/file-lock.js";
 import { defaultConcurrencyForEndpoint } from "../core/loopback.js";
 import { classifyPathAccess, describeInaccessiblePath } from "../core/path-access.js";
 import { getDbPath } from "../core/paths.js";
 import { SCRIPT_EXTENSIONS } from "../core/recognition-util.js";
-import { withStateDb } from "../core/state-db.js";
+import { formatLockHolderPid } from "../core/run-lock.js";
+import { isSqliteContentionError, withStateDb } from "../core/state-db.js";
 import { isVerbose, warn, warnOnce, warnVerbose } from "../core/warn.js";
 import { disposeLoweredExecutionDispatchLease, } from "../integrations/agent/execution-lowering.js";
 import { isLlmFeatureEnabled } from "../llm/feature-gate.js";
@@ -28,6 +30,7 @@ import { upsertUtilityScore } from "../storage/repositories/index-utility-reposi
 import { getEmbeddingCount, isVecAvailable, isVecFastPathReady, warnIfVecMissing, } from "../storage/repositories/index-vec-repository.js";
 import { assertIndexedWorkflowSourceIdentity, WorkflowSourceIdentityError } from "../workflows/source-files.js";
 import { deleteStoredGraph } from "./db/graph-db.js";
+import { indexRebuildLockPath } from "./index-rebuild-lock.js";
 import { deriveEntryProvenance, deriveInstallations } from "./installations.js";
 import { indexedPathMatchesOwner, resolveAdapterConceptOwner, } from "./lookup/adapter-concept-owner.js";
 import { generateEmbeddingsForDb } from "./materialize-embeddings.js";
@@ -371,6 +374,44 @@ let akmIndexOverride;
 export function _setAkmIndexForTests(fake) {
     akmIndexOverride = fake;
 }
+/**
+ * Read-only description of the rebuild lock's current holder, appended to a
+ * reclassified index.db contention message when known (field follow-up to
+ * #956). `probeLock` only inspects the sentinel — it never acquires or
+ * mutates it — so this is safe to call from inside an error path.
+ */
+function describeIndexRebuildLockHolder() {
+    const probe = probeLock(indexRebuildLockPath());
+    if (probe.state !== "held")
+        return "";
+    return ` The rebuild lock is currently held by pid ${formatLockHolderPid({
+        pid: probe.holderPid,
+        launcherPid: probe.launcherPid ?? null,
+    })}.`;
+}
+/**
+ * Reclassify a contention-shaped error escaping the walk, index, or
+ * embedding phase into a retryable-shortly `TransientError` (field
+ * follow-up to #956, dev-team field review 2026-09-10): a concurrent writer
+ * (another `akm index`, a source-update embedding pass, the per-command
+ * background reindex) can make index.db busy, and the raw SQLite driver
+ * error ("database is locked") used to escape as exit 70
+ * (internal/unclassified) instead of the "retry shortly" contract exit 75
+ * gives a scheduler to branch on — mirroring `STATE_DB_CONTENDED`'s
+ * precedent for state.db (`core/state-db.ts`). Reuses the ONE shared
+ * classifier, `isSqliteContentionError`, rather than a second one. An error
+ * that is already a classified akm error (e.g. a `STATE_DB_CONTENDED`
+ * TransientError from an inner state.db write) is never re-wrapped — only a
+ * raw, unclassified error matching the shared contention shape is
+ * reclassified. Every other error is rethrown unchanged.
+ */
+export function reclassifyIndexDbContention(error) {
+    if (error instanceof AkmError || !isSqliteContentionError(error))
+        return error;
+    const contended = new TransientError(`akm's index database is busy (another akm process is writing it); retry shortly.${describeIndexRebuildLockHolder()}`, "INDEX_DB_CONTENDED");
+    contended.cause = error;
+    return contended;
+}
 export async function akmIndex(options) {
     try {
         const override = akmIndexOverride;
@@ -387,7 +428,7 @@ export async function akmIndex(options) {
                 // rollback before closing its borrowed unified handle.
             }
         }
-        throw error;
+        throw reclassifyIndexDbContention(error);
     }
 }
 let indexTransactionHookForTests;

package/dist/indexer/materialize-embeddings.js

@@ -136,8 +136,14 @@ function deriveObservedEmbeddingIdentity(embedding, observedModel, observedVecto
  * direct `RemoteEmbedder`) so every embedder branch — remote, local,
  * deterministic, and test overrides via `_setEmbedderForTests` — is
  * exercised identically to the main embedding pass.
+ *
+ * `maxInputTokens` must be the SAME cap the main pass below applies via
+ * {@link capEmbeddingText} — the stored vector for each sampled entry was
+ * produced from its capped text, so comparing against a fresh vector of the
+ * uncapped text would compare unlike inputs for any entry over the cap
+ * (#955).
  */
-async function runEmbeddingCanary(db, config, signal) {
+async function runEmbeddingCanary(db, config, signal, maxInputTokens) {
     const samples = sampleEmbeddedEntriesForCanary(db, CANARY_SAMPLE_SIZE);
     if (samples.length === 0) {
         return { outcome: "keep", verified: false, viaIdentityMatch: false };
@@ -146,7 +152,15 @@ async function runEmbeddingCanary(db, config, signal) {
     const skips = [];
     let canaryVectors;
     try {
-        canaryVectors = await embedBatch(samples.map((sample) => sample.searchText), config.embedding, signal, (skip) => skips.push(skip), (_indices, _embeddings, model) => {
+        canaryVectors = await embedBatch(
+        // #955: the stored vector for each sample was produced from
+        // capEmbeddingText(searchText, maxInputTokens) — the main pass below
+        // caps every document before embedding it. The canary must re-embed
+        // the SAME capped text, or an entry over the cap compares a fresh
+        // vector of a different input against a stored vector of the capped
+        // one, and a genuine model match can read as a rebuild-worthy
+        // mismatch for reasons unrelated to the model.
+        samples.map((sample) => capEmbeddingText(sample.searchText, maxInputTokens).text), config.embedding, signal, (skip) => skips.push(skip), (_indices, _embeddings, model) => {
             if (model)
                 observedModel = model;
         });
@@ -252,6 +266,10 @@ export async function generateEmbeddingsForDb(db, config, onProgress, signal, en
     let targetEntryIds = entryIds;
     /** Set only on an actual rebuild, so the up-front "Re-embedding N entries" line names why. */
     let rebuildReason;
+    // Resolved once and reused by both the canary (below) and the main pass's
+    // cap loop (further down) — the same cap must apply to both, or the canary
+    // compares a differently-capped text against the stored vector (#955).
+    const maxInputTokens = config.embedding?.maxInputTokens ?? DEFAULT_MAX_INPUT_TOKENS;
     if (opts?.forceReembed) {
         // `akm index --reembed`: an explicit operator override, skips the canary
         // entirely. The new fingerprint (and identity, now stale/unknown until
@@ -272,7 +290,7 @@ export async function generateEmbeddingsForDb(db, config, onProgress, signal, en
         rebuildReason = "forced by --reembed";
     }
     else if (storedFingerprint && storedFingerprint !== currentFingerprint) {
-        const decision = await runEmbeddingCanary(db, config, signal);
+        const decision = await runEmbeddingCanary(db, config, signal, maxInputTokens);
         if (decision.outcome === "unverifiable") {
             // Destroying a good index because the server happens to be down right
             // now is worse than leaving a rename unverified until the next run —
@@ -377,12 +395,12 @@ export async function generateEmbeddingsForDb(db, config, onProgress, signal, en
             return reusedCount > 0 ? { success: true, vecInsertFailures: vecFailedCount } : { success: true };
         }
         // Cap each document's embedded text at
-        // embedding.maxInputTokens (default DEFAULT_MAX_INPUT_TOKENS) instead of
-        // ever failing a whole batch over one oversized entry — truncation keeps
-        // the head of the text, unicode-safe. A document is skipped only when its
+        // embedding.maxInputTokens (default DEFAULT_MAX_INPUT_TOKENS, resolved
+        // once above so the canary uses the identical cap) instead of ever
+        // failing a whole batch over one oversized entry — truncation keeps the
+        // head of the text, unicode-safe. A document is skipped only when its
         // head is empty (the impossible case: nothing left to embed), never
         // merely for being long.
-        const maxInputTokens = config.embedding?.maxInputTokens ?? DEFAULT_MAX_INPUT_TOKENS;
         let truncatedCount = 0;
         const texts = [];
         const pendingEntries = [];
@@ -529,6 +547,23 @@ export async function generateEmbeddingsForDb(db, config, onProgress, signal, en
                     }
                     return;
                 }
+                // #954: a "budget-lowered" event is the same kind of notice as
+                // "retrying" above — the run's first context-size rejection just
+                // shrank the request budget for everything not yet dispatched, but
+                // THIS rejected batch's own indices are still being split and
+                // retried by the embedder (their real stored/failed outcome lands in
+                // a later onBatch call). Nothing here has settled, so it must never
+                // touch storage, only report the notice — one line, at most once per
+                // run.
+                if (outcome?.outcome === "budget-lowered") {
+                    if (reportPerBatchLine) {
+                        onProgress({
+                            phase: "embeddings",
+                            message: `[embed] batch ${outcome.batchIndex}/${outcome.batchCount}: ${outcome.docCount} docs, ${outcome.requestTokens.toLocaleString()} tokens → ${outcome.reason}`,
+                        });
+                    }
+                    return;
+                }
                 if (model)
                     observedModel = model;
                 // A batch that delivered at least one real embedding proves the
@@ -542,7 +577,8 @@ export async function generateEmbeddingsForDb(db, config, onProgress, signal, en
                 }
                 db.transaction(() => {
                     for (let k = 0; k < indices.length; k++) {
-                        const entry = pendingEntries[indices[k]];
+                        const index = indices[k];
+                        const entry = pendingEntries[index];
                         if (!entry)
                             continue;
                         const embedding = batchEmbeddings[k];
@@ -555,7 +591,13 @@ export async function generateEmbeddingsForDb(db, config, onProgress, signal, en
                         const result = upsertEmbedding(db, entry.id, embedding);
                         if (result.stored) {
                             storedCount++;
-                            storedTokens += estimateTokenCount(entry.searchText);
+                            // #954: sum the estimate of the text actually sent —
+                            // `texts[index]` is the capped string `embedBatch` was handed,
+                            // parallel to `pendingEntries` by construction above (the
+                            // `entry` guard covers both) — not `entry.searchText`, which is
+                            // the pre-cap original and overstates throughput for every
+                            // entry over the cap.
+                            storedTokens += estimateTokenCount(texts[index]);
                         }
                         else {
                             skippedCount++;