@compr/opscontext-mcp 2.5.3 → 2.5.4

package/README.md

@@ -539,7 +539,7 @@ Everything happens locally — search, scoring, learnings, sessions, embeddings.
 | Email | Activation only | Tie the licence to an account |
 | Package version | Activation only | Serve a compatible module bundle |
 | Platform/arch (e.g., `darwin/arm64`) | Activation only | Compatibility check |
-| Delta bundle version | Daily heartbeat | Detect an out-of-date module cache |
+| Licence bundle version | Daily heartbeat | Compatibility marker carried in the signed licence |
 
 That is the complete list. The activation request sends exactly six fields and the heartbeat exactly three — enforced by a lock comment in `src/activation.ts` that forbids adding a seventh field reflecting usage.
 

package/dist/activation.d.ts

@@ -1,4 +1,3 @@
-export declare const PREMIUM_MODULES: readonly ["agents", "search-adv"];
 export declare const PREMIUM_TOOLS: readonly ["score_project", "run_audit", "check_ports", "list_projects"];
 export interface LicenseInfo {
     key: string;
@@ -17,33 +16,6 @@ export declare function activate(licenseKey: string, email: string): Promise<{
     message: string;
     plan?: string;
 }>;
-/**
- * Check if delta modules are installed and valid.
- */
-export declare function isDeltaInstalled(): boolean;
-/**
- * Version of the delta bundle currently cached on disk, or null if none/unreadable.
- * Exported so callers can report the mismatch rather than guess at it.
- */
-export declare function installedDeltaVersion(): string | null;
-/**
- * Dynamically import a delta module.
- * Returns null if not activated, module missing, or the cached delta is stale.
- *
- * 🔒 LOCKED [DELTA-VERSION-PIN] — 2026-08-14
- * ⛔ NEVER import a delta module without checking its manifest version against this package.
- * WHY: the cache at ~/.contextengine/delta/ is written once at activation and never expires. On
- *      the author's own machine it held version 1.19.1 while the installed package was 2.3.1 —
- *      two months and three sessions of scorer fixes out of date. Because this function imported
- *      whatever .mjs happened to be on disk, wiring it up would have silently run the OLD scorer
- *      inside the NEW package: no error, no symptom, just quietly wrong scores. The canary cannot
- *      catch this — a stale delta carries its own stale canary and its own stale pins, so it
- *      passes against itself.
- * FIX: refuse to load a delta whose version does not match the running package, and say so on
- *      stderr. A stale module is an unknown, not a usable one — [ABSENCE-IS-NOT-A-VERDICT]
- *      applied to code delivery rather than to a check result.
- */
-export declare function loadDeltaModule(name: string): Promise<any | null>;
 export declare function heartbeat(): Promise<boolean>;
 export declare function deactivate(): void;
 export declare function getActivationStatus(): {

package/dist/activation.js

@@ -1,7 +1,18 @@
-// LOCKED — verified March 3 2026 — activation + delta decryption + machine fingerprint + heartbeat
+// LOCKED — verified March 3 2026 — activation + machine fingerprint + heartbeat
 // DO NOT RE-AUDIT — E2E tested Feb 23 2026, all 4 Pro tools verified
+//
+// [LOCKED] [DELTA-RETIRED] — 2026-08-21
+// [NEVER] reintroduce a client-side "delta bundle" (download, decrypt, cache, import premium code).
+// WHY: from 0f12967 (2026-02-20) to 2.5.3 the client fetched an AES-encrypted bundle on activation,
+//      wrote it to ~/.contextengine/delta/, and never imported it: loadDeltaModule() had no caller,
+//      index.ts and cli.ts import agents.js / search.js / firewall.js from the package. Yet gateCheck
+//      refused premium tools when the unused cache was missing, and a stale cache needed its own
+//      guard (the former [DELTA-VERSION-PIN], 2026-08-14). Dead weight with live failure modes.
+// FIX: the gate is the signed licence alone (Ed25519, machine-bound, expiry, daily heartbeat).
+//      The moat is the gate plus BSL-1.1, as CLAUDE.md rule 3 states. Retired on Yan's decision,
+//      SESSION_23. deactivate() still empties a legacy ~/.contextengine/delta/ so old caches go away.
 /**
- * Activation & Delta Module System
+ * Activation System
  *
  * The npm package ships with core functionality (search, sessions, learnings,
  * operational collectors). PRO unlocks the four high-value tools that consume
@@ -24,48 +35,29 @@
  *
  * On activation:
  *   1. License key is validated against the ContextEngine API
- *   2. Server returns a signed delta bundle (encrypted JS modules)
- *   3. Delta is cached locally at ~/.contextengine/delta/
- *   4. Premium tools become available
+ *   2. Server returns a signed licence (Ed25519), saved to ~/.contextengine/license.json
+ *   3. Premium tools become available
+ * The server may still include a `delta` field in its response; it is ignored. [LOCK] [DELTA-RETIRED]
  */
 import { existsSync, readFileSync, writeFileSync, mkdirSync, readdirSync, unlinkSync } from "fs";
-import { join, dirname } from "path";
+import { join } from "path";
 import { homedir } from "os";
-import { fileURLToPath } from "url";
-import { createHash, createDecipheriv } from "crypto";
+import { createHash } from "crypto";
 import { safeAppend } from "./audit.js";
 import { verifyLicenseSignature } from "./license-sig.js";
 // ---------------------------------------------------------------------------
 // Constants
 // ---------------------------------------------------------------------------
-const DELTA_DIR = join(homedir(), ".contextengine", "delta");
-/**
- * Version of the running package. Read from package.json at module load, the same way
- * agents.ts does it, so [DELTA-VERSION-PIN] compares against the real installed version
- * rather than a constant someone forgets to bump.
- */
-const PACKAGE_VERSION = (() => {
-    try {
-        const here = dirname(fileURLToPath(import.meta.url));
-        return JSON.parse(readFileSync(join(here, "..", "package.json"), "utf-8")).version ?? "unknown";
-    }
-    catch {
-        return "unknown";
-    }
-})();
+// Legacy cache location, only ever cleaned now. [LOCK] [DELTA-RETIRED]
+const LEGACY_DELTA_DIR = join(homedir(), ".contextengine", "delta");
 const LICENSE_FILE = join(homedir(), ".contextengine", "license.json");
 const ACTIVATION_API_BASE = process.env.CONTEXTENGINE_API || "https://api.compr.ch/contextengine";
 const ACTIVATION_API = `${ACTIVATION_API_BASE}/activate`;
 const HEARTBEAT_INTERVAL_MS = 24 * 60 * 60 * 1000; // daily check
-// Premium modules that require activation.
 // NOTE: collectors.ts runs unconditionally during reindex for all users
-// (operational data feeds search_context for everyone). The PRO tools below
-// in PREMIUM_TOOLS are what consume that data for scoring/audit/cross-project
+// (operational data feeds search_context for everyone). The PRO tools in
+// PREMIUM_TOOLS are what consume that data for scoring/audit/cross-project
 // reports. Keep the gate at the tool layer, not the data-collection layer.
-export const PREMIUM_MODULES = [
-    "agents", // scorer, auditor, port checker, HTML report formatters
-    "search-adv", // advanced BM25 with tuned parameters
-];
 // Tools that require activation. Re-exported from the central manifest so
 // the count and the name list have a SINGLE source of truth. Adding a new
 // PRO tool requires editing src/tools-manifest.ts (which also feeds the
@@ -194,8 +186,6 @@ export async function activate(licenseKey, email) {
         }
         // Save license
         saveLicense(data.license);
-        // Decrypt and store delta modules
-        await installDelta(data.delta, data.license.key);
         safeAppend("activation.activate", {
             plan: data.license.plan,
             email: data.license.email,
@@ -214,112 +204,6 @@ export async function activate(licenseKey, email) {
     }
 }
 // ---------------------------------------------------------------------------
-// Delta module management
-// ---------------------------------------------------------------------------
-async function installDelta(delta, licenseKey) {
-    if (!existsSync(DELTA_DIR))
-        mkdirSync(DELTA_DIR, { recursive: true });
-    // Derive decryption key from license key
-    const derivedKey = createHash("sha256")
-        .update(licenseKey + getMachineId())
-        .digest();
-    const iv = Buffer.from(delta.iv, "hex");
-    for (const mod of delta.modules) {
-        const encrypted = Buffer.from(mod.payload, "base64");
-        // AES-256-CBC decrypt
-        const decipher = createDecipheriv("aes-256-cbc", derivedKey, iv);
-        let decrypted = decipher.update(encrypted);
-        decrypted = Buffer.concat([decrypted, decipher.final()]);
-        const content = decrypted.toString("utf-8");
-        // Verify checksum
-        const checksum = createHash("sha256").update(content).digest("hex");
-        if (checksum !== mod.checksum) {
-            throw new Error(`Delta module ${mod.name} checksum mismatch — possible tampering`);
-        }
-        // Write to delta directory
-        writeFileSync(join(DELTA_DIR, `${mod.name}.mjs`), content);
-    }
-    // Write version marker
-    writeFileSync(join(DELTA_DIR, "manifest.json"), JSON.stringify({
-        version: delta.version,
-        installedAt: new Date().toISOString(),
-        modules: delta.modules.map((m) => m.name),
-    }));
-    console.error(`[ContextEngine] 📦 Delta v${delta.version} installed (${delta.modules.length} modules)`);
-}
-/**
- * Check if delta modules are installed and valid.
- */
-export function isDeltaInstalled() {
-    const manifestPath = join(DELTA_DIR, "manifest.json");
-    if (!existsSync(manifestPath))
-        return false;
-    try {
-        const manifest = JSON.parse(readFileSync(manifestPath, "utf-8"));
-        // Verify all expected module files exist
-        for (const modName of manifest.modules) {
-            if (!existsSync(join(DELTA_DIR, `${modName}.mjs`)))
-                return false;
-        }
-        return true;
-    }
-    catch {
-        return false;
-    }
-}
-/**
- * Version of the delta bundle currently cached on disk, or null if none/unreadable.
- * Exported so callers can report the mismatch rather than guess at it.
- */
-export function installedDeltaVersion() {
-    try {
-        const manifest = JSON.parse(readFileSync(join(DELTA_DIR, "manifest.json"), "utf-8"));
-        return typeof manifest.version === "string" ? manifest.version : null;
-    }
-    catch {
-        return null;
-    }
-}
-/**
- * Dynamically import a delta module.
- * Returns null if not activated, module missing, or the cached delta is stale.
- *
- * 🔒 LOCKED [DELTA-VERSION-PIN] — 2026-08-14
- * ⛔ NEVER import a delta module without checking its manifest version against this package.
- * WHY: the cache at ~/.contextengine/delta/ is written once at activation and never expires. On
- *      the author's own machine it held version 1.19.1 while the installed package was 2.3.1 —
- *      two months and three sessions of scorer fixes out of date. Because this function imported
- *      whatever .mjs happened to be on disk, wiring it up would have silently run the OLD scorer
- *      inside the NEW package: no error, no symptom, just quietly wrong scores. The canary cannot
- *      catch this — a stale delta carries its own stale canary and its own stale pins, so it
- *      passes against itself.
- * FIX: refuse to load a delta whose version does not match the running package, and say so on
- *      stderr. A stale module is an unknown, not a usable one — [ABSENCE-IS-NOT-A-VERDICT]
- *      applied to code delivery rather than to a check result.
- */
-export async function loadDeltaModule(name) {
-    if (!isDeltaInstalled())
-        return null;
-    const cached = installedDeltaVersion();
-    if (cached !== PACKAGE_VERSION) {
-        console.error(`[ContextEngine] ⚠ Delta module "${name}" is version ${cached ?? "unknown"} but this package is ` +
-            `${PACKAGE_VERSION} — refusing to load a stale module. Re-run \`contextengine activate\` to refresh.`);
-        return null;
-    }
-    const modulePath = join(DELTA_DIR, `${name}.mjs`);
-    if (!existsSync(modulePath))
-        return null;
-    try {
-        // Dynamic import of the decrypted module
-        const moduleUrl = `file://${modulePath}`;
-        return await import(moduleUrl);
-    }
-    catch (err) {
-        console.error(`[ContextEngine] ⚠ Failed to load delta module ${name}:`, err.message);
-        return null;
-    }
-}
-// ---------------------------------------------------------------------------
 // Heartbeat — periodic license validation
 // ---------------------------------------------------------------------------
 export async function heartbeat() {
@@ -368,10 +252,10 @@ export function deactivate() {
     // Remove license
     if (existsSync(LICENSE_FILE))
         unlinkSync(LICENSE_FILE);
-    // Remove delta modules
-    if (existsSync(DELTA_DIR)) {
-        for (const file of readdirSync(DELTA_DIR)) {
-            unlinkSync(join(DELTA_DIR, file));
+    // Remove a legacy delta cache if one is still around. [LOCK] [DELTA-RETIRED]
+    if (existsSync(LEGACY_DELTA_DIR)) {
+        for (const file of readdirSync(LEGACY_DELTA_DIR)) {
+            unlinkSync(join(LEGACY_DELTA_DIR, file));
         }
     }
     safeAppend("activation.deactivate", {
@@ -386,8 +270,7 @@ export function deactivate() {
 // ---------------------------------------------------------------------------
 export function getActivationStatus() {
     const license = loadLicense();
-    const deltaInstalled = isDeltaInstalled();
-    if (!license || !deltaInstalled) {
+    if (!license) {
         return {
             activated: false,
             plan: "community",
@@ -428,10 +311,6 @@ export function gateCheck(toolName) {
             `save_session, load_session, list_sessions, end_session, save_learning, ` +
             `list_learnings, import_learnings`;
     }
-    if (!isDeltaInstalled()) {
-        return `🔒 Premium modules not installed. Re-activate:\n` +
-            `npx contextengine activate ${license.key} ${license.email}`;
-    }
     return null;
 }
 // ---------------------------------------------------------------------------

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" | "audit.rotate";
+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" | "audit.redact";
 export interface AuditRecord {
     ts: string;
     event: AuditEvent;
@@ -66,6 +66,35 @@ export declare function planRotation(opts?: RotateOptions): RotationPlan;
  * cause unrecoverable. Forks are fine — they are concurrency, not tampering.
  */
 export declare function rotateAuditLog(opts?: RotateOptions): RotationResult;
+/**
+ * Startup auto-rotation for the MCP server.
+ *
+ * [LOCKED] [AUTO-ROTATE-HYSTERESIS-AND-ONE-RUNNER] — 2026-08-21
+ * [NEVER] trigger at the same count the rotation keeps, and never let two servers rotate at once.
+ * WHY: rotation was manual and the live log crossed the 50k ceiling in ~15h, so the drift
+ *      detectors' per-tick read slowed by the day between hand runs. A startup hook fixes the
+ *      cadence, but (a) triggering at 50k and rotating down to 50k would cut a handful of
+ *      records into a new segment on every start, and (b) three MCP servers start together
+ *      on this machine (VS Code, launchd, Claude Code); each would plan on the same oversized
+ *      file and the late ones would archive records the first one had already kept.
+ * FIX: trigger at AUTO_ROTATE_TRIGGER (2x the ceiling), rotate down to the ceiling, so a
+ *      rotation buys ~a day of quiet. A dedicated rotate lock (O_EXCL, stale after 10 min,
+ *      long enough to verify a 500k-record chain) makes late starters return "in progress"
+ *      without touching the log. Opt out with CONTEXTENGINE_AUTO_ROTATE=0.
+ */
+export declare const AUTO_ROTATE_TRIGGER: number;
+/** Count newline-terminated lines without parsing. The live log is small by construction. */
+export declare function countLiveRecords(): number;
+export interface AutoRotateOutcome {
+    action: "disabled" | "below_trigger" | "in_progress" | "rotated" | "refused" | "error";
+    liveRecords: number;
+    detail: string;
+    result?: RotationResult;
+}
+export declare function autoRotateAuditLog(opts?: {
+    trigger?: number;
+    maxRecords?: number;
+}): AutoRotateOutcome;
 export interface IntegrityReport {
     ok: boolean;
     total: number;
@@ -79,6 +108,10 @@ export interface IntegrityReport {
     /** Records whose prev_hash names a KNOWN earlier head — a concurrent-append fork.
      *  Content is provably intact; only the linkage is non-linear. Not tampering. */
     forkIndices?: number[];
+    /** Records whose content was altered AND whose alteration is acknowledged by a later, intact
+     *  `audit.redact` record binding the original hash to the current content. Not counted as
+     *  tampering. */
+    redactedIndices?: number[];
 }
 /**
  * 🔒 LOCKED [VERIFY-FORK-IS-NOT-TAMPER] — 2026-08-17
@@ -104,6 +137,31 @@ export interface IntegrityReport {
  *      never claim a forked log is pristine either.
  */
 export declare function verifyChain(): IntegrityReport;
+/**
+ * Acknowledge that records were deliberately redacted (a secret removed from their content).
+ *
+ * [LOCKED] [REDACTION-IS-A-CHAINED-RECORD] — 2026-08-21
+ * [NEVER] let the verifier accept an allow-list that lives outside the chain (a file, an env
+ *         var, a CLI flag) as grounds to stop calling an altered record altered.
+ * WHY: on 2026-08-20 a credentials sweep replaced a password with [REDACTED_SECRET] in 3
+ *      archived records. Correct, but the chain can only see "content no longer matches its
+ *      hash", so the compliance report read "tampering" for a deliberate act nobody recorded.
+ *      An out-of-band allow-list would fix the wording and destroy the property: anyone who
+ *      can edit the log can edit the list.
+ * FIX: the acknowledgement is an `audit.redact` record, appended to the chain like any other,
+ *      naming the original hash of each redacted record and the hash of its redacted content.
+ *      It can only be written after the fact, only for records that are actually altered, and
+ *      a further edit breaks the binding. The verifier reports such records as "redacted",
+ *      counts them separately, and `ok` ignores them; everything else stays "altered".
+ */
+export declare function acknowledgeRedaction(indices: number[], reason: string, actor?: string): {
+    acknowledged: number[];
+    rejected: Array<{
+        index: number;
+        why: string;
+    }>;
+    record: AuditRecord | null;
+};
 export declare function filterByRange(records: AuditRecord[], since?: string, until?: string): AuditRecord[];
 export declare function toCsv(records: AuditRecord[]): string;
 export declare function resetCacheForTest(): void;

package/dist/audit.js

@@ -407,10 +407,28 @@ export function rotateAuditLog(opts = {}) {
     }
     const integrity = verifyChain();
     if (!integrity.ok) {
-        return {
-            ...empty,
-            refusedReason: `chain does not verify (${integrity.breakReason}) — refusing to archive a damaged log`,
-        };
+        // [LOCKED] [ROTATE-REFUSES-LIVE-DAMAGE-ONLY] — 2026-08-21
+        // [NEVER] refuse a rotation for damage that sits entirely inside segments already archived.
+        // WHY: on 2026-08-20 a credentials sweep replaced a password literal with [REDACTED_SECRET]
+        //      in 3 records of audit-0001.jsonl. Correct, deliberate, and permanent: the verifier
+        //      reports them as altered for good. A whole-chain refusal then blocks every future
+        //      rotation, the live log grows without bound (170k records a day later, 3x the
+        //      ceiling) and the detectors slow down again, which is the failure rotation exists to
+        //      prevent. Archived segments are already immutable by policy; refusing to archive new
+        //      records protects nothing there.
+        // FIX: refuse only when an altered or orphaned record is in the live log, the part about to
+        //      be rewritten. Damage confined to segments is reported, not treated as a veto.
+        const firstLive = integrity.total - plan.archiveCount - plan.keepCount;
+        const bad = [...(integrity.tamperedIndices ?? []), ...(integrity.orphanIndices ?? [])];
+        const inLive = bad.filter((i) => i >= firstLive);
+        if (inLive.length > 0) {
+            return {
+                ...empty,
+                refusedReason: `chain does not verify (${integrity.breakReason}) — ${inLive.length} damaged record(s) in the live log, refusing to archive a damaged log`,
+            };
+        }
+        console.error(`[ContextEngine] ⚠ audit rotation: ${bad.length} known damaged record(s) in archived segments ` +
+            `(first at ${bad[0]}); none in the live log, rotating.`);
     }
     if (opts.dryRun)
         return { ...plan, rotated: false, bytesArchived: 0, bytesRemaining: 0 };
@@ -472,6 +490,99 @@ export function rotateAuditLog(opts = {}) {
         bytesRemaining: statSync(path).size,
     };
 }
+/**
+ * Startup auto-rotation for the MCP server.
+ *
+ * [LOCKED] [AUTO-ROTATE-HYSTERESIS-AND-ONE-RUNNER] — 2026-08-21
+ * [NEVER] trigger at the same count the rotation keeps, and never let two servers rotate at once.
+ * WHY: rotation was manual and the live log crossed the 50k ceiling in ~15h, so the drift
+ *      detectors' per-tick read slowed by the day between hand runs. A startup hook fixes the
+ *      cadence, but (a) triggering at 50k and rotating down to 50k would cut a handful of
+ *      records into a new segment on every start, and (b) three MCP servers start together
+ *      on this machine (VS Code, launchd, Claude Code); each would plan on the same oversized
+ *      file and the late ones would archive records the first one had already kept.
+ * FIX: trigger at AUTO_ROTATE_TRIGGER (2x the ceiling), rotate down to the ceiling, so a
+ *      rotation buys ~a day of quiet. A dedicated rotate lock (O_EXCL, stale after 10 min,
+ *      long enough to verify a 500k-record chain) makes late starters return "in progress"
+ *      without touching the log. Opt out with CONTEXTENGINE_AUTO_ROTATE=0.
+ */
+export const AUTO_ROTATE_TRIGGER = 2 * DEFAULT_MAX_LIVE_RECORDS;
+const ROTATE_LOCK_STALE_MS = 10 * 60_000;
+function rotateLockPath() {
+    return join(auditDir(), "audit.rotate.lock");
+}
+/** Count newline-terminated lines without parsing. The live log is small by construction. */
+export function countLiveRecords() {
+    const path = auditPath();
+    if (!existsSync(path))
+        return 0;
+    const buf = readFileSync(path);
+    let n = 0;
+    for (let i = 0; i < buf.length; i++)
+        if (buf[i] === 10)
+            n++;
+    return n;
+}
+export function autoRotateAuditLog(opts = {}) {
+    const trigger = opts.trigger ?? AUTO_ROTATE_TRIGGER;
+    const maxRecords = opts.maxRecords ?? DEFAULT_MAX_LIVE_RECORDS;
+    if (process.env.CONTEXTENGINE_AUTO_ROTATE === "0") {
+        return { action: "disabled", liveRecords: -1, detail: "CONTEXTENGINE_AUTO_ROTATE=0" };
+    }
+    const liveRecords = countLiveRecords();
+    if (liveRecords <= trigger) {
+        return { action: "below_trigger", liveRecords, detail: `${liveRecords} live record(s), trigger is ${trigger}` };
+    }
+    // One runner at a time. O_EXCL create is the primitive; a stale file is an orphan from a
+    // crashed rotation, not a live one.
+    const lock = rotateLockPath();
+    let fd;
+    try {
+        ensureDir();
+        try {
+            fd = openSync(lock, constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY, 0o600);
+        }
+        catch (e) {
+            if (e.code !== "EEXIST")
+                throw e;
+            const age = Date.now() - statSync(lock).mtimeMs;
+            if (age < ROTATE_LOCK_STALE_MS) {
+                return { action: "in_progress", liveRecords, detail: `another rotation holds ${lock} (${Math.round(age / 1000)}s old)` };
+            }
+            unlinkSync(lock);
+            fd = openSync(lock, constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY, 0o600);
+        }
+    }
+    catch (e) {
+        return { action: "error", liveRecords, detail: `rotate lock: ${e.message}` };
+    }
+    try {
+        try {
+            writeSync(fd, `${process.pid}\n${new Date().toISOString()}\n`);
+        }
+        catch { /* contents are a courtesy */ }
+        closeSync(fd);
+        const result = rotateAuditLog({ maxRecords });
+        if (!result.rotated) {
+            return { action: "refused", liveRecords, detail: result.refusedReason ?? "not rotated", result };
+        }
+        return {
+            action: "rotated",
+            liveRecords,
+            detail: `archived ${result.archiveCount} record(s) to ${result.segmentFile}, ${result.keepCount + 1} live`,
+            result,
+        };
+    }
+    catch (e) {
+        return { action: "error", liveRecords, detail: e.message };
+    }
+    finally {
+        try {
+            unlinkSync(lock);
+        }
+        catch { /* already gone */ }
+    }
+}
 function writeFileAndSync(target, body) {
     const fd = openSync(target, "w");
     try {
@@ -543,6 +654,37 @@ export function verifyChain() {
         seen.add(r.hash);
         prev = r.hash;
     }
+    // 3. Acknowledged redactions. [LOCK] [REDACTION-IS-A-CHAINED-RECORD]
+    //    An `audit.redact` record that is itself intact binds (original hash -> hash of the
+    //    redacted content). A tampered record matching such a binding is "redacted", not
+    //    "altered". Binding to the current content means a second edit after the acknowledgement
+    //    makes it tampered again.
+    const tamperedSet = new Set(tampered);
+    const acks = new Map();
+    for (let i = 0; i < records.length; i++) {
+        const r = records[i];
+        if (r.event !== "audit.redact" || tamperedSet.has(i))
+            continue;
+        const list = r.payload.redacted;
+        if (!Array.isArray(list))
+            continue;
+        for (const e of list) {
+            if (typeof e.hash === "string" && typeof e.content_hash === "string")
+                acks.set(e.hash, e.content_hash);
+        }
+    }
+    const redacted = [];
+    const stillTampered = [];
+    for (const i of tampered) {
+        const r = records[i];
+        const bound = acks.get(r.hash);
+        if (bound && bound === computeHash(r.prev_hash, r.ts, r.event, r.actor, r.payload))
+            redacted.push(i);
+        else
+            stillTampered.push(i);
+    }
+    tampered.length = 0;
+    tampered.push(...stillTampered);
     const ok = tampered.length === 0 && orphans.length === 0;
     const firstProblem = tampered.length > 0 ? tampered[0] : orphans.length > 0 ? orphans[0] : null;
     let reason = null;
@@ -560,8 +702,56 @@ export function verifyChain() {
         tamperedIndices: tampered,
         orphanIndices: orphans,
         forkIndices: forks,
+        redactedIndices: redacted,
     };
 }
+/**
+ * Acknowledge that records were deliberately redacted (a secret removed from their content).
+ *
+ * [LOCKED] [REDACTION-IS-A-CHAINED-RECORD] — 2026-08-21
+ * [NEVER] let the verifier accept an allow-list that lives outside the chain (a file, an env
+ *         var, a CLI flag) as grounds to stop calling an altered record altered.
+ * WHY: on 2026-08-20 a credentials sweep replaced a password with [REDACTED_SECRET] in 3
+ *      archived records. Correct, but the chain can only see "content no longer matches its
+ *      hash", so the compliance report read "tampering" for a deliberate act nobody recorded.
+ *      An out-of-band allow-list would fix the wording and destroy the property: anyone who
+ *      can edit the log can edit the list.
+ * FIX: the acknowledgement is an `audit.redact` record, appended to the chain like any other,
+ *      naming the original hash of each redacted record and the hash of its redacted content.
+ *      It can only be written after the fact, only for records that are actually altered, and
+ *      a further edit breaks the binding. The verifier reports such records as "redacted",
+ *      counts them separately, and `ok` ignores them; everything else stays "altered".
+ */
+export function acknowledgeRedaction(indices, reason, actor = "system") {
+    if (!reason.trim())
+        throw new Error("a reason is required");
+    const records = readAuditLog();
+    const acknowledged = [];
+    const rejected = [];
+    const entries = [];
+    for (const i of [...new Set(indices)].sort((a, b) => a - b)) {
+        const r = records[i];
+        if (!r) {
+            rejected.push({ index: i, why: "no such record" });
+            continue;
+        }
+        const current = computeHash(r.prev_hash, r.ts, r.event, r.actor, r.payload);
+        if (current === r.hash) {
+            rejected.push({ index: i, why: "content is intact, nothing to acknowledge" });
+            continue;
+        }
+        if (r.event === "audit.redact") {
+            rejected.push({ index: i, why: "an acknowledgement cannot itself be redacted" });
+            continue;
+        }
+        acknowledged.push(i);
+        entries.push({ index: i, hash: r.hash, content_hash: current, ts: r.ts, event: r.event });
+    }
+    if (entries.length === 0)
+        return { acknowledged, rejected, record: null };
+    const record = appendAudit("audit.redact", { reason, redacted: entries }, actor);
+    return { acknowledged, rejected, record };
+}
 export function filterByRange(records, since, until) {
     return records.filter((r) => {
         if (since && r.ts < since)

package/dist/cli-commands.js

@@ -25,6 +25,7 @@ export const KNOWN_COMMANDS = [
     "audit",
     "audit-export",
     "audit-rotate",
+    "audit-redact-ack",
     "audit-verify",
     "autostart-status",
     "cost",

package/dist/cli.js

@@ -650,11 +650,9 @@ 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, rotateAuditLog, planRotation, listSegments, } from "./audit.js";
+import { readAuditLog, verifyChain, filterByRange, toCsv, rotateAuditLog, planRotation, listSegments, acknowledgeRedaction, } 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";
-import { runTranscriptHeuristics, DEFAULT_COST_THRESHOLDS, } from "./detector.js";
+import { buildCostReport } from "./cost-report.js";
 import { getStagedFiles, runSecretScan, runDocCoverage, runCommitMessageRequired, runRuleParity, formatSecretViolations, formatDocCoverageViolations, formatSecretViolationsJson, formatDocCoverageViolationsJson, formatCommitMessageViolations, formatCommitMessageViolationsJson, formatRuleParityViolations, formatRuleParityViolationsJson, } from "./hooks.js";
 import { safeAppend } from "./audit.js";
 import { installSkill, locateBundledSkill, buildManagedBlock, syncClaudeMd, } from "./claude-integration.js";
@@ -1966,12 +1964,39 @@ function cliAuditRotate(args) {
         process.exit(2);
     }
 }
+/** Acknowledge deliberately redacted audit records on the chain. [LOCK] [REDACTION-IS-A-CHAINED-RECORD] */
+function cliAuditRedactAck(args) {
+    const idxAt = args.indexOf("--index");
+    const reasonAt = args.indexOf("--reason");
+    const raw = idxAt >= 0 ? args[idxAt + 1] ?? "" : "";
+    const reason = reasonAt >= 0 ? args[reasonAt + 1] ?? "" : "";
+    const indices = raw.split(",").map((x) => Number(x.trim())).filter((n) => Number.isInteger(n) && n >= 0);
+    if (indices.length === 0 || !reason.trim()) {
+        console.error(`usage: contextengine audit-redact-ack --index <i,j,k> --reason "<what was removed and why>"`);
+        console.error(`   Indices are the ones 'audit-verify' lists as altered. Only altered records can be acknowledged.`);
+        process.exit(1);
+    }
+    const r = acknowledgeRedaction(indices, reason, "cli");
+    for (const x of r.rejected)
+        console.error(`  ✗ ${x.index}: ${x.why}`);
+    if (!r.record) {
+        console.error(`\nNothing acknowledged.`);
+        process.exit(1);
+    }
+    console.log(`\n✅ Acknowledged ${r.acknowledged.length} redacted record(s): ${r.acknowledged.join(", ")}`);
+    console.log(`   Chained as audit.redact, hash ${r.record.hash.slice(0, 16)}…`);
+    const after = verifyChain();
+    console.log(`   audit-verify now: ${after.ok ? "OK" : "FAILED"}, ${(after.redactedIndices ?? []).length} redacted, ${(after.tamperedIndices ?? []).length} altered.`);
+}
 async function cliAuditVerify() {
     const report = verifyChain();
     const forks = report.forkIndices ?? [];
+    const redacted = report.redactedIndices ?? [];
     if (report.ok) {
         console.log(`✅ Audit chain verified — ${report.total} record(s).`);
-        console.log(`   No record was altered, and no history is missing.`);
+        console.log(redacted.length === 0
+            ? `   No record was altered, and no history is missing.`
+            : `   No history is missing. ${redacted.length} record(s) redacted and acknowledged on the chain (indices ${redacted.slice(0, 8).join(", ")}${redacted.length > 8 ? ", …" : ""}), 0 altered.`);
         if (forks.length > 0) {
             // [VERIFY-FORK-IS-NOT-TAMPER] — surface this, but do not call it tampering.
             console.log(`\n⚠️  ${forks.length} concurrent-append fork(s) detected (not tampering).`);
@@ -1990,6 +2015,11 @@ async function cliAuditVerify() {
         console.error(`\n   Altered records (content does not match its own hash):`);
         console.error(`     ${t.slice(0, 10).join(", ")}${t.length > 10 ? `, … (+${t.length - 10} more)` : ""}`);
         console.error(`   This is tampering: the record's bytes were changed after it was written.`);
+        console.error(`   If this was a deliberate redaction of a secret, acknowledge it on the chain:`);
+        console.error(`     contextengine audit-redact-ack --index ${t.slice(0, 3).join(",")} --reason "<what was removed and why>"`);
+    }
+    if (redacted.length > 0) {
+        console.error(`\n   Also ${redacted.length} redacted record(s), acknowledged on the chain, not counted above.`);
     }
     if ((report.orphanIndices ?? []).length > 0) {
         const o = report.orphanIndices;
@@ -2374,218 +2404,28 @@ function cliStats() {
     }
 }
 // ---------------------------------------------------------------------------
-// cost — multi-agent spend, read from Claude Code's own transcripts
+// cost — multi-agent spend, read from Claude Code's own transcripts.
+// Rendered by src/cost-report.ts, shared with the MCP tool. [LOCK] [COST-REPORT-ONE-RENDERER]
 // ---------------------------------------------------------------------------
-function fmtTok(n) {
-    if (n >= 1e6)
-        return `${(n / 1e6).toFixed(1)}M`;
-    if (n >= 1e3)
-        return `${(n / 1e3).toFixed(0)}k`;
-    return String(n);
-}
-function fmtDur(ms) {
-    if (ms === null || !Number.isFinite(ms))
-        return "—";
-    const s = Math.round(ms / 1000);
-    if (s < 60)
-        return `${s}s`;
-    const m = Math.floor(s / 60);
-    if (m < 60)
-        return `${m}m${String(s % 60).padStart(2, "0")}s`;
-    return `${Math.floor(m / 60)}h${String(m % 60).padStart(2, "0")}m`;
-}
-/** Resolve cost thresholds + pricing from policy, falling back to defaults. */
-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: 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" +
-                (hasOwnRates ? "" : ` (rates: built-in, as of ${DEFAULT_PRICING_ASOF})`),
-        };
-    }
-    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) => {
         const i = argv.indexOf(`--${name}`);
         return i >= 0 ? argv[i + 1] : undefined;
     };
-    const json = argv.includes("--json");
     const topRaw = flag("top");
-    const top = topRaw ? Math.max(1, parseInt(topRaw, 10) || 10) : 10;
     const daysRaw = flag("days");
-    const since = daysRaw ? Date.now() - parseInt(daysRaw, 10) * 86_400_000 : undefined;
-    const cwd = process.cwd();
-    const { t, source } = loadCostThresholds(cwd);
-    const runs = collectRuns({
+    const report = buildCostReport({
         session: flag("session"),
         project: flag("project"),
         run: flag("run"),
-        since,
+        top: topRaw ? parseInt(topRaw, 10) || 10 : 10,
+        days: daysRaw ? parseInt(daysRaw, 10) || undefined : undefined,
     });
-    if (!runs.length) {
-        console.log("No multi-agent runs found in " + transcriptRoot());
-        console.log("(fan-outs only: parent sessions are not counted — this measures delegation)");
-        return;
-    }
-    const scored = runs
-        .map((r) => ({ run: r, m: metricsFor(r, t.pricing) }))
-        .sort((a, b) => b.m.cost.total - a.m.cost.total);
-    const signals = runTranscriptHeuristics(runs, t);
-    if (json) {
-        console.log(JSON.stringify({
-            billing_mode: t.billing_mode,
-            cost_is_notional: t.billing_mode === "subscription",
-            thresholds_source: source,
-            runs: scored.map(({ run, m }) => ({
-                runId: run.runId, kind: run.kind, project: run.project, sessionId: run.sessionId,
-                volume: run.totals, intensity: {
-                    agents: m.agents, reported: m.reported, failed: m.failed,
-                    capacityExhausted: m.capacityExhausted, toolCalls: m.toolCalls,
-                    medianToolCalls: m.medianToolCalls, durationMs: run.durationMs,
-                    launchedBeforeFirstReport: m.launchedBeforeFirstReport,
-                },
-                cost: m.cost, cacheEfficiency: Number.isFinite(m.cacheEfficiency) ? m.cacheEfficiency : null,
-                outputShare: m.outputShare,
-            })),
-            signals,
-        }, null, 2));
+    if (argv.includes("--json") && report.json) {
+        console.log(JSON.stringify(report.json, null, 2));
         return;
     }
-    // Aggregate across everything in scope.
-    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;
-        failed += m.failed;
-        capacity += m.capacityExhausted;
-        reported += m.reported;
-        cost += m.cost.total;
-        withoutCache += m.cost.withoutCache;
-        unpriced += m.cost.unpricedTokens;
-    }
-    const allTok = totalTokens(vol);
-    const cw = vol.cacheWrite5m + vol.cacheWrite1h;
-    console.log("");
-    console.log(`MULTI-AGENT COST — ${scored.length} run(s), ${agents} subagents`);
-    console.log(`thresholds: ${source}`);
-    console.log("");
-    // ── 1. VOLUME ───────────────────────────────────────────────────────────
-    console.log("VOLUME (tokens moved)");
-    const volRow = (label, n) => console.log(`  ${label.padEnd(16)} ${fmtTok(n).padStart(8)}  ${allTok ? ((100 * n) / allTok).toFixed(1).padStart(5) : "  0.0"}%`);
-    volRow("cache read", vol.cacheRead);
-    volRow("cache write", cw);
-    volRow("input (fresh)", vol.input);
-    volRow("output", vol.output);
-    console.log(`  ${"total".padEnd(16)} ${fmtTok(allTok).padStart(8)}`);
-    console.log("");
-    // ── 2. VALUED COST ──────────────────────────────────────────────────────
-    const notional = t.billing_mode === "subscription";
-    let ci = 0, ccw = 0, ccr = 0, co = 0;
-    for (const { m } of scored) {
-        ci += m.cost.input;
-        ccw += m.cost.cacheWrite;
-        ccr += m.cost.cacheRead;
-        co += m.cost.output;
-    }
-    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)}`);
-    console.log(`  reported         ${String(reported).padStart(8)}`);
-    console.log(`  returned nothing ${String(failed).padStart(8)}${failed ? `  (${((100 * failed) / agents).toFixed(0)}% of the fleet)` : ""}`);
-    console.log(`  died at window   ${String(capacity).padStart(8)}${capacity ? "  ← capacity spent for no result" : ""}`);
-    console.log(`  tool calls       ${String(toolCalls).padStart(8)}  (${(toolCalls / Math.max(1, agents)).toFixed(1)}/agent)`);
-    console.log(`  cache reuse      ${(cw ? (vol.cacheRead / cw).toFixed(1) + "x" : "—").padStart(8)}  ${cw && vol.cacheRead / cw < t.min_cache_efficiency ? "← below floor, prefix is being rebuilt" : "(higher is better)"}`);
-    console.log("");
-    // ── Top runs ────────────────────────────────────────────────────────────
-    console.log(`TOP RUNS BY VALUED COST (${Math.min(top, scored.length)} of ${scored.length})`);
-    console.log(`  ${"cost".padStart(8)} ${"agents".padStart(6)} ${"dead".padStart(4)} ${"tools".padStart(5)} ${"reuse".padStart(6)} ${"dur".padStart(7)}  run`);
-    for (const { run, m } of scored.slice(0, top)) {
-        const reuse = Number.isFinite(m.cacheEfficiency) ? m.cacheEfficiency.toFixed(1) + "x" : "—";
-        console.log(`  ${("$" + m.cost.total.toFixed(2)).padStart(8)} ${String(m.agents).padStart(6)} ` +
-            `${String(m.failed).padStart(4)} ${String(m.medianToolCalls).padStart(5)} ${reuse.padStart(6)} ` +
-            `${fmtDur(run.durationMs).padStart(7)}  ${run.runId} ${run.project.replace(/^-Users-yan-/, "")}`);
-    }
-    console.log("");
-    // ── Signals ─────────────────────────────────────────────────────────────
-    if (!signals.length) {
-        console.log("✅ No context_burn or fanout_without_canary signals.");
-    }
-    else {
-        const crit = signals.filter((s) => s.severity === "critical");
-        console.log(`SIGNALS — ${signals.length} (${crit.length} critical)`);
-        for (const s of signals.slice(0, 20)) {
-            console.log(`  ${s.severity === "critical" ? "🔴" : "⚠️ "} [${s.kind}] ${s.reason}`);
-        }
-        if (signals.length > 20)
-            console.log(`  … ${signals.length - 20} more (use --json)`);
-    }
-    console.log("");
+    console.log(report.text);
 }
 /** Package version, read from the installed package.json rather than hardcoded. */
 function readPackageVersion() {
@@ -2635,6 +2475,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 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
                                        whatever is older than N days (default 30) OR beyond
@@ -2840,6 +2681,9 @@ else if (command === "sync-claude-md") {
         process.exit(1);
     });
 }
+else if (command === "audit-redact-ack") {
+    cliAuditRedactAck(process.argv.slice(3));
+}
 else if (command === "audit-rotate") {
     cliAuditRotate(process.argv.slice(3));
 }

package/dist/cost-report.d.ts

@@ -0,0 +1,22 @@
+import { type CostThresholds } from "./detector.js";
+export interface CostReportOptions {
+    session?: string;
+    project?: string;
+    run?: string;
+    days?: number;
+    top?: number;
+}
+export interface CostReport {
+    /** Human-readable report, what the CLI prints. */
+    text: string;
+    /** Structured report, what `--json` prints. null when no runs were found. */
+    json: Record<string, unknown> | null;
+    runs: number;
+}
+/** Resolve cost thresholds + pricing from policy, falling back to defaults. */
+export declare function loadCostThresholds(cwd: string): {
+    t: CostThresholds;
+    source: string;
+};
+export declare function buildCostReport(opts?: CostReportOptions, cwd?: string): CostReport;
+//# sourceMappingURL=cost-report.d.ts.map

package/dist/cost-report.js

@@ -0,0 +1,220 @@
+/**
+ * Multi-agent cost report, shared by the CLI (`contextengine cost`) and the MCP tool
+ * (`agent_cost`). One renderer, two surfaces.
+ *
+ * [LOCKED] [COST-REPORT-ONE-RENDERER] — 2026-08-21
+ * [NEVER] render the cost report in cli.ts or index.ts directly.
+ * WHY: the CLI shipped on 2026-08-20 as 170 lines of console.log; an MCP tool written the same
+ *      way would have been a second copy of every threshold, label and guard (NOTIONAL, UNPRICED,
+ *      floor-not-cost) that drifts the first time one of them is edited.
+ * FIX: buildCostReport() returns { text, json }; cli.ts prints, index.ts responds. Both surfaces
+ *      read the same thresholds from .contextengine/policy.json via loadCostThresholds().
+ */
+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 { loadRepoPolicy } from "./policy.js";
+function fmtTok(n) {
+    if (n >= 1e6)
+        return `${(n / 1e6).toFixed(1)}M`;
+    if (n >= 1e3)
+        return `${(n / 1e3).toFixed(0)}k`;
+    return String(n);
+}
+function fmtDur(ms) {
+    if (ms === null || !Number.isFinite(ms))
+        return "—";
+    const s = Math.round(ms / 1000);
+    if (s < 60)
+        return `${s}s`;
+    const m = Math.floor(s / 60);
+    if (m < 60)
+        return `${m}m${String(s % 60).padStart(2, "0")}s`;
+    return `${Math.floor(m / 60)}h${String(m % 60).padStart(2, "0")}m`;
+}
+/** Resolve cost thresholds + pricing from policy, falling back to defaults. */
+export 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: 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" +
+                (hasOwnRates ? "" : ` (rates: built-in, as of ${DEFAULT_PRICING_ASOF})`),
+        };
+    }
+    return {
+        t: DEFAULT_COST_THRESHOLDS,
+        source: `built-in defaults, rates as of ${DEFAULT_PRICING_ASOF} (no agent_cost in policy.json)`,
+    };
+}
+export function buildCostReport(opts = {}, cwd = process.cwd()) {
+    const out = [];
+    const line = (s = "") => { out.push(s); };
+    const top = Math.max(1, opts.top ?? 10);
+    const since = opts.days ? Date.now() - opts.days * 86_400_000 : undefined;
+    const { t, source } = loadCostThresholds(cwd);
+    const runs = collectRuns({
+        session: opts.session,
+        project: opts.project,
+        run: opts.run,
+        since,
+    });
+    if (!runs.length) {
+        line("No multi-agent runs found in " + transcriptRoot());
+        line("(fan-outs only: parent sessions are not counted — this measures delegation)");
+        return { text: out.join("\n"), json: null, runs: 0 };
+    }
+    const scored = runs
+        .map((r) => ({ run: r, m: metricsFor(r, t.pricing) }))
+        .sort((a, b) => b.m.cost.total - a.m.cost.total);
+    const signals = runTranscriptHeuristics(runs, t);
+    const json = {
+        billing_mode: t.billing_mode,
+        cost_is_notional: t.billing_mode === "subscription",
+        thresholds_source: source,
+        runs: scored.map(({ run, m }) => ({
+            runId: run.runId, kind: run.kind, project: run.project, sessionId: run.sessionId,
+            volume: run.totals, intensity: {
+                agents: m.agents, reported: m.reported, failed: m.failed,
+                capacityExhausted: m.capacityExhausted, toolCalls: m.toolCalls,
+                medianToolCalls: m.medianToolCalls, durationMs: run.durationMs,
+                launchedBeforeFirstReport: m.launchedBeforeFirstReport,
+            },
+            cost: m.cost, cacheEfficiency: Number.isFinite(m.cacheEfficiency) ? m.cacheEfficiency : null,
+            outputShare: m.outputShare,
+        })),
+        signals,
+    };
+    // Aggregate across everything in scope.
+    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;
+        failed += m.failed;
+        capacity += m.capacityExhausted;
+        reported += m.reported;
+        cost += m.cost.total;
+        withoutCache += m.cost.withoutCache;
+        unpriced += m.cost.unpricedTokens;
+    }
+    const allTok = totalTokens(vol);
+    const cw = vol.cacheWrite5m + vol.cacheWrite1h;
+    line();
+    line(`MULTI-AGENT COST — ${scored.length} run(s), ${agents} subagents`);
+    line(`thresholds: ${source}`);
+    line();
+    // ── 1. VOLUME ───────────────────────────────────────────────────────────
+    line("VOLUME (tokens moved)");
+    const volRow = (label, n) => line(`  ${label.padEnd(16)} ${fmtTok(n).padStart(8)}  ${allTok ? ((100 * n) / allTok).toFixed(1).padStart(5) : "  0.0"}%`);
+    volRow("cache read", vol.cacheRead);
+    volRow("cache write", cw);
+    volRow("input (fresh)", vol.input);
+    volRow("output", vol.output);
+    line(`  ${"total".padEnd(16)} ${fmtTok(allTok).padStart(8)}`);
+    line();
+    // ── 2. VALUED COST ──────────────────────────────────────────────────────
+    const notional = t.billing_mode === "subscription";
+    let ci = 0, ccw = 0, ccr = 0, co = 0;
+    for (const { m } of scored) {
+        ci += m.cost.input;
+        ccw += m.cost.cacheWrite;
+        ccr += m.cost.cacheRead;
+        co += m.cost.output;
+    }
+    const agg = {
+        input: ci, cacheWrite: ccw, cacheRead: ccr, output: co,
+        total: cost, withoutCache, unpricedTokens: unpriced,
+    };
+    const status = pricingStatus(agg);
+    line(`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") {
+        line(`  UNPRICED — no rate matched any model in this data, so no cost can be`);
+        line(`  stated. ${fmtTok(unpriced)} tokens were moved. This is an unknown, not $0.`);
+        line();
+        line(`  Models seen without a rate: ${[...unpricedModels].sort().join(", ") || "(unknown)"}`);
+        line(`  Add them to .contextengine/policy.json → agent_cost.pricing.`);
+        line();
+    }
+    else {
+        if (notional) {
+            line("  This machine runs Claude Code on a subscription: no dollar below is");
+            line("  debited. Use these figures to compare approaches, not as spend.");
+        }
+        const costRow = (label, n) => line(`  ${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);
+        line(`  ${"total".padEnd(16)} ${("$" + cost.toFixed(2)).padStart(8)}`);
+        line(`  ${"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") {
+            line(`  ⚠ ${fmtTok(unpriced)} tokens UNPRICED and NOT in the figures above` +
+                ` (${[...unpricedModels].sort().join(", ") || "unknown model"}) — the total is a floor, not the cost`);
+        }
+        line();
+    }
+    // ── 3. INTENSITY (the capacity proxy) ───────────────────────────────────
+    line(`INTENSITY (capacity proxy${notional ? " — the scarce resource here" : ""})`);
+    line(`  subagents        ${String(agents).padStart(8)}`);
+    line(`  reported         ${String(reported).padStart(8)}`);
+    line(`  returned nothing ${String(failed).padStart(8)}${failed ? `  (${((100 * failed) / agents).toFixed(0)}% of the fleet)` : ""}`);
+    line(`  died at window   ${String(capacity).padStart(8)}${capacity ? "  ← capacity spent for no result" : ""}`);
+    line(`  tool calls       ${String(toolCalls).padStart(8)}  (${(toolCalls / Math.max(1, agents)).toFixed(1)}/agent)`);
+    line(`  cache reuse      ${(cw ? (vol.cacheRead / cw).toFixed(1) + "x" : "—").padStart(8)}  ${cw && vol.cacheRead / cw < t.min_cache_efficiency ? "← below floor, prefix is being rebuilt" : "(higher is better)"}`);
+    line();
+    // ── Top runs ────────────────────────────────────────────────────────────
+    line(`TOP RUNS BY VALUED COST (${Math.min(top, scored.length)} of ${scored.length})`);
+    line(`  ${"cost".padStart(8)} ${"agents".padStart(6)} ${"dead".padStart(4)} ${"tools".padStart(5)} ${"reuse".padStart(6)} ${"dur".padStart(7)}  run`);
+    for (const { run, m } of scored.slice(0, top)) {
+        const reuse = Number.isFinite(m.cacheEfficiency) ? m.cacheEfficiency.toFixed(1) + "x" : "—";
+        line(`  ${("$" + m.cost.total.toFixed(2)).padStart(8)} ${String(m.agents).padStart(6)} ` +
+            `${String(m.failed).padStart(4)} ${String(m.medianToolCalls).padStart(5)} ${reuse.padStart(6)} ` +
+            `${fmtDur(run.durationMs).padStart(7)}  ${run.runId} ${run.project.replace(/^-Users-yan-/, "")}`);
+    }
+    line();
+    // ── Signals ─────────────────────────────────────────────────────────────
+    if (!signals.length) {
+        line("✅ No context_burn or fanout_without_canary signals.");
+    }
+    else {
+        const crit = signals.filter((s) => s.severity === "critical");
+        line(`SIGNALS — ${signals.length} (${crit.length} critical)`);
+        for (const s of signals.slice(0, 20)) {
+            line(`  ${s.severity === "critical" ? "🔴" : "⚠️ "} [${s.kind}] ${s.reason}`);
+        }
+        if (signals.length > 20)
+            line(`  … ${signals.length - 20} more (use --json)`);
+    }
+    line();
+    return { text: out.join("\n"), json, runs: scored.length };
+}
+//# sourceMappingURL=cost-report.js.map

package/dist/index.js

@@ -10,9 +10,10 @@ import { collectProjectOps, collectSystemOps } from "./collectors.js";
 import { loadCache, saveCache } from "./cache.js";
 import { listProjects, checkPorts, runComplianceAudit, formatProjectList, formatPortMap, formatPlan, scoreProject, formatScoreReport, runScoreCanary, } from "./agents.js";
 import { saveSession, loadSession, listSessions, deleteSession, formatSession, formatSessionList, } from "./sessions.js";
-import { verifyChain, readAuditLog, filterByRange } from "./audit.js";
+import { verifyChain, readAuditLog, filterByRange, autoRotateAuditLog } from "./audit.js";
 import { startEventIngestServer } from "./http-server.js";
 import { detect } from "./detector.js";
+import { buildCostReport } from "./cost-report.js";
 import { saveLearning, searchLearnings, listLearnings, deleteLearning, learningsToChunks, learningsStats, formatLearnings, importLearningsFromFile, autoImportFromSources, LEARNING_CATEGORIES, } from "./learnings.js";
 import { communityRulesToChunks, mergeWithDedup, loadCommunityStore, } from "./community-sync.js";
 import { readFileSync, existsSync, watch, statSync, writeFileSync, mkdirSync } from "fs";
@@ -609,6 +610,9 @@ server.tool("audit_verify", "Verify the integrity of the local audit log chain.
     const summary = [];
     summary.push(`Audit chain: ${report.ok ? "✅ INTACT" : "❌ BROKEN"}`);
     summary.push(`Total records: ${report.total}`);
+    if ((report.redactedIndices ?? []).length > 0) {
+        summary.push(`Redacted and acknowledged on the chain: ${report.redactedIndices.length} record(s), not counted as altered`);
+    }
     if (since || until) {
         summary.push(`Range filter: ${since ?? "start"} → ${until ?? "now"}  (${filtered.length} record(s) in range)`);
     }
@@ -623,6 +627,28 @@ server.tool("audit_verify", "Verify the integrity of the local audit log chain.
     return respond("audit_verify", summary.join("\n"));
 });
 // ---------------------------------------------------------------------------
+// Tool: agent_cost (multi-agent token / cost / capacity report)
+// ---------------------------------------------------------------------------
+// Same renderer as `contextengine cost`. [LOCK] [COST-REPORT-ONE-RENDERER]
+// Free tool: it reads the caller's own Claude Code transcripts on this machine,
+// nothing leaves it. Added 2026-08-21, one day after the CLI (707fcc8).
+server.tool("agent_cost", "Multi-agent cost report from Claude Code's own transcripts on this machine: tokens moved (cache read/write, fresh input, output), valued cost at API list prices (marked NOTIONAL on a subscription, UNPRICED when no rate matches), capacity intensity (subagents, failed, died at window, tool calls per agent, cache reuse), top runs, and context_burn / fanout_without_canary signals. Call it after a fan-out to read what it consumed, or before one to compare with the last. Thresholds come from .contextengine/policy.json agent_cost, else built-in defaults.", {
+    days: z.number().int().positive().optional().describe("Only runs started within the last N days"),
+    project: z.string().optional().describe("Filter by project slug as it appears in ~/.claude/projects (e.g. -Users-yan-Projects-ContextEngine)"),
+    session: z.string().optional().describe("Filter by parent session id"),
+    run: z.string().optional().describe("Filter by run id (wf_... or task group id)"),
+    top: z.number().int().positive().max(50).optional().describe("How many runs to list (default 10)"),
+    json: z.boolean().optional().describe("Return the structured JSON report instead of the text one"),
+    policy_dir: z.string().optional().describe("Absolute path of the repo whose .contextengine/policy.json supplies agent_cost thresholds and rates. Default: the MCP server's working directory, which under launchd is the home dir, not a repo; the report names which source it used on its 'thresholds:' line"),
+}, async ({ days, project, session, run, top, json, policy_dir }) => {
+    // [COST-POLICY-DIR-IS-EXPLICIT] — the daemon's cwd is not a project. Without this the MCP
+    // surface silently priced with built-in defaults while the CLI in the repo read policy.json.
+    const report = buildCostReport({ days, project, session, run, top }, policy_dir || process.cwd());
+    if (json && report.json)
+        return respond("agent_cost", JSON.stringify(report.json, null, 2));
+    return respond("agent_cost", report.text);
+});
+// ---------------------------------------------------------------------------
 // Tool: drift_status (Detector — read current drift signals)
 // ---------------------------------------------------------------------------
 // Agents should call this between major task phases. If any 'critical' signal
@@ -1131,6 +1157,24 @@ async function main() {
     const transport = new StdioServerTransport();
     await server.connect(transport);
     console.error("[ContextEngine] 🚀 MCP server running on stdio (keyword search ready)");
+    // 3a. Audit log auto-rotation. Deferred so the first requests are answered before the
+    // synchronous verify + rewrite (a few seconds on a 500k-record chain) blocks the loop.
+    // [LOCK] [AUTO-ROTATE-HYSTERESIS-AND-ONE-RUNNER]
+    // Measured 2026-08-21: ~13k records/hour on this machine, so the 100k trigger is hours
+    // away, not a day; a server that is never restarted must still rotate. Hourly recheck.
+    const runAutoRotate = () => {
+        try {
+            const o = autoRotateAuditLog();
+            if (o.action === "rotated" || o.action === "refused" || o.action === "error" || o.action === "in_progress") {
+                console.error(`[ContextEngine] 📦 audit auto-rotate (${o.action}): ${o.detail}`);
+            }
+        }
+        catch (err) {
+            console.error(`[ContextEngine] ⚠ audit auto-rotate failed: ${err.message}`);
+        }
+    };
+    setTimeout(runAutoRotate, 3_000).unref();
+    setInterval(runAutoRotate, 60 * 60_000).unref();
     // 3b. Write server-meta.json so the VS Code extension can read tool count
     // without needing an active MCP session. Single source of truth =
     // src/tools-manifest.ts (asserted by tests/tools-manifest.test.ts).

package/dist/tools-manifest.d.ts

@@ -24,14 +24,14 @@
  * Every tool name registered on the MCP server, in registration order.
  * Order is not load-bearing — kept stable for easier diffs.
  */
-export declare const ALL_TOOLS: readonly ["search_context", "list_sources", "read_source", "reindex", "list_projects", "check_ports", "run_audit", "score_project", "save_session", "load_session", "list_sessions", "delete_session", "audit_verify", "drift_status", "end_session", "save_learning", "list_learnings", "delete_learning", "import_learnings", "activate", "activation_status"];
+export declare const ALL_TOOLS: readonly ["search_context", "list_sources", "read_source", "reindex", "list_projects", "check_ports", "run_audit", "score_project", "save_session", "load_session", "list_sessions", "delete_session", "audit_verify", "drift_status", "agent_cost", "end_session", "save_learning", "list_learnings", "delete_learning", "import_learnings", "activate", "activation_status"];
 /**
  * The 4 tools gated behind PRO activation. Subset of `ALL_TOOLS`.
  * Must match `PREMIUM_TOOLS` in `src/activation.ts` (asserted by test).
  */
 export declare const PREMIUM_TOOL_NAMES: readonly ["score_project", "run_audit", "check_ports", "list_projects"];
 /** Total count — what users see as "Active on all N MCP tools". */
-export declare const TOOL_COUNT: 21;
+export declare const TOOL_COUNT: 22;
 /** Free-tier tool count — everything except `PREMIUM_TOOL_NAMES`. */
 export declare const FREE_TOOL_COUNT: number;
 //# sourceMappingURL=tools-manifest.d.ts.map

package/dist/tools-manifest.js

@@ -39,6 +39,7 @@ export const ALL_TOOLS = [
     "delete_session",
     "audit_verify",
     "drift_status",
+    "agent_cost",
     "end_session",
     "save_learning",
     "list_learnings",

package/package.json

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