@houtini/lm 2.13.1 → 3.1.0

package/dist/index.js

@@ -5,12 +5,18 @@
  * Connects to LM Studio (or any OpenAI-compatible endpoint) and exposes
  * chat, custom prompts, code tasks, and model discovery as MCP tools.
  */
+// Must be first: registers the node:sqlite experimental-warning filter BEFORE
+// the model-cache import (which pulls in node:sqlite and would emit the warning
+// at import time, i.e. before any later-registered handler could catch it).
+import './suppress-experimental-warnings.js';
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { CallToolRequestSchema, ListToolsRequestSchema, ListResourcesRequestSchema, ReadResourceRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
 import { profileModelsAtStartup, getCachedProfile, toModelProfile as cachedToProfile, getHFEnrichmentLine, getPromptHints, getThinkingSupport, recordPerformance, getAllPerformance, getLifetimeTotals, recordPrefillSample, getPrefillSamples, fitPrefillLinear, } from './model-cache.js';
-import { readFile } from 'node:fs/promises';
-import { isAbsolute, basename } from 'node:path';
+import { acquireInferenceLock } from './inference-lock.js';
+import { readFile, stat, realpath } from 'node:fs/promises';
+import { realpathSync } from 'node:fs';
+import { isAbsolute, basename, resolve, sep } from 'node:path';
 // Env var naming: HOUTINI_LM_* is the preferred namespace now that we
 // support more than just LM Studio. The legacy LM_STUDIO_* names remain
 // accepted indefinitely so existing users don't need to change anything.
@@ -34,7 +40,78 @@ const SOFT_TIMEOUT_MS = 300_000; // 5 min — progress notifications reset MCP c
 const READ_CHUNK_TIMEOUT_MS = 30_000; // max wait for a single SSE chunk mid-stream
 const PREFILL_TIMEOUT_MS = 180_000; // max wait for the FIRST chunk — prompt prefill on slow hardware with big inputs can legitimately take 1-2 min
 const PREFILL_KEEPALIVE_MS = 10_000; // fire a progress notification every N ms while waiting for prefill to finish
+const STREAM_PROGRESS_THROTTLE_MS = 500; // min gap between per-delta streaming progress pings — decoupled from token rate so a fast model can't flood stdio
 const FALLBACK_CONTEXT_LENGTH = parseInt(process.env.HOUTINI_LM_CONTEXT_WINDOW || process.env.LM_CONTEXT_WINDOW || '100000', 10);
+// ── code_task_files read guards ──────────────────────────────────────
+// Per-file size cap (default 10 MB) — files are read fully into memory before
+// the token estimator runs, so an unbounded read risks memory exhaustion.
+const MAX_FILE_BYTES = Math.max(1, parseInt(process.env.HOUTINI_LM_MAX_FILE_MB || '10', 10)) * 1024 * 1024;
+// Optional allowlist of directory roots that code_task_files may read from.
+// Unset = current behaviour (any absolute path). When set (colon- or
+// comma-separated), reads are confined to these roots AFTER symlink resolution,
+// so a prompt-injected call can't escape to ~/.ssh/id_rsa via a planted symlink.
+// Roots are realpath'd (not just resolved) so they compare correctly against the
+// realpath'd file below — otherwise a root under a symlinked ancestor (e.g. macOS
+// /tmp → /private/tmp) would never match and every confined read would fail. A
+// non-existent root falls back to resolve(), which simply won't match anything.
+const FILE_ROOTS = (process.env.HOUTINI_LM_FILE_ROOTS || '')
+    .split(/[:,]/)
+    .map((r) => r.trim())
+    .filter(Boolean)
+    .map((r) => { try {
+    return realpathSync(resolve(r));
+}
+catch {
+    return resolve(r);
+} });
+/**
+ * Read a file for code_task_files with size and (optional) root confinement.
+ * Resolves symlinks first so neither the allowlist check nor the caller can be
+ * tricked by a symlink pointing outside an allowed root. Throws on violation;
+ * the caller turns the throw into an inline "READ FAILED" section.
+ */
+async function readGuardedFile(p) {
+    const real = await realpath(p);
+    if (FILE_ROOTS.length > 0) {
+        const ok = FILE_ROOTS.some((root) => real === root || real.startsWith(root + sep));
+        if (!ok)
+            throw new Error('path is outside the allowed roots (HOUTINI_LM_FILE_ROOTS)');
+    }
+    const info = await stat(real);
+    if (!info.isFile())
+        throw new Error('not a regular file');
+    if (info.size > MAX_FILE_BYTES) {
+        throw new Error(`file is ${(info.size / 1024 / 1024).toFixed(1)} MB, over the ${(MAX_FILE_BYTES / 1024 / 1024).toFixed(0)} MB limit (set HOUTINI_LM_MAX_FILE_MB to raise)`);
+    }
+    return readFile(real, 'utf8');
+}
+/**
+ * Redact secrets embedded in an endpoint URL before echoing it to the client
+ * or logs. Strips userinfo (`user:pass@`) and common secret query params
+ * (`api_key`, `token`, …). Returns the input unchanged when it parses to no
+ * secret, so the common `http://localhost:1234` case is displayed verbatim.
+ */
+function redactUrl(raw) {
+    try {
+        const u = new URL(raw);
+        let hadSecret = false;
+        if (u.username || u.password) {
+            u.username = '';
+            u.password = '';
+            hadSecret = true;
+        }
+        for (const key of ['api_key', 'apikey', 'key', 'token', 'password', 'access_token']) {
+            if (u.searchParams.has(key)) {
+                u.searchParams.set(key, '***');
+                hadSecret = true;
+            }
+        }
+        return hadSecret ? u.toString() : raw;
+    }
+    catch {
+        return raw;
+    }
+}
 // ── Session-level token accounting ───────────────────────────────────
 // Tracks cumulative tokens offloaded to the local LLM across all calls
 // in this session. Shown in every response footer so Claude can reason
@@ -85,6 +162,57 @@ async function hydrateLifetimeFromDb() {
         process.stderr.write(`[houtini-lm] Lifetime hydration failed (stats will build from this session): ${err}\n`);
     }
 }
