@compr/opscontext-mcp 2.8.1 → 2.8.3

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.3] 2026-09-16: one hook per event, verified
+
+### Fixed
+
+- **`install-claude-hook` no longer registers the emit hooks twice** (`src/install-claude-hook.ts`,
+  LOCKs `[HOOKS-COMPARED-BY-EXPANDED-PATH]`, `[INSTALL-VERIFIES-BY-COUNT]`). Its "already
+  installed?" check compared command text literally, so hooks written as
+  `$HOME/.claude/hooks/opscontext-emit.sh` looked absent and a second set was added: on the
+  author's machine every Claude Code prompt and tool call reached the audit log twice from
+  2026-09-06 to 2026-09-15, doubling the inputs of the `stuck` and `silent_failure` heuristics.
+  The installer now compares script paths with `$HOME`, `${HOME}` and `~` expanded, removes
+  extra copies of its own commands (other hooks untouched), and after writing re-reads
+  `settings.json` and exits 1 unless each event runs its script exactly once. Running
+  `install-claude-hook` again repairs an affected machine; the audit log is left as it is (it is
+  hash-chained).
+
+## [2.8.2] 2026-09-08: every source says what it is
+
+### Added
+
+- **One-line summary per source in `list_sources` and `contextengine list-sources`**
+  (`src/source-summary.ts`): frontmatter `description` when the file has one, else H1 title
+  plus first prose line, else the module docstring or header comment for code. Read from the
+  first 4 KB of each file only. Why: with 800+ sources an agent opened two or three whole
+  documents to find the right one; the summary lets it pick once.
+
 ## [2.8.1] 2026-09-07: a push is not done until its CI is read
 
 ### Added

package/dist/cli.js

