grepmax 0.24.0 → 0.25.0

package/dist/commands/setup.js

@@ -142,10 +142,10 @@ exports.setup = new commander_1.Command("setup")
         const tierChanged = existingConfig.modelTier !== modelTier;
         const modeChanged = existingConfig.embedMode !== embedMode;
         if (tierChanged) {
-            p.log.warn(`Model tier changed (${(_d = existingConfig.vectorDim) !== null && _d !== void 0 ? _d : 384}d → ${selectedTier.vectorDim}d). Existing indexes will be rebuilt on next use.`);
+            p.log.warn(`Model tier changed (${(_d = existingConfig.vectorDim) !== null && _d !== void 0 ? _d : 384}d → ${selectedTier.vectorDim}d). Existing indexes are preserved and search is blocked until you run 'gmax repair --rebuild'.`);
         }
         else if (modeChanged) {
-            p.log.warn("Embedding mode changed. Run `gmax serve` to apply the new settings.");
+            p.log.warn("Embedding mode changed. Restart the gmax daemon to apply the new settings.");
         }
     }
     // Step 8: Install plugins for detected clients

package/dist/commands/similar.js

@@ -43,13 +43,13 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.similar = void 0;
-const path = __importStar(require("node:path"));
 const commander_1 = require("commander");
 const vector_db_1 = require("../lib/store/vector-db");
 const agent_errors_1 = require("../lib/utils/agent-errors");
 const arrow_1 = require("../lib/utils/arrow");
 const exit_1 = require("../lib/utils/exit");
 const filter_builder_1 = require("../lib/utils/filter-builder");
+const path_containment_1 = require("../lib/utils/path-containment");
 const project_registry_1 = require("../lib/utils/project-registry");
 const project_root_1 = require("../lib/utils/project-root");
 const stale_hint_1 = require("../lib/utils/stale-hint");
@@ -81,9 +81,9 @@ exports.similar = new commander_1.Command("similar")
         // Look up the source chunk's vector
         let sourceRows;
         if (isFile) {
-            const absPath = target.startsWith("/")
-                ? target
-                : path.resolve(projectRoot, target);
+            const absPath = (0, path_containment_1.resolveContainedPath)(projectRoot, target, {
+                verifyExistingTarget: true,
+            });
             sourceRows = yield table
                 .query()
                 .select(["vector", "path", "defined_symbols", "start_line"])
@@ -95,7 +95,7 @@ exports.similar = new commander_1.Command("similar")
             sourceRows = yield table
                 .query()
                 .select(["vector", "path", "defined_symbols", "start_line"])
-                .where(`array_contains(defined_symbols, '${(0, filter_builder_1.escapeSqlString)(target)}')`)
+                .where(`array_contains(defined_symbols, '${(0, filter_builder_1.escapeSqlString)(target)}') AND ${(0, filter_builder_1.pathStartsWith)(`${projectRoot}/`)}`)
                 .limit(1)
                 .toArray();
         }

package/dist/commands/skeleton.js

@@ -52,8 +52,8 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.skeleton = void 0;
 const fs = __importStar(require("node:fs"));
-const path = __importStar(require("node:path"));
 const commander_1 = require("commander");
+const config_1 = require("../config");
 const sync_helpers_1 = require("../lib/index/sync-helpers");
 const syncer_1 = require("../lib/index/syncer");
 const searcher_1 = require("../lib/search/searcher");
@@ -62,20 +62,11 @@ const retriever_1 = require("../lib/skeleton/retriever");
 const skeletonizer_1 = require("../lib/skeleton/skeletonizer");
 const vector_db_1 = require("../lib/store/vector-db");
 const exit_1 = require("../lib/utils/exit");
+const file_utils_1 = require("../lib/utils/file-utils");
+const filter_builder_1 = require("../lib/utils/filter-builder");
+const path_containment_1 = require("../lib/utils/path-containment");
 const project_registry_1 = require("../lib/utils/project-registry");
 const project_root_1 = require("../lib/utils/project-root");
-/**
- * Resolve a relative path across all indexed projects.
- * Returns the first match found, or null.
- */
-function resolveAcrossProjects(relativePath) {
-    for (const project of (0, project_registry_1.listProjects)()) {
-        const candidate = path.join(project.root, relativePath);
-        if (fs.existsSync(candidate))
-            return candidate;
-    }
-    return null;
-}
 /**
  * Check if target looks like a file path.
  */
