@jagilber-org/index-server 1.27.0 → 1.28.0

package/dist/dashboard/server/AdminPanelConfig.js

@@ -4,6 +4,10 @@
  *
  * Owns the AdminConfig data structure and provides CRUD methods for
  * reading and updating admin panel configuration.
+ *
+ * Updates here mutate `process.env.INDEX_SERVER_*` and call `reloadRuntimeConfig()`
+ * so the dashboard "Server Configuration" panel reflects (and applies to) the
+ * single runtimeConfig source of truth.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.AdminPanelConfig = void 0;
@@ -39,14 +43,18 @@ class AdminPanelConfig {
             }
         };
     }
+    /** Re-read from runtime config so callers always see the current authoritative values. */
     getAdminConfig() {
+        this.config = this.loadDefaultConfig();
         return JSON.parse(JSON.stringify(this.config));
     }
     updateAdminConfig(updates) {
         try {
-            this.config = { ...this.config, ...updates };
-            this.applyConfigChanges(updates);
-            return { success: true, message: 'Configuration updated successfully' };
+            const applied = [];
+            this.applyConfigChanges(updates, applied);
+            // Refresh in-memory snapshot from runtime config (post-reload).
+            this.config = this.loadDefaultConfig();
+            return { success: true, message: 'Configuration updated successfully', appliedFields: applied };
         }
         catch (error) {
             return {
@@ -55,21 +63,43 @@ class AdminPanelConfig {
             };
         }
     }
-    applyConfigChanges(updates) {
-        if (updates.serverSettings) {
-            let runtimeReloadNeeded = false;
-            if (updates.serverSettings.enableVerboseLogging !== undefined) {
-                process.env.INDEX_SERVER_VERBOSE_LOGGING = updates.serverSettings.enableVerboseLogging ? '1' : '0';
-                runtimeReloadNeeded = true;
-            }
-            if (updates.serverSettings.enableMutation !== undefined) {
-                process.env.INDEX_SERVER_MUTATION = updates.serverSettings.enableMutation ? '1' : '0';
-                runtimeReloadNeeded = true;
-            }
-            if (runtimeReloadNeeded) {
-                (0, runtimeConfig_1.reloadRuntimeConfig)();
-            }
+    /**
+     * Apply incoming serverSettings to `process.env.INDEX_SERVER_*` and reload runtime config
+     * so the dashboard form actually drives behavior. Bind every editable field to its env var
+     * (per constitution S-4: "All environment configuration must flow through runtimeConfig.ts").
+     */
+    applyConfigChanges(updates, applied = []) {
+        if (!updates.serverSettings)
+            return;
+        const s = updates.serverSettings;
+        let needsReload = false;
+        if (s.enableVerboseLogging !== undefined) {
+            process.env.INDEX_SERVER_VERBOSE_LOGGING = s.enableVerboseLogging ? '1' : '0';
+            applied.push('verboseLogging');
+            needsReload = true;
+        }
+        if (s.enableMutation !== undefined) {
+            process.env.INDEX_SERVER_MUTATION = s.enableMutation ? '1' : '0';
+            applied.push('mutation');
+            needsReload = true;
+        }
+        if (s.maxConnections !== undefined && Number.isFinite(s.maxConnections) && s.maxConnections > 0) {
+            process.env.INDEX_SERVER_MAX_CONNECTIONS = String(Math.floor(s.maxConnections));
+            applied.push('maxConnections');
+            needsReload = true;
+        }
+        if (s.requestTimeout !== undefined && Number.isFinite(s.requestTimeout) && s.requestTimeout > 0) {
+            process.env.INDEX_SERVER_REQUEST_TIMEOUT = String(Math.floor(s.requestTimeout));
+            applied.push('requestTimeout');
+            needsReload = true;
+        }
+        if (s.rateLimit && s.rateLimit.perMinute !== undefined && Number.isFinite(s.rateLimit.perMinute) && s.rateLimit.perMinute >= 0) {
+            process.env.INDEX_SERVER_RATE_LIMIT = String(Math.floor(s.rateLimit.perMinute));
+            applied.push('rateLimitPerMinute');
+            needsReload = true;
         }
+        if (needsReload)
+            (0, runtimeConfig_1.reloadRuntimeConfig)();
     }
     /** Session timeout in milliseconds — consumed by state management. */
     get sessionTimeout() {

package/dist/dashboard/server/AdminPanelState.js

@@ -5,8 +5,12 @@
  * Manages active admin sessions and session history, including
  * persistence, creation, termination, and cleanup of expired sessions.
  */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.AdminPanelState = void 0;
+const crypto_1 = __importDefault(require("crypto"));
 const runtimeConfig_1 = require("../../config/runtimeConfig");
 const SessionPersistenceManager_1 = require("./SessionPersistenceManager");
 const logger_js_1 = require("../../services/logger.js");
@@ -178,7 +182,7 @@ class AdminPanelState {
         }
     }
     generateSessionId() {
-        return `admin_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
+        return `admin_${crypto_1.default.randomUUID()}`;
     }
     getSessionHistory(limit) {
         const slice = typeof limit === 'number' ? this.sessionHistory.slice(0, Math.max(0, limit)) : this.sessionHistory;

package/dist/dashboard/server/ApiRoutes.js

@@ -148,6 +148,7 @@ function createApiRoutes(options = {}) {
                         const success = res.statusCode < 500;
                         const route = normalizeRoute(req);
                         const toolId = `http/${req.method} ${route}`;
+                        metricsCollector.recordToolCall('http/request', success, ms, success ? undefined : `http_${res.statusCode}`);
                         metricsCollector.recordToolCall(toolId, success, ms, success ? undefined : `http_${res.statusCode}`);
                     }
                     catch { /* never block response path */ }
@@ -185,7 +186,7 @@ function createApiRoutes(options = {}) {
     // -------------------------------------------------------------------------
     // Pre-load instruction index once per request so route handlers can use
     // res.locals.indexState instead of calling ensureLoaded() repeatedly.
-    // See: https://github.com/jagilber-dev/index-server/issues/45
+    // See internal tracker #45.
     router.use(ensureLoadedMiddleware_js_1.ensureLoadedMiddleware);
     // Mount route modules
     router.use((0, index_js_1.createStatusRoutes)(metricsCollector));

package/dist/dashboard/server/DashboardServer.js

@@ -146,6 +146,19 @@ class DashboardServer {
             }
             next();
         });
+        // Structured request logger — every dashboard HTTP hit lands in mcp-server.log.
+        // Critical for diagnosing import/restore failures where stderr output is lost
+        // when the MCP server runs under stdio transport without an attached TTY.
+        this.app.use((req, res, next) => {
+            const start = Date.now();
+            const ctype = req.header('content-type') || '';
+            const clen = req.header('content-length') || '';
+            (0, logger_js_1.logInfo)('[http] request', { method: req.method, url: req.originalUrl || req.url, ctype, clen });
+            res.on('finish', () => {
+                (0, logger_js_1.logInfo)('[http] response', { method: req.method, url: req.originalUrl || req.url, status: res.statusCode, ms: Date.now() - start });
+            });
+            next();
+        });
         this.app.use(express_1.default.json());
         this.app.use(express_1.default.static(path_1.default.join(__dirname, '..', 'client'), {
             etag: true,

package/dist/dashboard/server/MetricsCollector.js

@@ -14,6 +14,7 @@ exports.MetricsCollector = void 0;
 exports.getMetricsCollector = getMetricsCollector;
 exports.setMetricsCollector = setMetricsCollector;
 const fs_1 = __importDefault(require("fs"));
+const crypto_1 = __importDefault(require("crypto"));
 const path_1 = __importDefault(require("path"));
 const v8_1 = __importDefault(require("v8"));
 const FileMetricsStorage_js_1 = require("./FileMetricsStorage.js");
@@ -690,7 +691,7 @@ class MetricsCollector {
             recentActivity: (0, metricsSerializer_js_1.buildRecentActivity)(this.tools),
             streamingStats: {
                 totalStreamingConnections: this.activeConnections,
-                dataTransferRate: this.connections.size * 0.1 + Math.random() * 0.5,
+                dataTransferRate: this.connections.size * 0.1 + Math.random() * 0.5, // nosemgrep: insecure-randomness — simulated metric jitter
                 latency,
                 compressionRatio: 0.7,
             },
@@ -735,7 +736,7 @@ class MetricsCollector {
      */
     generateRealTimeAlert(type, severity, message, value, threshold) {
         const alert = {
-            id: `alert_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`,
+            id: `alert_${Date.now()}_${crypto_1.default.randomBytes(6).toString('hex')}`,
             type: type,
             severity: severity,
             message,

package/dist/dashboard/server/WebSocketManager.js

@@ -148,7 +148,7 @@ class WebSocketManager {
         }
         catch {
             // Fallback simple id
-            ws.clientId = `client-${Date.now()}-${Math.floor(Math.random() * 1000)}`;
+            ws.clientId = `client-${Date.now()}-${Math.floor(Math.random() * 1000)}`; // lgtm[js/insecure-randomness] — fallback when safeGenerateClientId() throws; loopback-only dashboard
         }
         ws.connectedAt = Date.now();
         ws.lastActivity = Date.now();
@@ -327,7 +327,7 @@ class WebSocketManager {
         if (typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function') {
             return crypto.randomUUID();
         }
-        return 'client-' + Math.random().toString(36).slice(2);
+        return 'client-' + Math.random().toString(36).slice(2); // lgtm[js/insecure-randomness] — fallback when crypto.randomUUID unavailable
     }
     /** Send current metrics snapshot to a specific client */
     sendCurrentMetrics(client) {

package/dist/dashboard/server/middleware/ensureLoadedMiddleware.d.ts

@@ -8,7 +8,7 @@
  * Mutation handlers that call invalidate() must still call ensureLoaded()
  * explicitly after invalidation to pick up their own changes.
  *
- * See: https://github.com/jagilber-dev/index-server/issues/45
+ * See internal tracker #45.
  */
 import { Request, Response, NextFunction } from 'express';
 import { IndexState } from '../../../services/indexContext.js';

package/dist/dashboard/server/middleware/ensureLoadedMiddleware.js

@@ -9,7 +9,7 @@
  * Mutation handlers that call invalidate() must still call ensureLoaded()
  * explicitly after invalidation to pick up their own changes.
  *
- * See: https://github.com/jagilber-dev/index-server/issues/45
+ * See internal tracker #45.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ensureLoadedMiddleware = ensureLoadedMiddleware;

package/dist/dashboard/server/routes/admin.routes.js

@@ -23,6 +23,8 @@ const AdminPanel_js_1 = require("../AdminPanel.js");
 const WebSocketManager_js_1 = require("../WebSocketManager.js");
 const featureFlags_js_1 = require("../../../services/featureFlags.js");
 const handlers_dashboardConfig_js_1 = require("../../../services/handlers.dashboardConfig.js");
+const runtimeConfig_js_1 = require("../../../config/runtimeConfig.js");
+const eventBuffer_js_1 = require("../../../services/eventBuffer.js");
 const registry_js_1 = require("../../../server/registry.js");
 const adminAuth_js_1 = require("./adminAuth.js");
 const logger_js_1 = require("../../../services/logger.js");
@@ -91,10 +93,35 @@ function createAdminRoutes(metricsCollector) {
         try {
             const updates = req.body;
             const result = adminPanel.updateAdminConfig(updates);
-            // Feature flag persistence (optional field featureFlags { name:boolean })
+            // Feature flag persistence: split incoming flags into
+            //  (a) namespace flags (e.g. response_envelope_v1) — persisted to flags.json
+            //  (b) INDEX_SERVER_* boolean toggles — routed to process.env + reloadRuntimeConfig()
+            // so dashboard toggles actually take effect at runtime (issue #282 / fix #4).
             if (updates.featureFlags && typeof updates.featureFlags === 'object') {
                 try {
-                    (0, featureFlags_js_1.updateFlags)(updates.featureFlags);
+                    const knownEnv = new Set((0, handlers_dashboardConfig_js_1.getFlagRegistrySnapshot)().filter(f => f.type === 'boolean').map(f => f.name));
+                    const namespaceFlags = {};
+                    let envChanged = 0;
+                    const appliedEnv = [];
+                    for (const [k, v] of Object.entries(updates.featureFlags)) {
+                        if (typeof v !== 'boolean')
+                            continue;
+                        const upper = String(k).toUpperCase();
+                        if (upper.startsWith('INDEX_SERVER_') && knownEnv.has(upper)) {
+                            process.env[upper] = v ? '1' : '0';
+                            appliedEnv.push(upper);
+                            envChanged++;
+                        }
+                        else {
+                            namespaceFlags[k] = v;
+                        }
+                    }
+                    if (envChanged > 0) {
+                        (0, runtimeConfig_js_1.reloadRuntimeConfig)();
+                        (0, logger_js_1.logInfo)(`[admin] applied ${envChanged} INDEX_SERVER_* toggle(s): ${appliedEnv.join(', ')}`);
+                    }
+                    if (Object.keys(namespaceFlags).length > 0)
+                        (0, featureFlags_js_1.updateFlags)(namespaceFlags);
                 }
                 catch (e) {
                     (0, logger_js_1.logWarn)('[API] feature flag update failed:', e instanceof Error ? e.message : e);
@@ -340,7 +367,9 @@ function createAdminRoutes(metricsCollector) {
     router.post('/admin/maintenance/restore', (req, res) => {
         try {
             const { backupId } = req.body || {};
+            (0, logger_js_1.logInfo)('[admin] restore requested', { backupId });
             const result = adminPanel.restoreBackup(backupId);
+            (0, logger_js_1.logInfo)('[admin] restore result', { backupId, success: result.success, restored: result.restored ?? 0, message: result.message });
             if (result.success) {
                 res.json({ success: true, message: result.message, restored: result.restored, timestamp: Date.now() });
             }
@@ -428,28 +457,75 @@ function createAdminRoutes(metricsCollector) {
     /**
      * POST /api/admin/maintenance/backup/import - Import backup from uploaded JSON bundle or zip archive
      * body: { manifest?: object, files: { [filename]: content } } or raw zip bytes
+     * query: ?restore=1  - if set, immediately restore the imported backup (one-click "Restore from File")
      */
     router.post('/admin/maintenance/backup/import', (0, express_1.raw)({ type: ['application/zip', 'application/octet-stream'], limit: '100mb' }), (req, res) => {
+        // Narrow req.query.restore safely — Express may return string | string[] | ParsedQs | ParsedQs[].
+        // Only treat a literal scalar string '1' / 'true' (case-insensitive) as opt-in; arrays/objects are rejected.
+        const restoreParam = req.query?.restore;
+        const wantRestore = typeof restoreParam === 'string' && (restoreParam === '1' || restoreParam.toLowerCase() === 'true');
+        const ctype = req.header('content-type') || '';
+        const rawBody = req.body;
+        // Refine req.body through typed locals so downstream uses don't rely on `as Buffer` casts.
+        // CodeQL js/type-confusion-through-parameter-tampering does NOT recognize Buffer.isBuffer
+        // as a sanitizer; use `instanceof Buffer` (native JS predicate, modeled by CodeQL).
+        // Array.isArray IS recognized. Avoid `.length` interpolation on tainted values.
+        const bodyBuffer = rawBody instanceof Buffer ? rawBody : null;
+        const bodyArray = Array.isArray(rawBody) ? rawBody : null;
+        const bodyObject = rawBody !== null
+            && typeof rawBody === 'object'
+            && !Array.isArray(rawBody)
+            && !(rawBody instanceof Buffer)
+            ? rawBody
+            : null;
+        const bodyKind = bodyBuffer !== null
+            ? 'buffer'
+            : bodyArray !== null
+                ? 'array'
+                : bodyObject !== null
+                    ? 'json'
+                    : typeof rawBody;
+        (0, logger_js_1.logInfo)('[admin] backup/import received', { ctype, body: bodyKind, restore: wantRestore });
         try {
-            if (Buffer.isBuffer(req.body) && req.body.length > 0) {
-                const sourceName = req.header('x-backup-filename') || req.header('x-file-name') || undefined;
-                const result = adminPanel.importZipBackup(req.body, sourceName);
-                if (result.success) {
-                    return res.json({ success: true, message: result.message, backupId: result.backupId, files: result.files, timestamp: Date.now() });
-                }
-                return res.status(400).json({ success: false, error: result.message, timestamp: Date.now() });
+            let importResult;
+            if (bodyBuffer !== null && bodyBuffer.length > 0) {
+                const filenameHeader = req.header('x-backup-filename') || req.header('x-file-name');
+                const sourceName = typeof filenameHeader === 'string' ? filenameHeader : undefined;
+                importResult = adminPanel.importZipBackup(bodyBuffer, sourceName);
             }
-            const bundle = req.body;
-            if (!bundle || typeof bundle !== 'object' || !bundle.files) {
-                return res.status(400).json({ success: false, error: 'Request body must contain a "files" object', timestamp: Date.now() });
+            else {
+                if (bodyObject === null) {
+                    (0, logger_js_1.logWarn)('[admin] backup/import rejected', { reason: 'body-not-json-object', ctype });
+                    return res.status(400).json({ success: false, error: 'Request body must be a JSON object containing a "files" object', timestamp: Date.now() });
+                }
+                const bundle = bodyObject;
+                const files = bundle.files;
+                if (!files || typeof files !== 'object' || Array.isArray(files)) {
+                    (0, logger_js_1.logWarn)('[admin] backup/import rejected', { reason: 'missing-or-invalid-files-object' });
+                    return res.status(400).json({ success: false, error: 'Request body must contain a "files" object', timestamp: Date.now() });
+                }
+                importResult = adminPanel.importBackup({
+                    manifest: typeof bundle.manifest === 'object' && bundle.manifest !== null && !Array.isArray(bundle.manifest)
+                        ? bundle.manifest
+                        : undefined,
+                    files: files,
+                });
             }
-            const result = adminPanel.importBackup(bundle);
-            if (result.success) {
-                res.json({ success: true, message: result.message, backupId: result.backupId, files: result.files, timestamp: Date.now() });
+            if (!importResult.success) {
+                (0, logger_js_1.logWarn)('[admin] backup/import failed', { message: importResult.message });
+                return res.status(400).json({ success: false, error: importResult.message, timestamp: Date.now() });
             }
-            else {
-                res.status(400).json({ success: false, error: result.message, timestamp: Date.now() });
+            (0, logger_js_1.logInfo)('[admin] backup/import ok', { backupId: importResult.backupId, files: importResult.files });
+            if (wantRestore && importResult.backupId) {
+                (0, logger_js_1.logInfo)('[admin] backup/import auto-restore start', { backupId: importResult.backupId });
+                const restoreResult = adminPanel.restoreBackup(importResult.backupId);
+                (0, logger_js_1.logInfo)('[admin] backup/import auto-restore result', { backupId: importResult.backupId, success: restoreResult.success, restored: restoreResult.restored ?? 0, message: restoreResult.message });
+                if (!restoreResult.success) {
+                    return res.status(500).json({ success: false, error: `Imported as ${importResult.backupId} but restore failed: ${restoreResult.message}`, backupId: importResult.backupId, files: importResult.files, restored: 0, timestamp: Date.now() });
+                }
+                return res.json({ success: true, message: `Imported and restored ${importResult.backupId} (${restoreResult.restored ?? 0} files)`, backupId: importResult.backupId, files: importResult.files, restored: restoreResult.restored ?? 0, restored_applied: true, timestamp: Date.now() });
             }
+            return res.json({ success: true, message: importResult.message, backupId: importResult.backupId, files: importResult.files, timestamp: Date.now() });
         }
         catch (error) {
             (0, logger_js_1.logError)('[API] Import backup error:', error);
@@ -578,5 +654,55 @@ function createAdminRoutes(metricsCollector) {
             });
         }
     });
+    /**
+     * GET /api/admin/events - Recent WARN/ERROR events from the in-memory ring buffer
+     * Query: ?since=<id>&level=WARN|ERROR&limit=<n>
+     */
+    router.get('/admin/events', (req, res) => {
+        try {
+            const since = req.query.since !== undefined ? parseInt(String(req.query.since), 10) : undefined;
+            const limit = req.query.limit !== undefined ? parseInt(String(req.query.limit), 10) : undefined;
+            const levelRaw = String(req.query.level || '').toUpperCase();
+            const level = (levelRaw === 'WARN' || levelRaw === 'ERROR') ? levelRaw : undefined;
+            const events = (0, eventBuffer_js_1.listEvents)({
+                sinceId: Number.isFinite(since) ? since : undefined,
+                limit: Number.isFinite(limit) ? limit : undefined,
+                level,
+            });
+            const counts = (0, eventBuffer_js_1.eventCounts)(0);
+            res.json({ success: true, events, counts, timestamp: Date.now() });
+        }
+        catch (error) {
+            (0, logger_js_1.logError)('[API] Get events error:', error);
+            res.status(500).json({ success: false, error: 'Failed to read events' });
+        }
+    });
+    /**
+     * GET /api/admin/events/counts - Lightweight counts for nav-bubble polling
+     */
+    router.get('/admin/events/counts', (req, res) => {
+        try {
+            const since = req.query.since !== undefined ? parseInt(String(req.query.since), 10) : 0;
+            const counts = (0, eventBuffer_js_1.eventCounts)(Number.isFinite(since) ? since : 0);
+            res.json({ success: true, counts, timestamp: Date.now() });
+        }
+        catch (error) {
+            (0, logger_js_1.logError)('[API] Get event counts error:', error);
+            res.status(500).json({ success: false, error: 'Failed to read event counts' });
+        }
+    });
+    /**
+     * DELETE /api/admin/events - Clear the buffer (also acts as "mark all read")
+     */
+    router.delete('/admin/events', (_req, res) => {
+        try {
+            (0, eventBuffer_js_1.clearEvents)();
+            res.json({ success: true, message: 'Events cleared', timestamp: Date.now() });
+        }
+        catch (error) {
+            (0, logger_js_1.logError)('[API] Clear events error:', error);
+            res.status(500).json({ success: false, error: 'Failed to clear events' });
+        }
+    });
     return router;
 }

package/dist/dashboard/server/routes/api.usage.routes.js

@@ -5,8 +5,12 @@
  * Manages API request execution (retry, rate-limit enforcement, auth, transforms)
  * and the monitoring event bus. Depends on EndpointManager for endpoint config.
  */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.UsageManager = void 0;
+const crypto_1 = __importDefault(require("crypto"));
 const logger_js_1 = require("../../../services/logger.js");
 // ── UsageManager ─────────────────────────────────────────────────────────────────────
 class UsageManager {
@@ -22,7 +26,7 @@ class UsageManager {
         if (!this.endpointMgr.checkRateLimit(endpointId)) {
             throw new Error(`Rate limit exceeded for endpoint: ${endpointId}`);
         }
-        const requestId = `req_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
+        const requestId = `req_${Date.now()}_${crypto_1.default.randomBytes(6).toString('hex')}`;
         const request = {
             id: requestId,
             endpointId,

package/dist/dashboard/server/routes/embeddings.routes.js

@@ -211,6 +211,85 @@ function createEmbeddingsRoutes(embeddingPathOverride, embeddingStore) {
             });
         }
     });
+    // GET /embeddings/status — surface model + cache state for the Embeddings tab
+    router.get('/embeddings/status', (_req, res) => {
+        try {
+            const config = (0, runtimeConfig_js_1.getRuntimeConfig)();
+            const sem = config.semantic;
+            if (!sem.enabled) {
+                return res.json({
+                    success: true,
+                    enabled: false,
+                    ready: false,
+                    state: 'disabled',
+                    message: 'Semantic embeddings are disabled. Set INDEX_SERVER_SEMANTIC_ENABLED=1 and restart to enable.',
+                });
+            }
+            const readiness = (0, embeddingService_js_1.checkModelReadiness)(sem.model, sem.cacheDir, sem.localOnly);
+            let embeddingsFileExists = false;
+            let embeddingsCount = 0;
+            let embeddingsModelName;
+            try {
+                if (embeddingStore) {
+                    const loaded = embeddingStore.load();
+                    if (loaded) {
+                        embeddingsFileExists = true;
+                        embeddingsCount = Object.keys(loaded.embeddings || {}).length;
+                        embeddingsModelName = loaded.modelName ?? undefined;
+                    }
+                }
+                else {
+                    const file = embeddingPathOverride ?? sem.embeddingPath;
+                    if (file && node_fs_1.default.existsSync(file)) {
+                        embeddingsFileExists = true;
+                        const raw = node_fs_1.default.readFileSync(file, 'utf8');
+                        const parsed = JSON.parse(raw);
+                        embeddingsCount = parsed.embeddings ? Object.keys(parsed.embeddings).length : 0;
+                        embeddingsModelName = parsed.modelName ?? undefined;
+                    }
+                }
+            }
+            catch { /* tolerate parse / read failures — surface as not present */ }
+            // State machine for the dashboard banner.
+            let state;
+            if (!readiness.ready) {
+                state = 'missing'; // localOnly=true and model not cached
+            }
+            else if (!readiness.cached) {
+                state = 'will-download';
+            }
+            else if (!embeddingsFileExists || embeddingsCount === 0) {
+                state = 'no-embeddings';
+            }
+            else {
+                state = 'ready';
+            }
+            return res.json({
+                success: true,
+                enabled: true,
+                ready: readiness.ready && embeddingsFileExists && embeddingsCount > 0,
+                state,
+                model: sem.model,
+                device: sem.device,
+                cacheDir: sem.cacheDir,
+                localOnly: sem.localOnly,
+                modelCached: readiness.cached,
+                modelPath: readiness.modelPath,
+                embeddingPath: sem.embeddingPath,
+                embeddingsFileExists,
+                embeddingsCount,
+                embeddingsModelName,
+                message: readiness.message,
+            });
+        }
+        catch (err) {
+            return res.status(500).json({
+                success: false,
+                error: 'Failed to compute embeddings status',
+                message: err.message,
+            });
+        }
+    });
     // POST /embeddings/compute — trigger embedding computation for all instructions
     router.post('/embeddings/compute', adminAuth_js_1.dashboardAdminAuth, async (_req, res) => {
         try {
@@ -244,10 +323,21 @@ function createEmbeddingsRoutes(embeddingPathOverride, embeddingStore) {
             });
         }
         catch (err) {
+            const msg = err.message ?? String(err);
+            // Detect the canonical "model not cached locally" signature from
+            // @huggingface/transformers and translate to an actionable hint so
+            // the dashboard can surface a useful banner.
+            const isLocalOnlyMiss = /local_files_only=true/i.test(msg) ||
+                /allowRemoteModels=false/i.test(msg) ||
+                /file was not found locally/i.test(msg);
             return res.status(500).json({
                 success: false,
                 error: 'Failed to compute embeddings',
-                message: err.message,
+                message: msg,
+                hint: isLocalOnlyMiss
+                    ? 'The embedding model is not cached locally and remote downloads are disabled. ' +
+                        'Set INDEX_SERVER_SEMANTIC_LOCAL_ONLY=0 and restart, or pre-stage the model in INDEX_SERVER_SEMANTIC_CACHE_DIR.'
+                    : undefined,
             });
         }
     });