+/**
+ * Compose the system prompt sent to the local model. Guarantees a non-empty,
+ * directionally-productive instruction on EVERY call — the previous per-handler
+ * merge sent no system message at all when the caller passed none and the model
+ * family had no outputConstraint (Llama/Nemotron/Granite/gpt-oss/unknown).
+ * Layers, in order:
+ *   base       — persona (+ task, for code tasks); always present
+ *   grounding  — universal anti-hallucination line (the trust lever for the QA loop)
+ *   format     — JSON-only when a json_schema is set (which SUPPRESSES the
+ *                markdown guidance that would otherwise contradict it);
+ *                otherwise the task-appropriate format line plus any per-family
+ *                constraint.
+ * Compact by design — every token here is prefill the estimator and latency pay for.
+ */
+function buildSystemPrompt(opts) {
+    const layers = [opts.base.trim()];
+    layers.push('Base your answer only on the information provided in this conversation. ' +
+        'If it is insufficient to answer correctly, say what is missing rather than guessing.');
+    if (opts.structuredOutput) {
+        layers.push('Return only valid JSON conforming to the requested schema — no prose, no markdown, no code fences.');
+    }
+    else {
+        if (opts.formatLine && opts.formatLine.trim())
+            layers.push(opts.formatLine.trim());
+        if (opts.modelConstraint && opts.modelConstraint.trim())
+            layers.push(opts.modelConstraint.trim());
+    }
+    return layers.join('\n\n');
+}
+/**
+ * Generation throughput in tokens/sec, isolating decode time from prefill.
+ * `generationMs` spans connect + prefill + decode; dividing by the whole span
+ * makes a large-prompt call look many times slower than the model actually
+ * decodes, and that pessimistic number is what the footer, the first-call
+ * benchmark, and the persisted per-model stats report back to the orchestrator.
+ * Subtract TTFT so the denominator is the decode window. Returns null when it
+ * can't be measured.
+ *
+ * Known limitation (tracked separately): for thinking models TTFT is time to
+ * first *visible* token, so reasoning time is excluded from the denominator
+ * while reasoning tokens remain in completion_tokens — resolving that needs the
+ * TTFT-vs-reasoning fix, out of scope for this change.
+ */
+function computeTokPerSec(resp) {
+    if (!resp.usage)
+        return null;
+    const decodeMs = resp.generationMs - (resp.ttftMs ?? 0);
+    if (decodeMs <= 50)
+        return null;
+    return resp.usage.completion_tokens / (decodeMs / 1000);
+}
 function recordUsage(resp) {
     session.calls++;
     const promptTokens = resp.usage?.prompt_tokens ?? 0;
@@ -101,9 +229,7 @@ function recordUsage(resp) {
         session.completionTokens += est;
     }
     // Tok/s used by both session and lifetime stats
-    const tokPerSec = resp.usage && resp.generationMs > 50
-        ? (resp.usage.completion_tokens / (resp.generationMs / 1000))
-        : 0;
+    const tokPerSec = computeTokPerSec(resp) ?? 0;
     // Session per-model (unchanged behaviour)
     if (resp.model) {
         const existing = session.modelStats.get(resp.model) || { calls: 0, ttftCalls: 0, perfCalls: 0, totalTtftMs: 0, totalTokPerSec: 0 };
@@ -205,13 +331,24 @@ function apiHeaders() {
 }
 // ── Request semaphore ────────────────────────────────────────────────
 // Most local LLM servers run a single model and queue parallel requests,
-// which stacks timeouts and wastes the 55s budget. This semaphore ensures
-// only one inference call runs at a time; others wait in line.
+// which stacks timeouts and wastes the budget. This semaphore ensures only one
+// inference call runs at a time; others wait in line.
+// Global override: HOUTINI_LM_SERIALISE=0 (or false/no/off) turns OFF inference
+// serialisation entirely — both the in-process semaphore and the cross-process
+// file lock. The right setting for backends that batch requests natively (vLLM,
+// TGI, SGLang), where one-at-a-time only throttles throughput. Default on, which
+// suits a single-model LM Studio / Ollama host contending for one GPU.
+const SERIALISE_INFERENCE = !/^(0|false|no|off)$/i.test(process.env.HOUTINI_LM_SERIALISE || '');
+/** Serialise inference for the current backend? Combines the env override with
+ *  the provider profile (OpenRouter and other parallel-friendly backends off). */
+function shouldSerialiseInference() {
+    return SERIALISE_INFERENCE && getProviderProfile().serialiseInference;
+}
 let inferenceLock = Promise.resolve();
 function withInferenceLock(fn) {
-    // Remote providers (OpenRouter etc.) benefit from parallelism and do
-    // their own rate-limit handling; serialising here just throttles us.
-    if (!getProviderProfile().serialiseInference)
+    // Skip when serialisation is off (env override) or the backend is
+    // parallel-friendly (OpenRouter etc.) — serialising there just throttles us.
+    if (!shouldSerialiseInference())
         return fn();
     let release;
     const next = new Promise((resolve) => { release = resolve; });
@@ -482,9 +619,12 @@ async function fetchWithRetry(url, options, timeoutMs, retries) {
                     await res.body?.cancel();
                 }
                 catch { /* ignore */ }
-                const base = 400 * (attempt + 1);
-                const target = Math.min(Math.max(base, retryAfter ?? 0), 10_000);
-                const delay = Math.round(target * (0.5 + Math.random())); // 0.5×..1.5×
+                // Exponential base capped at 10s, but honour an explicit server
+                // Retry-After (up to 60s) even when larger. Jitter UPWARD only
+                // (target..1.5×) so we never retry before the server-mandated delay.
+                const base = Math.min(400 * (attempt + 1), 10_000);
+                const target = Math.max(base, Math.min(retryAfter ?? 0, 60_000));
+                const delay = Math.round(target * (1 + Math.random() * 0.5));
                 await new Promise((r) => setTimeout(r, delay));
                 continue;
             }
@@ -492,10 +632,15 @@ async function fetchWithRetry(url, options, timeoutMs, retries) {
         }
         catch (e) {
             lastErr = e;
-            if (attempt < retries) {
-                const delay = Math.round(400 * (attempt + 1) * (0.5 + Math.random()));
-                await new Promise((r) => setTimeout(r, delay));
-            }
+            // A timeout abort can mean the server already received the POST and began
+            // a (billed) generation — re-POSTing /v1/chat/completions would duplicate
+            // it. Only retry errors that indicate the request never reached the
+            // server (connection refused/reset); never on our own abort.
+            const isAbort = e instanceof Error && e.name === 'AbortError';
+            if (isAbort || attempt >= retries)
+                break;
+            const delay = Math.round(400 * (attempt + 1) * (1 + Math.random() * 0.5));
+            await new Promise((r) => setTimeout(r, delay));
         }
     }
     throw lastErr instanceof Error ? lastErr : new Error(String(lastErr));
@@ -517,16 +662,96 @@ async function timedRead(reader, timeoutMs) {
     }
 }
 /**
- * Streaming chat completion with soft timeout.
- *
- * Uses SSE streaming (`stream: true`) so tokens arrive incrementally.
- * If we approach the MCP SDK's ~60s timeout (soft limit at 55s), we
- * return whatever content we have so far with `truncated: true`.
- * This means large code reviews return partial results instead of nothing.
+ * Extract and RANGE-VALIDATE optional sampling params from tool args. Out-of-range,
+ * NaN, or wrong-type values are dropped (undefined) rather than forwarded — the
+ * backend then applies its own default. This also closes the earlier gap where an
+ * unvalidated max_tokens/temperature could reach the upstream request.
+ */
+function extractSamplingParams(args) {
+    const range = (v, min, max) => {
+        const n = typeof v === 'number' ? v : NaN;
+        return Number.isFinite(n) && n >= min && n <= max ? n : undefined;
+    };
+    const stopRaw = args.stop;
+    const stop = typeof stopRaw === 'string'
+        ? stopRaw
+        : Array.isArray(stopRaw)
+            ? stopRaw.filter((s) => typeof s === 'string').slice(0, 4)
+            : undefined;
+    return {
+        seed: Number.isInteger(args.seed) ? args.seed : undefined,
+        stop: stop && stop.length ? stop : undefined,
+        topP: range(args.top_p, 0, 1),
+        topK: range(args.top_k, 1, 100_000),
+        repeatPenalty: range(args.repeat_penalty, 0, 2),
+        frequencyPenalty: range(args.frequency_penalty, -2, 2),
+        presencePenalty: range(args.presence_penalty, -2, 2),
+    };
+}
+/** Clamp a caller-supplied temperature to a sane range, or undefined if unusable. */
+function validTemperature(v) {
+    const n = typeof v === 'number' ? v : NaN;
+    return Number.isFinite(n) && n >= 0 && n <= 2 ? n : undefined;
+}
+/**
+ * Minimum caller-supplied max_tokens the server will honour. Values below this
+ * are discarded so the dynamic context-based budget (25% of the model's context
+ * window) applies instead — MCP clients habitually pass tiny caps like 256 that
+ * strangle reasoning models. Set HOUTINI_LM_MIN_TOKENS=0 to honour any value
+ * (e.g. deliberate micro-chunking on slow hardware), or a different floor.
  */
+const MIN_MAX_TOKENS = (() => {
+    const v = Number(process.env.HOUTINI_LM_MIN_TOKENS);
+    return Number.isFinite(v) && v >= 0 ? Math.floor(v) : 4096;
+})();
+/** Clamp a caller-supplied max_tokens to a positive sane range, or undefined. */
+function validMaxTokens(v) {
+    const n = typeof v === 'number' ? v : NaN;
+    if (!Number.isInteger(n) || n <= 0 || n > 1_000_000)
+        return undefined;
+    if (n < MIN_MAX_TOKENS) {
+        process.stderr.write(`[houtini-lm] max_tokens=${n} is below the ${MIN_MAX_TOKENS} floor — ignoring it and using the dynamic context-based budget (HOUTINI_LM_MIN_TOKENS=0 to allow)\n`);
+        return undefined;
+    }
+    return n;
+}
+/**
+ * Build an OpenAI response_format from the tool's json_schema input. Accepts
+ * BOTH the documented wrapper `{ name, schema, strict }` and a bare JSON Schema
+ * (which the description invites) — the latter previously produced undefined
+ * name/schema and silently unconstrained output.
+ */
+function toResponseFormat(js) {
+    if (!js || typeof js !== 'object')
+        return undefined;
+    const obj = js;
+    const hasWrapper = !!obj.schema && typeof obj.schema === 'object';
+    const schema = (hasWrapper ? obj.schema : obj);
+    const name = hasWrapper && typeof obj.name === 'string' ? obj.name : 'response';
+    const strict = hasWrapper && typeof obj.strict === 'boolean' ? obj.strict : true;
+    return { type: 'json_schema', json_schema: { name, strict, schema } };
+}
 async function chatCompletionStreaming(messages, options = {}) {
     return withInferenceLock(() => chatCompletionStreamingInner(messages, options));
 }
