@jagilber-org/index-server 1.26.11 → 1.27.2

package/dist/services/handlers.dashboardConfig.js

@@ -46,8 +46,7 @@ exports.FLAG_REGISTRY = [
     { name: 'INDEX_SERVER_VISIBILITY_DIAG', category: 'tracing', description: 'Force core trace level for visibility diagnostics.', stability: 'diagnostic', default: 'off', type: 'boolean', since: '1.1.1' },
     { name: 'INDEX_SERVER_FILE_TRACE', category: 'tracing', description: 'Promote index file events to trace level (files).', stability: 'diagnostic', default: 'off', type: 'boolean', since: '1.1.1' },
     // Usage & metrics
-    { name: 'INDEX_SERVER_DISABLE_RATE_LIMIT', category: 'usage', description: 'Disable all rate limiting (dashboard HTTP API and usage tracking). Rate limiting is enabled by default.', stability: 'stable', default: 'off', type: 'boolean', since: '1.1.3' },
-    { name: 'INDEX_SERVER_DISABLE_USAGE_RATE_LIMIT', category: 'usage', description: '(Deprecated) Legacy per-subsystem override to disable usage rate limit.', stability: 'diagnostic', default: 'off', type: 'boolean', since: '1.1.1' },
+    { name: 'INDEX_SERVER_RATE_LIMIT', category: 'usage', description: 'Dashboard HTTP API and usage-tracking rate limit, in requests per minute. 0 (default) disables rate limiting. Bulk import/export/backup/restore routes are unconditionally exempt.', stability: 'stable', default: '0', type: 'number', since: '1.27.0' },
     { name: 'INDEX_SERVER_DISABLE_USAGE_CLAMP', category: 'usage', description: 'Disable initial usage count clamp logic.', stability: 'diagnostic', default: 'off', type: 'boolean', since: '1.1.1' },
     { name: 'INDEX_SERVER_USAGE_FLUSH_MS', category: 'usage', description: 'Override usage flush debounce interval.', stability: 'diagnostic', default: '75', type: 'number', since: '1.1.1' },
     // Validation / schema
@@ -77,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;

package/dist/services/indexContext.js

@@ -3,6 +3,9 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports._internal = void 0;
+exports._resetIndexContextProcessLatches = _resetIndexContextProcessLatches;
+exports._resetIndexContextStateForTests = _resetIndexContextStateForTests;
 exports.getInvariantRepairSummary = getInvariantRepairSummary;
 exports.clearUsageRateLimit = clearUsageRateLimit;
 exports.loadUsageSnapshot = loadUsageSnapshot;
@@ -36,7 +39,6 @@ const features_1 = require("./features");
 const atomicFs_1 = require("./atomicFs");
 const classificationService_1 = require("./classificationService");
 const ownershipService_1 = require("./ownershipService");
-const envUtils_1 = require("../utils/envUtils");
 const runtimeConfig_1 = require("../config/runtimeConfig");
 const factory_1 = require("./storage/factory");
 const migrationEngine_1 = require("./storage/migrationEngine");
@@ -96,6 +98,33 @@ function trackInvariantRepair(id, field, source) {
     if (invariantRepairLog.length > MAX_REPAIR_LOG)
         invariantRepairLog.shift();
 }
+// ── Process-scoped latches for noise + work suppression ──────────
+// Symptom that motivated these latches (observed live on dev port 8687,
+// 2026-05-01): every dashboard request triggered ensureLoaded() →
+// migrateJsonToSqlite() because jsonFiles.length > sqliteRowCount was
+// permanently true (a few JSON files failed loader validation), and every
+// /api/admin/stats request emitted hundreds of stack-traced WARN entries
+// from restoreFirstSeenInvariant for entries whose firstSeenTs was
+// genuinely unrecoverable. Both of those are infinite-cost loops once the
+// process is up. We dedupe both per-process here.
+const autoMigrationAttempted = new Set();
+const firstSeenExhaustedReported = new Set();
+/**
+ * Test-only hook — reset process-scoped latches between vitest specs.
+ * @internal Not part of the public API.
+ */
+function _resetIndexContextProcessLatches() {
+    autoMigrationAttempted.clear();
+    firstSeenExhaustedReported.clear();
+}
+/**
+ * Test-only hook — reset the module-scoped index state cache.
+ * @internal Not part of the public API.
+ */
+function _resetIndexContextStateForTests() {
+    state = null;
+    dirty = false;
+}
 /** Returns a summary of invariant repairs for health check visibility. */
 function getInvariantRepairSummary() {
     return { totalRepairs: invariantRepairLog.length, recentRepairs: invariantRepairLog.slice(-20) };
@@ -111,7 +140,7 @@ function restoreFirstSeenInvariant(e) {
         e.firstSeenTs = auth;
         (0, features_1.incrementCounter)('usage:firstSeenAuthorityRepair');
         trackInvariantRepair(e.id, 'firstSeenTs', 'authority');
-        (0, logger_js_1.logWarn)(`[invariant-repair] firstSeenTs restored from authority for ${e.id}`);
+        (0, logger_js_1.logDebug)(`[invariant-repair] firstSeenTs restored from authority for ${e.id}`);
         return;
     }
     const ep = ephemeralFirstSeen[e.id];
@@ -119,7 +148,7 @@ function restoreFirstSeenInvariant(e) {
         e.firstSeenTs = ep;
         (0, features_1.incrementCounter)('usage:firstSeenInvariantRepair');
         trackInvariantRepair(e.id, 'firstSeenTs', 'ephemeral');
-        (0, logger_js_1.logWarn)(`[invariant-repair] firstSeenTs restored from ephemeral cache for ${e.id}`);
+        (0, logger_js_1.logDebug)(`[invariant-repair] firstSeenTs restored from ephemeral cache for ${e.id}`);
         return;
     }
     const snap = lastGoodUsageSnapshot[e.id];
@@ -127,15 +156,40 @@ function restoreFirstSeenInvariant(e) {
         e.firstSeenTs = snap.firstSeenTs;
         (0, features_1.incrementCounter)('usage:firstSeenInvariantRepair');
         trackInvariantRepair(e.id, 'firstSeenTs', 'snapshot');
-        (0, logger_js_1.logWarn)(`[invariant-repair] firstSeenTs restored from snapshot for ${e.id}`);
+        (0, logger_js_1.logDebug)(`[invariant-repair] firstSeenTs restored from snapshot for ${e.id}`);
+        return;
+    }
+    // Final fallback: createdAt. By definition firstSeenTs ≤ createdAt is impossible
+    // (the index can never have observed an entry before it was created). For
+    // freshly-imported / freshly-added entries with no usage history yet, this is
+    // the correct answer; for legacy on-disk entries written before write-path
+    // populated firstSeenTs, it heals them silently. Repaired silently (no WARN)
+    // because this is the documented authoritative semantic, not a defect.
+    if (e.createdAt) {
+        e.firstSeenTs = e.createdAt;
+        firstSeenAuthority[e.id] = e.createdAt;
+        (0, features_1.incrementCounter)('usage:firstSeenCreatedAtFallback');
+        trackInvariantRepair(e.id, 'firstSeenTs', 'createdAt');
+        return;
     }
-    // If still missing after all repair sources, track an exhausted repair attempt (extremely rare diagnostic)
+    // If still missing after all repair sources, track an exhausted repair attempt (extremely rare diagnostic).
+    // Dedup the WARN per-id-per-process: a permanently unrecoverable id otherwise spams hundreds of
+    // stack-traced WARNs per dashboard poll (RCA 2026-05-01, dev port 8687). The counter and audit
+    // trail still increment on every call so health metrics remain accurate.
     if (!e.firstSeenTs) {
         (0, features_1.incrementCounter)('usage:firstSeenRepairExhausted');
         trackInvariantRepair(e.id, 'firstSeenTs', 'exhausted');
-        (0, logger_js_1.logWarn)(`[invariant-repair] firstSeenTs repair exhausted — no source found for ${e.id}`);
+        if (!firstSeenExhaustedReported.has(e.id)) {
+            firstSeenExhaustedReported.add(e.id);
+            (0, logger_js_1.logWarn)(`[invariant-repair] firstSeenTs repair exhausted — no source found for ${e.id}`);
+        }
     }
 }
+/**
+ * Internal handles for unit tests only. Not part of the public API.
+ * @internal
+ */
+exports._internal = { restoreFirstSeenInvariant };
 // Usage invariant repair (mirrors firstSeen invariant strategy). Extremely rare reload races in CI produced
 // states where a freshly re-materialized InstructionEntry temporarily lacked its prior usageCount (observed
 // by usageTracking.spec snapshot reads) even though authority maps retained the correct monotonic value.
@@ -202,11 +256,11 @@ function restoreLastUsedInvariant(e) {
 const USAGE_RATE_LIMIT_PER_SECOND = 10; // max increments per id per second
 const usageRateLimiter = new Map();
 function checkUsageRateLimit(id) {
-    // Rate limiting is enabled by default. Set INDEX_SERVER_DISABLE_RATE_LIMIT=1 to disable all rate limiting.
-    if ((0, envUtils_1.getBooleanEnv)('INDEX_SERVER_DISABLE_RATE_LIMIT'))
-        return true;
-    // Legacy per-subsystem override (backward compat / deterministic tests).
-    if ((0, envUtils_1.getBooleanEnv)('INDEX_SERVER_DISABLE_USAGE_RATE_LIMIT'))
+    // Rate limiting is opt-in. INDEX_SERVER_RATE_LIMIT=0 (default) or unset
+    // disables both the dashboard HTTP limiter and this usage limiter.
+    // Any positive integer enables both.
+    const rl = Number(process.env.INDEX_SERVER_RATE_LIMIT);
+    if (!Number.isFinite(rl) || rl <= 0)
         return true;
     const now = Date.now();
     const windowStart = Math.floor(now / 1000) * 1000; // 1-second windows
@@ -422,14 +476,30 @@ function touchIndexVersion() {
     }
     catch { /* ignore */ }
 }
-function readVersionMTime() { try {
-    const vf = getVersionFile();
-    if (fs_1.default.existsSync(vf)) {
-        const st = fs_1.default.statSync(vf);
+function readVersionMTime() {
+    try {
+        const vf = getVersionFile();
+        if (fs_1.default.existsSync(vf)) {
+            const st = fs_1.default.statSync(vf);
+            return st.mtimeMs || 0;
+        }
+    }
+    catch { /* ignore */ }
+    // Fallback: when no .index-version file exists, use the instructions
+    // directory's own mtime so the ensureLoaded() cache short-circuit can still
+    // recognize an unchanged source. RCA 2026-05-01 (live dev port 8787 vs an
+    // operator-explored repo with no version file): readVersionMTime() returned
+    // 0, the falsy short-circuit `if (currentVersionMTime && ...)` always failed,
+    // every dashboard poll triggered a full disk reload + simple-reload trace,
+    // saturating the event loop and breaking dashboard imports.
+    try {
+        const baseDir = getInstructionsDir();
+        const st = fs_1.default.statSync(baseDir);
         return st.mtimeMs || 0;
     }
+    catch { /* ignore */ }
+    return 0;
 }
-catch { /* ignore */ } return 0; }
 function readVersionToken() { try {
     const vf = getVersionFile();
     if (fs_1.default.existsSync(vf)) {
@@ -504,20 +574,30 @@ function ensureLoaded() {
     const backend = (0, runtimeConfig_1.getRuntimeConfig)().storage?.backend ?? 'json';
     const store = backend === 'sqlite' ? getStoreForDir(baseDir) : null;
     let result = store ? store.load() : new indexLoader_1.IndexLoader(baseDir).load();
-    // Auto-migrate JSON → SQLite when JSON files on disk outnumber SQLite rows
+    // Auto-migrate JSON → SQLite when JSON files on disk outnumber SQLite rows.
+    // Per-process latch (RCA 2026-05-01): without this, mismatched counts caused by
+    // a few unparseable JSON files (jsonFiles.length permanently > sqlite rows) made
+    // ensureLoaded() re-invoke migrateJsonToSqlite() on every reload tick, causing
+    // INSERT-OR-REPLACE storms and unbounded WAL growth (~1.21 GB observed in dev
+    // before the fix). One attempt per (baseDir, dbPath) per process is enough; if
+    // an operator truly needs a re-migrate, they restart the server.
     if (store && (0, runtimeConfig_1.getRuntimeConfig)().storage?.sqliteMigrateOnStart) {
-        const jsonFiles = fs_1.default.existsSync(baseDir) ? fs_1.default.readdirSync(baseDir).filter(f => f.endsWith('.json') && !f.startsWith('_')) : [];
-        if (jsonFiles.length > result.entries.length) {
-            try {
-                const dbPath = (0, runtimeConfig_1.getRuntimeConfig)().storage?.sqlitePath ?? path_1.default.join(process.cwd(), 'data', 'index.db');
-                const mr = (0, migrationEngine_1.migrateJsonToSqlite)(baseDir, dbPath);
-                if (mr.migrated > 0) {
-                    (0, logger_js_1.logInfo)(`[storage] Auto-migrated ${mr.migrated} instruction(s) from JSON → SQLite`);
-                    result = store.load();
+        const dbPath = (0, runtimeConfig_1.getRuntimeConfig)().storage?.sqlitePath ?? path_1.default.join(process.cwd(), 'data', 'index.db');
+        const latchKey = `${baseDir}|${dbPath}`;
+        if (!autoMigrationAttempted.has(latchKey)) {
+            autoMigrationAttempted.add(latchKey);
+            const jsonFiles = fs_1.default.existsSync(baseDir) ? fs_1.default.readdirSync(baseDir).filter(f => f.endsWith('.json') && !f.startsWith('_')) : [];
+            if (jsonFiles.length > result.entries.length) {
+                try {
+                    const mr = (0, migrationEngine_1.migrateJsonToSqlite)(baseDir, dbPath);
+                    if (mr.migrated > 0) {
+                        (0, logger_js_1.logInfo)(`[storage] Auto-migrated ${mr.migrated} instruction(s) from JSON → SQLite`);
+                        result = store.load();
+                    }
+                }
+                catch (err) {
+                    (0, logger_js_1.logWarn)('[storage] Auto-migration failed:', err);
                 }
-            }
-            catch (err) {
-                (0, logger_js_1.logWarn)('[storage] Auto-migration failed:', err);
             }
         }
     }
@@ -526,7 +606,17 @@ function ensureLoaded() {
     // Deduplicate list using byId so two on-disk files with the same id field never produce duplicate
     // search results. byId already uses last-write-wins semantics; list must be consistent with it.
     const deduplicatedList = Array.from(byId.values());
-    state = { loadedAt: new Date().toISOString(), hash: result.hash, byId, list: deduplicatedList, fileCount: deduplicatedList.length, versionMTime: currentVersionMTime, versionToken: currentVersionToken, loadErrors: result.errors, loadDebug: result.debug, loadSummary: result.summary };
+    // RCA 2026-05-01 (live dev port 8787): IndexLoader.load() writes _manifest.json
+    // and _skipped.json into baseDir as a side-effect, which bumps the directory's
+    // mtime. If we cached the pre-load mtime here, the very next ensureLoaded()
+    // call would observe a newer mtime, miss the cache, and reload again — an
+    // unbounded loop that emitted [trace:ensureLoaded:simple-reload] hundreds of
+    // times per second and saturated the event loop (dashboard imports failed).
+    // Re-read the mtime AFTER load so the cached value reflects the post-write
+    // state; subsequent calls without source changes will then short-circuit.
+    const postLoadVersionMTime = readVersionMTime();
+    const postLoadVersionToken = readVersionToken();
+    state = { loadedAt: new Date().toISOString(), hash: result.hash, byId, list: deduplicatedList, fileCount: deduplicatedList.length, versionMTime: postLoadVersionMTime || currentVersionMTime, versionToken: postLoadVersionToken || currentVersionToken, loadErrors: result.errors, loadDebug: result.debug, loadSummary: result.summary };
     dirty = false;
     // Overlay usage snapshot (simplified; no spin/repair loops here—existing invariant repairs still occur in getIndexState)
     try {
@@ -574,7 +664,11 @@ async function ensureLoadedAsync() {
     const byId = new Map();
     result.entries.forEach(e => byId.set(e.id, e));
     const deduplicatedList = Array.from(byId.values());
-    state = { loadedAt: new Date().toISOString(), hash: result.hash, byId, list: deduplicatedList, fileCount: deduplicatedList.length, versionMTime: currentVersionMTime, versionToken: currentVersionToken, loadErrors: result.errors, loadDebug: result.debug, loadSummary: result.summary };
+    // See RCA comment in ensureLoaded() above: re-read mtime AFTER load to absorb
+    // _manifest.json / _skipped.json side-effect writes.
+    const postLoadVersionMTime = readVersionMTime();
+    const postLoadVersionToken = readVersionToken();
+    state = { loadedAt: new Date().toISOString(), hash: result.hash, byId, list: deduplicatedList, fileCount: deduplicatedList.length, versionMTime: postLoadVersionMTime || currentVersionMTime, versionToken: postLoadVersionToken || currentVersionToken, loadErrors: result.errors, loadDebug: result.debug, loadSummary: result.summary };
     dirty = false;
     try {
         const snap = loadUsageSnapshot();
@@ -827,6 +921,15 @@ function isDuplicateInstructionWriteError(error) {
 }
 function writeEntry(entry, opts) {
     const file = path_1.default.join(getInstructionsDir(), `${entry.id}.json`);
+    // Establish firstSeenTs at the write boundary if the caller omitted it.
+    // Semantically firstSeenTs ≤ createdAt always — for fresh entries this is
+    // the correct value, and persisting it on disk avoids spurious
+    // [invariant-repair] WARN spam on every subsequent getIndexState() poll
+    // (RCA 2026-05-01 dev port 8687, third loop in chain after PR #285/#286).
+    if (!entry.firstSeenTs) {
+        entry.firstSeenTs = entry.createdAt || new Date().toISOString();
+        firstSeenAuthority[entry.id] = entry.firstSeenTs;
+    }
     const classifier = new classificationService_1.ClassificationService();
     let record = classifier.normalize(entry);
     if (record.owner === 'unowned') {
@@ -881,6 +984,11 @@ function writeEntry(entry, opts) {
 }
 async function writeEntryAsync(entry, opts) {
     const file = path_1.default.join(getInstructionsDir(), `${entry.id}.json`);
+    // See writeEntry: establish firstSeenTs at the write boundary if missing.
+    if (!entry.firstSeenTs) {
+        entry.firstSeenTs = entry.createdAt || new Date().toISOString();
+        firstSeenAuthority[entry.id] = entry.firstSeenTs;
+    }
     const classifier = new classificationService_1.ClassificationService();
     let record = classifier.normalize(entry);
     if (record.owner === 'unowned') {

package/dist/services/logger.js

@@ -11,6 +11,7 @@ const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
 const runtimeConfig_1 = require("../config/runtimeConfig");
 const mcpLogBridge_1 = require("./mcpLogBridge");
+const eventBuffer_1 = require("./eventBuffer");
 /** Numeric priority for log level filtering (lower = more verbose). */
 const LEVEL_PRIORITY = {
     TRACE: 0,
@@ -231,6 +232,14 @@ function emit(rec) {
         }
         catch { /* ignore file write failures */ }
     }
+    // Surface WARN/ERROR into the in-process events ring buffer so the dashboard
+    // Monitoring panel can display them without log-file tailing (OB-3, OB-5).
+    if (rec.level === 'WARN' || rec.level === 'ERROR') {
+        try {
+            (0, eventBuffer_1.recordEvent)(rec.level, rec.msg, rec.detail, rec.pid);
+        }
+        catch { /* never let buffer failure break logging */ }
+    }
 }
 /**
  * Emit a structured NDJSON log record at the specified level.

package/dist/services/manifestManager.js

@@ -20,7 +20,17 @@ const features_1 = require("./features");
 const logger_1 = require("./logger");
 const runtimeConfig_1 = require("../config/runtimeConfig");
 const MANIFEST_RELATIVE = path_1.default.join('snapshots', 'index-manifest.json');
-function getManifestPath() { return path_1.default.join(process.cwd(), MANIFEST_RELATIVE); }
+function getManifestPath() {
+    // Tests run in parallel forks (vitest pool=forks, maxWorkers=4) and each fork
+    // shares the same process.cwd(); without an override, multiple test files that
+    // enable manifest write race on the same on-disk file. Honor an explicit path
+    // override so test setup can isolate per-spec output. Production leaves this
+    // unset and continues to use the canonical snapshot path.
+    const override = process.env.INDEX_SERVER_MANIFEST_PATH;
+    if (override && override.trim())
+        return path_1.default.isAbsolute(override) ? override : path_1.default.join(process.cwd(), override);
+    return path_1.default.join(process.cwd(), MANIFEST_RELATIVE);
+}
 /**
  * Load the manifest from disk.
  * @returns The parsed {@link IndexManifest}, or `null` if the file is absent or unparseable

package/dist/services/seedBootstrap.js

@@ -223,7 +223,11 @@ function autoSeedBootstrap() {
         // Directory empty OR missing seed triggers creation.
         try {
             const tmp = path_1.default.join(dir, `.${seed.file}.tmp-${process.pid}-${Date.now()}-${Math.random().toString(16).slice(2)}`);
-            fs_1.default.writeFileSync(tmp, JSON.stringify(seed.json, null, 2), { encoding: 'utf8' });
+            // Inject timestamps at write time so loaders never trigger
+            // [invariant-repair] firstSeenTs WARN noise on subsequent reads.
+            const nowIso = new Date().toISOString();
+            const stamped = { createdAt: nowIso, firstSeenTs: nowIso, ...seed.json };
+            fs_1.default.writeFileSync(tmp, JSON.stringify(stamped, null, 2), { encoding: 'utf8' });
             fs_1.default.renameSync(tmp, target);
             summary.created.push(seed.file);
         }

package/dist/services/storage/factory.d.ts

@@ -6,6 +6,8 @@
  */
 import type { IInstructionStore, IEmbeddingStore } from './types.js';
 export type StorageBackend = 'json' | 'sqlite';
+/** Test-only: reset the warn-once latch. */
+export declare function _resetSqliteExperimentalWarning(): void;
 /**
  * Check that the current Node.js version meets the minimum requirement.
  * Throws a clear error if the version is too old.

package/dist/services/storage/factory.js

@@ -6,6 +6,7 @@
  * Default: JsonFileStore (json). Experimental: SqliteStore (sqlite).
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports._resetSqliteExperimentalWarning = _resetSqliteExperimentalWarning;
 exports.checkNodeVersion = checkNodeVersion;
 exports.createStore = createStore;
 exports.createEmbeddingStore = createEmbeddingStore;
@@ -14,6 +15,13 @@ const jsonFileStore_js_1 = require("./jsonFileStore.js");
 const jsonEmbeddingStore_js_1 = require("./jsonEmbeddingStore.js");
 const sqliteStore_js_1 = require("./sqliteStore.js");
 const logger_js_1 = require("../logger.js");
+/** Process-scoped flag so the EXPERIMENTAL SQLite warning is emitted once,
+ *  not per-store-creation (which floods the events ring on every request). */
+let sqliteExperimentalWarned = false;
+/** Test-only: reset the warn-once latch. */
+function _resetSqliteExperimentalWarning() {
+    sqliteExperimentalWarned = false;
+}
 /**
  * Check that the current Node.js version meets the minimum requirement.
  * Throws a clear error if the version is too old.
@@ -46,7 +54,10 @@ function createStore(backend, dir, sqlitePath) {
     switch (resolvedBackend) {
         case 'sqlite': {
             checkNodeVersion('22.5.0', 'SQLite storage backend (node:sqlite)');
-            (0, logger_js_1.logWarn)('[storage] ⚠️  EXPERIMENTAL: SQLite backend is enabled. This feature has limited testing and may have data-loss or compatibility issues. Not recommended for production use.');
+            if (!sqliteExperimentalWarned) {
+                sqliteExperimentalWarned = true;
+                (0, logger_js_1.logWarn)('[storage] ⚠️  EXPERIMENTAL: SQLite backend is enabled. This feature has limited testing and may have data-loss or compatibility issues. Not recommended for production use.');
+            }
             const dbPath = sqlitePath ?? config.storage?.sqlitePath ?? 'data/index.db';
             return new sqliteStore_js_1.SqliteStore(dbPath);
         }

package/dist/services/tracing.js

@@ -219,8 +219,10 @@ function emitTrace(label, data, min = 1) {
     if (caller)
         rec.func = caller;
     pushBuffer(rec, tracing.buffer);
+    // Trace records are diagnostic, not errors. Route through DEBUG so they do
+    // not pollute the WARN/ERROR events ring buffer surfaced to the dashboard.
     try {
-        (0, logger_js_1.logError)(label, JSON.stringify(rec));
+        (0, logger_js_1.logDebug)(label, JSON.stringify(rec));
     }
     catch { /* ignore */ }
     if (!(tracing.persist || tracing.file))

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@jagilber-org/index-server",
-  "version": "1.26.11",
+  "version": "1.27.2",
   "mcpName": "io.github.jagilber-org/index-server",
-  "description": "MCP instruction indexing server for AI assistant governance — search, CRUD, schema validation, usage tracking, and cross-repo knowledge promotion.",
+  "description": "MCP instruction indexing server with search, CRUD, validation, and cross-repo knowledge promotion.",
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",
     "access": "public"
@@ -62,6 +62,7 @@
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "lint": "eslint .",
     "lint:instructions": "node scripts/lint-instructions.mjs",
+    "lint:logs": "node scripts/crawl-logs.mjs --dir logs --file test-results/test-output.log --allowlist .crawl-logs-allowlist --strict",
     "format": "prettier --write .",
     "prepare": "node scripts/setup-hooks.cjs",
     "audit": "npm audit --omit=dev --audit-level=high",
@@ -134,6 +135,15 @@
     "ws": "^8.19.0",
     "zod": "^3.23.8"
   },
+  "overrides": {
+    "mermaid": {
+      "uuid": "^14.0.0"
+    },
+    "@mermaid-js/layout-elk": {
+      "uuid": "^14.0.0"
+    },
+    "@types/express-serve-static-core": "5.0.7"
+  },
   "optionalScripts": {},
   "promptReviewCriteriaVersion": "1.0.0",
   "license": "MIT",