@compr/opscontext-mcp 2.5.7 → 2.5.9

package/CHANGELOG.md

@@ -4,6 +4,35 @@ 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.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
+importer for two hours and re-imported 1,766 records the owner had just had deleted. `ps` found
+them on the second look only. Nine more servers, one per open chat, were each re-embedding the
+corpus after every doc change (load average 230). Nothing in the product could say any of this.
+
+### Added
+
+- **Server registry** (`[SERVERS-ARE-INVENTORIED]`, `src/server-registry.ts`): every server writes
+  `~/.contextengine/servers/<pid>.json` at the top of `main()` with pid, parent process, start time,
+  version, a sha256 of the script it loaded and its cwd; heartbeats every 60 s; removes the record on
+  exit; emits `server.start` to the audit log. `contextengine servers` and the end-session checklist
+  (§ 3b) list live servers, drop dead records, flag **STALE BUILD** when the script on disk no longer
+  matches the hash a server loaded, and warn above 3 concurrent servers. Exit 1 on any warning.
+- **Growth tripwire** (`[STORE-GROWTH-IS-A-TRIPWIRE-TOO]`): a write that adds more than 200 records
+  to the learnings store is refused (`learning.store_growth_refused`), the mirror of the shrink guard.
+  The auto-import reports `refused` and the server keeps running; `import_learnings` and the CLI
+  print the refusal. `CONTEXTENGINE_ALLOW_BULK=1` for one deliberate bulk import.
+
+## [2.5.8] — 2026-09-05 — "rules" is not a learnings heading
+
+### Fixed
+
+- `LEARNINGS_HEADING` no longer matches the word "rules". "## Key rules" and "### Security Rules"
+  are ordinary doc sections; on the evening 2.5.7 shipped the word let 231 subsection headings back
+  into the store. "## Essential Rules, distilled from Learnings" still qualifies through "learnings".
+  Replayed from a foreign cwd with the default patterns over ~/Projects: 99 records from 819 sources.
+
 ## [2.5.7] — 2026-09-05 — The learnings store was a pile of headings
 
 Of 3,005 records, about 2,760 had been produced by the doc importer from ~160 ordinary docs
@@ -17,7 +46,7 @@ secrets" under mobile because "expose" contains "expo".
 
 - **Auto-import takes only marked learnings** (`[AUTO-IMPORT-ONLY-MARKED-LEARNINGS]`): inline
   `- [category] rule → context` bullets anywhere; every shape inside a `*LEARNINGS.md` file; every
-  shape under a heading that says learnings / lessons / gotchas / pitfalls / rules / anti-patterns /
+  shape under a heading that says learnings / lessons / gotchas / pitfalls / anti-patterns /
   "never repeat" / "the hard way"; JSON. Bare H3 headings, bold bullets and table rows in ordinary
   docs are reported as `ignored` and left alone; the docs stay searchable as docs. Replayed over the
   818 discovered sources: 129 records instead of 1,879. `import_learnings` gains `permissive: true`

package/dist/audit.d.ts

@@ -1,4 +1,4 @@
-export type AuditEvent = "learning.save" | "learning.delete" | "learning.store_unreadable" | "learning.store_shrink_refused" | "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" | "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/cli-commands.js

