@compr/opscontext-mcp 2.5.0 → 2.5.2

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

@@ -593,6 +593,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,9 +601,10 @@ 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, } from "./transcript-collector.js";
+import { collectRuns, metricsFor, transcriptRoot, emptyTally, addTally, totalTokens, pricingStatus, pricingFor, } from "./transcript-collector.js";
+import { DEFAULT_PRICING, DEFAULT_PRICING_ASOF } from "./default-pricing.js";
 import { runTranscriptHeuristics, DEFAULT_COST_THRESHOLDS, } from "./detector.js";
 import { getStagedFiles, runSecretScan, runDocCoverage, runCommitMessageRequired, runRuleParity, formatSecretViolations, formatDocCoverageViolations, formatSecretViolationsJson, formatDocCoverageViolationsJson, formatCommitMessageViolations, formatCommitMessageViolationsJson, formatRuleParityViolations, formatRuleParityViolationsJson, } from "./hooks.js";
 import { safeAppend } from "./audit.js";
@@ -1856,6 +1858,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 ?? [];
@@ -2289,20 +2350,27 @@ function loadCostThresholds(cwd) {
     const res = loadRepoPolicy(cwd);
     if (res && res.ok && res.policy.agent_cost) {
         const a = res.policy.agent_cost;
+        // [DEFAULT-RATES-SHIP-WITH-THE-PACKAGE] — an agent_cost block that omits
+        // `pricing` must not silently price nothing.
+        const hasOwnRates = a.pricing.length > 0;
         return {
             t: {
                 billing_mode: a.billing_mode,
-                pricing: a.pricing,
+                pricing: hasOwnRates ? a.pricing : DEFAULT_PRICING,
                 min_cache_efficiency: a.min_cache_efficiency,
                 max_tool_calls_per_agent: a.max_tool_calls_per_agent,
                 max_cost_per_agent_usd: a.max_cost_per_agent_usd,
                 min_fanout_for_canary: a.min_fanout_for_canary,
                 max_failed_share: a.max_failed_share,
             },
-            source: ".contextengine/policy.json",
+            source: ".contextengine/policy.json" +
+                (hasOwnRates ? "" : ` (rates: built-in, as of ${DEFAULT_PRICING_ASOF})`),
         };
     }
-    return { t: DEFAULT_COST_THRESHOLDS, source: "built-in defaults (no agent_cost in policy.json)" };
+    return {
+        t: DEFAULT_COST_THRESHOLDS,
+        source: `built-in defaults, rates as of ${DEFAULT_PRICING_ASOF} (no agent_cost in policy.json)`,
+    };
 }
 async function cliCost(argv) {
     const flag = (name) => {
@@ -2355,7 +2423,17 @@ async function cliCost(argv) {
     let vol = emptyTally();
     let agents = 0, toolCalls = 0, failed = 0, capacity = 0, reported = 0;
     let cost = 0, withoutCache = 0, unpriced = 0;
+    // Which models carried tokens but matched no rate — named in the output so
+    // the fix is actionable instead of "something was unpriced".
+    const unpricedModels = new Set();
     for (const { run, m } of scored) {
+        for (const a of run.agents) {
+            for (const [model, tally] of a.tokensByModel) {
+                if (totalTokens(tally) > 0 && !pricingFor(model, t.pricing)) {
+                    unpricedModels.add(model ?? "(no model recorded)");
+                }
+            }
+        }
         vol = addTally(vol, run.totals);
         agents += m.agents;
         toolCalls += m.toolCalls;
@@ -2383,12 +2461,6 @@ async function cliCost(argv) {
     console.log("");
     // ── 2. VALUED COST ──────────────────────────────────────────────────────
     const notional = t.billing_mode === "subscription";
-    console.log(`VALUED COST (API list prices)${notional ? " — NOTIONAL, NOT BILLED" : ""}`);
-    if (notional) {
-        console.log("  This machine runs Claude Code on a subscription: no dollar below is");
-        console.log("  debited. Use these figures to compare approaches, not as spend.");
-    }
-    const costRow = (label, n) => console.log(`  ${label.padEnd(16)} ${("$" + n.toFixed(2)).padStart(8)}  ${cost ? ((100 * n) / cost).toFixed(1).padStart(5) : "  0.0"}%`);
     let ci = 0, ccw = 0, ccr = 0, co = 0;
     for (const { m } of scored) {
         ci += m.cost.input;
@@ -2396,16 +2468,42 @@ async function cliCost(argv) {
         ccr += m.cost.cacheRead;
         co += m.cost.output;
     }
-    costRow("cache read", ccr);
-    costRow("cache write", ccw);
-    costRow("input (fresh)", ci);
-    costRow("output", co);
-    console.log(`  ${"total".padEnd(16)} ${("$" + cost.toFixed(2)).padStart(8)}`);
-    console.log(`  ${"without cache".padEnd(16)} ${("$" + withoutCache.toFixed(2)).padStart(8)}  ` +
-        `caching saved $${(withoutCache - cost).toFixed(2)} (${withoutCache ? (100 * (1 - cost / withoutCache)).toFixed(0) : "0"}%)`);
-    if (unpriced > 0)
-        console.log(`  ⚠ ${fmtTok(unpriced)} tokens UNPRICED (no matching model in policy) — not counted above`);
-    console.log("");
+    const agg = {
+        input: ci, cacheWrite: ccw, cacheRead: ccr, output: co,
+        total: cost, withoutCache, unpricedTokens: unpriced,
+    };
+    const status = pricingStatus(agg);
+    console.log(`VALUED COST (API list prices)${notional && status !== "unpriced" ? " — NOTIONAL, NOT BILLED" : ""}`);
+    // [NEVER-RENDER-AN-UNKNOWN-AS-A-NUMBER] — with nothing priced there is no
+    // cost to show. Printing a $0.00 table here reads as "this run was free"
+    // and "caching saved 0%", both false.
+    if (status === "unpriced") {
+        console.log(`  UNPRICED — no rate matched any model in this data, so no cost can be`);
+        console.log(`  stated. ${fmtTok(unpriced)} tokens were moved. This is an unknown, not $0.`);
+        console.log("");
+        console.log(`  Models seen without a rate: ${[...unpricedModels].sort().join(", ") || "(unknown)"}`);
+        console.log(`  Add them to .contextengine/policy.json → agent_cost.pricing.`);
+        console.log("");
+    }
+    else {
+        if (notional) {
+            console.log("  This machine runs Claude Code on a subscription: no dollar below is");
+            console.log("  debited. Use these figures to compare approaches, not as spend.");
+        }
+        const costRow = (label, n) => console.log(`  ${label.padEnd(16)} ${("$" + n.toFixed(2)).padStart(8)}  ${cost ? ((100 * n) / cost).toFixed(1).padStart(5) : "  0.0"}%`);
+        costRow("cache read", ccr);
+        costRow("cache write", ccw);
+        costRow("input (fresh)", ci);
+        costRow("output", co);
+        console.log(`  ${"total".padEnd(16)} ${("$" + cost.toFixed(2)).padStart(8)}`);
+        console.log(`  ${"without cache".padEnd(16)} ${("$" + withoutCache.toFixed(2)).padStart(8)}  ` +
+            `caching saved $${(withoutCache - cost).toFixed(2)} (${withoutCache ? (100 * (1 - cost / withoutCache)).toFixed(0) : "0"}%)`);
+        if (status === "partial") {
+            console.log(`  ⚠ ${fmtTok(unpriced)} tokens UNPRICED and NOT in the figures above` +
+                ` (${[...unpricedModels].sort().join(", ") || "unknown model"}) — the total is a floor, not the cost`);
+        }
+        console.log("");
+    }
     // ── 3. INTENSITY (the capacity proxy) ───────────────────────────────────
     console.log(`INTENSITY (capacity proxy${notional ? " — the scarce resource here" : ""})`);
     console.log(`  subagents        ${String(agents).padStart(8)}`);
@@ -2440,6 +2538,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
 // ---------------------------------------------------------------------------
@@ -2477,6 +2586,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
@@ -2676,6 +2791,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);
@@ -2787,8 +2905,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/default-pricing.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Built-in model rates, in dollars per million tokens.
+ *
+ * 🔒 LOCKED [DEFAULT-RATES-SHIP-WITH-THE-PACKAGE] — 2026-08-20
+ * ⛔ NEVER ship an empty default pricing table again.
+ * WHY: `[PRICING-LIVES-IN-POLICY]` was read as "ship no rates at all", so
+ *    2.5.0 shipped `pricing: []` as the default. Every user without an
+ *    `agent_cost` block in their own policy.json got a VALUED COST panel
+ *    reading `total $0.00` and `caching saved $0.00 (0%)` over 1.08 BILLION
+ *    real tokens — a confident, wrong-looking verdict on the headline feature
+ *    of the release. The LOCK's intent was "rates must be correctable without
+ *    a release", not "the product ships priced at nothing".
+ * FIX: ship rates here, as DATA in their own module, never inline in the
+ *    collector / detector / CLI. `.contextengine/policy.json` →
+ *    `agent_cost.pricing` still wins outright when present, and this file
+ *    compiles to plain readable JS in `dist/`, so a rate can be corrected in
+ *    place without waiting for a release.
+ *
+ * Rates are Anthropic API list prices. Cache read is 0.1x input, cache write
+ * 5m is 1.25x input, cache write 1h is 2x input.
+ */
+import type { ModelPricing } from "./transcript-collector.js";
+/**
+ * When these rates were last checked against published pricing. Surfaced in
+ * `contextengine cost` output: a rate table with no date is a rate table
+ * nobody knows to distrust.
+ */
+export declare const DEFAULT_PRICING_ASOF = "2026-08-20";
+/**
+ * Longest-prefix matched, so dated ids (`claude-haiku-4-5-20251001`) resolve
+ * to their family. Deliberately NO `*` catch-all: a model absent from this
+ * table must report as UNPRICED, never be valued at a guessed rate
+ * (`[ABSENCE-IS-NOT-A-VERDICT]`).
+ */
+export declare const DEFAULT_PRICING: ModelPricing[];
+//# sourceMappingURL=default-pricing.d.ts.map

package/dist/default-pricing.js

@@ -0,0 +1,57 @@
+/**
+ * Built-in model rates, in dollars per million tokens.
+ *
+ * 🔒 LOCKED [DEFAULT-RATES-SHIP-WITH-THE-PACKAGE] — 2026-08-20
+ * ⛔ NEVER ship an empty default pricing table again.
+ * WHY: `[PRICING-LIVES-IN-POLICY]` was read as "ship no rates at all", so
+ *    2.5.0 shipped `pricing: []` as the default. Every user without an
+ *    `agent_cost` block in their own policy.json got a VALUED COST panel
+ *    reading `total $0.00` and `caching saved $0.00 (0%)` over 1.08 BILLION
+ *    real tokens — a confident, wrong-looking verdict on the headline feature
+ *    of the release. The LOCK's intent was "rates must be correctable without
+ *    a release", not "the product ships priced at nothing".
+ * FIX: ship rates here, as DATA in their own module, never inline in the
+ *    collector / detector / CLI. `.contextengine/policy.json` →
+ *    `agent_cost.pricing` still wins outright when present, and this file
+ *    compiles to plain readable JS in `dist/`, so a rate can be corrected in
+ *    place without waiting for a release.
+ *
+ * Rates are Anthropic API list prices. Cache read is 0.1x input, cache write
+ * 5m is 1.25x input, cache write 1h is 2x input.
+ */
+/**
+ * When these rates were last checked against published pricing. Surfaced in
+ * `contextengine cost` output: a rate table with no date is a rate table
+ * nobody knows to distrust.
+ */
+export const DEFAULT_PRICING_ASOF = "2026-08-20";
+function rate(model, input, output) {
+    return {
+        model,
+        input_per_mtok: input,
+        output_per_mtok: output,
+        cache_read_per_mtok: Number((input * 0.1).toFixed(4)),
+        cache_write_5m_per_mtok: Number((input * 1.25).toFixed(4)),
+        cache_write_1h_per_mtok: Number((input * 2).toFixed(4)),
+    };
+}
+/**
+ * Longest-prefix matched, so dated ids (`claude-haiku-4-5-20251001`) resolve
+ * to their family. Deliberately NO `*` catch-all: a model absent from this
+ * table must report as UNPRICED, never be valued at a guessed rate
+ * (`[ABSENCE-IS-NOT-A-VERDICT]`).
+ */
+export const DEFAULT_PRICING = [
+    rate("claude-opus-5", 5, 25),
+    rate("claude-opus-4-8", 5, 25),
+    rate("claude-opus-4-7", 5, 25),
+    rate("claude-opus-4-6", 5, 25),
+    rate("claude-opus-4-5", 5, 25),
+    rate("claude-fable-5", 10, 50),
+    rate("claude-mythos-5", 10, 50),
+    rate("claude-sonnet-5", 3, 15),
+    rate("claude-sonnet-4-6", 3, 15),
+    rate("claude-sonnet-4-5", 3, 15),
+    rate("claude-haiku-4-5", 1, 5),
+];
+//# sourceMappingURL=default-pricing.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 [];
@@ -334,9 +337,11 @@ export const _internal = {
     detectDrift, detectNoInsight, detectSilentFailure, detectStaleDocSignal,
 };
 import { metricsFor } from "./transcript-collector.js";
+import { DEFAULT_PRICING } from "./default-pricing.js";
 export const DEFAULT_COST_THRESHOLDS = {
     billing_mode: "subscription",
-    pricing: [],
+    // [DEFAULT-RATES-SHIP-WITH-THE-PACKAGE] — never [] again.
+    pricing: DEFAULT_PRICING,
     min_cache_efficiency: 3,
     max_tool_calls_per_agent: 2,
     max_cost_per_agent_usd: 3,

package/dist/transcript-collector.d.ts

@@ -130,6 +130,24 @@ export declare function pricingFor(model: string | null, table: ModelPricing[]):
  *    AND intensity — never one alone.
  */
 export declare function costOf(t: TokenTally, p: ModelPricing | null): CostBreakdown;
+/**
+ * Whether a cost figure can be presented as money at all.
+ *
+ * 🔒 LOCKED [NEVER-RENDER-AN-UNKNOWN-AS-A-NUMBER] — 2026-08-20
+ * ⛔ NEVER print a $0.00 cost row, total, or "caching saved" figure while
+ *    `unpricedTokens > 0`.
+ * WHY: 2.5.0 rendered a full VALUED COST table of $0.00 over 1.08 billion
+ *    unpriced tokens, including "caching saved $0.00 (0%)" — which reads as
+ *    "your caching achieves nothing" when the true reuse was 8x. The token
+ *    accounting was right; the PRESENTATION layer turned "I have no rates"
+ *    into a number. That is Session 21's rule at the display layer: any
+ *    plausible-looking value returned from a branch meaning "I could not
+ *    determine this" is the bug, however reasonable it looks.
+ * FIX: branch on this before formatting. `unpriced` must render the word
+ *    UNPRICED, never a currency amount.
+ */
+export type PricingStatus = "priced" | "partial" | "unpriced";
+export declare function pricingStatus(c: CostBreakdown): PricingStatus;
 export declare function emptyTally(): TokenTally;
 export declare function addTally(a: TokenTally, b: TokenTally): TokenTally;
 export declare function totalTokens(t: TokenTally): number;

package/dist/transcript-collector.js

@@ -84,6 +84,11 @@ export function costOf(t, p) {
         t.output * p.output_per_mtok) / M;
     return { input, cacheWrite, cacheRead, output, total: input + cacheWrite + cacheRead + output, withoutCache, unpricedTokens: 0 };
 }
+export function pricingStatus(c) {
+    if (c.unpricedTokens === 0)
+        return "priced";
+    return c.total === 0 ? "unpriced" : "partial";
+}
 export function emptyTally() {
     return { input: 0, cacheWrite5m: 0, cacheWrite1h: 0, cacheRead: 0, output: 0 };
 }

package/package.json

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