@compr/opscontext-mcp 2.8.4 → 2.9.0

package/dist/audit.js

@@ -46,8 +46,8 @@
 // Records every state-changing operation. Each line carries the SHA-256 hash
 // of the previous line's canonical content, so mutation of any historical
 // record breaks chain verification at that index.
-import { existsSync, mkdirSync, readFileSync, appendFileSync, openSync, closeSync, unlinkSync, statSync, writeSync, readSync, fsyncSync, renameSync, readdirSync, constants, } from "fs";
-import { join } from "path";
+import { existsSync, mkdirSync, readFileSync, appendFileSync, openSync, closeSync, unlinkSync, statSync, writeSync, readSync, fsyncSync, renameSync, linkSync, readdirSync, constants, } from "fs";
+import { basename, join } from "path";
 import { homedir } from "os";
 import { createHash } from "crypto";
 const GENESIS_HASH = "0".repeat(64);
@@ -210,6 +210,35 @@ function parseHeadOrThrow(line) {
     }
     return rec.hash;
 }
+/** Hash of the first record of a log file, or null when it is empty. Reads the head only. */
+function readFirstRecordHash(path) {
+    if (!existsSync(path))
+        return null;
+    const fd = openSync(path, constants.O_RDONLY);
+    let head = "";
+    try {
+        const buf = Buffer.alloc(TAIL_READ_BYTES);
+        const n = readSync(fd, buf, 0, buf.length, 0);
+        head = buf.subarray(0, n).toString("utf-8");
+    }
+    finally {
+        closeSync(fd);
+    }
+    let nl = head.indexOf("\n");
+    if (nl === -1) {
+        head = readFileSync(path, "utf-8"); // a first record longer than the window
+        nl = head.indexOf("\n");
+    }
+    const line = (nl === -1 ? head : head.slice(0, nl)).trim();
+    if (!line)
+        return null;
+    try {
+        return JSON.parse(line).hash ?? null;
+    }
+    catch {
+        return null;
+    }
+}
 /** Fallback for the pathological case: a single record longer than TAIL_READ_BYTES. */
 function readLastHashFullScan() {
     const path = auditPath();
@@ -293,7 +322,15 @@ export function appendAudit(event, payload, actor = "system") {
 function archiveDir() {
     return join(auditDir(), "audit-archive");
 }
-const SEGMENT_RE = /^audit-(\d{4,})\.jsonl$/;
+// `audit-NNNN.jsonl` is written by rotation. `audit-NNNN-rK.jsonl` holds records put back by
+// restoreSegment() and sorts right after `audit-NNNN.jsonl` (K from 1), so a restored block
+// takes its place in the chain without renaming any existing segment.
+// [LOCK] [RESTORE-ONLY-CLOSES-A-PROVEN-GAP]
+const SEGMENT_RE = /^audit-(\d{4,})(?:-r([1-9]\d*))?\.jsonl$/;
+function segmentKey(f) {
+    const m = SEGMENT_RE.exec(f);
+    return [Number(m[1]), m[2] === undefined ? 0 : Number(m[2])];
+}
 /** Archived segment filenames in chain order (oldest first). */
 export function listSegments() {
     const dir = archiveDir();
@@ -301,7 +338,66 @@ export function listSegments() {
         return [];
     return readdirSync(dir)
         .filter((f) => SEGMENT_RE.test(f))
-        .sort((a, b) => Number(SEGMENT_RE.exec(a)[1]) - Number(SEGMENT_RE.exec(b)[1]));
+        .sort((a, b) => {
+        const [an, ar] = segmentKey(a);
+        const [bn, br] = segmentKey(b);
+        return an - bn || ar - br;
+    });
+}
+/**
+ * [LOCKED] [SEGMENT-IS-NEVER-OVERWRITTEN] - 2026-09-24
+ * [NEVER] number a new segment from the segment COUNT, and never put a segment in place with
+ *         renameSync onto a name that may already exist.
+ * WHY: renameSync replaces an existing file without a word. On 2026-09-15 two rotations both
+ *      chose audit-0020.jsonl and the second rename erased the first: 51,174 records gone, and
+ *      verifyChain() reported the next record as an orphan, i.e. "history was deleted". Count+1
+ *      naming also lands on an existing file as soon as one number is missing or a restored
+ *      `-rK` segment exists.
+ * FIX: the next number is the highest existing one + 1, chosen while holding the rotate lock
+ *      ([ROTATION-HOLDS-THE-LOCK-BEFORE-IT-PLANS]), and placeWithoutOverwrite() puts the file
+ *      in place with a hard link, which fails on an existing name instead of replacing it.
+ *      The one sanctioned rewrite of an existing segment is scrubAuditLog(), which removes
+ *      credentials and acknowledges each change on the chain. [LOCK] [SCRUB-IS-ACKNOWLEDGED-REDACTION]
+ */
+function nextSegmentName() {
+    const highest = listSegments().reduce((m, f) => Math.max(m, segmentKey(f)[0]), 0);
+    return `audit-${String(highest + 1).padStart(4, "0")}.jsonl`;
+}
+function safeUnlink(path) {
+    try {
+        unlinkSync(path);
+    }
+    catch {
+        /* already gone */
+    }
+}
+/** Put a fully written, fsynced temp file at `target` only if nothing is there yet. Returns
+ *  false, and removes the temp file, when `target` exists. [LOCK] [SEGMENT-IS-NEVER-OVERWRITTEN] */
+function placeWithoutOverwrite(tmp, target) {
+    try {
+        linkSync(tmp, target); // atomic, and fails with EEXIST rather than replacing
+    }
+    catch (e) {
+        const code = e.code;
+        if (code === "EEXIST") {
+            safeUnlink(tmp);
+            return false;
+        }
+        if (code === "EPERM" || code === "ENOTSUP" || code === "EOPNOTSUPP" || code === "ENOSYS") {
+            // No hard links on this filesystem (FAT, exFAT, some network mounts): check, then rename.
+            // Safe only because every writer of segments holds the rotate lock.
+            if (existsSync(target)) {
+                safeUnlink(tmp);
+                return false;
+            }
+            renameSync(tmp, target);
+            return true;
+        }
+        safeUnlink(tmp);
+        throw e;
+    }
+    safeUnlink(tmp);
+    return true;
 }
 function parseLines(data, label) {
     return data
@@ -375,13 +471,15 @@ export function planRotation(opts = {}) {
     let cut = Math.max(cutByDate, cutByCount);
     // Keep the tail intact regardless of either rule.
     cut = Math.min(cut, Math.max(0, live.length - MIN_LIVE_RECORDS));
-    const next = listSegments().length + 1;
+    // [LOCK] [SEGMENT-IS-NEVER-OVERWRITTEN]: highest number + 1, not count + 1.
     return {
         archiveCount: cut,
         keepCount: live.length - cut,
         cutoff,
-        segmentFile: cut > 0 ? `audit-${String(next).padStart(4, "0")}.jsonl` : null,
+        segmentFile: cut > 0 ? nextSegmentName() : null,
         refusedReason: null,
+        firstLiveHash: live[0]?.hash ?? null,
+        liveCount: live.length,
     };
 }
 /**
@@ -390,8 +488,47 @@ export function planRotation(opts = {}) {
  * Refuses to run on a chain that does not currently verify: rotating a log with altered
  * or orphaned records would bake the damage into an append-only segment and make the
  * cause unrecoverable. Forks are fine — they are concurrency, not tampering.
+ *
+ * [LOCKED] [ROTATION-HOLDS-THE-LOCK-BEFORE-IT-PLANS] - 2026-09-24
+ * [NEVER] let any caller rotate without the rotate lock, and never plan (choose the segment
+ *         name, count the slice) before holding it.
+ * WHY: on 2026-09-15 at 12:44:46Z and 12:44:51Z two rotations both wrote audit-0020.jsonl. The
+ *      manual `audit-rotate` command called this function directly, and only autoRotateAuditLog()
+ *      took the lock. The second run planned while the first was mid-write (same segment name),
+ *      then applied its old count to the live log the first run had already cut: it archived the
+ *      first run's remainder into the same file name and erased the first run's segment. 51,174
+ *      records vanished; verifyChain() reported an orphan. They were put back on 2026-09-24 from a
+ *      Time Machine local snapshot with restoreSegment().
+ * FIX: this function takes the lock first and plans under it, so the manual command, auto-rotation
+ *      and anything added later all go through one lock. The slice is refused unless the live log
+ *      still starts with the record the plan read. A held lock returns inProgress, untouched.
  */
 export function rotateAuditLog(opts = {}) {
+    // A dry run writes nothing, so it needs no lock and never waits for one.
+    if (opts.dryRun)
+        return rotateHoldingLock(opts);
+    const lock = acquireRotateLock();
+    if ("heldMs" in lock) {
+        return {
+            archiveCount: 0,
+            keepCount: 0,
+            cutoff: "",
+            segmentFile: null,
+            refusedReason: `another rotation is in progress (its lock is ${Math.round(lock.heldMs / 1000)}s old); nothing was read or written`,
+            rotated: false,
+            bytesArchived: 0,
+            bytesRemaining: 0,
+            inProgress: true,
+        };
+    }
+    try {
+        return rotateHoldingLock(opts);
+    }
+    finally {
+        lock.release();
+    }
+}
+function rotateHoldingLock(opts) {
     const path = auditPath();
     const plan = planRotation(opts);
     const empty = { ...plan, rotated: false, bytesArchived: 0, bytesRemaining: 0 };
@@ -440,19 +577,44 @@ export function rotateAuditLog(opts = {}) {
     // lock for, and acquireLockSync() force-breaks locks older than STALE_LOCK_MS.
     const snapshotSize = statSync(path).size;
     const live = parseLines(readFileSync(path, "utf-8"), "audit.log");
+    // [LOCK] [ROTATION-HOLDS-THE-LOCK-BEFORE-IT-PLANS]: archiveCount is a count from the plan's
+    // read. Appends at the tail since then are fine; a different head means someone else cut or
+    // rewrote the log, and slicing it with an old count archives the wrong records.
+    if ((live[0]?.hash ?? null) !== (plan.firstLiveHash ?? null) || live.length < (plan.liveCount ?? 0)) {
+        return {
+            ...empty,
+            refusedReason: "the live log changed after the rotation planned (it no longer starts with the record the plan read); nothing was written",
+        };
+    }
     const archived = live.slice(0, plan.archiveCount);
     const remainder = live.slice(plan.archiveCount);
     const segName = plan.segmentFile;
     const segTmp = join(adir, `.${segName}.tmp`);
     const segBody = archived.map((r) => JSON.stringify(r)).join("\n") + "\n";
     writeFileAndSync(segTmp, segBody);
-    renameSync(segTmp, join(adir, segName));
+    // [LOCK] [SEGMENT-IS-NEVER-OVERWRITTEN]
+    if (!placeWithoutOverwrite(segTmp, join(adir, segName))) {
+        return { ...empty, refusedReason: `segment ${segName} already exists; refusing to overwrite archived history` };
+    }
     // [ROTATE-ARCHIVE-BEFORE-TRUNCATE]: the segment is durable from here on. Only now may
     // the live log shrink.
     const release = acquireLockSync();
     let remainderBody = remainder.map((r) => JSON.stringify(r)).join("\n") + "\n";
     try {
         const currentSize = statSync(path).size;
+        // [LOCK] [ROTATION-HOLDS-THE-LOCK-BEFORE-IT-PLANS]: last check before the live log is
+        // replaced. Appends only ever grow it and keep its head. Smaller, or a different first record,
+        // means another writer cut it since our snapshot (possible only if our rotate lock was broken
+        // as stale), and writing our remainder over it would erase that writer's records. Replayed on
+        // 2026-09-24: this is how the second of two overlapping rotations lost a record silently.
+        // Our segment then only duplicates records that other rotation archived, so it goes.
+        if (currentSize < snapshotSize || readFirstRecordHash(path) !== plan.firstLiveHash) {
+            safeUnlink(join(adir, segName));
+            return {
+                ...empty,
+                refusedReason: "the live log was cut by another writer during this rotation; our segment was removed and nothing else was written",
+            };
+        }
         if (currentSize > snapshotSize) {
             // Appends landed while we were writing the segment. They are newer than the cutoff
             // by construction, so they belong to the remainder. Copy the raw bytes across
@@ -505,12 +667,55 @@ export function rotateAuditLog(opts = {}) {
  *      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.
+ * 2026-09-24: the lock is now taken inside rotateAuditLog(), not here, because the manual
+ *      command bypassed it. [LOCK] [ROTATION-HOLDS-THE-LOCK-BEFORE-IT-PLANS]
  */
 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");
 }
+/**
+ * Take the rotate lock, or report how old the holder's lock is. O_EXCL create is the primitive; a
+ * lock older than ROTATE_LOCK_STALE_MS is an orphan from a crashed rotation and is broken. Every
+ * writer of archive segments goes through this: rotateAuditLog() and restoreSegment().
+ * [LOCK] [AUTO-ROTATE-HYSTERESIS-AND-ONE-RUNNER] [LOCK] [ROTATION-HOLDS-THE-LOCK-BEFORE-IT-PLANS]
+ */
+function acquireRotateLock() {
+    const lock = rotateLockPath();
+    ensureDir();
+    for (let attempt = 0; attempt < 2; attempt++) {
+        let fd;
+        try {
+            fd = openSync(lock, constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY, 0o600);
+        }
+        catch (e) {
+            if (e.code !== "EEXIST")
+                throw e;
+            let age;
+            try {
+                age = Date.now() - statSync(lock).mtimeMs;
+            }
+            catch {
+                continue; // released between our open and our stat: try again
+            }
+            if (age < ROTATE_LOCK_STALE_MS)
+                return { heldMs: age };
+            safeUnlink(lock);
+            continue;
+        }
+        try {
+            writeSync(fd, `${process.pid}\n${new Date().toISOString()}\n`);
+        }
+        catch {
+            /* contents are a courtesy */
+        }
+        closeSync(fd);
+        return { release: () => safeUnlink(lock) };
+    }
+    // Another process broke the same stale lock and won the create.
+    return { heldMs: 0 };
+}
 /** Count newline-terminated lines without parsing. The live log is small by construction. */
 export function countLiveRecords() {
     const path = auditPath();
@@ -533,36 +738,13 @@ export function autoRotateAuditLog(opts = {}) {
     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;
+    // One runner at a time: rotateAuditLog() takes the rotate lock itself, so this path and the
+    // manual `audit-rotate` command share it. [LOCK] [ROTATION-HOLDS-THE-LOCK-BEFORE-IT-PLANS]
     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.inProgress) {
+            return { action: "in_progress", liveRecords, detail: result.refusedReason ?? "another rotation holds the lock" };
+        }
         if (!result.rotated) {
             return { action: "refused", liveRecords, detail: result.refusedReason ?? "not rotated", result };
         }
@@ -576,12 +758,6 @@ export function autoRotateAuditLog(opts = {}) {
     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");
@@ -752,6 +928,274 @@ export function acknowledgeRedaction(indices, reason, actor = "system") {
     const record = appendAudit("audit.redact", { reason, redacted: entries }, actor);
     return { acknowledged, rejected, record };
 }
+/**
+ * Put a lost block of records back into the archive, from a backup.
+ *
+ * [LOCKED] [RESTORE-ONLY-CLOSES-A-PROVEN-GAP] - 2026-09-24
+ * [NEVER] put records into the archive unless every record hashes correctly, each names the one
+ *         before it as its parent, the block's first parent is the last record of the segment it
+ *         follows, the record after the gap names the block's last record as its parent, and none
+ *         of the block's records is already in the log. Together these admit only the original
+ *         records: a substitute block would need a SHA-256 preimage.
+ * WHY: the archive is evidence. A restore that accepted any block would be a sanctioned way to
+ *      rewrite history, the one thing the chain exists to make visible. First real use: the
+ *      51,174 records erased on 2026-09-15 (see [SEGMENT-IS-NEVER-OVERWRITTEN]), found whole in a
+ *      Time Machine local snapshot on 2026-09-24.
+ * FIX: only a hole the verifier already reports can be filled, and only at a segment boundary.
+ *      Dry run by default. Apply takes the rotate lock before it plans, never overwrites a file,
+ *      re-verifies, removes its own segment unless the chain has exactly one orphan fewer and no
+ *      new damage, and records itself as an `audit.restore` event with a reason.
+ */
+export function restoreSegment(file, opts = {}) {
+    const empty = {
+        refusedReason: null, records: 0, firstTs: null, lastTs: null,
+        after: null, before: null, segmentFile: null, orphanIndex: null,
+    };
+    const refuse = (why, partial = {}) => ({ ...empty, ...partial, refusedReason: why, restored: false, record: null });
+    if (opts.apply && !opts.reason?.trim())
+        return refuse("a reason is required to apply a restore");
+    if (!existsSync(file))
+        return refuse(`no such file: ${file}`);
+    let block;
+    try {
+        block = parseLines(readFileSync(file, "utf-8"), basename(file));
+    }
+    catch (e) {
+        return refuse(e.message);
+    }
+    if (block.length === 0)
+        return refuse("the file holds no records");
+    const base = { records: block.length, firstTs: block[0].ts, lastTs: block[block.length - 1].ts };
+    // Every record hashes to itself and names the record before it as its parent: a strictly
+    // linear block. With the two boundary checks below, that pins the block to the one chain that
+    // ends in the orphan's missing parent, so only the original records can pass (a substitute
+    // would need a SHA-256 preimage). A side branch inside the block would be unconstrained by
+    // that, so it is refused rather than trusted.
+    const blockHashes = new Set();
+    for (let i = 0; i < block.length; i++) {
+        const r = block[i];
+        if (computeHash(r.prev_hash, r.ts, r.event, r.actor, r.payload) !== r.hash) {
+            return refuse(`record ${i + 1} of the file does not match its own hash`, base);
+        }
+        if (i > 0 && r.prev_hash !== block[i - 1].hash) {
+            return refuse(`record ${i + 1} of the file does not name record ${i} as its parent; only a strictly linear block can be restored`, base);
+        }
+        blockHashes.add(r.hash);
+    }
+    const lastHash = block[block.length - 1].hash;
+    const planAndMaybeWrite = () => {
+        const parts = [];
+        let index = 0;
+        const names = [...listSegments(), "audit.log"];
+        for (const name of names) {
+            const path = name === "audit.log" ? auditPath() : join(archiveDir(), name);
+            if (!existsSync(path))
+                continue;
+            const recs = parseLines(readFileSync(path, "utf-8"), name);
+            if (recs.length === 0)
+                continue;
+            for (const r of recs) {
+                if (blockHashes.has(r.hash))
+                    return refuse(`record ${r.hash.slice(0, 12)} of the file is already in ${name}`, base);
+            }
+            parts.push({ name, start: index, first: recs[0], last: recs[recs.length - 1] });
+            index += recs.length;
+        }
+        const at = parts.findIndex((p, i) => p.name !== "audit.log" &&
+            p.last.hash === block[0].prev_hash &&
+            i + 1 < parts.length &&
+            parts[i + 1].first.prev_hash === lastHash);
+        if (at === -1) {
+            return refuse("the block does not fill a gap at a segment boundary: its first record's parent must be the last record of a segment, and the record after that segment must name the block's last record as its parent", base);
+        }
+        const prev = parts[at];
+        const next = parts[at + 1];
+        const [n, r] = segmentKey(prev.name);
+        const segName = `audit-${String(n).padStart(4, "0")}-r${r + 1}.jsonl`;
+        if (next.name === segName)
+            return refuse(`no free segment name between ${prev.name} and ${next.name}`, base);
+        const plan = {
+            ...empty, ...base,
+            after: prev.name,
+            before: next.name,
+            segmentFile: segName,
+            orphanIndex: next.start,
+        };
+        if (!opts.apply)
+            return { ...plan, restored: false, record: null };
+        const beforeReport = verifyChain();
+        if (!(beforeReport.orphanIndices ?? []).includes(next.start)) {
+            return refuse(`the verifier does not report the record after ${prev.name} as an orphan; nothing to restore`, base);
+        }
+        const adir = archiveDir();
+        const tmp = join(adir, `.${segName}.tmp`);
+        writeFileAndSync(tmp, block.map((x) => JSON.stringify(x)).join("\n") + "\n");
+        const target = join(adir, segName);
+        if (!placeWithoutOverwrite(tmp, target))
+            return refuse(`segment ${segName} already exists; refusing to overwrite it`, base);
+        const afterReport = verifyChain();
+        // `>=` on the total: live appends keep landing during two full verifies (seconds on a real
+        // log), and they only ever add records.
+        const improved = (afterReport.orphanIndices ?? []).length === (beforeReport.orphanIndices ?? []).length - 1 &&
+            (afterReport.tamperedIndices ?? []).length === (beforeReport.tamperedIndices ?? []).length &&
+            afterReport.total >= beforeReport.total + block.length;
+        if (!improved) {
+            safeUnlink(target);
+            return refuse("the chain did not come out exactly one orphan better; the restored segment was removed again", base);
+        }
+        const record = appendAudit("audit.restore", {
+            segment: segName,
+            after: prev.name,
+            records: block.length,
+            first_hash: block[0].hash,
+            last_hash: block[block.length - 1].hash,
+            first_ts: block[0].ts,
+            last_ts: block[block.length - 1].ts,
+            source: basename(file),
+            reason: opts.reason.trim(),
+        }, opts.actor ?? "system");
+        return { ...plan, restored: true, record };
+    };
+    if (!opts.apply)
+        return planAndMaybeWrite();
+    // [LOCK] [ROTATION-HOLDS-THE-LOCK-BEFORE-IT-PLANS]: the same lock as rotation, taken before planning.
+    const lock = acquireRotateLock();
+    if ("heldMs" in lock)
+        return refuse("a rotation is in progress; try again in a minute", base);
+    try {
+        return planAndMaybeWrite();
+    }
+    finally {
+        lock.release();
+    }
+}
+/** Capture records: the only ones that carry text someone typed or ran. */
+const SCRUB_EVENT_RE = /^(?:vscode\.|browser\.|cli\.)|^(?:drift\.detected|notification\.fired)$/;
+const SCRUB_LINE_HINT = /"event":"(?:vscode\.|browser\.|cli\.|drift\.detected"|notification\.fired")/;
+const SCRUB_ACK_BATCH = 100;
+/** Redact the capture records of one log file's text; unchanged lines are kept byte for byte. */
+function scrubText(text, redact) {
+    const lines = text.split("\n");
+    const redacted = [];
+    const counts = {};
+    let records = 0;
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        if (!line)
+            continue;
+        records++;
+        if (!SCRUB_LINE_HINT.test(line))
+            continue;
+        let r;
+        try {
+            r = JSON.parse(line);
+        }
+        catch {
+            continue; // an unreadable line is the verifier's to report, never ours to rewrite
+        }
+        if (!SCRUB_EVENT_RE.test(r.event) || !r.payload || typeof r.payload !== "object")
+            continue;
+        const out = redact(r.payload);
+        if (!out.changed)
+            continue;
+        for (const [k, n] of Object.entries(out.counts))
+            counts[k] = (counts[k] ?? 0) + n;
+        lines[i] = JSON.stringify({ ...r, payload: out.value });
+        redacted.push({
+            hash: r.hash,
+            content_hash: computeHash(r.prev_hash, r.ts, r.event, r.actor, out.value),
+            ts: r.ts,
+            event: r.event,
+        });
+    }
+    return { body: lines.join("\n"), redacted, records, counts };
+}
+/**
+ * Remove credentials from records already written, and acknowledge each rewrite on the chain.
+ *
+ * [LOCKED] [SCRUB-IS-ACKNOWLEDGED-REDACTION] - 2026-09-25
+ * [NEVER] rewrite a record's content without appending the audit.redact acknowledgement that
+ *         binds its original hash to its new content, and never touch a record that is not a
+ *         capture record or a line the redactor left unchanged.
+ * WHY: the credentials found on 2026-09-24 sat in 45 archived segments and the live log. Segments
+ *      are never overwritten ([SEGMENT-IS-NEVER-OVERWRITTEN]); this is the one sanctioned
+ *      exception, because leaving a live Stripe key or a database password in an evidence
+ *      archive forever is worse than an acknowledged edit. Without the acknowledgement the
+ *      verifier would, truthfully, call every scrubbed record altered.
+ * FIX: dry run by default. With apply: under the rotate lock (no rotation moves records while we
+ *      rewrite), each segment is rewritten via temp file and rename only where a line changed,
+ *      the live log under the append lock (appends wait, none is lost), then one audit.redact
+ *      record per 100 rewrites names each original hash and its new content hash
+ *      ([REDACTION-IS-A-CHAINED-RECORD]). Running it again changes nothing.
+ */
+export function scrubAuditLog(opts) {
+    const report = { applied: false, refusedReason: null, files: [], redactedRecords: 0, counts: {}, acknowledgements: [] };
+    if (opts.apply && !opts.reason?.trim())
+        return { ...report, refusedReason: "a reason is required to apply a scrub" };
+    const tally = (name, s) => {
+        report.files.push({ name, records: s.records, redacted: s.redacted.length });
+        report.redactedRecords += s.redacted.length;
+        for (const [k, n] of Object.entries(s.counts))
+            report.counts[k] = (report.counts[k] ?? 0) + n;
+    };
+    // Acknowledge each file right after it is rewritten, so a scrub that stops halfway leaves no
+    // rewritten record unacknowledged.
+    const acknowledge = (entries) => {
+        for (let i = 0; i < entries.length; i += SCRUB_ACK_BATCH) {
+            report.acknowledgements.push(appendAudit("audit.redact", { reason: opts.reason.trim(), redacted: entries.slice(i, i + SCRUB_ACK_BATCH) }, opts.actor ?? "system"));
+        }
+    };
+    const run = () => {
+        const adir = archiveDir();
+        for (const name of listSegments()) {
+            const path = join(adir, name);
+            const s = scrubText(readFileSync(path, "utf-8"), opts.redact);
+            tally(name, s);
+            if (opts.apply && s.redacted.length > 0) {
+                const tmp = join(adir, `.${name}.scrub.tmp`);
+                writeFileAndSync(tmp, s.body);
+                renameSync(tmp, path);
+                acknowledge(s.redacted);
+            }
+        }
+        const live = auditPath();
+        if (existsSync(live)) {
+            if (!opts.apply) {
+                tally("audit.log", scrubText(readFileSync(live, "utf-8"), opts.redact));
+            }
+            else {
+                let liveAcks = [];
+                const release = acquireLockSync();
+                try {
+                    const s = scrubText(readFileSync(live, "utf-8"), opts.redact);
+                    tally("audit.log", s);
+                    if (s.redacted.length > 0) {
+                        const tmp = join(auditDir(), ".audit.log.scrub.tmp");
+                        writeFileAndSync(tmp, s.body);
+                        renameSync(tmp, live);
+                        liveAcks = s.redacted;
+                    }
+                }
+                finally {
+                    release();
+                }
+                acknowledge(liveAcks); // after the release: appendAudit takes the same lock
+            }
+        }
+        return { ...report, applied: !!opts.apply };
+    };
+    if (!opts.apply)
+        return run();
+    const lock = acquireRotateLock();
+    if ("heldMs" in lock)
+        return { ...report, refusedReason: "a rotation is in progress; try again in a minute" };
+    try {
+        return run();
+    }
+    finally {
+        lock.release();
+    }
+}
 export function filterByRange(records, since, until) {
     return records.filter((r) => {
         if (since && r.ts < since)

package/dist/cli-commands.js

@@ -26,6 +26,8 @@ export const KNOWN_COMMANDS = [
     "audit-export",
     "audit-rotate",
     "audit-redact-ack",
+    "audit-restore",
+    "audit-scrub",
     "audit-verify",
     "servers",
     "session-gate",