@@ -94,12 +85,16 @@ function isSymbolLike(target) {
 /**
  * Find a file by symbol name in the index.
  */
-function findFileBySymbol(symbol, db) {
+function findFileBySymbol(symbol, db, projectRoot) {
     return __awaiter(this, void 0, void 0, function* () {
         try {
             const table = yield db.ensureTable();
             // Search for files that define this symbol
-            const results = yield table.search(symbol).limit(10).toArray();
+            const results = yield table
+                .search(symbol)
+                .where((0, filter_builder_1.pathStartsWith)(`${projectRoot}/`))
+                .limit(10)
+                .toArray();
             // Find a result where this symbol is defined
             for (const result of results) {
                 const defined = result.defined_symbols;
@@ -144,8 +139,26 @@ Examples:
         // Sync if requested
         if (options.sync) {
             const { spinner, onProgress } = (0, sync_helpers_1.createIndexingSpinner)(projectRoot, "Syncing...", { verbose: false });
-            yield (0, syncer_1.initialSync)({ projectRoot, onProgress });
-            spinner.succeed("Sync complete");
+            const result = yield (0, syncer_1.initialSync)({ projectRoot, onProgress });
+            if (result.degraded) {
+                spinner.warn(`Sync incomplete: ${result.scanErrors} scan error(s), ${result.failedFiles} file failure(s)`);
+            }
+            else {
+                const prefix = projectRoot.endsWith("/")
+                    ? projectRoot
+                    : `${projectRoot}/`;
+                const chunkCount = yield vectorDb.countRowsForPath(prefix);
+                (0, project_registry_1.stampProjectFullSync)({
+                    root: projectRoot,
+                    generation: result.generation,
+                    embedMode: result.embedMode,
+                    chunkCount,
+                    chunkerVersion: config_1.CONFIG.CHUNKER_VERSION,
+                    expectedFingerprint: result.registryExpectation.embeddingFingerprint,
+                    expectedRebuildId: result.registryExpectation.rebuildId,
+                });
+                spinner.succeed("Sync complete");
+            }
         }
         // Initialize skeletonizer
         const skeletonizer = new skeletonizer_1.Skeletonizer();
@@ -154,7 +167,9 @@ Examples:
             includeSummary: !options.noSummary,
         };
         // Determine mode based on target
-        const resolvedTarget = path.resolve(target);
+        const resolvedTarget = (0, path_containment_1.resolveContainedPath)(projectRoot, target, {
+            verifyExistingTarget: true,
+        });
         // Directory mode is unsupported. Auto-picking files from a directory
         // was confusingly magical (and on '.' it fell through to the resolver
         // path and skeletonized .gitignore). Refuse and point at the file form.
@@ -176,12 +191,14 @@ Examples:
                 .map((t) => t.trim())
                 .filter(Boolean);
             for (const t of targets) {
-                const filePath = path.resolve(t);
+                const filePath = (0, path_containment_1.resolveContainedPath)(projectRoot, t, {
+                    verifyExistingTarget: true,
+                });
                 if (!fs.existsSync(filePath)) {
                     console.error(`Not found: ${t}`);
                     continue;
                 }
-                const content = fs.readFileSync(filePath, "utf-8");
+                const content = (0, file_utils_1.readContainedTextFileSync)(projectRoot, filePath);
                 const result = yield skeletonizer.skeletonizeFile(filePath, content, skeletonOpts);
                 outputResult(result, options);
             }
@@ -189,16 +206,13 @@ Examples:
         }
         if (isFilePath(target)) {
             // === FILE MODE ===
-            let filePath = path.resolve(target);
+            const filePath = (0, path_containment_1.resolveContainedPath)(projectRoot, target, {
+                verifyExistingTarget: true,
+            });
             if (!fs.existsSync(filePath)) {
-                // Try resolving across indexed projects
-                const found = resolveAcrossProjects(target);
-                if (!found) {
-                    console.error(`File not found: ${filePath}`);
-                    process.exitCode = 1;
-                    return;
-                }
-                filePath = found;
+                console.error(`File not found: ${filePath}`);
+                process.exitCode = 1;
+                return;
             }
             if (vectorDb) {
                 // Use absolute path for DB lookup (centralized index stores absolute paths)
@@ -212,13 +226,13 @@ Examples:
                     return;
                 }
             }
-            const content = fs.readFileSync(filePath, "utf-8");
+            const content = (0, file_utils_1.readContainedTextFileSync)(projectRoot, filePath);
             const result = yield skeletonizer.skeletonizeFile(filePath, content, skeletonOpts);
             outputResult(result, options);
         }
         else if (isSymbolLike(target) && !target.includes(" ")) {
             // === SYMBOL MODE ===
-            const filePath = yield findFileBySymbol(target, vectorDb);
+            const filePath = yield findFileBySymbol(target, vectorDb, projectRoot);
             if (!filePath) {
                 console.error(`Symbol not found in index: ${target}`);
                 console.error("Try running 'gmax index' first or use a search query.");
@@ -226,9 +240,9 @@ Examples:
                 return;
             }
             // filePath from DB is absolute (centralized index)
-            const absolutePath = path.isAbsolute(filePath)
-                ? filePath
-                : path.resolve(projectRoot, filePath);
+            const absolutePath = (0, path_containment_1.resolveContainedPath)(projectRoot, filePath, {
+                verifyExistingTarget: true,
+            });
             if (!fs.existsSync(absolutePath)) {
                 console.error(`File not found: ${absolutePath}`);
                 process.exitCode = 1;
@@ -243,7 +257,7 @@ Examples:
                 }, options);
                 return;
             }
-            const content = fs.readFileSync(absolutePath, "utf-8");
+            const content = (0, file_utils_1.readContainedTextFileSync)(projectRoot, absolutePath);
             const result = yield skeletonizer.skeletonizeFile(absolutePath, content, skeletonOpts);
             outputResult(result, options);
         }
@@ -251,7 +265,7 @@ Examples:
             // === QUERY MODE ===
             const searcher = new searcher_1.Searcher(vectorDb);
             const limit = Math.min(Number.parseInt(options.limit, 10) || 3, 10);
-            const searchResults = yield searcher.search(target, limit);
+            const searchResults = yield searcher.search(target, limit, {}, {}, `${projectRoot}/`);
             if (!searchResults.data || searchResults.data.length === 0) {
                 console.error(`No results found for: ${target}`);
                 process.exitCode = 1;
@@ -273,9 +287,21 @@ Examples:
             const results = [];
             for (const filePath of filePaths) {
                 // Paths from search results are absolute (centralized index)
-                const absolutePath = path.isAbsolute(filePath)
-                    ? filePath
-                    : path.resolve(projectRoot, filePath);
+                let absolutePath;
+                try {
+                    absolutePath = (0, path_containment_1.resolveContainedPath)(projectRoot, filePath, {
+                        verifyExistingTarget: true,
+                    });
+                }
+                catch (_c) {
+                    results.push({
+                        file: filePath,
+                        skeleton: `// File outside selected project: ${filePath}`,
+                        tokens: 0,
+                        error: "File outside selected project",
+                    });
+                    continue;
+                }
                 if (!fs.existsSync(absolutePath)) {
                     results.push({
                         file: filePath,
@@ -295,7 +321,7 @@ Examples:
                     });
                     continue;
                 }
-                const content = fs.readFileSync(absolutePath, "utf-8");
+                const content = (0, file_utils_1.readContainedTextFileSync)(projectRoot, absolutePath);
                 const result = yield skeletonizer.skeletonizeFile(absolutePath, content, skeletonOpts);
                 results.push({
                     file: filePath,
@@ -326,7 +352,7 @@ Examples:
             try {
                 yield vectorDb.close();
             }
-            catch (_c) {
+            catch (_d) {
                 // Ignore close errors
             }
         }

package/dist/commands/status.js

@@ -46,6 +46,7 @@ exports.status = void 0;
 const os = __importStar(require("node:os"));
 const commander_1 = require("commander");
 const config_1 = require("../config");
+const embedding_status_1 = require("../lib/index/embedding-status");
 const index_config_1 = require("../lib/index/index-config");
 const exit_1 = require("../lib/utils/exit");
 const filter_builder_1 = require("../lib/utils/filter-builder");
@@ -157,7 +158,8 @@ Examples:
                 st = "idle";
             const isCurrent = project.root === currentRoot;
             const count = (_b = chunkCounts.get(project.root)) !== null && _b !== void 0 ? _b : project.chunkCount;
-            console.log(`${project.name}\t${formatChunks(count)}\t${formatAge(project.lastIndexed)}\t${st}${isCurrent ? "\tcurrent" : ""}`);
+            const identity = (0, embedding_status_1.projectEmbeddingStatus)(project, globalConfig);
+            console.log(`${project.name}\t${formatChunks(count)}\t${formatAge(project.lastIndexed)}\t${st}\tembedding=${identity.state}${isCurrent ? "\tcurrent" : ""}`);
         }
         yield (0, exit_1.gracefulExit)();
         return;
@@ -191,10 +193,11 @@ Examples:
         const chunks = `${formatChunks(count)} chunks`;
         // Age column
         const age = formatAge(project.lastIndexed);
+        const embedding = (0, embedding_status_1.projectEmbeddingStatus)(project, globalConfig).state;
         // Current marker
         const marker = isCurrent ? style.cyan(" ←") : "";
         const name = project.name.padEnd(nameWidth);
-        console.log(`  ${name}  ${chunks.padEnd(12)}  ${age.padEnd(10)}  ${statusStr}${marker}`);
+        console.log(`  ${name}  ${chunks.padEnd(12)}  ${age.padEnd(10)}  ${statusStr}  embedding:${embedding}${marker}`);
     }
     if (currentRoot) {
         console.log(`\n${style.dim("Current")}: ${shortenPath(currentRoot)}`);

package/dist/commands/summarize.js

@@ -50,6 +50,12 @@ const syncer_1 = require("../lib/index/syncer");
 const vector_db_1 = require("../lib/store/vector-db");
 const exit_1 = require("../lib/utils/exit");
 const project_root_1 = require("../lib/utils/project-root");
+// ⛔ HARD STOP FOR AI AGENTS: The summarizer is decommissioned on purpose.
+// `generateSummaries` (src/lib/index/syncer.ts) is a no-op stub, so this
+// command intentionally does nothing. DO NOT re-enable it, and DO NOT start
+// the summarizer server (mlx-embed-server/summarizer.py, port 8101) or load its
+// ~16GB model to "measure"/"benchmark" — doing so has crashed the machine.
+// Stop and get the user's explicit authorization first. See CLAUDE.md.
 exports.summarize = new commander_1.Command("summarize")
     .description("Generate LLM summaries for indexed chunks without re-indexing")
     .option("-p, --path <dir>", "Only summarize chunks under this directory")

package/dist/commands/watch.js

@@ -48,7 +48,6 @@ const fs = __importStar(require("node:fs"));
 const path = __importStar(require("node:path"));
 const commander_1 = require("commander");
 const config_1 = require("../config");
-const index_config_1 = require("../lib/index/index-config");
 const syncer_1 = require("../lib/index/syncer");
 const watcher_1 = require("../lib/index/watcher");
 const meta_cache_1 = require("../lib/store/meta-cache");
@@ -122,19 +121,51 @@ exports.watch = new commander_1.Command("watch")
             }
             const logFile = path.join(config_1.PATHS.logsDir, "daemon.log");
             const out = (0, log_rotate_1.openRotatedLog)(logFile);
-            const child = (0, node_child_process_1.spawn)(process.argv[0], [process.argv[1], "watch", "--daemon"], {
-                detached: true,
-                stdio: ["ignore", out, out],
-                cwd: process.cwd(),
-                env: Object.assign(Object.assign({}, process.env), { GMAX_BACKGROUND: "true" }),
-            });
+            let child;
+            try {
+                child = (0, node_child_process_1.spawn)(process.argv[0], [process.argv[1], "watch", "--daemon"], {
+                    detached: true,
+                    stdio: ["ignore", out, out],
+                    cwd: process.cwd(),
+                    env: Object.assign(Object.assign({}, process.env), { GMAX_BACKGROUND: "true" }),
+                });
+                yield new Promise((resolve, reject) => {
+                    child.once("spawn", resolve);
+                    child.once("error", reject);
+                });
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                console.error(`Failed to start daemon: ${message}`);
+                process.exitCode = 1;
+                return;
+            }
+            finally {
+                try {
+                    fs.closeSync(out);
+                }
+                catch (_c) { }
+            }
             child.unref();
             console.log(`Daemon started (PID: ${child.pid}, log: ${logFile})`);
             process.exit(0);
         }
         // Daemon foreground
+        // Stamp every daemon.log line so incidents can be correlated with the
+        // timestamped MLX/LLM server logs. Workers inherit via env flag.
+        const { installTimestampedOutput } = yield Promise.resolve().then(() => __importStar(require("../lib/utils/logger")));
+        installTimestampedOutput();
         const { Daemon } = yield Promise.resolve().then(() => __importStar(require("../lib/daemon/daemon")));
         const daemon = new Daemon();
+        process.on("SIGINT", () => daemon.shutdown().then(() => (0, exit_1.gracefulExit)()));
+        process.on("SIGTERM", () => daemon.shutdown().then(() => (0, exit_1.gracefulExit)()));
+        process.on("uncaughtException", (err) => {
+            console.error("[daemon] uncaughtException:", err);
+            daemon.shutdown().then(() => (0, exit_1.gracefulExit)(1));
+        });
+        process.on("unhandledRejection", (reason) => {
+            console.error("[daemon] unhandledRejection:", reason);
+        });
         try {
             yield daemon.start();
         }
@@ -151,19 +182,10 @@ exports.watch = new commander_1.Command("watch")
             try {
                 yield daemon.shutdown();
             }
-            catch (_c) { }
+            catch (_d) { }
             process.exitCode = 1;
             return;
         }
-        process.on("SIGINT", () => daemon.shutdown().then(() => (0, exit_1.gracefulExit)()));
-        process.on("SIGTERM", () => daemon.shutdown().then(() => (0, exit_1.gracefulExit)()));
-        process.on("uncaughtException", (err) => {
-            console.error("[daemon] uncaughtException:", err);
-            daemon.shutdown().then(() => (0, exit_1.gracefulExit)(1));
-        });
-        process.on("unhandledRejection", (reason) => {
-            console.error("[daemon] unhandledRejection:", reason);
-        });
         return;
     }
     // --- Per-project mode ---
@@ -185,12 +207,31 @@ exports.watch = new commander_1.Command("watch")
         const safeName = projectName.replace(/[^a-zA-Z0-9._-]/g, "_");
         const logFile = path.join(config_1.PATHS.logsDir, `watch-${safeName}.log`);
         const out = (0, log_rotate_1.openRotatedLog)(logFile);
-        const child = (0, node_child_process_1.spawn)(process.argv[0], [process.argv[1], ...args], {
-            detached: true,
-            stdio: ["ignore", out, out],
-            cwd: process.cwd(),
-            env: Object.assign(Object.assign({}, process.env), { GMAX_BACKGROUND: "true" }),
-        });
+        let child;
+        try {
+            child = (0, node_child_process_1.spawn)(process.argv[0], [process.argv[1], ...args], {
+                detached: true,
+                stdio: ["ignore", out, out],
+                cwd: process.cwd(),
+                env: Object.assign(Object.assign({}, process.env), { GMAX_BACKGROUND: "true" }),
+            });
+            yield new Promise((resolve, reject) => {
+                child.once("spawn", resolve);
+                child.once("error", reject);
+            });
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            console.error(`Failed to start watcher for ${projectName}: ${message}`);
+            process.exitCode = 1;
+            return;
+        }
+        finally {
+            try {
+                fs.closeSync(out);
+            }
+            catch (_e) { }
+        }
         child.unref();
         console.log(`Watcher started for ${projectName} (PID: ${child.pid}, log: ${logFile})`);
         process.exit(0);
@@ -225,24 +266,36 @@ exports.watch = new commander_1.Command("watch")
         .where((0, filter_builder_1.pathStartsWith)(prefix))
         .limit(1)
         .toArray();
+    let degraded = false;
+    let degradedErrors = 0;
+    let initialScanErrors = 0;
+    let initialFailedFiles = 0;
     if (indexed.length === 0) {
         console.log(`[watch:${projectName}] No index found for ${projectRoot}, running initial sync...`);
         const syncResult = yield (0, syncer_1.initialSync)({ projectRoot });
-        // Update registry after sync
-        const globalConfig = (0, index_config_1.readGlobalConfig)();
-        (0, project_registry_1.registerProject)({
-            root: projectRoot,
-            name: projectName,
-            vectorDim: globalConfig.vectorDim,
-            modelTier: globalConfig.modelTier,
-            embedMode: globalConfig.embedMode,
-            lastIndexed: new Date().toISOString(),
-            chunkCount: syncResult.indexed,
-            status: "indexed",
-        });
-        console.log(`[watch:${projectName}] Initial sync complete.`);
+        if (syncResult.degraded) {
+            degraded = true;
+            degradedErrors = syncResult.scanErrors + syncResult.failedFiles;
+            initialScanErrors = syncResult.scanErrors;
+            initialFailedFiles = syncResult.failedFiles;
+            console.warn(`[watch:${projectName}] Initial sync incomplete: ${syncResult.scanErrors} scan error(s), ${syncResult.failedFiles} file failure(s). Preserving pending registry state.`);
+        }
+        else {
+            const chunkCount = yield vectorDb.countRowsForPath(prefix);
+            (0, project_registry_1.stampProjectFullSync)({
+                root: projectRoot,
+                name: projectName,
+                generation: syncResult.generation,
+                embedMode: syncResult.embedMode,
+                chunkCount,
+                chunkerVersion: config_1.CONFIG.CHUNKER_VERSION,
+                expectedFingerprint: syncResult.registryExpectation.embeddingFingerprint,
+                expectedRebuildId: syncResult.registryExpectation.rebuildId,
+            });
+            console.log(`[watch:${projectName}] Initial sync complete.`);
+        }
     }
-    (0, watcher_store_1.updateWatcherStatus)(process.pid, "watching");
+    (0, watcher_store_1.updateWatcherStatus)(process.pid, degraded ? "degraded" : "watching", undefined, degraded ? `${degradedErrors} incomplete scan path(s)` : undefined);
     // Open resources for watcher
     const metaCache = new meta_cache_1.MetaCache(paths.lmdbPath);
     // Start watching
@@ -251,10 +304,17 @@ exports.watch = new commander_1.Command("watch")
         vectorDb,
         metaCache,
         dataDir: paths.dataDir,
+        initialScanErrors,
+        initialFailedFiles,
         onReindex: (files, ms) => {
             console.log(`[watch:${projectName}] Reindexed ${files} file${files !== 1 ? "s" : ""} (${(ms / 1000).toFixed(1)}s)`);
             lastActivity = Date.now();
-            (0, watcher_store_1.updateWatcherStatus)(process.pid, "watching", Date.now());
+            (0, watcher_store_1.updateWatcherStatus)(process.pid, degraded ? "degraded" : "watching", Date.now(), degraded ? `${degradedErrors} incomplete scan path(s)` : undefined);
+        },
+        onHealthChange: (complete, errors) => {
+            degraded = !complete;
+            degradedErrors = errors;
+            (0, watcher_store_1.updateWatcherStatus)(process.pid, complete ? "watching" : "degraded", undefined, complete ? undefined : `${errors} incomplete scan path(s)`);
         },
     });
     console.log(`[watch:${projectName}] File watcher active`);
