@compr/opscontext-mcp 2.5.3 → 2.5.5

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