@jagilber-org/index-server 1.27.0 → 1.27.2

package/dist/services/eventBuffer.js

@@ -0,0 +1,110 @@
+"use strict";
+/**
+ * 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).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.recordEvent = recordEvent;
+exports.listEvents = listEvents;
+exports.eventCounts = eventCounts;
+exports.clearEvents = clearEvents;
+exports._eventBufferSize = _eventBufferSize;
+const DEFAULT_CAPACITY = 500;
+class EventRing {
+    buf = [];
+    nextId = 1;
+    capacity = DEFAULT_CAPACITY;
+    /** Read the configured capacity (env: INDEX_SERVER_EVENT_BUFFER_SIZE, min 50, max 5000). */
+    resolveCapacity() {
+        const raw = process.env.INDEX_SERVER_EVENT_BUFFER_SIZE;
+        if (!raw)
+            return DEFAULT_CAPACITY;
+        const n = parseInt(raw, 10);
+        if (!Number.isFinite(n) || n <= 0)
+            return DEFAULT_CAPACITY;
+        return Math.min(5000, Math.max(50, n));
+    }
+    add(level, msg, detail, pid) {
+        // Refresh capacity lazily so runtime changes take effect.
+        const cap = this.resolveCapacity();
+        if (cap !== this.capacity) {
+            this.capacity = cap;
+            if (this.buf.length > cap)
+                this.buf.splice(0, this.buf.length - cap);
+        }
+        const evt = {
+            id: this.nextId++,
+            ts: new Date().toISOString(),
+            level,
+            msg,
+            pid,
+        };
+        if (detail)
+            evt.detail = detail.length > 4096 ? detail.slice(0, 4096) + '…' : detail;
+        this.buf.push(evt);
+        if (this.buf.length > this.capacity)
+            this.buf.shift();
+    }
+    /** List events newer than `sinceId` (exclusive), optionally filtered by level. */
+    list(opts = {}) {
+        const sinceId = opts.sinceId ?? 0;
+        const limit = Math.min(1000, Math.max(1, opts.limit ?? 200));
+        const filtered = [];
+        for (let i = this.buf.length - 1; i >= 0 && filtered.length < limit; i--) {
+            const e = this.buf[i];
+            if (e.id <= sinceId)
+                break;
+            if (opts.level && e.level !== opts.level)
+                continue;
+            filtered.push(e);
+        }
+        return filtered.reverse();
+    }
+    /** Counts of WARN and ERROR events newer than `sinceId`. */
+    counts(sinceId = 0) {
+        let warn = 0, error = 0;
+        for (const e of this.buf) {
+            if (e.id <= sinceId)
+                continue;
+            if (e.level === 'WARN')
+                warn++;
+            else if (e.level === 'ERROR')
+                error++;
+        }
+        const latestId = this.buf.length ? this.buf[this.buf.length - 1].id : 0;
+        return { warn, error, total: warn + error, latestId };
+    }
+    clear() {
+        this.buf = [];
+    }
+    /** Test-only: current size. */
+    size() { return this.buf.length; }
+}
+const ring = new EventRing();
+/** Emit a WARN/ERROR event into the buffer. Called by the logger. */
+function recordEvent(level, msg, detail, pid) {
+    ring.add(level, msg, detail, pid);
+}
+/** List recent events (most recent last). */
+function listEvents(opts) {
+    return ring.list(opts);
+}
+/** Compute new-event counts since the supplied id (used for the dashboard counter bubble). */
+function eventCounts(sinceId) {
+    return ring.counts(sinceId);
+}
+/** Clear the buffer (used by `Mark all read` and tests). */
+function clearEvents() {
+    ring.clear();
+}
+/** Test-only helper. */
+function _eventBufferSize() {
+    return ring.size();
+}

package/dist/services/handlers/instructions.import.js

@@ -15,6 +15,12 @@ const ownershipService_1 = require("../ownershipService");
 const instructionRecordValidation_1 = require("../instructionRecordValidation");
 const instructionRecordValidation_2 = require("../instructionRecordValidation");
 const auditLog_1 = require("../auditLog");
