akm-cli 0.9.1 → 0.9.2-alpha.2

package/dist/integrations/lockfile.js

@@ -78,34 +78,24 @@ function assertLockfilePathReadable(target) {
         "records, and writing over them would destroy every bundle they track. Fix the ownership or mode of that " +
         "path (or point AKM_DATA_DIR / XDG_DATA_HOME somewhere this user owns) and retry.", "DATA_DIR_UNREADABLE");
 }
-/**
- * Like {@link readLockfile}, but THROWS instead of silently degrading to `[]`
- * when the on-disk lockfile exists yet is not parseable JSON or not a JSON
- * array (R-012).
- *
- * `readLockfile`'s fail-open contract is intentional for READ paths — a
- * corrupt lock degrades a managed bundle to "unmanaged" rather than erroring
- * every read-only command (`list`, `installed-stashes`, …). But
- * {@link upsertLockEntry} and {@link removeLockEntry} read the current
- * entries and then WRITE `[...entries, change]` back out; if that read
- * silently returned `[]` for a corrupt file, the write would silently
- * replace the corrupt file with one containing only the single new/changed
- * entry — permanently destroying every other surviving lock record. Write
- * paths use this strict variant so a corrupt lockfile fails the operation
- * loudly (matching the guard `mergeLockEntriesSync` already applies) instead
- * of quietly deleting user state. A missing file is NOT corruption — there
- * is nothing to preserve, so that case still returns `[]`. Entries that fail
- * per-entry validation are still tolerated (filtered out), matching
- * `readLockfile`'s existing shape-tolerant behavior.
- */
-function readLockfileOrThrow() {
+function readLockfileSnapshotOrThrow() {
     const lockfilePath = getLockfilePath();
+    let fd;
     let raw;
+    let mode;
     try {
-        raw = fs.readFileSync(lockfilePath, "utf8");
+        // One descriptor owns both byte and metadata observation so a rename or
+        // chmod between separate path-based calls cannot synthesize a generation
+        // that never existed on disk.
+        fd = fs.openSync(lockfilePath, "r");
+        raw = fs.readFileSync(fd, "utf8");
+        mode = fs.fstatSync(fd).mode & 0o777;
     }
     catch (err) {
         rethrowIfTestIsolationError(err);
+        if (err.code === "ENOENT") {
+            return { entries: [], raw: null, mode: 0o600 };
+        }
         // "Missing file" is the only failure with nothing to preserve. An
         // UNREADABLE lockfile has everything to preserve and we cannot see it —
         // degrading it to `[]` here is precisely the destructive overwrite this
@@ -114,7 +104,11 @@ function readLockfileOrThrow() {
         // happy path costs no extra syscall and the answer describes the failure
         // we actually got.
         assertLockfilePathReadable(lockfilePath);
-        return [];
+        return { entries: [], raw: null, mode: 0o600 };
+    }
+    finally {
+        if (fd !== undefined)
+            fs.closeSync(fd);
     }
     let parsed;
     try {
@@ -136,7 +130,23 @@ function readLockfileOrThrow() {
         throw new ConfigError(`Refusing to modify lockfile ${lockfilePath}: ${invalid.length} existing entr${invalid.length === 1 ? "y is" : "ies are"} malformed. ` +
             "Fix or remove the file by hand before retrying — those entries would otherwise be lost.", "INVALID_CONFIG_FILE");
     }
-    return parsed.filter(isValidLockfileEntry);
+    return {
+        entries: parsed.filter(isValidLockfileEntry),
+        raw,
+        mode,
+    };
+}
+function readLockfileOrThrow() {
+    return readLockfileSnapshotOrThrow().entries;
+}
+/**
+ * Read the exact lock generation that a source-lifecycle transaction may
+ * replace. Unlike {@link readLockfile}, this refuses corrupt, malformed, or
+ * unreadable state so an update can never treat state it could not snapshot as
+ * an empty generation.
+ */
+export function readLockfileForUpdate() {
+    return readLockfileSnapshotOrThrow();
 }
 /**
  * The materialized content root recorded in the lock for a managed (git/npm)
@@ -147,9 +157,8 @@ function readLockfileOrThrow() {
  * path (`resolveEntryContentDir` in indexer/search) and the command-layer WRITE
  * path (`adaptConfiguredSource` in core/write-source): consulting it first makes
  * a write land in exactly the directory a read walks. Returns `undefined` for a
- * bundle with no lock `localRoot` (e.g. a config migrated from a `sources[]`
- * url, whose provider re-derives the cache path) or a non-managed type, so both
- * callers fall back to the identical provider-path derivation.
+ * bundle with no lock `localRoot` or a non-managed type, so both callers fall
+ * back to the identical provider-path derivation.
  */
 export function lockContentRootFor(bundleId, type) {
     if (!bundleId || (type !== "git" && type !== "npm"))
@@ -191,6 +200,52 @@ export async function compareAndSwapLockfile(expected, desired) {
         release();
     }
 }
+/**
+ * Publish an update from one exact raw + parsed lockfile generation and return
+ * the exact bytes that were written. Formatting-only concurrent edits are a
+ * generation change here: rollback must never overwrite bytes it did not
+ * publish merely because they parse to an equivalent array.
+ */
+export async function publishLockfileUpdate(expected, desired) {
+    const release = await acquireLockSentinel();
+    try {
+        const current = readLockfileSnapshotOrThrow();
+        if (JSON.stringify(current.entries) !== JSON.stringify(expected.entries) ||
+            current.raw !== expected.raw ||
+            current.mode !== expected.mode) {
+            return null;
+        }
+        writeLockfileUnlocked(desired);
+        return readLockfileSnapshotOrThrow();
+    }
+    finally {
+        release();
+    }
+}
+/** Restore an exact raw snapshot after verifying the exact generation we published. */
+export async function compareAndSwapLockfileSnapshot(expected, desired) {
+    const release = await acquireLockSentinel();
+    try {
+        const current = readLockfileSnapshotOrThrow();
+        if (JSON.stringify(current.entries) !== JSON.stringify(expected.entries) ||
+            current.raw !== expected.raw ||
+            current.mode !== expected.mode) {
+            return false;
+        }
+        const lockfilePath = getLockfilePath();
+        if (desired.raw === null) {
+            fs.rmSync(lockfilePath, { force: true });
+        }
+        else {
+            fs.mkdirSync(path.dirname(lockfilePath), { recursive: true });
+            writeFileAtomic(lockfilePath, desired.raw, desired.mode);
+        }
+        return true;
+    }
+    finally {
+        release();
+    }
+}
 export async function upsertLockEntry(entry) {
     const release = await acquireLockSentinel();
     try {
@@ -205,58 +260,6 @@ export async function upsertLockEntry(entry) {
         release();
     }
 }
-/**
- * Synchronously upsert lock entries (merge by id) WITHOUT acquiring the async
- * sentinel — for a caller already holding an exclusive lifecycle lock (e.g.
- * migrate-apply's config lock + maintenance barrier) whose synchronous body
- * cannot await the sentinel's retry loop. No-op for an empty list.
- */
-function readLockEntriesForMigration() {
-    let existing = [];
-    const lockfilePath = getLockfilePath();
-    // `mergeLockEntriesSync` writes `existing` straight back out, so an
-    // unreadable lockfile read as absent would be overwritten with just the
-    // migrator's sparse entries (#791). This is also what
-    // `assertMigrationLockfileReadable` promises to have checked.
-    assertLockfilePathReadable(lockfilePath);
-    if (fs.existsSync(lockfilePath)) {
-        let raw;
-        try {
-            raw = JSON.parse(fs.readFileSync(lockfilePath, "utf8"));
-        }
-        catch (error) {
-            throw new ConfigError(`Cannot merge migration lock entries into unreadable lockfile ${lockfilePath}: ${error instanceof Error ? error.message : String(error)}.`, "INVALID_CONFIG_FILE");
-        }
-        if (!Array.isArray(raw) || !raw.every(isValidLockfileEntry)) {
-            throw new ConfigError(`Cannot merge migration lock entries into malformed lockfile ${lockfilePath}.`, "INVALID_CONFIG_FILE");
-        }
-        existing = raw;
-    }
-    return existing;
-}
-/** Validate the current lockfile before migrate-apply creates its backup or sentinel. */
-export function assertMigrationLockfileReadable() {
-    readLockEntriesForMigration();
-}
-export function mergeLockEntriesSync(entries) {
-    const existing = readLockEntriesForMigration();
-    if (entries.length === 0)
-        return;
-    // MERGE per id, never replace: the migrator's entries are sparse (id/source/
-    // ref/localRoot), while an existing row may carry `resolvedVersion`,
-    // `resolvedRevision`, `integrity`, `installedAt`, … from a real install.
-    // Replacing the whole row discarded the user's recorded resolution/pin and
-    // left later update reporting comparing against an unknown prior version.
-    // Incoming DEFINED fields win; existing fields absent from the incoming
-    // entry are preserved.
-    const byId = new Map(existing.map((e) => [e.id, e]));
-    const merged = entries.map((incoming) => {
-        const prior = byId.get(incoming.id);
-        return prior ? { ...prior, ...incoming } : incoming;
-    });
-    const incomingIds = new Set(entries.map((e) => e.id));
-    writeLockfileUnlocked([...existing.filter((e) => !incomingIds.has(e.id)), ...merged]);
-}
 export async function removeLockEntry(id) {
     // Returning early says "there is no lock record to remove", and the uninstall
     // that called us reports success on that basis. Only an absent data dir earns

package/dist/integrations/session-logs/index.js

@@ -10,7 +10,7 @@ export { extractInlineRefMentions } from "./inline-refs.js";
 // therefore one registry entry, never an edit here.
 //
 // Ordered by canonical id so the pre-derivation provider order
-// ([claude-code, opencode] — visible in e.g. `extract --auto` result order)
+// ([claude, opencode] — visible in e.g. `extract --auto` result order)
 // is preserved deterministically, independent of HARNESS_REGISTRY declaration
 // order (which is pinned for JSON-schema enum stability).
 //
@@ -25,10 +25,7 @@ export { extractInlineRefMentions } from "./inline-refs.js";
 const HARNESSES = [...SESSION_LOG_HARNESSES]
     .sort((a, b) => a.id.localeCompare(b.id))
     .map((h) => h.sessionLogProvider());
-// Reverse invariant (kept from #562): every derived provider's runtime `name`
-// — a plain string the provider implementation sets independently of the
-// harness registry (e.g. `ClaudeCodeProvider`'s `"claude-code"`) — must
-// resolve back, via the id-normalization bridge, to a registry harness whose
+// Every derived provider's `name` must exactly identify a registry harness whose
 // `sessionLogs` capability is set. This is NOT expressible as a compile-time
 // type constraint: `SessionLogHarness.name` is a runtime string with no
 // static link to the `AkmHarness` that produced it, so a typo'd or
@@ -102,9 +99,8 @@ export function aggregateSessionEvents(events) {
  * Extracted as a pure function (harnesses injected) so it is unit-testable
  * without touching the real on-disk session-log locations.
  *
- * `maxSessionsPerHarness` bounds the rich path: `readSession()` reads each
- * session file IN FULL (unlike the legacy flat scan, which only touched files
- * with mtime ≥ sinceMs and skipped non-string content). On a machine with a
+ * `maxSessionsPerHarness` bounds the path: `readSession()` reads each
+ * session file in full. On a machine with a
  * deep `~/.claude/projects` history a 30-day window can hold hundreds of
  * multi-MB session files, and reading+parsing every one in full made the
  * health command (`akm health`, which calls this synchronously) blow past its
@@ -117,16 +113,9 @@ export function collectSessionEvents(harnesses, sinceMs, maxSessionsPerHarness =
     const events = [];
     for (const harness of harnesses) {
         try {
-            // Rich path: enumerate sessions cheaply, then read each one's full
-            // structured event stream. Falls back to readEvents if listSessions
-            // surfaces nothing (e.g. a harness that wired readSession but whose
-            // listSessions returns empty on this machine) so we never regress
-            // coverage relative to the legacy scan.
+            // Enumerate sessions cheaply, then read each one's full structured event
+            // stream. There is no parallel flat-log parser.
             const summaries = harness.listSessions({ sinceMs });
-            if (summaries.length === 0) {
-                events.push(...harness.readEvents({ sinceMs }));
-                continue;
-            }
             // summaries are newest-first; bound the full-file reads (see doc above).
             for (const summary of summaries.slice(0, maxSessionsPerHarness)) {
                 try {

package/dist/integrations/session-logs/provider-base.js

@@ -6,7 +6,7 @@
  *
  * Holds only what the concrete providers genuinely share: safe stat'ing,
  * recursive directory walking, the mtime-filtered file→summary listing loop,
- * the flat JSONL/log line→event scan, and conditional-spread assembly of
+ * and conditional-spread assembly of
  * {@link SessionSummary} refs stamped with the provider's runtime name.
  * Everything platform-specific — file layouts, metadata peeking, SQLite
  * stores, message flattening — stays in the subclasses.
@@ -82,32 +82,4 @@ export class AbstractSessionLogProvider {
         }
         return summaries.sort((a, b) => (b.endedAt ?? 0) - (a.endedAt ?? 0));
     }
-    /**
-     * The legacy flat line scan shared by both providers' `readEvents`: parse
-     * each line as JSON, pull text/session-id through the per-provider
-     * selectors, skip entries whose text is missing or under 10 chars, and
-     * fall back to the file mtime when the entry carries no numeric timestamp.
-     */
-    *logLineEvents(input) {
-        for (const line of input.lines) {
-            try {
-                const entry = JSON.parse(line);
-                const text = input.selectText(entry);
-                if (typeof text !== "string" || text.length < 10)
-                    continue;
-                const sessionId = input.selectSessionId(entry);
-                yield {
-                    harness: this.name,
-                    text,
-                    ts: typeof entry?.timestamp === "number" ? entry.timestamp : input.fallbackTsMs,
-                    sessionId: typeof sessionId === "string" ? sessionId : undefined,
-                    role: typeof entry?.role === "string" ? entry.role : "unknown",
-                    filePath: input.filePath,
-                };
-            }
-            catch {
-                // skip malformed lines
-            }
-        }
-    }
 }

package/dist/llm/client.js

@@ -13,7 +13,7 @@ import { ENV_REFERENCE_PATTERN } from "../core/config/schema/primitives.js";
 import { formatExtraParamsIssue, validateExtraParams } from "../core/extra-params.js";
 import { parseJsonResponse } from "../core/parse.js";
 import { redactErrorBody, redactSensitiveText } from "../core/redaction.js";
-import { warnVerbose } from "../core/warn.js";
+import { warn, warnVerbose } from "../core/warn.js";
 import { DEFAULT_LLM_TIMEOUT_MS } from "../integrations/agent/config.js";
 import { emitLlmUsage, extractUsageTokens, } from "./usage-telemetry.js";
 /** Maximum length of an upstream response excerpt included in thrown errors. */
@@ -211,9 +211,8 @@ async function chatCompletionAttempt(config, messages, options, timeoutMs) {
             throw new Error(formatExtraParamsIssue("LLM extraParams", issue));
     }
     const headers = { "Content-Type": "application/json" };
-    // Resolve ONLY a whole-string env reference. Every live caller already hands
-    // us the materialized credential (materializeLlmConnection / materializeFrozenLlm
-    // resolve `$VAR` upstream, and engine config REQUIRES the symbolic form), so
+    // Resolve ONLY a whole-string env reference. The execution boundary normally
+    // hands us a materialized credential after resolving `$VAR` upstream, so
     // re-running the substitution over a literal key mangled any credential
     // containing `$` — `sk-live$ecret` lost everything from the `$` onward, and
     // the request failed with an opaque 401. The narrow check keeps the symbolic
@@ -240,14 +239,16 @@ async function chatCompletionAttempt(config, messages, options, timeoutMs) {
         : config.provider === "vllm"
             ? { chat_template_kwargs: { enable_thinking: resolvedEnableThinking } }
             : { enable_thinking: resolvedEnableThinking };
+    const reasoningEffortParams = config.reasoningEffort === undefined ? {} : { reasoning_effort: config.reasoningEffort };
     const requestBody = JSON.stringify({
         model: config.model,
         messages,
         temperature: options?.temperature ?? config.temperature ?? 0.3,
         ...(resolvedMaxTokens !== undefined ? { max_tokens: resolvedMaxTokens } : {}),
+        ...config.extraParams,
         ...responseFormat,
         ...thinkingParams,
-        ...config.extraParams,
+        ...reasoningEffortParams,
     });
     // Wall-clock start for per-attempt usage telemetry (#576). Captured here so the
     // emitted duration covers the full request/response/parse cycle of a single
@@ -344,6 +345,10 @@ async function chatCompletionAttempt(config, messages, options, timeoutMs) {
             finishReason: typeof json.choices?.[0]?.finish_reason === "string" ? json.choices[0].finish_reason : undefined,
             ...extractUsageTokens(json.usage),
         };
+        if (resolvedEnableThinking === false && (terminalFields.reasoningTokens ?? 0) > 0) {
+            warn(`[akm] LLM returned ${terminalFields.reasoningTokens} reasoning tokens despite enableThinking: false; ` +
+                'the provider may not honor that control. Configure reasoningEffort: "none" when the provider supports it.');
+        }
         const content = (json.choices?.[0]?.message?.content ?? "").trim();
         const reasoning = (json.choices?.[0]?.message?.reasoning_content ?? "").trim();
         const result = redactSensitiveText(content || reasoning, resolvedKey ? [resolvedKey] : []);

package/dist/llm/embedder.js

@@ -5,7 +5,7 @@ import { embedCacheKey, getCachedEmbedding, setCachedEmbedding } from "./embedde
 import { DETERMINISTIC_EMBED_MODEL_ID, deterministicEmbed, isDeterministicEmbedEnabled, } from "./embedders/deterministic.js";
 import { DEFAULT_LOCAL_MODEL, isTransformersAvailable as isTransformersAvailableReal, LocalEmbedder, } from "./embedders/local.js";
 import { hasRemoteEndpoint, RemoteEmbedder } from "./embedders/remote.js";
-// ── Re-exports (public API) ─────────────────────────────────────────────────
+// ── Shared exports ──────────────────────────────────────────────────────────
 export { clearEmbeddingCache } from "./embedders/cache.js";
 export { _setTransformersLoaderForTests, DEFAULT_LOCAL_MODEL } from "./embedders/local.js";
 let embedderOverrides;
@@ -14,7 +14,7 @@ export function _setEmbedderForTests(fakes) {
     embedderOverrides = fakes;
 }
 /**
- * Check whether the @huggingface/transformers package is importable.
+ * Check whether the external Transformers dependency is available.
  * Delegating wrapper around `./embedders/local`'s probe so tests can swap it
  * via {@link _setEmbedderForTests}.
  */
@@ -25,7 +25,7 @@ export function isTransformersAvailable() {
 }
 // ── Singleton local embedder ────────────────────────────────────────────────
 // `_localEmbedder` is an intentional module-level singleton but constructed
-// lazily on first use. The underlying @huggingface/transformers pipeline is
+// lazily on first use. The underlying Transformers.js pipeline is
 // expensive to initialise (model download + WASM compilation) and is safe to
 // share across calls because it is stateless once created. Deferring
 // construction to first call keeps the module side-effect-free at import time,
@@ -48,7 +48,7 @@ export function resetLocalEmbedder() {
 /**
  * Generate an embedding for the given text.
  * If embeddingConfig has a remote endpoint, uses the configured OpenAI-compatible endpoint.
- * Otherwise falls back to local @huggingface/transformers using the model from
+ * Otherwise falls back to local Transformers.js using the model from
  * `embeddingConfig.localModel` or `DEFAULT_LOCAL_MODEL`.
  *
  * Results are cached in an LRU cache (max ~100 entries) keyed by query text
@@ -128,8 +128,7 @@ export async function embedBatch(texts, embeddingConfig, signal) {
 // ── Similarity ──────────────────────────────────────────────────────────────
 // `cosineSimilarity` was moved to `./embedders/types.ts` so importers
 // (notably `db.ts`) can pull the math function without dragging in this
-// facade and its `@huggingface/transformers` import chain. Re-export
-// preserves the existing public API.
+// module and its Transformers.js import chain.
 export { cosineSimilarity } from "./embedders/types.js";
 // ── Model ID resolution ─────────────────────────────────────────────────────
 /**
@@ -183,7 +182,7 @@ export async function checkEmbeddingAvailability(embeddingConfig) {
         return {
             available: false,
             reason: "missing-package",
-            message: "@huggingface/transformers is not installed.",
+            message: "The @huggingface/transformers dependency is unavailable.",
         };
     }
     try {

package/dist/llm/embedders/local.js

@@ -2,7 +2,7 @@
 // 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/.
 /**
- * Local @huggingface/transformers embedder.
+ * Local embedder backed by the external @huggingface/transformers package.
  *
  * Encapsulates the transformer pipeline lifecycle as instance state on a
  * `LocalEmbedder` so tests can construct fresh instances without leaking
@@ -12,7 +12,6 @@
 import path from "node:path";
 import { getCacheDir } from "../../core/paths.js";
 import { warn } from "../../core/warn.js";
-import { getDirname, resolveModule } from "../../runtime.js";
 /**
  * Default local transformer model for embeddings.
  * `bge-small-en-v1.5` scores higher on MTEB benchmarks than the previous
@@ -23,10 +22,14 @@ export const DEFAULT_LOCAL_MODEL = "Xenova/bge-small-en-v1.5";
 function isBatchTensor(v) {
     return (v !== null &&
         typeof v === "object" &&
-        "data" in v &&
+        v.data instanceof Float32Array &&
         "dims" in v &&
         Array.isArray(v.dims) &&
-        v.dims.length >= 2);
+        v.dims.length === 2 &&
+        v.dims.every((dim) => Number.isInteger(dim) && dim > 0));
+}
+function isEnabledEnvironmentFlag(value) {
+    return /^(?:1|true|yes|on)$/i.test(value?.trim() ?? "");
 }
 const realTransformersLoader = () => import("@huggingface/transformers");
 let transformersLoader = realTransformersLoader;
@@ -51,31 +54,6 @@ const LOCAL_BATCH_SIZE = 32;
 function resolveLocalModelName(overrideModel) {
     return overrideModel || DEFAULT_LOCAL_MODEL;
 }
-/**
- * Detect whether the current process is running from a Bun-compiled binary
- * (i.e. `bun build --compile` produced a single executable). Bun marks the
- * compiled binary with a synthesized `process.execPath` that ends in the
- * binary name rather than `bun`, AND sets a flag we can probe.
- *
- * Used to gate the "install @huggingface/transformers" hint — that advice
- * is impossible to follow from a single-binary install, so we replace it
- * with the only working remediation (switch to npm/Bun install, or turn
- * semantic search off). See #482.
- */
-function isCompiledBinary() {
-    try {
-        const flag = Bun.embeddedFiles;
-        if (flag !== undefined)
-            return true;
-    }
-    catch {
-        // Bun not available (under Node tests, for example) — treat as not-binary.
-    }
-    const exec = (process.execPath || "").toLowerCase();
-    if (exec.endsWith("/akm") || exec.endsWith("\\akm.exe"))
-        return true;
-    return false;
-}
 export class LocalEmbedder {
     defaultModel;
     /**
@@ -102,9 +80,7 @@ export class LocalEmbedder {
     /**
      * Embed a batch of texts. Processes in chunks of `LOCAL_BATCH_SIZE` (32) so
      * the transformers pipeline can run genuine batched inference rather than one
-     * call per text. Falls back to one-at-a-time if the pipeline does not support
-     * array input (older versions of @huggingface/transformers). Each chunk is
-     * checked against the AbortSignal between calls.
+     * call per text. Each chunk is checked against the AbortSignal between calls.
      */
     async embedBatch(texts, signal) {
         if (texts.length === 0)
@@ -119,42 +95,22 @@ export class LocalEmbedder {
                 throw signal.reason instanceof Error ? signal.reason : new Error("embedding interrupted");
             }
             const chunk = texts.slice(i, i + LOCAL_BATCH_SIZE);
-            try {
-                // @huggingface/transformers feature-extraction pipeline accepts a
-                // string[] and returns a batch Tensor (NOT an Array<{data}>).
-                // The Tensor has .data (flat Float32Array, length = batch * dim) and
-                // .dims = [batch, dim]. Slice .data into per-row vectors using .dims.
-                const batchResult = await pipeline(chunk, {
-                    pooling: "mean",
-                    normalize: true,
-                });
-                if (isBatchTensor(batchResult)) {
-                    const dim = batchResult.dims[1];
-                    for (let row = 0; row < chunk.length; row++) {
-                        results.push(Array.from(batchResult.data.subarray(row * dim, (row + 1) * dim)));
-                    }
-                }
-                else if (Array.isArray(batchResult)) {
-                    // Older versions of @huggingface/transformers returned Array<{data}>.
-                    for (const r of batchResult) {
-                        results.push(Array.from(r.data));
-                    }
-                }
-                else {
-                    // Single-text result returned for a chunk — should not happen for
-                    // string[] input, but handle defensively.
-                    throw new Error("unexpected pipeline return shape for batch input");
-                }
+            // @huggingface/transformers 4.2 returns a single batch Tensor. Validate
+            // that exact shape and propagate inference failures without re-executing
+            // the same inputs through a second runtime path.
+            const batchResult = await pipeline(chunk, {
+                pooling: "mean",
+                normalize: true,
+            });
+            if (!isBatchTensor(batchResult)) {
+                throw new Error("unexpected pipeline return shape for batch input");
             }
-            catch {
-                // Fallback: process one-at-a-time (older pipeline versions or mismatched
-                // return type). Fail-open per text: a single failure aborts the chunk.
-                for (const text of chunk) {
-                    if (signal?.aborted) {
-                        throw signal.reason instanceof Error ? signal.reason : new Error("embedding interrupted");
-                    }
-                    results.push(await this.embedWithModel(text, this.defaultModel));
-                }
+            const [batch, dim] = batchResult.dims;
+            if (batch !== chunk.length || batchResult.data.length !== batch * dim) {
+                throw new Error("unexpected pipeline return shape for batch input");
+            }
+            for (let row = 0; row < chunk.length; row++) {
+                results.push(Array.from(batchResult.data.subarray(row * dim, (row + 1) * dim)));
             }
         }
         return results;
@@ -187,25 +143,21 @@ export class LocalEmbedder {
                 let pipeline;
                 try {
                     const mod = await transformersLoader();
+                    // Transformers.js 4.x defaults its filesystem cache underneath the
+                    // installed package and no longer derives it from HF_HOME. Point the
+                    // public runtime setting at our stable cache explicitly so package
+                    // reinstalls and test-sandbox HOME rotation do not re-download the
+                    // model. The exact pinned 4.2 module owns this public environment.
+                    mod.env.cacheDir = process.env.HF_HOME;
+                    if (isEnabledEnvironmentFlag(process.env.HF_HUB_OFFLINE)) {
+                        mod.env.allowRemoteModels = false;
+                    }
                     pipeline = mod.pipeline;
                 }
                 catch (importError) {
                     const msg = importError instanceof Error ? importError.message : String(importError);
-                    if (/Cannot find module|MODULE_NOT_FOUND|Cannot resolve/i.test(msg)) {
-                        // #482: the prebuilt binary build is invoked with
-                        // `bun install --omit optional` (release.yml), so binary users
-                        // can NEVER load @huggingface/transformers. Telling them to
-                        // `bun add` it is a dead-end — there is no install target.
-                        // Detect the binary execution path and give the only working
-                        // remediation: switch to the npm/Bun install of akm-cli, or
-                        // turn off semantic search.
-                        const isBinary = isCompiledBinary();
-                        const hint = isBinary
-                            ? "You are running the prebuilt akm binary, which cannot load optional native dependencies. " +
-                                "To enable semantic search, install akm-cli via Bun: `curl -fsSL https://bun.sh/install | bash && bun install -g akm-cli`. " +
-                                "To keep using the binary, set `semanticSearchMode: off` in your config and use keyword-only FTS."
-                            : "Install it with: `bun add @huggingface/transformers` (or `npm install @huggingface/transformers`).";
-                        throw new Error(`Semantic search requires @huggingface/transformers. ${hint}`);
+                    if (/Cannot find (?:module|package)|MODULE_NOT_FOUND|ERR_MODULE_NOT_FOUND|Cannot resolve/i.test(msg)) {
+                        throw new Error("Semantic search requires @huggingface/transformers. Reinstall akm-cli.");
                     }
                     throw new Error(`Failed to load embedding runtime: ${msg}. Check platform compatibility.`);
                 }
@@ -239,15 +191,12 @@ function shouldRetryWithoutExplicitDtype(error) {
     return /dtype|fp32|precision|quant/i.test(message);
 }
 /**
- * Check whether the `@huggingface/transformers` package can be resolved.
- * Uses the runtime boundary's `resolveModule` so we never load the module
- * (which would trigger heavy WASM/model side-effects) just to test
- * availability. `resolveModule` uses `Bun.resolveSync` on Bun and
- * `require.resolve` on Node.
+ * Check whether the declared Transformers dependency can be resolved without
+ * loading a model.
  */
 export function isTransformersAvailable() {
     try {
-        resolveModule("@huggingface/transformers", getDirname(import.meta.url));
+        import.meta.resolve("@huggingface/transformers");
         return true;
     }
     catch {

package/dist/llm/embedders/types.js

@@ -6,7 +6,7 @@
  *
  * Lives next to {@link EmbeddingVector} so importers (notably `db.ts`)
  * can pull just the math without dragging in the embedder facade and its
- * transitive `@huggingface/transformers` import chain.
+ * transitive Transformers.js runtime import chain.
  *
  * Returns 0 when the vectors have different dimensions — silently
  * computing on a truncated view would produce meaningless scores.