offgrid-ai 0.9.5 → 0.10.0

package/src/process.mjs

@@ -35,11 +35,13 @@ async function startLocalServer(profile) {
 
   // Build argv: binary + command.json args
   const argv = [...commandArgv];
+  // mlx-vlm requires APC_ENABLED=1 (86x TTFT improvement; fixes Metal cache clearing).
+  const env = profile.backend === "mlx-vlm" ? { ...process.env, APC_ENABLED: "1" } : process.env;
 
   const rawFd = openSync(rawLogPath, "a");
   let child;
   try {
-    child = spawn(binary, argv, { detached: true, stdio: ["ignore", rawFd, rawFd] });
+    child = spawn(binary, argv, { detached: true, stdio: ["ignore", rawFd, rawFd], env });
   } finally {
     closeSync(rawFd);
   }
@@ -96,16 +98,134 @@ export async function stopProfile(profile) {
     await writeState(profile.id, { ...state, pid: null, stoppedAt: new Date().toISOString(), stopReason: "pid-not-running" });
     return { stopped: false, message: `${profile.id} pid ${state.pid} is no longer running.` };
   }
+  const pid = state.pid;
   try {
-    try {
-      process.kill(-state.pid, "SIGTERM");
-    } catch {
-      process.kill(state.pid, "SIGTERM");
-    }
-    await writeState(profile.id, { ...state, pid: null, stoppedAt: new Date().toISOString(), stopSignal: "SIGTERM" });
-    return { stopped: true, message: `Stopped ${profile.id} pid ${state.pid}` };
+    const signal = await terminateProcess(pid);
+    await writeState(profile.id, { ...state, pid: null, stoppedAt: new Date().toISOString(), stopSignal: signal });
+    return { stopped: true, message: `Stopped ${profile.id} pid ${pid}` };
   } catch (error) {
-    return { stopped: false, message: `Could not stop pid ${state.pid}: ${error.message}` };
+    return { stopped: false, message: `Could not stop pid ${pid}: ${error.message}` };
+  }
+}
+
+// Reliably terminate a detached local-server process group: SIGTERM with a
+// grace period for graceful shutdown (lets mlx-vlm/llama-server release the
+// model), then SIGKILL if still alive. Guarantees the model is unloaded when a
+// profile stops — consistent across backends (llama-server exits on SIGTERM;
+// mlx-vlm/uvicorn often does not, hence the SIGKILL fallback).
+async function terminateProcess(pid) {
+  const signalGroup = (sig) => {
+    try { process.kill(-pid, sig); }
+    catch { process.kill(pid, sig); } // not a group leader — kill the proc itself
+  };
+  signalGroup("SIGTERM");
+  for (let i = 0; i < 50; i++) { // 5s grace for graceful shutdown
+    if (await processGone(pid)) return "SIGTERM";
+    await sleep(100);
+  }
+  signalGroup("SIGKILL");
+  for (let i = 0; i < 30; i++) { // 3s for SIGKILL to take effect
+    if (await processGone(pid)) return "SIGKILL";
+    await sleep(100);
+  }
+  throw new Error(`pid ${pid} did not exit after SIGKILL`);
+}
+
+// True if the process is dead (or a zombie about to be reaped).
+async function processGone(pid) {
+  try { process.kill(pid, 0); }
+  catch { return true; } // no such process
+  // Alive to signal(0) — but a detached setsid child can briefly appear as a
+  // zombie before launchd reaps it. Treat zombie as gone.
+  try {
+    const { stdout } = await execFileAsync("ps", ["-o", "stat=", "-p", String(pid)]);
+    return /^Z/.test(stdout.trim());
+  } catch {
+    return false;
+  }
+}
+
+// ── Unload model from a managed server (oMLX) ─────────────────────────────
+// Counterpart to stopProfile for local-server backends: stopProfile kills the
+// server process (which unloads the model); unloadModelFromServer asks a
+// managed server to release the model from memory via its HTTP API, leaving the
+// server itself running. Together they give a consistent UX: quitting Pi
+// unloads the model regardless of backend type.
+
+export async function unloadModelFromServer(profile) {
+  const backend = backendFor(profile.backend);
+
+  if (backend.id === "llama-cpp" || backend.id === "llama-cpp-mtp") {
+    // llama.cpp unloads when the server process exits; no HTTP unload API exists.
+    // If offgrid-ai started the server, stopProfile already handled it.
+    return { unloaded: false, backend: backend.id, reason: "stop server to unload" };
+  }
+
+  if (backend.id === "omlx") {
+    return await unloadOmlxModel(profile);
+  }
+
+  if (backend.id === "mlx-vlm") {
+    // mlx-vlm is a local-server backend — stopProfile handles unload by killing
+    // the process. No HTTP unload API.
+    return { unloaded: false, backend: backend.id, reason: "stop server to unload" };
+  }
+
+  return { unloaded: false, backend: backend.id, reason: "unsupported backend" };
+}
+
+async function unloadOmlxModel(profile) {
+  const baseUrl = profile.baseUrl?.replace(/\/v1\/?$/u, "") || "";
+  const adminUrl = `${baseUrl}/admin/api/models`;
+  const modelId = profile.modelAlias || profile.omlxModel || profile.id;
+
+  try {
+    const ids = await serverModelIds(profile.baseUrl);
+    const match = ids.find((id) => id.toLowerCase() === modelId.toLowerCase());
+    const targetId = match ?? modelId;
+
+    const response = await fetch(`${adminUrl}/${encodeURIComponent(targetId)}/unload`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      signal: AbortSignal.timeout(30000),
+    });
+
+    if (response.ok) {
+      return { unloaded: true, backend: "omlx", modelId: targetId };
+    }
+
+    const detail = await responseErrorDetail(response);
+
+    if (response.status === 400 && /not loaded/i.test(detail)) {
+      return { unloaded: true, backend: "omlx", modelId: targetId, reason: "model was not loaded" };
+    }
+
+    if (response.status === 401 || response.status === 403) {
+      return {
+        unloaded: false,
+        backend: "omlx",
+        modelId: targetId,
+        error: "oMLX admin authentication required. Enable skip_api_key_verification in oMLX settings, or unload manually from the admin panel.",
+      };
+    }
+
+    return { unloaded: false, backend: "omlx", modelId: targetId, error: `HTTP ${response.status}: ${detail}` };
+  } catch (err) {
+    if (err?.name === "AbortError" || err?.name === "TimeoutError") {
+      return { unloaded: false, backend: "omlx", modelId, error: "Unload request timed out. The model may still be unloading in the background." };
+    }
+    return { unloaded: false, backend: "omlx", modelId, error: err.message };
+  }
+}
+
+async function responseErrorDetail(response) {
+  const text = await response.text().catch(() => "");
+  if (!text) return "";
+  try {
+    const body = JSON.parse(text);
+    return body?.detail ?? body?.message ?? text;
+  } catch {
+    return text;
   }
 }
 
