@compr/opscontext-mcp 2.6.1 → 2.7.0

package/CHANGELOG.md

@@ -4,6 +4,27 @@ 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.7.0] 2026-09-06: the session gate ships in the package
+
+### Added
+
+- **`contextengine session-gate`** (`[SESSION-SAVE-IS-A-GATE]`, `src/session-gate.ts`): the body of
+  a Claude Code Stop hook. A turn cannot end (exit 2, reason on stderr) while the repo's CE session
+  (newest `~/.contextengine/sessions/*.json` whose name starts with the repo's name) is older than
+  the last commit. The message names the session to save, the newest `docs/sessions/SESSION_*.md`,
+  and how many `src/` commits `.github/copilot-instructions.md` is behind. Passes outside git,
+  before the first commit, and when Claude Code reports `stop_hook_active`. Why: the owner had to
+  type "check and update session and ce docs" at the end of every session; a reminder is not a rule.
+- **`install-claude-hook` wires the gate** as a fourth entry (`Stop`) at user scope, through
+  `~/.claude/hooks/opscontext-session-gate.sh` with absolute node and CLI paths. Idempotent;
+  `uninstall-claude-hook` removes it with the others.
+
+### Fixed
+
+- **`install-claude-hook` crashed with "__dirname is not defined"** from the published package:
+  the module is ESM and looked up `defaults/` through a CommonJS global. It had never worked
+  outside the dev tree. Resolved through `import.meta.url` (`[M2-ESM-FILENAME-FIX]`).
+
 ## [2.6.1] 2026-09-06: readers never embed; a store record without tags no longer breaks search
 
 ### Fixed

package/README.md

@@ -165,7 +165,7 @@ Companion commands: `uninstall-autostart`, `autostart-status`.
 npx @compr/opscontext-mcp install-claude-hook
 ```
 
-Adds `UserPromptSubmit`, `PostToolUse`, and `SessionStart` hook entries to `~/.claude/settings.json` so every Claude Code prompt + tool call lands in the same audit log as the browser events.
+Adds `UserPromptSubmit`, `PostToolUse`, and `SessionStart` hook entries to `~/.claude/settings.json` so every Claude Code prompt + tool call lands in the same audit log as the browser events, plus a `Stop` entry: the **session gate** (2.7.0). A Claude Code turn cannot end while the repo's OpsContext session is older than the last commit; the agent is told which session to save, which session doc to update, and how far the agent docs are behind. No more "did you save the session?" at the end of a day. Details: `npx @compr/opscontext-mcp session-gate --help`.
 
 Verify:
 ```bash
@@ -525,7 +525,7 @@ Everything happens locally — search, scoring, learnings, sessions, embeddings.
 | Learnings (operational rules) | `~/.contextengine/learnings.json` | ❌ Never |
 | Sessions (decisions, progress) | `~/.contextengine/sessions/` | ❌ Never |
 | Session stats (value meter) | `~/.contextengine/session-stats.json` | ❌ Never |
-| Search index & embeddings | In-memory + `~/.contextengine/embedding-cache.json` | ❌ Never |
+| Search index & embeddings | In-memory + `~/.contextengine/embeddings.bin` (vectors) and `~/.contextengine/index/` (shared index) | ❌ Never |
 | Git history & branches | Local `git` commands | ❌ Never |
 | Dependencies & package.json | Read locally | ❌ Never |
 | .env variable names | Read locally (values are never read) | ❌ Never |

package/dist/cli-commands.js

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

package/dist/cli.js

@@ -2548,7 +2548,8 @@ Usage:
   contextengine install-autostart [--force]
                                        Install macOS LaunchAgent so MCP server auto-starts at login
                                        (uninstall-autostart / autostart-status — companion commands)
-  contextengine install-claude-hook    Wire Claude Code terminal sessions into the OpsContext audit log
+  contextengine install-claude-hook    Wire Claude Code terminal sessions into the OpsContext audit log, plus the Stop session gate
+  contextengine session-gate           Claude Code Stop hook body: exit 2 while the repo's CE session is older than HEAD
                                        (UserPromptSubmit + PostToolUse + SessionStart hook entries)
   contextengine watch [--json] [--severity info|warn|critical] [--once] [--window SECONDS]
                                        Stream drift / loop / stuck-tool / fabrication alerts from the audit log
@@ -2814,6 +2815,12 @@ else if (command === "autostart-status") {
         process.exit(1);
     });
 }
