@jagilber-org/index-server 1.27.0 → 1.28.0

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;
@@ -95,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) };
@@ -110,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];
@@ -118,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];
@@ -126,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.
@@ -421,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)) {
@@ -503,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);
             }
         }
     }
@@ -525,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 {
@@ -573,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();
@@ -826,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') {
@@ -880,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/instructionRecordValidation.d.ts

@@ -14,6 +14,9 @@ export declare class InstructionValidationError extends Error {
     constructor(validationErrors: string[], hints?: string[], schemaRef?: string);
 }
 export declare const INSTRUCTION_ID_MAX_LENGTH = 120;
+export declare const INSTRUCTION_ID_PATTERN: RegExp;
+export declare function validateInstructionIdSurface(id: unknown): string[];
+export declare function validateInstructionInputEnumMembership(entry: Record<string, unknown>): string[];
 export declare function validateInstructionInputSurface(entry: Record<string, unknown>): InstructionValidationResult;
 export declare function validateInstructionRecord(entry: InstructionEntry): InstructionValidationResult;
 export declare function assertValidInstructionRecord(entry: InstructionEntry): InstructionEntry;

package/dist/services/instructionRecordValidation.js

@@ -3,7 +3,9 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.INSTRUCTION_INPUT_SCHEMA_REF = exports.INSTRUCTION_ID_MAX_LENGTH = exports.InstructionValidationError = void 0;
+exports.INSTRUCTION_INPUT_SCHEMA_REF = exports.INSTRUCTION_ID_PATTERN = exports.INSTRUCTION_ID_MAX_LENGTH = exports.InstructionValidationError = void 0;
+exports.validateInstructionIdSurface = validateInstructionIdSurface;
+exports.validateInstructionInputEnumMembership = validateInstructionInputEnumMembership;
 exports.validateInstructionInputSurface = validateInstructionInputSurface;
 exports.validateInstructionRecord = validateInstructionRecord;
 exports.assertValidInstructionRecord = assertValidInstructionRecord;
@@ -218,12 +220,16 @@ function applyWriteCompatibility(entry) {
         else if (legacyRequirementMap[upper])
             next.requirement = legacyRequirementMap[upper];
     }
+    if (next.contentType === 'chat-session') {
+        next.contentType = 'workflow';
+    }
     if (typeof next.priority !== 'number' || next.priority < 1 || next.priority > 100)
         next.priority = 50;
     return next;
 }
 // Matches the upper bound declared in schemas/instruction.schema.json (id maxLength).
 exports.INSTRUCTION_ID_MAX_LENGTH = 120;
