@compr/opscontext-mcp 2.6.1 → 2.7.1

package/CHANGELOG.md

@@ -4,6 +4,43 @@ 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.1] 2026-09-06: the autostart agent is the standing indexer; servers --cost
+
+### Changed
+
+- **`install-autostart` writes a plist that makes the agent the standing indexer**
+  (`[AUTOSTART-IS-THE-STANDING-INDEXER]`): `ProcessType Standard` instead of `Background` (as
+  Background it got 2.5 s of CPU in 15 minutes under load and served nobody),
+  `CONTEXTENGINE_SHARED_INDEX=1`, and `CONTEXTENGINE_CONFIG` / `CONTEXTENGINE_WORKSPACES` passed
+  through from the installing shell so its corpus id equals the chats'. The Claude-memory skip is
+  no longer a default; it is passed through only when the installer itself ran with it. Re-run
+  `install-autostart --force` to pick this up.
+- **`contextengine servers --cost`**: CPU time and resident memory per server and in total, the
+  number that was invisible on 2026-09-05 until someone ran `ps` by hand.
+- **The session-gate wrapper prefers a global install** of the CLI (`npm root -g`) over the
+  directory the installer ran from, so an npx cache prune cannot break the Stop hook.
+
+## [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

@@ -162,10 +162,12 @@ Companion commands: `uninstall-autostart`, `autostart-status`.
 **3c. Wire Claude Code terminal sessions**
 
 ```bash
-npx @compr/opscontext-mcp install-claude-hook
+npm i -g @compr/opscontext-mcp && opscontext 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.
+(Prefer the global install here: the hook scripts keep absolute paths to the CLI, and an `npx` cache copy can be pruned.)
+
+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 +527,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

@@ -2527,7 +2527,7 @@ Usage:
                                        Export hash-chained audit log (evidence aligned with
                                        SOC 2 CC7.2 + ISO 27001 A.12.4.1 — not a certification)
   contextengine audit-verify           Verify audit log chain integrity (tamper detection)
-  contextengine servers                List running MCP servers, their build vs the file on disk
+  contextengine servers [--cost]       List running MCP servers, their build vs the file on disk, role; --cost adds CPU time and memory
   contextengine audit-redact-ack       Acknowledge deliberately redacted records on the chain (--index i,j --reason "...")
   contextengine audit-rotate [--keep-days N] [--max-records N] [--dry-run]
                                        Move old history into an archive segment. Archives
@@ -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
@@ -2741,7 +2742,7 @@ else if (command === "audit-rotate") {
 }
 else if (command === "servers") {
     const fleet = listServers();
-    console.log(formatServers(fleet));
+    console.log(formatServers(fleet, undefined, { cost: process.argv.includes("--cost") }));
     process.exit(fleet.warnings.length > 0 ? 1 : 0);
 }
 else if (command === "audit-verify") {
@@ -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/index.js

@@ -1402,6 +1402,14 @@ async function main() {
     else
         startIndexPolling();
     startRolePolling();
+    // 5b. A daemon (launchd, OPSCONTEXT_DAEMON=1) has stdin on /dev/null, so the stdio transport
+    // closes at once; as a reader it holds no watchers and every poller is unref'd, and the loop
+    // would drain and exit 0, which KeepAlive turns into a restart every 10 s. Hold the loop open.
+    // [LOCK] [AUTOSTART-IS-THE-STANDING-INDEXER]
+    if (process.env.OPSCONTEXT_DAEMON === "1") {
+        setInterval(() => { }, 60_000);
+        console.error("[ContextEngine] 🛡 Daemon mode: staying alive without an MCP client");
+    }
     // 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).

package/dist/install-autostart.d.ts

@@ -1,3 +1,4 @@
+export declare function buildPlist(nodePath: string, entryPath: string, nodeBinDir: string, env?: NodeJS.ProcessEnv): string;
 export declare function cliInstallAutostart(args: string[]): Promise<void>;
 export declare function cliUninstallAutostart(args: string[]): Promise<void>;
 export declare function cliAutostartStatus(args: string[]): Promise<void>;

package/dist/install-autostart.js

@@ -87,7 +87,30 @@ function detectOpscontextEntry() {
     }
     return null;
 }
-function buildPlist(nodePath, entryPath, nodeBinDir) {
+// [LOCKED] [AUTOSTART-IS-THE-STANDING-INDEXER] 2026-09-06
+// [NEVER] run the agent as ProcessType Background, drop CONTEXTENGINE_SHARED_INDEX from its
+//         environment, or give it a corpus the chats do not have.
+// WHY: measured 2026-09-05 (SESSION_26): as Background the agent got 2.5 s of CPU in 15 minutes
+//      under load, took 4.5 min from exec to main(), served no MCP client (stdin is /dev/null),
+//      lost the browser-event port to whichever chat started first, and, with the memory skip and
+//      no config, indexed a corpus no chat used. It burned CPU keeping a cache warm that never
+//      hit. As the standing indexer it is the oldest server at every login, so it wins the
+//      election, every chat opens onto a ready index, and it owns the port from boot.
+// FIX: Standard priority; the shared-index flag; CONTEXTENGINE_CONFIG passed through from the
+//      installing shell so its corpus id equals the chats'; the memory skip only if the installer
+//      was itself run with it (an explicit choice, not a default).
+export function buildPlist(nodePath, entryPath, nodeBinDir, env = process.env) {
+    // OPSCONTEXT_DAEMON tells the server it has no MCP client on stdin and must stay alive on its
+    // own: as a reader it holds no file watchers, and every poller is unref'd, so without this the
+    // event loop drained and launchd restarted it every 10 s (found 2026-09-06, first real run).
+    const passthrough = [["CONTEXTENGINE_SHARED_INDEX", "1"], ["OPSCONTEXT_DAEMON", "1"]];
+    if (env.CONTEXTENGINE_CONFIG)
+        passthrough.push(["CONTEXTENGINE_CONFIG", env.CONTEXTENGINE_CONFIG]);
+    if (env.CONTEXTENGINE_WORKSPACES)
+        passthrough.push(["CONTEXTENGINE_WORKSPACES", env.CONTEXTENGINE_WORKSPACES]);
+    if (env.OPSCONTEXT_SKIP_CLAUDE_MEMORY === "1")
+        passthrough.push(["OPSCONTEXT_SKIP_CLAUDE_MEMORY", "1"]);
+    const extraEnv = passthrough.map(([k, v]) => `        <key>${k}</key>\n        <string>${v.replace(/&/g, "&amp;").replace(/</g, "&lt;")}</string>`).join("\n");
     return `<?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
 <plist version="1.0">