+else if (command === "session-gate") {
+    import("./session-gate.js").then((m) => m.cliSessionGate(process.argv.slice(3))).catch((err) => {
+        console.error("Error:", err);
+        process.exit(0); // a broken gate must never trap the user in a turn
+    });
+}
 else if (command === "install-claude-hook") {
     import("./install-claude-hook.js").then((m) => m.cliInstallClaudeHook(process.argv.slice(3))).catch((err) => {
         console.error("Error:", err instanceof Error ? err.message : err);

package/dist/install-claude-hook.js

@@ -15,12 +15,21 @@
 // FIX: To add a new hook event, extend EVENT_KINDS + the splice block.
 //    Keep the "preserve existing" discipline in every code path.
 import { existsSync, readFileSync, writeFileSync, copyFileSync, chmodSync, mkdirSync } from "fs";
-import { join } from "path";
+import { join, dirname } from "path";
 import { homedir } from "os";
+import { fileURLToPath } from "url";
+// [LOCK] [M2-ESM-FILENAME-FIX]: the package is "type": "module", so a bare __dirname is a
+// ReferenceError at runtime. Found 2026-09-06 while adding the Stop gate: the defaults/ lookup
+// below used `__dirname_esm`, and a real run against a throwaway HOME died with
+// "__dirname is not defined": the installer had never worked from the published package.
+const __dirname_esm = dirname(fileURLToPath(import.meta.url));
 const CLAUDE_DIR = join(homedir(), ".claude");
 const SETTINGS_FILE = join(CLAUDE_DIR, "settings.json");
 const HOOKS_DIR = join(CLAUDE_DIR, "hooks");
 const HOOK_SCRIPT = join(HOOKS_DIR, "opscontext-emit.sh");
+/** The Stop gate: a wrapper that runs `session-gate` with the node and CLI that installed it.
+ *  [LOCK] [SESSION-SAVE-IS-A-GATE] (src/session-gate.ts) */
+const GATE_SCRIPT = join(HOOKS_DIR, "opscontext-session-gate.sh");
 const EVENT_KINDS = ["UserPromptSubmit", "PostToolUse", "SessionStart"];
 function readSettings() {
     if (!existsSync(SETTINGS_FILE))
@@ -52,8 +61,8 @@ function bundledHookSource() {
     // when globally / locally installed via npm. Both follow the same relative
     // shape because npm copies defaults/ via the `files` whitelist.
     const candidates = [
-        join(__dirname || "", "..", "defaults", "claude-code-hook.sh"),
-        join(__dirname || "", "defaults", "claude-code-hook.sh"),
+        join(__dirname_esm, "..", "defaults", "claude-code-hook.sh"),
+        join(__dirname_esm, "defaults", "claude-code-hook.sh"),
     ];
     for (const c of candidates) {
         if (existsSync(c))
@@ -73,10 +82,13 @@ Events emitted (all go through the local HTTP endpoint, never the network):
   • UserPromptSubmit → vscode.prompt_submit  (feeds the loop heuristic)
   • PostToolUse      → vscode.tool_call      (feeds stuck + silent_failure)
   • SessionStart     → vscode.session_start
+  • Stop             → the session gate: a turn cannot end while the repo's CE session
+                       is older than the last commit (contextengine session-gate --help)
 
 The installer:
   1. Copies the bundled hook script to ~/.claude/hooks/opscontext-emit.sh
-  2. Splices three entries into ~/.claude/settings.json under "hooks"
+     and writes ~/.claude/hooks/opscontext-session-gate.sh (node + this CLI, absolute paths)
+  2. Splices four entries into ~/.claude/settings.json under "hooks"
   3. Preserves every existing hook entry (idempotent, safe to re-run)
 
 A timestamped backup is written next to settings.json before any change.
@@ -130,6 +142,19 @@ Run: opscontext install-autostart
         settings.hooks[kind].push(entry);
         added++;
     }
+    // Step 3: the Stop gate. Absolute node + CLI paths: hooks run without the user's shell PATH.
+    const cliPath = join(__dirname_esm, "cli.js");
+    writeFileSync(GATE_SCRIPT, `#!/bin/sh\n# Generated by \`opscontext install-claude-hook\`: the CE session gate on Claude Code Stop.\n# Exit 2 = the turn may not end yet (reason on stderr). See: contextengine session-gate --help\nexec "${process.execPath}" "${cliPath}" session-gate\n`);
+    chmodSync(GATE_SCRIPT, 0o755);
+    settings.hooks.Stop ??= [];
+    if (hookAlreadyWired(settings.hooks.Stop, GATE_SCRIPT)) {
+        skipped++;
+    }
+    else {
+        settings.hooks.Stop.push({ hooks: [{ type: "command", command: GATE_SCRIPT, timeout: 15 }] });
+        added++;
+    }
+    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.`);
     console.log(``);
@@ -159,11 +184,11 @@ manually if you want it gone. The audit log is NOT touched.`);
     if (backup)
         console.log(`✅ Backed up settings.json → ${backup}`);
     let removed = 0;
-    for (const kind of EVENT_KINDS) {
+    for (const kind of [...EVENT_KINDS, "Stop"]) {
         const entries = settings.hooks[kind];
         if (!entries)
             continue;
-        const filtered = entries.filter((e) => !e.hooks?.some((h) => h.command?.includes("opscontext-emit.sh")));
+        const filtered = entries.filter((e) => !e.hooks?.some((h) => h.command?.includes("opscontext-emit.sh") || h.command?.includes("opscontext-session-gate.sh")));
         removed += entries.length - filtered.length;
         if (filtered.length === 0) {
             delete settings.hooks[kind];

package/dist/session-gate.d.ts

@@ -0,0 +1,32 @@
+export interface GateInput {
+    /** The repository the turn ran in (CLAUDE_PROJECT_DIR, else cwd). */
+    repo: string;
+    /** Where CE keeps sessions; default ~/.contextengine/sessions. */
+    sessionsDir?: string;
+    /** Claude Code sets this when the turn is already continuing because of a Stop hook. */
+    stopHookActive?: boolean;
+    /** Tests: a session file to use instead of the lookup. */
+    sessionFile?: string;
+}
+export interface GateResult {
+    block: boolean;
+    reason: "loop_guard" | "not_git" | "no_commits" | "fresh" | "stale";
+    sessionName: string;
+    sessionTs: number;
+    commitTs: number;
+    /** Commits under src/ since copilot-instructions.md last changed; null when unknown. */
+    docsBehind: number | null;
+    /** Newest docs/sessions/SESSION_*.md, relative to the repo; null when none. */
+    sessionDoc: string | null;
+    message: string;
+}
+export declare function normalizeName(s: string): string;
+/** The session for a repo: the newest file whose normalized name starts with the repo's. */
+export declare function findRepoSession(repo: string, sessionsDir: string): {
+    name: string;
+    ts: number;
+};
+export declare function evaluateSessionGate(input: GateInput): GateResult;
+/** `contextengine session-gate`: the Stop hook body. Exit 2 blocks the turn end, 0 lets it end. */
+export declare function cliSessionGate(args: string[]): Promise<never>;
+//# sourceMappingURL=session-gate.d.ts.map

package/dist/session-gate.js

@@ -0,0 +1,167 @@
+// [LOCKED] [SESSION-SAVE-IS-A-GATE] 2026-09-06 (moved here from scripts/session-gate.sh, 2.7.0)
+// [NEVER] turn this back into a reminder (exit 0 with a message), gate it on a wall clock, or
+//         make it block outside a git repo.
+// WHY: the owner had to type "check and update session and ce docs!" at the end of every session
+//      ("why do I have to write this systematically?", 2026-09-06). The firewall nag lives inside
+//      MCP tool responses and the post-push hook only reminds; on 2026-09-05 the MCP server was
+//      disconnected for hours and the work went through the CLI, so nothing fired. A rule that
+//      lives in prose is not a rule; a Stop hook that refuses is. The first version was a shell
+//      script copied into 33 repos, which no paying user could get; now it ships in the package
+//      and `install-claude-hook` wires it once, at user scope, for every repo the user opens.
+// FIX: compare the repo's CE session file (newest session whose normalized name starts with the
+//      repo's normalized basename) with the last commit's time. Older = block (exit 2) with the
+//      session-doc and copilot-instructions staleness in the same message, so the docs get the
+//      same pass. `stop_hook_active` from Claude Code means "you are already continuing because
+//      of me": never block twice. Not a git repo, or no commit yet: nothing to gate, pass.
+import { existsSync, readdirSync, statSync } from "fs";
+import { basename, join } from "path";
+import { homedir } from "os";
+import { execFileSync } from "child_process";
+export function normalizeName(s) {
+    return s.toLowerCase().replace(/[^a-z0-9]/g, "");
+}
+function mtime(p) {
+    try {
+        return Math.floor(statSync(p).mtimeMs / 1000);
+    }
+    catch {
+        return 0;
+    }
+}
+function git(repo, args) {
+    try {
+        // Hardcoded argv, no shell; the only variable parts are paths and a commit hash git itself printed.
+        return execFileSync("git", args, { cwd: repo, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], timeout: 5000 }).trim();
+    }
+    catch {
+        return null;
+    }
+}
+/** The session for a repo: the newest file whose normalized name starts with the repo's. */
+export function findRepoSession(repo, sessionsDir) {
+    const name = basename(repo);
+    const want = normalizeName(name);
+    let best = { name, ts: 0 };
+    let files = [];
+    try {
+        files = readdirSync(sessionsDir);
+    }
+    catch {
+        return best;
+    }
+    for (const f of files) {
+        if (!f.endsWith(".json"))
+            continue;
+        const base = f.slice(0, -5);
+        if (!normalizeName(base).startsWith(want))
+            continue;
+        const ts = mtime(join(sessionsDir, f));
+        if (ts > best.ts)
+            best = { name: base, ts };
+    }
+    return best;
+}
+function newestSessionDoc(repo) {
+    const dir = join(repo, "docs", "sessions");
+    let files = [];
+    try {
+        files = readdirSync(dir).filter((f) => /^SESSION_.*\.md$/.test(f));
+    }
+    catch {
+        return null;
+    }
+    let best = null;
+    for (const f of files) {
+        const ts = mtime(join(dir, f));
+        if (!best || ts > best.ts)
+            best = { f, ts };
+    }
+    return best ? join("docs", "sessions", best.f) : null;
+}
+function docsBehind(repo) {
+    const ci = ".github/copilot-instructions.md";
+    if (!existsSync(join(repo, ci)))
+        return null;
+    const last = git(repo, ["log", "-1", "--format=%H", "--", ci]);
+    if (!last)
+        return null;
+    const n = git(repo, ["rev-list", "--count", `${last}..HEAD`, "--", "src"]);
+    return n === null ? null : Number(n) || 0;
+}
+function fmt(ts) {
+    return ts === 0 ? "never saved" : new Date(ts * 1000).toISOString().slice(0, 16).replace("T", " ") + "Z";
+}
+export function evaluateSessionGate(input) {
+    const repo = input.repo;
+    const name = basename(repo);
+    const sessionsDir = input.sessionsDir ?? join(process.env.CONTEXTENGINE_HOME || join(homedir(), ".contextengine"), "sessions");
+    const base = { sessionName: name, sessionTs: 0, commitTs: 0, docsBehind: null, sessionDoc: null };
+    if (input.stopHookActive)
+        return { ...base, block: false, reason: "loop_guard", message: "" };
+    if (!git(repo, ["rev-parse", "--git-dir"]))
+        return { ...base, block: false, reason: "not_git", message: "" };
+    const commitRaw = git(repo, ["log", "-1", "--format=%ct"]);
+    const commitTs = commitRaw ? Number(commitRaw) || 0 : 0;
+    if (commitTs === 0)
+        return { ...base, block: false, reason: "no_commits", message: "" };
+    let session;
+    if (input.sessionFile)
+        session = { name: name, ts: existsSync(input.sessionFile) ? mtime(input.sessionFile) : 0 };
+    else
+        session = findRepoSession(repo, sessionsDir);
+    const doc = newestSessionDoc(repo);
+    const behind = docsBehind(repo);
+    const filled = { ...base, sessionName: session.name, sessionTs: session.ts, commitTs, docsBehind: behind, sessionDoc: doc };
+    if (session.ts >= commitTs)
+        return { ...filled, block: false, reason: "fresh", message: "" };
+    const lines = [
+        `CE session gate: session '${session.name}' (${fmt(session.ts)}) is older than the last commit (${fmt(commitTs)}). Before ending:`,
+        `1. save_session (MCP) session='${session.name}' keys summary and open, with what changed since the last save;`,
+        `2. update ${doc ?? "docs/sessions/SESSION_N.md"} if the work changed and commit it;`,
+        behind === null
+            ? `3. no .github/copilot-instructions.md here; if the project has agent docs, update them the same way;`
+            : `3. .github/copilot-instructions.md is ${behind} src commit(s) behind; update it if any of them changed how the project works;`,
+        `4. save_learning for any reusable lesson. Then end the turn; this gate passes once the session file is newer than HEAD.`,
+    ];
+    return { ...filled, block: true, reason: "stale", message: lines.join("\n") };
+}
+/** Read Claude Code's hook payload from stdin without ever blocking on a TTY. */
+async function readStdinJson() {
+    if (process.stdin.isTTY)
+        return {};
+    return new Promise((resolve) => {
+        let buf = "";
+        const done = () => { try {
+            resolve(buf.trim() ? JSON.parse(buf) : {});
+        }
+        catch {
+            resolve({});
+        } };
+        process.stdin.setEncoding("utf8");
+        process.stdin.on("data", (d) => { buf += d; });
+        process.stdin.on("end", done);
+        process.stdin.on("error", done);
+        setTimeout(done, 1500).unref();
+    });
+}
+/** `contextengine session-gate`: the Stop hook body. Exit 2 blocks the turn end, 0 lets it end. */
+export async function cliSessionGate(args) {
+    if (args.includes("-h") || args.includes("--help")) {
+        console.log(`Usage: contextengine session-gate   (as a Claude Code Stop hook; see install-claude-hook)
+
+Refuses to end a Claude Code turn (exit 2, reason on stderr) while the repo's CE session is
+older than the last commit. The repo is CLAUDE_PROJECT_DIR or the cwd; the session is the newest
+~/.contextengine/sessions/*.json whose name starts with the repo's name. Passes (exit 0) when the
+session is newer, outside a git repo, before the first commit, or when stop_hook_active is set.`);
+        process.exit(0);
+    }
+    const payload = await readStdinJson();
+    const repo = process.env.CLAUDE_PROJECT_DIR || process.cwd();
+    const r = evaluateSessionGate({ repo, stopHookActive: payload.stop_hook_active === true });
+    if (r.block) {
+        console.error(r.message);
+        process.exit(2);
+    }
+    process.exit(0);
+}
+//# sourceMappingURL=session-gate.js.map

package/package.json

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

package/skills/opscontext/SKILL.md

@@ -120,6 +120,7 @@ Add to your OpenClaw `openclaw.json` MCP servers section:
 | `list_projects` | Discover and analyze all projects (tech stack, git, docker, pm2) |
 | `check_ports` | Scan all projects for port conflicts |
 | `run_audit` | Compliance agent — git remotes, hooks, .env, Docker, PM2, versions |
+| CLI `session-gate` | Claude Code Stop hook (installed by `install-claude-hook`): a turn cannot end while the repo's CE session is older than the last commit |
 | `score_project` | AI-readiness scoring 0-100% with anti-gaming v2 (symlink/ghost config detection) |
 | `save_session` | Save key-value entry to a named session for cross-session persistence |
 | `load_session` | Load all entries from a named session |