@compr/opscontext-mcp 2.0.2 → 2.1.0

package/CHANGELOG.md

@@ -2,6 +2,49 @@
 
 All notable changes to OpsContext for AI Agents (previously ContextEngine — MCP server + CLI) are documented here.
 
+## [2.1.0] — 2026-06-23 — Phase 1: cross-surface capture + drift detector + local event ingest
+
+The first feature release after the OpsContext rebrand. Closes the wedge the audit identified: **no other tool captures AI interactions across browser + IDE + terminal and feeds them into a tamper-evident audit log with policy enforcement**. Now we do.
+
+### Added
+- **`src/http-server.ts`** (LOCK `[HTTP-EVENT-INGEST]`) — local event-ingest HTTP endpoint at `http://127.0.0.1:7842`. The browser extension and the VS Code extension POST batched events here; the MCP server validates and appends them to the existing hash-chained audit log via `safeAppend()`.
+  - `POST /events` — schema-validated batched events (max 50 events, 64 KB body). Event-kind allowlist: `^(browser|vscode|cli)\.` — system kinds like `learning.save` can only come from the local writer, never the network. Auth via shared 32-byte hex secret at `~/.contextengine/extension-secret` (mode 0600), compared in constant time.
+  - `GET /health` — unauthenticated liveness probe.
+  - Bound to `127.0.0.1` ONLY — never `0.0.0.0`. LAN devices cannot inject audit events.
+  - Hot-reload of the secret on every request — `init-extension-secret --force` rotates without restarting MCP.
+  - Started automatically at MCP boot. Gracefully degrades on port conflict (`OPSCONTEXT_EVENT_PORT=<n>` to override).
+- **`src/detector.ts`** (LOCK `[DRIFT-HEURISTICS]`) — 8-heuristic drift / loop / fabrication detector.
+  - **loop** (warn): same prompt sent 3+ times in 5 min (Jaccard > 0.6 token overlap)
+  - **stuck** (warn): identical tool call 3+ times in 5 min
+  - **context_bloat** (warn): session > 80K tokens with no `session.save` event
+  - **fabrication_suspect** (critical): assistant response cites `file.ext:NN` that doesn't exist on disk
+  - **drift** (info): per-session, last 3 prompts have joint Jaccard < 0.10 against the session's first prompt
+  - **no_insight** (info): 30+ tool calls since the last `learning.save`
+  - **silent_failure** (critical): same tool returns error 3+ times in 5 min
+  - **stale_doc_signal**: stubbed (Phase 3.1; reads `policy.json` `doc_coverage`)
+  - `watchAuditLog()` uses `fs.watch` + 250 ms debounce + in-memory LRU dedupe (100 entries) so the same signal doesn't fire every poll cycle.
+  - Auto-emits `drift.detected` audit records for each fired signal — alerting itself is auditable.
+- **`contextengine watch`** CLI — streams alerts as they fire. Supports `--json` (NDJSON for log aggregators), `--severity info|warn|critical` (floor filter), `--once` (single-scan exit, code 2 if any critical signal — usable in CI), `--window SECONDS`.
+- **`contextengine init-extension-secret`** CLI — generates a 32-byte hex secret at `~/.contextengine/extension-secret` (mode 0600). Refuses by default if one already exists (`--force` to rotate).
+- **`contextengine emit-event <kind> <payload-json> [--actor NAME]`** CLI — appends a single event to the audit log. Used by the VS Code extension `0.9.0` for `vscode.prompt_submit` and `vscode.tool_call` events. Also useful for custom integrations and scripted tests.
+- **`drift_status` MCP tool** — agents can call this between major task phases to self-check active signals. Returns "pause and surface to the human" guidance if any critical signal is active.
+
+### Audit-log event types added (additive — no breaking changes)
+- `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`
+
+### Tests
+- **14 new tests** in `tests/detector.test.ts` with 11 hand-written NDJSON fixtures in `tests/__fixtures__/audit-logs/`. One catalog test per heuristic + its negative ("similar prompts" fires loop; "different prompts" doesn't). Plus 2 integration tests on `detect()` and evidence cap.
+- **196 / 196 tests passing total** (was 182).
+
+### Companion release
+- **`@compr/opscontext-chrome@0.1.0`** — new Chrome extension scaffold under `chrome-extension/`. Captures Claude.ai + ChatGPT prompts/responses/tool-calls, streams them via the new `POST /events` endpoint. Not yet on the Chrome Web Store; loadable unpacked via `chrome://extensions` → Developer mode → "Load unpacked" → pick `chrome-extension/dist/`. BSL-1.1 license; selector seeds attributed to MIT prior art in `chrome-extension/LICENSE_THIRD_PARTY.md`.
+- **`css-llc.contextengine@0.9.0`** — VS Code extension companion release that emits `vscode.prompt_submit` and `vscode.tool_call` events into the audit log via the new `emit-event` CLI.
+
+### Day-1 test plan
+[`docs/test-plans/PHASE1_DAY1.md`](docs/test-plans/PHASE1_DAY1.md) — 10-step, ~15-minute end-to-end verification. Starts with `init-extension-secret`, ends with deliberate `fabrication_suspect` + `silent_failure` triggers verifying `watch` exits code 2.
+
 ## [2.0.2] — 2026-06-11 — HTML score report browser tab title → OpsContext
 
 Tiny patch release. One change:

package/dist/audit.d.ts

@@ -1,4 +1,4 @@
-export type AuditEvent = "learning.save" | "learning.delete" | "learning.import" | "session.save" | "session.delete" | "activation.activate" | "activation.deactivate" | "activation.heartbeat" | "activation.signature_reject" | "activation.legacy_signature" | "firewall.escalate" | "hook.block" | "hook.bypass";
+export type AuditEvent = "learning.save" | "learning.delete" | "learning.import" | "session.save" | "session.delete" | "activation.activate" | "activation.deactivate" | "activation.heartbeat" | "activation.signature_reject" | "activation.legacy_signature" | "firewall.escalate" | "hook.block" | "hook.bypass" | "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";
 export interface AuditRecord {
     ts: string;
     event: AuditEvent;

package/dist/cli.js

@@ -1212,6 +1212,193 @@ tamper-evident audit log at ~/.contextengine/audit.log.`);
     console.error(`Unknown hook subcommand: ${sub}. Try 'contextengine hook --help'.`);
     process.exit(1);
 }
+async function cliEmitEvent(args) {
+    const { safeAppend } = await import("./audit.js");
+    const help = args.includes("-h") || args.includes("--help");
+    if (help || args.length < 2) {
+        console.log(`Usage: contextengine emit-event <event-kind> <payload-json> [--actor NAME]
+
+Appends a single event to the hash-chained audit log. Useful for VS Code
+extensions, custom integrations, or scripted test scenarios.
+
+  event-kind    One of: browser.* / vscode.* / cli.* / learning.* / etc.
+  payload-json  A JSON object describing the event. Will be validated as
+                a Record<string, unknown>.
+  --actor NAME  Override the actor field. Defaults to 'cli'.
+
+Examples:
+  contextengine emit-event vscode.tool_call '{"tool":"Edit","args_preview":"file=src/x.ts"}'
+  contextengine emit-event browser.prompt   '{"surface":"claude.ai","text":"hello","char_count":5}' --actor browser-ext
+
+The event becomes a regular audit-chain record (prev_hash + hash added by
+safeAppend), visible via 'contextengine audit-verify' and consumed by the
+'contextengine watch' detector + 'drift_status' MCP tool.`);
+        process.exit(help ? 0 : 1);
+    }
+    const eventKind = args[0];
+    const payloadJson = args[1];
+    let actor = "cli";
+    for (let i = 2; i < args.length; i++) {
+        if (args[i] === "--actor" && args[i + 1])
+            actor = args[++i];
+    }
+    let payload;
+    try {
+        const parsed = JSON.parse(payloadJson);
+        if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+            throw new Error("payload must be a JSON object (not array, not primitive)");
+        }
+        payload = parsed;
+    }
+    catch (e) {
+        console.error(`Bad payload JSON: ${e instanceof Error ? e.message : String(e)}`);
+        process.exit(1);
+    }
+    // Cast — the audit module accepts any string for the event field; the
+    // AuditEvent union is documentation, not enforcement. Validation of
+    // "what's a valid event kind" is the caller's responsibility (the HTTP
+    // server enforces a prefix allow-list; this CLI is trusted).
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    safeAppend(eventKind, payload, actor);
+    console.log(`✅ Appended ${eventKind} to audit log.`);
+}
+async function cliWatch(args) {
+    const { watchAuditLog, detect } = await import("./detector.js");
+    let jsonMode = false;
+    let once = false;
+    let minSeverity = "info";
+    let windowSeconds = 300;
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i];
+        if (a === "--json")
+            jsonMode = true;
+        else if (a === "--once")
+            once = true;
+        else if (a === "--severity" && args[i + 1]) {
+            const sev = args[++i];
+            if (sev !== "info" && sev !== "warn" && sev !== "critical") {
+                console.error(`Unknown severity: ${sev}. Try info|warn|critical.`);
+                process.exit(1);
+            }
+            minSeverity = sev;
+        }
+        else if (a === "--window" && args[i + 1]) {
+            windowSeconds = parseInt(args[++i], 10) || 300;
+        }
+        else if (a === "-h" || a === "--help") {
+            console.log(`Usage: contextengine watch [--json] [--severity info|warn|critical] [--once] [--window SECONDS]
+
+Streams drift / hallucination / loop / stuck-tool / context-bloat alerts as
+they're detected in ~/.contextengine/audit.log.
+
+  --json              One line of NDJSON per alert (for log aggregators / jq).
+  --severity X        Floor filter. Default: info (everything).
+  --once              Run a single scan over the recent window and exit.
+                      Good for cron / health checks.
+  --window SECONDS    How far back to scan in --once mode. Default: 300.
+
+Exit codes:
+  0   clean (or --once found no critical signals)
+  2   --once found at least one critical signal — useful in CI pipelines
+
+Signals also append a 'drift.detected' record to the audit log (hash-chained)
+so the alerting itself is auditable.
+
+Status-bar / OS-notification integration is via the VS Code extension —
+this CLI is for terminal users, CI, and cron.`);
+            return;
+        }
+    }
+    const sevOrder = { info: 0, warn: 1, critical: 2 };
+    const passesFilter = (s) => sevOrder[s.severity] >= sevOrder[minSeverity];
+    const fmt = (s) => {
+        if (jsonMode) {
+            return JSON.stringify({
+                ts: new Date(s.detectedAt).toISOString(),
+                kind: s.kind,
+                severity: s.severity,
+                reason: s.reason,
+                payload: s.payload,
+            });
+        }
+        const sev = s.severity === "critical" ? "CRIT " : s.severity === "warn" ? "WARN " : "INFO ";
+        const t = new Date(s.detectedAt).toISOString().slice(11, 19);
+        return `[${t}] ${sev} ${s.kind.padEnd(20)} ${s.reason}`;
+    };
+    if (once) {
+        const signals = detect({ windowSeconds }).filter(passesFilter);
+        for (const s of signals) {
+            console.log(fmt(s));
+        }
+        const hasCritical = signals.some((s) => s.severity === "critical");
+        process.exit(hasCritical ? 2 : 0);
+    }
+    if (!jsonMode) {
+        console.error("[opscontext watch] streaming drift signals (Ctrl-C to exit)…");
+    }
+    const dispose = watchAuditLog((s) => {
+        if (passesFilter(s))
+            console.log(fmt(s));
+    }, { windowSeconds });
+    process.on("SIGINT", () => {
+        dispose();
+        if (!jsonMode)
+            console.error("\n[opscontext watch] stopped.");
+        process.exit(0);
+    });
+    // Keep alive — the watcher uses internal timers, but a stdin listener also
+    // helps catch terminal closes.
+    process.stdin.resume();
+}
+async function cliInitExtensionSecret(args) {
+    const force = args.includes("--force") || args.includes("-f");
+    const help = args.includes("-h") || args.includes("--help");
+    if (help) {
+        console.log(`Usage: contextengine init-extension-secret [--force]
+
+Generates a 32-byte hex token at ~/.contextengine/extension-secret (mode 0600)
+and prints it to stdout. The OpsContext browser extension reads the same
+token from its options page; both sides must match for events to flow.
+
+  --force, -f   Overwrite an existing secret. Default is to refuse if one
+                already exists (prevents accidental rotation that would
+                disconnect the extension until it's re-pasted).
+
+After running, paste the printed value into the extension's Options page
+(Cmd+Shift+P → "Open extension options" in Chrome, or click the extension
+icon → Options).`);
+        return;
+    }
+    const { randomBytes } = await import("crypto");
+    const { writeFileSync, existsSync, chmodSync, mkdirSync } = await import("fs");
+    const { join } = await import("path");
+    const { homedir } = await import("os");
+    const dir = join(homedir(), ".contextengine");
+    const path = join(dir, "extension-secret");
+    if (existsSync(path) && !force) {
+        console.error(`❌ ${path} already exists. Re-running would invalidate any extension that already has the old value pasted in.\n` +
+            `\n` +
+            `   Pass --force to rotate (you'll need to re-paste the new value in the extension's Options page).\n` +
+            `   Or read the current secret with: cat ${path}`);
+        process.exit(1);
+    }
+    mkdirSync(dir, { recursive: true });
+    const secret = randomBytes(32).toString("hex");
+    writeFileSync(path, secret + "\n", { mode: 0o600 });
+    try {
+        chmodSync(path, 0o600);
+    }
+    catch { /* best-effort */ }
+    console.log(`✅ Wrote ${path} (mode 600)\n`);
+    console.log(`Secret (paste this into the browser extension's Options page):\n`);
+    console.log(`  ${secret}\n`);
+    console.log(`Next steps:`);
+    console.log(`  1. Open Chrome → chrome://extensions → Find "OpsContext Browser Capture"`);
+    console.log(`  2. Click "Options" → paste the secret → Save`);
+    console.log(`  3. Visit https://claude.ai or https://chatgpt.com — events will flow.`);
+    console.log(`\nThe MCP server's event-ingest endpoint is at http://127.0.0.1:7842/events`);
+    console.log(`(GET /health to verify it's running).`);
+}
 async function cliPolicy(args) {
     const sub = args[0];
     if (!sub || sub === "-h" || sub === "--help") {
@@ -1595,6 +1782,12 @@ Usage:
   contextengine audit-verify           Verify audit log chain integrity (tamper detection)
   contextengine policy <validate|show> [args]
                                        Author + validate the declarative .contextengine/policy.json
+  contextengine init-extension-secret [--force]
+                                       Generate ~/.contextengine/extension-secret for the browser ext
+  contextengine watch [--json] [--severity info|warn|critical] [--once] [--window SECONDS]
+                                       Stream drift / loop / stuck-tool / fabrication alerts from the audit log
+  contextengine emit-event <kind> <payload-json> [--actor NAME]
+                                       Append a single event to the audit log (for integrations / scripted tests)
   contextengine hook <secret-scan|doc-coverage>
                                        Run policy-driven pre-commit checks against staged diff
                                        (exit 1 on blocking violation; CE_JSON=1 for CI output)
@@ -1793,6 +1986,24 @@ else if (command === "activate") {
         process.exit(1);
     });
 }
+else if (command === "emit-event") {
+    cliEmitEvent(process.argv.slice(3)).catch((err) => {
+        console.error("Error:", err);
+        process.exit(1);
+    });
+}
+else if (command === "watch") {
+    cliWatch(process.argv.slice(3)).catch((err) => {
+        console.error("Error:", err);
+        process.exit(1);
+    });
+}
+else if (command === "init-extension-secret") {
+    cliInitExtensionSecret(process.argv.slice(3)).catch((err) => {
+        console.error("Error:", err);
+        process.exit(1);
+    });
+}
 else if (command === "stats") {
     cliStats();
 }

package/dist/detector.d.ts

@@ -0,0 +1,64 @@
+import { type AuditRecord, type AuditEvent } from "./audit.js";
+export type DriftKind = "loop" | "stuck" | "context_bloat" | "fabrication_suspect" | "drift" | "no_insight" | "stale_doc_signal" | "silent_failure";
+export type Severity = "info" | "warn" | "critical";
+export interface DriftSignal {
+    kind: DriftKind;
+    severity: Severity;
+    reason: string;
+    evidence: AuditRecord[];
+    payload: Record<string, unknown>;
+    detectedAt: number;
+}
+export interface DetectorOptions {
+    /** Window in seconds for event scan. Default 300 (5 min). */
+    windowSeconds?: number;
+    /** Inject a "now" for deterministic tests. */
+    now?: number;
+    /** Inject the events instead of reading from disk (for tests). */
+    events?: AuditRecord[];
+    /** Project root for fabrication_suspect file-existence checks. */
+    cwd?: string;
+}
+export declare function scanRecentEvents(windowSeconds?: number, now?: number): AuditRecord[];
+/** Tokenize text for cheap similarity comparisons (Jaccard / BM25-lite). */
+export declare function tokens(s: string): Set<string>;
+export declare function jaccard(a: Set<string>, b: Set<string>): number;
+declare function detectLoop(events: AuditRecord[]): DriftSignal | null;
+declare function detectStuck(events: AuditRecord[], now: number): DriftSignal | null;
+declare function detectContextBloat(events: AuditRecord[]): DriftSignal | null;
+declare function detectFabrication(events: AuditRecord[], cwd: string): DriftSignal | null;
+declare function detectDrift(events: AuditRecord[]): DriftSignal | null;
+declare function detectNoInsight(events: AuditRecord[]): DriftSignal | null;
+declare function detectSilentFailure(events: AuditRecord[], now: number): DriftSignal | null;
+declare function detectStaleDocSignal(_events: AuditRecord[]): DriftSignal | null;
+export declare function runHeuristics(events: AuditRecord[], opts?: {
+    now?: number;
+    cwd?: string;
+}): DriftSignal[];
+/** Convenience for callers: scan recent events and run heuristics in one call. */
+export declare function detect(opts?: DetectorOptions): DriftSignal[];
+/**
+ * Watch the audit log and fire `onAlert` for each new signal. Dedupe key is
+ * `kind:reason` kept in an in-memory LRU bounded at 100 entries — prevents
+ * the same drift from firing every poll cycle.
+ *
+ * Returns a dispose function. Caller is responsible for handling SIGINT
+ * cleanly.
+ */
+export declare function watchAuditLog(onAlert: (s: DriftSignal) => void, opts?: {
+    windowSeconds?: number;
+    debounceMs?: number;
+    emitAuditEvent?: boolean;
+}): () => void;
+export declare const _internal: {
+    detectLoop: typeof detectLoop;
+    detectStuck: typeof detectStuck;
+    detectContextBloat: typeof detectContextBloat;
+    detectFabrication: typeof detectFabrication;
+    detectDrift: typeof detectDrift;
+    detectNoInsight: typeof detectNoInsight;
+    detectSilentFailure: typeof detectSilentFailure;
+    detectStaleDocSignal: typeof detectStaleDocSignal;
+};
+export type { AuditRecord, AuditEvent };
+//# sourceMappingURL=detector.d.ts.map

package/dist/detector.js

@@ -0,0 +1,336 @@
+// 🔒 LOCKED [DRIFT-HEURISTICS] — 2026-06-23
+// ⛔ NEVER make a heuristic fire on a single event in isolation. Every
+//    heuristic looks at a WINDOW of events. Single-event triggers will
+//    fire on the user's normal workflow and burn trust in the alerts.
+// ⛔ NEVER raise a critical severity from a heuristic without a corresponding
+//    audit event (drift.detected with full payload). Critical = OS
+//    notification + interrupt — the audit trail is what the user reviews
+//    after-the-fact to understand WHY the alert fired.
+// ⛔ NEVER trust the assistant's claim that something exists in the file
+//    system. The fabrication_suspect check is precisely about catching
+//    those claims. If you add helpers, default to "verify against fs".
+// WHY: Drift alerts have to be precise. False positives train users to
+//    ignore the status bar, defeating the entire purpose. Conservative
+//    thresholds + window-based detection + auditable trail are the
+//    discipline that earns user trust.
+// FIX: To add a new heuristic, copy the shape of detectLoop or detectStuck,
+//    keep the predicate pure (no I/O except fs.existsSync), append it to
+//    HEURISTICS at the bottom, and add a fixture to tests/__fixtures__/
+//    audit-logs/.
+import { readAuditLog, safeAppend } from "./audit.js";
+import { watch, existsSync } from "fs";
+import { join, isAbsolute } from "path";
+import { homedir } from "os";
+// ─── Window scan ───────────────────────────────────────────────────────────
+export function scanRecentEvents(windowSeconds = 300, now = Date.now()) {
+    let all;
+    try {
+        all = readAuditLog();
+    }
+    catch {
+        return [];
+    }
+    const cutoff = now - windowSeconds * 1000;
+    return all.filter((r) => {
+        const ts = Date.parse(r.ts);
+        return Number.isFinite(ts) && ts >= cutoff;
+    });
+}
+// ─── Helpers ───────────────────────────────────────────────────────────────
+/** Tokenize text for cheap similarity comparisons (Jaccard / BM25-lite). */
+export function tokens(s) {
+    return new Set(String(s || "")
+        .toLowerCase()
+        .replace(/[^\p{L}\p{N}\s]+/gu, " ")
+        .split(/\s+/)
+        .filter((t) => t.length > 2));
+}
+export function jaccard(a, b) {
+    if (a.size === 0 && b.size === 0)
+        return 1;
+    if (a.size === 0 || b.size === 0)
+        return 0;
+    let intersect = 0;
+    for (const t of a)
+        if (b.has(t))
+            intersect++;
+    return intersect / (a.size + b.size - intersect);
+}
+function groupBy(arr, keyFn) {
+    const m = new Map();
+    for (const x of arr) {
+        const k = keyFn(x);
+        const list = m.get(k) || [];
+        list.push(x);
+        m.set(k, list);
+    }
+    return m;
+}
+function stableStringify(v) {
+    if (v === null || typeof v !== "object")
+        return JSON.stringify(v);
+    if (Array.isArray(v))
+        return "[" + v.map(stableStringify).join(",") + "]";
+    const keys = Object.keys(v).sort();
+    return "{" + keys.map((k) => JSON.stringify(k) + ":" + stableStringify(v[k])).join(",") + "}";
+}
+function getText(r) {
+    const p = r.payload || {};
+    return String(p.text ?? p.preview ?? p.args_preview ?? "");
+}
+function sessionKey(r) {
+    const p = r.payload || {};
+    return String(p.conversation_id ?? p.session_name ?? p.session ?? "default");
+}
+function mk(kind, severity, reason, evidence, payload) {
+    return {
+        kind,
+        severity,
+        reason,
+        evidence: evidence.slice(0, 5),
+        payload,
+        detectedAt: Date.now(),
+    };
+}
+// ─── Heuristics ────────────────────────────────────────────────────────────
+function detectLoop(events) {
+    const prompts = events
+        .filter((e) => e.event === "browser.prompt" || e.event === "vscode.prompt_submit")
+        .slice(-10);
+    for (let i = 0; i < prompts.length; i++) {
+        let dupes = 0;
+        const matches = [prompts[i]];
+        const ti = tokens(getText(prompts[i]));
+        if (ti.size === 0)
+            continue;
+        for (let j = i + 1; j < prompts.length; j++) {
+            const tj = tokens(getText(prompts[j]));
+            // 0.6 Jaccard ≈ 60% token overlap. Lower than initially gut-felt
+            // because real prompt loops include "let me rephrase" wording shifts
+            // that drop overlap quickly. 0.85 missed the "fix login bug" /
+            // "login bug fix please" pattern; 0.6 catches it without falsing on
+            // genuinely different prompts that happen to share verbs.
+            if (jaccard(ti, tj) > 0.6 &&
+                Date.parse(prompts[j].ts) - Date.parse(prompts[i].ts) < 300_000) {
+                dupes++;
+                matches.push(prompts[j]);
+            }
+        }
+        if (dupes >= 2) {
+            const snippet = getText(prompts[i]).slice(0, 80);
+            return mk("loop", "warn", `Same prompt sent ${dupes + 1}× in 5 min`, matches, { repetitions: dupes + 1, snippet });
+        }
+    }
+    return null;
+}
+function detectStuck(events, now) {
+    const calls = events.filter((e) => e.event === "browser.tool_call" || e.event === "vscode.tool_call");
+    // 5-minute window. The "3 identical calls in a row" pattern usually plays
+    // out over a few minutes — the user retries, waits, retries, gives up,
+    // retries again. 2 min was too tight for normal LLM-agent rhythms.
+    const recent = calls.filter((c) => now - Date.parse(c.ts) < 300_000);
+    const byKey = groupBy(recent, (c) => {
+        const p = c.payload || {};
+        return `${p.tool}:${stableStringify(p.args ?? p.args_preview ?? "")}`;
+    });
+    for (const group of byKey.values()) {
+        if (group.length >= 3) {
+            const tool = String(group[0].payload?.tool ?? "unknown");
+            return mk("stuck", "warn", `Tool ${tool} called ${group.length}× with identical args in 2 min`, group, { tool, count: group.length, args_preview: String(group[0].payload?.args_preview ?? "") });
+        }
+    }
+    return null;
+}
+function detectContextBloat(events) {
+    const bySession = groupBy(events, sessionKey);
+    for (const [sid, group] of bySession) {
+        let tokensSum = 0;
+        let hasSave = false;
+        for (const e of group) {
+            const p = e.payload || {};
+            if (typeof p.tokens === "number")
+                tokensSum += p.tokens;
+            else if (typeof p.char_count === "number")
+                tokensSum += Math.ceil(p.char_count / 4);
+            if (e.event === "session.save")
+                hasSave = true;
+        }
+        if (tokensSum > 80_000 && !hasSave) {
+            return mk("context_bloat", "warn", `Session "${sid}" at ~${Math.round(tokensSum / 1000)}K tokens, no save_session yet`, group.slice(-3), { sessionId: sid, approxTokens: tokensSum });
+        }
+    }
+    return null;
+}
+function detectFabrication(events, cwd) {
+    const responses = events.filter((e) => e.event === "browser.response").slice(-5);
+    // Match file paths with a line number: "src/foo.ts:42", "lib/x.py:3-7", etc.
+    // Conservative: only flag paths with a recognizable code extension AND a line ref.
+    const re = /([A-Za-z0-9_\-./]+\.(?:ts|tsx|js|jsx|py|md|json|yml|yaml|go|rs|rb|java|cs|cpp|c|h)):\d+/g;
+    for (const r of responses) {
+        const text = getText(r);
+        const found = new Set();
+        for (const m of text.matchAll(re)) {
+            const p = m[1];
+            if (found.has(p))
+                continue;
+            found.add(p);
+            const abs = isAbsolute(p) ? p : join(cwd, p);
+            if (!existsSync(abs)) {
+                return mk("fabrication_suspect", "critical", `Assistant referenced non-existent file: ${p}`, [r], { citedPath: p, responseHash: r.hash });
+            }
+        }
+    }
+    return null;
+}
+function detectDrift(events) {
+    // Per-session: if the last 3 prompts are jointly far (low overlap) from
+    // the session's FIRST prompt, the conversation has drifted off-topic.
+    const bySession = groupBy(events.filter((e) => e.event === "browser.prompt" || e.event === "vscode.prompt_submit"), sessionKey);
+    for (const [sid, prompts] of bySession) {
+        if (prompts.length < 4)
+            continue;
+        const first = tokens(getText(prompts[0]));
+        if (first.size === 0)
+            continue;
+        const last3 = prompts.slice(-3).map((p) => tokens(getText(p)));
+        const avgSim = last3.reduce((sum, t) => sum + jaccard(first, t), 0) / 3;
+        if (avgSim < 0.10) {
+            return mk("drift", "info", `Session "${sid}" has drifted from its opening prompt (similarity ${avgSim.toFixed(2)})`, prompts.slice(-3), { sessionId: sid, similarity: avgSim, firstPrompt: getText(prompts[0]).slice(0, 80) });
+        }
+    }
+    return null;
+}
+function detectNoInsight(events) {
+    const lastLearn = [...events].reverse().find((e) => e.event === "learning.save");
+    const since = lastLearn ? Date.parse(lastLearn.ts) : 0;
+    const toolCalls = events.filter((e) => (e.event === "browser.tool_call" ||
+        e.event === "vscode.tool_call") &&
+        Date.parse(e.ts) > since);
+    if (toolCalls.length >= 30) {
+        return mk("no_insight", "info", `${toolCalls.length} tool calls since the last save_learning`, toolCalls.slice(-3), { toolCallCount: toolCalls.length, lastLearningAt: since || null });
+    }
+    return null;
+}
+function detectSilentFailure(events, now) {
+    const errs = events.filter((e) => {
+        if (e.event !== "browser.tool_call" && e.event !== "vscode.tool_call")
+            return false;
+        const p = e.payload || {};
+        return Boolean(p.error || p.failed || p.status === "error");
+    });
+    const recent = errs.filter((e) => now - Date.parse(e.ts) < 300_000);
+    const byTool = groupBy(recent, (e) => String(e.payload?.tool ?? "unknown"));
+    for (const [tool, group] of byTool) {
+        if (group.length >= 3) {
+            const snippet = String((group[0].payload?.error || group[0].payload?.message || "")).slice(0, 200);
+            return mk("silent_failure", "critical", `Tool ${tool} failed ${group.length}× in 5 min`, group, { tool, errorSnippet: snippet, count: group.length });
+        }
+    }
+    return null;
+}
+function detectStaleDocSignal(_events) {
+    // Stub: full implementation requires reading .contextengine/policy.json
+    // and matching staged edits to doc_coverage rules. Defer to Phase 3.1
+    // when the policy module exposes a helper. For now, return null so the
+    // heuristic is wired but inert (keeps the union complete + lets tests
+    // assert "no signal" against fixtures that don't trigger it).
+    return null;
+}
+// ─── Runner ────────────────────────────────────────────────────────────────
+export function runHeuristics(events, opts = {}) {
+    const now = opts.now ?? Date.now();
+    const cwd = opts.cwd ?? process.cwd();
+    const signals = [];
+    const push = (s) => { if (s)
+        signals.push(s); };
+    push(detectLoop(events));
+    push(detectStuck(events, now));
+    push(detectContextBloat(events));
+    push(detectFabrication(events, cwd));
+    push(detectDrift(events));
+    push(detectNoInsight(events));
+    push(detectSilentFailure(events, now));
+    push(detectStaleDocSignal(events));
+    return signals;
+}
+/** Convenience for callers: scan recent events and run heuristics in one call. */
+export function detect(opts = {}) {
+    const now = opts.now ?? Date.now();
+    const events = opts.events ?? scanRecentEvents(opts.windowSeconds ?? 300, now);
+    return runHeuristics(events, { now, cwd: opts.cwd });
+}
+// ─── Live watcher (CLI + MCP) ──────────────────────────────────────────────
+/**
+ * Watch the audit log and fire `onAlert` for each new signal. Dedupe key is
+ * `kind:reason` kept in an in-memory LRU bounded at 100 entries — prevents
+ * the same drift from firing every poll cycle.
+ *
+ * Returns a dispose function. Caller is responsible for handling SIGINT
+ * cleanly.
+ */
+export function watchAuditLog(onAlert, opts = {}) {
+    const auditPath = join(process.env.CONTEXTENGINE_HOME || join(homedir(), ".contextengine"), "audit.log");
+    const seen = new Set();
+    const seenOrder = [];
+    const SEEN_CAP = 100;
+    function maybeFire(signal) {
+        const key = `${signal.kind}:${signal.reason}`;
+        if (seen.has(key))
+            return;
+        seen.add(key);
+        seenOrder.push(key);
+        if (seenOrder.length > SEEN_CAP) {
+            const evict = seenOrder.shift();
+            if (evict)
+                seen.delete(evict);
+        }
+        onAlert(signal);
+        if (opts.emitAuditEvent !== false) {
+            safeAppend("drift.detected", {
+                kind: signal.kind,
+                severity: signal.severity,
+                reason: signal.reason,
+                evidence_count: signal.evidence.length,
+                ...signal.payload,
+            });
+        }
+    }
+    function tick() {
+        const events = scanRecentEvents(opts.windowSeconds ?? 300);
+        const signals = runHeuristics(events);
+        for (const s of signals)
+            maybeFire(s);
+    }
+    // Initial scan.
+    tick();
+    let debounceTimer = null;
+    const debounce = opts.debounceMs ?? 250;
+    let watcher = null;
+    try {
+        if (existsSync(auditPath)) {
+            watcher = watch(auditPath, { persistent: false }, () => {
+                if (debounceTimer)
+                    clearTimeout(debounceTimer);
+                debounceTimer = setTimeout(tick, debounce);
+            });
+        }
+    }
+    catch {
+        /* fs.watch unsupported on some platforms — fall back to polling below */
+    }
+    // Poll-based fallback (in case watch doesn't fire, e.g., remote FS).
+    const pollTimer = setInterval(tick, 5_000);
+    return () => {
+        if (watcher)
+            watcher.close();
+        clearInterval(pollTimer);
+        if (debounceTimer)
+            clearTimeout(debounceTimer);
+    };
+}
+// Test-only — clear the dedupe LRU between fixture runs.
+export const _internal = {
+    detectLoop, detectStuck, detectContextBloat, detectFabrication,
+    detectDrift, detectNoInsight, detectSilentFailure, detectStaleDocSignal,
+};
+//# sourceMappingURL=detector.js.map

package/dist/http-server.d.ts

@@ -0,0 +1,30 @@
+interface IncomingEvent {
+    v?: number;
+    ts?: string;
+    event?: string;
+    actor?: string;
+    payload?: Record<string, unknown>;
+}
+/** Hot-reload the secret from disk so the CLI can rotate without restarting MCP. */
+declare function loadSecret(): string | null;
+declare function constantTimeEqual(a: string, b: string): boolean;
+/** Validate an event has the minimum shape we'll write to audit. */
+declare function validateEvent(e: IncomingEvent, idx: number): string | null;
+/**
+ * Boot the local event-ingest HTTP server. Returns the listening port or null
+ * if the port was already in use (caller may decide whether to retry on
+ * another port or surface the error).
+ *
+ * Safe to call multiple times — second call returns the existing server.
+ */
+export declare function startEventIngestServer(): Promise<number | null>;
+export declare function stopEventIngestServer(): Promise<void>;
+export declare const _internal: {
+    loadSecret: typeof loadSecret;
+    constantTimeEqual: typeof constantTimeEqual;
+    validateEvent: typeof validateEvent;
+    SECRET_FILE: string;
+    PORT: number;
+};
+export {};
+//# sourceMappingURL=http-server.d.ts.map

package/dist/http-server.js

@@ -0,0 +1,242 @@
+// 🔒 LOCKED [HTTP-EVENT-INGEST] — 2026-06-23
+// ⛔ NEVER bind to 0.0.0.0 — only 127.0.0.1. The threat model is "browser
+//    extension running on the same machine"; a network-reachable port would
+//    let any device on the LAN inject audit events.
+// ⛔ NEVER compare the secret with `===` — use timingSafeEqual. String compare
+//    leaks timing info that lets a remote attacker brute-force the secret
+//    one byte at a time.
+// ⛔ NEVER auto-generate the secret on first request. The CLI must create it
+//    explicitly (so a stray client can't bootstrap itself into the audit log).
+//    Refuse with 401 if ~/.contextengine/extension-secret is missing.
+// ⛔ NEVER write events before validating shape — a malformed event in the
+//    audit log corrupts the chain verifier and ruins compliance evidence.
+// WHY: This is the only network surface OpsContext exposes locally. Every
+//    decision here is about keeping it auth-required, scope-bound, and shape-
+//    validated, because the audit log is the foundation everything else
+//    builds on.
+// FIX: To add more endpoints, follow the same auth + validation pattern. Do
+//    not add a /raw-write or /admin route without a separate secret + a
+//    separate LOCK comment explaining why.
+import * as http from "http";
+import { existsSync, readFileSync } from "fs";
+import { join } from "path";
+import { homedir } from "os";
+import { timingSafeEqual } from "crypto";
+import { safeAppend } from "./audit.js";
+const PORT = parseInt(process.env.OPSCONTEXT_EVENT_PORT || "7842", 10);
+const HOST = "127.0.0.1";
+const SECRET_FILE = join(homedir(), ".contextengine", "extension-secret");
+const MAX_BODY = 64 * 1024; // 64 KB per batch
+const MAX_BATCH = 50;
+let serverInstance = null;
+/** Hot-reload the secret from disk so the CLI can rotate without restarting MCP. */
+function loadSecret() {
+    try {
+        if (!existsSync(SECRET_FILE))
+            return null;
+        return readFileSync(SECRET_FILE, "utf-8").trim();
+    }
+    catch {
+        return null;
+    }
+}
+function constantTimeEqual(a, b) {
+    // timingSafeEqual requires equal-length buffers — short-circuit on mismatch
+    // length but only via Buffer.byteLength so we don't leak via string-length
+    // comparison early-exit. Acceptable because length isn't a secret.
+    if (a.length !== b.length)
+        return false;
+    try {
+        return timingSafeEqual(Buffer.from(a), Buffer.from(b));
+    }
+    catch {
+        return false;
+    }
+}
+/** Validate an event has the minimum shape we'll write to audit. */
+function validateEvent(e, idx) {
+    if (typeof e !== "object" || e === null)
+        return `events[${idx}]: not an object`;
+    if (e.v !== 1)
+        return `events[${idx}]: missing or unsupported version field (v=${e.v})`;
+    if (typeof e.event !== "string" || !e.event)
+        return `events[${idx}]: missing event kind`;
+    if (typeof e.ts !== "string" || !e.ts)
+        return `events[${idx}]: missing ts`;
+    if (typeof e.payload !== "object" || e.payload === null)
+        return `events[${idx}]: missing payload object`;
+    // Restrict event kinds to the browser.* + vscode.* + cli.* namespaces.
+    // The audit module's own writers use other kinds (learning.save etc.);
+    // those events come from the LOCAL server, not the network surface.
+    if (!/^(browser|vscode|cli)\./.test(e.event)) {
+        return `events[${idx}]: event kind '${e.event}' not allowed via HTTP (only browser.*/vscode.*/cli.*)`;
+    }
+    return null;
+}
+function sendJson(res, status, body) {
+    const json = JSON.stringify(body);
+    res.writeHead(status, {
+        "Content-Type": "application/json",
+        "Content-Length": Buffer.byteLength(json),
+        // Belt-and-braces: even though the manifest's host_permissions already
+        // lets the SW POST without preflight, we set the response header so
+        // future popup-side probe pings work too.
+        "Access-Control-Allow-Origin": "*",
+        "Access-Control-Allow-Methods": "POST, OPTIONS",
+        "Access-Control-Allow-Headers": "Content-Type, X-OpsContext-Secret",
+    });
+    res.end(json);
+}
+function handleEvents(req, res) {
+    const secret = loadSecret();
+    if (!secret) {
+        sendJson(res, 401, {
+            ok: false,
+            error: "no_secret_configured",
+            hint: "Run: contextengine init-extension-secret",
+        });
+        return;
+    }
+    const provided = req.headers["x-opscontext-secret"];
+    if (typeof provided !== "string" || !constantTimeEqual(provided, secret)) {
+        sendJson(res, 401, { ok: false, error: "bad_secret" });
+        return;
+    }
+    let bytes = 0;
+    const chunks = [];
+    req.on("data", (chunk) => {
+        bytes += chunk.length;
+        if (bytes > MAX_BODY) {
+            req.destroy();
+            sendJson(res, 413, { ok: false, error: "payload_too_large", limit: MAX_BODY });
+            return;
+        }
+        chunks.push(chunk);
+    });
+    req.on("end", () => {
+        let batch;
+        try {
+            batch = JSON.parse(Buffer.concat(chunks).toString("utf-8"));
+        }
+        catch {
+            sendJson(res, 400, { ok: false, error: "bad_json" });
+            return;
+        }
+        if (!batch || !Array.isArray(batch.events)) {
+            sendJson(res, 400, { ok: false, error: "missing_events_array" });
+            return;
+        }
+        if (batch.events.length > MAX_BATCH) {
+            sendJson(res, 400, { ok: false, error: "batch_too_large", limit: MAX_BATCH });
+            return;
+        }
+        // Validate every event BEFORE writing any of them.
+        for (let i = 0; i < batch.events.length; i++) {
+            const err = validateEvent(batch.events[i], i);
+            if (err) {
+                sendJson(res, 400, { ok: false, error: "invalid_event", detail: err });
+                return;
+            }
+        }
+        // All valid — write them to audit log via safeAppend.
+        let written = 0;
+        for (const ev of batch.events) {
+            const actor = typeof ev.actor === "string" ? ev.actor : "browser-ext";
+            // event/payload were validated above — cast is safe.
+            safeAppend(ev.event, ev.payload, actor);
+            written++;
+        }
+        sendJson(res, 200, { ok: true, written });
+    });
+}
+function handleHealth(_req, res) {
+    sendJson(res, 200, {
+        ok: true,
+        service: "opscontext-event-ingest",
+        port: PORT,
+        secretConfigured: loadSecret() !== null,
+    });
+}
+function handleOptions(_req, res) {
+    // CORS preflight — the SW shouldn't need this thanks to host_permissions,
+    // but answering it cleanly costs nothing and helps popup probes.
+    res.writeHead(204, {
+        "Access-Control-Allow-Origin": "*",
+        "Access-Control-Allow-Methods": "POST, OPTIONS",
+        "Access-Control-Allow-Headers": "Content-Type, X-OpsContext-Secret",
+        "Access-Control-Max-Age": "600",
+    });
+    res.end();
+}
+/**
+ * Boot the local event-ingest HTTP server. Returns the listening port or null
+ * if the port was already in use (caller may decide whether to retry on
+ * another port or surface the error).
+ *
+ * Safe to call multiple times — second call returns the existing server.
+ */
+export function startEventIngestServer() {
+    if (serverInstance) {
+        const addr = serverInstance.address();
+        return Promise.resolve(typeof addr === "object" && addr ? addr.port : PORT);
+    }
+    return new Promise((resolve) => {
+        const srv = http.createServer((req, res) => {
+            try {
+                if (req.method === "OPTIONS")
+                    return handleOptions(req, res);
+                const url = req.url || "/";
+                if (req.method === "POST" && url.startsWith("/events"))
+                    return handleEvents(req, res);
+                if (req.method === "GET" && url.startsWith("/health"))
+                    return handleHealth(req, res);
+                sendJson(res, 404, { ok: false, error: "not_found" });
+            }
+            catch (err) {
+                console.error("[ContextEngine] event-ingest error:", err);
+                try {
+                    sendJson(res, 500, { ok: false, error: "internal" });
+                }
+                catch {
+                    /* ignore — response may already be closed */
+                }
+            }
+        });
+        srv.on("error", (err) => {
+            if (err.code === "EADDRINUSE") {
+                console.error(`[ContextEngine] ⚠ port ${PORT} already in use — browser-event ingest disabled.\n` +
+                    `  Set OPSCONTEXT_EVENT_PORT=<n> to use a different port (must also update extension options).`);
+                resolve(null);
+                return;
+            }
+            console.error("[ContextEngine] event-ingest server error:", err);
+            resolve(null);
+        });
+        srv.listen(PORT, HOST, () => {
+            serverInstance = srv;
+            console.error(`[ContextEngine] 🌐 event-ingest on http://${HOST}:${PORT} ` +
+                (loadSecret() ? "(secret loaded)" : "(NO SECRET — run `contextengine init-extension-secret`)"));
+            resolve(PORT);
+        });
+    });
+}
+export function stopEventIngestServer() {
+    return new Promise((resolve) => {
+        if (!serverInstance)
+            return resolve();
+        serverInstance.close(() => {
+            serverInstance = null;
+            resolve();
+        });
+    });
+}
+// Test helpers (not exported in dist surface in production use — but the
+// module is small enough that tests can import them directly).
+export const _internal = {
+    loadSecret,
+    constantTimeEqual,
+    validateEvent,
+    SECRET_FILE,
+    PORT,
+};
+//# sourceMappingURL=http-server.js.map

package/dist/index.js

@@ -11,6 +11,8 @@ import { loadCache, saveCache } from "./cache.js";
 import { listProjects, checkPorts, runComplianceAudit, formatProjectList, formatPortMap, formatPlan, scoreProject, formatScoreReport, } from "./agents.js";
 import { saveSession, loadSession, listSessions, deleteSession, formatSession, formatSessionList, } from "./sessions.js";
 import { verifyChain, readAuditLog, filterByRange } from "./audit.js";
+import { startEventIngestServer } from "./http-server.js";
+import { detect } from "./detector.js";
 import { saveLearning, searchLearnings, listLearnings, deleteLearning, learningsToChunks, learningsStats, formatLearnings, importLearningsFromFile, autoImportFromSources, LEARNING_CATEGORIES, } from "./learnings.js";
 import { readFileSync, existsSync, watch, statSync } from "fs";
 import { basename, join, dirname } from "path";
@@ -580,6 +582,39 @@ server.tool("audit_verify", "Verify the integrity of the local audit log chain.
     return respond("audit_verify", summary.join("\n"));
 });
 // ---------------------------------------------------------------------------
+// Tool: drift_status (Detector — read current drift signals)
+// ---------------------------------------------------------------------------
+// Agents should call this between major task phases. If any 'critical' signal
+// is active, they should pause and surface to the human. The signals are also
+// appended to the audit log as drift.detected events so post-hoc review can
+// reconstruct what fired and when.
+server.tool("drift_status", "Returns active drift / loop / stuck-tool / fabrication / silent-failure signals detected over the recent audit-log window. Use to self-check before starting a major task phase. If any 'critical' signal is active (fabrication_suspect or silent_failure), pause and surface to the human.", {
+    windowSeconds: z.number().optional().describe("Look-back window in seconds. Default 300 (5 min)."),
+    minSeverity: z.enum(["info", "warn", "critical"]).optional().describe("Floor filter for severity. Default 'info' (everything)."),
+}, async ({ windowSeconds, minSeverity }) => {
+    const signals = detect({ windowSeconds: windowSeconds ?? 300 });
+    const order = { info: 0, warn: 1, critical: 2 };
+    const floor = order[minSeverity ?? "info"];
+    const filtered = signals.filter((s) => order[s.severity] >= floor);
+    const lines = [];
+    lines.push(`Drift signals: ${filtered.length} active (window=${windowSeconds ?? 300}s, minSeverity=${minSeverity ?? "info"}).`);
+    if (filtered.length === 0) {
+        lines.push("All clear.");
+    }
+    else {
+        for (const s of filtered) {
+            const sev = s.severity.toUpperCase();
+            lines.push(`  [${sev}] ${s.kind}: ${s.reason}`);
+        }
+        const critical = filtered.filter((s) => s.severity === "critical");
+        if (critical.length > 0) {
+            lines.push("");
+            lines.push(`⛔ ${critical.length} CRITICAL signal(s) — pause the task and surface to the human.`);
+        }
+    }
+    return respond("drift_status", lines.join("\n"));
+});
+// ---------------------------------------------------------------------------
 // Tool: end_session (End-of-Session Protocol Enforcer)
 // ---------------------------------------------------------------------------
 server.tool("end_session", "MUST be called before ending any coding session. Checks all project repos for uncommitted changes, verifies documentation freshness (copilot-instructions.md, SKILLS.md, session docs), and returns a checklist of required actions. Will report PASS/FAIL for each check. The AI agent should resolve all FAIL items before ending.", {}, async () => {
@@ -1073,6 +1108,15 @@ async function main() {
     }
     // 5. Start file watchers
     startWatching();
+    // 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).
+    // No-op if secret is missing; the endpoint will refuse with 401 until
+    // a secret is configured. Failure to bind (port collision) logs and
+    // continues — the MCP server stays usable without browser capture.
+    startEventIngestServer().catch((err) => {
+        console.error("[ContextEngine] event-ingest start failed:", err);
+    });
 }
 main().catch((err) => {
     console.error("[ContextEngine] Fatal:", err);

package/package.json

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