@jagilber-org/index-server 1.22.0 → 1.26.1

package/dist/services/handlers.graph.js

@@ -18,6 +18,7 @@ exports.__resetGraphCache = __resetGraphCache;
 const registry_1 = require("../server/registry");
 const indexContext_1 = require("./indexContext");
 const runtimeConfig_1 = require("../config/runtimeConfig");
+const logger_js_1 = require("./logger.js");
 // NOTE: For enriched responses we bump schema version to 2 (only when enrich=true)
 const GRAPH_SCHEMA_VERSION_V1 = 1;
 const GRAPH_SCHEMA_VERSION_V2 = 2;
@@ -216,8 +217,7 @@ function buildGraph(params, graphCfg = (0, runtimeConfig_1.getRuntimeConfig)().g
     const graph = buildGraph(p, graphCfg);
     // Defensive: unexpected undefined safeguard (should never happen). Emit diagnostic once.
     if (!graph) {
-        // eslint-disable-next-line no-console
-        console.error('[graph_export] buildGraph returned undefined - returning empty graph (diagnostic)');
+        (0, logger_js_1.logError)('[graph_export] buildGraph returned undefined - returning empty graph (diagnostic)');
         return { meta: { graphSchemaVersion: 1, nodeCount: 0, edgeCount: 0 }, nodes: [], edges: [] };
     }
     if (cacheEligible && !envExplicit) {

package/dist/services/handlers.help.js

@@ -7,7 +7,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
  * onboarding guidance so a naive / first-time agent can self-bootstrap:
  * - Discover tools & their purpose
  * - Understand local (P0) vs indexed (P1+) lifecycle & promotion workflow
- * - Learn safe mutation enabling pattern (INDEX_SERVER_MUTATION)
+ * - Learn safe mutation override pattern (INDEX_SERVER_MUTATION)
  * - Follow a deterministic promotion checklist
  * - Avoid governance/spec recursion (documents intentionally NOT ingested)
  */
@@ -64,7 +64,7 @@ function buildSections() {
         {
             id: 'mutation-safety',
             title: 'Safe Mutation',
-            content: 'All write operations require INDEX_SERVER_MUTATION=1. Without it, mutation tools return disabled errors ensuring read-only safety by default.'
+            content: 'Write operations are enabled by default, but bootstrap confirmation and reference mode still gate risky changes. Set INDEX_SERVER_MUTATION=0 when you need an explicit read-only runtime.'
         },
         {
             id: 'recursion-safeguards',

package/dist/services/handlers.instructionSchema.js

@@ -48,6 +48,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 const registry_1 = require("../server/registry");
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
+const runtimeConfig_1 = require("../config/runtimeConfig");
 const SCHEMA_VERSION = '1.0.0';
 /**
  * Load the canonical instruction.schema.json from disk
@@ -158,11 +159,12 @@ function definePromotionWorkflow() {
  * Define key validation rules
  */
 function defineValidationRules() {
+    const bodyWarnLength = (0, runtimeConfig_1.getRuntimeConfig)().index.bodyWarnLength.toLocaleString('en-US');
     return [
         { field: 'id', rule: 'Pattern', constraint: '^[a-z0-9](?:[a-z0-9-_]{0,118}[a-z0-9])?$ (120 chars max, lowercase, no leading/trailing hyphen/underscore)' },
         { field: 'id', rule: 'Uniqueness', constraint: 'Must be unique across the index' },
         { field: 'title', rule: 'Length', constraint: '1-200 characters, non-empty' },
-        { field: 'body', rule: 'Length', constraint: '1-20,000 characters, markdown supported' },
+        { field: 'body', rule: 'Length', constraint: `1-${bodyWarnLength} characters on add/import writes (INDEX_SERVER_BODY_WARN_LENGTH), markdown supported` },
         { field: 'priority', rule: 'Range', constraint: '1-100 (lower number = higher priority)' },
         { field: 'audience', rule: 'Enum', constraint: 'One of: individual, group, all' },
         { field: 'requirement', rule: 'Enum', constraint: 'One of: mandatory, critical, recommended, optional, deprecated' },
@@ -216,7 +218,7 @@ function defineValidationRules() {
             '1. Review the minimalExample for required fields',
             '2. Study promotionWorkflow stages (P0 → P1 → P2+)',
             '3. Validate against validationRules before submission',
-            '4. Use index_dispatch {action: "add"} to create (requires INDEX_SERVER_MUTATION=1)',
+            '4. Use index_dispatch {action: "add"} to create (writes are enabled by default; set INDEX_SERVER_MUTATION=0 for read-only mode)',
             '5. Monitor index_health for recursionRisk and drift',
             '6. Track usage with usage_track',
             '7. Iterate via index_dispatch {action: "update"} as needed',

package/dist/services/handlers.integrity.js

@@ -9,27 +9,47 @@ const path_1 = __importDefault(require("path"));
 const registry_1 = require("../server/registry");
 const indexContext_1 = require("./indexContext");
 const features_1 = require("./features");
-(0, registry_1.registerHandler)('integrity_verify', () => { const st = (0, indexContext_1.ensureLoaded)(); const issues = []; for (const e of st.list) {
-    const actual = crypto_1.default.createHash('sha256').update(e.body, 'utf8').digest('hex');
-    if (actual !== e.sourceHash)
-        issues.push({ id: e.id, expected: e.sourceHash, actual });
-} return { hash: st.hash, count: st.list.length, issues, issueCount: issues.length }; });
-(0, registry_1.registerHandler)('integrity_manifest', () => { const manifestPath = path_1.default.join(process.cwd(), 'snapshots', 'index-manifest.json'); if (!fs_1.default.existsSync(manifestPath))
-    return { manifest: 'missing' }; let manifest; try {
-    manifest = JSON.parse(fs_1.default.readFileSync(manifestPath, 'utf8'));
-}
-catch (e) {
-    return { manifest: 'invalid', error: e instanceof Error ? e.message : String(e) };
-} const entries = Array.isArray(manifest.entries) ? manifest.entries : []; const map = new Map(entries.map(e => [e.id, e])); const st = (0, indexContext_1.ensureLoaded)(); const drift = []; for (const e of st.list) {
-    const entry = map.get(e.id);
-    const bodyHash = crypto_1.default.createHash('sha256').update(e.body, 'utf8').digest('hex');
-    if (!entry)
-        drift.push({ id: e.id, change: 'added' });
-    else if (entry.sourceHash !== e.sourceHash || entry.bodyHash !== bodyHash)
-        drift.push({ id: e.id, change: 'hash-mismatch' });
-} for (const id of map.keys()) {
-    if (!st.byId.has(id))
-        drift.push({ id, change: 'removed' });
-} return { manifest: 'present', drift: drift.length, details: drift }; });
+(0, registry_1.registerHandler)('integrity_verify', () => {
+    const st = (0, indexContext_1.ensureLoaded)();
+    const issues = [];
+    for (const e of st.list) {
+        const actual = crypto_1.default.createHash('sha256').update(e.body, 'utf8').digest('hex');
+        if (actual !== e.sourceHash) {
+            issues.push({ id: e.id, expected: e.sourceHash, actual });
+        }
+    }
+    return { hash: st.hash, count: st.list.length, issues, issueCount: issues.length };
+});
+(0, registry_1.registerHandler)('integrity_manifest', () => {
+    const manifestPath = path_1.default.join(process.cwd(), 'snapshots', 'index-manifest.json');
+    if (!fs_1.default.existsSync(manifestPath))
+        return { manifest: 'missing' };
+    let manifest;
+    try {
+        manifest = JSON.parse(fs_1.default.readFileSync(manifestPath, 'utf8'));
+    }
+    catch (e) {
+        return { manifest: 'invalid', error: e instanceof Error ? e.message : String(e) };
+    }
+    const entries = Array.isArray(manifest.entries) ? manifest.entries : [];
+    const map = new Map(entries.map(e => [e.id, e]));
+    const st = (0, indexContext_1.ensureLoaded)();
+    const drift = [];
+    for (const e of st.list) {
+        const entry = map.get(e.id);
+        const bodyHash = crypto_1.default.createHash('sha256').update(e.body, 'utf8').digest('hex');
+        if (!entry) {
+            drift.push({ id: e.id, change: 'added' });
+        }
+        else if (entry.sourceHash !== e.sourceHash || entry.bodyHash !== bodyHash) {
+            drift.push({ id: e.id, change: 'hash-mismatch' });
+        }
+    }
+    for (const id of map.keys()) {
+        if (!st.byId.has(id))
+            drift.push({ id, change: 'removed' });
+    }
+    return { manifest: 'present', drift: drift.length, details: drift };
+});
 // Phase 0: feature flags status
 (0, registry_1.registerHandler)('feature_status', () => (0, features_1.featureStatus)());

package/dist/services/handlers.messaging.js

@@ -138,7 +138,7 @@ function _resetMailbox() {
 (0, registry_1.registerHandler)('messaging_purge', (params = {}) => {
     const mailbox = getMailbox();
     let removed;
-    let action = 'purge_all';
+    let action;
     if (params.all) {
         removed = mailbox.purgeAll();
         action = 'purge_all';

package/dist/services/handlers.metrics.js

@@ -10,7 +10,22 @@ const InstanceManager_1 = require("../dashboard/server/InstanceManager");
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
 const validationService_1 = require("./validationService");
-(0, registry_1.registerHandler)('metrics_snapshot', () => { const raw = (0, registry_1.getMetricsRaw)(); const methods = Object.entries(raw).map(([method, rec]) => ({ method, count: rec.count, avgMs: rec.count ? +(rec.totalMs / rec.count).toFixed(2) : 0, maxMs: +rec.maxMs.toFixed(2) })).sort((a, b) => a.method.localeCompare(b.method)); const features = (0, features_1.featureStatus)(); const validation = (0, validationService_1.getValidationMetrics)(); return { generatedAt: new Date().toISOString(), methods, features, validation }; });
+const auditLog_1 = require("./auditLog");
+const features_2 = require("./features");
+(0, registry_1.registerHandler)('metrics_snapshot', () => {
+    const raw = (0, registry_1.getMetricsRaw)();
+    const methods = Object.entries(raw)
+        .map(([method, rec]) => ({
+        method,
+        count: rec.count,
+        avgMs: rec.count ? +(rec.totalMs / rec.count).toFixed(2) : 0,
+        maxMs: +rec.maxMs.toFixed(2),
+    }))
+        .sort((a, b) => a.method.localeCompare(b.method));
+    const features = (0, features_1.featureStatus)();
+    const validation = (0, validationService_1.getValidationMetrics)();
+    return { generatedAt: new Date().toISOString(), methods, features, validation };
+});
 // health_check retained here (meta_tools provided by shim for rich output)
 // Resolve version locally (mirrors transport logic) to avoid import cycles
 let VERSION = '0.0.0';
@@ -23,21 +38,51 @@ try {
     }
 }
 catch { /* ignore */ }
-(0, registry_1.registerHandler)('health_check', () => {
+(0, registry_1.registerHandler)('health_check', async () => {
     let summary;
     try {
-        const st = (0, indexContext_1.getIndexState)();
+        const st = await (0, indexContext_1.getIndexStateAsync)();
         if (st.loadSummary) {
             const s = st.loadSummary;
-            summary = { scanned: s.scanned, accepted: s.accepted, skipped: s.skipped, reasons: s.reasons, salvage: s.salvage, softWarnings: s.softWarnings };
+            summary = {
+                scanned: s.scanned,
+                accepted: s.accepted,
+                skipped: s.skipped,
+                reasons: s.reasons,
+                salvage: s.salvage,
+                softWarnings: s.softWarnings,
+            };
         }
     }
     catch { /* swallow to keep health resilient */ }
     // Instance discovery — resilient: never fail health due to port-file read errors
     let instances = [];
     try {
-        instances = (0, InstanceManager_1.getActiveInstances)().map(i => ({ pid: i.pid, port: i.port, host: i.host, startedAt: i.startedAt, current: i.current }));
+        instances = (0, InstanceManager_1.getActiveInstances)().map(i => ({
+            pid: i.pid,
+            port: i.port,
+            host: i.host,
+            startedAt: i.startedAt,
+            current: i.current,
+        }));
     }
     catch { /* swallow */ }
-    return { status: 'ok', timestamp: new Date().toISOString(), version: VERSION, pid: process.pid, uptime: Math.round(process.uptime()), index: summary, instances };
+    // Expose usage invariant repair counters so operators can see silent data reconstruction
+    const allCounters = (0, features_2.getCounters)();
+    const repairCounters = {};
+    for (const [key, val] of Object.entries(allCounters)) {
+        if (key.startsWith('usage:') && val > 0)
+            repairCounters[key] = val;
+    }
+    return {
+        status: 'ok',
+        timestamp: new Date().toISOString(),
+        version: VERSION,
+        pid: process.pid,
+        uptime: Math.round(process.uptime()),
+        index: summary,
+        instances,
+        audit: (0, auditLog_1.getAuditLogHealth)(),
+        ...(Object.keys(repairCounters).length ? { usageRepairs: repairCounters } : {}),
+    };
 });

package/dist/services/handlers.prompt.js

@@ -3,5 +3,13 @@ Object.defineProperty(exports, "__esModule", { value: true });
 const registry_1 = require("../server/registry");
 const promptReviewService_1 = require("./promptReviewService");
 const promptService = new promptReviewService_1.PromptReviewService();
-(0, registry_1.registerHandler)('prompt_review', (p) => { const raw = p.prompt || ''; const MAX = 10_000; if (raw.length > MAX)
-    return { truncated: true, message: 'prompt too large', max: MAX }; const sanitized = raw.replace(/\0/g, ''); const issues = promptService.review(sanitized); const summary = (0, promptReviewService_1.summarizeIssues)(issues); return { issues, summary, length: sanitized.length }; });
+(0, registry_1.registerHandler)('prompt_review', (p) => {
+    const raw = p.prompt || '';
+    const MAX = 10_000;
+    if (raw.length > MAX)
+        return { truncated: true, message: 'prompt too large', max: MAX };
+    const sanitized = raw.replace(/\0/g, '');
+    const issues = promptService.review(sanitized);
+    const summary = (0, promptReviewService_1.summarizeIssues)(issues);
+    return { issues, summary, length: sanitized.length };
+});

package/dist/services/handlers.search.js

@@ -19,6 +19,9 @@
  * - Proper tool registration
  * - Input sanitization and limits
  */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.handleInstructionsSearch = handleInstructionsSearch;
 exports.buildAfterRetrievalMeta = buildAfterRetrievalMeta;
@@ -28,6 +31,7 @@ const indexContext_1 = require("./indexContext");
 const errors_1 = require("./errors");
 const runtimeConfig_1 = require("../config/runtimeConfig");
 const embeddingService_1 = require("./embeddingService");
+const safe_regex2_1 = __importDefault(require("safe-regex2"));
 const SEARCH_SCHEMA = {
     type: 'object',
     required: ['keywords'],
@@ -42,6 +46,7 @@ const SEARCH_SCHEMA = {
     example: { keywords: ['build', 'validate', 'discipline'], limit: 10, includeCategories: true }
 };
 const VALID_MODES = ['keyword', 'regex', 'semantic'];
+const MAX_REGEX_PATTERN_LENGTH = 200;
 function normalizeSearchText(text, caseSensitive) {
     const normalized = text
         .normalize('NFD')
@@ -123,18 +128,32 @@ function buildKeywordSearchContext(instructions, keywords, caseSensitive, includ
 /**
  * Calculate relevance score for an instruction based on keyword matches
  */
-function calculateRelevance(instruction, keywords, caseSensitive, includeCategories, mode = 'keyword', keywordContext) {
+function calculateRelevance(instruction, keywords, caseSensitive, includeCategories, mode = 'keyword', keywordContext, regexKeywords) {
     let score = 0;
     const matchedFieldSet = new Set();
     const prepareText = (text) => caseSensitive ? text : text.toLowerCase();
     const preparedKeywords = keywords.map(k => mode === 'keyword' ? prepareText(k) : k);
     const regexFlags = caseSensitive ? 'g' : 'gi';
+    const compiledRegexKeywords = mode === 'regex'
+        ? (regexKeywords ?? keywords.map((keyword) => {
+            // Defense-in-depth: production callers route through compileRegexKeywords →
+            // validateRegexKeyword. Re-validate here in the fallback path so direct
+            // invocations (tests, future handlers) cannot bypass ReDoS / unsupported-
+            // construct rejection. Throws on invalid pattern.
+            return {
+                source: keyword,
+                testRegex: compileSafeUserRegex(keyword, caseSensitive ? '' : 'i'),
+                countRegex: compileSafeUserRegex(keyword, regexFlags),
+            };
+        }))
+        : [];
     // Build matchers: regex mode uses raw patterns, keyword mode uses substring/escaped regex
     const testMatch = (text, keyword) => {
         if (mode === 'regex') {
             try {
-                // Regex patterns are pre-validated in the handler; try-catch is defense-in-depth
-                return new RegExp(keyword, caseSensitive ? '' : 'i').test(text); // lgtm[js/regex-injection] — patterns pre-validated at handler entry
+                const compiled = keyword;
+                compiled.testRegex.lastIndex = 0;
+                return compiled.testRegex.test(text); // lgtm[js/regex-injection] — patterns pre-validated and pre-compiled at handler entry
             }
             catch {
                 return false;
@@ -228,7 +247,9 @@ function calculateRelevance(instruction, keywords, caseSensitive, includeCategor
     const countMatches = (text, keyword) => {
         if (mode === 'regex') {
             try {
-                return (text.match(new RegExp(keyword, regexFlags)) || []).length; // lgtm[js/regex-injection] — patterns pre-validated at handler entry
+                const compiled = keyword;
+                compiled.countRegex.lastIndex = 0;
+                return (text.match(compiled.countRegex) || []).length; // lgtm[js/regex-injection] — patterns pre-validated and pre-compiled at handler entry
             }
             catch {
                 return 0;
@@ -237,7 +258,7 @@ function calculateRelevance(instruction, keywords, caseSensitive, includeCategor
         return (text.match(new RegExp(escapeRegex(keyword), regexFlags)) || []).length;
     };
     let idMatches = 0;
-    for (const keyword of preparedKeywords) {
+    for (const keyword of mode === 'regex' ? compiledRegexKeywords : preparedKeywords) {
         if (testMatch(instruction.id, keyword)) {
             idMatches += countMatches(instruction.id, keyword);
         }
@@ -247,7 +268,7 @@ function calculateRelevance(instruction, keywords, caseSensitive, includeCategor
         matchedFieldSet.add('id');
     }
     let titleMatches = 0;
-    for (const keyword of preparedKeywords) {
+    for (const keyword of mode === 'regex' ? compiledRegexKeywords : preparedKeywords) {
         titleMatches += countMatches(instruction.title, keyword);
     }
     if (titleMatches > 0) {
@@ -255,7 +276,7 @@ function calculateRelevance(instruction, keywords, caseSensitive, includeCategor
         matchedFieldSet.add('title');
     }
     let summaryMatches = 0;
-    for (const keyword of preparedKeywords) {
+    for (const keyword of mode === 'regex' ? compiledRegexKeywords : preparedKeywords) {
         summaryMatches += countMatches(instruction.semanticSummary || '', keyword);
     }
     if (summaryMatches > 0) {
@@ -263,7 +284,7 @@ function calculateRelevance(instruction, keywords, caseSensitive, includeCategor
         matchedFieldSet.add('semanticSummary');
     }
     let bodyMatches = 0;
-    for (const keyword of preparedKeywords) {
+    for (const keyword of mode === 'regex' ? compiledRegexKeywords : preparedKeywords) {
         bodyMatches += countMatches(instruction.body, keyword);
     }
     if (bodyMatches > 0) {
@@ -273,7 +294,7 @@ function calculateRelevance(instruction, keywords, caseSensitive, includeCategor
     if (includeCategories && instruction.categories?.length) {
         const categoryText = instruction.categories.join(' ');
         let categoryMatches = 0;
-        for (const keyword of preparedKeywords) {
+        for (const keyword of mode === 'regex' ? compiledRegexKeywords : preparedKeywords) {
             categoryMatches += countMatches(categoryText, keyword);
         }
         if (categoryMatches > 0) {
@@ -282,13 +303,14 @@ function calculateRelevance(instruction, keywords, caseSensitive, includeCategor
         }
     }
     const uniqueMatches = new Set();
-    for (const keyword of preparedKeywords) {
+    for (const keyword of mode === 'regex' ? compiledRegexKeywords : preparedKeywords) {
+        const keywordSource = mode === 'regex' ? keyword.source : keyword;
         if (testMatch(instruction.id, keyword) ||
             testMatch(instruction.title, keyword) ||
             testMatch(instruction.semanticSummary || '', keyword) ||
             testMatch(instruction.body, keyword) ||
             (includeCategories && instruction.categories?.some((cat) => testMatch(cat, keyword)))) {
-            uniqueMatches.add(keyword);
+            uniqueMatches.add(keywordSource);
         }
     }
     if (uniqueMatches.size > 1) {
@@ -302,6 +324,58 @@ function calculateRelevance(instruction, keywords, caseSensitive, includeCategor
 function escapeRegex(string) {
     return string.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 }
+function sanitizeKeywords(keywords) {
+    return keywords
+        .filter(k => typeof k === 'string' && k.trim().length > 0)
+        .map(k => k.trim())
+        .slice(0, 10);
+}
+function validateRegexKeyword(keyword) {
+    if (keyword.length > MAX_REGEX_PATTERN_LENGTH) {
+        throw new Error(`Regex patterns must not exceed ${MAX_REGEX_PATTERN_LENGTH} characters to prevent ReDoS`);
+    }
+    try {
+        new RegExp(keyword); // lgtm[js/regex-injection] — this IS the syntax validation step
+    }
+    catch {
+        throw new Error(`Invalid regex pattern "${keyword}": check syntax and try again`);
+    }
+    if (/\(\?(?:[=!]|<[=!])/.test(keyword)) {
+        throw new Error('Regex pattern rejected: lookaround assertions are not supported in regex search mode');
+    }
+    if (/\\[1-9]/.test(keyword)) {
+        throw new Error('Regex pattern rejected: backreferences are not supported in regex search mode');
+    }
+    if (/\([^)]*[+*?}]\)[+*?{]/.test(keyword)) {
+        throw new Error('Regex pattern rejected: nested quantifiers can cause catastrophic backtracking');
+    }
+    if (/\)[+*?}][^(]*\)[+*?{]/.test(keyword)) {
+        throw new Error('Regex pattern rejected: nested quantifiers can cause catastrophic backtracking');
+    }
+    if (/\([^)]*\|[^)]*\)[+*?{]/.test(keyword)) {
+        throw new Error('Regex pattern rejected: alternation with quantifiers can cause catastrophic backtracking');
+    }
+    if (!(0, safe_regex2_1.default)(keyword)) {
+        throw new Error('Regex pattern rejected: potentially catastrophic backtracking detected');
+    }
+}
+/**
+ * Compile a user-supplied regex pattern after running ReDoS / unsupported-
+ * construct validation. This is the single trusted construction site for
+ * `new RegExp(<user input>)` in the search pipeline; all callers must route
+ * through here so the validation step is provably adjacent to construction.
+ */
+function compileSafeUserRegex(pattern, flags) {
+    validateRegexKeyword(pattern);
+    return new RegExp(pattern, flags); // lgtm[js/regex-injection] — pattern validated by validateRegexKeyword above
+}
+function compileRegexKeywords(keywords, caseSensitive) {
+    return keywords.map((keyword) => ({
+        source: keyword,
+        testRegex: compileSafeUserRegex(keyword, caseSensitive ? '' : 'i'),
+        countRegex: compileSafeUserRegex(keyword, caseSensitive ? 'g' : 'gi'),
+    }));
+}
 /**
  * Load and search instructions from the index
  */
@@ -325,10 +399,7 @@ function performSearch(params) {
         throw new Error(`Invalid contentType: must be one of ${validContentTypes.join(', ')}`);
     }
     // Validate and sanitize keywords
-    const sanitizedKeywords = keywords
-        .filter(k => typeof k === 'string' && k.trim().length > 0)
-        .map(k => k.trim())
-        .slice(0, 10); // Enforce max 10 keywords
+    const sanitizedKeywords = sanitizeKeywords(keywords);
     if (sanitizedKeywords.length === 0) {
         throw new Error('At least one valid keyword is required');
     }
@@ -351,7 +422,7 @@ function performSearch(params) {
                 continue; // Skip instructions that don't match the contentType filter
             }
         }
-        const { score, matchedFields } = calculateRelevance(instruction, sanitizedKeywords, caseSensitive, includeCategories, mode, keywordContext);
+        const { score, matchedFields } = calculateRelevance(instruction, sanitizedKeywords, caseSensitive, includeCategories, mode, keywordContext, params.compiledRegexKeywords);
         if (score > 0) {
             results.push({
                 instructionId: instruction.id,
@@ -496,33 +567,11 @@ async function handleInstructionsSearch(params) {
             throw new Error(`Invalid mode: must be one of ${VALID_MODES.join(', ')}`);
         }
         (0, logger_1.logInfo)(`[search] Search request: mode=${mode}, keywords=[${params.keywords.join(', ')}], limit=${params.limit ?? 50}, contentType=${params.contentType ?? 'any'}`);
+        const sanitizedKeywords = sanitizeKeywords(params.keywords);
         // Regex mode validation: pattern safety checks
-        if (mode === 'regex') {
-            for (const keyword of params.keywords) {
-                if (keyword.length > 200) {
-                    throw new Error('Regex patterns must not exceed 200 characters to prevent ReDoS');
-                }
-                // Reject patterns with nested quantifiers that cause catastrophic backtracking
-                if (/\([^)]*[+*}]\)[+*{]/.test(keyword)) {
-                    throw new Error('Regex pattern rejected: nested quantifiers can cause catastrophic backtracking');
-                }
-                // Also catch double-nested quantified groups like ((a)+)+ where inner )+
-                // is followed by more chars and another )+
-                if (/\)[+*}][^(]*\)[+*{]/.test(keyword)) {
-                    throw new Error('Regex pattern rejected: nested quantifiers can cause catastrophic backtracking');
-                }
-                // Reject overlapping alternations with quantifiers: (a|a)+
-                if (/\([^)]*\|[^)]*\)[+*]{1,}/.test(keyword)) {
-                    throw new Error('Regex pattern rejected: alternation with quantifiers can cause catastrophic backtracking');
-                }
-                try {
-                    new RegExp(keyword); // lgtm[js/regex-injection] — this IS the validation code
-                }
-                catch {
-                    throw new Error(`Invalid regex pattern "${keyword}": check syntax and try again`);
-                }
-            }
-        }
+        const compiledRegexKeywords = mode === 'regex'
+            ? compileRegexKeywords(sanitizedKeywords, params.caseSensitive ?? false)
+            : undefined;
         // Semantic mode: check feature flag
         if (mode === 'semantic') {
             const cfg = (0, runtimeConfig_1.getRuntimeConfig)().semantic;
@@ -534,12 +583,13 @@ async function handleInstructionsSearch(params) {
         }
         // Ensure case-insensitive search by default
         const searchParams = {
-            keywords: params.keywords,
+            keywords: sanitizedKeywords,
             mode: mode,
             limit: params.limit,
             includeCategories: params.includeCategories,
             caseSensitive: params.caseSensitive ?? false, // Explicit default to false for case-insensitive search
-            contentType: params.contentType
+            contentType: params.contentType,
+            compiledRegexKeywords,
         };
         // Semantic mode: embedding-based similarity search
         if (mode === 'semantic') {

package/dist/services/handlers.trace.js

@@ -30,6 +30,6 @@ const fs_1 = __importDefault(require("fs"));
         if (raw && Array.isArray(raw.records))
             size = raw.records.length;
     }
-    catch { /* ignore */ }
+    catch { /* ignore */ } // lgtm[js/file-system-race] — file path containment to cwd validated above
     return { dumped: true, file, records: size, bytes, env: (0, tracing_1.summarizeTraceEnv)(), bufferEnabled: (0, tracing_1.getTraceBuffer)().length > 0 };
 });

package/dist/services/handlers.usage.js

@@ -2,10 +2,41 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 const registry_1 = require("../server/registry");
 const indexContext_1 = require("./indexContext");
-(0, registry_1.registerHandler)('usage_track', (p) => { if (!p.id)
-    return { error: 'missing id' }; const opts = { action: p.action, signal: p.signal, comment: p.comment }; const r = (0, indexContext_1.incrementUsage)(p.id, opts); if (!r)
-    return { notFound: true }; return r; });
-(0, registry_1.registerHandler)('usage_hotset', (p) => { const st = (0, indexContext_1.ensureLoaded)(); const snap = (0, indexContext_1.loadUsageSnapshot)(); const limit = Math.max(1, Math.min(p.limit ?? 10, 100)); const items = [...st.list].filter(e => (e.usageCount ?? 0) > 0).sort((a, b) => { const ua = a.usageCount ?? 0, ub = b.usageCount ?? 0; if (ub !== ua)
-    return ub - ua; return (b.lastUsedAt || '').localeCompare(a.lastUsedAt || ''); }).slice(0, limit).map(e => { const rec = snap[e.id] || {}; const item = { id: e.id, usageCount: e.usageCount, lastUsedAt: e.lastUsedAt }; if (rec.lastSignal)
-    item.lastSignal = rec.lastSignal; if (rec.lastComment)
-    item.lastComment = rec.lastComment; return item; }); return { hash: st.hash, count: items.length, items, limit }; });
+(0, registry_1.registerHandler)('usage_track', (p) => {
+    if (!p.id)
+        return { error: 'missing id' };
+    const opts = { action: p.action, signal: p.signal, comment: p.comment };
+    const r = (0, indexContext_1.incrementUsage)(p.id, opts);
+    if (!r)
+        return { notFound: true };
+    return r;
+});
+(0, registry_1.registerHandler)('usage_hotset', (p) => {
+    const st = (0, indexContext_1.ensureLoaded)();
+    const snap = (0, indexContext_1.loadUsageSnapshot)();
+    const limit = Math.max(1, Math.min(p.limit ?? 10, 100));
+    const items = [...st.list]
+        .filter(e => (e.usageCount ?? 0) > 0)
+        .sort((a, b) => {
+        const ua = a.usageCount ?? 0;
+        const ub = b.usageCount ?? 0;
+        if (ub !== ua)
+            return ub - ua;
+        return (b.lastUsedAt || '').localeCompare(a.lastUsedAt || '');
+    })
+        .slice(0, limit)
+        .map(e => {
+        const rec = snap[e.id] || {};
+        const item = {
+            id: e.id,
+            usageCount: e.usageCount,
+            lastUsedAt: e.lastUsedAt,
+        };
+        if (rec.lastSignal)
+            item.lastSignal = rec.lastSignal;
+        if (rec.lastComment)
+            item.lastComment = rec.lastComment;
+        return item;
+    });
+    return { hash: st.hash, count: items.length, items, limit };
+});

package/dist/services/indexContext.d.ts

@@ -43,6 +43,17 @@ export interface UsageTrackOptions {
     signal?: string;
     comment?: string;
 }
+declare const invariantRepairLog: {
+    ts: string;
+    id: string;
+    field: string;
+    source: string;
+}[];
+/** Returns a summary of invariant repairs for health check visibility. */
+export declare function getInvariantRepairSummary(): {
+    totalRepairs: number;
+    recentRepairs: typeof invariantRepairLog;
+};
 export declare function clearUsageRateLimit(id?: string): void;
 export declare function loadUsageSnapshot(): Record<string, UsagePersistRecord>;
 export declare function getInstructionsDir(): string;
@@ -55,6 +66,7 @@ export declare function diagnoseInstructionsDir(): {
 export declare function touchIndexVersion(): void;
 export declare function markindexDirty(): void;
 export declare function ensureLoaded(): IndexState;
+export declare function ensureLoadedAsync(): Promise<IndexState>;
 export interface IndexPollerOptions {
     intervalMs?: number;
     proactive?: boolean;
@@ -63,6 +75,7 @@ export declare function startIndexVersionPoller(opts?: IndexPollerOptions): void
 export declare function stopIndexVersionPoller(): void;
 export declare function invalidate(): void;
 export declare function getIndexState(): IndexState;
+export declare function getIndexStateAsync(): Promise<IndexState>;
 export declare function getDebugIndexSnapshot(): {
     dir: string;
     fileCountOnDisk: number;
@@ -110,8 +123,15 @@ export declare function projectGovernance(e: InstructionEntry): {
     changeLogLength: number;
 };
 export declare function computeGovernanceHash(entries: InstructionEntry[]): string;
-export declare function writeEntry(entry: InstructionEntry): void;
+export declare function isDuplicateInstructionWriteError(error: unknown): boolean;
+export declare function writeEntry(entry: InstructionEntry, opts?: {
+    createOnly?: boolean;
+}): void;
+export declare function writeEntryAsync(entry: InstructionEntry, opts?: {
+    createOnly?: boolean;
+}): Promise<void>;
 export declare function removeEntry(id: string): void;
 export declare function scheduleUsagePersist(): void;
 export declare function incrementUsage(id: string, opts?: UsageTrackOptions): Record<string, unknown> | null;
 export declare function __testResetUsageState(): void;
+export {};