@compr/opscontext-mcp 2.5.9 → 2.6.0

package/CHANGELOG.md

@@ -4,6 +4,38 @@ All notable changes to OpsContext for AI Agents (previously ContextEngine — MC
 
 > Entries for 2.2.0 through 2.4.0 were not backfilled here; see `docs/sessions/SESSION_19` through `SESSION_21` for those releases.
 
+## [2.6.0] 2026-09-05: One indexer, many readers
+
+Every Claude Code chat spawns its own MCP server, plus launchd, plus VS Code. Measured on
+2026-09-05 (SESSION_26): eleven servers, 9.3 CPU-hours in 1.4 h, load average 230, each one
+parsing the same ~820 sources and re-embedding every chunk after every save. The embedding cache
+had hit 2 times in 51 starts, because its key was one hash over the whole corpus, git status
+included; and a hit meant the model never loaded, so no semantic search and no re-embed, ever.
+
+### Added
+
+- **Content-addressed vector store** (`[EMBEDDINGS-ARE-CONTENT-ADDRESSED]`,
+  `src/embedding-store.ts`): one vector per distinct embedded text in
+  `~/.contextengine/embeddings.bin`, shared by every server on the machine. A doc change embeds
+  only its new chunks; a cold start embeds only texts never seen before. Always on. The old
+  `embedding-cache.json` is no longer read.
+- **Shared index with one writer per corpus** (`[ONE-INDEXER-MANY-READERS]`,
+  `src/shared-index.ts`), behind `CONTEXTENGINE_SHARED_INDEX=1`: the indexer is elected from the
+  server registry (a build equal to the file on disk first, then the earliest start), parses,
+  imports learnings, embeds, watches the files and writes `~/.contextengine/index/<corpus>.json`;
+  every other server of that corpus loads it, reloads within 3 s of a change, never watches files,
+  never sweep-imports learnings, and loads the model only on its first semantic query. A reader
+  with no index yet builds once locally. Off, every server indexes on its own as before.
+- `contextengine servers` shows `indexer` / `reader` and the corpus per server; audit events
+  `server.role` and `index.write`; `scripts/trial-shared-index.mjs` proves the behaviour on
+  three servers from three cwds (one re-index, readers current within 5 s, reader CPU flat).
+
+### Changed
+
+- The `reindex` tool on a reader reloads the shared index and names the indexer instead of
+  rebuilding on its own.
+- The "too many servers" warning counts only servers that index on their own.
+
 ## [2.5.9] — 2026-09-05 — The servers inventory themselves; growth is a tripwire too
 
 The evening 2.5.7 shipped, two MCP servers that had started before the build kept the old

package/dist/audit.d.ts

@@ -1,4 +1,4 @@
-export type AuditEvent = "learning.save" | "learning.delete" | "learning.store_unreadable" | "learning.store_shrink_refused" | "learning.store_growth_refused" | "server.start" | "learning.import" | "learning.export" | "session.save" | "session.delete" | "activation.activate" | "activation.deactivate" | "activation.heartbeat" | "activation.signature_reject" | "activation.legacy_signature" | "firewall.escalate" | "hook.block" | "hook.bypass" | "policy.skipped" | "browser.prompt" | "browser.response" | "browser.tool_call" | "browser.session_start" | "browser.session_end" | "browser.capture_miss" | "vscode.prompt_submit" | "vscode.tool_call" | "vscode.session_start" | "drift.detected" | "notification.fired" | "community.sync_ok" | "community.sync_error" | "audit.rotate" | "audit.redact";
+export type AuditEvent = "learning.save" | "learning.delete" | "learning.store_unreadable" | "learning.store_shrink_refused" | "learning.store_growth_refused" | "server.start" | "server.role" | "index.write" | "learning.import" | "learning.export" | "session.save" | "session.delete" | "activation.activate" | "activation.deactivate" | "activation.heartbeat" | "activation.signature_reject" | "activation.legacy_signature" | "firewall.escalate" | "hook.block" | "hook.bypass" | "policy.skipped" | "browser.prompt" | "browser.response" | "browser.tool_call" | "browser.session_start" | "browser.session_end" | "browser.capture_miss" | "vscode.prompt_submit" | "vscode.tool_call" | "vscode.session_start" | "drift.detected" | "notification.fired" | "community.sync_ok" | "community.sync_error" | "audit.rotate" | "audit.redact";
 export interface AuditRecord {
     ts: string;
     event: AuditEvent;

package/dist/config.d.ts

@@ -49,6 +49,11 @@ export interface ContextEngineConfig {
         enabled?: boolean;
     }>;
 }
+/**
+ * Look for contextengine.json in standard locations.
+ * Priority: env var > CWD > home dir
+ */
+export declare function findConfigFile(): string | null;
 /**
  * Load knowledge sources.
  *

package/dist/config.js

@@ -28,7 +28,7 @@ const DEFAULT_PATTERNS = [
  * Look for contextengine.json in standard locations.
  * Priority: env var > CWD > home dir
  */
-function findConfigFile() {
+export function findConfigFile() {
     const candidates = [];
     const envPath = process.env.CONTEXTENGINE_CONFIG;
     if (envPath) {

package/dist/embedding-store.d.ts

@@ -0,0 +1,46 @@
+export declare const EMBED_DIM = 384;
+export declare function embeddingStoreDir(): string;
+export declare function embeddingStorePath(): string;
+/** The key of one embedded text: 16 bytes (32 hex) of SHA-256 over model + text. */
+export declare function embedKey(model: string, text: string): string;
+export interface StoreLoad {
+    vectors: Map<string, Float32Array>;
+    /** Records on disk, duplicates included (the same key appended twice by two servers). */
+    records: number;
+    /** Bytes ignored at the tail (a partial record from a concurrent appender). */
+    partialBytes: number;
+    /** True when the file exists but its header is not ours; nothing is read from it. */
+    foreign: boolean;
+}
+/** Read the whole store. Missing file = empty store. ~7 MB for 4,400 vectors, tens of ms. */
+export declare function loadEmbeddingStore(path?: string): StoreLoad;
+/**
+ * Append vectors. One write syscall for the batch; the header is written with the first batch.
+ * Two servers creating the file at the same instant both write header + batch and the last
+ * truncating write wins; the loser's vectors are simply embedded again later.
+ */
+export declare function appendEmbeddings(entries: Array<[string, Float32Array]>, path?: string): {
+    written: number;
+    bytes: number;
+};
+/**
+ * Rewrite the store with only the live keys, temp file + rename. Called by an indexer when the
+ * file holds far more records than the corpus needs (every save of an edited doc appends its
+ * changed chunks again). A record appended by another server between the read and the rename
+ * is lost and re-embedded later; nothing else can be.
+ */
+export declare function compactEmbeddingStore(liveKeys: Set<string>, path?: string, opts?: {
+    minRecords?: number;
+    ratio?: number;
+}): {
+    compacted: boolean;
+    before: number;
+    after: number;
+};
+export declare const _internal: {
+    HEADER_BYTES: number;
+    RECORD_BYTES: number;
+    KEY_BYTES: number;
+    MAGIC: string;
+};
+//# sourceMappingURL=embedding-store.d.ts.map

package/dist/embedding-store.js

@@ -0,0 +1,141 @@
+// [LOCKED] [EMBEDDINGS-ARE-CONTENT-ADDRESSED] 2026-09-05
+// [NEVER] key the embedding cache on the whole corpus again (one hash over every chunk), and
+//         [NEVER] skip loading the model because "the cache hit".
+// WHY: the previous cache (src/cache.ts, removed in this commit) used one SHA-256 over all
+//      ~4,400 chunks as its key, and the corpus contains a `git diff --stat HEAD~1..HEAD` ops
+//      chunk per project, the learnings and the last session. Any commit in any of 40 projects,
+//      any saved learning, or another server with a different cwd writing the same single-slot
+//      file made it stale: measured 2 hits in 51 server starts (SESSION_26). Every start and
+//      every doc change then re-embedded every chunk, about 2 min unloaded and 29 min under the
+//      load those re-embeds themselves created (nine chats open, load average 230). And on the
+//      rare hit, initEmbeddings() was never called, so that server had no query pipeline: no
+//      semantic search, and reindex() never re-embedded again for its whole life.
+// FIX: one vector per distinct embedded text, keyed by SHA-256(model + text), in an
+//      append-only binary file shared by every server on the machine. A doc change embeds
+//      only its new chunks; a cold start embeds only texts never seen before, whatever the cwd.
+//      Whoever embeds loads the model at start; a reader of the shared index loads it on its
+//      first semantic query, never "skipped because the cache hit". Appends are one write
+//      syscall each; a torn tail is cut before the next append and ignored by the loader.
+import { appendFileSync, existsSync, mkdirSync, readFileSync, renameSync, statSync, truncateSync, writeFileSync } from "fs";
+import { join } from "path";
+import { homedir } from "os";
+import { createHash } from "crypto";
+export const EMBED_DIM = 384;
+const MAGIC = "CEEMB001"; // 8 bytes
+const HEADER_BYTES = 16; // magic (8) + dims uint32 LE (4) + reserved (4)
+const KEY_BYTES = 16;
+const RECORD_BYTES = KEY_BYTES + EMBED_DIM * 4;
+export function embeddingStoreDir() {
+    return process.env.CONTEXTENGINE_HOME || join(homedir(), ".contextengine");
+}
+export function embeddingStorePath() {
+    return join(embeddingStoreDir(), "embeddings.bin");
+}
+/** The key of one embedded text: 16 bytes (32 hex) of SHA-256 over model + text. */
+export function embedKey(model, text) {
+    return createHash("sha256").update(model).update("\0").update(text).digest("hex").slice(0, KEY_BYTES * 2);
+}
+function header() {
+    const b = Buffer.alloc(HEADER_BYTES);
+    b.write(MAGIC, 0, "ascii");
+    b.writeUInt32LE(EMBED_DIM, 8);
+    return b;
+}
+function recordOf(key, vec) {
+    const b = Buffer.alloc(RECORD_BYTES);
+    Buffer.from(key, "hex").copy(b, 0, 0, KEY_BYTES);
+    for (let i = 0; i < EMBED_DIM; i++)
+        b.writeFloatLE(vec[i] ?? 0, KEY_BYTES + i * 4);
+    return b;
+}
+/** Read the whole store. Missing file = empty store. ~7 MB for 4,400 vectors, tens of ms. */
+export function loadEmbeddingStore(path = embeddingStorePath()) {
+    const out = { vectors: new Map(), records: 0, partialBytes: 0, foreign: false };
+    if (!existsSync(path))
+        return out;
+    let buf;
+    try {
+        buf = readFileSync(path);
+    }
+    catch {
+        return out;
+    }
+    if (buf.length < HEADER_BYTES || buf.toString("ascii", 0, 8) !== MAGIC || buf.readUInt32LE(8) !== EMBED_DIM) {
+        out.foreign = true;
+        return out;
+    }
+    const body = buf.length - HEADER_BYTES;
+    const n = Math.floor(body / RECORD_BYTES);
+    out.partialBytes = body - n * RECORD_BYTES;
+    for (let r = 0; r < n; r++) {
+        const off = HEADER_BYTES + r * RECORD_BYTES;
+        const key = buf.toString("hex", off, off + KEY_BYTES);
+        // A copy, not a view: the file buffer must be collectable.
+        const vec = new Float32Array(EMBED_DIM);
+        for (let i = 0; i < EMBED_DIM; i++)
+            vec[i] = buf.readFloatLE(off + KEY_BYTES + i * 4);
+        out.vectors.set(key, vec);
+    }
+    out.records = n;
+    return out;
+}
+/**
+ * Append vectors. One write syscall for the batch; the header is written with the first batch.
+ * Two servers creating the file at the same instant both write header + batch and the last
+ * truncating write wins; the loser's vectors are simply embedded again later.
+ */
+export function appendEmbeddings(entries, path = embeddingStorePath()) {
+    if (entries.length === 0)
+        return { written: 0, bytes: 0 };
+    const recs = Buffer.concat(entries.map(([k, v]) => recordOf(k, v)));
+    mkdirSync(join(path, ".."), { recursive: true });
+    let size = 0;
+    try {
+        size = statSync(path).size;
+    }
+    catch {
+        size = 0;
+    }
+    if (size < HEADER_BYTES) {
+        writeFileSync(path, Buffer.concat([header(), recs]));
+        return { written: entries.length, bytes: recs.length };
+    }
+    // A torn tail (a writer that died mid-record) would shift the frame of every record appended
+    // after it; cut back to the last whole record before adding ours.
+    const torn = (size - HEADER_BYTES) % RECORD_BYTES;
+    if (torn !== 0)
+        truncateSync(path, size - torn);
+    appendFileSync(path, recs);
+    return { written: entries.length, bytes: recs.length };
+}
+/**
+ * Rewrite the store with only the live keys, temp file + rename. Called by an indexer when the
+ * file holds far more records than the corpus needs (every save of an edited doc appends its
+ * changed chunks again). A record appended by another server between the read and the rename
+ * is lost and re-embedded later; nothing else can be.
+ */
+export function compactEmbeddingStore(liveKeys, path = embeddingStorePath(), opts = {}) {
+    const minRecords = opts.minRecords ?? 10_000;
+    const ratio = opts.ratio ?? 2;
+    // Decide from the size first: below the floor there is nothing to read.
+    let onDisk = 0;
+    try {
+        onDisk = Math.max(0, Math.floor((statSync(path).size - HEADER_BYTES) / RECORD_BYTES));
+    }
+    catch {
+        onDisk = 0;
+    }
+    if (onDisk < minRecords)
+        return { compacted: false, before: onDisk, after: onDisk };
+    const load = loadEmbeddingStore(path);
+    const live = [...load.vectors.entries()].filter(([k]) => liveKeys.has(k));
+    if (load.records < minRecords || load.records < ratio * Math.max(live.length, 1)) {
+        return { compacted: false, before: load.records, after: load.records };
+    }
+    const tmp = `${path}.tmp-${process.pid}`;
+    writeFileSync(tmp, Buffer.concat([header(), ...live.map(([k, v]) => recordOf(k, v))]));
+    renameSync(tmp, path);
+    return { compacted: true, before: load.records, after: live.length };
+}
+export const _internal = { HEADER_BYTES, RECORD_BYTES, KEY_BYTES, MAGIC };
+//# sourceMappingURL=embedding-store.js.map

package/dist/embeddings.d.ts

@@ -1,4 +1,5 @@
 import type { Chunk } from "./ingest.js";
+export declare const MODEL_NAME = "Xenova/all-MiniLM-L6-v2";
 /**
  * Initialize the embedding pipeline (downloads model on first run, ~22MB).
  * Subsequent calls use cached model.
@@ -16,11 +17,22 @@ export interface EmbeddedChunk {
     chunk: Chunk;
     vector: Float32Array;
 }
+/** The exact text that is embedded for a chunk; the store key is derived from it. */
+export declare function embedInputOf(chunk: Chunk): string;
+export declare function embedKeyOf(chunk: Chunk): string;
+export interface EmbedChunksResult {
+    embedded: EmbeddedChunk[];
+    /** Chunks whose vector came from the shared store. */
+    reused: number;
+    /** Chunks embedded now and appended to the store. */
+    fresh: number;
+}
 /**
- * Embed all chunks. Returns the chunks with their vectors.
- * Shows progress on stderr.
+ * Embed all chunks, reusing the content-addressed store for every text it already holds and
+ * embedding only the rest. [LOCK] [EMBEDDINGS-ARE-CONTENT-ADDRESSED]
+ * Returns the chunks in input order. Shows progress on stderr.
  */
-export declare function embedChunks(chunks: Chunk[]): Promise<EmbeddedChunk[]>;
+export declare function embedChunks(chunks: Chunk[], store?: Map<string, Float32Array>, embedFn?: (text: string) => Promise<Float32Array>, storePath?: string): Promise<EmbedChunksResult>;
 export interface VectorSearchResult {
     chunk: Chunk;
     score: number;

package/dist/embeddings.js

@@ -14,10 +14,11 @@
 //    a whole class of buyers. A static import would silently re-break this.
 // FIX: If you need to take a dependency on a transformer feature, add it
 //    behind the same dynamic-import + isEmbeddingsReady() check pattern.
+import { embedKey, appendEmbeddings } from "./embedding-store.js";
 // We dynamically import @huggingface/transformers to keep startup fast
 // and handle the case where it fails gracefully.
 let embedPipeline = null;
-const MODEL_NAME = "Xenova/all-MiniLM-L6-v2";
+export const MODEL_NAME = "Xenova/all-MiniLM-L6-v2";
 /**
  * Initialize the embedding pipeline (downloads model on first run, ~22MB).
  * Subsequent calls use cached model.
@@ -77,29 +78,58 @@ function cosineSimilarity(a, b) {
     }
     return dot;
 }
+/** The exact text that is embedded for a chunk; the store key is derived from it. */
+export function embedInputOf(chunk) {
+    // Embed section + content together for context
+    return `${chunk.section}\n${chunk.content}`.slice(0, 512);
+}
+export function embedKeyOf(chunk) {
+    return embedKey(MODEL_NAME, embedInputOf(chunk));
+}
 /**
- * Embed all chunks. Returns the chunks with their vectors.
- * Shows progress on stderr.
+ * Embed all chunks, reusing the content-addressed store for every text it already holds and
+ * embedding only the rest. [LOCK] [EMBEDDINGS-ARE-CONTENT-ADDRESSED]
+ * Returns the chunks in input order. Shows progress on stderr.
  */
-export async function embedChunks(chunks) {
-    const results = [];
-    const total = chunks.length;
+export async function embedChunks(chunks, store, embedFn = embedText, storePath) {
+    const known = store ?? new Map();
+    const keys = chunks.map(embedKeyOf);
+    const results = new Array(chunks.length);
+    const todo = [];
+    for (let i = 0; i < chunks.length; i++) {
+        const v = known.get(keys[i]);
+        if (v)
+            results[i] = { chunk: chunks[i], vector: v };
+        else
+            todo.push(i);
+    }
+    const total = todo.length;
     const batchSize = 10;
-    for (let i = 0; i < total; i += batchSize) {
-        const batch = chunks.slice(i, i + batchSize);
-        const batchResults = await Promise.all(batch.map(async (chunk) => {
-            // Embed section + content together for context
-            const text = `${chunk.section}\n${chunk.content}`.slice(0, 512);
-            const vector = await embedText(text);
-            return { chunk, vector };
-        }));
-        results.push(...batchResults);
-        const done = Math.min(i + batchSize, total);
+    const appended = [];
+    for (let b = 0; b < total; b += batchSize) {
+        const batch = todo.slice(b, b + batchSize);
+        const vectors = await Promise.all(batch.map((i) => embedFn(embedInputOf(chunks[i]))));
+        batch.forEach((i, j) => {
+            results[i] = { chunk: chunks[i], vector: vectors[j] };
+            if (!known.has(keys[i])) {
+                known.set(keys[i], vectors[j]);
+                appended.push([keys[i], vectors[j]]);
+            }
+        });
+        const done = Math.min(b + batchSize, total);
         if (done % 50 === 0 || done === total) {
-            console.error(`[ContextEngine] 📊 Embedded ${done}/${total} chunks`);
+            console.error(`[ContextEngine] 📊 Embedded ${done}/${total} new chunks`);
+        }
+    }
+    if (appended.length > 0) {
+        try {
+            appendEmbeddings(appended, storePath);
+        }
+        catch (err) {
+            console.error(`[ContextEngine] ⚠ embedding store append failed: ${err.message}`);
         }
     }
-    return results;
+    return { embedded: results, reused: chunks.length - total, fresh: total };
 }
 /**
  * Semantic search: embed the query, then find most similar chunks.

package/dist/index.js

@@ -5,9 +5,10 @@ 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, safeAppend } from "./audit.js";
@@ -44,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)
@@ -59,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
@@ -105,14 +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)`);
-    }
-    if (autoImport.refused) {
-        console.error(`[ContextEngine] ⛔ Auto-import write refused: ${autoImport.refused}`);
+    // 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);
@@ -135,18 +152,110 @@ 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
 // ---------------------------------------------------------------------------
@@ -221,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();
@@ -232,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))
@@ -242,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`);
@@ -255,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
 // ---------------------------------------------------------------------------
@@ -293,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()) {
@@ -428,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.`);
 });
@@ -1089,83 +1270,44 @@ function registerResources() {
 // ---------------------------------------------------------------------------
 async function main() {
     // 0. Inventory this server FIRST, before indexing takes minutes: a server exists the moment it
-    //    starts. [LOCK] [SERVERS-ARE-INVENTORIED]
+    //    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();
+        }
+        catch (err) {
+            console.error("[ContextEngine] ⚠ corpus id failed, shared index off for this server:", err);
+        }
+    }
     try {
-        const { record } = registerServer({ version: PKG_VERSION, script: fileURLToPath(import.meta.url) });
+        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)}`);
-        safeAppend("server.start", { pid: record.pid, parent: record.parent, version: record.version, build: record.build, cwd: record.cwd, servers_running: fleet.servers.length, stale_builds: fleet.servers.filter((x) => x.staleBuild).length });
+        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 });
     }
     catch (err) {
         console.error("[ContextEngine] ⚠ Server registry failed:", err);
     }
-    // 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`);
-        }
-    }
-    if (config.collectSystemOps !== false) {
-        const sysOps = collectSystemOps();
-        if (sysOps.length > 0) {
-            chunks.push(...sysOps);
-            console.error(`[ContextEngine] 🖥 Collected ${sysOps.length} system operational chunks`);
-        }
-    }
-    // 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`);
-        }
-    }
-    // 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)`);
-    }
-    if (autoImport.refused) {
-        console.error(`[ContextEngine] ⛔ Auto-import write refused: ${autoImport.refused}`);
-    }
-    // 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();
@@ -1232,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/server-registry.d.ts

@@ -9,6 +9,10 @@ export interface ServerRecord {
     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 & {
@@ -30,9 +34,12 @@ export declare function isAlive(pid: number): boolean;
 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;

package/dist/server-registry.js

@@ -69,6 +69,8 @@ export function registerServer(opts) {
         build: buildHashOf(opts.script) || "unknown",
         cwd: process.cwd(),
         node: process.version,
+        ...(opts.corpus ? { corpus: opts.corpus } : {}),
+        ...(opts.role ? { role: opts.role } : {}),
     };
     const file = join(dir, `${process.pid}.json`);
     const write = () => { try {
@@ -93,7 +95,8 @@ export function registerServer(opts) {
     for (const sig of ["SIGTERM", "SIGINT", "SIGHUP"]) {
         process.on(sig, () => { stop(); process.exit(0); });
     }
-    return { record, stop };
+    const setRole = (role) => { record.role = role; write(); };
+    return { record, stop, setRole };
 }
 /** Read every record, drop the dead ones, compare builds with the files on disk now. */
 export function listServers() {
@@ -134,8 +137,11 @@ export function listServers() {
     if (stale.length > 0) {
         report.warnings.push(`${stale.length} server(s) run a build older than the file on disk (pid ${stale.map((s) => s.pid).join(", ")}): restart them or they keep the old behaviour`);
     }
-    if (report.servers.length > SERVER_COUNT_WARN) {
-        report.warnings.push(`${report.servers.length} servers run at once; every doc change makes each of them re-index and re-embed the corpus (${SERVER_COUNT_WARN} is the comfortable ceiling)`);
+    // Only servers that index on their own cost a re-index per doc change; readers of a shared
+    // index do not. [LOCK] [ONE-INDEXER-MANY-READERS]
+    const indexing = report.servers.filter((s) => s.role !== "reader");
+    if (indexing.length > SERVER_COUNT_WARN) {
+        report.warnings.push(`${indexing.length} of ${report.servers.length} servers index on their own; every doc change makes each of them re-index the corpus (${SERVER_COUNT_WARN} is the comfortable ceiling; CONTEXTENGINE_SHARED_INDEX=1 makes all but one per corpus readers)`);
     }
     return report;
 }
@@ -146,7 +152,8 @@ export function formatServers(report, home = homedir()) {
     for (const s of report.servers) {
         const t = s.started.slice(11, 19) + "Z";
         const flag = s.staleBuild ? `STALE BUILD (disk ${s.currentBuild})` : s.currentBuild === null ? "script missing on disk" : "current";
-        lines.push(`  pid ${String(s.pid).padEnd(6)} ${t}  v${s.version}  build ${s.build}  ${flag}  parent ${s.parent}  cwd ${short(s.cwd)}`);
+        const role = s.role ? `  ${s.role.padEnd(7)} corpus ${s.corpus ?? "?"}` : "";
+        lines.push(`  pid ${String(s.pid).padEnd(6)} ${t}  v${s.version}  build ${s.build}  ${flag}${role}  parent ${s.parent}  cwd ${short(s.cwd)}`);
     }
     for (const w of report.warnings)
         lines.push(`  ⚠ ${w}`);

package/dist/shared-index.d.ts

@@ -0,0 +1,45 @@
+import { type KnowledgeSource } from "./config.js";
+import type { Chunk } from "./ingest.js";
+import type { ServerReport } from "./server-registry.js";
+export type ServerRole = "indexer" | "reader";
+export declare const SHARED_INDEX_VERSION = 1;
+export declare function sharedIndexEnabled(): boolean;
+/**
+ * What a server's corpus is made of, as a short id: the config file it resolved (path and
+ * content) or the discovery fallback, and the env flags that change discovery. Two servers with
+ * the same id index the same thing and can share one index; different ids get their own writer.
+ */
+export declare function corpusId(): string;
+export interface SharedIndexFile {
+    version: number;
+    corpus: string;
+    seq: number;
+    stamp: string;
+    writer: number;
+    sources: KnowledgeSource[];
+    activeProjectNames: string[];
+    chunks: Chunk[];
+    /** One embedding-store key per chunk, same order. */
+    keys: string[];
+}
+export declare function sharedIndexPath(corpus: string): string;
+/** Temp file + rename: a reader never sees a half-written index. */
+export declare function writeSharedIndex(data: Omit<SharedIndexFile, "version" | "stamp">): {
+    path: string;
+    bytes: number;
+    ms: number;
+};
+export declare function readSharedIndex(corpus: string): SharedIndexFile | null;
+/** Cheap change detector for readers: the file's mtime, or null when absent. */
+export declare function sharedIndexMtime(corpus: string): number | null;
+/**
+ * Who indexes this corpus. Among the live registered servers of the corpus: a server whose
+ * build equals the file on disk beats a stale one, then the earliest start, then the lowest pid.
+ * A server that does not find itself in the registry indexes on its own: never wait on a
+ * registry that failed.
+ */
+export declare function electIndexer(corpus: string, servers: ServerReport["servers"], myPid: number): {
+    indexer: number | null;
+    role: ServerRole;
+};
+//# sourceMappingURL=shared-index.d.ts.map

package/dist/shared-index.js

@@ -0,0 +1,113 @@
+// [LOCKED] [ONE-INDEXER-MANY-READERS] 2026-09-05
+// [NEVER] let every MCP server watch the corpus and re-index it on its own again once the
+//         shared index is on, and [NEVER] let a server whose build is older than the file on
+//         disk win the election while a current one is alive.
+// WHY: every Claude Code chat spawns its own MCP server (`.mcp.json` per project, the user-scope
+//      entry elsewhere), plus launchd, plus VS Code. Each one parsed the same ~820 doc sources,
+//      collected ops from 40 projects, watched the same files and re-embedded the whole corpus
+//      on every save. Measured 2026-09-05 (SESSION_26): eleven servers, 9.3 CPU-hours in 1.4 h
+//      of wall clock, load average 230, a test suite that timed out, and until 2.5.6 nine
+//      writers racing on one learnings.json. A stale-build server that kept indexing after a
+//      rebuild re-imported 1,766 records the owner had just had deleted (SESSION_25).
+// FIX: one writer per corpus, chosen from the server registry (current build first, then the
+//      earliest start, then the lowest pid), parses, embeds and writes this file with a stamp;
+//      every other server of that corpus loads it read-only and reloads when the stamp moves.
+//      Off unless CONTEXTENGINE_SHARED_INDEX=1 until the trial has run on a real fleet. A reader
+//      that finds no index runs the old pipeline once, without importing learnings: the fallback
+//      is today's code path, not a second one.
+import { existsSync, mkdirSync, readFileSync, renameSync, statSync, writeFileSync } from "fs";
+import { join } from "path";
+import { homedir } from "os";
+import { createHash } from "crypto";
+import { findConfigFile } from "./config.js";
+export const SHARED_INDEX_VERSION = 1;
+export function sharedIndexEnabled() {
+    return process.env.CONTEXTENGINE_SHARED_INDEX === "1";
+}
+function ceHome() {
+    return process.env.CONTEXTENGINE_HOME || join(homedir(), ".contextengine");
+}
+/**
+ * What a server's corpus is made of, as a short id: the config file it resolved (path and
+ * content) or the discovery fallback, and the env flags that change discovery. Two servers with
+ * the same id index the same thing and can share one index; different ids get their own writer.
+ */
+export function corpusId() {
+    const h = createHash("sha256");
+    const cfg = findConfigFile();
+    h.update(`config=${cfg ?? "none"}\0`);
+    if (cfg) {
+        try {
+            h.update(readFileSync(cfg));
+        }
+        catch {
+            h.update("unreadable");
+        }
+    }
+    h.update(`\0ws=${process.env.CONTEXTENGINE_WORKSPACES ?? ""}`);
+    h.update(`\0skipmem=${process.env.OPSCONTEXT_SKIP_CLAUDE_MEMORY ?? ""}`);
+    h.update(`\0home=${homedir()}`);
+    return h.digest("hex").slice(0, 12);
+}
+export function sharedIndexPath(corpus) {
+    return join(ceHome(), "index", `${corpus}.json`);
+}
+/** Temp file + rename: a reader never sees a half-written index. */
+export function writeSharedIndex(data) {
+    const t0 = Date.now();
+    const path = sharedIndexPath(data.corpus);
+    mkdirSync(join(path, ".."), { recursive: true });
+    const file = { version: SHARED_INDEX_VERSION, stamp: new Date().toISOString(), ...data };
+    const json = JSON.stringify(file);
+    const tmp = `${path}.tmp-${process.pid}`;
+    writeFileSync(tmp, json);
+    renameSync(tmp, path);
+    return { path, bytes: Buffer.byteLength(json), ms: Date.now() - t0 };
+}
+export function readSharedIndex(corpus) {
+    const path = sharedIndexPath(corpus);
+    if (!existsSync(path))
+        return null;
+    try {
+        const f = JSON.parse(readFileSync(path, "utf8"));
+        if (f.version !== SHARED_INDEX_VERSION || f.corpus !== corpus || !Array.isArray(f.chunks) || !Array.isArray(f.keys))
+            return null;
+        if (f.keys.length !== f.chunks.length)
+            return null;
+        return f;
+    }
+    catch {
+        return null;
+    }
+}
+/** Cheap change detector for readers: the file's mtime, or null when absent. */
+export function sharedIndexMtime(corpus) {
+    try {
+        return statSync(sharedIndexPath(corpus)).mtimeMs;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Who indexes this corpus. Among the live registered servers of the corpus: a server whose
+ * build equals the file on disk beats a stale one, then the earliest start, then the lowest pid.
+ * A server that does not find itself in the registry indexes on its own: never wait on a
+ * registry that failed.
+ */
+export function electIndexer(corpus, servers, myPid) {
+    const mine = servers.filter((s) => s.corpus === corpus);
+    if (!mine.some((s) => s.pid === myPid))
+        return { indexer: null, role: "indexer" };
+    mine.sort((a, b) => {
+        if (a.staleBuild !== b.staleBuild)
+            return a.staleBuild ? 1 : -1;
+        const t = a.started.localeCompare(b.started);
+        if (t !== 0)
+            return t;
+        return a.pid - b.pid;
+    });
+    const winner = mine[0];
+    return { indexer: winner.pid, role: winner.pid === myPid ? "indexer" : "reader" };
+}
+//# sourceMappingURL=shared-index.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@compr/opscontext-mcp",
-  "version": "2.5.9",
+  "version": "2.6.0",
   "description": "OpsContext for AI Agents — read-only fleet visibility (PM2/nginx/Docker/git/cron) + tamper-evident audit log + policy-as-code hooks. The ops + compliance layer Claude Code can't grow natively.",
   "type": "module",
   "main": "dist/index.js",