@compr/opscontext-mcp 2.5.8 → 2.6.0

package/dist/index.js

@@ -5,12 +5,14 @@ import { z } from "zod";
 import { loadSources, loadProjectDirs, loadConfig, resolveProjectDir } from "./config.js";
 import { ingestSources } from "./ingest.js";
 import { searchChunks } from "./search.js";
-import { initEmbeddings, embedChunks, vectorSearch, isEmbeddingsReady, } from "./embeddings.js";
+import { initEmbeddings, embedChunks, embedKeyOf, vectorSearch, isEmbeddingsReady, } from "./embeddings.js";
 import { collectProjectOps, collectSystemOps } from "./collectors.js";
-import { loadCache, saveCache } from "./cache.js";
+import { loadEmbeddingStore, compactEmbeddingStore } from "./embedding-store.js";
+import { sharedIndexEnabled, corpusId, electIndexer, writeSharedIndex, readSharedIndex, sharedIndexMtime, } from "./shared-index.js";
 import { listProjects, checkPorts, runComplianceAudit, formatProjectList, formatPortMap, formatPlan, scoreProject, formatScoreReport, runScoreCanary, } from "./agents.js";
 import { saveSession, loadSession, listSessions, deleteSession, formatSession, formatSessionList, } from "./sessions.js";
-import { verifyChain, readAuditLog, filterByRange, autoRotateAuditLog } from "./audit.js";
+import { verifyChain, readAuditLog, filterByRange, autoRotateAuditLog, safeAppend } from "./audit.js";
+import { registerServer, listServers, formatServers } from "./server-registry.js";
 import { startEventIngestServer } from "./http-server.js";
 import { detect } from "./detector.js";
 import { buildCostReport } from "./cost-report.js";
@@ -43,6 +45,18 @@ let chunks = [];
 let embeddedChunks = [];
 let activeProjectNames = [];
 const firewall = new ProtocolFirewall();