@@ -300,6 +360,10 @@ exports.watch
         const projects = resp.projects;
         const uptime = Math.floor(resp.uptime / 60);
         console.log(`Daemon (PID: ${resp.pid}, uptime: ${uptime}m):`);
+        const mlx = resp.mlx;
+        if (mlx) {
+            console.log(`  MLX: ${mlx.state} (${mlx.model}${mlx.pid ? `, PID ${mlx.pid}` : ""})${mlx.error ? ` — ${mlx.error}` : ""}`);
+        }
         for (const p of projects) {
             console.log(`  - ${p.root} [${p.status}]`);
         }

package/dist/config.js

@@ -217,6 +217,9 @@ exports.PATHS = {
     globalRoot: GLOBAL_ROOT,
     models: path.join(GLOBAL_ROOT, "models"),
     grammars: path.join(GLOBAL_ROOT, "grammars"),
+    // HF cache for the MLX embed server, pinned to internal disk so the server
+    // survives an unmounted external volume behind the user's HF_HOME.
+    hfDir: path.join(GLOBAL_ROOT, "hf"),
     logsDir: path.join(GLOBAL_ROOT, "logs"),
     daemonSocket: path.join(GLOBAL_ROOT, "daemon.sock"),
     daemonPidFile: path.join(GLOBAL_ROOT, "daemon.pid"),