@compr/opscontext-mcp 2.5.1 → 2.5.3

package/dist/audit.d.ts

@@ -1,4 +1,4 @@
-export type AuditEvent = "learning.save" | "learning.delete" | "learning.import" | "learning.export" | "session.save" | "session.delete" | "activation.activate" | "activation.deactivate" | "activation.heartbeat" | "activation.signature_reject" | "activation.legacy_signature" | "firewall.escalate" | "hook.block" | "hook.bypass" | "policy.skipped" | "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" | "community.sync_ok" | "community.sync_error";
+export type AuditEvent = "learning.save" | "learning.delete" | "learning.import" | "learning.export" | "session.save" | "session.delete" | "activation.activate" | "activation.deactivate" | "activation.heartbeat" | "activation.signature_reject" | "activation.legacy_signature" | "firewall.escalate" | "hook.block" | "hook.bypass" | "policy.skipped" | "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" | "community.sync_ok" | "community.sync_error" | "audit.rotate";
 export interface AuditRecord {
     ts: string;
     event: AuditEvent;
@@ -8,7 +8,64 @@ export interface AuditRecord {
     hash: string;
 }
 export declare function appendAudit(event: AuditEvent, payload: Record<string, unknown>, actor?: string): AuditRecord;
-export declare function readAuditLog(): AuditRecord[];
+/** Archived segment filenames in chain order (oldest first). */
+export declare function listSegments(): string[];
+export interface ReadOptions {
+    /** Include archived segments. Default true — callers asking for "the audit log" mean
+     *  the whole history. Hot paths that only care about a recent window pass false. */
+    includeArchives?: boolean;
+}
+export declare function readAuditLog(opts?: ReadOptions): AuditRecord[];
+export interface RotationPlan {
+    /** Records that would move to a segment. */
+    archiveCount: number;
+    /** Records that would stay in the live log. */
+    keepCount: number;
+    /** Timestamp cutoff: records strictly older than this are archived. */
+    cutoff: string;
+    segmentFile: string | null;
+    /** Set when the rotation must not run, with the reason. */
+    refusedReason: string | null;
+}
+export interface RotationResult extends RotationPlan {
+    rotated: boolean;
+    bytesArchived: number;
+    bytesRemaining: number;
+}
+export interface RotateOptions {
+    /** Archive records older than this many days. Minimum 1. */
+    keepDays?: number;
+    /**
+     * Hard ceiling on how many records stay in the live log, whatever the dates say.
+     *
+     * 🔒 LOCKED [DATE-RETENTION-DOES-NOT-BOUND-SIZE] — 2026-08-20
+     * ⛔ NEVER ship rotation with a date rule alone.
+     * WHY: measured on the real log before shipping this — at 80,000 records/day, a 30-day
+     *      window left 390,445 records live and even a 3-day window left 205,422. Date
+     *      retention bounds AGE, not SIZE, so on a busy machine it rotates and changes
+     *      nothing that matters: readAuditLog() still costs seconds and hundreds of MB.
+     *      The feature would have looked like it worked while leaving the problem in place.
+     * FIX: cut at whichever rule archives more, date or count. Count is what actually caps
+     *      the file.
+     */
+    maxRecords?: number;
+    /** Report what would happen and write nothing. */
+    dryRun?: boolean;
+    now?: number;
+}
+/**
+ * Plan a rotation without writing anything. Exported so the CLI's dry-run and the real
+ * run share one implementation and cannot disagree.
+ */
+export declare function planRotation(opts?: RotateOptions): RotationPlan;
+/**
+ * Move everything older than the cutoff into a numbered archive segment.
+ *
+ * Refuses to run on a chain that does not currently verify: rotating a log with altered
+ * or orphaned records would bake the damage into an append-only segment and make the
+ * cause unrecoverable. Forks are fine — they are concurrency, not tampering.
+ */
+export declare function rotateAuditLog(opts?: RotateOptions): RotationResult;
 export interface IntegrityReport {
     ok: boolean;
     total: number;

package/dist/audit.js

@@ -46,7 +46,7 @@
 // Records every state-changing operation. Each line carries the SHA-256 hash
 // of the previous line's canonical content, so mutation of any historical
 // record breaks chain verification at that index.
-import { existsSync, mkdirSync, readFileSync, appendFileSync, openSync, closeSync, unlinkSync, statSync, writeSync, readSync, constants, } from "fs";
+import { existsSync, mkdirSync, readFileSync, appendFileSync, openSync, closeSync, unlinkSync, statSync, writeSync, readSync, fsyncSync, renameSync, readdirSync, constants, } from "fs";
 import { join } from "path";
 import { homedir } from "os";
 import { createHash } from "crypto";
@@ -180,12 +180,35 @@ function readLastHash() {
         // Tail window held no complete record — fall back to the full read.
         return readLastHashFullScan();
     }
+    return parseHeadOrThrow(lines[lines.length - 1]);
+}
+/**
+ * 🔒 LOCKED [UNREADABLE-HEAD-IS-NOT-GENESIS] — 2026-08-20
+ * ⛔ NEVER return GENESIS_HASH because the last line failed to parse.
+ * WHY: both head readers ended in `catch { return GENESIS_HASH }`. A truncated or corrupt
+ *      final record — a partial write, a full disk, a killed process — therefore made the
+ *      next append chain onto genesis instead of onto the real head. verifyChain() reports
+ *      that as an ORPHAN, i.e. "history was deleted", the hardest failure the log can
+ *      produce, and it would be caused by the writer itself rather than by tampering.
+ *      It is [ABSENCE-IS-NOT-A-VERDICT] on the bedrock path: "I could not read the head"
+ *      was rendered as the specific, plausible claim "there is no history".
+ * FIX: throw. appendAudit() must surface problems loudly (see [AUDIT-CHAIN]); call sites
+ *      that need isolation already use safeAppend(), which logs to stderr and continues.
+ */
+function parseHeadOrThrow(line) {
+    let rec;
     try {
-        return JSON.parse(lines[lines.length - 1]).hash;
+        rec = JSON.parse(line);
     }
     catch {
-        return GENESIS_HASH;
+        throw new Error("Audit log tail is not valid JSON — refusing to append onto an unknown head. " +
+            "Inspect the last line of ~/.contextengine/audit.log; a partial final record can be " +
+            "removed by hand, which verifyChain() will then confirm.");
     }
+    if (typeof rec.hash !== "string" || rec.hash.length !== 64) {
+        throw new Error("Audit log tail has no usable hash — refusing to append onto an unknown head.");
+    }
+    return rec.hash;
 }
 /** Fallback for the pathological case: a single record longer than TAIL_READ_BYTES. */
 function readLastHashFullScan() {
@@ -194,12 +217,8 @@ function readLastHashFullScan() {
     const lines = data.split("\n").filter(Boolean);
     if (lines.length === 0)
         return GENESIS_HASH;
-    try {
-        return JSON.parse(lines[lines.length - 1]).hash;
-    }
-    catch {
-        return GENESIS_HASH;
-    }
+    // [LOCK] [UNREADABLE-HEAD-IS-NOT-GENESIS] — same rule as the tail reader.
+    return parseHeadOrThrow(lines[lines.length - 1]);
 }
 function computeHash(prevHash, ts, event, actor, payload) {
     // Canonical serialization — keys in fixed order so independent verifiers get
@@ -248,11 +267,43 @@ export function appendAudit(event, payload, actor = "system") {
         release();
     }
 }
-export function readAuditLog() {
-    const path = auditPath();
-    if (!existsSync(path))
+/**
+ * 🔒 LOCKED [ROTATION-MUST-NOT-ORPHAN-THE-CHAIN] — 2026-08-20
+ * ⛔ NEVER rotate by truncating, moving or deleting audit.log. NEVER let a rotated log
+ *    read as "history was deleted".
+ * WHY: verifyChain() classifies a record whose prev_hash names a hash absent from the log
+ *      as an ORPHAN, which is a hard failure meaning deleted or truncated history — the
+ *      exact evidence claim SOC 2 CC7.2 / ISO 27001 A.12.4.1 rest on. A `mv audit.log
+ *      audit.log.1` makes the very first record of the new file an orphan, so the naive
+ *      rotation turns a healthy log into a permanent "TAMPERED" verdict for every future
+ *      audit. The log reached 195 MB / 533,987 records with no rotation path precisely
+ *      because the safe shape was never built.
+ * FIX: rotation MOVES a prefix of history into a numbered segment under audit-archive/
+ *      and the canonical history is `segments in order ++ live log`. readAuditLog() reads
+ *      that concatenation by default, so the chain stays linear and verification is
+ *      unchanged. Segments are append-only and never rewritten.
+ *
+ * 🔒 LOCKED [ROTATE-ARCHIVE-BEFORE-TRUNCATE] — 2026-08-20
+ * ⛔ NEVER truncate the live log before the segment file is durably renamed into place.
+ * WHY: the reverse order loses records permanently on a crash between the two steps.
+ *      This order can only ever produce a DUPLICATE (records in both the segment and the
+ *      live log), which the seam de-dup below removes and which loses nothing.
+ * FIX: write segment tmp → fsync → rename → write live remainder tmp → fsync → rename.
+ */
+function archiveDir() {
+    return join(auditDir(), "audit-archive");
+}
+const SEGMENT_RE = /^audit-(\d{4,})\.jsonl$/;
+/** Archived segment filenames in chain order (oldest first). */
+export function listSegments() {
+    const dir = archiveDir();
+    if (!existsSync(dir))
         return [];
-    const data = readFileSync(path, "utf-8");
+    return readdirSync(dir)
+        .filter((f) => SEGMENT_RE.test(f))
+        .sort((a, b) => Number(SEGMENT_RE.exec(a)[1]) - Number(SEGMENT_RE.exec(b)[1]));
+}
+function parseLines(data, label) {
     return data
         .split("\n")
         .filter(Boolean)
@@ -261,10 +312,176 @@ export function readAuditLog() {
             return JSON.parse(line);
         }
         catch {
-            throw new Error(`Corrupt audit line ${i + 1}: not valid JSON`);
+            throw new Error(`Corrupt audit line ${i + 1} in ${label}: not valid JSON`);
         }
     });
 }
+export function readAuditLog(opts = {}) {
+    const includeArchives = opts.includeArchives !== false;
+    const path = auditPath();
+    const live = existsSync(path) ? parseLines(readFileSync(path, "utf-8"), "audit.log") : [];
+    if (!includeArchives)
+        return live;
+    const segments = listSegments();
+    if (segments.length === 0)
+        return live;
+    const history = [];
+    let lastSegmentHashes = new Set();
+    for (const f of segments) {
+        const recs = parseLines(readFileSync(join(archiveDir(), f), "utf-8"), f);
+        // 🔒 LOCKED [NO-SPREAD-OVER-A-SEGMENT] — 2026-08-20
+        // ⛔ NEVER use push(...records) on a segment. Found on the first real rotation:
+        //    a 494,152-record segment threw "Maximum call stack size exceeded" because the
+        //    spread passes every element as a separate argument. Every unit test passed —
+        //    they used chains of a few thousand. Push in a loop, whatever the size.
+        for (const r of recs)
+            history.push(r);
+        lastSegmentHashes = new Set(recs.map((r) => r.hash));
+    }
+    // Seam de-dup — see [ROTATE-ARCHIVE-BEFORE-TRUNCATE]. A crash after the segment was
+    // renamed but before the live log was truncated leaves the archived prefix present in
+    // both files. Drop only the LEADING run of live records already in the last segment;
+    // anything else is real history and must never be dropped.
+    let start = 0;
+    while (start < live.length && lastSegmentHashes.has(live[start].hash))
+        start++;
+    // [LOCK] [NO-SPREAD-OVER-A-SEGMENT] — same reason.
+    for (let i = start; i < live.length; i++)
+        history.push(live[i]);
+    return history;
+}
+/** Never archive below this many most-recent records, whatever the date cutoff says.
+ *  The live log has to keep enough context for the drift detectors' window. */
+const MIN_LIVE_RECORDS = 2000;
+/** Live-log ceiling when the caller does not set one. ~50k records ≈ 18 MB. */
+const DEFAULT_MAX_LIVE_RECORDS = 50_000;
+/**
+ * Plan a rotation without writing anything. Exported so the CLI's dry-run and the real
+ * run share one implementation and cannot disagree.
+ */
+export function planRotation(opts = {}) {
+    const keepDays = Math.max(1, Math.floor(opts.keepDays ?? 30));
+    const now = opts.now ?? Date.now();
+    const cutoff = new Date(now - keepDays * 86_400_000).toISOString();
+    const live = existsSync(auditPath())
+        ? parseLines(readFileSync(auditPath(), "utf-8"), "audit.log")
+        : [];
+    let cutByDate = live.findIndex((r) => r.ts >= cutoff);
+    if (cutByDate === -1)
+        cutByDate = live.length; // every record is older than the cutoff
+    // [DATE-RETENTION-DOES-NOT-BOUND-SIZE] — whichever rule archives more wins.
+    const maxRecords = Math.max(1, Math.floor(opts.maxRecords ?? DEFAULT_MAX_LIVE_RECORDS));
+    const cutByCount = Math.max(0, live.length - maxRecords);
+    let cut = Math.max(cutByDate, cutByCount);
+    // Keep the tail intact regardless of either rule.
+    cut = Math.min(cut, Math.max(0, live.length - MIN_LIVE_RECORDS));
+    const next = listSegments().length + 1;
+    return {
+        archiveCount: cut,
+        keepCount: live.length - cut,
+        cutoff,
+        segmentFile: cut > 0 ? `audit-${String(next).padStart(4, "0")}.jsonl` : null,
+        refusedReason: null,
+    };
+}
+/**
+ * Move everything older than the cutoff into a numbered archive segment.
+ *
+ * Refuses to run on a chain that does not currently verify: rotating a log with altered
+ * or orphaned records would bake the damage into an append-only segment and make the
+ * cause unrecoverable. Forks are fine — they are concurrency, not tampering.
+ */
+export function rotateAuditLog(opts = {}) {
+    const path = auditPath();
+    const plan = planRotation(opts);
+    const empty = { ...plan, rotated: false, bytesArchived: 0, bytesRemaining: 0 };
+    if (!existsSync(path)) {
+        return { ...empty, refusedReason: "no audit log on disk" };
+    }
+    if (plan.archiveCount === 0) {
+        return {
+            ...empty,
+            bytesRemaining: statSync(path).size,
+            refusedReason: `nothing to archive: ${plan.keepCount} record(s) live, within both the retention window and the size ceiling`,
+        };
+    }
+    const integrity = verifyChain();
+    if (!integrity.ok) {
+        return {
+            ...empty,
+            refusedReason: `chain does not verify (${integrity.breakReason}) — refusing to archive a damaged log`,
+        };
+    }
+    if (opts.dryRun)
+        return { ...plan, rotated: false, bytesArchived: 0, bytesRemaining: 0 };
+    ensureDir();
+    const adir = archiveDir();
+    if (!existsSync(adir))
+        mkdirSync(adir, { recursive: true });
+    // Snapshot outside the lock: parsing 500k records is far too slow to hold the append
+    // lock for, and acquireLockSync() force-breaks locks older than STALE_LOCK_MS.
+    const snapshotSize = statSync(path).size;
+    const live = parseLines(readFileSync(path, "utf-8"), "audit.log");
+    const archived = live.slice(0, plan.archiveCount);
+    const remainder = live.slice(plan.archiveCount);
+    const segName = plan.segmentFile;
+    const segTmp = join(adir, `.${segName}.tmp`);
+    const segBody = archived.map((r) => JSON.stringify(r)).join("\n") + "\n";
+    writeFileAndSync(segTmp, segBody);
+    renameSync(segTmp, join(adir, segName));
+    // [ROTATE-ARCHIVE-BEFORE-TRUNCATE]: the segment is durable from here on. Only now may
+    // the live log shrink.
+    const release = acquireLockSync();
+    let remainderBody = remainder.map((r) => JSON.stringify(r)).join("\n") + "\n";
+    try {
+        const currentSize = statSync(path).size;
+        if (currentSize > snapshotSize) {
+            // Appends landed while we were writing the segment. They are newer than the cutoff
+            // by construction, so they belong to the remainder. Copy the raw bytes across
+            // rather than re-parsing the whole file.
+            const fd = openSync(path, constants.O_RDONLY);
+            try {
+                const buf = Buffer.alloc(currentSize - snapshotSize);
+                readSync(fd, buf, 0, buf.length, snapshotSize);
+                remainderBody += buf.toString("utf-8");
+            }
+            finally {
+                closeSync(fd);
+            }
+        }
+        const liveTmp = join(auditDir(), ".audit.log.tmp");
+        writeFileAndSync(liveTmp, remainderBody);
+        renameSync(liveTmp, path);
+    }
+    finally {
+        release();
+    }
+    // Self-documenting evidence: the rotation itself is an audited event, chained onto the
+    // new head like any other record.
+    appendAudit("audit.rotate", {
+        segment: segName,
+        archived_records: archived.length,
+        first_hash: archived[0].hash,
+        last_hash: archived[archived.length - 1].hash,
+        cutoff: plan.cutoff,
+    }, "system");
+    return {
+        ...plan,
+        rotated: true,
+        bytesArchived: Buffer.byteLength(segBody),
+        bytesRemaining: statSync(path).size,
+    };
+}
+function writeFileAndSync(target, body) {
+    const fd = openSync(target, "w");
+    try {
+        writeSync(fd, body);
+        fsyncSync(fd);
+    }
+    finally {
+        closeSync(fd);
+    }
+}
 /**
  * 🔒 LOCKED [VERIFY-FORK-IS-NOT-TAMPER] — 2026-08-17
  * ⛔ NEVER report a forked chain as "the log was edited", and never stop at the first

package/dist/cli-commands.d.ts

@@ -0,0 +1,30 @@
+/**
+ * 🔒 LOCKED [UNKNOWN-COMMAND-MUST-NOT-START-A-SERVER] — 2026-08-20
+ * ⛔ NEVER route an unrecognised argv[2] to the MCP server again. The MCP server starts
+ *    ONLY on a bare invocation, or on the explicit `serve` alias.
+ * WHY: `cli.ts` dispatched with a long if/else chain ending in `else { import("./index.js") }`,
+ *      so ANY unknown token started a stdio server that silently waits on stdin. A typo
+ *      (`contextengine scor`), a flag-first invocation (`contextengine --version`) or a
+ *      renamed subcommand produced no error, no exit code, and no output — it hung.
+ *      This is [ABSENCE-IS-NOT-A-VERDICT] at the dispatch layer: "I do not recognise this"
+ *      was rendered as "start the default mode", a plausible action chosen from a branch
+ *      that had determined nothing. It has already cost a wrong finding: SESSION_22 §E3
+ *      recorded "check_ports is ungated on the CLI" when there is no `check-ports` command
+ *      at all — what got measured was an MCP server booting.
+ * FIX: KNOWN_COMMANDS below is the single source of truth. Unknown token → name it on
+ *      stderr, suggest the nearest command, exit 1. A parity test asserts this list matches
+ *      the literals the dispatcher actually handles, so the two cannot drift.
+ */
+/** Every token `cli.ts` dispatches on, including flag-style aliases. */
+export declare const KNOWN_COMMANDS: readonly string[];
+/** Commands that start the stdio MCP server. A bare invocation (argv[2] undefined)
+ *  does the same — that is the documented default and every launcher on disk uses it. */
+export declare const SERVER_COMMANDS: readonly string[];
+/**
+ * Closest known commands to `input`, nearest first, at most `limit`.
+ * Returns [] when nothing is close enough — an empty suggestion list is honest,
+ * a wrong suggestion is not.
+ */
+export declare function suggestCommands(input: string, limit?: number): string[];
+export declare function isKnownCommand(token: string): boolean;
+//# sourceMappingURL=cli-commands.d.ts.map

package/dist/cli-commands.js

@@ -0,0 +1,102 @@
+/**
+ * 🔒 LOCKED [UNKNOWN-COMMAND-MUST-NOT-START-A-SERVER] — 2026-08-20
+ * ⛔ NEVER route an unrecognised argv[2] to the MCP server again. The MCP server starts
+ *    ONLY on a bare invocation, or on the explicit `serve` alias.
+ * WHY: `cli.ts` dispatched with a long if/else chain ending in `else { import("./index.js") }`,
+ *      so ANY unknown token started a stdio server that silently waits on stdin. A typo
+ *      (`contextengine scor`), a flag-first invocation (`contextengine --version`) or a
+ *      renamed subcommand produced no error, no exit code, and no output — it hung.
+ *      This is [ABSENCE-IS-NOT-A-VERDICT] at the dispatch layer: "I do not recognise this"
+ *      was rendered as "start the default mode", a plausible action chosen from a branch
+ *      that had determined nothing. It has already cost a wrong finding: SESSION_22 §E3
+ *      recorded "check_ports is ungated on the CLI" when there is no `check-ports` command
+ *      at all — what got measured was an MCP server booting.
+ * FIX: KNOWN_COMMANDS below is the single source of truth. Unknown token → name it on
+ *      stderr, suggest the nearest command, exit 1. A parity test asserts this list matches
+ *      the literals the dispatcher actually handles, so the two cannot drift.
+ */
+/** Every token `cli.ts` dispatches on, including flag-style aliases. */
+export const KNOWN_COMMANDS = [
+    "--help",
+    "--version",
+    "-h",
+    "-v",
+    "activate",
+    "audit",
+    "audit-export",
+    "audit-rotate",
+    "audit-verify",
+    "autostart-status",
+    "cost",
+    "deactivate",
+    "delete-learning",
+    "delete-session",
+    "emit-event",
+    "end-session",
+    "export-learnings",
+    "help",
+    "hook",
+    "import-learnings",
+    "init",
+    "init-extension-secret",
+    "install-autostart",
+    "install-claude-hook",
+    "install-skill",
+    "list-learnings",
+    "list-projects",
+    "list-sessions",
+    "list-sources",
+    "load-session",
+    "policy",
+    "save-learning",
+    "save-session",
+    "score",
+    "search",
+    "serve",
+    "stats",
+    "status",
+    "sync-claude-md",
+    "sync-community-rules",
+    "uninstall-autostart",
+    "uninstall-claude-hook",
+    "version",
+    "watch",
+];
+/** Commands that start the stdio MCP server. A bare invocation (argv[2] undefined)
+ *  does the same — that is the documented default and every launcher on disk uses it. */
+export const SERVER_COMMANDS = ["serve"];
+/** Levenshtein distance, capped early — only used to build a "did you mean" line. */
+function editDistance(a, b) {
+    const m = a.length;
+    const n = b.length;
+    if (Math.abs(m - n) > 4)
+        return 99;
+    let prev = Array.from({ length: n + 1 }, (_, i) => i);
+    for (let i = 1; i <= m; i++) {
+        const cur = [i];
+        for (let j = 1; j <= n; j++) {
+            cur[j] = Math.min(prev[j] + 1, cur[j - 1] + 1, prev[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
+        }
+        prev = cur;
+    }
+    return prev[n];
+}
+/**
+ * Closest known commands to `input`, nearest first, at most `limit`.
+ * Returns [] when nothing is close enough — an empty suggestion list is honest,
+ * a wrong suggestion is not.
+ */
+export function suggestCommands(input, limit = 3) {
+    const candidates = KNOWN_COMMANDS.filter((c) => !c.startsWith("-"));
+    const scored = candidates
+        .map((c) => ({ c, d: editDistance(input.toLowerCase(), c) }))
+        // A prefix match is always relevant however long the tail ("audit" → "audit-export").
+        .map((s) => ({ ...s, d: s.c.startsWith(input.toLowerCase()) ? Math.min(s.d, 2) : s.d }))
+        .filter((s) => s.d <= 3)
+        .sort((a, b) => a.d - b.d || a.c.localeCompare(b.c));
+    return scored.slice(0, limit).map((s) => s.c);
+}
+export function isKnownCommand(token) {
+    return KNOWN_COMMANDS.includes(token);
+}
+//# sourceMappingURL=cli-commands.js.map

package/dist/cli.js

@@ -226,6 +226,52 @@ function generateMcpJson() {
 // ---------------------------------------------------------------------------
 // Template for pre-commit hook (CE doc freshness + secret scanner)
 // ---------------------------------------------------------------------------
+/**
+ * 🔒 LOCKED [SKIPPING-A-HOOK-MUST-NAME-WHAT-IS-UNENFORCED] — 2026-08-20
+ * ⛔ NEVER print a bare "already exists, skipping" for a hook slot. NEVER overwrite or
+ *    append to a foreign hook either.
+ * WHY: `init` refuses to clobber an existing hook, which is right, but it said so with one
+ *      grey line among a column of green ticks. The user reads "init done" and believes the
+ *      policy gates are live; in that repo they were never installed and enforce nothing.
+ *      This is exactly §E1 arriving through a different door: there, the rule existed and no
+ *      hook called it; here, a hook exists and does not call the rule. Both produce a gate
+ *      that is present in every document and absent at runtime, and neither produces an error.
+ *      A real instance is on this machine: invocme-odoo-connector has a hand-written
+ *      pre-commit, so `init` skipped it, and none of that repo's CE gates have ever run.
+ *      Appending instead is not the fix, and is how that repo ended up with a whole secret
+ *      scanner sitting unreachable behind an earlier `exit 0`.
+ * FIX: on skip, read the existing hook. If it does not invoke the CE CLI, say which gates are
+ *      therefore unenforced and print the one line that wires them in. Silence here reads as
+ *      success.
+ */
+function existingHookInvokesCE(path) {
+    try {
+        const body = readFileSync(path, "utf-8");
+        return /\b(contextengine|opscontext)\b/.test(body);
+    }
+    catch {
+        // Unreadable is not proof of absence; say nothing rather than claim a verdict.
+        return true;
+    }
+}
+function warnSkippedHook(path, slot) {
+    if (existingHookInvokesCE(path))
+        return;
+    const gates = {
+        "pre-commit": "secret-scan, doc-coverage, rule-parity",
+        "commit-msg": "commit-message-required",
+        "post-commit": "audit trail of the push",
+    };
+    const wire = {
+        "pre-commit": 'contextengine hook secret-scan && contextengine hook doc-coverage && contextengine hook rule-parity',
+        "commit-msg": 'contextengine hook commit-message-required "$1"',
+        "post-commit": "contextengine end-session",
+    };
+    console.log(`     ⚠️  that hook never calls ContextEngine, so these enforce NOTHING here:`);
+    console.log(`        ${gates[slot]}`);
+    console.log(`        Wire them by adding this line to ${path}:`);
+    console.log(`          ${wire[slot]}`);
+}
 function generatePreCommitHook() {
     const lines = [];
     lines.push("#!/bin/zsh");
@@ -508,7 +554,8 @@ async function runInit() {
             const postCommitDest = join(hooksDir, "post-commit");
             const commitMsgDest = join(hooksDir, "commit-msg");
             if (existsSync(preCommitDest)) {
-                console.log("  ⏭  .git/hooks/pre-commit already exists — skipping");
+                console.log("  ⏭  .git/hooks/pre-commit already exists — skipping (never overwritten)");
+                warnSkippedHook(preCommitDest, "pre-commit");
                 skipped++;
             }
             else {
@@ -523,7 +570,8 @@ async function runInit() {
             // [COMMIT-MSG-HOOK-MUST-BE-INSTALLED] — without this, every
             // commit_message_required rule is silently unenforced.
             if (existsSync(commitMsgDest)) {
-                console.log("  ⏭  .git/hooks/commit-msg already exists — skipping");
+                console.log("  ⏭  .git/hooks/commit-msg already exists — skipping (never overwritten)");
+                warnSkippedHook(commitMsgDest, "commit-msg");
                 skipped++;
             }
             else {
@@ -536,7 +584,8 @@ async function runInit() {
                 }
             }
             if (existsSync(postCommitDest)) {
-                console.log("  ⏭  .git/hooks/post-commit already exists — skipping");
+                console.log("  ⏭  .git/hooks/post-commit already exists — skipping (never overwritten)");
+                warnSkippedHook(postCommitDest, "post-commit");
                 skipped++;
             }
             else {
@@ -593,6 +642,7 @@ async function runInit() {
 import { loadSources, loadProjectDirs, loadConfig, resolveProjectDir, findProjectRoot, looksLikePath } from "./config.js";
 import { ingestSources } from "./ingest.js";
 import { searchChunks } from "./search.js";
+import { SERVER_COMMANDS, suggestCommands } from "./cli-commands.js";
 import { collectProjectOps, collectSystemOps } from "./collectors.js";
 import { scanCodeDir } from "./code-chunker.js";
 import { listProjects, runComplianceAudit, formatProjectList, formatPlan, scoreProject, runScoreCanary, formatScoreReport, generateScoreHTML, generateProjectScoreMD, } from "./agents.js";
@@ -600,7 +650,7 @@ import { listLearnings, learningsToChunks, learningsStats, formatLearnings, save
 import { saveSession, loadSession, listSessions, deleteSession, formatSession, formatSessionList, } from "./sessions.js";
 import { activate, deactivate, getActivationStatus, gateCheck, } from "./activation.js";
 import { syncTierA, syncTierB, loadCommunityStore, communityRulesToChunks, mergeWithDedup, STORE_PATH as COMMUNITY_STORE_PATH, } from "./community-sync.js";
-import { readAuditLog, verifyChain, filterByRange, toCsv, } from "./audit.js";
+import { readAuditLog, verifyChain, filterByRange, toCsv, rotateAuditLog, planRotation, listSegments, } from "./audit.js";
 import { loadRepoPolicy, parsePolicy, formatPolicySummary, formatValidationErrors, repoPolicyPath, } from "./policy.js";
 import { collectRuns, metricsFor, transcriptRoot, emptyTally, addTally, totalTokens, pricingStatus, pricingFor, } from "./transcript-collector.js";
 import { DEFAULT_PRICING, DEFAULT_PRICING_ASOF } from "./default-pricing.js";
@@ -1857,6 +1907,65 @@ reviewed, and validated in PR ahead of the hook wiring.`);
     console.error(`Unknown subcommand: ${sub}. Try 'contextengine policy --help'.`);
     process.exit(1);
 }
+function fmtBytes(n) {
+    if (n >= 1024 ** 3)
+        return `${(n / 1024 ** 3).toFixed(1)} GB`;
+    if (n >= 1024 ** 2)
+        return `${(n / 1024 ** 2).toFixed(1)} MB`;
+    if (n >= 1024)
+        return `${(n / 1024).toFixed(1)} KB`;
+    return `${n} B`;
+}
+function cliAuditRotate(args) {
+    const keepIdx = args.findIndex((a) => a === "--keep-days");
+    const keepDays = keepIdx >= 0 ? Number(args[keepIdx + 1]) : 30;
+    const maxIdx = args.findIndex((a) => a === "--max-records");
+    const maxRecords = maxIdx >= 0 ? Number(args[maxIdx + 1]) : undefined;
+    const dryRun = args.includes("--dry-run");
+    if (!Number.isFinite(keepDays) || keepDays < 1) {
+        console.error("--keep-days must be a number >= 1.");
+        process.exit(1);
+    }
+    if (maxIdx >= 0 && (!Number.isFinite(maxRecords) || maxRecords < 1)) {
+        console.error("--max-records must be a number >= 1.");
+        process.exit(1);
+    }
+    if (dryRun) {
+        const plan = planRotation({ keepDays, maxRecords });
+        console.log(`\n📦 Audit log rotation — DRY RUN, nothing written\n`);
+        console.log(`  cutoff            records older than ${plan.cutoff}`);
+        console.log(`  size ceiling      ${maxRecords ?? 50000} record(s) kept live at most`);
+        console.log(`  would archive     ${plan.archiveCount} record(s) → ${plan.segmentFile ?? "(nothing)"}`);
+        console.log(`  would keep live   ${plan.keepCount} record(s)`);
+        console.log(`\n  Run again without --dry-run to perform it.\n`);
+        return;
+    }
+    const result = rotateAuditLog({ keepDays, maxRecords });
+    if (!result.rotated) {
+        console.log(`\nNothing rotated: ${result.refusedReason}\n`);
+        // Refusing because the chain is damaged is a failure, not a no-op.
+        if (result.refusedReason?.includes("does not verify"))
+            process.exit(2);
+        return;
+    }
+    console.log(`\n📦 Audit log rotated\n`);
+    console.log(`  archived          ${result.archiveCount} record(s) → audit-archive/${result.segmentFile}`);
+    console.log(`  segment size      ${fmtBytes(result.bytesArchived)}`);
+    console.log(`  live log now      ${result.keepCount + 1} record(s), ${fmtBytes(result.bytesRemaining)}`);
+    console.log(`  segments on disk  ${listSegments().length}`);
+    console.log(`\n  History is unchanged: archived segments are part of the chain, and`);
+    console.log(`  'audit-verify' reads them. Do not delete or edit them — that is the`);
+    console.log(`  one action that would turn this into missing history.\n`);
+    const after = verifyChain();
+    if (after.ok) {
+        console.log(`  ✅ post-rotation verify: ${after.total} record(s), chain intact.\n`);
+    }
+    else {
+        console.error(`  ❌ post-rotation verify FAILED: ${after.breakReason}`);
+        console.error(`     The segment is on disk and nothing was deleted. Do not rotate again.\n`);
+        process.exit(2);
+    }
+}
 async function cliAuditVerify() {
     const report = verifyChain();
     const forks = report.forkIndices ?? [];
@@ -2478,6 +2587,17 @@ async function cliCost(argv) {
     }
     console.log("");
 }
+/** Package version, read from the installed package.json rather than hardcoded. */
+function readPackageVersion() {
+    try {
+        const here = new URL("../package.json", import.meta.url);
+        return JSON.parse(readFileSync(here, "utf-8")).version;
+    }
+    catch {
+        // No plausible-looking fallback here: an unknown version must read as unknown.
+        return "unknown";
+    }
+}
 // ---------------------------------------------------------------------------
 // Main — route to init, CLI subcommand, or MCP server
 // ---------------------------------------------------------------------------
@@ -2515,6 +2635,12 @@ 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 audit-rotate [--keep-days N] [--max-records N] [--dry-run]
+                                       Move old history into an archive segment. Archives
+                                       whatever is older than N days (default 30) OR beyond
+                                       the size ceiling (default 50000 live records),
+                                       whichever is more. The chain stays linear: segments
+                                       are part of the verified history, never deleted.
   contextengine cost [--session ID] [--project NAME] [--run wf_ID] [--days N] [--top N] [--json]
                                        Multi-agent spend from Claude Code transcripts. Always prints
                                        VOLUME (tokens), VALUED COST (API list prices — notional on a
@@ -2714,6 +2840,9 @@ else if (command === "sync-claude-md") {
         process.exit(1);
     });
 }
+else if (command === "audit-rotate") {
+    cliAuditRotate(process.argv.slice(3));
+}
 else if (command === "audit-verify") {
     cliAuditVerify().catch((err) => {
         console.error("Error:", err);
@@ -2825,8 +2954,25 @@ else if (command === "status") {
     }
     console.log("");
 }
-else {
-    // Default: start MCP server
+else if (command === undefined || SERVER_COMMANDS.includes(command)) {
+    // Documented default: a bare invocation (or the explicit `serve` alias) starts the
+    // stdio MCP server. Every launcher on this machine uses the bare form.
     import("./index.js");
 }
+else if (command === "--version" || command === "-v" || command === "version") {
+    console.log(readPackageVersion());
+}
+else {
+    // 🔒 [LOCK] [UNKNOWN-COMMAND-MUST-NOT-START-A-SERVER] — see src/cli-commands.ts
+    // An unrecognised token used to fall through to the MCP server, which then waited on
+    // stdin forever: no error, no exit code, no output. Name it and fail instead.
+    console.error(`Unknown command: ${command}`);
+    const suggestions = suggestCommands(command);
+    if (suggestions.length > 0) {
+        console.error(`Did you mean: ${suggestions.join(", ")}?`);
+    }
+    console.error(`Run 'contextengine help' for the full list.`);
+    console.error(`To start the MCP server, run 'contextengine' with no arguments.`);
+    process.exit(1);
+}
 //# sourceMappingURL=cli.js.map

package/dist/detector.js

@@ -25,7 +25,10 @@ import { homedir } from "os";
 export function scanRecentEvents(windowSeconds = 300, now = Date.now()) {
     let all;
     try {
-        all = readAuditLog();
+        // Live log only. The window is minutes; archived segments are days old by
+        // construction (see [ROTATION-MUST-NOT-ORPHAN-THE-CHAIN], MIN_LIVE_RECORDS floor),
+        // so reading them here would add the whole history to a hot path for zero hits.
+        all = readAuditLog({ includeArchives: false });
     }
     catch {
         return [];

package/package.json

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