akm-cli 0.9.0-rc.9 → 0.9.1-beta.1

package/dist/integrations/lockfile.js

@@ -7,6 +7,7 @@ import { writeFileAtomic } from "../core/common.js";
 import { ConfigError, rethrowIfTestIsolationError } from "../core/errors.js";
 import { createLockPayload, probeLock, reclaimStaleLock, releaseLock, tryAcquireLockSync } from "../core/file-lock.js";
 import { acquireMaintenanceBarrier } from "../core/maintenance-barrier.js";
+import { classifyPathAccess, describeInaccessiblePath } from "../core/path-access.js";
 import { getDataDir, getLockfileLockPath, getLockfilePath } from "../core/paths.js";
 // ── Lock sentinel ────────────────────────────────────────────────────────────
 const LOCK_MAX_RETRIES = 3;
@@ -54,6 +55,79 @@ export function readLockfile() {
         return [];
     }
 }
+/**
+ * Refuse to treat an UNREADABLE lockfile (or data dir) as an absent one (#791).
+ *
+ * Every write path here is read-modify-WRITE: it loads the current entries and
+ * writes the whole array back. An unreadable `akm.lock` that reads as `[]`
+ * therefore does not merely lose information — the very next
+ * `writeFileAtomic` replaces the operator's entire lock record with the single
+ * entry this call happened to be adding. That is the same catastrophe R-012
+ * guards against for a *corrupt* file, reached instead through a permission
+ * fault, and `fs.existsSync`/a swallowed `readFileSync` could not tell the two
+ * apart from "the file was never created".
+ *
+ * No-op when the path is genuinely absent — that case really does have nothing
+ * to preserve.
+ */
+function assertLockfilePathReadable(target) {
+    const { access, code } = classifyPathAccess(target);
+    if (access !== "inaccessible")
+        return;
+    throw new ConfigError(`Refusing to modify the lockfile: ${describeInaccessiblePath(target, code)}. akm cannot read the existing lock ` +
+        "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() {
+    const lockfilePath = getLockfilePath();
+    let raw;
+    try {
+        raw = fs.readFileSync(lockfilePath, "utf8");
+    }
+    catch (err) {
+        rethrowIfTestIsolationError(err);
+        // "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
+        // function was written to prevent, only triggered by a permission fault
+        // instead of a corrupt file (#791). Classify AFTER the failed read so the
+        // happy path costs no extra syscall and the answer describes the failure
+        // we actually got.
+        assertLockfilePathReadable(lockfilePath);
+        return [];
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (error) {
+        throw new ConfigError(`Refusing to modify lockfile ${lockfilePath}: existing content is not valid JSON (${error instanceof Error ? error.message : String(error)}). Fix or remove the file by hand before retrying — every existing lock entry would otherwise be lost.`, "INVALID_CONFIG_FILE");
+    }
+    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");
+    }
+    return parsed.filter(isValidLockfileEntry);
+}
 /**
  * The materialized content root recorded in the lock for a managed (git/npm)
  * bundle — spec §10.2 desired/resolved split, where the desired config carries
@@ -93,10 +167,27 @@ export async function writeLockfile(entries) {
         release();
     }
 }
+/** Replace one exact parsed lock generation while the lockfile sentinel is held. */
+export async function compareAndSwapLockfile(expected, desired) {
+    const release = await acquireLockSentinel();
+    try {
+        const current = readLockfileOrThrow();
+        if (JSON.stringify(current) !== JSON.stringify(expected))
+            return false;
+        writeLockfileUnlocked(desired);
+        return true;
+    }
+    finally {
+        release();
+    }
+}
 export async function upsertLockEntry(entry) {
     const release = await acquireLockSentinel();
     try {
-        const entries = readLockfile();
+        // R-012: readLockfileOrThrow (not readLockfile) — a corrupt/malformed
+        // lockfile must abort the upsert loudly rather than read as `[]` and get
+        // silently overwritten with just this one entry.
+        const entries = readLockfileOrThrow();
         const withoutExisting = entries.filter((e) => e.id !== entry.id);
         writeLockfileUnlocked([...withoutExisting, entry]);
     }
@@ -110,11 +201,14 @@ export async function upsertLockEntry(entry) {
  * migrate-apply's config lock + maintenance barrier) whose synchronous body
  * cannot await the sentinel's retry loop. No-op for an empty list.
  */
-export function mergeLockEntriesSync(entries) {
-    if (entries.length === 0)
-        return;
+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 {
@@ -128,15 +222,45 @@ export function mergeLockEntriesSync(entries) {
         }
         existing = raw;
     }
-    const incoming = new Set(entries.map((e) => e.id));
-    writeLockfileUnlocked([...existing.filter((e) => !incoming.has(e.id)), ...entries]);
+    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) {
-    if (!fs.existsSync(getDataDir()))
+    // 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
+    // it — one we cannot read may hold the very entry we were asked to drop, and
+    // silently leaving it behind is how a bundle stays "installed" forever (#791).
+    const dataDir = getDataDir();
+    assertLockfilePathReadable(dataDir);
+    if (!fs.existsSync(dataDir))
         return;
     const release = await acquireLockSentinel();
     try {
-        const entries = readLockfile();
+        // R-012: see upsertLockEntry — same destructive-overwrite risk on a
+        // corrupt lockfile, so the same strict reader is used here.
+        const entries = readLockfileOrThrow();
         writeLockfileUnlocked(entries.filter((e) => e.id !== id));
     }
     finally {

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

@@ -50,22 +50,6 @@ const ERROR_PATTERNS = /error|failed|exception|cannot|undefined|null pointer|ENO
 export function getAvailableHarnesses() {
     return HARNESSES.filter((harness) => harness.isAvailable());
 }
-/**
- * Map each available harness to its `{ harnessName, roots }` watch target,
- * skipping harnesses that expose no roots (absent `watchRoots()` or an empty
- * result). This is the one stable entry point the watcher uses so it never
- * reaches into providers directly.
- */
-export function getWatchTargets() {
-    const targets = [];
-    for (const harness of getAvailableHarnesses()) {
-        const roots = harness.watchRoots?.() ?? [];
-        if (roots.length === 0)
-            continue;
-        targets.push({ harnessName: harness.name, roots });
-    }
-    return targets;
-}
 export function normalizeSessionTopic(text) {
     const normalized = text.replace(/\s+/g, " ").trim().toLowerCase();
     if (normalized.length < 10)
@@ -107,16 +91,13 @@ export function aggregateSessionEvents(events) {
  * Collect normalized session events from a set of harnesses for the health
  * candidate scan (#568).
  *
- * Pipeline selection per harness (capability-gated):
- *   - readSession-capable harness (`supportsReadSession !== false`): drive the
- *     richer `listSessions()` + `readSession()` pipeline. `readSession` flattens
+ * Pipeline selection per harness:
+ *   - Drive the richer `listSessions()` + `readSession()` pipeline. `readSession` flattens
  *     structured content — tool calls, assistant content blocks, thinking,
  *     tool_result — into event text (e.g. ClaudeCodeProvider's `parseClaudeEvent`
  *     surfaces `[tool:*]` / `[tool_result]` blocks that the legacy flat
  *     `readEvents` scan drops entirely). This is what lets health advisories see
  *     repeated tool failures / long runs that the flat scan hid.
- *   - legacy-only harness (`supportsReadSession === false`): fall back to the
- *     legacy flat `readEvents()` scan (behaviour-preserving).
  *
  * Extracted as a pure function (harnesses injected) so it is unit-testable
  * without touching the real on-disk session-log locations.
@@ -129,19 +110,13 @@ export function aggregateSessionEvents(events) {
  * health command (`akm health`, which calls this synchronously) blow past its
  * latency budget. `listSessions()` returns summaries sorted newest-first, so
  * capping to the most-recent N sessions per harness keeps the richer signal
- * for what actually matters (recent activity) while bounding cost. The legacy
- * flat-scan path is naturally cheaper and is left uncapped.
+ * for what actually matters (recent activity) while bounding cost.
  */
 const DEFAULT_MAX_SESSIONS_PER_HARNESS = 50;
 export function collectSessionEvents(harnesses, sinceMs, maxSessionsPerHarness = DEFAULT_MAX_SESSIONS_PER_HARNESS) {
     const events = [];
     for (const harness of harnesses) {
         try {
-            if (harness.supportsReadSession === false) {
-                // Legacy-only harness: only the flat event scan is available.
-                events.push(...harness.readEvents({ sinceMs }));
-                continue;
-            }
             // 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

package/dist/llm/client.js

@@ -4,23 +4,17 @@
 /**
  * Low-level OpenAI-compatible chat completions client and capability probing.
  *
- * Split out of `llm.ts` to keep the transport-layer concerns (HTTP request,
- * response parsing, JSON-fence stripping, capability probe, availability
- * check) separate from higher-level metadata-enhancement workflows.
- *
- * `llm.ts` re-exports everything from this module for backward compatibility.
+ * Keeps transport-layer concerns (HTTP request, response parsing, capability
+ * probing, and availability checks) separate from higher-level workflows.
  */
-import { fetchWithTimeout } from "../core/common.js";
+import { fetchWithTimeout, readBodyWithByteCap } from "../core/common.js";
 import { resolveSecret } from "../core/config/config.js";
 import { formatExtraParamsIssue, validateExtraParams } from "../core/extra-params.js";
-import { escapeJsonStringControls, parseJsonResponse, stripCodeFences, stripThinkBlocks } from "../core/parse.js";
-import { redactSensitiveText } from "../core/redaction.js";
+import { parseJsonResponse } from "../core/parse.js";
+import { redactCredentialPatterns, 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";
-// Re-export shared parse utilities so existing importers of `client.ts` continue
-// to resolve `parseJsonResponse` and `parseEmbeddedJsonResponse` from this module.
-export { escapeJsonStringControls, parseEmbeddedJsonResponse, parseJsonResponse, stripCodeFences, stripThinkBlocks, } from "../core/parse.js";
+import { emitLlmUsage, extractUsageTokens, } from "./usage-telemetry.js";
 /** Maximum length of an LLM error response body included in thrown errors. */
 const ERROR_BODY_MAX_LEN = 200;
 /** Stable OpenAI-compatible response-schema name used for every structured call. */
@@ -30,24 +24,14 @@ const JSON_SCHEMA_RESPONSE_NAME = "akm_response";
  * 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.
  *
- * Targets:
- *  - `Bearer <token>` headers echoed back by the provider
- *  - `sk-…` / `sk_…` style API keys (OpenAI / Anthropic-shaped)
- *  - `key-…` / `key_…` shorthand keys
- *  - `"api_key": "…"` / `"apiKey": "…"` JSON fields
+ * 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.
  */
 export function redactErrorBody(input) {
     if (!input)
         return "";
-    let out = input
-        // Bearer tokens (case-insensitive)
-        .replace(/\bBearer\s+[A-Za-z0-9._\-+/=]+/gi, "Bearer [REDACTED]")
-        // sk-/sk_ style keys
-        .replace(/\bsk[-_][A-Za-z0-9._-]{6,}/g, "[REDACTED]")
-        // key-/key_ shorthand keys
-        .replace(/\bkey[-_][A-Za-z0-9._-]{6,}/g, "[REDACTED]")
-        // JSON-style "api_key": "...", "apiKey": "...", "api-key": "..."
-        .replace(/("(?:api[_-]?key|apiKey|authorization|token)"\s*:\s*")([^"]*)(")/gi, "$1[REDACTED]$3");
+    let out = redactCredentialPatterns(input);
     if (out.length > ERROR_BODY_MAX_LEN) {
         out = `${out.slice(0, ERROR_BODY_MAX_LEN)}…`;
     }
@@ -103,6 +87,19 @@ const RETRY_BUDGET_FRACTION = 0.9;
 export function sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
+async function waitForRetry(ms, wait, signal) {
+    if (!signal)
+        return wait(ms);
+    if (signal.aborted)
+        throw new LlmCallError("LLM request aborted", "aborted");
+    await new Promise((resolve, reject) => {
+        const onAbort = () => reject(new LlmCallError("LLM request aborted", "aborted"));
+        signal.addEventListener("abort", onAbort, { once: true });
+        wait(ms)
+            .then(resolve, reject)
+            .finally(() => signal.removeEventListener("abort", onAbort));
+    });
+}
 /** Compute a uniform jittered backoff in the [200, 800)ms range. */
 function retryBackoffMs() {
     return RETRY_BACKOFF_MIN_MS + Math.random() * (RETRY_BACKOFF_MAX_MS - RETRY_BACKOFF_MIN_MS);
@@ -209,7 +206,7 @@ async function chatCompletionReal(config, messages, options) {
         // authoritative.
         warnVerbose(`[akm] LLM transient failure (${err.code}); retrying once: ${err.message}`);
         const wait = retryBackoffMs();
-        await (options?.sleep ?? sleep)(wait);
+        await waitForRetry(wait, options?.sleep ?? sleep, options?.signal);
         // The retry must not exceed the original budget.
         return await chatCompletionAttempt(config, messages, options, remaining);
     }
@@ -248,90 +245,129 @@ async function chatCompletionAttempt(config, messages, options, timeoutMs) {
         : config.provider === "vllm"
             ? { chat_template_kwargs: { enable_thinking: resolvedEnableThinking } }
             : { enable_thinking: resolvedEnableThinking };
-    // Wall-clock start for per-call usage telemetry (#576). Captured here so the
+    const requestBody = JSON.stringify({
+        model: config.model,
+        messages,
+        temperature: options?.temperature ?? config.temperature ?? 0.3,
+        ...(resolvedMaxTokens !== undefined ? { max_tokens: resolvedMaxTokens } : {}),
+        ...responseFormat,
+        ...thinkingParams,
+        ...config.extraParams,
+    });
+    // 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
     // attempt, not the retry-wrapping `chatCompletion`.
     const requestStartedAt = Date.now();
-    let response;
+    const requestDeadlineAt = timeoutMs === null ? null : requestStartedAt + timeoutMs;
+    const remainingAttemptMs = () => requestDeadlineAt === null ? undefined : Math.max(0, requestDeadlineAt - Date.now());
+    let terminalFields = {
+        model: config.model,
+        modelSource: "configured",
+    };
     try {
-        response = await fetchWithTimeout(config.endpoint, {
-            method: "POST",
-            headers,
-            body: JSON.stringify({
-                model: config.model,
-                messages,
-                temperature: options?.temperature ?? config.temperature ?? 0.3,
-                ...(resolvedMaxTokens !== undefined ? { max_tokens: resolvedMaxTokens } : {}),
-                ...responseFormat,
-                ...thinkingParams,
-                ...config.extraParams,
-            }),
-        }, timeoutMs, options?.signal);
-    }
-    catch (err) {
-        // fetchWithTimeout throws a plain Error with a message containing
-        // "timed out" for AbortController-driven timeouts, or "aborted" for
-        // caller-driven cancellations. Map both to typed LlmCallError.
-        const msg = err instanceof Error ? err.message : String(err);
-        if (err instanceof DOMException && err.name === "AbortError") {
-            throw new LlmCallError(`Request timed out${timeoutMs === null ? "" : ` after ${timeoutMs}ms`}`, "timeout");
+        let response;
+        try {
+            response = await fetchWithTimeout(config.endpoint, {
+                method: "POST",
+                headers,
+                body: requestBody,
+            }, timeoutMs, options?.signal);
         }
-        if (msg.includes("timed out")) {
-            throw new LlmCallError(`Request timed out${timeoutMs === null ? "" : ` after ${timeoutMs}ms`}`, "timeout");
+        catch (err) {
+            // fetchWithTimeout throws a plain Error with a message containing
+            // "timed out" for AbortController-driven timeouts, or "aborted" for
+            // caller-driven cancellations. Map both to typed LlmCallError.
+            const msg = err instanceof Error ? err.message : String(err);
+            if (options?.signal?.aborted || msg.includes("Request aborted")) {
+                throw new LlmCallError("LLM request aborted", "aborted");
+            }
+            if (err instanceof DOMException && err.name === "AbortError") {
+                throw new LlmCallError(`Request timed out${timeoutMs === null ? "" : ` after ${timeoutMs}ms`}`, "timeout");
+            }
+            if (msg.includes("timed out")) {
+                throw new LlmCallError(`Request timed out${timeoutMs === null ? "" : ` after ${timeoutMs}ms`}`, "timeout");
+            }
+            throw new LlmCallError(`Network error: ${msg}`, "network_error");
         }
-        throw new LlmCallError(`Network error: ${msg}`, "network_error");
-    }
-    if (!response.ok) {
-        const rawBody = await response.text().catch(() => "");
-        const safeBody = redactSensitiveText(redactErrorBody(rawBody), resolvedKey ? [resolvedKey] : []);
-        const status = response.status;
-        if (status === 429) {
-            throw new LlmCallError(`LLM request rate limited (429) ${config.endpoint}: ${safeBody}`, "rate_limited", status);
+        if (!response.ok) {
+            const rawBody = await readBodyWithByteCap(response, undefined, {
+                ...(requestDeadlineAt === null ? {} : { bodyTimeoutMs: remainingAttemptMs() }),
+                signal: options?.signal,
+            }).catch((err) => {
+                if (options?.signal?.aborted)
+                    throw new LlmCallError("LLM response read aborted", "aborted");
+                if (err instanceof Error && err.name === "BodyReadTimeoutError") {
+                    throw new LlmCallError("LLM response body read timed out", "timeout");
+                }
+                return "";
+            });
+            const safeBody = redactSensitiveText(redactErrorBody(rawBody), resolvedKey ? [resolvedKey] : []);
+            const status = response.status;
+            if (status === 429) {
+                throw new LlmCallError(`LLM request rate limited (429) ${config.endpoint}: ${safeBody}`, "rate_limited", status);
+            }
+            if (status >= 500 && isHtmlResponse(rawBody)) {
+                throw new LlmCallError(`LLM provider returned HTML instead of JSON (${status}) ${config.endpoint}: ${redactSensitiveText(htmlExcerpt(rawBody), resolvedKey ? [resolvedKey] : [])}`, "provider_html_error", status);
+            }
+            if (status >= 500) {
+                throw new LlmCallError(`LLM provider error (${status}) ${config.endpoint}: ${safeBody}`, "provider_error", status);
+            }
+            throw new LlmCallError(`LLM request failed (${status}) ${config.endpoint}: ${safeBody}`, "provider_error", status);
         }
-        if (status >= 500 && isHtmlResponse(rawBody)) {
-            throw new LlmCallError(`LLM provider returned HTML instead of JSON (${status}) ${config.endpoint}: ${redactSensitiveText(htmlExcerpt(rawBody), resolvedKey ? [resolvedKey] : [])}`, "provider_html_error", status);
+        // A 2xx response is still an error if the body is HTML where JSON was
+        // expected (e.g. a provider serving its web UI). Read the raw body first so
+        // we can categorize an HTML page distinctly from a malformed-JSON parse_error.
+        let rawOkBody;
+        try {
+            rawOkBody = await readBodyWithByteCap(response, undefined, {
+                ...(requestDeadlineAt === null ? {} : { bodyTimeoutMs: remainingAttemptMs() }),
+                signal: options?.signal,
+            });
         }
-        if (status >= 500) {
-            throw new LlmCallError(`LLM provider error (${status}) ${config.endpoint}: ${safeBody}`, "provider_error", status);
+        catch (err) {
+            if (options?.signal?.aborted)
+                throw new LlmCallError("LLM response read aborted", "aborted");
+            if (err instanceof Error && err.name === "BodyReadTimeoutError") {
+                throw new LlmCallError("LLM response body read timed out", "timeout");
+            }
+            throw err;
         }
-        throw new LlmCallError(`LLM request failed (${status}) ${config.endpoint}: ${safeBody}`, "provider_error", status);
-    }
-    // A 2xx response is still an error if the body is HTML where JSON was
-    // expected (e.g. a provider serving its web UI). Read the raw body first so
-    // we can categorize an HTML page distinctly from a malformed-JSON parse_error.
-    const rawOkBody = await response.text();
-    if (isHtmlResponse(rawOkBody)) {
-        throw new LlmCallError(`LLM provider returned HTML instead of JSON (${response.status}) ${config.endpoint}: ${redactSensitiveText(htmlExcerpt(rawOkBody), resolvedKey ? [resolvedKey] : [])}`, "provider_html_error", response.status);
-    }
-    let json;
-    try {
-        json = JSON.parse(rawOkBody);
+        if (isHtmlResponse(rawOkBody)) {
+            throw new LlmCallError(`LLM provider returned HTML instead of JSON (${response.status}) ${config.endpoint}: ${redactSensitiveText(htmlExcerpt(rawOkBody), resolvedKey ? [resolvedKey] : [])}`, "provider_html_error", response.status);
+        }
+        let json;
+        try {
+            json = JSON.parse(rawOkBody);
+        }
+        catch {
+            throw new LlmCallError(`LLM response was not valid JSON ${config.endpoint}: ${redactSensitiveText(redactErrorBody(rawOkBody), resolvedKey ? [resolvedKey] : [])}`, "parse_error", response.status);
+        }
+        const responseModel = typeof json.model === "string" && json.model.trim().length > 0 ? json.model : undefined;
+        terminalFields = {
+            model: responseModel ?? config.model,
+            modelSource: responseModel === undefined ? "configured" : "response",
+            finishReason: typeof json.choices?.[0]?.finish_reason === "string" ? json.choices[0].finish_reason : undefined,
+            ...extractUsageTokens(json.usage),
+        };
+        const content = (json.choices?.[0]?.message?.content ?? "").trim();
+        const reasoning = (json.choices?.[0]?.message?.reasoning_content ?? "").trim();
+        const result = redactSensitiveText(content || reasoning, resolvedKey ? [resolvedKey] : []);
+        emitLlmUsage({
+            ...terminalFields,
+            outcome: "success",
+            durationMs: Date.now() - requestStartedAt,
+        });
+        return result;
     }
-    catch {
-        throw new LlmCallError(`LLM response was not valid JSON ${config.endpoint}: ${redactSensitiveText(redactErrorBody(rawOkBody), resolvedKey ? [resolvedKey] : [])}`, "parse_error", response.status);
+    catch (err) {
+        emitLlmUsage({
+            ...terminalFields,
+            outcome: "error",
+            durationMs: Date.now() - requestStartedAt,
+            errorCode: err instanceof LlmCallError ? err.code : "unknown_error",
+        });
+        throw err;
     }
-    // Per-call usage telemetry (#576). Best-effort and fully isolated: a missing
-    // or garbled usage block still records duration + model, and a throwing sink
-    // can never fail the call (emitLlmUsage swallows its own errors). The stage
-    // is supplied ambiently by emitLlmUsage; no `stage` param is threaded here.
-    emitLlmUsage({
-        model: typeof json.model === "string" && json.model ? json.model : config.model,
-        durationMs: Date.now() - requestStartedAt,
-        finishReason: typeof json.choices?.[0]?.finish_reason === "string" ? json.choices[0].finish_reason : undefined,
-        ...extractUsageTokens(json.usage),
-    });
-    const content = (json.choices?.[0]?.message?.content ?? "").trim();
-    const reasoning = (json.choices?.[0]?.message?.reasoning_content ?? "").trim();
-    return redactSensitiveText(content || reasoning, resolvedKey ? [resolvedKey] : []);
-}
-/**
- * Strip `<think>` blocks, code fences, and escape control characters in JSON
- * strings. Thin wrapper kept for backward compatibility with call sites that
- * import `stripJsonFences` from this module. New code should prefer the
- * granular helpers from `../core/parse`.
- */
-export function stripJsonFences(raw) {
-    return escapeJsonStringControls(stripCodeFences(stripThinkBlocks(raw)));
 }
 // ── Availability check ──────────────────────────────────────────────────────
 /**

package/dist/llm/embedders/remote.js

@@ -7,7 +7,7 @@
  * Calls the configured `/embeddings` endpoint and L2-normalizes the returned
  * vectors so the scoring pipeline's L2-to-cosine conversion is correct.
  */
-import { fetchWithTimeout, isHttpUrl } from "../../core/common.js";
+import { fetchWithTimeout, isHttpUrl, readBodyWithByteCap } from "../../core/common.js";
 import { resolveSecret } from "../../core/config/config.js";
 const DEFAULT_REMOTE_BATCH_SIZE = 100;
 /** Cheap token estimator: 4 chars ≈ 1 token. Used in verbose logging and error messages. */
@@ -49,10 +49,14 @@ export class RemoteEmbedder {
             body: JSON.stringify(body),
         }, 30_000, signal);
         if (!response.ok) {
-            const errBody = await response.text().catch(() => "");
+            const errBody = await readBodyWithByteCap(response, undefined, { bodyTimeoutMs: 30_000, signal }).catch((err) => {
+                if (signal?.aborted)
+                    throw err;
+                return "";
+            });
             throw new Error(`Embedding request failed (${response.status}): ${errBody}`);
         }
-        const json = (await response.json());
+        const json = JSON.parse(await readBodyWithByteCap(response, undefined, { bodyTimeoutMs: 30_000, signal }));
         if (!json.data?.[0]?.embedding) {
             throw new Error(`Unexpected embedding response format: missing data[0].embedding.${embeddingEndpointPathHint(this.endpoint)}`);
         }
@@ -85,10 +89,14 @@ export class RemoteEmbedder {
                 body: JSON.stringify(body),
             }, 30_000, signal);
             if (!response.ok) {
-                const respBody = await response.text().catch(() => "");
+                const respBody = await readBodyWithByteCap(response, undefined, { bodyTimeoutMs: 30_000, signal }).catch((err) => {
+                    if (signal?.aborted)
+                        throw err;
+                    return "";
+                });
                 throw new Error(`Embedding batch request failed (${response.status}): ${respBody}`);
             }
-            const json = (await response.json());
+            const json = JSON.parse(await readBodyWithByteCap(response, undefined, { bodyTimeoutMs: 30_000, signal }));
             if (!json.data || json.data.length !== batch.length) {
                 throw new Error(`Unexpected embedding batch response: expected ${batch.length} embeddings, got ${json.data?.length ?? 0}.${embeddingEndpointPathHint(this.endpoint)}`);
             }

package/dist/llm/feature-gate.js

@@ -3,16 +3,11 @@
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
 /**
  * For each feature key, return the effective enabled state by reading the
- * 0.9.0 config shape. Defaults match the legacy `LlmFeatureFlags` docstrings.
+ * 0.9.0 config shape.
  */
-// Defaults below mirror the legacy LlmFeatureFlags docstrings so existing
-// behaviour is preserved when a config is silent on a flag.
 const FEATURE_LOCATION = {
-    // Legacy default: true
     memory_inference: (cfg) => cfg.index?.memory?.enabled ?? true,
-    // Legacy default: true
     graph_extraction: (cfg) => cfg.index?.graph?.enabled ?? true,
-    // Legacy default: false
     metadata_enhance: (cfg) => cfg.index?.metadataEnhance?.enabled ?? false,
     // Always on at the LLM-wrapper level. Enablement is decided ONCE at the
     // extract entry point (`akmExtract`): the `extract.enabled` process toggle
@@ -26,8 +21,7 @@ const FEATURE_LOCATION = {
 /**
  * Pure predicate: is the named feature gate enabled in `config`?
  *
- * Reads from the unified 0.9.0 config shape. Defaults follow the legacy
- * `LlmFeatureFlags` docstring defaults.
+ * Reads from the unified 0.9.0 config shape.
  */
 export function isLlmFeatureEnabled(config, feature, improveEnabled) {
     if (!config)
@@ -71,10 +65,8 @@ export async function tryLlmFeature(feature, config, fn, fallback, opts) {
     }
 }
 /**
- * Section-agnostic process gate. After the 0.8.0 migration, the canonical
- * accessor is the `FEATURE_LOCATION` map above; this helper exists so older
- * call sites that knew the (section, processName) pair don't all need to
- * relearn the new mapping.
+ * Section-agnostic process gate that maps process identifiers to their current
+ * config locations.
  *
  * For unknown (section, processName) pairs the result is `false`.
  */