@@ -641,6 +641,7 @@ async function runInit() {
 // ---------------------------------------------------------------------------
 import { loadSources, loadProjectDirs, loadConfig, resolveProjectDir, findProjectRoot, looksLikePath } from "./config.js";
 import { ingestSources } from "./ingest.js";
+import { summarizeSource } from "./source-summary.js";
 import { searchChunks } from "./search.js";
 import { SERVER_COMMANDS, suggestCommands } from "./cli-commands.js";
 import { collectProjectOps, collectSystemOps } from "./collectors.js";
@@ -743,6 +744,9 @@ async function cliListSources() {
         const count = chunks.filter((c) => c.source === s.name).length;
         const status = exists ? `✅ ${count} chunks` : "⚠ file not found";
         console.log(`  ${s.name}: ${status}`);
+        const summary = exists ? summarizeSource(s) : "";
+        if (summary)
+            console.log(`    ${summary}`);
         console.log(`    ${s.path}`);
     }
     console.log("");

package/dist/index.js

@@ -4,6 +4,7 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { z } from "zod";
 import { loadSources, loadProjectDirs, loadConfig, resolveProjectDir } from "./config.js";
 import { ingestSources } from "./ingest.js";
+import { summarizeSource } from "./source-summary.js";
 import { searchChunks } from "./search.js";
 import { initEmbeddings, embedChunks, embedKeyOf, vectorSearch, isEmbeddingsReady, } from "./embeddings.js";
 import { collectProjectOps, collectSystemOps } from "./collectors.js";
@@ -575,7 +576,7 @@ server.tool("search_context", "Search across all indexed project knowledge (copi
 // ---------------------------------------------------------------------------
 // Tool: list_sources
 // ---------------------------------------------------------------------------
-server.tool("list_sources", "List all knowledge sources indexed by ContextEngine, with their status (found/missing) and chunk counts.", {}, async () => {
+server.tool("list_sources", "List all knowledge sources indexed by ContextEngine, each with a one-line summary (from the file's own head: frontmatter description, title plus first sentence, or module docstring), status (found/missing) and chunk counts. Read the summary to pick the right source before calling read_source.", {}, async () => {
     const lines = sources.map((s) => {
         const exists = existsSync(s.path);
         const count = chunks.filter((c) => c.source === s.name).length;
@@ -583,7 +584,8 @@ server.tool("list_sources", "List all knowledge sources indexed by ContextEngine
         const status = exists
             ? `✅ ${count} chunks${embeddedCount > 0 ? ` (${embeddedCount} embedded)` : ""}`
             : "⚠ file not found";
-        return `${s.name}: ${status}\n  ${s.path}`;
+        const summary = exists ? summarizeSource(s) : "";
+        return `${s.name}: ${status}${summary ? `\n  ${summary}` : ""}\n  ${s.path}`;
     });
     const embStatus = isEmbeddingsReady()
         ? `✅ ${embeddedChunks.length} vectors`

package/dist/install-claude-hook.d.ts

@@ -1,3 +1,26 @@
+export interface HookCommand {
+    type: string;
+    command: string;
+    timeout?: number;
+}
+export interface HookEntry {
+    matcher?: string;
+    hooks: HookCommand[];
+}
+export interface Settings {
+    hooks?: Record<string, HookEntry[]>;
+    [k: string]: unknown;
+}
+/** The script path of a hook command, with $HOME, ${HOME} or a leading ~ expanded. */
+export declare function hookScriptPath(command: string, home?: string): string;
+/** Removes repeated registrations of our scripts under the same matcher. Keeps the first copy
+ *  and every hook that is not ours; drops an entry only when that leaves it empty. */
+export declare function dropDuplicateHooks(entries: HookEntry[], ourScripts: string[], home?: string): {
+    entries: HookEntry[];
+    removed: number;
+};
+/** How many times each event runs `script`. A correct install has exactly 1 everywhere. */
+export declare function countOurHooks(settings: Settings, events: readonly string[], script: string, home?: string): Record<string, number>;
 export declare function cliInstallClaudeHook(args: string[]): Promise<void>;
 export declare function cliUninstallClaudeHook(args: string[]): Promise<void>;
 //# sourceMappingURL=install-claude-hook.d.ts.map

package/dist/install-claude-hook.js

@@ -50,10 +50,59 @@ function backupSettings() {
     copyFileSync(SETTINGS_FILE, backup);
     return backup;
 }
-function hookAlreadyWired(entries, hookScript) {
-    if (!entries)
-        return false;
-    return entries.some((e) => e.hooks?.some((h) => h.command?.startsWith(hookScript)));
+// [LOCKED] [HOOKS-COMPARED-BY-EXPANDED-PATH] - 2026-09-15
+// [NEVER] compare a hook command with startsWith or any other literal text match again.
+// WHY: settings.json held the emit hooks as "$HOME/.claude/hooks/opscontext-emit.sh <Kind>",
+//      hand-wired on 2026-06-23 before this installer existed. On 2026-09-06 the 2.7.0 rollout
+//      ran install-claude-hook; its startsWith(absolute path) check did not see them, printed
+//      "4 hook entries added, 0 already present" and wrote a second set. From 2026-09-06
+//      08:20:21Z every Claude Code event reached the audit log twice (0 doubled events in the 8
+//      days before, 99.5 to 100 percent every day after), doubling the stuck and silent_failure
+//      inputs that [OPSCONTEXT-CC-HOOK] protects.
+// FIX: compare the script path after expanding $HOME, ${HOME} and a leading ~; installing also
+//      removes extra copies of our own commands under the same matcher, and nothing else.
+/** The script path of a hook command, with $HOME, ${HOME} or a leading ~ expanded. */
+export function hookScriptPath(command, home = homedir()) {
+    const m = /^\s*(?:"([^"]*)"|'([^']*)'|(\S+))/.exec(command ?? "");
+    const path = m ? (m[1] ?? m[2] ?? m[3]) : "";
+    return path.replace(/^(?:\$HOME|\$\{HOME\}|~)(?=\/)/, home);
+}
+/** The command with its script path expanded, so two spellings of one call compare equal. */
+function normalizedCommand(command, home) {
+    const args = (command ?? "").trim().replace(/^(?:"[^"]*"|'[^']*'|\S+)/, "").trim();
+    return `${hookScriptPath(command, home)} ${args}`.trim();
+}
+function hookAlreadyWired(entries, hookScript, home = homedir()) {
+    return (entries ?? []).some((e) => e.hooks?.some((h) => hookScriptPath(h.command, home) === hookScript));
+}
+/** Removes repeated registrations of our scripts under the same matcher. Keeps the first copy
+ *  and every hook that is not ours; drops an entry only when that leaves it empty. */
+export function dropDuplicateHooks(entries, ourScripts, home = homedir()) {
+    const seen = new Set();
+    let removed = 0;
+    const kept = [];
+    for (const entry of entries) {
+        const before = entry.hooks ?? [];
+        const hooks = before.filter((h) => {
+            if (!ourScripts.includes(hookScriptPath(h.command, home)))
+                return true;
+            const key = `${entry.matcher ?? ""}\u0000${normalizedCommand(h.command, home)}`;
+            if (seen.has(key)) {
+                removed++;
+                return false;
+            }
+            seen.add(key);
+            return true;
+        });
+        if (hooks.length > 0 || before.length === 0)
+            kept.push({ ...entry, hooks });
+    }
+    return { entries: kept, removed };
+}
+/** How many times each event runs `script`. A correct install has exactly 1 everywhere. */
+export function countOurHooks(settings, events, script, home = homedir()) {
+    const count = (ev) => (settings.hooks?.[ev] ?? []).flatMap((e) => e.hooks ?? []).filter((h) => hookScriptPath(h.command, home) === script).length;
+    return Object.fromEntries(events.map((ev) => [ev, count(ev)]));
 }
 /** Path to the reference hook script bundled with this package. */
 function bundledHookSource() {
@@ -129,7 +178,17 @@ Run: opscontext install-autostart
     if (backup)
         console.log(`✅ Backed up settings.json → ${backup}`);
     settings.hooks ??= {};
-    const hookCmdPrefix = `${HOOK_SCRIPT}`; // command string starts with this
+    const hookCmdPrefix = `${HOOK_SCRIPT}`; // compared by expanded path, [HOOKS-COMPARED-BY-EXPANDED-PATH]
+    // [LOCK] [HOOKS-COMPARED-BY-EXPANDED-PATH]: remove extra copies before deciding what to add.
+    let deduped = 0;
+    for (const kind of [...EVENT_KINDS, "Stop"]) {
+        const entries = settings.hooks[kind];
+        if (!entries)
+            continue;
+        const r = dropDuplicateHooks(entries, [HOOK_SCRIPT, GATE_SCRIPT]);
+        settings.hooks[kind] = r.entries;
+        deduped += r.removed;
+    }
     let added = 0;
     let skipped = 0;
     for (const kind of EVENT_KINDS) {
@@ -169,7 +228,26 @@ Run: opscontext install-autostart
     }
     console.log(`✅ Installed session gate: ${GATE_SCRIPT}`);
     writeFileSync(SETTINGS_FILE, JSON.stringify(settings, null, 2) + "\n");
-    console.log(`✅ ${added} hook entries added, ${skipped} already present.`);
+    const removedNote = deduped ? `, ${deduped} duplicate registrations removed` : "";
+    console.log(`✅ ${added} hook entries added, ${skipped} already present${removedNote}.`);
+    // [LOCKED] [INSTALL-VERIFIES-BY-COUNT] - 2026-09-15
+    // [NEVER] treat the added/present counters above as proof of a correct install.
+    // WHY: on 2026-09-06 this command printed "0 already present" over three existing hooks, and
+    //      the session that ran it recorded "they were not there"; the doubled audit events then
+    //      went unseen for nine days.
+    // FIX: re-read settings.json from disk and require exactly one registration per event.
+    const written = readSettings();
+    const counts = {
+        ...countOurHooks(written, EVENT_KINDS, HOOK_SCRIPT),
+        ...countOurHooks(written, ["Stop"], GATE_SCRIPT),
+    };
+    const wrong = Object.entries(counts).filter(([, n]) => n !== 1);
+    if (wrong.length > 0) {
+        const detail = wrong.map(([ev, n]) => `${ev}=${n}`).join(", ");
+        console.error(`❌ settings.json must hold exactly one OpsContext hook per event, found ${detail}. Backup: ${backup || "none"}`);
+        process.exit(1);
+    }
+    console.log(`✅ Verified in settings.json: exactly one registration for ${Object.keys(counts).join(", ")}.`);
     console.log(``);
     console.log(`Test live:`);
     console.log(`  1. Open a NEW VS Code terminal (settings.json is read at session start).`);

package/dist/source-summary.d.ts

@@ -0,0 +1,9 @@
+import type { KnowledgeSource } from "./config.js";
+export declare const HEAD_BYTES = 4096;
+export declare const SUMMARY_MAX = 110;
+/** Read at most `bytes` from the start of a file. Empty string on any error. */
+export declare function readHead(path: string, bytes?: number): string;
+/** Summary for a configured source; "" when the file is unreadable or says nothing. */
+export declare function summarizeSource(source: KnowledgeSource): string;
+export declare function summarizeText(text: string, type: "markdown" | "code"): string;
+//# sourceMappingURL=source-summary.d.ts.map

package/dist/source-summary.js

@@ -0,0 +1,150 @@
+/**
+ * One-line summary per knowledge source, for list_sources (MCP) and
+ * `contextengine list-sources` (CLI).
+ *
+ * Why: with 800+ sources, an agent reading a bare name plus a path opens two
+ * or three files to find the right one. Each open puts a whole document into
+ * its context (see CLAUDE.md, multi-agent cost). A summary line derived from
+ * the first few KB of the file lets it pick once.
+ *
+ * Reads only the head of the file (HEAD_BYTES), never the whole document, so
+ * the cost is bounded no matter how many sources are configured.
+ */
+import { openSync, readSync, closeSync } from "fs";
+export const HEAD_BYTES = 4096;
+export const SUMMARY_MAX = 110;
+/** Read at most `bytes` from the start of a file. Empty string on any error. */
+export function readHead(path, bytes = HEAD_BYTES) {
+    let fd;
+    try {
+        fd = openSync(path, "r");
+        const buf = Buffer.alloc(bytes);
+        const n = readSync(fd, buf, 0, bytes, 0);
+        return buf.subarray(0, n).toString("utf-8");
+    }
+    catch {
+        return "";
+    }
+    finally {
+        if (fd !== undefined)
+            closeSync(fd);
+    }
+}
+/** Summary for a configured source; "" when the file is unreadable or says nothing. */
+export function summarizeSource(source) {
+    return summarizeText(readHead(source.path), source.type);
+}
+export function summarizeText(text, type) {
+    if (!text)
+        return "";
+    return clip(type === "code" ? summarizeCode(text) : summarizeMarkdown(text));
+}
+function clip(s) {
+    const one = s.replace(/\s+/g, " ").trim();
+    if (one.length <= SUMMARY_MAX)
+        return one;
+    return one.slice(0, SUMMARY_MAX - 3).trimEnd() + "...";
+}
+/** Strip markdown decoration so the line reads as plain text. */
+function plain(line) {
+    return line
+        .replace(/!\[[^\]]*\]\([^)]*\)/g, "") // images
+        .replace(/\[([^\]]+)\]\([^)]*\)/g, "$1") // links -> text
+        .replace(/`([^`]*)`/g, "$1") // inline code
+        .replace(/\*\*|__/g, "") // bold
+        .replace(/^\s*(?:[-*+]|\d+[.)])\s+/, "") // list bullet
+        .replace(/^\s*>\s?/, "") // blockquote
+        .trim();
+}
+/** Header metadata lines that say nothing about the content. */
+const META_LINE = /^(updated|last updated|created|date|status|author|owner|version|scope|audience)\b\s*[:\-]/i;
+function summarizeMarkdown(text) {
+    let body = text;
+    // YAML frontmatter: prefer its description, it IS a one-line summary.
+    if (body.startsWith("---\n") || body.startsWith("---\r\n")) {
+        const end = body.indexOf("\n---", 4);
+        if (end !== -1) {
+            const fm = body.slice(4, end);
+            const desc = fm.match(/^description:\s*(.+)$/m);
+            if (desc)
+                return desc[1].trim().replace(/^["']|["']$/g, "");
+            body = body.slice(end + 4);
+        }
+    }
+    let title = "";
+    let prose = "";
+    let inFence = false;
+    for (const raw of body.split("\n")) {
+        const line = raw.trim();
+        if (line.startsWith("```") || line.startsWith("~~~")) {
+            inFence = !inFence;
+            continue;
+        }
+        if (inFence || !line)
+            continue;
+        if (line.startsWith("<!--") || line.startsWith("|") || line.startsWith("![") || line.startsWith("[!"))
+            continue;
+        if (/^[-=*_]{3,}$/.test(line))
+            continue;
+        if (line.startsWith("#")) {
+            if (!title)
+                title = plain(line.replace(/^#+\s*/, ""));
+            continue;
+        }
+        const p = plain(line);
+        if (p.length < 12)
+            continue; // lone dates, "v2.1", etc.
+        if (META_LINE.test(p))
+            continue; // "Updated: 2026-03-13", "Status: draft"
+        prose = p;
+        break;
+    }
+    if (title && prose)
+        return `${title}: ${prose}`;
+    return title || prose;
+}
+const CODE_SKIP = /^(#!|\/\/\s*eslint|\/\*\s*eslint|@ts-|#\s*-\*-|#\s*coding[:=]|SPDX|Copyright|\[LOCK|\[LOCKED\]|\[NEVER\]|WHY:|FIX:|import |from |export |const |let |var |use strict|"use strict")/i;
+function summarizeCode(text) {
+    const lines = text.split("\n");
+    let inBlock = false;
+    for (const raw of lines) {
+        let line = raw.trim();
+        if (!line)
+            continue;
+        if (!inBlock) {
+            const opensBlock = line.startsWith("/*") || line.startsWith('"""') || line.startsWith("'''");
+            const closesOnSameLine = (line.startsWith("/*") && /\*\/$/.test(line)) ||
+                (/^("""|''')/.test(line) && line.length > 3 && /("""|''')$/.test(line));
+            if (CODE_SKIP.test(line)) {
+                // Pragma, shebang or marker on the raw line: skip it. A one-line
+                // block comment ("/* eslint-disable */") must not leave us in a block.
+                if (opensBlock && !closesOnSameLine)
+                    inBlock = true;
+                continue;
+            }
+            if (opensBlock) {
+                inBlock = !closesOnSameLine;
+                line = line.replace(/^(\/\*+|"""|''')\s*/, "").replace(/(\*\/|"""|''')\s*$/, "").trim();
+            }
+            else if (line.startsWith("//") || line.startsWith("#")) {
+                line = line.replace(/^(\/\/|#)+\s*/, "").trim();
+            }
+            else {
+                // Code before any comment: nothing worth saying about this file.
+                return "";
+            }
+        }
+        else {
+            if (/(\*\/|"""|''')$/.test(line))
+                inBlock = false;
+            line = line.replace(/^\*+\s*/, "").replace(/(\*\/|"""|''')\s*$/, "").trim();
+        }
+        if (!line || /^[-=*_#]{3,}$/.test(line) || CODE_SKIP.test(line))
+            continue;
+        if (line.length < 12)
+            continue;
+        return line;
+    }
+    return "";
+}
+//# sourceMappingURL=source-summary.js.map

package/package.json

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