@compr/opscontext-mcp 2.8.2 → 2.8.3

package/CHANGELOG.md

@@ -4,6 +4,22 @@ 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

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/package.json

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