+exports.INSTRUCTION_ID_PATTERN = /^[a-z0-9](?:[a-z0-9-_]{0,118}[a-z0-9])?$/;
 function findIllegalControlChar(id) {
     for (let i = 0; i < id.length; i++) {
         const code = id.charCodeAt(i);
@@ -235,7 +241,7 @@ function findIllegalControlChar(id) {
     }
     return undefined;
 }
-function validateIdSurface(id) {
+function validateInstructionIdSurface(id) {
     if (typeof id !== 'string' || !id.trim())
         return ['id: missing required field'];
     const illegal = findIllegalControlChar(id);
@@ -248,8 +254,48 @@ function validateIdSurface(id) {
     if (id.includes('..') || id.includes('/') || id.includes('\\') || /[:*?"<>|]/.test(id)) {
         return ['id: must be a safe instruction id without path traversal or path separators'];
     }
+    if (!exports.INSTRUCTION_ID_PATTERN.test(id)) {
+        return ['id: must match /^[a-z0-9](?:[a-z0-9-_]{0,118}[a-z0-9])?$/ using lower-case ASCII letters, digits, hyphen, or underscore'];
+    }
     return [];
 }
+// Enum membership checks for governance fields. These run at input-surface time so that
+// invalid enum values are rejected early, before applyWriteCompatibility can silently
+// coerce them (e.g. status:"active" → "approved", audience:"agents" → "group").
+// However, values that ARE coercible by applyWriteCompatibility are accepted here to
+// avoid rejecting inputs that would otherwise succeed after coercion.
+const VALID_STATUS = ['approved', 'draft', 'review', 'deprecated'];
+const COERCIBLE_STATUS = ['active'];
+const VALID_PRIORITY_TIER = ['P1', 'P2', 'P3', 'P4'];
+const VALID_CLASSIFICATION = ['public', 'internal', 'restricted'];
+const VALID_CONTENT_TYPE = ['instruction', 'template', 'workflow', 'reference', 'example', 'agent'];
+const COERCIBLE_CONTENT_TYPE = ['chat-session'];
+const VALID_AUDIENCE = ['individual', 'group', 'all'];
+const COERCIBLE_AUDIENCE = ['system', 'developers', 'developer', 'team', 'teams', 'users', 'dev', 'devs', 'testers', 'administrators', 'admins', 'agents', 'powershell script authors'];
+const VALID_REQUIREMENT = ['mandatory', 'critical', 'recommended', 'optional', 'deprecated'];
+const COERCIBLE_REQUIREMENT = ['MUST', 'SHOULD', 'MAY', 'CRITICAL', 'OPTIONAL', 'MANDATORY', 'DEPRECATED'];
+function validateInstructionInputEnumMembership(entry) {
+    const errs = [];
+    if (typeof entry.status === 'string' && !VALID_STATUS.includes(entry.status) && !COERCIBLE_STATUS.includes(entry.status)) {
+        errs.push(`/status: must be one of ${VALID_STATUS.join(', ')}`);
+    }
+    if (typeof entry.priorityTier === 'string' && !VALID_PRIORITY_TIER.includes(entry.priorityTier)) {
+        errs.push(`/priorityTier: must be one of ${VALID_PRIORITY_TIER.join(', ')}`);
+    }
+    if (typeof entry.classification === 'string' && !VALID_CLASSIFICATION.includes(entry.classification)) {
+        errs.push(`/classification: must be one of ${VALID_CLASSIFICATION.join(', ')}`);
+    }
+    if (typeof entry.contentType === 'string' && !VALID_CONTENT_TYPE.includes(entry.contentType) && !COERCIBLE_CONTENT_TYPE.includes(entry.contentType)) {
+        errs.push(`/contentType: must be one of ${VALID_CONTENT_TYPE.join(', ')}`);
+    }
+    if (typeof entry.audience === 'string' && !VALID_AUDIENCE.includes(entry.audience) && !COERCIBLE_AUDIENCE.includes(entry.audience.toLowerCase())) {
+        errs.push(`/audience: must be one of ${VALID_AUDIENCE.join(', ')}`);
+    }
+    if (typeof entry.requirement === 'string' && !VALID_REQUIREMENT.includes(entry.requirement) && !COERCIBLE_REQUIREMENT.includes(entry.requirement.toUpperCase())) {
+        errs.push(`/requirement: must be one of ${VALID_REQUIREMENT.join(', ')}`);
+    }
+    return errs;
+}
 // Typed-field shape checks. These run for both strict and lax callers so that lax mode
 // fills defaults for *missing* fields but never silently coerces wrong-typed inputs.
 function validateTypedInputShape(entry) {
@@ -257,9 +303,22 @@ function validateTypedInputShape(entry) {
     if (entry.priority !== undefined && typeof entry.priority !== 'number') {
         errs.push(`/priority: must be a number, received ${typeof entry.priority}`);
     }
+    else if (typeof entry.priority === 'number' && (!Number.isInteger(entry.priority) || entry.priority < 1 || entry.priority > 100)) {
+        errs.push('/priority: must be an integer from 1 to 100');
+    }
     if (entry.categories !== undefined && !Array.isArray(entry.categories)) {
         errs.push(`/categories: must be an array of strings, received ${typeof entry.categories}`);
     }
+    else if (Array.isArray(entry.categories)) {
+        for (const [index, category] of entry.categories.entries()) {
+            if (typeof category !== 'string') {
+                errs.push(`/categories/${index}: must be a string, received ${typeof category}`);
+            }
+            else if (!/^[a-z0-9][a-z0-9-_]{0,48}$/.test(category.toLowerCase())) {
+                errs.push(`/categories/${index}: must match /^[a-z0-9][a-z0-9-_]{0,48}$/`);
+            }
+        }
+    }
     if (entry.audience !== undefined && typeof entry.audience !== 'string') {
         errs.push(`/audience: must be a string, received ${typeof entry.audience}`);
     }
@@ -282,7 +341,7 @@ function validateTypedInputShape(entry) {
 }
 function validateInstructionInputSurface(entry) {
     const validationErrors = [];
-    validationErrors.push(...validateIdSurface(entry.id));
+    validationErrors.push(...validateInstructionIdSurface(entry.id));
     for (const key of Object.keys(entry)) {
         if (!ALLOWED_INPUT_KEYS.has(key)) {
             validationErrors.push(`/: unexpected property "${key}"`);
@@ -292,6 +351,7 @@ function validateInstructionInputSurface(entry) {
             validationErrors.push(`/${key}: null is not allowed`);
     }
     validationErrors.push(...validateTypedInputShape(entry));
+    validationErrors.push(...validateInstructionInputEnumMembership(entry));
     return {
         record: entry,
         validationErrors: dedupe(validationErrors),
@@ -311,7 +371,7 @@ function validateInstructionRecord(entry) {
     if (record.classification !== undefined && !['public', 'internal', 'restricted'].includes(record.classification)) {
         validationErrors.push(`/classification: invalid value "${String(record.classification)}"`);
     }
-    if (record.contentType !== undefined && !['instruction', 'template', 'chat-session', 'reference', 'example', 'agent'].includes(record.contentType)) {
+    if (record.contentType !== undefined && !['instruction', 'template', 'workflow', 'reference', 'example', 'agent'].includes(record.contentType)) {
         validationErrors.push(`/contentType: invalid value "${String(record.contentType)}"`);
     }
     if (!validateInstructionSchema(record)) {

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

@@ -162,7 +162,7 @@ For full configuration options: see \`docs/mcp_configuration.md\` and \`docs/con
             categories: ['bootstrap', 'mcp-activation', 'quick-start', 'documentation'],
             owner: 'system',
             version: 3,
-            schemaVersion: '4',
+            schemaVersion: '5',
             semanticSummary: 'Index Server quick start: search-first workflow, knowledge contribution, copilot instructions setup, and MCP client configuration for AI agents'
         }
     },
@@ -179,7 +179,7 @@ For full configuration options: see \`docs/mcp_configuration.md\` and \`docs/con
             categories: ['bootstrap', 'lifecycle'],
             owner: 'system',
             version: 1,
-            schemaVersion: '4',
+            schemaVersion: '5',
             semanticSummary: 'Lifecycle and promotion guardrails after bootstrap confirmation',
             reviewIntervalDays: 120
         }
@@ -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/toolRegistry.js

@@ -94,7 +94,7 @@ const INPUT_SCHEMAS = {
             keywords: { type: 'array', items: { type: 'string' }, description: 'Explicit keyword array for search action when the caller wants direct token control.' },
             ids: { type: 'array', items: { type: 'string' }, description: 'Array of instruction IDs for remove or export actions.' },
             category: { type: 'string', description: 'Filter by category for list action.' },
-            contentType: { type: 'string', enum: ['instruction', 'template', 'chat-session', 'reference', 'example', 'agent'], description: 'Filter by content type for list, search, or query actions, or specify the entry content type for add action.' },
+            contentType: { type: 'string', enum: ['instruction', 'template', 'workflow', 'reference', 'example', 'agent', 'chat-session'], description: 'Filter by content type for list, search, or query actions, or specify the entry content type for add action. Legacy "chat-session" write inputs are migrated to "workflow".' },
             text: { type: 'string', description: 'Full-text search within query action.' },
             includeCategories: { type: 'boolean', description: 'Search categories in addition to id/title/semanticSummary/body for search action.' },
             caseSensitive: { type: 'boolean', description: 'Enable case-sensitive matching for search action.' },
@@ -148,7 +148,7 @@ const INPUT_SCHEMAS = {
     'index_import': { type: 'object', additionalProperties: false, properties: {
             entries: { oneOf: [
                     { type: 'array', minItems: 1, items: { type: 'object', required: ['id', 'title', 'body', 'priority', 'audience', 'requirement'], additionalProperties: false, properties: {
-                                id: { type: 'string' }, title: { type: 'string' }, body: { type: 'string' }, rationale: { type: 'string' }, priority: { type: 'number' }, audience: { type: 'string' }, requirement: { type: 'string' }, categories: { type: 'array', items: { type: 'string' } }, version: { type: 'string' }, owner: { type: 'string' }, status: { type: 'string', enum: ['approved', 'draft', 'review', 'deprecated'] }, priorityTier: { type: 'string', enum: ['P1', 'P2', 'P3', 'P4'] }, classification: { type: 'string', enum: ['public', 'internal', 'restricted'] }, lastReviewedAt: { type: 'string' }, nextReviewDue: { type: 'string' }, semanticSummary: { type: 'string' }, changeLog: { type: 'array', items: { type: 'object', additionalProperties: true } }, contentType: { type: 'string', enum: ['instruction', 'template', 'chat-session', 'reference', 'example', 'agent'] }, extensions: extensionsInputSchema, mode: { type: 'string' }
+                                id: { type: 'string' }, title: { type: 'string' }, body: { type: 'string' }, rationale: { type: 'string' }, priority: { type: 'number' }, audience: { type: 'string' }, requirement: { type: 'string' }, categories: { type: 'array', items: { type: 'string' } }, version: { type: 'string' }, owner: { type: 'string' }, status: { type: 'string', enum: ['approved', 'draft', 'review', 'deprecated'] }, priorityTier: { type: 'string', enum: ['P1', 'P2', 'P3', 'P4'] }, classification: { type: 'string', enum: ['public', 'internal', 'restricted'] }, lastReviewedAt: { type: 'string' }, nextReviewDue: { type: 'string' }, semanticSummary: { type: 'string' }, changeLog: { type: 'array', items: { type: 'object', additionalProperties: true } }, contentType: { type: 'string', enum: ['instruction', 'template', 'workflow', 'reference', 'example', 'agent', 'chat-session'] }, extensions: extensionsInputSchema, mode: { type: 'string' }
                             } } },
                     { type: 'string', description: 'Stringified JSON array of instruction entries, or a file path to a JSON array of instruction entries' }
                 ] },
@@ -157,7 +157,7 @@ const INPUT_SCHEMAS = {
         } },
     'index_add': { type: 'object', additionalProperties: false, required: ['entry'], properties: {
             entry: { type: 'object', required: ['id', 'body'], additionalProperties: false, properties: {
-                    id: { type: 'string', maxLength: 120 }, title: { type: 'string' }, body: { type: 'string' }, rationale: { type: 'string' }, priority: { type: 'number' }, audience: { type: 'string' }, requirement: { type: 'string' }, categories: { type: 'array', items: { type: 'string' } }, deprecatedBy: { type: 'string' }, riskScore: { type: 'number' }, version: { type: 'string' }, owner: { type: 'string' }, status: { type: 'string', enum: ['approved', 'draft', 'review', 'deprecated'] }, priorityTier: { type: 'string', enum: ['P1', 'P2', 'P3', 'P4'] }, classification: { type: 'string', enum: ['public', 'internal', 'restricted'] }, lastReviewedAt: { type: 'string' }, nextReviewDue: { type: 'string' }, semanticSummary: { type: 'string' }, changeLog: { type: 'array', items: { type: 'object', additionalProperties: true } }, contentType: { type: 'string', enum: ['instruction', 'template', 'chat-session', 'reference', 'example', 'agent'] }, extensions: extensionsInputSchema
+                    id: { type: 'string', minLength: 1, maxLength: 120, pattern: '^[a-z0-9](?:[a-z0-9-_]{0,118}[a-z0-9])?$' }, title: { type: 'string' }, body: { type: 'string' }, rationale: { type: 'string' }, priority: { type: 'number', minimum: 1, maximum: 100 }, audience: { type: 'string', enum: ['individual', 'group', 'all'] }, requirement: { type: 'string', enum: ['mandatory', 'critical', 'recommended', 'optional', 'deprecated'] }, categories: { type: 'array', items: { type: 'string', pattern: '^[a-z0-9][a-z0-9-_]{0,48}$' } }, deprecatedBy: { type: 'string' }, riskScore: { type: 'number' }, version: { type: 'string' }, owner: { type: 'string' }, status: { type: 'string', enum: ['approved', 'draft', 'review', 'deprecated'] }, priorityTier: { type: 'string', enum: ['P1', 'P2', 'P3', 'P4'] }, classification: { type: 'string', enum: ['public', 'internal', 'restricted'] }, lastReviewedAt: { type: 'string' }, nextReviewDue: { type: 'string' }, semanticSummary: { type: 'string' }, changeLog: { type: 'array', items: { type: 'object', additionalProperties: true } }, contentType: { type: 'string', enum: ['instruction', 'template', 'workflow', 'reference', 'example', 'agent', 'chat-session'] }, extensions: extensionsInputSchema
                 } },
             overwrite: { type: 'boolean' },
             lax: { type: 'boolean' }
@@ -221,7 +221,7 @@ const INPUT_SCHEMAS = {
             limit: { type: 'number', minimum: 1, maximum: 100, default: 50, description: 'Maximum number of instruction IDs to return' },
             includeCategories: { type: 'boolean', default: false, description: 'Include categories in search scope' },
             caseSensitive: { type: 'boolean', default: false, description: 'Perform case-sensitive matching' },
-            contentType: { type: 'string', enum: ['instruction', 'template', 'chat-session', 'reference', 'example', 'agent'], description: 'Filter results by content type (optional)' }
+            contentType: { type: 'string', enum: ['instruction', 'template', 'workflow', 'reference', 'example', 'agent'], description: 'Filter results by content type (optional)' }
         } },
     // promote_from_repo tool
     'promote_from_repo': { type: 'object', additionalProperties: false, required: ['repoPath'], properties: {
@@ -321,15 +321,16 @@ INPUT_SCHEMAS['trace_dump'] = { type: 'object', additionalProperties: false, pro
         file: { type: 'string', description: 'Optional path to write the trace buffer JSON file' }
     } };
 // Stable & mutation classification lists (mirrors usage in toolHandlers; exported to remove duplication there).
-exports.STABLE = new Set(['health_check', 'graph_export', 'index_dispatch', 'index_search', 'index_governanceHash', 'prompt_review', 'integrity_verify', 'usage_track', 'usage_hotset', 'metrics_snapshot', 'gates_evaluate', 'meta_tools', 'help_overview', 'index_schema', 'manifest_status', 'index_diagnostics', 'meta_activation_guide', 'meta_check_activation', 'bootstrap', 'bootstrap_status', 'feature_status', 'index_health', 'index_inspect', 'index_debug', 'integrity_manifest', 'messaging_read', 'messaging_list_channels', 'messaging_stats', 'messaging_get', 'messaging_thread', 'trace_dump']);
-exports.MUTATION = new Set(['index_add', 'index_import', 'index_repair', 'index_reload', 'index_remove', 'index_groom', 'index_enrich', 'index_governanceUpdate', 'index_normalize', 'usage_flush', 'feedback_submit', 'manifest_refresh', 'manifest_repair', 'promote_from_repo', 'bootstrap_request', 'bootstrap_confirmFinalize', 'messaging_send', 'messaging_ack', 'messaging_update', 'messaging_purge', 'messaging_reply', 'diagnostics_block', 'diagnostics_microtaskFlood', 'diagnostics_memoryPressure']);
+exports.STABLE = new Set(['health_check', 'feedback_submit', 'graph_export', 'index_dispatch', 'index_search', 'index_governanceHash', 'prompt_review', 'integrity_verify', 'usage_track', 'usage_hotset', 'metrics_snapshot', 'gates_evaluate', 'meta_tools', 'help_overview', 'index_schema', 'manifest_status', 'index_diagnostics', 'meta_activation_guide', 'meta_check_activation', 'bootstrap', 'bootstrap_status', 'feature_status', 'index_health', 'index_inspect', 'index_debug', 'integrity_manifest', 'messaging_read', 'messaging_list_channels', 'messaging_stats', 'messaging_get', 'messaging_thread', 'trace_dump']);
+exports.MUTATION = new Set(['index_add', 'index_import', 'index_repair', 'index_reload', 'index_remove', 'index_groom', 'index_enrich', 'index_governanceUpdate', 'index_normalize', 'usage_flush', 'manifest_refresh', 'manifest_repair', 'promote_from_repo', 'bootstrap_request', 'bootstrap_confirmFinalize', 'messaging_send', 'messaging_ack', 'messaging_update', 'messaging_purge', 'messaging_reply', 'diagnostics_block', 'diagnostics_microtaskFlood', 'diagnostics_memoryPressure']);
 // Tool tier classification (002-tool-consolidation spec)
 // core: always visible, essential daily use
 // extended: opt-in via INDEX_SERVER_FLAG_TOOLS_EXTENDED=1 or flags.json tools_extended:true
 // admin: opt-in via INDEX_SERVER_FLAG_TOOLS_ADMIN=1, rarely needed ops/debug tools
 const TOOL_TIERS = {
-    // Core (7 → 6 after feedback_dispatch removal)
+    // Core (7 after feedback_dispatch removal; feedback_submit remains always visible for agent reporting)
     'health_check': 'core',
+    'feedback_submit': 'core',
     'index_dispatch': 'core',
     'index_search': 'core',
     'prompt_review': 'core',
@@ -351,7 +352,6 @@ const TOOL_TIERS = {
     'promote_from_repo': 'extended',
     'index_schema': 'extended',
     // Admin (everything else)
-    'feedback_submit': 'admin',
     'meta_tools': 'admin',
     'meta_activation_guide': 'admin',
     'meta_check_activation': 'admin',

package/dist/services/toolRegistry.zod.js

@@ -35,7 +35,7 @@ const zDispatch = zod_1.z.object({
     keywords: zod_1.z.array(zod_1.z.string()).optional(),
     ids: zod_1.z.array(zod_1.z.string()).optional(),
     category: zod_1.z.string().optional(),
-    contentType: zod_1.z.enum(['instruction', 'template', 'chat-session', 'reference', 'example', 'agent']).optional(),
+    contentType: zod_1.z.enum(['instruction', 'template', 'workflow', 'reference', 'example', 'agent', 'chat-session']).optional(),
     text: zod_1.z.string().optional(),
     includeCategories: zod_1.z.boolean().optional(),
     caseSensitive: zod_1.z.boolean().optional(),
@@ -98,7 +98,7 @@ function buildZIndexEntry() {
         nextReviewDue: zod_1.z.string().optional(),
         semanticSummary: zod_1.z.string().optional(),
         changeLog: zod_1.z.array(zod_1.z.object({}).passthrough()).optional(),
-        contentType: zod_1.z.enum(['instruction', 'template', 'chat-session', 'reference', 'example', 'agent']).optional(),
+        contentType: zod_1.z.enum(['instruction', 'template', 'workflow', 'reference', 'example', 'agent', 'chat-session']).optional(),
         extensions: zod_1.z.record(zod_1.z.string(), zExtensionValue).optional()
     }).strict();
 }
@@ -166,7 +166,7 @@ const zSearch = zod_1.z.object({
     limit: zod_1.z.number().int().min(1).max(100).default(50).optional(),
     includeCategories: zod_1.z.boolean().default(false).optional(),
     caseSensitive: zod_1.z.boolean().default(false).optional(),
-    contentType: zod_1.z.enum(['instruction', 'template', 'chat-session', 'reference', 'example', 'agent']).optional()
+    contentType: zod_1.z.enum(['instruction', 'template', 'workflow', 'reference', 'example', 'agent']).optional()
 }).strict();
 // ── Diagnostics ──────────────────────────────────────────────────────────────
 const zDiagnostics = zod_1.z.object({

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))