@compr/opscontext-mcp 2.7.1 → 2.8.0

package/CHANGELOG.md

@@ -4,6 +4,32 @@ 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.8.0] 2026-09-06: health is measured, never estimated
+
+### Added
+
+- **Fleet health** (`[HEALTH-IS-MEASURED-NEVER-ESTIMATED]`, `src/fleet-health.ts`): the indexing
+  server writes `~/.contextengine/fleet-health.json` once a minute: servers on an old build
+  (version drift), shared-index writes in the last hour (reindex rate, ceiling 30), today's
+  pre-commit blocks with file and reason, learnings-store refusals, learnings saved (creates,
+  not a sweep's updates), and the last release for which `verify-release` passed. Every number
+  is counted from the audit log, the server registry or a file on disk. Warnings list measured
+  problems only. Shown by `contextengine servers` (exit 1 on any warning) and by `end-session`
+  § 3b; each server logs "N server(s) on an old build" when that number changes.
+- `index.write` audit events carry the writer's pid.
+
+### VS Code extension 0.12.0
+
+- **Status bar redesign** (Session 25 item 4): warning colour only on a measured problem (a
+  store refusal, servers on an old build, an index-write storm, commits made since the last
+  saved CE session, no MCP session, too many uncommitted files). Never on a timer. Default text
+  `CE` plus blocks prevented and recalls surfaced. Tooltip: measured problems, today's counts,
+  the last blocks with file and reason, servers and roles, version and last verified release,
+  the repo's CE session and commits since it was saved. "Time saved" is gone from the bar and
+  the info panel: it was a multiplier nobody could check.
+- `fleetHealthPoller.ts` reads the health file every 15 s and treats a file older than 5 min as
+  absent.
+
 ## [2.7.1] 2026-09-06: the autostart agent is the standing indexer; servers --cost
 
 ### Changed

package/dist/cli.js

@@ -656,6 +656,7 @@ 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 { computeFleetHealth, formatFleetHealth } from "./fleet-health.js";
 import { installSkill, locateBundledSkill, buildManagedBlock, syncClaudeMd, } from "./claude-integration.js";
 import { fileURLToPath } from "url";
 // ---------------------------------------------------------------------------
@@ -2233,7 +2234,7 @@ async function cliEndSession() {
     // --- Check 3b: running servers ([LOCK] [SERVERS-ARE-INVENTORIED]) ---
     checks.push("## 3b. Running servers\n");
     const fleet = listServers();
-    checks.push("```\n" + formatServers(fleet) + "\n```");
+    checks.push("```\n" + formatServers(fleet) + "\n" + formatFleetHealth(computeFleetHealth({ version: readPackageVersion(), report: fleet })) + "\n```");
     if (fleet.warnings.length > 0)
         failCount += fleet.warnings.length;
     checks.push("");
@@ -2742,8 +2743,10 @@ else if (command === "audit-rotate") {
 }
 else if (command === "servers") {
     const fleet = listServers();
+    const health = computeFleetHealth({ version: readPackageVersion(), report: fleet });
     console.log(formatServers(fleet, undefined, { cost: process.argv.includes("--cost") }));
-    process.exit(fleet.warnings.length > 0 ? 1 : 0);
+    console.log(formatFleetHealth(health));
+    process.exit(fleet.warnings.length > 0 || health.warnings.length > 0 ? 1 : 0);
 }
 else if (command === "audit-verify") {
     cliAuditVerify().catch((err) => {

package/dist/fleet-health.d.ts

@@ -0,0 +1,57 @@
+import { type ServerReport } from "./server-registry.js";
+export interface FleetHealth {
+    generatedAt: string;
+    version: string;
+    writerPid: number;
+    servers: {
+        total: number;
+        indexers: number;
+        readers: number;
+        /** Servers whose loaded build differs from the file on disk. */
+        stale: Array<{
+            pid: number;
+            version: string;
+            build: string;
+            cwd: string;
+        }>;
+        diskBuild: string | null;
+    };
+    reindex: {
+        /** Shared-index writes in the last hour, all corpora. */
+        lastHourWrites: number;
+        perCorpus: Record<string, number>;
+        /** Above this many writes per hour a warning is raised. */
+        threshold: number;
+    };
+    today: {
+        /** Pre-commit blocks (hook.block) since local midnight. */
+        blocks: number;
+        /** Store refusals (unreadable, shrink refused, growth refused) since local midnight. */
+        refusals: number;
+        learningsSaved: number;
+        /** Newest last: time, kind, one-line detail. */
+        lastBlocks: Array<{
+            ts: string;
+            kind: string;
+            detail: string;
+        }>;
+    };
+    /** The newest release for which verify-release passed on this machine, or null. */
+    lastVerifiedRelease: string | null;
+    /** Measured problems only. Empty means green. */
+    warnings: string[];
+}
+export declare const REINDEX_PER_HOUR_WARN = 30;
+export declare function fleetHealthPath(): string;
+/** The highest version with a verify-release marker; version order, not file time (ties). */
+export declare function lastVerifiedRelease(dir?: string): string | null;
+export declare function computeFleetHealth(opts?: {
+    now?: Date;
+    version?: string;
+    auditPath?: string;
+    report?: ServerReport;
+}): FleetHealth;
+/** Temp file + rename: a reader never sees half a file. */
+export declare function writeFleetHealth(h: FleetHealth): string;
+export declare function formatFleetHealth(h: FleetHealth): string;
+//# sourceMappingURL=fleet-health.d.ts.map

package/dist/fleet-health.js

@@ -0,0 +1,172 @@
+// [LOCKED] [HEALTH-IS-MEASURED-NEVER-ESTIMATED] 2026-09-06
+// [NEVER] put a number in this file that comes from a timer, a multiplier or a guess; every
+//         field is counted from the audit log, the server registry, git, or a file on disk.
+// WHY: the VS Code status bar showed "CE SAVE SESSION" in yellow on a wall-clock timer and
+//      "~N min saved" from a multiplier nobody could check (Session 25 item 4). Meanwhile the
+//      real problems of 2026-09-05 (eleven servers re-embedding, load average 230; two servers
+//      on a stale build re-importing 1,766 records; a store growth of 1,766 in one minute) had no
+//      surface at all. A nag without evidence trains the user to ignore the bar; a fact does not.
+// FIX: one function computes the fleet's health from evidence, one writer (the indexer) drops
+//      it into ~/.contextengine/fleet-health.json every minute, and every surface (servers CLI,
+//      end-session, the status bar) reads the same file. Warnings list measured problems only.
+import { closeSync, existsSync, fstatSync, mkdirSync, openSync, readSync, readdirSync, renameSync, writeFileSync } from "fs";
+import { join } from "path";
+import { homedir } from "os";
+import { listServers } from "./server-registry.js";
+export const REINDEX_PER_HOUR_WARN = 30;
+const TAIL_BYTES = 8 * 1024 * 1024;
+function ceHome() {
+    return process.env.CONTEXTENGINE_HOME || join(homedir(), ".contextengine");
+}
+export function fleetHealthPath() {
+    return join(ceHome(), "fleet-health.json");
+}
+/** The last `bytes` of a file as complete lines (the first partial line is dropped). */
+function tailLines(path, bytes) {
+    if (!existsSync(path))
+        return [];
+    let fd = null;
+    try {
+        fd = openSync(path, "r");
+        const size = fstatSync(fd).size;
+        const start = Math.max(0, size - bytes);
+        const buf = Buffer.alloc(size - start);
+        readSync(fd, buf, 0, buf.length, start);
+        let text = buf.toString("utf8");
+        if (start > 0) {
+            const nl = text.indexOf("\n");
+            text = nl === -1 ? "" : text.slice(nl + 1);
+        }
+        return text.split("\n").filter(Boolean);
+    }
+    catch {
+        return [];
+    }
+    finally {
+        if (fd !== null)
+            closeSync(fd);
+    }
+}
+function parseRecords(lines) {
+    const out = [];
+    for (const l of lines) {
+        try {
+            const r = JSON.parse(l);
+            if (r && typeof r.ts === "string" && typeof r.event === "string")
+                out.push(r);
+        }
+        catch {
+            /* a torn line, ignored */
+        }
+    }
+    return out;
+}
+function localMidnight(now) {
+    const d = new Date(now);
+    d.setHours(0, 0, 0, 0);
+    return d;
+}
+function blockDetail(p = {}) {
+    const check = String(p.check ?? "block");
+    if (p.file)
+        return `${check}: ${String(p.file)}${p.line ? `:${String(p.line)}` : ""}${p.pattern_id ? ` (${String(p.pattern_id)})` : ""}`;
+    if (p.requires_section)
+        return `${check}: ${String(p.requires_section)}`;
+    if (p.reason)
+        return `${check}: ${String(p.reason)}`;
+    return check;
+}
+/** The highest version with a verify-release marker; version order, not file time (ties). */
+export function lastVerifiedRelease(dir = ceHome()) {
+    let files = [];
+    try {
+        files = readdirSync(dir);
+    }
+    catch {
+        return null;
+    }
+    const versions = files.map((f) => /^verified-(\d+\.\d+\.\d+)$/.exec(f)?.[1]).filter((v) => !!v);
+    if (versions.length === 0)
+        return null;
+    const key = (v) => v.split(".").map(Number);
+    versions.sort((a, b) => { const x = key(a), y = key(b); return (x[0] - y[0]) || (x[1] - y[1]) || (x[2] - y[2]); });
+    return versions[versions.length - 1];
+}
+export function computeFleetHealth(opts = {}) {
+    const now = opts.now ?? new Date();
+    const report = opts.report ?? listServers();
+    const audit = opts.auditPath ?? join(ceHome(), "audit.log");
+    const records = parseRecords(tailLines(audit, TAIL_BYTES));
+    const midnight = localMidnight(now).getTime();
+    const hourAgo = now.getTime() - 3_600_000;
+    const perCorpus = {};
+    let lastHourWrites = 0, blocks = 0, refusals = 0, learningsSaved = 0;
+    const lastBlocks = [];
+    for (const r of records) {
+        const t = Date.parse(r.ts);
+        if (Number.isNaN(t))
+            continue;
+        if (r.event === "index.write" && t >= hourAgo) {
+            lastHourWrites++;
+            const c = String(r.payload?.corpus ?? "?");
+            perCorpus[c] = (perCorpus[c] ?? 0) + 1;
+        }
+        if (t < midnight)
+            continue;
+        if (r.event === "hook.block") {
+            blocks++;
+            lastBlocks.push({ ts: r.ts, kind: "pre-commit", detail: blockDetail(r.payload) });
+        }
+        else if (r.event === "learning.store_unreadable" || r.event === "learning.store_shrink_refused" || r.event === "learning.store_growth_refused") {
+            refusals++;
+            lastBlocks.push({ ts: r.ts, kind: "store", detail: r.event.replace("learning.store_", "").replace(/_/g, " ") });
+        }
+        else if (r.event === "learning.save" && r.payload?.mode !== "update")
+            learningsSaved++; // a sweep's updates are not saves
+    }
+    const stale = report.servers.filter((s) => s.staleBuild).map((s) => ({ pid: s.pid, version: s.version, build: s.build, cwd: s.cwd }));
+    const diskBuild = report.servers.find((s) => s.currentBuild)?.currentBuild ?? null;
+    const indexers = report.servers.filter((s) => s.role !== "reader").length;
+    const warnings = [];
+    if (stale.length > 0)
+        warnings.push(`${stale.length} server(s) on an old build (pid ${stale.map((s) => s.pid).join(", ")}): reload their windows`);
+    if (lastHourWrites > REINDEX_PER_HOUR_WARN)
+        warnings.push(`${lastHourWrites} shared-index writes in the last hour (ceiling ${REINDEX_PER_HOUR_WARN}): something saves in a loop`);
+    if (refusals > 0)
+        warnings.push(`${refusals} learnings-store refusal(s) today: a write looked like a wipe or a runaway import`);
+    for (const w of report.warnings)
+        if (/index on their own/.test(w))
+            warnings.push(w);
+    return {
+        generatedAt: now.toISOString(),
+        version: opts.version ?? "unknown",
+        writerPid: process.pid,
+        servers: { total: report.servers.length, indexers, readers: report.servers.length - indexers, stale, diskBuild },
+        reindex: { lastHourWrites, perCorpus, threshold: REINDEX_PER_HOUR_WARN },
+        today: { blocks, refusals, learningsSaved, lastBlocks: lastBlocks.slice(-3) },
+        lastVerifiedRelease: lastVerifiedRelease(),
+        warnings,
+    };
+}
+/** Temp file + rename: a reader never sees half a file. */
+export function writeFleetHealth(h) {
+    const path = fleetHealthPath();
+    mkdirSync(join(path, ".."), { recursive: true });
+    const tmp = `${path}.tmp-${process.pid}`;
+    writeFileSync(tmp, JSON.stringify(h, null, 2) + "\n");
+    renameSync(tmp, path);
+    return path;
+}
+export function formatFleetHealth(h) {
+    const lines = [];
+    lines.push(`health: ${h.warnings.length === 0 ? "green" : `${h.warnings.length} measured problem(s)`}  (v${h.version}, last verified release ${h.lastVerifiedRelease ?? "none"}, ${h.generatedAt.slice(11, 19)}Z)`);
+    lines.push(`  servers ${h.servers.total}: ${h.servers.indexers} indexing, ${h.servers.readers} reading, ${h.servers.stale.length} on an old build`);
+    lines.push(`  shared-index writes last hour: ${h.reindex.lastHourWrites} (ceiling ${h.reindex.threshold})`);
+    lines.push(`  today: ${h.today.blocks} block(s) prevented, ${h.today.refusals} store refusal(s), ${h.today.learningsSaved} learning(s) saved`);
+    for (const b of h.today.lastBlocks)
+        lines.push(`    ${b.ts.slice(11, 19)}Z ${b.kind}: ${b.detail}`);
+    for (const w of h.warnings)
+        lines.push(`  ⚠ ${w}`);
+    return lines.join("\n");
+}
+//# sourceMappingURL=fleet-health.js.map

package/dist/index.js

@@ -13,6 +13,7 @@ import { listProjects, checkPorts, runComplianceAudit, formatProjectList, format
 import { saveSession, loadSession, listSessions, deleteSession, formatSession, formatSessionList, } from "./sessions.js";
 import { verifyChain, readAuditLog, filterByRange, autoRotateAuditLog, safeAppend } from "./audit.js";
 import { registerServer, listServers, formatServers } from "./server-registry.js";
+import { computeFleetHealth, writeFleetHealth } from "./fleet-health.js";
 import { startEventIngestServer } from "./http-server.js";
 import { detect } from "./detector.js";
 import { buildCostReport } from "./cost-report.js";
@@ -210,7 +211,7 @@ function publishIndex() {
             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 });
+        safeAppend("index.write", { pid: process.pid, 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) {
@@ -422,11 +423,39 @@ function evaluateRole(reason) {
         startIndexPolling();
     }
 }
+let healthTick = 0;
+let lastStaleCount = -1;
+/**
+ * The indexer writes ~/.contextengine/fleet-health.json once a minute: version drift, reindex
+ * rate, today's blocks and refusals, the last verified release. Every surface reads that file.
+ * [LOCK] [HEALTH-IS-MEASURED-NEVER-ESTIMATED]
+ */
+function publishHealth() {
+    try {
+        const h = computeFleetHealth({ version: PKG_VERSION });
+        if (h.servers.stale.length !== lastStaleCount) {
+            lastStaleCount = h.servers.stale.length;
+            if (lastStaleCount > 0)
+                console.error(`[ContextEngine] 🧭 ${lastStaleCount} server(s) on an old build: pid ${h.servers.stale.map((s) => s.pid).join(", ")}`);
+        }
+        if (role === "indexer")
+            writeFleetHealth(h);
+    }
+    catch (err) {
+        console.error(`[ContextEngine] ⚠ fleet health failed: ${err.message}`);
+    }
+}
 function startRolePolling() {
-    if (rolePoll || !corpus)
+    if (rolePoll)
         return;
-    rolePoll = setInterval(() => evaluateRole("periodic"), ROLE_POLL_MS);
+    rolePoll = setInterval(() => {
+        if (corpus)
+            evaluateRole("periodic");
+        if (++healthTick % 4 === 0)
+            publishHealth(); // every 60 s
+    }, ROLE_POLL_MS);
     rolePoll.unref();
+    setTimeout(publishHealth, 5_000).unref();
 }
 // ---------------------------------------------------------------------------
 // MCP Server

package/package.json

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