@@ -126,7 +246,6 @@ export async function isProfileServerUp(profile) {
 
 export async function modelLoadedOnServer(profile) {
   const backend = backendFor(profile.backend);
-  if (backend.id === "ollama") return modelIdsMatch(await ollamaLoadedModelIds(profile), expectedModelIds(profile));
   if (backend.id === "omlx") return modelIdsMatch(await omlxLoadedModelIds(profile), expectedModelIds(profile));
   const { matches } = await serverMatchesProfile(profile);
   return matches;
@@ -134,9 +253,6 @@ export async function modelLoadedOnServer(profile) {
 
 export async function modelAvailableOnServer(profile) {
   const backend = backendFor(profile.backend);
-  if (backend.id === "ollama") {
-    return modelIdsMatch(await ollamaAvailableModelIds(profile), expectedModelIds(profile));
-  }
   if (backend.id === "omlx") {
     // /v1/models lists discovered models; an ID must exist there to be usable.
     return modelIdsMatch(await serverModelIds(profile.baseUrl), expectedModelIds(profile));
@@ -217,24 +333,6 @@ export async function serverModelIds(baseUrl) {
     .filter(Boolean);
 }
 
-async function ollamaLoadedModelIds(profile) {
-  const result = await fetchJson(`${apiRootUrl(profile.baseUrl)}/api/ps`);
-  if (!result.ok) return [];
-  return (Array.isArray(result.data?.models) ? result.data.models : [])
-    .flatMap((model) => [model?.name, model?.model])
-    .map((id) => String(id ?? "").trim())
-    .filter(Boolean);
-}
-
-async function ollamaAvailableModelIds(profile) {
-  const result = await fetchJson(`${apiRootUrl(profile.baseUrl)}/api/tags`);
-  if (!result.ok) return [];
-  return (Array.isArray(result.data?.models) ? result.data.models : [])
-    .flatMap((model) => [model?.name, model?.model])
-    .map((id) => String(id ?? "").trim())
-    .filter(Boolean);
-}
-
 async function omlxLoadedModelIds(profile) {
   const statusResult = await fetchJson(`${profile.baseUrl.replace(/\/+$/u, "")}/models/status`);
   const fromStatus = statusResult.ok
@@ -305,7 +403,6 @@ function expectedModelIds(profile) {
   return [
     profile.modelAlias,
     profile.label,
-    profile.ollamaModel,
     profile.omlxModel,
     profile.modelPath,
     fileName,

package/src/profile-setup.mjs

@@ -1,3 +1,4 @@
+import { existsSync } from "node:fs";
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
 import { estimateMemory } from "./estimate.mjs";
@@ -7,6 +8,7 @@ import { pc, formatBytes, renderRows, renderSection } from "./ui.mjs";
 import { detectCapabilities } from "./autodetect.mjs";
 import { matchDrafter } from "./scan.mjs";
 import { scanGgufModels } from "./scan.mjs";
+import { estimateMemoryMb } from "./mlx-flags.mjs";
 
 const execFileAsync = promisify(execFile);
 
@@ -36,6 +38,10 @@ export async function configureLocalProfile(prompt, profile) {
   // so that re-setup can pick up MTP availability, vision changes, etc.
   const freshCaps = detectCapabilities(profile.modelPath, profile.mmprojPath);
   let drafterPath = profile.drafterPath ?? null;
+  if (drafterPath && !existsSync(drafterPath)) {
+    // Stored drafter is no longer on disk — drop it and re-scan for a fresh one.
+    drafterPath = null;
+  }
   if (!drafterPath) {
     const { drafters } = await scanGgufModels();
     const drafter = matchDrafter(profile.modelPath, drafters);
@@ -47,6 +53,12 @@ export async function configureLocalProfile(prompt, profile) {
   if (hasMtp && configured.backend !== "llama-cpp-mtp") {
     configured = { ...configured, backend: "llama-cpp-mtp", providerId: "llama-cpp-mtp", drafterPath, capabilities: { ...configured.capabilities, mtp: true } };
   }
+  // If the profile was MTP but the drafter is now gone (and the model isn't
+  // natively MTP), switch back to plain llama.cpp so the server can start.
+  if (!hasMtp && configured.backend === "llama-cpp-mtp") {
+    console.log(pc.yellow("MTP drafter no longer found — switching to llama.cpp without speculative decoding."));
+    configured = removeMtpDefaults(configured);
+  }
   if (drafterPath && !configured.drafterPath) {
     configured = { ...configured, drafterPath };
   }
@@ -286,3 +298,107 @@ function detectionSummary(caps) {
 function samplingSummary(flags) {
   return `temp ${flags.temperature}, top-p ${flags.topP}, top-k ${flags.topK}`;
 }
+
+// ── MLX profile configuration ─────────────────────────────────────────────
+
+/**
+ * Interactive configuration for an mlx-vlm profile.
+ */
+export async function configureMlxProfile(prompt, profile) {
+  let configured = profile;
+
+  console.log("");
+  console.log(renderSection("Model setup", renderRows([
+    ["Model", pc.bold(profile.label)],
+    ["Detected", mlxDetectionSummary(configured.capabilities)],
+    ["Context", String(configured.flags.ctxSize) + " tokens"],
+  ])));
+  console.log(pc.dim("Larger context windows use more memory. You can edit the profile later if needed.\n"));
+
+  if (configured.capabilities.vision) {
+    console.log(renderSection("Vision detected", renderRows([
+      ["Capability", "image / multimodal input"],
+      ["Note", "mlx-vlm loads vision from the model directory automatically."],
+    ])));
+  }
+
+  if (configured.capabilities.thinking) {
+    console.log("");
+    console.log(renderSection("Thinking mode", renderRows([
+      ["Flag", "--enable-thinking"],
+      ["Default", "on for Qwen 3 / Gemma 4 / DeepSeek-R class models"],
+    ])));
+    const useThinking = await prompt.yesNo("Enable thinking mode?", true);
+    configured = await applyMlxThinkingToggle(configured, useThinking);
+  }
+
+  const ctxSize = await prompt.number("Context window tokens", configured.flags.ctxSize, 1024, 1048576);
+  configured = applyMlxContextSize(configured, ctxSize);
+
+  console.log("\n" + renderMlxMemoryEstimate(configured));
+
+  console.log("");
+  console.log(renderSection("Defaults", renderRows([
+    ["Backend", configured.backend],
+    ["Endpoint", configured.baseUrl],
+    ["Context", String(configured.flags.ctxSize) + " tokens"],
+    ["Thinking", configured.capabilities.thinking && configured.commandArgv.includes("--enable-thinking") ? "on" : "off"],
+    ["Vision", configured.capabilities.vision ? "yes" : "no"],
+  ])));
+
+  if (!(await prompt.yesNo("Save profile with these settings?", true))) return null;
+  return configured;
+}
+
+async function applyMlxThinkingToggle(profile, enabled) {
+  if (!profile.capabilities.thinking) return profile;
+  const { computeMlxVlmFlags } = await import("./mlx-flags.mjs");
+  const { args } = computeMlxVlmFlags(profile.modelPath, {
+    port: profile.flags.port,
+    ctxSize: profile.flags.ctxSize,
+    thinkingEnabled: enabled,
+  });
+  return {
+    ...profile,
+    commandArgv: args,
+    capabilities: { ...profile.capabilities, thinkingEnabled: enabled },
+  };
+}
+
+function applyMlxContextSize(profile, ctxSize) {
+  const flags = { ...profile.flags, ctxSize };
+  const next = {
+    ...profile,
+    flags,
+    baseUrl: baseUrlForFlags(flags),
+  };
+  const idx = next.commandArgv.indexOf("--max-kv-size");
+  if (idx !== -1 && next.commandArgv[idx + 1] != null) {
+    next.commandArgv[idx + 1] = String(ctxSize);
+  } else if (ctxSize && ctxSize > 0) {
+    next.commandArgv.push("--max-kv-size", String(ctxSize));
+  }
+  return next;
+}
+
+function renderMlxMemoryEstimate(profile) {
+  const modelBytes = profile.modelSizeBytes || 0;
+  if (!modelBytes) {
+    return renderSection("Memory estimate", pc.dim("Model size unknown — save the profile to estimate."));
+  }
+  const totalMb = estimateMemoryMb(modelBytes);
+  const overheadBytes = Math.max(0, totalMb * 1024 * 1024 - modelBytes);
+  return renderSection("Memory estimate", renderRows([
+    ["Estimated total", pc.bold(`~${formatBytes(totalMb * 1024 * 1024)}`)],
+    ["Model", formatBytes(modelBytes)],
+    ["Overhead", `~${formatBytes(overheadBytes)} (KV cache, APC, runtime)`],
+  ]));
+}
+
+function mlxDetectionSummary(caps) {
+  const parts = [];
+  if (caps.architecture) parts.push(caps.architecture);
+  if (caps.thinking) parts.push("thinking");
+  if (caps.vision) parts.push("vision");
+  return parts.length > 0 ? parts.join(" · ") : "standard MLX";
+}

package/src/profiles.mjs

@@ -4,6 +4,8 @@ import { join } from "node:path";
 import { PROFILE_DIR, RUN_DIR, LOG_DIR } from "./config.mjs";
 import { backendFor, baseUrlForFlags, defaultFlagsForBackend } from "./backends.mjs";
 import { computeFlags } from "./autodetect.mjs";
+import { detectMlxCapabilities, defaultMlxContextLength } from "./mlx-discovery.mjs";
+import { detectHardware } from "./hardware.mjs";
 import { readJson, writeJson } from "./json.mjs";
 
 // ── Path helpers ───────────────────────────────────────────────────────────
@@ -161,6 +163,34 @@ export async function createProfileFromModel(model, backendId, drafterPath) {
   });
 }
 
+// ── Auto-create profile from a discovered MLX model ────────────────────────
+
+export async function createProfileFromMlxModel(model) {
+  const { computeMlxVlmFlags, DEFAULT_PORT } = await import("./mlx-flags.mjs");
+  const caps = await detectMlxCapabilities(model.filePath);
+  const ctxSize = defaultMlxContextLength(caps.contextLength, detectHardware().totalRamBytes / (1024 ** 3));
+  const { args } = computeMlxVlmFlags(model.filePath, {
+    port: DEFAULT_PORT,
+    ctxSize,
+    thinkingEnabled: caps.thinking,
+  });
+  return normalizeProfile({
+    id: slugFromLabel(model.label),
+    label: model.label,
+    backend: "mlx-vlm",
+    providerId: "mlx-vlm",
+    modelAlias: model.label,
+    source: model.source,
+    modelPath: model.filePath,
+    mmprojPath: null,
+    drafterPath: null,
+    modelSizeBytes: model.sizeBytes,
+    capabilities: caps,
+    flags: { host: "127.0.0.1", port: DEFAULT_PORT, ctxSize },
+    commandArgv: args,
+  });
+}
+
 function summarizeCapabilities(caps) {
   return {
     architecture: caps.architecture,

package/src/recommendations.mjs

@@ -1,17 +1,59 @@
-import { totalmem } from "node:os";
-
-const MODEL_TIERS = [
-  { maxGB: 8, lms: "google/gemma-4-e2b", ollama: "gemma4:e2b", label: "Gemma 4 E2B (2B effective)" },
-  { maxGB: 16, lms: "google/gemma-4-e4b", ollama: "gemma4:e4b", label: "Gemma 4 E4B (4B effective)" },
-  { maxGB: 32, lms: "qwen/qwen3.5-9b", ollama: "qwen3.5:9b-q4_K_M", label: "Qwen 3.5 9B" },
-  { maxGB: Infinity, lms: "qwen/qwen3.6-35b-a3b", ollama: "qwen3.6:35b-a3b", label: "Qwen 3.6 35B-A3B" },
-];
-
-export function recommendedModel() {
-  const gb = totalmem() / (1024 ** 3);
-  return MODEL_TIERS.find((tier) => gb <= tier.maxGB) ?? MODEL_TIERS[MODEL_TIERS.length - 1];
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { detectHardware } from "./hardware.mjs";
+
+const GB = 1024 ** 3;
+
+const RECOMMENDATIONS_PATH = join(dirname(fileURLToPath(import.meta.url)), "..", "resources", "recommendations.json");
+
+function loadRecommendations() {
+  try {
+    const raw = readFileSync(RECOMMENDATIONS_PATH, "utf8");
+    return JSON.parse(raw).models ?? [];
+  } catch {
+    return [];
+  }
+}
+
+/** All curated model entries. */
+export function getModelEntries() {
+  return loadRecommendations();
+}
+
+/** Recommend models that fit the detected hardware (max tier first). */
+export function recommendModels(hardware) {
+  const entries = loadRecommendations();
+  const fitting = entries.filter((e) => e.minRamGb * GB <= hardware.totalRamBytes);
+  if (fitting.length === 0) return [];
+  const maxTier = Math.max(...fitting.map((e) => e.minRamGb));
+  // All models at the top fitting tier are genuine alternatives; sort by label
+  // so the pick is deterministic regardless of JSON order.
+  return fitting
+    .filter((e) => e.minRamGb === maxTier)
+    .sort((a, b) => a.label.localeCompare(b.label));
+}
+
+/** Pick the best format for the platform. */
+export function selectFormat(entry, hardware) {
+  if (hardware.platform === "darwin" && hardware.arch === "arm64") {
+    if (entry.mlx) return "mlx";
+    if (entry.gguf) return "gguf";
+  } else {
+    if (entry.gguf) return "gguf";
+  }
+  return null;
+}
+
+/** Primary recommendation for this machine. */
+export function recommendedModel(hardware) {
+  const fitting = recommendModels(hardware ?? detectHardware());
+  return fitting[0] ?? null;
 }
 
-export function installedRamGB() {
-  return (totalmem() / (1024 ** 3)).toFixed(0);
+/** All models that fit, sorted best-first (tier desc, then label). */
+export function allFittingModels(hardware) {
+  const entries = loadRecommendations();
+  const fitting = entries.filter((e) => e.minRamGb * GB <= hardware.totalRamBytes);
+  return fitting.sort((a, b) => b.minRamGb - a.minRamGb || a.label.localeCompare(b.label));
 }

package/src/scan.mjs

@@ -1,9 +1,10 @@
 import { statSync } from "node:fs";
-import { readdir } from "node:fs/promises";
+import { readdir, stat } from "node:fs/promises";
 import { basename, dirname, join } from "node:path";
 import { getModelScanDirs } from "./config.mjs";
 import { readGgufMetadata } from "./gguf.mjs";
 import { parseModelName } from "./model-name.mjs";
+import { inferSourceLabel, MIN_MODEL_SIZE_BYTES, EMBEDDING_MODEL_TYPES } from "./discovery-shared.mjs";
 
 // ── Scan for GGUF models and MTP drafters ────────────────────────────────
 
@@ -13,7 +14,8 @@ export async function scanGgufModels(dirs) {
   const allDrafters = [];
 
   for (const root of scanDirs) {
-    const { models, drafters } = await scanOneDir(root);
+    const sourceLabel = inferSourceLabel(root);
+    const { models, drafters } = await scanOneDir(root, sourceLabel);
     allModels.push(...models);
     allDrafters.push(...drafters);
   }
@@ -36,7 +38,7 @@ export async function scanGgufModels(dirs) {
   return { models, drafters };
 }
 
-async function scanOneDir(root) {
+async function scanOneDir(root, sourceLabel = "local-gguf") {
   const files = await findFiles(root, (path) => path.toLowerCase().endsWith(".gguf"));
   const mmprojs = files.filter((path) => basename(path).toLowerCase().includes("mmproj"));
   const candidates = files.filter((path) => !basename(path).toLowerCase().includes("mmproj"));
@@ -49,12 +51,15 @@ async function scanOneDir(root) {
     const mmprojPath = mmprojs.find((candidate) => dirname(candidate) === dir) ?? null;
     const name = basename(path).replace(/\.gguf$/i, "");
     const sizeBytes = statSync(path).size;
+    if (sizeBytes < MIN_MODEL_SIZE_BYTES) continue;
     const parsed = parseModelName(name, "local-gguf");
 
-    // Read GGUF metadata to detect drafter architecture
+    // Read GGUF metadata to detect drafter architecture and embeddings
     const meta = safeReadGgufMetadata(path);
     const architecture = typeof meta["general.architecture"] === "string" ? meta["general.architecture"] : null;
 
+    if (isEmbeddingArchitecture(architecture, name)) continue;
+
     if (architecture === "gemma4-assistant" || architecture === "gemma4_assistant") {
       // This is an MTP drafter model, not a main model
       drafters.push({
@@ -66,7 +71,7 @@ async function scanOneDir(root) {
         architecture,
         targetHint: drafterTargetHint(name),
         backend: "llama-cpp",
-        source: "local-gguf",
+        source: sourceLabel,
       });
     } else {
       models.push({
@@ -77,7 +82,7 @@ async function scanOneDir(root) {
         quant: parsed.quant,
         sizeBytes,
         backend: "llama-cpp",
-        source: "local-gguf",
+        source: sourceLabel,
       });
     }
   }
@@ -85,6 +90,26 @@ async function scanOneDir(root) {
   return { models, drafters };
 }
 
+// ── Embedding model filtering ─────────────────────────────────────────────
+
+const EMBEDDING_FILENAME_PATTERNS = [
+  /(?:^|[-_])bge[-_]/i,
+  /(?:^|[-_])jina[-_]/i,
+  /(?:^|[-_])e5[-_]/i,
+  /(?:^|[-_])gte[-_]/i,
+  /(?:^|[-_])all[-_]minilm/i,
+  /(?:^|[-_])mpnet/i,
+  /(?:^|[-_])nomic[-_]embed/i,
+  /(?:^|[-_])embed/i,
+  /(?:^|[-_])rerank/i,
+];
+
+export function isEmbeddingArchitecture(architecture, filename = "") {
+  if (architecture && EMBEDDING_MODEL_TYPES.has(architecture.toLowerCase())) return true;
+  const lowerName = filename.toLowerCase();
+  return EMBEDDING_FILENAME_PATTERNS.some((pattern) => pattern.test(lowerName));
+}
+
 // ── Match drafters to target models ────────────────────────────────────
 
 // Map a drafter filename to a regex that matches its target model filenames.
@@ -137,8 +162,14 @@ async function findFiles(root, predicate) {
     }
     for (const entry of entries) {
       const path = join(dir, entry.name);
-      if (entry.isDirectory()) await walk(path);
-      else if (entry.isFile() && predicate(path)) result.push(path);
+      if (entry.isDirectory() || entry.isSymbolicLink()) {
+        // Follow symlinks (HF cache uses them) and avoid recursion loops.
+        const stats = await stat(path).catch(() => null);
+        if (stats?.isDirectory()) await walk(path);
+        else if (stats?.isFile() && predicate(path)) result.push(path);
+      } else if (entry.isFile() && predicate(path)) {
+        result.push(path);
+      }
     }
   }
   await walk(root);