+// One indexer, many readers. [LOCK] [ONE-INDEXER-MANY-READERS]
+// With the shared index off (default until the trial), every server is its own indexer, exactly
+// as before, and only the content-addressed vector store below is new.
+let role = "indexer";
+let corpus;
+let indexerPid = null;
+let setRegistryRole = null;
+/** key -> vector, loaded from ~/.contextengine/embeddings.bin and grown by what we embed. */
+let vectorStore = new Map();
+let indexSeq = 0;
+let lastIndexMtime = null;
+let modelInit = null;
 // Wire up learning search for auto-injection (avoids circular import)
 firewall.setLearningSearchFn((query, projects) => {
     return searchLearnings(query)
@@ -58,9 +72,11 @@ firewall.setLearningSearchFn((query, projects) => {
         .map((l) => ({ rule: l.rule, project: l.project, category: l.category }));
 });
 /**
- * (Re-)ingest all sources. Called at startup and on file changes.
+ * Parse every source, collect ops and code, import learnings (indexer only), inject learnings,
+ * community rules and adapters. Sets `sources`, `chunks`, `activeProjectNames`. No embedding
+ * here. One body for startup and for every reindex; the two used to be separate copies.
  */
-async function reindex() {
+async function buildIndex(opts) {
     sources = loadSources();
     chunks = ingestSources(sources);
     // Collect operational data from project directories
@@ -104,11 +120,16 @@ async function reindex() {
             console.error(`[ContextEngine] 💻 Parsed ${codeChunks} code chunks from source files`);
         }
     }
-    // Auto-import learnings from discovered doc sources
-    // Dedup is built-in — safe to call on every reindex, no duplicates created
-    const autoImport = autoImportFromSources(sources.map((s) => ({ path: s.path, name: s.name })));
-    if (autoImport.imported > 0) {
-        console.error(`[ContextEngine] 📥 Auto-imported ${autoImport.imported} new learnings from ${autoImport.total} doc sources (${autoImport.updated} updated)`);
+    // Auto-import learnings from discovered doc sources. Dedup is built-in. Only the indexer of a
+    // corpus writes the store from a sweep; a reader leaves that to it (one writer, not N).
+    if (opts.importLearnings) {
+        const autoImport = autoImportFromSources(sources.map((s) => ({ path: s.path, name: s.name })));
+        if (autoImport.imported > 0) {
+            console.error(`[ContextEngine] 📥 Auto-imported ${autoImport.imported} new learnings from ${autoImport.total} doc sources (${autoImport.updated} updated)`);
+        }
+        if (autoImport.refused) {
+            console.error(`[ContextEngine] ⛔ Auto-import write refused: ${autoImport.refused}`);
+        }
     }
     // Inject learnings as searchable chunks (project-scoped to prevent IP leakage)
     const learningChunks = learningsToChunks(activeProjectNames);
@@ -131,17 +152,109 @@ async function reindex() {
     }
     // Collect from plugin adapters
     if (config.adapters && config.adapters.length > 0) {
+        if (opts.loadAdapters) {
+            const adapterCount = await loadAdapters(config.adapters);
+            if (adapterCount === 0)
+                return;
+        }
         const adapterChunks = await collectFromAdapters(config.adapters);
         if (adapterChunks.length > 0) {
             chunks.push(...adapterChunks);
             console.error(`[ContextEngine] 🔌 Adapters contributed ${adapterChunks.length} chunks`);
         }
     }
-    if (isEmbeddingsReady()) {
-        console.error(`[ContextEngine] 🧠 Re-embedding ${chunks.length} chunks...`);
-        embeddedChunks = await embedChunks(chunks);
-        saveCache(chunks, embeddedChunks);
+}
+/** Load the model once; every caller shares the same promise. */
+function ensureModel() {
+    if (!modelInit)
+        modelInit = initEmbeddings();
+    return modelInit;
+}
+/**
+ * Vectors for the current chunks: from the store for every text it holds, embedded now for
+ * the rest. [LOCK] [EMBEDDINGS-ARE-CONTENT-ADDRESSED]
+ */
+async function embedAll() {
+    if (!isEmbeddingsReady())
+        return;
+    const snapshot = chunks;
+    const r = await embedChunks(snapshot, vectorStore);
+    if (snapshot !== chunks)
+        return; // a newer build replaced these chunks meanwhile; its own embed follows
+    embeddedChunks = r.embedded;
+    console.error(`[ContextEngine] ✅ Semantic search ready: ${r.reused} vectors from the store, ${r.fresh} embedded now`);
+    if (role === "indexer") {
+        try {
+            const c = compactEmbeddingStore(new Set(snapshot.map(embedKeyOf)));
+            if (c.compacted)
+                console.error(`[ContextEngine] 🧹 Embedding store compacted: ${c.before} -> ${c.after} records`);
+        }
+        catch (err) {
+            console.error(`[ContextEngine] ⚠ embedding store compaction failed: ${err.message}`);
+        }
+    }
+}
+/** Indexer only: write the shared index for readers of this corpus. No-op otherwise. */
+function publishIndex() {
+    if (!corpus || role !== "indexer")
+        return;
+    try {
+        indexSeq++;
+        const r = writeSharedIndex({
+            corpus,
+            seq: indexSeq,
+            writer: process.pid,
+            sources,
+            activeProjectNames,
+            chunks,
+            keys: chunks.map(embedKeyOf),
+        });
+        lastIndexMtime = sharedIndexMtime(corpus);
+        safeAppend("index.write", { corpus, seq: indexSeq, chunks: chunks.length, vectors: embeddedChunks.length, bytes: r.bytes, ms: r.ms });
+        console.error(`[ContextEngine] 📤 Shared index written: seq ${indexSeq}, ${chunks.length} chunks, ${Math.round(r.bytes / 1024)} KB, ${r.ms} ms`);
+    }
+    catch (err) {
+        console.error(`[ContextEngine] ⚠ shared index write failed: ${err.message}`);
+    }
+}
+/** Reader: take the indexer's chunks and resolve their vectors from the store. */
+function adoptSharedIndex() {
+    if (!corpus)
+        return false;
+    const f = readSharedIndex(corpus);
+    if (!f)
+        return false;
+    sources = f.sources;
+    chunks = f.chunks;
+    activeProjectNames = f.activeProjectNames;
+    try {
+        firewall.setProjectDirs(loadProjectDirs());
     }
+    catch { /* scoping keeps its last value */ }
+    vectorStore = loadEmbeddingStore().vectors;
+    const vecs = [];
+    let missing = 0;
+    f.chunks.forEach((c, i) => {
+        const v = vectorStore.get(f.keys[i]);
+        if (v)
+            vecs.push({ chunk: c, vector: v });
+        else
+            missing++;
+    });
+    embeddedChunks = vecs;
+    indexSeq = f.seq;
+    lastIndexMtime = sharedIndexMtime(corpus);
+    console.error(`[ContextEngine] 📥 Shared index loaded: seq ${f.seq} from pid ${f.writer}, ${chunks.length} chunks, ${vecs.length} vectors${missing ? `, ${missing} not embedded yet` : ""}`);
+    return true;
+}
+/**
+ * (Re-)ingest all sources. Called at startup and on file changes by the indexer; a reader
+ * never calls it on its own except as the fallback when no shared index exists yet.
+ */
+async function reindex() {
+    await buildIndex({ importLearnings: role === "indexer" });
+    await embedAll();
+    publishIndex();
 }
 // ---------------------------------------------------------------------------
 // Hybrid Search: combine keyword + vector scores with temporal decay
@@ -217,8 +330,11 @@ function hybridSearch(query, keywordResults, vectorResults, topK) {
 // File Watching
 // ---------------------------------------------------------------------------
 const watchers = [];
-function startWatching() {
-    // Clean up old watchers
+let indexPoll = null;
+let rolePoll = null;
+const INDEX_POLL_MS = 3_000;
+const ROLE_POLL_MS = 15_000;
+function stopWatching() {
     for (const w of watchers) {
         try {
             w.close();
@@ -228,6 +344,10 @@ function startWatching() {
         }
     }
     watchers.length = 0;
+}
+/** Indexer only: one fs.watch per source; a change rebuilds, embeds the new chunks, publishes. */
+function startWatching() {
+    stopWatching();
     let debounceTimer = null;
     for (const source of sources) {
         if (!existsSync(source.path))
@@ -238,6 +358,8 @@ function startWatching() {
                 if (debounceTimer)
                     clearTimeout(debounceTimer);
                 debounceTimer = setTimeout(async () => {
+                    if (role !== "indexer")
+                        return; // demoted while the timer ran
                     console.error(`[ContextEngine] 📝 File changed: ${basename(source.path)} — re-indexing...`);
                     await reindex();
                     console.error(`[ContextEngine] ✅ Re-indexed: ${chunks.length} chunks from ${sources.length} sources`);
@@ -251,6 +373,61 @@ function startWatching() {
     }
     console.error(`[ContextEngine] 👁 Watching ${watchers.length} source files for changes`);
 }
+/** Reader only: reload the shared index when its stamp moves. A stat every 3 s, nothing else. */
+function startIndexPolling() {
+    if (indexPoll || !corpus)
+        return;
+    indexPoll = setInterval(() => {
+        if (role !== "reader" || !corpus)
+            return;
+        const m = sharedIndexMtime(corpus);
+        if (m !== null && m !== lastIndexMtime)
+            adoptSharedIndex();
+    }, INDEX_POLL_MS);
+    indexPoll.unref();
+}
+function stopIndexPolling() {
+    if (indexPoll)
+        clearInterval(indexPoll);
+    indexPoll = null;
+}
+/** Re-run the election; on a change of role, switch what this server does. */
+function evaluateRole(reason) {
+    if (!corpus)
+        return;
+    let e;
+    try {
+        e = electIndexer(corpus, listServers().servers, process.pid);
+    }
+    catch (err) {
+        console.error(`[ContextEngine] ⚠ election failed, staying ${role}: ${err.message}`);
+        return;
+    }
+    indexerPid = e.indexer;
+    if (e.role === role)
+        return;
+    const was = role;
+    role = e.role;
+    setRegistryRole?.(role);
+    safeAppend("server.role", { pid: process.pid, corpus, role, indexer: indexerPid, reason });
+    console.error(`[ContextEngine] 🧭 Role ${was} -> ${role} (${reason}; indexer pid ${indexerPid ?? process.pid})`);
+    if (role === "indexer") {
+        stopIndexPolling();
+        ensureModel().then(() => reindex()).then(() => startWatching()).catch((err) => {
+            console.error(`[ContextEngine] ⚠ taking over as indexer failed: ${err.message}`);
+        });
+    }
+    else {
+        stopWatching();
+        startIndexPolling();
+    }
+}
+function startRolePolling() {
+    if (rolePoll || !corpus)
+        return;
+    rolePoll = setInterval(() => evaluateRole("periodic"), ROLE_POLL_MS);
+    rolePoll.unref();
+}
 // ---------------------------------------------------------------------------
 // MCP Server
 // ---------------------------------------------------------------------------
@@ -289,6 +466,10 @@ server.tool("search_context", "Search across all indexed project knowledge (copi
         .describe("Search mode: hybrid (default), keyword-only, or semantic-only"),
 }, async ({ query, top_k, mode }) => {
     let results = [];
+    // A reader keeps its 300 MB model unloaded until someone asks for semantics; the first such
+    // query is answered by keyword while the model loads. [LOCK] [EMBEDDINGS-ARE-CONTENT-ADDRESSED]
+    if (mode !== "keyword" && !isEmbeddingsReady())
+        void ensureModel();
     if (mode === "keyword" || mode === "hybrid") {
         const kwResults = searchChunks(chunks, query, top_k * 2);
         if (mode === "keyword" || !isEmbeddingsReady()) {
@@ -424,6 +605,10 @@ server.tool("read_source", "Read the full content of a specific knowledge source
 // Tool: reindex
 // ---------------------------------------------------------------------------
 server.tool("reindex", "Force a full re-index of all knowledge sources. Use after adding new files or changing contextengine.json.", {}, async () => {
+    if (role === "reader" && corpus) {
+        adoptSharedIndex();
+        return respond("reindex", `This server reads the shared index of corpus ${corpus}, written by pid ${indexerPid ?? "?"}: reloaded seq ${indexSeq}, ${chunks.length} chunks, ${embeddedChunks.length} vectors. Saving a doc makes the indexer rebuild; every reader picks it up within ${INDEX_POLL_MS / 1000} s.`);
+    }
     await reindex();
     return respond("reindex", `Re-indexed: ${chunks.length} chunks from ${sources.length} sources. Embeddings: ${embeddedChunks.length} vectors.`);
 });
@@ -973,7 +1158,13 @@ server.tool("import_learnings", "Bulk-import learnings from a Markdown or JSON f
         .optional()
         .describe("Import every heading, bold bullet and table row as a rule (the pre-2.5.7 behaviour). Default false: only marked learnings."),
 }, async ({ file_path, default_category, project, permissive }) => {
-    const result = importLearningsFromFile(file_path, default_category || "other", project, { permissive: permissive === true });
+    let result;
+    try {
+        result = importLearningsFromFile(file_path, default_category || "other", project, { permissive: permissive === true });
+    }
+    catch (e) {
+        return respond("import_learnings", `⛔ Import refused: ${e?.message || e}`);
+    }
     // Re-inject learnings into search index (project-scoped)
     const newChunks = learningsToChunks(activeProjectNames);
     const nonLearningChunks = chunks.filter((c) => c.source !== "💡 Learnings Store");
@@ -1078,70 +1269,45 @@ function registerResources() {
 // Start
 // ---------------------------------------------------------------------------
 async function main() {
-    // 1. Ingest all sources (fast — keyword search available immediately)
-    sources = loadSources();
-    chunks = ingestSources(sources);
-    // 1b. Collect operational data (git, deps, env, docker, pm2, etc.)
-    const config = loadConfig();
-    const projectDirs = loadProjectDirs();
-    activeProjectNames = projectDirs.map((d) => d.name);
-    firewall.setProjectDirs(projectDirs);
-    if (config.collectOps !== false) {
-        let opsChunks = 0;
-        for (const dir of projectDirs) {
-            const ops = collectProjectOps(dir.path, dir.name);
-            chunks.push(...ops);
-            opsChunks += ops.length;
-        }
-        if (opsChunks > 0) {
-            console.error(`[ContextEngine] ⚙ Collected ${opsChunks} operational chunks from ${projectDirs.length} projects`);
+    // 0. Inventory this server FIRST, before indexing takes minutes: a server exists the moment it
+    //    starts. [LOCK] [SERVERS-ARE-INVENTORIED]. With the shared index on, the registry is also
+    //    the electorate: the record carries the corpus and the role. [LOCK] [ONE-INDEXER-MANY-READERS]
+    if (sharedIndexEnabled()) {
+        try {
+            corpus = corpusId();
         }
-    }
-    if (config.collectSystemOps !== false) {
-        const sysOps = collectSystemOps();
-        if (sysOps.length > 0) {
-            chunks.push(...sysOps);
-            console.error(`[ContextEngine] 🖥 Collected ${sysOps.length} system operational chunks`);
+        catch (err) {
+            console.error("[ContextEngine] ⚠ corpus id failed, shared index off for this server:", err);
         }
     }
-    // 1c. Scan code files (TS/JS/Python) if configured
-    if (config.codeDirs && config.codeDirs.length > 0) {
-        let codeChunks = 0;
-        for (const dir of projectDirs) {
-            for (const codeDir of config.codeDirs) {
-                const codePath = join(dir.path, codeDir);
-                if (existsSync(codePath)) {
-                    const codeResults = scanCodeDir(codePath, dir.name);
-                    chunks.push(...codeResults);
-                    codeChunks += codeResults.length;
-                }
-            }
-        }
-        if (codeChunks > 0) {
-            console.error(`[ContextEngine] 💻 Parsed ${codeChunks} code chunks from source files`);
+    try {
+        const reg = registerServer({ version: PKG_VERSION, script: fileURLToPath(import.meta.url), corpus, role: corpus ? "reader" : undefined });
+        setRegistryRole = reg.setRole;
+        const fleet = listServers();
+        if (corpus) {
+            const e = electIndexer(corpus, fleet.servers, process.pid);
+            role = e.role;
+            indexerPid = e.indexer;
+            reg.setRole(role);
+            safeAppend("server.role", { pid: process.pid, corpus, role, indexer: indexerPid, reason: "start" });
         }
+        console.error(`[ContextEngine] 🧭 ${formatServers(fleet)}`);
+        if (corpus)
+            console.error(`[ContextEngine] 🧭 This server: ${role} of corpus ${corpus}${role === "reader" ? ` (indexer pid ${indexerPid})` : ""}`);
+        safeAppend("server.start", { pid: reg.record.pid, parent: reg.record.parent, version: reg.record.version, build: reg.record.build, cwd: reg.record.cwd, servers_running: fleet.servers.length, stale_builds: fleet.servers.filter((x) => x.staleBuild).length });
     }
-    // 1d. Auto-import learnings from discovered doc sources
-    const autoImport = autoImportFromSources(sources.map((s) => ({ path: s.path, name: s.name })));
-    if (autoImport.imported > 0) {
-        console.error(`[ContextEngine] 📥 Auto-imported ${autoImport.imported} new learnings from ${autoImport.total} doc sources (${autoImport.updated} updated)`);
+    catch (err) {
+        console.error("[ContextEngine] ⚠ Server registry failed:", err);
     }
-    // 1e. Inject learnings into search index (project-scoped)
-    const learningChunks = learningsToChunks(activeProjectNames);
-    if (learningChunks.length > 0) {
-        chunks.push(...learningChunks);
-        console.error(`[ContextEngine] 💡 Injected ${learningChunks.length} learning chunks into search index (scoped)`);
-    }
-    // 1f. Load and collect from plugin adapters
-    if (config.adapters && config.adapters.length > 0) {
-        const adapterCount = await loadAdapters(config.adapters);
-        if (adapterCount > 0) {
-            const adapterChunks = await collectFromAdapters(config.adapters);
-            if (adapterChunks.length > 0) {
-                chunks.push(...adapterChunks);
-                console.error(`[ContextEngine] 🔌 Adapters contributed ${adapterChunks.length} chunks from ${adapterCount} adapters`);
-            }
-        }
+    // 1. The index: a reader takes the indexer's; everyone else, or a reader with nothing to
+    //    take yet, builds it (fast, keyword search available immediately).
+    let adopted = false;
+    if (role === "reader")
+        adopted = adoptSharedIndex();
+    if (!adopted) {
+        if (role === "reader")
+            console.error("[ContextEngine] 📥 No shared index yet; building locally once, without importing learnings");
+        await buildIndex({ importLearnings: role === "indexer", loadAdapters: true });
     }
     // 2. Register MCP resources
     registerResources();
@@ -1208,24 +1374,28 @@ async function main() {
     catch (err) {
         console.error("[ContextEngine] ⚠ Failed to write server-meta.json:", err);
     }
-    // 4. Load embeddings — try cache first, then model (non-blocking)
-    const cached = loadCache(chunks);
-    if (cached) {
-        embeddedChunks = cached;
-        console.error(`[ContextEngine] ✅ Semantic search ready from cache (${embeddedChunks.length} vectors)`);
-    }
-    else {
-        initEmbeddings().then(async (ready) => {
-            if (ready) {
-                console.error(`[ContextEngine] 🧠 Embedding ${chunks.length} chunks...`);
-                embeddedChunks = await embedChunks(chunks);
-                saveCache(chunks, embeddedChunks);
-                console.error(`[ContextEngine] ✅ Semantic search ready (${embeddedChunks.length} vectors)`);
-            }
+    // 4. Vectors. The store holds one vector per text ever embedded on this machine; the model
+    //    always loads for whoever embeds or answers queries. [LOCK] [EMBEDDINGS-ARE-CONTENT-ADDRESSED]
+    //    A reader that adopted the index already has its vectors and loads the model on its first
+    //    semantic query, not before: 300 MB per process is worth waiting for.
+    if (!adopted) {
+        vectorStore = loadEmbeddingStore().vectors;
+        if (vectorStore.size > 0)
+            console.error(`[ContextEngine] 💾 Embedding store: ${vectorStore.size} vectors`);
+        publishIndex(); // keyword-searchable index for readers now; vectors follow
+        ensureModel().then(async (ready) => {
+            if (!ready)
+                return;
+            await embedAll();
+            publishIndex();
         });
     }
-    // 5. Start file watchers
-    startWatching();
+    // 5. Watch (indexer) or poll (reader), and keep the election running
+    if (role === "indexer")
+        startWatching();
+    else
+        startIndexPolling();
+    startRolePolling();
     // 6. Boot the local HTTP event-ingest endpoint for the browser extension.
     // Local 127.0.0.1:7842 only; auth via shared secret at
     // ~/.contextengine/extension-secret (see init-extension-secret CLI).

package/dist/learnings.d.ts

@@ -26,6 +26,7 @@ export declare function withStoreLock<T>(fn: () => T): T;
  * loadStore() returns the same in-memory store and every saveStore() only marks it dirty.
  */
 export declare function withStoreBatch<T>(fn: () => T): T;
+export declare const MAX_GROWTH_PER_WRITE = 200;
 /** Test seam for the writer's tripwire; not part of the API. */
 export declare function __writeStoreForTests(store: LearningsStore): void;
 /**
@@ -120,6 +121,7 @@ export declare function autoImportFromSources(sources: Array<{
     imported: number;
     updated: number;
     ignored: number;
+    refused?: string;
 };
 /**
  * Get the store stats.

package/dist/learnings.js

@@ -266,6 +266,19 @@ function dailyBackup() {
     }
     catch { /* a missing backup must never block a save */ }
 }
+// [LOCKED] [STORE-GROWTH-IS-A-TRIPWIRE-TOO] 2026-09-05
+// [NEVER] let one write add more than MAX_GROWTH_PER_WRITE records to the store without the
+//         explicit override, and never raise the limit to make an import "just work".
+// WHY: the shrink guard below caught the wipe of 2026-09-05; the same evening two stale servers
+//      wrote 1,766 records in one minute and nothing objected, because only shrinking was
+//      guarded. Every legitimate write is small: an agent saves one rule, the strict auto-import
+//      of a whole workspace produced 99 (replayed 2026-09-05), the largest real learnings file
+//      a few dozen. Thousands in one write is a bug or old code, never a lesson.
+// FIX: a write that grows the store by more than MAX_GROWTH_PER_WRITE over the file on disk
+//      is refused with an audit event, unless CONTEXTENGINE_ALLOW_BULK=1 (set knowingly, for
+//      one deliberate bulk import). The auto-import catches the refusal and reports it; the
+//      server keeps running.
+export const MAX_GROWTH_PER_WRITE = 200;
 function writeStoreToDisk(store) {
     ensureDir();
     store.count = store.learnings.length;
@@ -284,6 +297,21 @@ function writeStoreToDisk(store) {
             throw new Error(`refusing to write ${store.learnings.length} learnings over a store of ${onDisk}: that is the shape of a wipe, not an edit. Set CONTEXTENGINE_ALLOW_SHRINK=1 if this is deliberate.`);
         }
     }
+    // Growth tripwire. [LOCK] [STORE-GROWTH-IS-A-TRIPWIRE-TOO]
+    if (existsSync(LEARNINGS_PATH) && process.env.CONTEXTENGINE_ALLOW_BULK !== "1") {
+        let onDisk = -1;
+        try {
+            onDisk = (JSON.parse(readFileSync(LEARNINGS_PATH, "utf-8")).learnings || []).length;
+        }
+        catch {
+            onDisk = -1;
+        }
+        const growth = store.learnings.length - onDisk;
+        if (onDisk >= 0 && growth > MAX_GROWTH_PER_WRITE) {
+            safeAppend("learning.store_growth_refused", { on_disk: onDisk, attempted: store.learnings.length, growth });
+            throw new Error(`refusing to add ${growth} learnings in one write (store ${onDisk}, limit ${MAX_GROWTH_PER_WRITE}): that is the shape of a runaway import, not a lesson. Set CONTEXTENGINE_ALLOW_BULK=1 for one deliberate bulk import.`);
+        }
+    }
     dailyBackup();
     const tmp = `${LEARNINGS_PATH}.tmp-${process.pid}-${Date.now()}`;
     writeFileSync(tmp, JSON.stringify(store, null, 2));
@@ -975,27 +1003,38 @@ export function autoImportFromSources(sources) {
     let totalUpdated = 0;
     let totalIgnored = 0;
     let processed = 0;
+    let refused;
     // One load and one save for the whole sweep (~880 files), instead of one full-file
     // rewrite per rule per file. [LOCK] [STORE-NEVER-STARTS-FRESH-OVER-DATA]
-    withStoreBatch(() => {
-        for (const source of sources) {
-            // Only process markdown files
-            if (!source.path.endsWith(".md"))
-                continue;
-            if (!existsSync(source.path))
-                continue;
-            // Extract project name from source name (e.g., "ContextEngine — copilot-instructions.md")
-            const project = source.name.split(" — ")[0]?.trim() || undefined;
-            // Strict by construction: only marked learnings. [LOCK] [AUTO-IMPORT-ONLY-MARKED-LEARNINGS]
-            const result = importLearningsFromFile(source.path, "other", project);
-            totalImported += result.imported;
-            totalUpdated += result.updated;
-            totalIgnored += result.ignored;
-            if (result.imported > 0 || result.updated > 0)
-                processed++;
-        }
-    });
-    return { total: processed, imported: totalImported, updated: totalUpdated, ignored: totalIgnored };
+    try {
+        withStoreBatch(() => {
+            for (const source of sources) {
+                // Only process markdown files
+                if (!source.path.endsWith(".md"))
+                    continue;
+                if (!existsSync(source.path))
+                    continue;
+                // Extract project name from source name (e.g., "ContextEngine — copilot-instructions.md")
+                const project = source.name.split(" — ")[0]?.trim() || undefined;
+                // Strict by construction: only marked learnings. [LOCK] [AUTO-IMPORT-ONLY-MARKED-LEARNINGS]
+                const result = importLearningsFromFile(source.path, "other", project);
+                totalImported += result.imported;
+                totalUpdated += result.updated;
+                totalIgnored += result.ignored;
+                if (result.imported > 0 || result.updated > 0)
+                    processed++;
+            }
+        });
+    }
+    catch (e) {
+        // A refused write (growth or shrink tripwire, lock timeout) must not take the server down;
+        // it is reported to the caller and the store is left as it was. [LOCK] [STORE-GROWTH-IS-A-TRIPWIRE-TOO]
+        refused = String(e?.message || e);
+        totalImported = 0;
+        totalUpdated = 0;
+        processed = 0;
+    }
+    return { total: processed, imported: totalImported, updated: totalUpdated, ignored: totalIgnored, refused };
 }
 /**
  * Get the store stats.

package/dist/server-registry.d.ts

@@ -0,0 +1,47 @@
+export interface ServerRecord {
+    pid: number;
+    ppid: number;
+    parent: string;
+    started: string;
+    heartbeat: string;
+    version: string;
+    script: string;
+    build: string;
+    cwd: string;
+    node: string;
+    /** Since 2.6.0: what this server indexes (see shared-index.ts corpusId) and whether it is
+     *  the one writing the shared index for it, or a reader of it. Absent on older builds. */
+    corpus?: string;
+    role?: "indexer" | "reader";
+}
+export interface ServerReport {
+    servers: Array<ServerRecord & {
+        alive: true;
+        currentBuild: string | null;
+        staleBuild: boolean;
+    }>;
+    removed: number;
+    warnings: string[];
+}
+/** More concurrent servers than this and every doc change costs that many re-embeds. */
+export declare const SERVER_COUNT_WARN = 3;
+/** Short content hash of the script a server loaded; the build identity. */
+export declare function buildHashOf(scriptPath: string): string | null;
+export declare function isAlive(pid: number): boolean;
+/**
+ * Register the running server. Returns a stop() that removes the record; exit handlers call it too.
+ */
+export declare function registerServer(opts: {
+    version: string;
+    script: string;
+    corpus?: string;
+    role?: "indexer" | "reader";
+}): {
+    record: ServerRecord;
+    stop: () => void;
+    setRole: (role: "indexer" | "reader") => void;
+};
+/** Read every record, drop the dead ones, compare builds with the files on disk now. */
+export declare function listServers(): ServerReport;
+export declare function formatServers(report: ServerReport, home?: string): string;
+//# sourceMappingURL=server-registry.d.ts.map