+/**
+ * Pull a human-readable message out of an OpenAI-style mid-stream error
+ * payload (`data: {"error":{...}}`). Returns undefined when the chunk carries
+ * no error, so callers can treat a truthy result as "the backend failed".
+ */
+function extractStreamError(json) {
+    if (!json || typeof json !== 'object')
+        return undefined;
+    const err = json.error;
+    if (!err)
+        return undefined;
+    if (typeof err === 'string')
+        return err;
+    if (typeof err === 'object' && typeof err.message === 'string') {
+        return err.message;
+    }
+    return JSON.stringify(err);
+}
 /** Get the first loaded model's info for context-aware defaults. */
 async function getActiveModel() {
     try {
@@ -557,14 +782,30 @@ async function chatCompletionStreamingInner(messages, options = {}) {
     }
     // Derive max_tokens from the model's actual context window when not explicitly set.
     // Uses 25% of context as a generous output budget (e.g. 262K context → 65K output).
-    let effectiveMaxTokens = options.maxTokens ?? DEFAULT_MAX_TOKENS;
-    if (!options.maxTokens) {
+    let contextLen;
+    {
         const activeModel = await resolveActive();
-        if (activeModel) {
-            const ctx = getContextLength(activeModel);
-            effectiveMaxTokens = Math.floor(ctx * 0.25);
-        }
+        if (activeModel)
+            contextLen = getContextLength(activeModel);
+    }
+    let effectiveMaxTokens = options.maxTokens ?? DEFAULT_MAX_TOKENS;
+    if (!options.maxTokens && contextLen) {
+        effectiveMaxTokens = Math.floor(contextLen * 0.25);
     }
+    // Never request more output than the context window can hold alongside the
+    // prompt — vLLM (and strict OpenAI backends) reject prompt+max_tokens >
+    // context with a 400 instead of clamping. Conservative prompt estimate:
+    // 1 token ≈ 3 chars, plus per-message overhead.
+    const promptChars = messages.reduce((n, m) => n + (typeof m.content === 'string' ? m.content.length : JSON.stringify(m.content ?? '').length), 0);
+    const capToContext = (requested) => {
+        if (!contextLen)
+            return requested;
+        const cap = contextLen - (Math.ceil(promptChars / 3) + 64 * messages.length + 512);
+        // If the prompt alone (over)fills the context, don't mangle the request —
+        // let the backend report the real overflow.
+        return cap > 0 ? Math.min(requested, cap) : requested;
+    };
+    effectiveMaxTokens = capToContext(effectiveMaxTokens);
     const body = {
         messages,
         temperature: options.temperature ?? DEFAULT_TEMPERATURE,
@@ -582,6 +823,26 @@ async function chatCompletionStreamingInner(messages, options = {}) {
     if (options.responseFormat) {
         body.response_format = options.responseFormat;
     }
+    // Optional sampling controls — forwarded only when the caller set them (already
+    // range-validated in extractSamplingParams). Backends ignore unknown fields, so
+    // sending e.g. top_k to one that doesn't support it is harmless.
+    const s = options.sampling;
+    if (s) {
+        if (s.seed !== undefined)
+            body.seed = s.seed;
+        if (s.stop !== undefined)
+            body.stop = s.stop;
+        if (s.topP !== undefined)
+            body.top_p = s.topP;
+        if (s.topK !== undefined)
+            body.top_k = s.topK;
+        if (s.repeatPenalty !== undefined)
+            body.repeat_penalty = s.repeatPenalty;
+        if (s.frequencyPenalty !== undefined)
+            body.frequency_penalty = s.frequencyPenalty;
+        if (s.presencePenalty !== undefined)
+            body.presence_penalty = s.presencePenalty;
+    }
     // Handle thinking/reasoning models.
     // Some models (Gemma 4, Qwen3, DeepSeek R1, Nemotron, gpt-oss) have extended
     // thinking that consumes part of the max_tokens budget for invisible reasoning
@@ -609,7 +870,7 @@ async function chatCompletionStreamingInner(messages, options = {}) {
         // guarantee the model generates less of it.
         body.reasoning = { exclude: true };
         const beforeInflation = effectiveMaxTokens;
-        const inflated = Math.max(beforeInflation * 4, beforeInflation + 2000);
+        const inflated = capToContext(Math.max(beforeInflation * 4, beforeInflation + 2000));
         body.max_tokens = inflated;
         body.max_completion_tokens = inflated;
         process.stderr.write(`[houtini-lm] OpenRouter model ${modelId || '(unspecified)'}: reasoning.exclude=true, max_tokens inflated ${beforeInflation} → ${inflated}\n`);
@@ -625,40 +886,20 @@ async function chatCompletionStreamingInner(messages, options = {}) {
             // Inflation uses effectiveMaxTokens (the context-aware value), not
             // DEFAULT_MAX_TOKENS — otherwise big-context models get sized down.
             const beforeInflation = effectiveMaxTokens;
-            const inflated = Math.max(beforeInflation * 4, beforeInflation + 2000);
+            const inflated = capToContext(Math.max(beforeInflation * 4, beforeInflation + 2000));
             body.max_tokens = inflated;
             body.max_completion_tokens = inflated;
             process.stderr.write(`[houtini-lm] Thinking model ${modelId}: reasoning_effort=${reasoningValue ?? '(omitted)'}, enable_thinking=false, max_tokens inflated ${beforeInflation} → ${inflated}\n`);
         }
     }
     const startTime = Date.now();
-    const res = profile.retryOnRateLimit
-        ? await fetchWithRetry(`${LM_BASE_URL}/v1/chat/completions`, { method: 'POST', headers: apiHeaders(), body: JSON.stringify(body) }, INFERENCE_CONNECT_TIMEOUT_MS, 2)
-        : await fetchWithTimeout(`${LM_BASE_URL}/v1/chat/completions`, { method: 'POST', headers: apiHeaders(), body: JSON.stringify(body) }, INFERENCE_CONNECT_TIMEOUT_MS);
-    if (!res.ok) {
-        const text = await res.text().catch(() => '');
-        throw new Error(`LM Studio API error ${res.status}: ${text}`);
-    }
-    if (!res.body) {
-        throw new Error('Response body is null — streaming not supported by endpoint');
-    }
-    const reader = res.body.getReader();
-    const decoder = new TextDecoder();
-    let content = '';
-    let reasoning = '';
+    // Progress-notification plumbing lifted ABOVE the fetch so we can keep the
+    // MCP client's request timeout alive during the HTTP handshake with the
+    // upstream LLM. On slow backends (big prompt, heavy prefill, cold model)
+    // the POST to /v1/chat/completions can sit for 30-60+ seconds before the
+    // response headers flush — that window used to be silent and would trip
+    // the client's 60s default timeout before any SSE chunk reached us.
     let progressSeq = 0;
-    let model = '';
-    let usage;
-    let finishReason = '';
-    let truncated = false;
-    let prefillStall = false;
-    let buffer = '';
-    let ttftMs;
-    let firstChunkReceived = false;
-    // Prefill keep-alive — /v1/chat/completions gives no SSE events during
-    // prompt processing, so the MCP client clock ticks uninterrupted on a slow
-    // backend with a big input. Fire a progress notification every 10s until
-    // the first chunk arrives to keep the client from timing out at 60s.
     const sendProgress = (message) => {
         if (options.progressToken === undefined)
             return;
@@ -672,190 +913,323 @@ async function chatCompletionStreamingInner(messages, options = {}) {
             },
         }).catch(() => { });
     };
-    const keepAliveTimer = setInterval(() => {
-        if (firstChunkReceived)
+    // Throttled variant for the per-delta streaming updates. Streaming fires a
+    // progress event on every content/reasoning chunk; on a fast model (e.g.
+    // 145 tok/s) that would be ~145 JSON-RPC notifications/sec over stdio,
+    // flooding the transport and the client's notification handler. Gate those
+    // on a time interval so the notification rate is decoupled from the token
+    // rate — slow models still update often, fast models emit at most one ping
+    // per interval. The immediate connect ping and the interval keepalives below
+    // bypass this deliberately.
+    let lastStreamProgressMs = 0;
+    const sendStreamProgress = (message) => {
+        const now = Date.now();
+        if (now - lastStreamProgressMs < STREAM_PROGRESS_THROTTLE_MS)
             return;
-        const waitedMs = Date.now() - startTime;
-        sendProgress(`Waiting for model... (${(waitedMs / 1000).toFixed(0)}s, still in prefill)`);
-    }, PREFILL_KEEPALIVE_MS);
+        lastStreamProgressMs = now;
+        sendProgress(message);
+    };
+    // Ping once immediately — resets the client's timeout clock as soon as the
+    // tool call is acknowledged server-side, regardless of how long prefill or
+    // the upstream handshake takes.
+    sendProgress('Connecting to model...');
+    // Cross-process inference serialisation (local single-model backends only).
+    // Acquire BEFORE the request so only one process at a time drives the model;
+    // the in-process semaphore already gates same-process calls, so this only ever
+    // contends across processes. Keepalive via sendProgress during the wait so a
+    // queued call doesn't sit silent past the client's request timeout. Fail-open:
+    // the lock module returns a no-op release on error or after the wait cap.
+    const canKeepalive = options.progressToken !== undefined;
+    const releaseInferenceLock = shouldSerialiseInference()
+        ? await acquireInferenceLock({
+            onWait: canKeepalive
+                ? (waitedMs) => sendProgress(`Waiting for the local model — another request is running (${(waitedMs / 1000).toFixed(0)}s)`)
+                : undefined,
+            // Without a progressToken we can't keep the client alive during a long
+            // wait, so fail open well before the typical ~60s client request timeout
+            // rather than sit silent in the queue and get aborted.
+            maxWaitMs: canKeepalive ? undefined : 45_000,
+        })
+        : () => { };
     try {
-        while (true) {
-            // Check soft timeout before each read
-            const elapsed = Date.now() - startTime;
-            if (elapsed > SOFT_TIMEOUT_MS) {
-                truncated = true;
-                process.stderr.write(`[houtini-lm] Soft timeout at ${elapsed}ms, returning ${content.length} chars of partial content\n`);
-                break;
-            }
-            // Split prefill vs mid-stream timeouts. Prefill on slow hardware with
-            // a 7k-token input can legitimately take 1-2 min; mid-stream stalls
-            // should surface much faster. Track firstChunkReceived to switch.
-            const remaining = SOFT_TIMEOUT_MS - elapsed;
-            const perChunkCeiling = firstChunkReceived ? READ_CHUNK_TIMEOUT_MS : PREFILL_TIMEOUT_MS;
-            const chunkTimeout = Math.min(perChunkCeiling, remaining);
-            const result = await timedRead(reader, chunkTimeout);
-            if (result === 'timeout') {
-                truncated = true;
-                prefillStall = !firstChunkReceived;
-                process.stderr.write(`[houtini-lm] ${prefillStall ? 'Prefill' : 'Mid-stream'} timeout, returning ${content.length} chars of partial content\n`);
-                break;
-            }
-            if (result.done)
-                break;
-            if (!firstChunkReceived) {
-                firstChunkReceived = true;
-            }
-            buffer += decoder.decode(result.value, { stream: true });
-            // Parse SSE lines
-            const lines = buffer.split('\n');
-            buffer = lines.pop() || ''; // Keep incomplete line in buffer
-            for (const line of lines) {
-                const trimmed = line.trim();
-                if (!trimmed || trimmed === 'data: [DONE]')
-                    continue;
-                if (!trimmed.startsWith('data: '))
-                    continue;
-                try {
-                    const json = JSON.parse(trimmed.slice(6));
-                    if (json.model)
-                        model = json.model;
-                    const delta = json.choices?.[0]?.delta;
-                    // Reasoning channel. Two field names exist in the wild:
-                    //   - LM Studio (dev toggle "Separate reasoning_content"), DeepSeek R1,
-                    //     Nemotron       → delta.reasoning_content
-                    //   - Ollama OpenAI-compat (all thinking models)       → delta.reasoning
-                    // We capture both so runtime detection and safety-net fallback fire
-                    // regardless of backend. An Ollama qwen3:4b at low max_tokens
-                    // previously looked like a broken model — silent empty content —
-                    // because this channel was dropped.
-                    const reasoningChunk = (typeof delta?.reasoning_content === 'string' && delta.reasoning_content.length > 0)
-                        ? delta.reasoning_content
-                        : (typeof delta?.reasoning === 'string' && delta.reasoning.length > 0)
-                            ? delta.reasoning
-                            : '';
-                    if (reasoningChunk) {
-                        reasoning += reasoningChunk;
-                        sendProgress(`Thinking... (${reasoning.length} chars of reasoning)`);
+        // Pre-fetch heartbeat — keep the client alive while we wait for the
+        // upstream LLM to return response headers. Cleared once fetch resolves.
+        const preFetchTimer = setInterval(() => {
+            const waitedMs = Date.now() - startTime;
+            sendProgress(`Connecting to model... (${(waitedMs / 1000).toFixed(0)}s)`);
+        }, PREFILL_KEEPALIVE_MS);
+        let res;
+        try {
+            res = profile.retryOnRateLimit
+                ? await fetchWithRetry(`${LM_BASE_URL}/v1/chat/completions`, { method: 'POST', headers: apiHeaders(), body: JSON.stringify(body) }, INFERENCE_CONNECT_TIMEOUT_MS, 2)
+                : await fetchWithTimeout(`${LM_BASE_URL}/v1/chat/completions`, { method: 'POST', headers: apiHeaders(), body: JSON.stringify(body) }, INFERENCE_CONNECT_TIMEOUT_MS);
+        }
+        finally {
+            clearInterval(preFetchTimer);
+        }
+        if (!res.ok) {
+            const text = await res.text().catch(() => '');
+            throw new Error(`LM Studio API error ${res.status}: ${text}`);
+        }
+        if (!res.body) {
+            throw new Error('Response body is null — streaming not supported by endpoint');
+        }
+        const reader = res.body.getReader();
+        const decoder = new TextDecoder();
+        let content = '';
+        let reasoning = '';
+        let model = '';
+        let usage;
+        let finishReason = '';
+        let truncated = false;
+        let prefillStall = false;
+        let buffer = '';
+        let ttftMs;
+        let firstChunkReceived = false;
+        // Backends (OpenRouter, vLLM, llama.cpp) can emit an error object mid-stream
+        // — `data: {"error":{...}}` — then close the connection normally. Without
+        // capturing it, the loop parses the payload, matches no field, and returns
+        // the partial/empty content as a clean success. Track it so we can surface
+        // the real cause instead of silently corrupting the result.
+        let streamError;
+        // Prefill keep-alive — even after HTTP headers flush, the first SSE chunk
+        // can still lag while the model finishes prompt processing. Fire a progress
+        // notification every 10s until the first chunk arrives.
+        const keepAliveTimer = setInterval(() => {
+            if (firstChunkReceived)
+                return;
+            const waitedMs = Date.now() - startTime;
+            sendProgress(`Waiting for model... (${(waitedMs / 1000).toFixed(0)}s, still in prefill)`);
+        }, PREFILL_KEEPALIVE_MS);
+        try {
+            while (true) {
+                // Check soft timeout before each read
+                const elapsed = Date.now() - startTime;
+                if (elapsed > SOFT_TIMEOUT_MS) {
+                    truncated = true;
+                    process.stderr.write(`[houtini-lm] Soft timeout at ${elapsed}ms, returning ${content.length} chars of partial content\n`);
+                    break;
+                }
+                // Split prefill vs mid-stream timeouts. Prefill on slow hardware with
+                // a 7k-token input can legitimately take 1-2 min; mid-stream stalls
+                // should surface much faster. Track firstChunkReceived to switch.
+                const remaining = SOFT_TIMEOUT_MS - elapsed;
+                const perChunkCeiling = firstChunkReceived ? READ_CHUNK_TIMEOUT_MS : PREFILL_TIMEOUT_MS;
+                const chunkTimeout = Math.min(perChunkCeiling, remaining);
+                const result = await timedRead(reader, chunkTimeout);
+                if (result === 'timeout') {
+                    truncated = true;
+                    prefillStall = !firstChunkReceived;
+                    process.stderr.write(`[houtini-lm] ${prefillStall ? 'Prefill' : 'Mid-stream'} timeout, returning ${content.length} chars of partial content\n`);
+                    break;
+                }
+                if (result.done)
+                    break;
+                if (!firstChunkReceived) {
+                    firstChunkReceived = true;
+                }
+                buffer += decoder.decode(result.value, { stream: true });
+                // Parse SSE lines
+                const lines = buffer.split('\n');
+                buffer = lines.pop() || ''; // Keep incomplete line in buffer
+                for (const line of lines) {
+                    const trimmed = line.trim();
+                    if (!trimmed || trimmed === 'data: [DONE]')
+                        continue;
+                    if (!trimmed.startsWith('data: '))
+                        continue;
+                    try {
+                        const json = JSON.parse(trimmed.slice(6));
+                        // Mid-stream error from the backend — capture the cause and stop.
+                        // The connection usually closes normally right after, so without
+                        // this the partial result would be returned as a success.
+                        const errMsg = extractStreamError(json);
+                        if (errMsg) {
+                            streamError = errMsg;
+                            truncated = true;
+                            break;
+                        }
+                        if (json.model)
+                            model = json.model;
+                        const delta = json.choices?.[0]?.delta;
+                        // Reasoning channel. Two field names exist in the wild:
+                        //   - LM Studio (dev toggle "Separate reasoning_content"), DeepSeek R1,
+                        //     Nemotron       → delta.reasoning_content
+                        //   - Ollama OpenAI-compat (all thinking models)       → delta.reasoning
+                        // We capture both so runtime detection and safety-net fallback fire
+                        // regardless of backend. An Ollama qwen3:4b at low max_tokens
+                        // previously looked like a broken model — silent empty content —
+                        // because this channel was dropped.
+                        const reasoningChunk = (typeof delta?.reasoning_content === 'string' && delta.reasoning_content.length > 0)
+                            ? delta.reasoning_content
+                            : (typeof delta?.reasoning === 'string' && delta.reasoning.length > 0)
+                                ? delta.reasoning
+                                : '';
+                        if (reasoningChunk) {
+                            // TTFT = time to first token of ANY channel (true prefill end). For
+                            // thinking models the first token is reasoning, not content; setting
+                            // TTFT here keeps the prefill estimator from mistaking the whole
+                            // reasoning phase for prefill (which caused spurious code_task_files
+                            // refusals) and keeps the decode-window tok/s denominator consistent.
+                            if (ttftMs === undefined)
+                                ttftMs = Date.now() - startTime;
+                            reasoning += reasoningChunk;
+                            sendStreamProgress(`Thinking... (${reasoning.length} chars of reasoning)`);
+                        }
+                        if (typeof delta?.content === 'string' && delta.content.length > 0) {
+                            if (ttftMs === undefined)
+                                ttftMs = Date.now() - startTime;
+                            content += delta.content;
+                            sendStreamProgress(`Streaming... ${content.length} chars`);
+                        }
+                        const reason = json.choices?.[0]?.finish_reason;
+                        if (reason)
+                            finishReason = reason;
+                        // Some endpoints include usage in the final streaming chunk
+                        if (json.usage)
+                            usage = json.usage;
                     }
-                    if (typeof delta?.content === 'string' && delta.content.length > 0) {
-                        if (ttftMs === undefined)
-                            ttftMs = Date.now() - startTime;
-                        content += delta.content;
-                        sendProgress(`Streaming... ${content.length} chars`);
+                    catch {
+                        // Skip unparseable chunks (partial JSON, comments, etc.)
                     }
-                    const reason = json.choices?.[0]?.finish_reason;
-                    if (reason)
-                        finishReason = reason;
-                    // Some endpoints include usage in the final streaming chunk
-                    if (json.usage)
-                        usage = json.usage;
-                }
-                catch {
-                    // Skip unparseable chunks (partial JSON, comments, etc.)
                 }
+                // A mid-stream error breaks the inner line loop; also stop reading here
+                // rather than waiting out the per-chunk timeout on a connection the
+                // backend is about to close.
+                if (streamError)
+                    break;
             }
-        }
-        // Flush remaining buffer — the usage chunk often arrives in the final SSE
-        // message and may not have a trailing newline, leaving it stranded in buffer.
-        if (buffer.trim()) {
-            const trimmed = buffer.trim();
-            if (trimmed.startsWith('data: ') && trimmed !== 'data: [DONE]') {
-                try {
-                    const json = JSON.parse(trimmed.slice(6));
-                    if (json.model)
-                        model = json.model;
-                    const delta = json.choices?.[0]?.delta;
-                    const finalReasoningChunk = (typeof delta?.reasoning_content === 'string' && delta.reasoning_content.length > 0)
-                        ? delta.reasoning_content
-                        : (typeof delta?.reasoning === 'string' && delta.reasoning.length > 0)
-                            ? delta.reasoning
-                            : '';
-                    if (finalReasoningChunk) {
-                        reasoning += finalReasoningChunk;
+            // Flush remaining buffer — the usage chunk often arrives in the final SSE
+            // message and may not have a trailing newline, leaving it stranded in buffer.
+            if (buffer.trim()) {
+                const trimmed = buffer.trim();
+                if (trimmed.startsWith('data: ') && trimmed !== 'data: [DONE]') {
+                    try {
+                        const json = JSON.parse(trimmed.slice(6));
+                        const errMsg = extractStreamError(json);
+                        if (errMsg) {
+                            streamError = errMsg;
+                            truncated = true;
+                        }
+                        if (json.model)
+                            model = json.model;
+                        const delta = json.choices?.[0]?.delta;
+                        const finalReasoningChunk = (typeof delta?.reasoning_content === 'string' && delta.reasoning_content.length > 0)
+                            ? delta.reasoning_content
+                            : (typeof delta?.reasoning === 'string' && delta.reasoning.length > 0)
+                                ? delta.reasoning
+                                : '';
+                        if (finalReasoningChunk) {
+                            if (ttftMs === undefined)
+                                ttftMs = Date.now() - startTime;
+                            reasoning += finalReasoningChunk;
+                        }
+                        if (typeof delta?.content === 'string' && delta.content.length > 0) {
+                            if (ttftMs === undefined)
+                                ttftMs = Date.now() - startTime;
+                            content += delta.content;
+                        }
+                        const reason = json.choices?.[0]?.finish_reason;
+                        if (reason)
+                            finishReason = reason;
+                        if (json.usage)
+                            usage = json.usage;
                     }
-                    if (typeof delta?.content === 'string' && delta.content.length > 0) {
-                        if (ttftMs === undefined)
-                            ttftMs = Date.now() - startTime;
-                        content += delta.content;
+                    catch (e) {
+                        // Incomplete JSON in final buffer — log for diagnostics
+                        process.stderr.write(`[houtini-lm] Unflushed buffer parse failed (${buffer.length} bytes): ${e}\n`);
                     }
-                    const reason = json.choices?.[0]?.finish_reason;
-                    if (reason)
-                        finishReason = reason;
-                    if (json.usage)
-                        usage = json.usage;
-                }
-                catch (e) {
-                    // Incomplete JSON in final buffer — log for diagnostics
-                    process.stderr.write(`[houtini-lm] Unflushed buffer parse failed (${buffer.length} bytes): ${e}\n`);
                 }
             }
         }
-    }
-    finally {
-        clearInterval(keepAliveTimer);
-        // Best-effort cancel with a short timeout — cancel() can hang if the upstream
-        // connection is wedged, so we race it against a 500ms timer. This frees the
-        // underlying socket sooner on abrupt client disconnects without blocking the
-        // tool response path.
-        try {
-            await Promise.race([
-                reader.cancel().catch(() => { }),
-                new Promise((resolve) => setTimeout(resolve, 500)),
-            ]);
+        finally {
+            clearInterval(keepAliveTimer);
+            // Best-effort cancel with a short timeout — cancel() can hang if the upstream
+            // connection is wedged, so we race it against a 500ms timer. This frees the
+            // underlying socket sooner on abrupt client disconnects without blocking the
+            // tool response path.
+            try {
+                await Promise.race([
+                    reader.cancel().catch(() => { }),
+                    new Promise((resolve) => setTimeout(resolve, 500)),
+                ]);
+            }
+            catch { /* never propagate cleanup errors */ }
+            try {
+                reader.releaseLock();
+            }
+            catch { /* already released */ }
         }
-        catch { /* never propagate cleanup errors */ }
-        try {
-            reader.releaseLock();
+        const generationMs = Date.now() - startTime;
+        // Backend failed mid-stream and produced nothing usable — surface the real
+        // cause as an error rather than returning an empty "success" the orchestrator
+        // would treat as a valid (empty) answer. When partial content did arrive we
+        // keep it but carry streamError through so the footer flags it.
+        if (streamError && !content.trim() && !reasoning.trim()) {
+            throw new Error(`Upstream model error mid-stream: ${streamError}`);
         }
-        catch { /* already released */ }
-    }
-    const generationMs = Date.now() - startTime;
-    // Strip <think>...</think> reasoning blocks from models that always emit them
-    // inline on the content channel (e.g. GLM Flash, Ollama Qwen3). Claude doesn't
-    // need the model's internal reasoning. Handle three shapes:
-    //   1. Balanced  <think>...</think>  — GLM Flash, Nemotron normal case
-    //   2. Orphan opener <think>... (truncated)
-    //   3. Orphan closer ...</think>  — Ollama Qwen3 streams reasoning directly
-    //      on the content channel and terminates with a bare </think> before the
-    //      real answer. Strip everything up to and including the first closer.
-    let cleanContent = content.replace(/<think>[\s\S]*?<\/think>\s*/g, ''); // closed blocks
-    cleanContent = cleanContent.replace(/^<think>\s*/, ''); // orphaned opening tag
-    cleanContent = cleanContent.replace(/^[\s\S]*?<\/think>\s*/, ''); // orphaned closing tag
-    cleanContent = cleanContent.trim();
-    // Safety nets for empty visible output. Try in order:
-    //   1. thinkStripFallback: stripping <think> left nothing, but raw content had text
-    //   2. reasoningFallback: no visible content AT ALL, but reasoning_content was streamed
-    //      (this is the Nemotron/DeepSeek-R1/LM-Studio-dev-toggle case — previously
-    //      produced silent empty bodies because reasoning was discarded)
-    let thinkStripFallback = false;
-    let reasoningFallback = false;
-    if (!cleanContent) {
-        if (content.trim()) {
-            thinkStripFallback = true;
-            cleanContent = content.trim();
+        // Strip <think>...</think> reasoning blocks from models that always emit them
+        // inline on the content channel (e.g. GLM Flash, Ollama Qwen3). Claude doesn't
+        // need the model's internal reasoning. Handle three shapes:
+        //   1. Balanced  <think>...</think>  — GLM Flash, Nemotron normal case
+        //   2. Orphan opener <think>... (truncated)
+        //   3. Orphan closer ...</think>  — Ollama Qwen3 streams reasoning directly
+        //      on the content channel and terminates with a bare </think> before the
+        //      real answer. Strip everything up to and including the first closer.
+        let cleanContent = content.replace(/<think>[\s\S]*?<\/think>\s*/g, ''); // closed blocks
+        cleanContent = cleanContent.replace(/^<think>\s*/, ''); // orphaned opening tag
+        // Orphaned closing tag: reasoning streamed on the content channel then a bare
+        // </think> before the answer (Ollama Qwen3). Strip up to the first closer ONLY
+        // for models KNOWN to emit think blocks (per the cached profile). For any other
+        // model, leave it: a real answer that merely quotes "</think>" would otherwise
+        // be truncated — and a leaked reasoning prefix (visible, recoverable) is a far
+        // safer failure than deleting answer text (silent, unrecoverable). The earlier
+        // backtick heuristic was lose-lose (leaked reasoning containing code, still
+        // deleted answers with an unquoted literal); the profile flag is the right signal.
+        const thinkProfile = await getThinkingSupport(modelId).catch(() => null);
+        if (thinkProfile?.emitsThinkBlocks && cleanContent.includes('</think>')) {
+            cleanContent = cleanContent.replace(/^[\s\S]*?<\/think>\s*/, '');
         }
-        else if (reasoning.trim()) {
-            reasoningFallback = true;
-            cleanContent =
-                '[No visible output — the model spent its entire output budget on reasoning_content before emitting any content. ' +
-                    'Raw reasoning below so you can see what it was doing:]\n\n' +
-                    reasoning.trim();
+        cleanContent = cleanContent.trim();
+        // Safety nets for empty visible output. Try in order:
+        //   1. thinkStripFallback: stripping <think> left nothing, but raw content had text
+        //   2. reasoningFallback: no visible content AT ALL, but reasoning_content was streamed
+        //      (this is the Nemotron/DeepSeek-R1/LM-Studio-dev-toggle case — previously
+        //      produced silent empty bodies because reasoning was discarded)
+        let thinkStripFallback = false;
+        let reasoningFallback = false;
+        if (!cleanContent) {
+            if (content.trim()) {
+                thinkStripFallback = true;
+                cleanContent = content.trim();
+            }
+            else if (reasoning.trim()) {
+                reasoningFallback = true;
+                cleanContent =
+                    '[No visible output — the model spent its entire output budget on reasoning_content before emitting any content. ' +
+                        'Raw reasoning below so you can see what it was doing:]\n\n' +
+                        reasoning.trim();
+            }
         }
+        return {
+            content: cleanContent,
+            rawContent: content,
+            reasoningContent: reasoning || undefined,
+            model,
+            usage,
+            finishReason,
+            truncated,
+            ttftMs,
+            generationMs,
+            thinkStripFallback,
+            reasoningFallback,
+            prefillStall,
+            streamError,
+        };
+    }
+    finally {
+        releaseInferenceLock();
     }
-    return {
-        content: cleanContent,
-        rawContent: content,
-        reasoningContent: reasoning || undefined,
-        model,
-        usage,
-        finishReason,
-        truncated,
-        ttftMs,
-        generationMs,
-        thinkStripFallback,
-        reasoningFallback,
-        prefillStall,
-    };
 }
 let detectedBackend = null;
 function getBackend() {
@@ -1021,7 +1395,11 @@ const PREFILL_WARN_THRESHOLD_SEC = 25;
  */
 async function estimatePrefill(inputChars, modelId) {
     const inputTokens = Math.ceil(inputChars / CHARS_PER_TOKEN);
-    // 1. Linear fit over recent samples (preferred).
+    // 1. Linear fit over recent samples (preferred); 2. ratio fallback from the
+    // SAME samples when there aren't enough for a fit. Both use the per-call
+    // (promptTokens, ttft) pairs, so the ratio can't mix populations the way the
+    // old aggregate did (avg prompt tokens over all calls vs avg TTFT over only
+    // TTFT-bearing calls), which skewed the rate and mis-fired the refusal guard.
     try {
         const samples = await getPrefillSamples(modelId);
         const fit = fitPrefillLinear(samples);
@@ -1034,24 +1412,22 @@ async function estimatePrefill(inputChars, modelId) {
                 fit,
             };
         }
+        if (samples.length >= 2) {
+            const sumPrompt = samples.reduce((a, s) => a + s.promptTokens, 0);
+            const sumTtftMs = samples.reduce((a, s) => a + s.ttftMs, 0);
+            if (sumPrompt > 0 && sumTtftMs > 0) {
+                const prefillTokPerSec = sumPrompt / (sumTtftMs / 1000);
+                return {
+                    inputTokens,
+                    estimatedSeconds: inputTokens / prefillTokPerSec,
+                    basis: 'ratio',
+                    prefillTokPerSec,
+                };
+            }
+        }
     }
     catch {
-        // Sample fetch failed — fall through to ratio estimator
-    }
-    // 2. Ratio fallback — uses aggregate stats already in memory.
-    const stats = lifetime.modelStats.get(modelId);
-    if (stats && stats.ttftCalls >= 2 && stats.totalTtftMs > 0 && stats.totalPromptTokens > 0) {
-        const avgPromptTokens = stats.totalPromptTokens / stats.calls;
-        const avgTtftSec = (stats.totalTtftMs / stats.ttftCalls) / 1000;
-        if (avgTtftSec > 0) {
-            const prefillTokPerSec = avgPromptTokens / avgTtftSec;
-            return {
-                inputTokens,
-                estimatedSeconds: inputTokens / prefillTokPerSec,
-                basis: 'ratio',
-                prefillTokPerSec,
-            };
-        }
+        // Sample fetch failed — fall through to the conservative default.
     }
     // 3. Conservative default for unknown model/hardware.
     return {
@@ -1130,9 +1506,7 @@ async function routeToModel(taskType, override) {
 function assessQuality(resp, rawContent) {
     const hadThinkBlocks = /<think>/.test(rawContent);
     const estimated = !resp.usage && resp.content.length > 0;
-    const tokPerSec = resp.usage && resp.generationMs > 50
-        ? resp.usage.completion_tokens / (resp.generationMs / 1000)
-        : null;
+    const tokPerSec = computeTokPerSec(resp);
     return {
         truncated: resp.truncated,
         prefillStall: resp.prefillStall ?? false,
@@ -1162,6 +1536,10 @@ function formatQualityLine(quality) {
         flags.push('tokens-estimated');
     if (quality.finishReason === 'length')
         flags.push('hit-max-tokens');
+    // content_filter is a REFUSAL, not a truncation — the orchestrator should
+    // handle it differently (don't retry with a bigger budget). Surface distinctly.
+    if (quality.finishReason === 'content_filter')
+        flags.push('CONTENT-FILTERED (model refused/blocked — not a length cut)');
     if (flags.length === 0)
         return '';
     return `Quality: ${flags.join(', ')}`;
@@ -1193,6 +1571,12 @@ function formatFooter(resp, extra) {
         else {
             parts.push(`${resp.usage.prompt_tokens}→${resp.usage.completion_tokens} tokens`);
         }
+        // Prefix-cache (KV reuse) hits — a strong "this delegation was nearly free"
+        // signal for the orchestrator when it re-sends shared context.
+        const cached = resp.usage.prompt_tokens_details?.cached_tokens;
+        if (typeof cached === 'number' && cached > 0) {
+            parts.push(`${cached} prompt tokens cached`);
+        }
     }
     else if (resp.content.length > 0) {
         // Estimate when usage is missing (truncated responses where final SSE chunk was lost)
@@ -1204,8 +1588,9 @@ function formatFooter(resp, extra) {
     if (resp.ttftMs !== undefined)
         perfParts.push(`TTFT: ${resp.ttftMs}ms`);
     let tokPerSec = 0;
-    if (resp.usage && resp.generationMs > 50) {
-        tokPerSec = resp.usage.completion_tokens / (resp.generationMs / 1000);
+    const measuredTokPerSec = computeTokPerSec(resp);
+    if (measuredTokPerSec !== null) {
+        tokPerSec = measuredTokPerSec;
         perfParts.push(`${tokPerSec.toFixed(1)} tok/s`);
     }
     if (resp.generationMs)
@@ -1219,7 +1604,9 @@ function formatFooter(resp, extra) {
     const qualityLine = formatQualityLine(quality);
     if (qualityLine)
         parts.push(qualityLine);
-    if (resp.truncated)
+    if (resp.streamError)
+        parts.push(`⚠ UPSTREAM ERROR (partial result — backend reported: ${resp.streamError})`);
+    else if (resp.truncated)
         parts.push('⚠ TRUNCATED (soft timeout — partial result)');
     const benchmarkLine = isFirstBenchmarkedCall(resp.model, tokPerSec)
         ? `📊 First measured call on ${resp.model}: ${tokPerSec.toFixed(1)} tok/s${resp.ttftMs !== undefined ? `, ${resp.ttftMs}ms to first token` : ''} — use this to gauge whether to delegate longer tasks.`
@@ -1239,6 +1626,17 @@ function formatFooter(resp, extra) {
     return lines.join('\n');
 }
 // ── MCP Tool definitions ─────────────────────────────────────────────
+// Optional sampling controls shared by the inference tools. Out-of-range values
+// are dropped server-side (extractSamplingParams), so the backend default applies.
+const SAMPLING_PROPS = {
+    seed: { type: 'integer', description: 'Deterministic sampling seed — same seed + same prompt → reproducible output. Useful for testing.' },
+    stop: { type: ['string', 'array'], items: { type: 'string' }, description: 'Stop sequence(s) — generation halts when one is produced (up to 4).' },
+    top_p: { type: 'number', description: 'Nucleus sampling 0–1 (e.g. 0.9). Lower = more focused. Alternative to temperature.' },
+    top_k: { type: 'integer', description: 'Sample only from the top-K tokens (e.g. 40). 0/omitted = disabled.' },
+    repeat_penalty: { type: 'number', description: 'Penalise repetition, 0–2 (1 = off, ~1.1 typical).' },
+    frequency_penalty: { type: 'number', description: 'OpenAI-style frequency penalty, -2 to 2.' },
+    presence_penalty: { type: 'number', description: 'OpenAI-style presence penalty, -2 to 2.' },
+};
 const TOOLS = [
     {
         name: 'chat',
@@ -1256,7 +1654,8 @@ const TOOLS = [
             '(1) Send COMPLETE context — the local LLM cannot read files.\n' +
             '(2) Be explicit about output format ("respond as a JSON array", "return only the function").\n' +
             '(3) Specific system persona beats generic — "Senior TypeScript dev" not "helpful assistant".\n' +
-            '(4) State constraints — "no preamble", "reference line numbers", "max 5 bullets".\n\n' +
+            '(4) State constraints — "no preamble", "reference line numbers", "max 5 bullets".\n' +
+            '(5) Leave max_tokens UNSET — the server sizes the budget from the model\'s real context window. Tiny caps like 256 waste the model: reasoning burns the budget before any visible output.\n\n' +
             'Routing picks the best loaded model automatically. Call `discover` to see what is loaded and, after the first real call, its measured speed. The footer shows cumulative tokens kept in the user\'s quota.',
         inputSchema: {
             type: 'object',
@@ -1275,7 +1674,7 @@ const TOOLS = [
                 },
                 max_tokens: {
                     type: 'number',
-                    description: 'Max response tokens. Defaults to 25% of the loaded model\'s context window (fallback 16,384). Pass a number to cap it tighter for quick answers.',
+                    description: 'Response token budget. OMIT THIS — when omitted the server checks the live model\'s context window and allocates 25% of it (e.g. ~32,000 tokens on a 128k-context model), which is right for almost every call. Small caps like 256/512/1024 strangle reasoning models (hidden thinking burns the budget before visible output), so values below 4,096 are IGNORED and the dynamic budget applies. Only set this to raise the ceiling for very long outputs.',
                 },
                 json_schema: {
                     type: 'object',
@@ -1285,6 +1684,7 @@ const TOOLS = [
                     type: 'string',
                     description: 'Optional: pin to a specific model id (e.g. "nvidia/nemotron-3-nano-30b-a3b:free" on OpenRouter, "qwen.qwen3-coder-30b-a3b-instruct" on LM Studio). When set, overrides automatic routing. Useful on providers with many models where auto-routing picks poorly.',
                 },
+                ...SAMPLING_PROPS,
             },
             required: ['message'],
         },
@@ -1325,7 +1725,7 @@ const TOOLS = [
                 },
                 max_tokens: {
                     type: 'number',
-                    description: 'Max response tokens. Defaults to 25% of the loaded model\'s context window (fallback 16,384).',
+                    description: 'Response token budget. OMIT THIS — the server sizes it from the live model\'s context window (25%, e.g. ~32,000 on a 128k-context model). Values below 4,096 are IGNORED (tiny caps strangle reasoning models) and the dynamic budget applies. Only set to raise the ceiling.',
                 },
                 json_schema: {
                     type: 'object',
@@ -1335,6 +1735,7 @@ const TOOLS = [
                     type: 'string',
                     description: 'Optional: pin to a specific model id. When set, overrides automatic routing.',
                 },
+                ...SAMPLING_PROPS,
             },
             required: ['instruction'],
         },
@@ -1371,12 +1772,13 @@ const TOOLS = [
                 },
                 max_tokens: {
                     type: 'number',
-                    description: 'Max response tokens. Defaults to 25% of the loaded model\'s context window (fallback 16,384).',
+                    description: 'Response token budget. OMIT THIS — the server sizes it from the live model\'s context window (25%, e.g. ~32,000 on a 128k-context model). Values below 4,096 are IGNORED (tiny caps strangle reasoning models) and the dynamic budget applies. Only set to raise the ceiling.',
                 },
                 model: {
                     type: 'string',
                     description: 'Optional: pin to a specific model id. When set, overrides automatic routing.',
                 },
+                ...SAMPLING_PROPS,
             },
             required: ['code', 'task'],
         },
@@ -1414,12 +1816,13 @@ const TOOLS = [
                 },
                 max_tokens: {
                     type: 'number',
-                    description: 'Optional output budget override. Defaults to 25% of the loaded model\'s context window.',
+                    description: 'Response token budget. OMIT THIS — the server sizes it from the live model\'s context window (25%). Values below 4,096 are IGNORED and the dynamic budget applies. Only set to raise the ceiling.',
                 },
                 model: {
                     type: 'string',
                     description: 'Optional: pin to a specific model id. When set, overrides automatic routing.',
                 },
+                ...SAMPLING_PROPS,
             },
             required: ['paths', 'task'],
         },
@@ -1486,7 +1889,7 @@ const SIDEKICK_INSTRUCTIONS = `Houtini-lm is a local LLM sidekick. It runs on th
     `When to reach for it: bounded, self-contained tasks you can describe in one message — explanations, boilerplate, test stubs, code review of pasted or file-loaded source, translations, commit messages, format conversion, brainstorming. Trades wall-clock time for tokens (typically 3-30× slower than frontier models).\n\n` +
     `When not to: tasks that need tool access, cross-file reasoning you haven't captured, or work fast enough to answer directly before the delegation round-trip completes.\n\n` +
     `Call \`discover\` in delegation-heavy sessions to see what model is loaded, its capability profile, and — after the first real call — its measured speed. The response footer reports cumulative tokens kept in the user's quota.`;
-const server = new Server({ name: 'houtini-lm', version: '2.13.1' }, { capabilities: { tools: {}, resources: {} }, instructions: SIDEKICK_INSTRUCTIONS });
+const server = new Server({ name: 'houtini-lm', version: '3.1.0' }, { capabilities: { tools: {}, resources: {} }, instructions: SIDEKICK_INSTRUCTIONS });
 // ── MCP Resources ─────────────────────────────────────────────────────
 // Exposes session performance metrics as a readable resource so Claude can
 // proactively check offload efficiency and make smarter delegation decisions.
@@ -1519,7 +1922,7 @@ server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
                 totalTokensOffloaded: session.promptTokens + session.completionTokens,
             },
             perModel: modelStats,
-            endpoint: LM_BASE_URL,
+            endpoint: redactUrl(LM_BASE_URL),
         };
         return {
             contents: [{
@@ -1533,30 +1936,36 @@ server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
 });
 server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS }));
 server.setRequestHandler(CallToolRequestSchema, async (request) => {
-    const { name, arguments: args } = request.params;
+    const { name } = request.params;
+    // `arguments` is optional in the MCP CallTool schema — a client may omit it
+    // entirely for a param-less tool (e.g. `stats` with no filter). Default to an
+    // empty object so handlers that destructure args never throw on `undefined`.
+    const args = request.params.arguments ?? {};
     const progressToken = request.params._meta?.progressToken;
     try {
         switch (name) {
             case 'chat': {
                 const { message, system, temperature, max_tokens, json_schema, model } = args;
                 const route = await routeToModel('chat', model);
+                const responseFormat = toResponseFormat(json_schema);
                 const messages = [];
-                // Inject output constraint into system prompt if the model needs it
-                const systemContent = system
-                    ? (route.hints.outputConstraint ? `${system}\n\n${route.hints.outputConstraint}` : system)
-                    : (route.hints.outputConstraint || undefined);
-                if (systemContent)
-                    messages.push({ role: 'system', content: systemContent });
+                messages.push({
+                    role: 'system',
+                    content: buildSystemPrompt({
+                        base: system && system.trim() ? system.trim() : 'You are a precise technical assistant.',
+                        formatLine: 'Be direct — no preamble, no restating the question. Use markdown formatting where it helps.',
+                        modelConstraint: route.hints.outputConstraint,
+                        structuredOutput: !!responseFormat,
+                    }),
+                });
                 messages.push({ role: 'user', content: message });
-                const responseFormat = json_schema
-                    ? { type: 'json_schema', json_schema: { name: json_schema.name, strict: json_schema.strict ?? true, schema: json_schema.schema } }
-                    : undefined;
                 const resp = await chatCompletionStreaming(messages, {
-                    temperature: temperature ?? route.hints.chatTemp,
-                    maxTokens: max_tokens,
+                    temperature: validTemperature(temperature) ?? route.hints.chatTemp,
+                    maxTokens: validMaxTokens(max_tokens),
                     model: route.modelId,
                     responseFormat,
                     progressToken,
+                    sampling: extractSamplingParams(args),
                 });
                 const footer = formatFooter(resp);
                 return { content: [{ type: 'text', text: resp.content + footer }] };
@@ -1564,12 +1973,17 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             case 'custom_prompt': {
                 const { system, context, instruction, temperature, max_tokens, json_schema, model } = args;
                 const route = await routeToModel('analysis', model);
+                const responseFormat = toResponseFormat(json_schema);
                 const messages = [];
-                const systemContent = system
-                    ? (route.hints.outputConstraint ? `${system}\n\n${route.hints.outputConstraint}` : system)
-                    : (route.hints.outputConstraint || undefined);
-                if (systemContent)
-                    messages.push({ role: 'system', content: systemContent });
+                messages.push({
+                    role: 'system',
+                    content: buildSystemPrompt({
+                        base: system && system.trim() ? system.trim() : 'You are a precise technical assistant.',
+                        formatLine: 'Be direct — no preamble, no restating the question. Use markdown formatting where it helps.',
+                        modelConstraint: route.hints.outputConstraint,
+                        structuredOutput: !!responseFormat,
+                    }),
+                });
                 // Multi-turn format prevents context bleed in smaller models.
                 // Context goes in a separate user→assistant exchange so the model
                 // "acknowledges" it before receiving the actual instruction.
@@ -1578,15 +1992,13 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                     messages.push({ role: 'assistant', content: 'Understood. I have read the full context. What would you like me to do with it?' });
                 }
                 messages.push({ role: 'user', content: instruction });
-                const responseFormat = json_schema
-                    ? { type: 'json_schema', json_schema: { name: json_schema.name, strict: json_schema.strict ?? true, schema: json_schema.schema } }
-                    : undefined;
                 const resp = await chatCompletionStreaming(messages, {
-                    temperature: temperature ?? route.hints.chatTemp,
-                    maxTokens: max_tokens,
+                    temperature: validTemperature(temperature) ?? route.hints.chatTemp,
+                    maxTokens: validMaxTokens(max_tokens),
                     model: route.modelId,
                     responseFormat,
                     progressToken,
+                    sampling: extractSamplingParams(args),
                 });
                 const footer = formatFooter(resp);
                 return {
@@ -1597,15 +2009,16 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 const { code, task, language, max_tokens: codeMaxTokens, model } = args;
                 const lang = language || 'unknown';
                 const route = await routeToModel('code', model);
-                const outputConstraint = route.hints.outputConstraint
-                    ? ` ${route.hints.outputConstraint}`
-                    : '';
                 // Task goes in system message so smaller models don't lose it once
                 // the code block fills the attention window. Code is sole user content.
                 const codeMessages = [
                     {
                         role: 'system',
-                        content: `Expert ${lang} developer. Your task: ${task}\n\nBe specific — reference line numbers, function names, and concrete fixes. Output your analysis as a markdown list.${outputConstraint}`,
+                        content: buildSystemPrompt({
+                            base: `You are a senior ${lang} developer. Your task: ${task}`,
+                            formatLine: 'Be specific — reference line numbers, function names, and concrete fixes. Output your analysis as a markdown list.',
+                            modelConstraint: route.hints.outputConstraint,
+                        }),
                     },
                     {
                         role: 'user',
@@ -1614,9 +2027,14 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 ];
                 const codeResp = await chatCompletionStreaming(codeMessages, {
                     temperature: route.hints.codeTemp,
-                    maxTokens: codeMaxTokens ?? DEFAULT_MAX_TOKENS,
+                    // Pass the (validated) value, undefined when omitted, so the
+                    // 25%-of-context auto-derivation in chatCompletionStreamingInner fires
+                    // — matching code_task_files. Forcing DEFAULT_MAX_TOKENS here made
+                    // options.maxTokens always truthy, capping long generations at 16K.
+                    maxTokens: validMaxTokens(codeMaxTokens),
                     model: route.modelId,
                     progressToken,
+                    sampling: extractSamplingParams(args),
                 });
                 const codeFooter = formatFooter(codeResp, lang);
                 const suggestionLine = route.suggestion ? `\n${route.suggestion}` : '';
@@ -1641,7 +2059,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 // Read all files in parallel. One unreadable file doesn't sink the call —
                 // failures become inline error sections so the model can still reason about
                 // the rest of the bundle.
-                const reads = await Promise.allSettled(paths.map(async (p) => ({ path: p, content: await readFile(p, 'utf8') })));
+                const reads = await Promise.allSettled(paths.map(async (p) => ({ path: p, content: await readGuardedFile(p) })));
                 const sections = [];
                 let successCount = 0;
                 reads.forEach((r, i) => {
@@ -1663,9 +2081,6 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 }
                 const lang = language || 'unknown';
                 const route = await routeToModel('code', model);
-                const outputConstraint = route.hints.outputConstraint
-                    ? ` ${route.hints.outputConstraint}`
-                    : '';
                 const combined = sections.join('\n\n');
                 // Pre-flight prefill estimate. Huge inputs can legitimately exceed
                 // the MCP client's ~60s request timeout during prompt processing, and
@@ -1680,7 +2095,12 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 // avoids the under-prediction a ratio-of-averages produces on inputs
                 // much larger than the historical mean.
                 const estimate = await estimatePrefill(combined.length, route.modelId);
-                const isConfidentEstimate = estimate.basis === 'linear-fit' || estimate.basis === 'ratio';
+                // A poor fit (low R² — e.g. bimodal samples straddling a backend
+                // restart with different perf settings) must not refuse the call: a
+                // false refusal is worse than a false-ok that the prefill keepalive
+                // and timeout machinery already handle.
+                const isConfidentEstimate = (estimate.basis === 'linear-fit' && estimate.fit.r2 >= 0.5) ||
+                    estimate.basis === 'ratio';
                 if (isConfidentEstimate && estimate.estimatedSeconds > PREFILL_REFUSE_THRESHOLD_SEC) {
                     const estSec = Math.round(estimate.estimatedSeconds);
                     const basisLine = estimate.basis === 'linear-fit'
@@ -1708,7 +2128,11 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 const codeMessages = [
                     {
                         role: 'system',
-                        content: `Expert ${lang} developer. Your task: ${task}\n\nThe user has provided ${paths.length} file(s), concatenated below with \`=== filename ===\` headers. Reference files by name in your output. Be specific — line numbers, function names, concrete fixes. Output your analysis as a markdown list.${outputConstraint}`,
+                        content: buildSystemPrompt({
+                            base: `You are a senior ${lang} developer. Your task: ${task}\n\nThe user has provided ${paths.length} file(s), concatenated below with \`=== filename ===\` headers. Reference files by name in your output.`,
+                            formatLine: 'Be specific — line numbers, function names, concrete fixes. Output your analysis as a markdown list.',
+                            modelConstraint: route.hints.outputConstraint,
+                        }),
                     },
                     {
                         role: 'user',
@@ -1719,9 +2143,10 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 // auto-derivation in chatCompletionStreamingInner fires when the caller omits it.
                 const codeResp = await chatCompletionStreaming(codeMessages, {
                     temperature: route.hints.codeTemp,
-                    maxTokens: codeMaxTokens,
+                    maxTokens: validMaxTokens(codeMaxTokens),
                     model: route.modelId,
                     progressToken,
+                    sampling: extractSamplingParams(args),
                 });
                 const readSummary = successCount === paths.length
                     ? `${paths.length} file(s) read`
@@ -1744,7 +2169,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                     return {
                         content: [{
                                 type: 'text',
-                                text: `Status: OFFLINE\nEndpoint: ${LM_BASE_URL}\n${reason}\n\nThe local LLM is not available right now. Do not attempt to delegate tasks to it.`,
+                                text: `Status: OFFLINE\nEndpoint: ${redactUrl(LM_BASE_URL)}\n${reason}\n\nThe local LLM is not available right now. Do not attempt to delegate tasks to it.`,
                             }],
                     };
                 }
@@ -1753,12 +2178,27 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                     return {
                         content: [{
                                 type: 'text',
-                                text: `Status: ONLINE (no model loaded)\nEndpoint: ${LM_BASE_URL}\nLatency: ${ms}ms\n\nThe server is running but no model is loaded. Ask the user to load a model in LM Studio.`,
+                                text: `Status: ONLINE (no model loaded)\nEndpoint: ${redactUrl(LM_BASE_URL)}\nLatency: ${ms}ms\n\nThe server is running but no model is loaded. Ask the user to load a model in LM Studio.`,
                             }],
                     };
                 }
                 const loaded = models.filter((m) => m.state === 'loaded' || !m.state);
                 const available = models.filter((m) => m.state === 'not-loaded');
+                // Models are downloaded but none is loaded (LM Studio with nothing
+                // active). `loaded` still includes state-less models from backends that
+                // don't report load state, so this fires only when every model is
+                // genuinely not-loaded. Report it distinctly instead of presenting an
+                // unloaded model as active — delegating to it would trigger an on-demand
+                // load on the first call and likely blow the client's request timeout.
+                if (loaded.length === 0) {
+                    const names = (available.length > 0 ? available : models).map((m) => m.id).join(', ');
+                    return {
+                        content: [{
+                                type: 'text',
+                                text: `Status: ONLINE (no model loaded)\nEndpoint: ${redactUrl(LM_BASE_URL)}\nLatency: ${ms}ms\n\nThe server is running but no model is currently loaded. Downloaded models the user can load: ${names}\n\nDo not delegate tasks until a model is loaded.`,
+                            }],
+                    };
+                }
                 const primary = loaded[0] || models[0];
                 const ctx = getContextLength(primary);
                 const primaryProfile = await getModelProfileAsync(primary);
@@ -1800,7 +2240,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                     : getBackend() === 'ollama' ? 'Ollama'
                         : 'OpenAI-compatible';
                 let text = `Status: ONLINE\n` +
-                    `Endpoint: ${LM_BASE_URL} (${backendLabel})\n` +
+                    `Endpoint: ${redactUrl(LM_BASE_URL)} (${backendLabel})\n` +
                     `Connection latency: ${ms}ms (does not reflect inference speed)\n` +
                     `Active model: ${primary.id}\n` +
                     `Context window: ${ctx.toLocaleString()} tokens\n` +
@@ -1889,13 +2329,19 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                     const usageInfo = data.usage
                         ? `${data.usage.prompt_tokens} tokens embedded`
                         : '';
+                    // Round to 7 significant figures for transport. Embedding components
+                    // are ~[-1, 1], so this is lossless for any similarity use but roughly
+                    // halves the serialised size — which for high-dimension models
+                    // (4k–8k dims) keeps the tool result from bloating the client context
+                    // or exceeding its result-size limit. Dimensions are preserved.
+                    const compact = embedding.map((x) => Number(x.toPrecision(7)));
                     return {
                         content: [{
                                 type: 'text',
                                 text: JSON.stringify({
                                     model: data.model,
                                     dimensions: embedding.length,
-                                    embedding,
+                                    embedding: compact,
                                     usage: usageInfo,
                                 }),
                             }],
@@ -1910,7 +2356,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 const lines = [];
                 lines.push(`## Houtini LM stats`);
                 lines.push('');
-                lines.push(`**Endpoint**: ${LM_BASE_URL} (${backendLabel})`);
+                lines.push(`**Endpoint**: ${redactUrl(LM_BASE_URL)} (${backendLabel})`);
                 if (lifetime.firstSeenAt) {
                     lines.push(`**First call on this workstation**: ${new Date(lifetime.firstSeenAt).toISOString().slice(0, 10)}`);
                 }
@@ -1999,7 +2445,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
 async function main() {
     const transport = new StdioServerTransport();
     await server.connect(transport);
-    process.stderr.write(`Houtini LM server running (${LM_BASE_URL})\n`);
+    process.stderr.write(`Houtini LM server running (${redactUrl(LM_BASE_URL)})\n`);
     // Background: profile all available models via HF → SQLite cache
     // Non-blocking — server is already accepting requests
     listModelsRaw()