+const logger_1 = require("../logger");
+// Structured WARN without auto-attached call stack: the log-hygiene gate
+// (scripts/crawl-logs.mjs) treats WARN-with-stack as a budget violation
+// (max-stack-warn=5). Use log('WARN', ...) directly with serialized detail
+// so per-entry import rejections stay structured but stackless.
+const warnStruct = (msg, detail) => (0, logger_1.log)('WARN', msg, { detail: detail === undefined ? undefined : typeof detail === 'string' ? detail : JSON.stringify(detail) });
 const runtimeConfig_1 = require("../../config/runtimeConfig");
 const manifestManager_1 = require("../manifestManager");
 const instructions_shared_1 = require("./instructions.shared");
@@ -44,48 +50,77 @@ function parseInlineEntries(rawEntries) {
 (0, registry_1.registerHandler)('index_import', (0, instructions_shared_1.guard)('index_import', async (p) => {
     let entries;
     const mode = p.mode || 'skip';
+    // Source-type breadcrumb for observability: agents currently get a silent
+    // { error: ... } back on top-level failures (path-blocked, parse errors,
+    // missing files). Without these explicit WARN logs the only signal is the
+    // RPC response, which dashboards/tails never see (RCA 2026-05-01 dev 8687).
+    const sourceType = Array.isArray(p.entries)
+        ? 'inline-array'
+        : typeof p.entries === 'string'
+            ? 'inline-or-file'
+            : typeof p.source === 'string'
+                ? 'directory'
+                : 'none';
+    const inlineCount = Array.isArray(p.entries) ? p.entries.length : undefined;
+    (0, logger_1.logInfo)('[import] start', { mode, sourceType, inlineCount, source: typeof p.source === 'string' ? p.source : undefined });
     if (Array.isArray(p.entries)) {
         entries = p.entries;
     }
     else if (typeof p.entries === 'string') {
         const inlineEntries = parseInlineEntries(p.entries);
-        if (inlineEntries.error)
+        if (inlineEntries.error) {
+            warnStruct('[import] rejected', { reason: 'inline-parse-error', detail: inlineEntries.error });
             return inlineEntries.error;
+        }
         if (inlineEntries.entries) {
             entries = inlineEntries.entries;
         }
         else {
             const filePath = path_1.default.resolve(p.entries);
-            if (!isPathAllowed(filePath))
+            if (!isPathAllowed(filePath)) {
+                warnStruct('[import] rejected', { reason: 'path-not-allowed', path: filePath });
                 return { error: 'entries path is outside allowed directories', path: filePath };
-            if (!fs_1.default.existsSync(filePath))
+            }
+            if (!fs_1.default.existsSync(filePath)) {
+                warnStruct('[import] rejected', { reason: 'entries-file-not-found', path: filePath });
                 return { error: 'entries file not found', path: filePath };
+            }
             try {
                 const raw = JSON.parse(fs_1.default.readFileSync(filePath, 'utf8'));
-                if (!Array.isArray(raw))
+                if (!Array.isArray(raw)) {
+                    warnStruct('[import] rejected', { reason: 'entries-file-not-array', path: filePath });
                     return { error: 'entries file must contain a JSON array', path: filePath };
+                }
                 entries = raw;
             }
             catch (e) {
+                warnStruct('[import] rejected', { reason: 'entries-file-parse-error', path: filePath, detail: e.message });
                 return { error: 'entries file parse error', path: filePath, detail: e.message };
             }
         }
     }
     else if (typeof p.source === 'string') {
         const dirPath = path_1.default.resolve(p.source);
-        if (!isPathAllowed(dirPath))
+        if (!isPathAllowed(dirPath)) {
+            warnStruct('[import] rejected', { reason: 'source-not-allowed', path: dirPath });
             return { error: 'source path is outside allowed directories', path: dirPath };
-        if (!fs_1.default.existsSync(dirPath))
+        }
+        if (!fs_1.default.existsSync(dirPath)) {
+            warnStruct('[import] rejected', { reason: 'source-not-found', path: dirPath });
             return { error: 'source directory not found', path: dirPath };
+        }
         let stat;
         try {
             stat = fs_1.default.statSync(dirPath);
         }
         catch (e) {
+            warnStruct('[import] rejected', { reason: 'source-inaccessible', path: dirPath, detail: e.message });
             return { error: 'source path inaccessible', path: dirPath, detail: e.message };
         }
-        if (!stat.isDirectory())
+        if (!stat.isDirectory()) {
+            warnStruct('[import] rejected', { reason: 'source-not-directory', path: dirPath });
             return { error: 'source path is not a directory', path: dirPath };
+        }
         const files = fs_1.default.readdirSync(dirPath).filter(f => f.endsWith('.json') && !f.startsWith('_'));
         entries = [];
         for (const fname of files) {
@@ -95,14 +130,18 @@ function parseInlineEntries(rawEntries) {
                 if (parsed && typeof parsed === 'object' && parsed.id)
                     entries.push(parsed);
             }
-            catch { /* skip unparseable files */ }
+            catch (e) {
+                warnStruct('[import] file skipped (parse error)', { file: fname, detail: e.message });
+            }
         }
     }
     else {
         entries = [];
     }
-    if (!entries.length)
+    if (!entries.length) {
+        warnStruct('[import] rejected', { reason: 'no-entries' });
         return { error: 'no entries' };
+    }
     const dir = (0, indexContext_1.getInstructionsDir)();
     if (!fs_1.default.existsSync(dir))
         fs_1.default.mkdirSync(dir, { recursive: true });
@@ -124,13 +163,16 @@ function parseInlineEntries(rawEntries) {
         ].filter((issue) => !!issue);
         const surfaceValidation = e ? (0, instructionRecordValidation_1.validateInstructionInputSurface)(e) : { validationErrors: [], hints: [], schemaRef: 'index_add#input' };
         if (!e || requiredFieldErrors.length || surfaceValidation.validationErrors.length) {
-            errors.push({ id, error: formatImportValidationError([...requiredFieldErrors, ...surfaceValidation.validationErrors]) });
+            const errMsg = formatImportValidationError([...requiredFieldErrors, ...surfaceValidation.validationErrors]);
+            errors.push({ id, error: errMsg });
+            warnStruct('[import] entry rejected', { id, reason: 'invalid-input', error: errMsg });
             continue;
         }
         const bodyTrimmed = typeof e.body === 'string' ? e.body.trim() : String(e.body);
         const { bodyWarnLength: importBodyMax } = (0, runtimeConfig_1.getRuntimeConfig)().index;
         if (bodyTrimmed.length > importBodyMax) {
             errors.push({ id: e.id, error: `body_too_large: ${bodyTrimmed.length} chars exceeds ${importBodyMax} limit. Split into cross-linked instructions.` });
+            warnStruct('[import] entry rejected', { id: e.id, reason: 'body-too-large', length: bodyTrimmed.length, limit: importBodyMax });
             continue;
         }
         const file = path_1.default.join(dir, `${e.id}.json`);
@@ -143,6 +185,7 @@ function parseInlineEntries(rawEntries) {
         if (!categories.length) {
             if (instructionsCfg.requireCategory) {
                 errors.push({ id: e.id, error: 'category_required' });
+                warnStruct('[import] entry rejected', { id: e.id, reason: 'category-required' });
                 continue;
             }
             categories = ['uncategorized'];
@@ -168,10 +211,12 @@ function parseInlineEntries(rawEntries) {
         }
         if (e.priorityTier === 'P1' && (!categories.length || !e.owner)) {
             errors.push({ id: e.id, error: 'P1 requires category & owner' });
+            warnStruct('[import] entry rejected', { id: e.id, reason: 'p1-requires-category-and-owner' });
             continue;
         }
         if ((e.requirement === 'mandatory' || e.requirement === 'critical') && !e.owner) {
             errors.push({ id: e.id, error: 'mandatory/critical require owner' });
+            warnStruct('[import] entry rejected', { id: e.id, reason: 'mandatory-critical-require-owner', requirement: e.requirement });
             continue;
         }
         if (fileExists && mode === 'skip') {
@@ -194,7 +239,9 @@ function parseInlineEntries(rawEntries) {
         }
         const recordValidation = (0, instructionRecordValidation_1.validateInstructionRecord)(record);
         if (recordValidation.validationErrors.length) {
-            errors.push({ id: e.id, error: formatImportValidationError(recordValidation.validationErrors) });
+            const errMsg = formatImportValidationError(recordValidation.validationErrors);
+            errors.push({ id: e.id, error: errMsg });
+            warnStruct('[import] entry rejected', { id: e.id, reason: 'record-validation-failed', error: errMsg });
             continue;
         }
         try {
@@ -202,10 +249,14 @@ function parseInlineEntries(rawEntries) {
         }
         catch (err) {
             if ((0, instructionRecordValidation_2.isInstructionValidationError)(err)) {
-                errors.push({ id: e.id, error: formatImportValidationError(err.validationErrors) });
+                const errMsg = formatImportValidationError(err.validationErrors);
+                errors.push({ id: e.id, error: errMsg });
+                (0, logger_1.logError)('[import] entry write rejected', { id: e.id, reason: 'validation-failed-at-write', error: errMsg });
                 continue;
             }
-            errors.push({ id: e.id, error: `write-failed: ${err.message || 'unknown'}` });
+            const writeMsg = err.message || 'unknown';
+            errors.push({ id: e.id, error: `write-failed: ${writeMsg}` });
+            (0, logger_1.logError)('[import] entry write failed', { id: e.id, error: writeMsg, stack: err.stack });
             continue;
         }
         if (fileExists && mode === 'overwrite')
@@ -229,10 +280,17 @@ function parseInlineEntries(rawEntries) {
     if (verificationErrors.length) {
         errors.push(...verificationErrors);
         (0, auditLog_1.logAudit)('import_verification', verificationErrors.map(v => v.id), { missingAfterReload: verificationErrors.length });
+        (0, logger_1.logError)('[import] verification failed', { missingAfterReload: verificationErrors.length, ids: verificationErrors.map(v => v.id) });
     }
     const verifiedCount = writtenIds.length - verificationErrors.length;
     const summary = { hash: st.hash, imported, skipped, overwritten, total: entries.length, errors, verified: verificationErrors.length === 0, verifiedCount, verificationErrorCount: verificationErrors.length };
     (0, auditLog_1.logAudit)('import', entries.map(e => e.id), { imported, skipped, overwritten, errors: errors.length, verified: verificationErrors.length === 0 });
+    if (errors.length) {
+        warnStruct('[import] complete with errors', { imported, skipped, overwritten, total: entries.length, errorCount: errors.length, verifiedCount, verificationErrorCount: verificationErrors.length, errorIds: errors.map(e => e.id) });
+    }
+    else {
+        (0, logger_1.logInfo)('[import] complete', { imported, skipped, overwritten, total: entries.length, verifiedCount });
+    }
     (0, manifestManager_1.attemptManifestUpdate)();
     return summary;
 }));

package/dist/services/handlers.dashboardConfig.js

@@ -76,6 +76,87 @@ exports.FLAG_REGISTRY = [
     { name: 'INDEX_SERVER_LEADER_PORT', category: 'multi-instance', description: 'HTTP port for leader MCP transport (thin clients connect here).', stability: 'experimental', default: '9090', type: 'number', since: '1.8.5' },
     { name: 'INDEX_SERVER_HEARTBEAT_MS', category: 'multi-instance', description: 'Leader heartbeat interval (ms).', stability: 'experimental', default: '5000', type: 'number', since: '1.8.5' },
     { name: 'INDEX_SERVER_STALE_THRESHOLD_MS', category: 'multi-instance', description: 'Stale leader threshold (ms) before follower promotes.', stability: 'experimental', default: '15000', type: 'number', since: '1.8.5' },
+    // Semantic / embeddings
+    { name: 'INDEX_SERVER_SEMANTIC_ENABLED', category: 'semantic', description: 'Enable semantic search & embedding compute.', stability: 'experimental', default: 'off', type: 'boolean', since: '1.20.0' },
+    { name: 'INDEX_SERVER_SEMANTIC_MODEL', category: 'semantic', description: 'HuggingFace embedding model id (e.g. Xenova/all-MiniLM-L6-v2).', stability: 'experimental', default: '(default)', type: 'string', since: '1.20.0' },
+    { name: 'INDEX_SERVER_SEMANTIC_DEVICE', category: 'semantic', description: 'Inference device: cpu | cuda | dml.', stability: 'experimental', default: 'cpu', type: 'string', since: '1.20.0' },
+    { name: 'INDEX_SERVER_SEMANTIC_CACHE_DIR', category: 'semantic', description: 'Directory for downloaded model artifacts.', stability: 'experimental', default: './data/models', type: 'string', since: '1.20.0' },
+    { name: 'INDEX_SERVER_SEMANTIC_LOCAL_ONLY', category: 'semantic', description: 'Disallow remote model downloads (offline mode).', stability: 'experimental', default: 'on', type: 'boolean', since: '1.20.0' },
+    { name: 'INDEX_SERVER_EMBEDDING_PATH', category: 'semantic', description: 'Path to embeddings JSON cache file.', stability: 'experimental', default: './data/embeddings.json', type: 'string', since: '1.20.0' },
+    { name: 'INDEX_SERVER_AUTO_EMBED_ON_IMPORT', category: 'semantic', description: 'Auto-compute embeddings after zip import / restore (when semantic enabled).', stability: 'experimental', default: 'on', type: 'boolean', since: '1.27.3' },
+    // Storage backend
+    { name: 'INDEX_SERVER_STORAGE_BACKEND', category: 'storage', description: 'Instruction store backend: json (default) | sqlite (experimental).', stability: 'experimental', default: 'json', type: 'string', since: '1.25.0' },
+    { name: 'INDEX_SERVER_SQLITE_PATH', category: 'storage', description: 'SQLite database file path.', stability: 'experimental', default: './data/index.db', type: 'string', since: '1.25.0' },
+    { name: 'INDEX_SERVER_SQLITE_WAL', category: 'storage', description: 'Enable SQLite WAL journaling.', stability: 'experimental', default: 'on', type: 'boolean', since: '1.25.0' },
+    { name: 'INDEX_SERVER_SQLITE_MIGRATE_ON_START', category: 'storage', description: 'Run schema migrations at startup.', stability: 'experimental', default: 'on', type: 'boolean', since: '1.25.0' },
+    { name: 'INDEX_SERVER_SQLITE_VEC_ENABLED', category: 'storage', description: 'Enable sqlite-vec extension for embeddings.', stability: 'experimental', default: 'off', type: 'boolean', since: '1.25.0' },
+    { name: 'INDEX_SERVER_SQLITE_VEC_PATH', category: 'storage', description: 'Path to sqlite-vec loadable extension.', stability: 'experimental', default: '(unset)', type: 'string', since: '1.25.0' },
+    // Feedback & messaging
+    { name: 'INDEX_SERVER_FEEDBACK_DIR', category: 'feedback', description: 'Feedback storage directory.', stability: 'stable', default: './feedback', type: 'string', since: '1.10.0' },
+    { name: 'INDEX_SERVER_FEEDBACK_MAX_ENTRIES', category: 'feedback', description: 'Maximum retained feedback entries.', stability: 'stable', default: '10000', type: 'number', since: '1.10.0' },
+    { name: 'INDEX_SERVER_MESSAGING_DIR', category: 'messaging', description: 'Inter-agent messaging storage dir.', stability: 'experimental', default: './data/messaging', type: 'string', since: '1.18.0' },
+    { name: 'INDEX_SERVER_MESSAGING_MAX', category: 'messaging', description: 'Max retained messages.', stability: 'experimental', default: '5000', type: 'number', since: '1.18.0' },
+    { name: 'INDEX_SERVER_MESSAGING_SWEEP_MS', category: 'messaging', description: 'Messaging sweep interval (ms).', stability: 'experimental', default: '60000', type: 'number', since: '1.18.0' },
+    // Dashboard / TLS
+    { name: 'INDEX_SERVER_DASHBOARD_TLS', category: 'dashboard', description: 'Enable HTTPS for the admin dashboard.', stability: 'stable', default: 'off', type: 'boolean', since: '1.20.0' },
+    { name: 'INDEX_SERVER_DASHBOARD_TLS_CERT', category: 'dashboard', description: 'TLS certificate path.', stability: 'stable', default: '(unset)', type: 'string', since: '1.20.0' },
+    { name: 'INDEX_SERVER_DASHBOARD_TLS_KEY', category: 'dashboard', description: 'TLS private key path.', stability: 'stable', default: '(unset)', type: 'string', since: '1.20.0' },
+    { name: 'INDEX_SERVER_DASHBOARD_TLS_CA', category: 'dashboard', description: 'Optional TLS CA bundle path.', stability: 'stable', default: '(unset)', type: 'string', since: '1.20.0' },
+    { name: 'INDEX_SERVER_DASHBOARD_GRAPH', category: 'dashboard', description: 'Enable dashboard graph rendering.', stability: 'stable', default: 'off', type: 'boolean', since: '1.18.0' },
+    { name: 'INDEX_SERVER_HTTP_METRICS', category: 'dashboard', description: 'Expose Prometheus-style HTTP metrics.', stability: 'stable', default: 'on', type: 'boolean', since: '1.20.0' },
+    { name: 'INDEX_SERVER_REQUEST_TIMEOUT', category: 'dashboard', description: 'HTTP request timeout (ms).', stability: 'stable', default: '30000', type: 'number', since: '1.20.0' },
+    { name: 'INDEX_SERVER_MAX_CONNECTIONS', category: 'dashboard', description: 'Max concurrent HTTP connections.', stability: 'stable', default: '100', type: 'number', since: '1.20.0' },
+    { name: 'INDEX_SERVER_ADMIN_API_KEY', category: 'auth', description: 'Bearer token for admin endpoints.', stability: 'stable', default: '(unset)', type: 'string', since: '1.20.0' },
+    { name: 'INDEX_SERVER_ADMIN_MAX_SESSION_HISTORY', category: 'dashboard', description: 'Max retained admin session history.', stability: 'stable', default: '500', type: 'number', since: '1.20.0' },
+    { name: 'INDEX_SERVER_BACKUPS_DIR', category: 'dashboard', description: 'Directory for backup zips.', stability: 'stable', default: './backups', type: 'string', since: '1.20.0' },
+    { name: 'INDEX_SERVER_STATE_DIR', category: 'dashboard', description: 'Persistent dashboard state directory.', stability: 'stable', default: './data/state', type: 'string', since: '1.20.0' },
+    // Backup / mutation safety
+    { name: 'INDEX_SERVER_AUTO_BACKUP', category: 'index', description: 'Auto-create backup before risky mutations.', stability: 'stable', default: 'on', type: 'boolean', since: '1.20.0' },
+    { name: 'INDEX_SERVER_AUTO_BACKUP_INTERVAL_MS', category: 'index', description: 'Auto-backup interval ms.', stability: 'stable', default: '3600000', type: 'number', since: '1.20.0' },
+    { name: 'INDEX_SERVER_AUTO_BACKUP_MAX_COUNT', category: 'index', description: 'Max retained auto-backups.', stability: 'stable', default: '10', type: 'number', since: '1.20.0' },
+    { name: 'INDEX_SERVER_BACKUP_BEFORE_BULK_DELETE', category: 'index', description: 'Snapshot before bulk delete.', stability: 'stable', default: 'on', type: 'boolean', since: '1.20.0' },
+    { name: 'INDEX_SERVER_MAX_BULK_DELETE', category: 'index', description: 'Max ids per bulk delete call.', stability: 'stable', default: '1000', type: 'number', since: '1.20.0' },
+    { name: 'INDEX_SERVER_BODY_WARN_LENGTH', category: 'index', description: 'Warn-then-reject threshold for instruction body length.', stability: 'stable', default: '50000', type: 'number', since: '1.20.0' },
+    { name: 'INDEX_SERVER_AUTO_SPLIT_OVERSIZED', category: 'index', description: 'Auto-split oversized instruction bodies on add.', stability: 'experimental', default: 'off', type: 'boolean', since: '1.20.0' },
+    { name: 'INDEX_SERVER_AUTO_USAGE_TRACK', category: 'usage', description: 'Auto-track usage for tool invocations.', stability: 'stable', default: 'on', type: 'boolean', since: '1.20.0' },
+    // Bootstrap & seed
+    { name: 'INDEX_SERVER_AUTO_SEED', category: 'bootstrap', description: 'Auto-seed canonical bootstrap instructions on first start.', stability: 'stable', default: 'on', type: 'boolean', since: '1.10.0' },
+    { name: 'INDEX_SERVER_SEED_VERBOSE', category: 'bootstrap', description: 'Verbose seed-bootstrap logging.', stability: 'diagnostic', default: 'off', type: 'boolean', since: '1.10.0' },
+    { name: 'INDEX_SERVER_BOOTSTRAP_AUTOCONFIRM', category: 'bootstrap', description: 'Auto-confirm bootstrap (skip token prompt).', stability: 'stable', default: 'off', type: 'boolean', since: '1.10.0' },
+    { name: 'INDEX_SERVER_BOOTSTRAP_TOKEN_TTL_SEC', category: 'bootstrap', description: 'Bootstrap token TTL (seconds).', stability: 'stable', default: '600', type: 'number', since: '1.10.0' },
+    // Logging surface
+    { name: 'INDEX_SERVER_LOG_FILE', category: 'core', description: 'NDJSON log file path (or 1 to use default).', stability: 'stable', default: '(unset)', type: 'string', since: '1.0.0' },
+    { name: 'INDEX_SERVER_LOG_LEVEL', category: 'core', description: 'Minimum log level: trace|debug|info|warn|error.', stability: 'stable', default: 'info', type: 'string', since: '1.20.0' },
+    { name: 'INDEX_SERVER_LOG_JSON', category: 'core', description: '(Reserved) Force JSON log mode.', stability: 'reserved', default: 'off', type: 'boolean', since: '1.0.0' },
+    { name: 'INDEX_SERVER_LOG_SYNC', category: 'diagnostics', description: 'Fsync after each log write (test determinism).', stability: 'diagnostic', default: 'off', type: 'boolean', since: '1.0.0' },
+    { name: 'INDEX_SERVER_LOG_PROTOCOL', category: 'diagnostics', description: 'Log MCP protocol frames.', stability: 'diagnostic', default: 'off', type: 'boolean', since: '1.0.0' },
+    { name: 'INDEX_SERVER_EVENT_BUFFER_SIZE', category: 'diagnostics', description: 'Capacity of in-memory WARN/ERROR ring buffer surfaced in dashboard Events panel.', stability: 'stable', default: '500', type: 'number', since: '1.27.3' },
+    { name: 'INDEX_SERVER_EVENT_SILENT', category: 'diagnostics', description: 'Suppress redundant index-event logs.', stability: 'diagnostic', default: 'off', type: 'boolean', since: '1.20.0' },
+    // Profile / dev mode
+    { name: 'INDEX_SERVER_PROFILE', category: 'core', description: 'Runtime profile selector (default | dev | prod).', stability: 'stable', default: 'default', type: 'string', since: '1.20.0' },
+    // Operationally-meaningful additions surfaced by the catalog drift test.
+    { name: 'INDEX_SERVER_BODY_MAX_LENGTH', category: 'index', description: 'Hard reject threshold for instruction body length (bytes).', stability: 'stable', default: '(unset)', type: 'number', since: '1.20.0' },
+    { name: 'INDEX_SERVER_MAX_FILES', category: 'index', description: 'Soft cap on number of indexed instruction files.', stability: 'stable', default: '(unset)', type: 'number', since: '1.20.0' },
+    { name: 'INDEX_SERVER_LOAD_WARN_MS', category: 'diagnostics', description: 'Emit WARN if initial index load exceeds this many ms.', stability: 'diagnostic', default: '(unset)', type: 'number', since: '1.20.0' },
+    { name: 'INDEX_SERVER_AGENT_ID', category: 'core', description: 'Logical agent identity for audit/attestation trailers.', stability: 'stable', default: '(unset)', type: 'string', since: '1.20.0' },
+    { name: 'INDEX_SERVER_FLAGS_FILE', category: 'core', description: 'Path to feature-flag persistence file.', stability: 'stable', default: './flags.json', type: 'string', since: '1.10.0' },
+    { name: 'INDEX_SERVER_HEALTH_MEMORY_THRESHOLD', category: 'diagnostics', description: 'Memory threshold (bytes) for /health degraded status.', stability: 'diagnostic', default: '(unset)', type: 'number', since: '1.20.0' },
+    { name: 'INDEX_SERVER_HEALTH_ERROR_THRESHOLD', category: 'diagnostics', description: 'Error-rate threshold for /health degraded status.', stability: 'diagnostic', default: '(unset)', type: 'number', since: '1.20.0' },
+    { name: 'INDEX_SERVER_HEALTH_MIN_UPTIME', category: 'diagnostics', description: 'Minimum uptime (s) before /health reports healthy.', stability: 'diagnostic', default: '(unset)', type: 'number', since: '1.20.0' },
+    { name: 'INDEX_SERVER_RESOURCE_CAPACITY', category: 'diagnostics', description: 'In-memory resource sample buffer capacity.', stability: 'diagnostic', default: '(unset)', type: 'number', since: '1.20.0' },
+    { name: 'INDEX_SERVER_RESOURCE_SAMPLE_INTERVAL_MS', category: 'diagnostics', description: 'Resource sampler interval (ms).', stability: 'diagnostic', default: '(unset)', type: 'number', since: '1.20.0' },
+    { name: 'INDEX_SERVER_TOOLCALL_CHUNK_SIZE', category: 'diagnostics', description: 'Tool-call ring buffer chunk size.', stability: 'diagnostic', default: '(unset)', type: 'number', since: '1.20.0' },
+    { name: 'INDEX_SERVER_TOOLCALL_FLUSH_MS', category: 'diagnostics', description: 'Tool-call ring buffer flush interval (ms).', stability: 'diagnostic', default: '(unset)', type: 'number', since: '1.20.0' },
+    { name: 'INDEX_SERVER_TOOLCALL_COMPACT_MS', category: 'diagnostics', description: 'Tool-call ring buffer compaction interval (ms).', stability: 'diagnostic', default: '(unset)', type: 'number', since: '1.20.0' },
+    { name: 'INDEX_SERVER_TOOLCALL_APPEND_LOG', category: 'diagnostics', description: 'Append-only tool-call log path.', stability: 'diagnostic', default: '(unset)', type: 'string', since: '1.20.0' },
+    { name: 'INDEX_SERVER_AUDIT_LOG', category: 'diagnostics', description: 'Audit log file path (mutation operations).', stability: 'diagnostic', default: '(unset)', type: 'string', since: '1.10.0' },
+    { name: 'INDEX_SERVER_NORMALIZATION_LOG', category: 'diagnostics', description: 'Normalization log file path.', stability: 'diagnostic', default: '(unset)', type: 'string', since: '1.10.0' },
+    { name: 'INDEX_SERVER_TRACE', category: 'diagnostics', description: 'Enable verbose trace logging.', stability: 'diagnostic', default: 'off', type: 'boolean', since: '1.0.0' },
+    { name: 'INDEX_SERVER_TIMING_JSON', category: 'diagnostics', description: 'Emit timing data as JSON-NDJSON.', stability: 'diagnostic', default: 'off', type: 'boolean', since: '1.20.0' },
+    { name: 'INDEX_SERVER_MINIMAL_DEBUG', category: 'diagnostics', description: 'Minimal debug surface (reduces verbosity).', stability: 'diagnostic', default: 'off', type: 'boolean', since: '1.20.0' },
+    { name: 'INDEX_SERVER_STRESS_MODE', category: 'diagnostics', description: 'Enable stress-test instrumentation.', stability: 'diagnostic', default: 'off', type: 'boolean', since: '1.20.0' },
+    { name: 'INDEX_SERVER_GRAPH_INCLUDE_PRIMARY_EDGES', category: 'index', description: 'Include primary edges in graph export.', stability: 'experimental', default: 'on', type: 'boolean', since: '1.18.0' },
+    { name: 'INDEX_SERVER_GRAPH_LARGE_CATEGORY_CAP', category: 'index', description: 'Cap large-category fanout in graph export.', stability: 'experimental', default: '(unset)', type: 'number', since: '1.18.0' },
 ];
 function parseValue(meta) {
     const raw = process.env[meta.name];

package/dist/services/indexContext.d.ts

@@ -49,11 +49,29 @@ declare const invariantRepairLog: {
     field: string;
     source: string;
 }[];
+/**
+ * Test-only hook — reset process-scoped latches between vitest specs.
+ * @internal Not part of the public API.
+ */
+export declare function _resetIndexContextProcessLatches(): void;
+/**
+ * Test-only hook — reset the module-scoped index state cache.
+ * @internal Not part of the public API.
+ */
+export declare function _resetIndexContextStateForTests(): void;
 /** Returns a summary of invariant repairs for health check visibility. */
 export declare function getInvariantRepairSummary(): {
     totalRepairs: number;
     recentRepairs: typeof invariantRepairLog;
 };
+declare function restoreFirstSeenInvariant(e: InstructionEntry): void;
+/**
+ * Internal handles for unit tests only. Not part of the public API.
+ * @internal
+ */
+export declare const _internal: {
+    restoreFirstSeenInvariant: typeof restoreFirstSeenInvariant;
+};
 export declare function clearUsageRateLimit(id?: string): void;
 export declare function loadUsageSnapshot(): Record<string, UsagePersistRecord>;
 export declare function getInstructionsDir(): string;