@jagilber-org/index-server 1.26.11 → 1.27.2

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;
@@ -23,8 +27,7 @@ class AdminPanelConfig {
                 enableVerboseLogging: !!serverHttp?.verboseLogging,
                 enableMutation: runtimeConfig.mutation.enabled,
                 rateLimit: {
-                    windowMs: 60000,
-                    maxRequests: 100
+                    perMinute: serverHttp?.rateLimitPerMinute ?? 0
                 }
             },
             indexSettings: {
@@ -40,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 {
@@ -56,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/ApiRoutes.d.ts

@@ -8,10 +8,11 @@
 import { Router } from 'express';
 export interface ApiRoutesOptions {
     enableCors?: boolean;
-    rateLimit?: {
-        windowMs: number;
-        max: number;
-    };
+    /**
+     * Optional override for the rate-limit (requests per 60s window).
+     * `0` disables. When omitted, falls back to `httpCfg.rateLimitPerMinute`.
+     */
+    rateLimitPerMinute?: number;
 }
 export declare function createApiRoutes(options?: ApiRoutesOptions): Router;
 export default createApiRoutes;

package/dist/dashboard/server/ApiRoutes.js

@@ -49,11 +49,41 @@ const runtimeConfig_js_1 = require("../../config/runtimeConfig.js");
 const index_js_1 = require("./routes/index.js");
 const ensureLoadedMiddleware_js_1 = require("./middleware/ensureLoadedMiddleware.js");
 const logger_js_1 = require("../../services/logger.js");
+/**
+ * Path prefixes whose endpoints are *unconditionally* exempt from the dashboard
+ * HTTP rate limiter. These are bulk-shaped, operator-driven operations
+ * (backup, restore, import/export, normalize) where the size of a single
+ * request — not the *frequency* of requests — is the natural cost driver.
+ *
+ * Matching is done with `req.path.startsWith(prefix)` against the path *as
+ * mounted on the /api router* (so prefixes do not include the leading "/api").
+ *
+ * Note: the MCP tool surface (index_import / index_export / promote_from_repo
+ * / restore handlers) is already outside this HTTP limiter, so no entries are
+ * needed for those.
+ */
+const BULK_EXEMPT_PREFIXES = [
+    '/admin/maintenance/normalize',
+    '/admin/maintenance/backup', // covers backup, backup/import, backup/:id, backup/:id/export
+    '/admin/maintenance/backups', // covers backups, backups/prune
+    '/admin/maintenance/restore',
+    '/charts/export',
+    '/sqlite/backup', // covers /sqlite/backup and /sqlite/backups
+    '/sqlite/restore',
+    '/sqlite/export',
+];
+function isBulkExempt(reqPath) {
+    for (const prefix of BULK_EXEMPT_PREFIXES) {
+        if (reqPath === prefix || reqPath.startsWith(prefix + '/'))
+            return true;
+    }
+    return false;
+}
 function createApiRoutes(options = {}) {
     const router = (0, express_1.Router)();
     const metricsCollector = (0, MetricsCollector_js_1.getMetricsCollector)();
     const httpCfg = (0, runtimeConfig_js_1.getRuntimeConfig)().dashboard.http;
-    const rateLimitOpts = options.rateLimit ?? { windowMs: httpCfg.rateLimitWindowMs, max: httpCfg.rateLimitMax };
+    const perMinute = options.rateLimitPerMinute ?? httpCfg.rateLimitPerMinute;
     // CORS middleware (if enabled)
     // Security: only allow loopback origins (localhost, 127.0.0.1, [::1]) to prevent
     // cross-origin attacks. No wildcard (*) origins; credentials are not exposed.
@@ -71,53 +101,28 @@ function createApiRoutes(options = {}) {
     }
     // JSON middleware
     router.use(express_1.default.json());
-    const rateLimitEnabled = httpCfg.rateLimitEnabled;
-    if (rateLimitEnabled && rateLimitOpts.max > 0 && rateLimitOpts.windowMs > 0) {
-        // Global rate limit for all routes (reads + mutations)
+    // Rate limit (single tier, fixed 60s window). Disabled when perMinute === 0.
+    // Bulk routes (backup/restore/import/export/normalize) are unconditionally
+    // exempt via BULK_EXEMPT_PREFIXES — see `skip` below.
+    if (perMinute > 0) {
+        const windowMs = 60_000;
         router.use((0, express_rate_limit_1.default)({
-            windowMs: rateLimitOpts.windowMs,
-            max: rateLimitOpts.max,
+            windowMs,
+            max: perMinute,
             standardHeaders: true,
             legacyHeaders: true,
             validate: { ip: false },
-            skip: (req) => req.method === 'OPTIONS',
+            skip: (req) => req.method === 'OPTIONS' || isBulkExempt(req.path),
             keyGenerator: (req) => {
                 const clientIp = req.ip || req.socket.remoteAddress;
                 return clientIp ? (0, express_rate_limit_1.ipKeyGenerator)(clientIp) : 'unknown';
             },
             handler: (_req, res) => {
-                const retryAfter = Number(res.getHeader('Retry-After') || Math.ceil(rateLimitOpts.windowMs / 1000));
+                const retryAfter = Number(res.getHeader('Retry-After') || Math.ceil(windowMs / 1000));
                 res.status(429).json({
                     error: 'Too Many Requests',
                     message: `Rate limit exceeded. Try again in ${retryAfter} second(s).`,
                     retryAfterSeconds: retryAfter,
-                    tier: 'global',
-                    timestamp: Date.now(),
-                });
-            },
-        }));
-        // Stricter rate limit for mutation endpoints (POST/PUT/PATCH/DELETE).
-        // Defaults to runtimeConfig httpCfg.rateLimitMutationMax (env-configurable),
-        // bounded by the global per-window cap so mutation-tier never exceeds global.
-        const mutationMax = Math.max(1, Math.min(httpCfg.rateLimitMutationMax, rateLimitOpts.max));
-        router.use((0, express_rate_limit_1.default)({
-            windowMs: rateLimitOpts.windowMs,
-            max: mutationMax,
-            standardHeaders: true,
-            legacyHeaders: false,
-            validate: { ip: false },
-            skip: (req) => req.method === 'OPTIONS' || req.method === 'GET' || req.method === 'HEAD',
-            keyGenerator: (req) => {
-                const clientIp = req.ip || req.socket.remoteAddress;
-                return `mutation:${clientIp ? (0, express_rate_limit_1.ipKeyGenerator)(clientIp) : 'unknown'}`;
-            },
-            handler: (_req, res) => {
-                const retryAfter = Number(res.getHeader('Retry-After') || Math.ceil(rateLimitOpts.windowMs / 1000));
-                res.status(429).json({
-                    error: 'Too Many Requests',
-                    message: `Mutation rate limit exceeded. Try again in ${retryAfter} second(s).`,
-                    retryAfterSeconds: retryAfter,
-                    tier: 'mutation',
                     timestamp: Date.now(),
                 });
             },

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/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/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,
             });
         }
     });

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

@@ -106,19 +106,21 @@ function renderPanelMarkdownHtml(name, markdown) {
  * Called once during DashboardServer construction after middleware is set up.
  */
 function mountDashboardRoutes(app, ctx) {
-    // Build a per-route rate limiter using the same dashboard.http.rateLimit*
-    // configuration as the /api router. Re-uses the same window/max so behavior
-    // is consistent across the dashboard. Disabled if rateLimitEnabled is false.
+    // Build a per-route rate limiter using the same dashboard.http.rateLimit
+    // configuration as the /api router. Re-uses the same per-minute cap so
+    // behavior is consistent across the dashboard. Disabled when
+    // rateLimitPerMinute === 0 (the default).
     const httpCfg = (0, runtimeConfig_js_1.getRuntimeConfig)().dashboard.http;
+    const perMinute = httpCfg.rateLimitPerMinute;
     const dashboardLimiter = (0, express_rate_limit_1.default)({
-        windowMs: Math.max(1, httpCfg.rateLimitWindowMs),
-        max: Math.max(1, httpCfg.rateLimitMax),
+        windowMs: 60_000,
+        max: perMinute > 0 ? perMinute : 1,
         standardHeaders: true,
         legacyHeaders: false,
         validate: { ip: false },
-        skip: () => !httpCfg.rateLimitEnabled,
+        skip: () => perMinute <= 0,
         handler: (_req, res) => {
-            const retryAfter = Number(res.getHeader('Retry-After') || Math.ceil(httpCfg.rateLimitWindowMs / 1000));
+            const retryAfter = Number(res.getHeader('Retry-After') || 60);
             res.status(429).json({
                 error: 'Too Many Requests',
                 message: `Rate limit exceeded. Try again in ${retryAfter} second(s).`,
@@ -222,8 +224,8 @@ function mountDashboardRoutes(app, ctx) {
             res.status(404).send('Screenshot not found');
         }
     });
-    // API sub-routes (mounted at /api). Rate limits sourced from runtimeConfig
-    // (INDEX_SERVER_RATE_LIMIT_*) — see ApiRoutes.createApiRoutes.
+    // API sub-routes (mounted at /api). Rate limit sourced from runtimeConfig
+    // (INDEX_SERVER_RATE_LIMIT) — see ApiRoutes.createApiRoutes.
     app.use('/api', (0, ApiRoutes_js_1.createApiRoutes)({ enableCors: ctx.enableCors }));
     // Back-compat: legacy tests expect /tools.json at dashboard root
     app.get('/tools.json', (_req, res) => {