@@ -27,6 +27,7 @@ export const KNOWN_COMMANDS = [
     "audit-rotate",
     "audit-redact-ack",
     "audit-verify",
+    "servers",
     "autostart-status",
     "cost",
     "deactivate",

package/dist/cli.js

@@ -655,6 +655,7 @@ import { loadRepoPolicy, parsePolicy, formatPolicySummary, formatValidationError
 import { buildCostReport } from "./cost-report.js";
 import { getStagedFiles, runSecretScan, runDocCoverage, runCommitMessageRequired, runRuleParity, formatSecretViolations, formatDocCoverageViolations, formatSecretViolationsJson, formatDocCoverageViolationsJson, formatCommitMessageViolations, formatCommitMessageViolationsJson, formatRuleParityViolations, formatRuleParityViolationsJson, } from "./hooks.js";
 import { safeAppend } from "./audit.js";
+import { listServers, formatServers } from "./server-registry.js";
 import { installSkill, locateBundledSkill, buildManagedBlock, syncClaudeMd, } from "./claude-integration.js";
 import { fileURLToPath } from "url";
 // ---------------------------------------------------------------------------
@@ -2208,6 +2209,10 @@ async function cliEndSession() {
     if (autoImport.imported > 0) {
         checks.push(`📥 Auto-imported ${autoImport.imported} new learnings from ${autoImport.total} doc sources\n`);
     }
+    if (autoImport.refused) {
+        checks.push(`- ⛔ Auto-import write refused: ${autoImport.refused}`);
+        failCount++;
+    }
     // --- Check 3: Learnings Store ---
     checks.push("## 3. Learnings Store\n");
     const stats = learningsStats();
@@ -2225,6 +2230,13 @@ async function cliEndSession() {
     passCount++;
     checks.push("");
     // --- Check 4: Sessions ---
+    // --- Check 3b: running servers ([LOCK] [SERVERS-ARE-INVENTORIED]) ---
+    checks.push("## 3b. Running servers\n");
+    const fleet = listServers();
+    checks.push("```\n" + formatServers(fleet) + "\n```");
+    if (fleet.warnings.length > 0)
+        failCount += fleet.warnings.length;
+    checks.push("");
     checks.push("## 4. Sessions\n");
     const sessions = listSessions();
     if (sessions.length > 0) {
@@ -2290,7 +2302,14 @@ async function cliImportLearnings(args) {
         console.error("  --permissive: every H3 heading, bold bullet and table row too.");
         process.exit(1);
     }
-    const result = importLearningsFromFile(filePath, category, project, { permissive });
+    let result;
+    try {
+        result = importLearningsFromFile(filePath, category, project, { permissive });
+    }
+    catch (e) {
+        console.error(`⛔ Import refused: ${e?.message || e}`);
+        process.exit(1);
+    }
     console.log(`\n📥 Import Results:`);
     console.log(`   Imported: ${result.imported}`);
     console.log(`   Updated:  ${result.updated}`);
@@ -2508,6 +2527,7 @@ Usage:
                                        Export hash-chained audit log (evidence aligned with
                                        SOC 2 CC7.2 + ISO 27001 A.12.4.1 — not a certification)
   contextengine audit-verify           Verify audit log chain integrity (tamper detection)
+  contextengine servers                List running MCP servers, their build vs the file on disk
   contextengine audit-redact-ack       Acknowledge deliberately redacted records on the chain (--index i,j --reason "...")
   contextengine audit-rotate [--keep-days N] [--max-records N] [--dry-run]
                                        Move old history into an archive segment. Archives
@@ -2719,6 +2739,11 @@ else if (command === "audit-redact-ack") {
 else if (command === "audit-rotate") {
     cliAuditRotate(process.argv.slice(3));
 }
+else if (command === "servers") {
+    const fleet = listServers();
+    console.log(formatServers(fleet));
+    process.exit(fleet.warnings.length > 0 ? 1 : 0);
+}
 else if (command === "audit-verify") {
     cliAuditVerify().catch((err) => {
         console.error("Error:", err);

package/dist/index.js

@@ -10,7 +10,8 @@ import { collectProjectOps, collectSystemOps } from "./collectors.js";
 import { loadCache, saveCache } from "./cache.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";
@@ -110,6 +111,9 @@ async function reindex() {
     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);
     if (learningChunks.length > 0) {
@@ -973,7 +977,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,6 +1088,17 @@ function registerResources() {
 // Start
 // ---------------------------------------------------------------------------
 async function main() {
+    // 0. Inventory this server FIRST, before indexing takes minutes: a server exists the moment it
+    //    starts. [LOCK] [SERVERS-ARE-INVENTORIED]
+    try {
+        const { record } = registerServer({ version: PKG_VERSION, script: fileURLToPath(import.meta.url) });
+        const fleet = listServers();
+        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 });
+    }
+    catch (err) {
+        console.error("[ContextEngine] ⚠ Server registry failed:", err);
+    }
     // 1. Ingest all sources (fast — keyword search available immediately)
     sources = loadSources();
     chunks = ingestSources(sources);
@@ -1126,6 +1147,9 @@ async function main() {
     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) {

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));
@@ -501,13 +529,15 @@ function deleteLearningUnlocked(id) {
 // FIX: a candidate becomes a learning only when the author marked it as one:
 //      (1) an inline-category bullet `- [category] rule → context`, anywhere;
 //      (2) any shape inside a file whose name says learnings (AGENT-LEARNINGS.md, LEARNINGS.md);
-//      (3) any shape under a heading that says learnings / lessons / gotchas / pitfalls / rules /
-//          anti-patterns / "never repeat" / "the hard way" (LEARNINGS_HEADING);
+//      (3) any shape under a heading that says learnings / lessons / gotchas / pitfalls /
+//          anti-patterns / "never repeat" / "the hard way" / mistakes (LEARNINGS_HEADING).
+//          Not "rules": "## Key rules" and "### Security Rules" are ordinary doc sections, and
+//          the word let 231 subsection headings back in on the evening this shipped;
 //      (4) JSON files, which are explicit by construction.
 //      `permissive: true` (MCP `import_learnings`, CLI `--permissive`) restores the old parser for
 //      a file the user chose on purpose. Every imported record now carries `source`.
 export const LEARNINGS_FILE_NAME = /learnings?\.md$/i;
-export const LEARNINGS_HEADING = /\b(learnings?|lessons?|gotchas?|pitfalls?|anti-?patterns?|never repeat|do not repeat|don'?t repeat|the hard way|hard way|mistakes?|rules?)\b/i;
+export const LEARNINGS_HEADING = /\b(learnings?|lessons?|gotchas?|pitfalls?|anti-?patterns?|never repeat|do not repeat|don'?t repeat|the hard way|hard way|mistakes?)\b/i;
 export function importLearningsFromFile(filePath, defaultCategory = "other", defaultProject, opts = {}) {
     if (!existsSync(filePath)) {
         return { imported: 0, updated: 0, skipped: 0, ignored: 0, errors: [`File not found: ${filePath}`] };
@@ -973,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,40 @@
+export interface ServerRecord {
+    pid: number;
+    ppid: number;
+    parent: string;
+    started: string;
+    heartbeat: string;
+    version: string;
+    script: string;
+    build: string;
+    cwd: string;
+    node: string;
+}
+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;
+}): {
+    record: ServerRecord;
+    stop: () => 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

package/dist/server-registry.js

@@ -0,0 +1,155 @@
+// [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,
+    };
+    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); });
+    }
+    return { record, stop };
+}
+/** 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`);
+    }
+    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)`);
+    }
+    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";
+        lines.push(`  pid ${String(s.pid).padEnd(6)} ${t}  v${s.version}  build ${s.build}  ${flag}  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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@compr/opscontext-mcp",
-  "version": "2.5.7",
+  "version": "2.5.9",
   "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",