@compr/opscontext-mcp 2.5.8 → 2.6.0

package/dist/server-registry.js

@@ -0,0 +1,162 @@
+// [LOCKED] [SERVERS-ARE-INVENTORIED] 2026-09-05
+// [NEVER] let an MCP server start without writing its registry record, or answer "which
+//         servers run and on which build?" from a `ps` grep instead of this registry.
+// WHY: on 2026-09-05 two servers started before a build kept running the old importer for
+//      two hours and re-imported 1,766 records the owner had just had deleted. `ps` found them
+//      only on the second look: the first grep matched the absolute script path and the two
+//      had been started with a relative one. Nine other servers, one per open chat, were each
+//      re-embedding the whole corpus after every doc change (load average 230) and nothing
+//      said so. `server-meta.json` held one version: the last server to start.
+// FIX: every server writes ~/.contextengine/servers/<pid>.json on start (pid, parent, start
+//      time, version, a hash of the script it loaded, cwd) and refreshes a heartbeat; the file
+//      goes on exit, and a lister removes records whose pid is dead. `contextengine servers`
+//      and the end-session checklist compare each record's build hash with the file on disk
+//      now, and warn when more than SERVER_COUNT_WARN servers run at once.
+import { existsSync, mkdirSync, readFileSync, readdirSync, unlinkSync, writeFileSync } from "fs";
+import { join } from "path";
+import { homedir } from "os";
+import { createHash } from "crypto";
+import { execFileSync } from "child_process";
+/** More concurrent servers than this and every doc change costs that many re-embeds. */
+export const SERVER_COUNT_WARN = 3;
+const HEARTBEAT_MS = 60_000;
+function registryDir() {
+    return join(process.env.CONTEXTENGINE_HOME || join(homedir(), ".contextengine"), "servers");
+}
+/** Short content hash of the script a server loaded; the build identity. */
+export function buildHashOf(scriptPath) {
+    try {
+        return createHash("sha256").update(readFileSync(scriptPath)).digest("hex").slice(0, 12);
+    }
+    catch {
+        return null;
+    }
+}
+function parentName(ppid) {
+    try {
+        // Hardcoded argv, no shell: the only variable is a number.
+        return execFileSync("ps", ["-o", "comm=", "-p", String(ppid)], { encoding: "utf8", timeout: 2000 })
+            .trim().split("/").pop() || "?";
+    }
+    catch {
+        return "?";
+    }
+}
+export function isAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (e) {
+        return e?.code === "EPERM"; // exists, not ours
+    }
+}
+/**
+ * Register the running server. Returns a stop() that removes the record; exit handlers call it too.
+ */
+export function registerServer(opts) {
+    const dir = registryDir();
+    mkdirSync(dir, { recursive: true });
+    const now = new Date().toISOString();
+    const record = {
+        pid: process.pid,
+        ppid: process.ppid,
+        parent: parentName(process.ppid),
+        started: now,
+        heartbeat: now,
+        version: opts.version,
+        script: opts.script,
+        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 {
+        writeFileSync(file, JSON.stringify(record, null, 2));
+    }
+    catch { /* registry is diagnostics, never fatal */ } };
+    write();
+    const timer = setInterval(() => { record.heartbeat = new Date().toISOString(); write(); }, HEARTBEAT_MS);
+    timer.unref();
+    let stopped = false;
+    const stop = () => {
+        if (stopped)
+            return;
+        stopped = true;
+        clearInterval(timer);
+        try {
+            unlinkSync(file);
+        }
+        catch { /* already gone */ }
+    };
+    process.on("exit", stop);
+    for (const sig of ["SIGTERM", "SIGINT", "SIGHUP"]) {
+        process.on(sig, () => { stop(); process.exit(0); });
+    }
+    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() {
+    const dir = registryDir();
+    const report = { servers: [], removed: 0, warnings: [] };
+    if (!existsSync(dir))
+        return report;
+    for (const f of readdirSync(dir)) {
+        if (!f.endsWith(".json"))
+            continue;
+        const path = join(dir, f);
+        let rec;
+        try {
+            rec = JSON.parse(readFileSync(path, "utf8"));
+        }
+        catch {
+            try {
+                unlinkSync(path);
+            }
+            catch { /* */ }
+            report.removed++;
+            continue;
+        }
+        if (!isAlive(rec.pid)) {
+            try {
+                unlinkSync(path);
+            }
+            catch { /* */ }
+            report.removed++;
+            continue;
+        }
+        const currentBuild = buildHashOf(rec.script);
+        const staleBuild = currentBuild !== null && rec.build !== "unknown" && currentBuild !== rec.build;
+        report.servers.push({ ...rec, alive: true, currentBuild, staleBuild });
+    }
+    report.servers.sort((a, b) => a.started.localeCompare(b.started));
+    const stale = report.servers.filter((s) => s.staleBuild);
+    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`);
+    }
+    // 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;
+}
+export function formatServers(report, home = homedir()) {
+    const short = (p) => p.startsWith(home) ? "~" + p.slice(home.length) : p;
+    const lines = [];
+    lines.push(`${report.servers.length} server(s) running${report.removed ? `, ${report.removed} dead record(s) removed` : ""}`);
+    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";
+        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}`);
+    return lines.join("\n");
+}
+//# sourceMappingURL=server-registry.js.map

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.8",
+  "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",