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

package/dist/core/fs-txn.js

@@ -81,7 +81,11 @@ export function txnFileHash(filePath) {
     return txnHash(fs.readFileSync(filePath));
 }
 export function fsyncTxnFile(filePath) {
-    const fd = fs.openSync(filePath, "r");
+    // Open for WRITE. Windows implements fsync as FlushFileBuffers, which
+    // requires write access on the handle — a read-only descriptor fails with
+    // EACCES/EPERM, so every proposal accept and reject failed on that platform.
+    // POSIX accepts "r+" here just as readily as "r".
+    const fd = fs.openSync(filePath, "r+");
     try {
         fs.fsyncSync(fd);
     }
@@ -91,7 +95,16 @@ export function fsyncTxnFile(filePath) {
 }
 export function fsyncTxnDir(dirPath) {
     try {
-        fsyncTxnFile(dirPath);
+        // Read-only, unlike {@link fsyncTxnFile}: a directory cannot be opened for
+        // write on POSIX (EISDIR), and on Windows this whole operation is
+        // unsupported anyway and falls into the catch.
+        const fd = fs.openSync(dirPath, "r");
+        try {
+            fs.fsyncSync(fd);
+        }
+        finally {
+            fs.closeSync(fd);
+        }
     }
     catch {
         // Directory fsync is unavailable on some platforms.

package/dist/core/json-schema.js

@@ -171,6 +171,13 @@ function pushIssue(issues, path, keyword, kind, message) {
 function isPlainObject(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
+/** Values the runtime's reference-equality `enum` check can enforce correctly. */
+function isSupportedEnumValue(value) {
+    return (value === null ||
+        typeof value === "string" ||
+        typeof value === "boolean" ||
+        (typeof value === "number" && Number.isFinite(value)));
+}
 function checkDefinitionNode(schema, path, issues, depth) {
     if (depth > MAX_DEFINITION_DEPTH) {
         pushIssue(issues, path, "(depth)", "malformed", `schema nesting exceeds the depth limit of ${MAX_DEFINITION_DEPTH}`);
@@ -199,8 +206,18 @@ function checkDefinitionNode(schema, path, issues, depth) {
             }
         }
     }
-    if (schema.enum !== undefined && (!Array.isArray(schema.enum) || schema.enum.length === 0)) {
-        pushIssue(issues, [...path, "enum"], "enum", "malformed", `"enum" must be a non-empty array of allowed values`);
+    if (schema.enum !== undefined) {
+        if (!Array.isArray(schema.enum) || schema.enum.length === 0) {
+            pushIssue(issues, [...path, "enum"], "enum", "malformed", `"enum" must be a non-empty array of allowed values`);
+        }
+        else {
+            schema.enum.forEach((value, index) => {
+                if (isSupportedEnumValue(value))
+                    return;
+                pushIssue(issues, [...path, "enum", index], "enum", "unsupported", `"enum" values must be JSON primitives (string, finite number, boolean, or null) in the workflow ` +
+                    `schema subset — object and array enum members cannot be matched by the runtime subset`);
+            });
+        }
     }
     for (const keyword of ["allOf", "anyOf", "oneOf"]) {
         const branches = schema[keyword];

package/dist/core/paths.js

@@ -160,9 +160,23 @@ export function getCacheDir(env = process.env) {
     }
     const home = env.HOME?.trim();
     if (!home)
-        return path.join("/tmp", "akm-cache");
+        return homelessFallbackDir("akm-cache");
     return path.join(home, ".cache", "akm");
 }
+/**
+ * Last-resort directory when neither the XDG variable nor HOME is set.
+ *
+ * Scoped by uid. A fixed `/tmp/akm-<kind>` path is world-shared and entirely
+ * predictable: on a multi-user host the first uid to run akm owns the
+ * directory and every other user then reads and writes the same databases, and
+ * any local user can pre-create the path (or a symlink at it) and wait. Adding
+ * the uid gives each account its own path; the caller still creates it with
+ * restrictive permissions.
+ */
+function homelessFallbackDir(kind) {
+    const uid = typeof process.getuid === "function" ? process.getuid() : undefined;
+    return path.join(os.tmpdir(), uid === undefined ? kind : `${kind}-${uid}`);
+}
 // ── Data directory ───────────────────────────────────────────────────────────
 /**
  * Returns the XDG data directory for akm (`~/.local/share/akm` on Linux/macOS,
@@ -209,7 +223,7 @@ export function getDataDir(env = process.env, platform = process.platform) {
         return path.join(xdgDataHome, "akm");
     const home = env.HOME?.trim();
     if (!home)
-        return path.join("/tmp", "akm-data");
+        return homelessFallbackDir("akm-data");
     return path.join(home, ".local", "share", "akm");
 }
 export function getDbPath(env = process.env) {

package/dist/core/redaction.js

@@ -322,7 +322,7 @@ function addPlainMatches(coverageDelta, text, needle) {
  * unlike {@link redactSensitiveText}, which requires the exact secret value
  * up front, this catches credentials no caller ever knew to list. No
  * truncation is applied; callers that need a length cap (e.g.
- * {@link redactErrorBody} in src/llm/client.ts) apply it themselves.
+ * {@link redactErrorBody}) apply it themselves.
  *
  * Targets:
  *  - `Bearer <token>` headers echoed back by a provider
@@ -367,6 +367,27 @@ export function redactCredentialPatterns(input) {
  * that is a memory-exhaustion hazard reachable from ordinary command output.
  * The encoded-form path never had the bug because it always worked this way.
  */
+/** Max characters of a provider error body worth surfacing in a message. */
+const ERROR_BODY_MAX_LEN = 200;
+/**
+ * Make an HTTP error body safe to put in an error message: pattern-redact
+ * credential shapes, then clip. Provider bodies can echo the credential that
+ * was sent and can be megabytes of HTML, and these messages travel — into
+ * persisted status files, `--json` output, and agent transcripts.
+ *
+ * Lives here rather than beside one transport because every HTTP client in the
+ * codebase needs it; the embeddings transport originally lacked it and leaked
+ * raw 10 MB bodies into `semantic-status.json`.
+ */
+export function redactErrorBody(input) {
+    if (!input)
+        return "";
+    let out = redactCredentialPatterns(input);
+    if (out.length > ERROR_BODY_MAX_LEN) {
+        out = `${out.slice(0, ERROR_BODY_MAX_LEN)}…`;
+    }
+    return out;
+}
 export function redactSensitiveText(text, sensitiveValues) {
     const values = [...new Set(sensitiveValues)]
         .filter((value) => value.length > 0)

package/dist/core/state-db.js

@@ -150,6 +150,7 @@ export function openStateDatabase(dbPath) {
             exec: db.exec.bind(db),
             run: db.run.bind(db),
             transaction: db.transaction.bind(db),
+            loadExtension: db.loadExtension.bind(db),
             get inTransaction() {
                 return db.inTransaction;
             },

package/dist/core/write-source.js

@@ -33,7 +33,7 @@ import { ensureAkmMarkdownType } from "./asset/akm-markdown.js";
 import { assetPathForName, stashDirFor } from "./asset/asset-placement.js";
 import { conceptIdFromTypeName, displayRef } from "./asset/resolve-ref.js";
 import { deriveBundleId } from "./bundle-id.js";
-import { isWithin, resolveStashDir } from "./common.js";
+import { existingFileMode, isWithin, resolveStashDir, writeFileAtomic } from "./common.js";
 import { resolveConfiguredSources } from "./config/config.js";
 import { ConfigError, UsageError } from "./errors.js";
 import { sanitizeCommitMessage } from "./git-message.js";
@@ -333,7 +333,11 @@ export async function writeAssetToSource(source, config, ref, content) {
     const preflight = preflightGitPathMutation(source, filePath);
     try {
         fs.mkdirSync(path.dirname(filePath), { recursive: true });
-        fs.writeFileSync(filePath, normalized, "utf8");
+        // Atomic: truncate-and-rewrite left a window in which a crash, a full disk,
+        // or a concurrent reader saw a half-written or empty asset — destroying user
+        // content that was fine a moment earlier. writeFileAtomic writes a sibling
+        // temp file, fdatasyncs it, and renames over the target.
+        writeFileAtomic(filePath, normalized, existingFileMode(filePath));
         recordWriteTargetPath(source, filePath);
         // #652: run-scoped write provenance — the canonical asset write is the
         // single largest contributor to an improve run's written-path set.
@@ -1003,11 +1007,31 @@ function ensureWritable(source, config) {
         throw new UsageError(`Source "${source.name}" is not writable. Set \`writable: true\` on the source config entry to enable writes.`, "INVALID_FLAG_VALUE");
     }
 }
+/**
+ * MS-DOS device names Windows still reserves in every directory, with or
+ * without an extension (CON, PRN, AUX, NUL, COM1-9, LPT1-9).
+ */
+const WINDOWS_RESERVED_DEVICE_NAMES = new Set([
+    "con",
+    "prn",
+    "aux",
+    "nul",
+    ...Array.from({ length: 9 }, (_, i) => `com${i + 1}`),
+    ...Array.from({ length: 9 }, (_, i) => `lpt${i + 1}`),
+]);
 function resolveAssetFilePath(source, ref) {
     const basename = path.posix.basename(ref.name.replaceAll("\\", "/")).replace(/\.md$/i, "").toLowerCase();
     if (basename === "index" || basename === "log") {
         throw new UsageError(`Reserved concept name "${basename}" cannot be written.`, "INVALID_FLAG_VALUE");
     }
+    // Windows resolves these names as DEVICES no matter the directory or the
+    // extension, so `CON.md` is not a file — a write goes to the console and a
+    // read blocks on console input. Rejected on every platform so a stash stays
+    // portable: an asset authored on Linux must not become unopenable when the
+    // same bundle is used on Windows.
+    if (WINDOWS_RESERVED_DEVICE_NAMES.has(basename)) {
+        throw new UsageError(`Asset name "${basename}" is a reserved Windows device name and cannot be written.`, "INVALID_FLAG_VALUE");
+    }
     const typeDir = stashDirFor(ref.type);
     if (!typeDir) {
         throw new UsageError(`Unknown asset type "${ref.type}". Cannot resolve a write path.`, "INVALID_FLAG_VALUE");

package/dist/indexer/indexer.js

@@ -19,7 +19,7 @@ import { closeDatabase, openExistingDatabase, openIndexDatabase } from "../stora
 import { deleteEntriesByDirAndStash, deleteEntriesByDirExceptKeys, deleteEntriesByIds, deleteEntriesByStashDir, deleteUsageEventsByEntryIds, findEntryIdByRef, getAllEntries, getEmbeddableEntryCount, getEntryCount, getIndexedDirPathsByStashDir, getIndexedStashDirsByDir, relinkUsageEvents, upsertEntry, upsertWorkflowDocument, } from "../storage/repositories/index-entries-repository.js";
 import { rebuildFts } from "../storage/repositories/index-fts-repository.js";
 import { clearStaleCacheEntries } from "../storage/repositories/index-llm-cache-repository.js";
-import { deleteIndexDirState, deleteIndexDirStatesByStashDir, getMeta, setMeta, upsertIndexDirState, } from "../storage/repositories/index-meta-repository.js";
+import { deleteIndexDirState, deleteIndexDirStatesByStashDir, deleteMeta, getMeta, setMeta, upsertIndexDirState, } from "../storage/repositories/index-meta-repository.js";
 import { upsertUtilityScore } from "../storage/repositories/index-utility-repository.js";
 import { getAllEntriesForEmbedding, getEmbeddingCount, isVecAvailable, isVecFastPathReady, purgeEmbeddings, setVecFastPathReady, upsertEmbedding, warnIfVecMissing, } from "../storage/repositories/index-vec-repository.js";
 import { takeWorkflowDocument } from "../workflows/runtime/document-cache.js";
@@ -158,7 +158,12 @@ async function runWalkPhase(ctx) {
 async function runEmbeddingPhase(ctx) {
     const { db, config, signal, onProgress } = ctx;
     throwIfAborted(signal);
-    ctx.embeddingResult = await generateEmbeddingsForDb(db, config, onProgress);
+    // Forward the signal. Without it generateEmbeddingsForDb's abort machinery was
+    // inert — its throwIfAborted checks and the signal it threads into embedBatch
+    // (which RemoteEmbedder passes to every fetch and LocalEmbedder honours between
+    // chunks) never saw a controller. Ctrl-C and the improve budget abort could not
+    // stop the embedding phase, the longest phase of an index run.
+    ctx.embeddingResult = await generateEmbeddingsForDb(db, config, onProgress, signal);
     ctx.timing.tEmbedEnd = Date.now();
 }
 /**
@@ -1357,9 +1362,20 @@ async function generateEmbeddingsForDb(db, config, onProgress, signal) {
     const currentFingerprint = deriveSemanticProviderFingerprint(config.embedding);
     const storedFingerprint = getMeta(db, "embeddingFingerprint");
     if (storedFingerprint && storedFingerprint !== currentFingerprint) {
-        // Model/provider changed → stored vectors are incompatible. Clear them
-        // (same dimension, so keep the vec table); re-embedded by this index run.
-        purgeEmbeddings(db);
+        // Model/provider changed → stored vectors are incompatible. Clear them;
+        // re-embedded by this index run.
+        //
+        // The vec table goes too. "Same dimension, so keep the vec table" only held
+        // for a same-width model swap: entries_vec is a vec0 virtual table declared
+        // at a FIXED width, so after a dimension-changing model change every insert
+        // failed against the old width, and ensureSchema's dim-change rebuild never
+        // fired because it only runs for callers that pass an explicit
+        // embeddingDim. The stale table survived `--full` — the exact remedy the
+        // warning recommended. Clearing the stored dim lets the next ensureSchema
+        // materialize it at the new width; until then the fast-path flag reads
+        // false (no table) and search uses the complete BLOB table.
+        purgeEmbeddings(db, { dropVecTable: true });
+        deleteMeta(db, "embeddingDim");
     }
     try {
         const { embedBatch } = await import("../llm/embedder.js");
@@ -1404,6 +1420,7 @@ async function generateEmbeddingsForDb(db, config, onProgress, signal) {
             let storedCount = 0;
             let skippedCount = 0;
             let vecFailedCount = 0;
+            let vecUnavailableCount = 0;
             db.transaction(() => {
                 for (let i = 0; i < allEntries.length; i++) {
                     const res = upsertEmbedding(db, allEntries[i].id, embeddings[i]);
@@ -1415,6 +1432,8 @@ async function generateEmbeddingsForDb(db, config, onProgress, signal) {
                     }
                     if (res.vec === "failed")
                         vecFailedCount++;
+                    if (res.vec === "unavailable")
+                        vecUnavailableCount++;
                 }
             })();
             if (skippedCount > 0) {
@@ -1424,7 +1443,13 @@ async function generateEmbeddingsForDb(db, config, onProgress, signal) {
             // instead of inferring readiness from stored-BLOB counts. Any failure
             // marks the fast path degraded, routing search to the JS-cosine fallback
             // over the (complete) BLOB table — honest degradation, not a hard failure.
-            setVecFastPathReady(db, vecFailedCount === 0);
+            //
+            // 'unavailable' has to degrade the flag too. It means no vec row was
+            // written at all, so marking the fast path ready left a later open (a
+            // different runtime, or sqlite-vec installed afterwards) trusting an
+            // empty entries_vec and returning zero semantic hits against a fully
+            // populated BLOB table.
+            setVecFastPathReady(db, vecFailedCount === 0 && vecUnavailableCount === 0);
             if (vecFailedCount > 0) {
                 warn(`[embed] ${vecFailedCount} sqlite-vec fast-path insert${vecFailedCount === 1 ? "" : "s"} failed — ` +
                     "semantic search will use the slower JS-cosine fallback over stored embeddings. " +

package/dist/indexer/search/db-search.js

@@ -86,6 +86,21 @@ export function shouldQueryPositiveFeedbackCounts(utilityDecayRaw) {
     return boost > 1.0;
 }
 // ── Main search entrypoint ───────────────────────────────────────────────────
+/**
+ * Whether an embedding provider is actually configured.
+ *
+ * A remote provider needs BOTH endpoint and model. A LOCAL provider needs
+ * neither — `embedding.localModel` selects a transformers model that runs in
+ * process. Checking only the remote pair told every local-provider user that
+ * "no embedding provider is configured" and pointed them at
+ * `akm config set embedding '{"endpoint":...}'`, which is the wrong remedy and
+ * hid the real diagnostic recorded in the semantic status.
+ */
+function hasConfiguredEmbeddingProvider(config) {
+    if (config.embedding?.localModel)
+        return true;
+    return Boolean(config.embedding?.endpoint && config.embedding?.model);
+}
 export async function searchLocal(input) {
     const { query, searchType, limit, stashDir, sources, config } = input;
     const filters = input.filters;
@@ -105,7 +120,7 @@ export async function searchLocal(input) {
         if (rawStatus && rawStatus.providerFingerprint !== currentFingerprint) {
             warnings.push("Embedding config changed. Run 'akm index --full' to rebuild the semantic index with the new provider.");
         }
-        else if (!config.embedding?.endpoint || !config.embedding?.model) {
+        else if (!hasConfiguredEmbeddingProvider(config)) {
             // #480: when semantic mode is `auto` but no embedding provider is
             // configured (e.g. `akm setup --yes` ran without picking one), telling
             // the user to "run akm setup" is misleading — they just did. Surface
@@ -120,7 +135,7 @@ export async function searchLocal(input) {
         }
     }
     if (config.semanticSearchMode === "auto" && semanticStatus === "blocked") {
-        if (!config.embedding?.endpoint || !config.embedding?.model) {
+        if (!hasConfiguredEmbeddingProvider(config)) {
             // F7/A2: same predicate as the `pending` branch above (#480) — a
             // `blocked` status can outlive the provider config that produced it
             // (e.g. the embedding config was later unset). This is not a fault;

package/dist/indexer/walk/walker.js

@@ -123,7 +123,12 @@ function walkStashGit(stashRoot, options) {
     for (const relFile of files) {
         const absPath = path.join(stashRoot, relFile);
         try {
-            if (fs.statSync(absPath).isFile()) {
+            // lstat, not stat: a tracked symlink must not be dereferenced. statSync
+            // follows the link, so a target outside stashRoot would be read and
+            // indexed. The manual walk below already skips symlinks for exactly this
+            // reason; the two walkers have to agree regardless of whether the stash
+            // happens to sit inside a git repo.
+            if (fs.lstatSync(absPath).isFile()) {
                 results.push(buildFileContext(stashRoot, absPath));
             }
         }

package/dist/integrations/agent/detect.js

@@ -74,6 +74,16 @@ const DEFAULT_PATHEXT = ".COM;.EXE;.BAT;.CMD";
  * on win32 or when the env supplies PATHEXT (which is also the seam tests use
  * to cover Windows resolution from a POSIX runner).
  */
+/**
+ * Script shims that `child_process.spawn` cannot execute directly on Windows.
+ *
+ * Node refuses to spawn `.bat`/`.cmd` without a shell (the CVE-2024-27980
+ * hardening), so a detection that returns one of these reports an agent as
+ * available that dispatch then fails to launch. They stay in the candidate
+ * list — a shim is better than reporting the CLI as missing — but they sort
+ * last, so a real `.exe` next to `claude.cmd` wins.
+ */
+const NON_SPAWNABLE_SUFFIXES = new Set([".cmd", ".bat"]);
 function executableSuffixes(envSource) {
     const pathext = envSource.PATHEXT ?? envSource.Pathext ?? envSource.pathext;
     if (process.platform !== "win32" && !pathext)
@@ -83,7 +93,9 @@ function executableSuffixes(envSource) {
         .map((ext) => ext.trim())
         .filter(Boolean)
         .map((ext) => (ext.startsWith(".") ? ext : `.${ext}`));
-    return ["", ...exts];
+    const directlySpawnable = exts.filter((ext) => !NON_SPAWNABLE_SUFFIXES.has(ext.toLowerCase()));
+    const shims = exts.filter((ext) => NON_SPAWNABLE_SUFFIXES.has(ext.toLowerCase()));
+    return ["", ...directlySpawnable, ...shims];
 }
 let detectOverrides;
 /** TEST-ONLY. Swap the detection implementations; pass undefined to restore. */

package/dist/integrations/harnesses/opencode-sdk/sdk-runner.js

@@ -118,6 +118,12 @@ let _testServer = null;
 // Test seam replacing the real `createOpencode` import (see __setServerFactory).
 let _serverFactory = null;
 let _exitHookInstalled = false;
+/**
+ * True once `process.on("exit")` has fired. Close paths consult it because an
+ * exit handler runs after the event loop has stopped: no timer scheduled there
+ * will ever fire, so any cleanup that needs to happen must happen inline.
+ */
+let _processExiting = false;
 /**
  * Test-only seam: inject a fake {@link SdkServer} so `runOpencodeSdk` can be
  * exercised without the real `@opencode-ai/sdk` (which would spin up a server).
@@ -424,6 +430,20 @@ async function createManagedOpencode(options) {
         }
         if (childExited())
             return;
+        if (_processExiting) {
+            // During `process.on("exit")` the event loop is finished, so a timer
+            // scheduled here would never fire and the SIGKILL escalation could not
+            // happen at all — a server child that ignores SIGTERM outlived akm.
+            // Exit handlers must be synchronous, so escalate immediately instead of
+            // waiting out a grace period we have no way to wait for.
+            try {
+                proc.kill("SIGKILL");
+            }
+            catch {
+                /* already dead */
+            }
+            return;
+        }
         closeEscalation = setTimeout(() => {
             closeEscalation = undefined;
             if (childExited())
@@ -525,6 +545,7 @@ async function startServer(profile, sdkConfig, env, registryKey, startupSignal)
     if (!_exitHookInstalled) {
         _exitHookInstalled = true;
         process.once("exit", () => {
+            _processExiting = true;
             void closeServer();
         });
     }

package/dist/integrations/lockfile.js

@@ -126,6 +126,16 @@ function readLockfileOrThrow() {
     if (!Array.isArray(parsed)) {
         throw new ConfigError(`Refusing to modify lockfile ${lockfilePath}: existing content is not a JSON array. Fix or remove the file by hand before retrying — every existing lock entry would otherwise be lost.`, "INVALID_CONFIG_FILE");
     }
+    // Refuse rather than filter. This is the WRITE path's read: everything it
+    // returns is what gets written back, so silently dropping entries that fail
+    // per-entry validation destroyed them on the next write — the same
+    // data-losing overwrite the two refusals above exist to prevent, just at
+    // entry granularity instead of file granularity.
+    const invalid = parsed.filter((entry) => !isValidLockfileEntry(entry));
+    if (invalid.length > 0) {
+        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);
 }
 /**

package/dist/llm/client.js

@@ -9,34 +9,22 @@
  */
 import { fetchWithTimeout, readBodyWithByteCap } from "../core/common.js";
 import { resolveSecret } from "../core/config/config.js";
+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 { redactCredentialPatterns, redactSensitiveText } from "../core/redaction.js";
+import { redactErrorBody, redactSensitiveText } from "../core/redaction.js";
 import { 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 LLM error response body included in thrown errors. */
+/** Maximum length of an upstream response excerpt included in thrown errors. */
 const ERROR_BODY_MAX_LEN = 200;
 /** Stable OpenAI-compatible response-schema name used for every structured call. */
 const JSON_SCHEMA_RESPONSE_NAME = "akm_response";
 /**
- * Redact credential-shaped substrings from an upstream error body before
- * including it in a thrown Error. The body is also trimmed to a fixed length
- * so that a verbose provider response cannot leak large amounts of context.
- *
- * The pattern set itself lives in {@link redactCredentialPatterns}
- * (src/core/redaction.ts) so other output paths (e.g. task run logs) can
- * reuse it without this function's length cap.
+ * Re-exported from src/core/redaction.ts, where it now lives so every HTTP
+ * transport can apply the same hardening — the embeddings client needs it too.
  */
-export function redactErrorBody(input) {
-    if (!input)
-        return "";
-    let out = redactCredentialPatterns(input);
-    if (out.length > ERROR_BODY_MAX_LEN) {
-        out = `${out.slice(0, ERROR_BODY_MAX_LEN)}…`;
-    }
-    return out;
-}
+export { redactErrorBody } from "../core/redaction.js";
 /**
  * Detect a response body that is an HTML document rather than the expected
  * JSON. LM Studio (and similar local providers) can serve their web UI on
@@ -223,7 +211,14 @@ async function chatCompletionAttempt(config, messages, options, timeoutMs) {
             throw new Error(formatExtraParamsIssue("LLM extraParams", issue));
     }
     const headers = { "Content-Type": "application/json" };
-    const resolvedKey = resolveSecret(config.apiKey);
+    // 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
+    // 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
+    // form working for any direct caller that still passes one.
+    const resolvedKey = ENV_REFERENCE_PATTERN.test(config.apiKey ?? "") ? resolveSecret(config.apiKey) : config.apiKey;
     if (resolvedKey) {
         headers.Authorization = `Bearer ${resolvedKey}`;
     }

package/dist/llm/embedder.js

@@ -65,12 +65,32 @@ export async function embed(text, embeddingConfig, signal) {
     const cached = getCachedEmbedding(key);
     if (cached)
         return cached;
-    const result = embeddingConfig && hasRemoteEndpoint(embeddingConfig)
-        ? await new RemoteEmbedder(embeddingConfig).embed(text, signal)
-        : await getLocalEmbedder().embed(text, signal);
+    const result = await embedOnce(text, embeddingConfig, signal);
     setCachedEmbedding(key, result);
     return result;
 }
+/**
+ * Resolve a single embedding through the configured provider.
+ *
+ * The local branch must honour `localModel` exactly as {@link embedBatch}
+ * does. The singleton is constructed with no default model, so routing through
+ * `getLocalEmbedder().embed()` silently used DEFAULT_LOCAL_MODEL: queries were
+ * embedded with a different model than the index was built with. Nothing
+ * detected it, because the provider fingerprint keys on `localModel`, so no
+ * purge or "pending" status ever fired — a dimension mismatch made semantic
+ * ranking contribute nothing, and a same-dimension override silently produced
+ * meaningless cross-model scores.
+ */
+async function embedOnce(text, embeddingConfig, signal) {
+    if (embeddingConfig && hasRemoteEndpoint(embeddingConfig)) {
+        return new RemoteEmbedder(embeddingConfig).embed(text, signal);
+    }
+    const localModel = embeddingConfig?.localModel;
+    if (localModel) {
+        return getLocalEmbedder().embedWithModel(text, localModel);
+    }
+    return getLocalEmbedder().embed(text, signal);
+}
 /**
  * Generate embeddings for multiple texts in batch.
  * Uses the OpenAI-compatible batch API for remote endpoints (batches of 100).

package/dist/llm/embedders/remote.js

@@ -9,6 +9,7 @@
  */
 import { fetchWithTimeout, isHttpUrl, readBodyWithByteCap } from "../../core/common.js";
 import { resolveSecret } from "../../core/config/config.js";
+import { redactErrorBody, redactSensitiveText } from "../../core/redaction.js";
 const DEFAULT_REMOTE_BATCH_SIZE = 100;
 /** Cheap token estimator: 4 chars ≈ 1 token. Used in verbose logging and error messages. */
 export function estimateTokenCount(text) {
@@ -54,7 +55,7 @@ export class RemoteEmbedder {
                     throw err;
                 return "";
             });
-            throw new Error(`Embedding request failed (${response.status}): ${errBody}`);
+            throw new Error(`Embedding request failed (${response.status}): ${this.safeErrorBody(errBody)}`);
         }
         const json = JSON.parse(await readBodyWithByteCap(response, undefined, { bodyTimeoutMs: 30_000, signal }));
         if (!json.data?.[0]?.embedding) {
@@ -94,7 +95,7 @@ export class RemoteEmbedder {
                         throw err;
                     return "";
                 });
-                throw new Error(`Embedding batch request failed (${response.status}): ${respBody}`);
+                throw new Error(`Embedding batch request failed (${response.status}): ${this.safeErrorBody(respBody)}`);
             }
             const json = JSON.parse(await readBodyWithByteCap(response, undefined, { bodyTimeoutMs: 30_000, signal }));
             if (!json.data || json.data.length !== batch.length) {
@@ -119,6 +120,21 @@ export class RemoteEmbedder {
         }
         return headers;
     }
+    /**
+     * Make a provider error body safe to embed in a thrown Error, matching the
+     * hardening llm/client.ts applies on the identical path: pattern-redact
+     * credential shapes, exact-scrub this connection's own key, and clip.
+     *
+     * These messages are durable — generateEmbeddingsForDb surfaces them as
+     * `embeddingResult.message`, which is written to semantic-status.json and
+     * replayed by `akm info` (including `--json`) until the next successful
+     * index, and printed on every vector-search attempt. Raw bodies reached that
+     * far unredacted and uncapped, at readBodyWithByteCap's 10 MB default.
+     */
+    safeErrorBody(body) {
+        const resolvedKey = resolveSecret(this.config.apiKey);
+        return redactSensitiveText(redactErrorBody(body), resolvedKey ? [resolvedKey] : []);
+    }
 }
 /**
  * L2-normalize a vector to unit length.
@@ -144,6 +160,15 @@ export function normalizeEmbeddingEndpoint(endpoint) {
     if (normalizedPath.endsWith("/embeddings")) {
         return parsed.toString();
     }
+    // Ollama's NATIVE embedding route is `/api/embed` (and the older
+    // `/api/embeddings`). Appending "/embeddings" to it produced
+    // `/api/embed/embeddings`, a 404 — so pointing akm at the native endpoint,
+    // which is what its own options like ollamaOptions and contextLength are
+    // for, could never work. An explicit path that is already an embedding route
+    // is left alone.
+    if (normalizedPath.endsWith("/embed")) {
+        return parsed.toString();
+    }
     parsed.pathname = normalizedPath ? `${normalizedPath}/embeddings` : "/embeddings";
     return parsed.toString();
 }

package/dist/output/html-render.js

@@ -14,8 +14,28 @@
  */
 import fs from "node:fs";
 import path from "node:path";
+import healthTemplate from "../assets/templates/html/health.html" with { type: "text" };
 import { getDirname } from "../runtime.js";
 const TEMPLATES_DIR = path.join(getDirname(import.meta.url), "../assets/templates/html");
+/**
+ * Templates embedded at build time, keyed by command name.
+ *
+ * `bun build --compile` embeds only what is imported `with { type: "text" }`;
+ * a plain `readFileSync` from a path relative to `import.meta.url` resolves
+ * into the virtual `/$bunfs` tree and misses. `akm health --report --format
+ * html` therefore crashed with ENOENT (exit 70) on the standalone binary that
+ * the CLI's own install error and the CHANGELOG promote as the runtime-free
+ * option. The text import works on all three runtimes: natively on Bun, via
+ * scripts/node-runtime/text-import-hook.mjs on Node, and embedded in the
+ * compiled binary.
+ */
+const EMBEDDED_TEMPLATES = {
+    // bun-types declares `*.html` as an `HTMLBundle` (its HTML-bundler entrypoint
+    // feature), which is not what a `type: "text"` import yields — the value is
+    // the file's contents as a string on every runtime. The cast reconciles the
+    // ambient declaration with the actual import attribute.
+    health: healthTemplate,
+};
 /**
  * Resolve the on-disk template path for a command's bespoke `<command>.html`.
  * The command name is sanitized to a bare basename so a hostile command
@@ -37,9 +57,28 @@ const TOKEN_RE = /%%[A-Z_]+%%/g;
  * matching the skill renderer's behaviour.
  */
 export function renderHtml(templatePath, replacements) {
-    const html = fs.readFileSync(templatePath, "utf8");
+    const html = readTemplate(templatePath);
     return html.replace(TOKEN_RE, (token) => replacements[token] ?? token);
 }
+/**
+ * Read a template from disk, falling back to the embedded copy.
+ *
+ * Disk stays primary so an operator (or a test) editing
+ * `src/assets/templates/html/<name>.html` sees the change without a rebuild.
+ * The fallback covers the standalone binary, where the file does not exist on
+ * any real filesystem.
+ */
+function readTemplate(templatePath) {
+    try {
+        return fs.readFileSync(templatePath, "utf8");
+    }
+    catch (err) {
+        const embedded = EMBEDDED_TEMPLATES[path.basename(templatePath, ".html")];
+        if (embedded !== undefined)
+            return embedded;
+        throw err;
+    }
+}
 /**
  * Minimal HTML entity escaping for text interpolated into templates. Escapes
  * the single quote as well as the double quote so escaped values are safe in