@jagilber-org/index-server 1.27.0 → 1.27.2

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/server/sdkServer.js

@@ -21,6 +21,7 @@ const registry_1 = require("./registry");
 const zod_1 = require("zod");
 const runtimeConfig_1 = require("../config/runtimeConfig");
 const mcpLogBridge_1 = require("../services/mcpLogBridge");
+const logger_1 = require("../services/logger");
 const handshakeManager_1 = require("./handshakeManager");
 const transportFactory_1 = require("./transportFactory");
 const mcpReadOnlySurfaces_1 = require("./mcpReadOnlySurfaces");
@@ -205,6 +206,8 @@ function createSdkServer(ServerClass) {
         const args = p.arguments || {};
         if (name === 'health_check')
             (0, handshakeManager_1.record)('tools_call_health');
+        const __callStart = Date.now();
+        (0, logger_1.logInfo)('[rpc] tools/call', { tool: name, id: req?.id ?? null });
         try {
             if ((0, runtimeConfig_1.getRuntimeConfig)().logging.verbose)
                 process.stderr.write(`[rpc] call method=tools/call tool=${name} id=${req?.id ?? 'n/a'}\n`);
@@ -216,9 +219,11 @@ function createSdkServer(ServerClass) {
         }
         try {
             const result = await Promise.resolve(handler(args));
+            const bytes = Buffer.byteLength(JSON.stringify(result), 'utf8');
+            (0, logger_1.logInfo)('[rpc] tools/call ok', { tool: name, ms: Date.now() - __callStart, bytes });
             try {
                 if ((0, runtimeConfig_1.getRuntimeConfig)().logging.verbose)
-                    process.stderr.write(`[rpc] tool_result tool=${name} bytes=${Buffer.byteLength(JSON.stringify(result), 'utf8')}\n`);
+                    process.stderr.write(`[rpc] tool_result tool=${name} bytes=${bytes}\n`);
             }
             catch { /* ignore */ }
             return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
@@ -226,7 +231,10 @@ function createSdkServer(ServerClass) {
         catch (e) {
             const code = e?.code;
             const sem = e?.__semantic === true;
+            const msgRaw = e instanceof Error ? e.message : String(e);
+            const stack = e instanceof Error ? e.stack : undefined;
             if (Number.isSafeInteger(code)) {
+                (0, logger_1.logError)('[rpc] tools/call error', { tool: name, ms: Date.now() - __callStart, code, semantic: sem, message: msgRaw, stack });
                 try {
                     if ((0, runtimeConfig_1.getRuntimeConfig)().logging.verbose)
                         process.stderr.write(`[rpc] tool_error_passthru tool=${name} code=${code} semantic=${sem ? '1' : '0'} msg=${e?.message || ''}\n`);
@@ -234,13 +242,13 @@ function createSdkServer(ServerClass) {
                 catch { /* ignore */ }
                 throw e;
             }
-            const msg = e instanceof Error ? e.message : String(e);
+            (0, logger_1.logError)('[rpc] tools/call error', { tool: name, ms: Date.now() - __callStart, code: code ?? null, message: msgRaw, stack });
             try {
                 if ((0, runtimeConfig_1.getRuntimeConfig)().logging.verbose)
-                    process.stderr.write(`[rpc] tool_error_wrap tool=${name} msg=${msg.replace(/\s+/g, ' ')} code=${code ?? 'n/a'}\n`);
+                    process.stderr.write(`[rpc] tool_error_wrap tool=${name} msg=${msgRaw.replace(/\s+/g, ' ')} code=${code ?? 'n/a'}\n`);
             }
             catch { /* ignore */ }
-            throw { code: -32603, message: 'Tool execution failed', data: { message: msg, method: name } };
+            throw { code: -32603, message: 'Tool execution failed', data: { message: msgRaw, method: name } };
         }
     });
     // Lightweight ping handler (simple reachability / latency measurement)

package/dist/services/embeddingService.d.ts

@@ -58,6 +58,8 @@ export declare function embedText(text: string, modelName: string, cacheDir: str
  */
 export declare function checkModelReadiness(modelName: string, cacheDir: string, localOnly: boolean): {
     ready: boolean;
+    cached: boolean;
+    modelPath: string;
     message?: string;
 };
 /** Signature for the embed function (injectable for testing). */

package/dist/services/embeddingService.js

@@ -187,22 +187,34 @@ async function embedText(text, modelName, cacheDir, device = 'cpu', localOnly =
  * @returns Object with `ready` flag and optional remediation `message`.
  */
 function checkModelReadiness(modelName, cacheDir, localOnly) {
-    if (!localOnly) {
-        return { ready: true }; // Model can be downloaded on demand
-    }
     // HuggingFace transformers caches models as: models--<org>--<name>
     const modelDirName = `models--${modelName.replace(/\//g, '--')}`;
     const modelPath = path_1.default.join(cacheDir, modelDirName);
+    let cached = false;
     try {
         if (fs_1.default.existsSync(modelPath) && fs_1.default.readdirSync(modelPath).length > 0) {
-            return { ready: true };
+            cached = true;
         }
     }
     catch {
         // Directory doesn't exist or can't be read
     }
+    if (cached) {
+        return { ready: true, cached: true, modelPath };
+    }
+    if (!localOnly) {
+        return {
+            ready: true,
+            cached: false,
+            modelPath,
+            message: `Embedding model '${modelName}' is not yet cached. ` +
+                `It will be downloaded to '${cacheDir}' on first compute (~25 MB).`,
+        };
+    }
     return {
         ready: false,
+        cached: false,
+        modelPath,
         message: `Embedding model '${modelName}' not found in cache (${cacheDir}). ` +
             `LOCAL_ONLY is enabled, so the model cannot be downloaded automatically. ` +
             `To fix: set INDEX_SERVER_SEMANTIC_LOCAL_ONLY=0 to allow download, ` +

package/dist/services/embeddingTrigger.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Auto-compute embeddings after operations that mutate the loaded instruction set
+ * (zip import, restore, bulk migrations).
+ *
+ * Behaviour:
+ *  - No-op when semantic is disabled (`INDEX_SERVER_SEMANTIC_ENABLED` falsy).
+ *  - No-op when explicitly opted out via `INDEX_SERVER_AUTO_EMBED_ON_IMPORT=0`.
+ *  - Runs asynchronously (fire-and-forget) so the caller's request returns promptly.
+ *  - Coalesces concurrent triggers via the existing in-flight lock inside
+ *    `getInstructionEmbeddings`.
+ *
+ * Logs success / failure at INFO / WARN so events surface in the events panel
+ * (constitution OB-3, OB-5).
+ */
+/** Whether auto-compute is enabled given current env / runtime config. */
+export declare function autoEmbedEnabled(): boolean;
+/**
+ * Trigger an embedding compute pass after an import / restore.
+ *
+ * @param reason - Free-form context (e.g. `import-zip`, `restore`) used in logs.
+ * @returns Promise resolving when compute finishes (or immediately if skipped).
+ */
+export declare function triggerEmbeddingComputeAfterImport(reason: string): Promise<{
+    triggered: boolean;
+    reason?: string;
+    entries?: number;
+    ms?: number;
+}>;
+/**
+ * Fire-and-forget variant — schedules the compute on the next tick and returns immediately.
+ * Use this from request handlers so HTTP responses are not blocked on model warm-up.
+ */
+export declare function scheduleEmbeddingComputeAfterImport(reason: string): void;

package/dist/services/embeddingTrigger.js

@@ -0,0 +1,86 @@
+"use strict";
+/**
+ * Auto-compute embeddings after operations that mutate the loaded instruction set
+ * (zip import, restore, bulk migrations).
+ *
+ * Behaviour:
+ *  - No-op when semantic is disabled (`INDEX_SERVER_SEMANTIC_ENABLED` falsy).
+ *  - No-op when explicitly opted out via `INDEX_SERVER_AUTO_EMBED_ON_IMPORT=0`.
+ *  - Runs asynchronously (fire-and-forget) so the caller's request returns promptly.
+ *  - Coalesces concurrent triggers via the existing in-flight lock inside
+ *    `getInstructionEmbeddings`.
+ *
+ * Logs success / failure at INFO / WARN so events surface in the events panel
+ * (constitution OB-3, OB-5).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.autoEmbedEnabled = autoEmbedEnabled;
+exports.triggerEmbeddingComputeAfterImport = triggerEmbeddingComputeAfterImport;
+exports.scheduleEmbeddingComputeAfterImport = scheduleEmbeddingComputeAfterImport;
+const runtimeConfig_1 = require("../config/runtimeConfig");
+const indexContext_1 = require("./indexContext");
+const embeddingService_1 = require("./embeddingService");
+const logger_1 = require("./logger");
+const envUtils_1 = require("../utils/envUtils");
+let lastTriggerAt = 0;
+/** Whether auto-compute is enabled given current env / runtime config. */
+function autoEmbedEnabled() {
+    const cfg = (0, runtimeConfig_1.getRuntimeConfig)();
+    if (!cfg.semantic.enabled)
+        return false;
+    const raw = process.env.INDEX_SERVER_AUTO_EMBED_ON_IMPORT;
+    // Default ON when semantic is enabled; explicit '0' / 'false' opts out.
+    if (raw === undefined)
+        return true;
+    return (0, envUtils_1.getBooleanEnv)('INDEX_SERVER_AUTO_EMBED_ON_IMPORT', true);
+}
+/**
+ * Trigger an embedding compute pass after an import / restore.
+ *
+ * @param reason - Free-form context (e.g. `import-zip`, `restore`) used in logs.
+ * @returns Promise resolving when compute finishes (or immediately if skipped).
+ */
+async function triggerEmbeddingComputeAfterImport(reason) {
+    if (!autoEmbedEnabled()) {
+        return { triggered: false, reason: 'auto-embed disabled or semantic disabled' };
+    }
+    // Light debounce — coalesce rapid back-to-back imports.
+    const now = Date.now();
+    if (now - lastTriggerAt < 1000) {
+        return { triggered: false, reason: 'debounced' };
+    }
+    lastTriggerAt = now;
+    const cfg = (0, runtimeConfig_1.getRuntimeConfig)();
+    const sem = cfg.semantic;
+    const start = Date.now();
+    try {
+        (0, indexContext_1.ensureLoaded)();
+        const state = (0, indexContext_1.getIndexState)();
+        if (!state.list || state.list.length === 0) {
+            (0, logger_1.logInfo)(`[embedding-trigger] Skipped (no instructions loaded) reason=${reason}`);
+            return { triggered: false, reason: 'no instructions loaded' };
+        }
+        (0, logger_1.logInfo)(`[embedding-trigger] Starting auto-compute reason=${reason} entries=${state.list.length}`);
+        await (0, embeddingService_1.getInstructionEmbeddings)(state.list, state.hash, sem.embeddingPath, sem.model, sem.cacheDir, sem.device, sem.localOnly);
+        const ms = Date.now() - start;
+        (0, logger_1.logInfo)(`[embedding-trigger] Auto-compute complete reason=${reason} entries=${state.list.length} ms=${ms}`);
+        return { triggered: true, entries: state.list.length, ms };
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        // Use WARN (not ERROR) so we don't escalate transient model-load issues to ERROR-level paging.
+        (0, logger_1.logWarn)(`[embedding-trigger] Auto-compute failed reason=${reason}: ${msg}`);
+        return { triggered: false, reason: `failed: ${msg}` };
+    }
+}
+/**
+ * Fire-and-forget variant — schedules the compute on the next tick and returns immediately.
+ * Use this from request handlers so HTTP responses are not blocked on model warm-up.
+ */
+function scheduleEmbeddingComputeAfterImport(reason) {
+    if (!autoEmbedEnabled())
+        return;
+    setImmediate(() => {
+        triggerEmbeddingComputeAfterImport(reason).catch(() => { });
+    });
+}

package/dist/services/eventBuffer.d.ts

@@ -0,0 +1,45 @@
+/**
+ * In-process ring buffer of recent log events at WARN/ERROR severity.
+ *
+ * Surfaces operationally-meaningful events to the admin dashboard so operators
+ * do not have to tail server logs. Read-only, bounded; never persists to disk.
+ *
+ * Capacity defaults to 500. The logger emits records via `recordEvent()` only
+ * for WARN or ERROR levels so that volume on healthy systems is negligible.
+ *
+ * Constitution alignment: OB-1, OB-3, OB-4, OB-5 (structured, severity-visible).
+ */
+export type EventLevel = 'WARN' | 'ERROR';
+export interface BufferedEvent {
+    /** Monotonically increasing per-process id (used for unread counts). */
+    id: number;
+    /** ISO 8601 timestamp. */
+    ts: string;
+    /** Severity. */
+    level: EventLevel;
+    /** Message; prefix `[module]` is preserved. */
+    msg: string;
+    /** Optional stack/detail snippet. */
+    detail?: string;
+    /** Process id of emitter. */
+    pid?: number;
+}
+/** Emit a WARN/ERROR event into the buffer. Called by the logger. */
+export declare function recordEvent(level: EventLevel, msg: string, detail?: string, pid?: number): void;
+/** List recent events (most recent last). */
+export declare function listEvents(opts?: {
+    sinceId?: number;
+    level?: EventLevel;
+    limit?: number;
+}): BufferedEvent[];
+/** Compute new-event counts since the supplied id (used for the dashboard counter bubble). */
+export declare function eventCounts(sinceId?: number): {
+    warn: number;
+    error: number;
+    total: number;
+    latestId: number;
+};
+/** Clear the buffer (used by `Mark all read` and tests). */
+export declare function clearEvents(): void;
+/** Test-only helper. */
+export declare function _eventBufferSize(): number;