@@ -107,8 +130,7 @@ function buildPlist(nodePath, entryPath, nodeBinDir) {
         <string>${nodeBinDir}:/usr/local/bin:/usr/bin:/bin</string>
         <key>HOME</key>
         <string>${homedir()}</string>
-        <key>OPSCONTEXT_SKIP_CLAUDE_MEMORY</key>
-        <string>1</string>
+${extraEnv}
     </dict>
 
     <key>WorkingDirectory</key>
@@ -130,7 +152,7 @@ function buildPlist(nodePath, entryPath, nodeBinDir) {
     <string>${join(LOG_DIR, "mcp-stderr.log")}</string>
 
     <key>ProcessType</key>
-    <string>Background</string>
+    <string>Standard</string>
 </dict>
 </plist>
 `;

package/dist/install-claude-hook.js

@@ -15,12 +15,22 @@
 // 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";
+import { execSync } from "child_process";
+// [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 +62,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))
@@ -61,6 +71,17 @@ function bundledHookSource() {
     }
     return null;
 }
+/** dist/cli.js of a global install, when there is one (same preference as install-autostart). */
+function globalCliPath() {
+    try {
+        const root = execSync("npm root -g 2>/dev/null", { encoding: "utf-8" }).trim();
+        const c = join(root, "@compr", "opscontext-mcp", "dist", "cli.js");
+        return existsSync(c) ? c : null;
+    }
+    catch {
+        return null;
+    }
+}
 export async function cliInstallClaudeHook(args) {
     const help = args.includes("-h") || args.includes("--help");
     if (help) {
@@ -73,10 +94,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 +154,20 @@ 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.
+    // Prefer the global install: an npx cache copy can be pruned and the hook would then exit 127.
+    const cliPath = globalCliPath() ?? 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 +197,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/server-registry.d.ts

@@ -43,5 +43,17 @@ export declare function registerServer(opts: {
 };
 /** Read every record, drop the dead ones, compare builds with the files on disk now. */
 export declare function listServers(): ServerReport;
-export declare function formatServers(report: ServerReport, home?: string): string;
+/** CPU seconds consumed and resident memory of a live pid, from ps (hardcoded argv, no shell). */
+export declare function processCost(pid: number): {
+    cpuSeconds: number;
+    rssMb: number;
+} | null;
+/**
+ * The listing. With `cost`, each line also carries CPU time and memory, and the total: this is
+ * the number that was invisible on 2026-09-05 (9.3 CPU-hours across eleven servers) until
+ * someone ran ps by hand. [LOCK] [ONE-INDEXER-MANY-READERS]
+ */
+export declare function formatServers(report: ServerReport, home?: string, opts?: {
+    cost?: boolean;
+}): string;
 //# sourceMappingURL=server-registry.d.ts.map

package/dist/server-registry.js

@@ -145,16 +145,57 @@ export function listServers() {
     }
     return report;
 }
-export function formatServers(report, home = homedir()) {
+/** CPU seconds consumed and resident memory of a live pid, from ps (hardcoded argv, no shell). */
+export function processCost(pid) {
+    try {
+        const out = execFileSync("ps", ["-o", "time=,rss=", "-p", String(pid)], { encoding: "utf8", timeout: 2000 }).trim();
+        const [time, rss] = out.split(/\s+/);
+        if (!time)
+            return null;
+        const parts = time.split(":").map(Number);
+        const cpuSeconds = parts.length === 3 ? parts[0] * 3600 + parts[1] * 60 + parts[2] : parts[0] * 60 + (parts[1] || 0);
+        return { cpuSeconds, rssMb: Math.round(Number(rss || 0) / 1024) };
+    }
+    catch {
+        return null;
+    }
+}
+function fmtCpu(s) {
+    if (s >= 3600)
+        return `${(s / 3600).toFixed(1)} CPU-h`;
+    if (s >= 60)
+        return `${Math.round(s / 60)} CPU-min`;
+    return `${Math.round(s)} CPU-s`;
+}
+/**
+ * The listing. With `cost`, each line also carries CPU time and memory, and the total: this is
+ * the number that was invisible on 2026-09-05 (9.3 CPU-hours across eleven servers) until
+ * someone ran ps by hand. [LOCK] [ONE-INDEXER-MANY-READERS]
+ */
+export function formatServers(report, home = homedir(), opts = {}) {
     const short = (p) => p.startsWith(home) ? "~" + p.slice(home.length) : p;
     const lines = [];
     lines.push(`${report.servers.length} server(s) running${report.removed ? `, ${report.removed} dead record(s) removed` : ""}`);
+    let cpuTotal = 0, rssTotal = 0;
     for (const s of report.servers) {
         const t = s.started.slice(11, 19) + "Z";
         const flag = s.staleBuild ? `STALE BUILD (disk ${s.currentBuild})` : s.currentBuild === null ? "script missing on disk" : "current";
         const role = s.role ? `  ${s.role.padEnd(7)} corpus ${s.corpus ?? "?"}` : "";
-        lines.push(`  pid ${String(s.pid).padEnd(6)} ${t}  v${s.version}  build ${s.build}  ${flag}${role}  parent ${s.parent}  cwd ${short(s.cwd)}`);
+        let cost = "";
+        if (opts.cost) {
+            const c = processCost(s.pid);
+            if (c) {
+                cpuTotal += c.cpuSeconds;
+                rssTotal += c.rssMb;
+                cost = `  ${fmtCpu(c.cpuSeconds).padStart(11)} ${String(c.rssMb).padStart(5)} MB`;
+            }
+            else
+                cost = "  (cost unknown)";
+        }
+        lines.push(`  pid ${String(s.pid).padEnd(6)} ${t}  v${s.version}  build ${s.build}  ${flag}${role}${cost}  parent ${s.parent}  cwd ${short(s.cwd)}`);
     }
+    if (opts.cost && report.servers.length > 0)
+        lines.push(`  total: ${fmtCpu(cpuTotal)}, ${rssTotal} MB resident, across ${report.servers.length} server(s)`);
     for (const w of report.warnings)
         lines.push(`  ⚠ ${w}`);
     return lines.join("\n");

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.1",
   "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 |