knodin 0.7.6 → 0.8.3

package/dist/src/diagnostics.js

@@ -0,0 +1,1476 @@
+import child_process from "node:child_process";
+import crypto from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import zlib from "node:zlib";
+import { compareBytes } from "./compare.js";
+const CONFIG_PATH = ".knodin/diagnostics/config.json";
+const JOURNAL_PATH = ".knodin/diagnostics/events.jsonl";
+const JOURNAL_LOCK_PATH = ".knodin/diagnostics/events.lock";
+/**
+ * How long a helper round trip may take before it is treated as wedged.
+ *
+ * The helper is spawned as compiled JavaScript in a release install, where 2s is
+ * generous for start-up plus a pipe exchange. Running from source it is spawned
+ * as TypeScript through tsx, which must boot and transpile before it can answer
+ * — seconds of legitimate start-up that has nothing to do with a hung helper,
+ * and more again under a loaded machine or coverage instrumentation. Budgeting
+ * per runtime keeps the shipped bound at 2s instead of making production wait
+ * for a cost it never pays.
+ */
+const HELPER_DEADLINE_MS = import.meta.url.endsWith(".ts") ? 30_000 : 2_000;
+/** Lock-free markers for records that could not be written. See DROPPED_PATH use. */
+const DROPPED_PATH = ".knodin/diagnostics/dropped";
+/**
+ * Poll interval while contending for the journal lock.
+ *
+ * The retry budget below is counted in ATTEMPTS, not wall-clock, and that is
+ * deliberate: an attempt is not just this sleep but several stat/read/parse
+ * operations, so each one costs more precisely when the lock is contended. The
+ * budget therefore stretches automatically under load, which is when patience is
+ * needed. Replacing it with a fixed deadline, or spacing retries with
+ * exponential backoff, both measurably LOSE more records — a freed lock must be
+ * claimed immediately, and fewer attempts means fewer chances.
+ */
+const JOURNAL_LOCK_POLL_MS = 5;
+/**
+ * Retry ceiling for the acquisition loop, which is 0-based and throws at
+ * `attempt >= JOURNAL_LOCK_ATTEMPTS`. So this is the index of the last attempt,
+ * not a count: acquisition is tried 41 times and waits 40 times between them.
+ * Stated because "attempts before giving up" reads as a count and invites an
+ * off-by-one the next time someone tunes it.
+ */
+const JOURNAL_LOCK_ATTEMPTS = 40;
+const PREVIEW_STORES = [
+    ".knodin/diagnostics/previews-a.json",
+    ".knodin/diagnostics/previews-b.json",
+];
+const DEFAULT_RETENTION_DAYS = 14;
+const MAX_RETENTION_DAYS = 365;
+const MAX_RECORDS = 500;
+const MAX_MCP_LOG_BYTES = 256 * 1024;
+const MAX_BUNDLE_BYTES = 512 * 1024;
+const MAX_BUNDLE_RECORDS = 32;
+const MAX_JOURNAL_BYTES = 2 * 1024 * 1024;
+const MAX_PREVIEW_COUNT = 8;
+const MAX_PREVIEW_AGE_MS = 7 * 24 * 60 * 60 * 1000;
+const MAX_PREVIEW_BYTES = 2 * 1024 * 1024;
+const OPERATIONS = new Set([
+    "init",
+    "configure",
+    "index",
+    "doctor",
+    "status",
+    "wait",
+    "repair",
+    "serve",
+    "context",
+    "explain",
+    "review",
+    "map",
+    "search",
+    "query",
+    "rename",
+    "wiki",
+    "visualize",
+    "pack",
+    "compress",
+    "prs",
+    "worktrees",
+    "telemetry",
+    "diagnostics",
+    "system",
+    "repos",
+    "repositories",
+    "remote",
+    "update",
+    "docs",
+    "unknown",
+]);
+function containedPath(repoPath, requested, purpose) {
+    const repo = fs.realpathSync(repoPath);
+    const target = path.resolve(repo, requested);
+    if (target !== repo && !target.startsWith(`${repo}${path.sep}`))
+        throw new Error(`knodin diagnostics ${purpose}: path must stay inside the repository`);
+    let cursor = repo;
+    for (const segment of path.relative(repo, target).split(path.sep).filter(Boolean)) {
+        cursor = path.join(cursor, segment);
+        try {
+            if (fs.lstatSync(cursor).isSymbolicLink())
+                throw new Error(`knodin diagnostics ${purpose}: refusing symlinked path`);
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                break;
+            throw error;
+        }
+    }
+    return { repo, target };
+}
+function helperPipeDescriptor(stream) {
+    const descriptor = stream._handle?.fd;
+    if (typeof descriptor !== "number")
+        throw new Error("knodin diagnostics helper pipe unavailable");
+    return descriptor;
+}
+function waitForPipe(deadline) {
+    if (Date.now() >= deadline)
+        throw new Error("knodin diagnostics helper deadline exceeded");
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 2);
+}
+function writeHelperPayload(descriptor, payload, deadline) {
+    let offset = 0;
+    while (offset < payload.length) {
+        try {
+            offset += fs.writeSync(descriptor, payload, offset, payload.length - offset);
+        }
+        catch (error) {
+            if (error.code === "EAGAIN") {
+                waitForPipe(deadline);
+                continue;
+            }
+            throw error;
+        }
+    }
+}
+function readPipeMessage(session, deadline) {
+    for (;;) {
+        const newline = session.outputBuffer.indexOf(10);
+        if (newline >= 0) {
+            const line = session.outputBuffer.subarray(0, newline);
+            session.outputBuffer = session.outputBuffer.subarray(newline + 1);
+            if (line.byteLength > session.protocolLimit)
+                throw new Error("knodin diagnostics helper protocol overflow");
+            try {
+                return JSON.parse(line.toString("utf8"));
+            }
+            catch {
+                throw new Error("knodin diagnostics helper emitted malformed protocol data");
+            }
+        }
+        try {
+            const chunk = Buffer.allocUnsafe(4096);
+            const count = fs.readSync(session.output, chunk, 0, chunk.length, null);
+            if (count === 0)
+                throw new Error("knodin diagnostics helper closed its protocol pipe");
+            session.outputBuffer = Buffer.concat([session.outputBuffer, chunk.subarray(0, count)]);
+            if (session.outputBuffer.byteLength > session.protocolLimit)
+                throw new Error("knodin diagnostics helper protocol overflow");
+        }
+        catch (error) {
+            if (error.code !== "EAGAIN")
+                throw error;
+            waitForPipe(deadline);
+        }
+    }
+}
+const appendSessions = new Map();
+function appendWithSession(session, payload, deadline) {
+    if (session.idle)
+        clearTimeout(session.idle);
+    const sequence = ++session.sequence;
+    const frame = Buffer.allocUnsafe(8 + payload.byteLength);
+    frame.writeUInt32BE(sequence, 0);
+    frame.writeUInt32BE(payload.byteLength, 4);
+    payload.copy(frame, 8);
+    writeHelperPayload(session.input, frame, deadline);
+    const receipt = readPipeMessage(session, deadline);
+    if (receipt.type === "ERROR")
+        throw new Error(typeof receipt.message === "string" ? receipt.message : "diagnostics helper failed");
+    if (receipt.version !== 1 ||
+        receipt.type !== "RECEIPT" ||
+        receipt.dev !== session.ready.dev ||
+        receipt.ino !== session.ready.ino ||
+        receipt.nonce !== session.nonce ||
+        receipt.sequence !== sequence ||
+        receipt.bytes !== payload.byteLength)
+        throw new Error("knodin diagnostics helper receipt mismatch");
+    session.idle = setTimeout(() => {
+        if (appendSessions.get(session.key) !== session)
+            return;
+        appendSessions.delete(session.key);
+        session.child.kill("SIGTERM");
+        session.child.stdin?.destroy();
+        session.child.stdout?.destroy();
+    }, 750);
+    session.idle.unref();
+    return payload.byteLength;
+}
+export function repositoryBoundWrite(repo, target, data, mode, maxBytes, maxAgeMs = 0, onBound) {
+    const requestedRepo = path.resolve(repo);
+    const requestedTarget = path.resolve(target);
+    if (requestedTarget === requestedRepo ||
+        !requestedTarget.startsWith(`${requestedRepo}${path.sep}`))
+        throw new Error("knodin repository-bound write escaped the repository");
+    const boundRepo = fs.realpathSync(repo);
+    const normalizedTarget = path.resolve(boundRepo, path.relative(requestedRepo, requestedTarget));
+    const relativeTarget = path.relative(boundRepo, normalizedTarget);
+    const isJournalLock = relativeTarget === JOURNAL_LOCK_PATH;
+    const root = fs.statSync(boundRepo);
+    containedPath(boundRepo, normalizedTarget, "write");
+    if (mode === "append") {
+        try {
+            const observed = fs.lstatSync(normalizedTarget);
+            if (!observed.isFile() || observed.isSymbolicLink() || observed.nlink !== 1)
+                throw new Error("knodin repository-bound append target is not a private file");
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+        }
+    }
+    const payload = Buffer.isBuffer(data) ? data : Buffer.from(data);
+    if (payload.byteLength > maxBytes)
+        throw new Error("knodin diagnostics write exceeds its bound");
+    const nonce = crypto.randomBytes(16).toString("hex");
+    const appendKey = `${root.dev}:${root.ino}:${normalizedTarget}`;
+    if (mode === "append") {
+        const existing = appendSessions.get(appendKey);
+        if (existing?.child.exitCode === null) {
+            try {
+                return appendWithSession(existing, payload, Date.now() + HELPER_DEADLINE_MS);
+            }
+            catch (error) {
+                existing.child.kill("SIGKILL");
+                appendSessions.delete(appendKey);
+                throw error;
+            }
+        }
+        appendSessions.delete(appendKey);
+    }
+    const extension = import.meta.url.endsWith(".ts") ? "ts" : "js";
+    const entry = fileURLToPath(new URL(extension === "ts" ? "./diagnostics-write-helper.ts" : "../src/diagnostics-write-helper.js", import.meta.url));
+    const runtimeArgs = extension === "ts" ? ["--import", fileURLToPath(import.meta.resolve("tsx"))] : [];
+    if (!isJournalLock &&
+        extension === "ts" &&
+        process.env.KNODIN_DIAGNOSTICS_TEST_FIXTURES === "1" &&
+        process.env.KNODIN_DIAGNOSTICS_TEST_PRESPAWN_SWAP_TO) {
+        const parentPath = path.dirname(target);
+        fs.renameSync(parentPath, `${parentPath}-displaced`);
+        fs.symlinkSync(process.env.KNODIN_DIAGNOSTICS_TEST_PRESPAWN_SWAP_TO, parentPath);
+    }
+    if (!isJournalLock &&
+        extension === "ts" &&
+        process.env.KNODIN_DIAGNOSTICS_TEST_FIXTURES === "1" &&
+        process.env.KNODIN_DIAGNOSTICS_TEST_PREPARENT_SWAP_TO) {
+        fs.renameSync(boundRepo, `${boundRepo}-displaced`);
+        fs.symlinkSync(process.env.KNODIN_DIAGNOSTICS_TEST_PREPARENT_SWAP_TO, boundRepo);
+    }
+    const faultFixturesEnabled = extension === "ts" && process.env.KNODIN_DIAGNOSTICS_TEST_FIXTURES === "1";
+    const componentSwapTarget = isJournalLock
+        ? (process.env.KNODIN_DIAGNOSTICS_TEST_LOCK_COMPONENT_SWAP_TO ?? "")
+        : (process.env.KNODIN_DIAGNOSTICS_TEST_COMPONENT_SWAP_TO ?? "");
+    const child = child_process.spawn(process.execPath, [
+        ...runtimeArgs,
+        entry,
+        String(root.dev),
+        String(root.ino),
+        relativeTarget,
+        mode,
+        String(maxBytes),
+        String(payload.byteLength),
+        nonce,
+        String(maxAgeMs),
+        extension === "ts" &&
+            process.env.KNODIN_DIAGNOSTICS_TEST_FIXTURES === "1" &&
+            (!isJournalLock ||
+                Boolean(process.env.KNODIN_DIAGNOSTICS_TEST_LOCK_COMPONENT_SWAP_TO) ||
+                process.env.KNODIN_DIAGNOSTICS_TEST_LOCK_SUCCESSOR === "1" ||
+                Boolean(process.env.KNODIN_DIAGNOSTICS_TEST_POST_READY_PARENT_SWAP_TO) ||
+                Boolean(process.env.KNODIN_DIAGNOSTICS_TEST_POST_READY_ROOT_SWAP_TO) ||
+                Boolean(process.env.KNODIN_DIAGNOSTICS_TEST_POST_PUBLISH_TARGET_SWAP_TO))
+            ? "enabled"
+            : "",
+        faultFixturesEnabled ? componentSwapTarget : "",
+        extension === "ts" && process.env.KNODIN_DIAGNOSTICS_TEST_FIXTURES === "1" && !isJournalLock
+            ? (process.env.KNODIN_DIAGNOSTICS_TEST_DELETE_SWAP_TO ?? "")
+            : "",
+    ], { cwd: boundRepo, stdio: ["pipe", "pipe", "ignore"] });
+    if (mode === "append") {
+        child.unref();
+        child.stdin?.unref?.();
+        child.stdout?.unref?.();
+    }
+    const deadline = Date.now() + HELPER_DEADLINE_MS;
+    try {
+        if (!child.stdin)
+            throw new Error("knodin diagnostics helper protocol unavailable");
+        const input = helperPipeDescriptor(child.stdin);
+        if (!child.stdout)
+            throw new Error("knodin diagnostics helper error pipe unavailable");
+        const output = helperPipeDescriptor(child.stdout);
+        const bootstrap = {
+            child,
+            input,
+            output,
+            outputBuffer: Buffer.alloc(0),
+            protocolLimit: mode === "read" ? Math.ceil((maxBytes * 4) / 3) + 4096 : 4096,
+            key: appendKey,
+            nonce,
+            ready: {},
+            sequence: 0,
+        };
+        const ready = readPipeMessage(bootstrap, deadline);
+        if (ready.type === "ERROR")
+            throw new Error(typeof ready.message === "string" ? ready.message : "diagnostics helper failed");
+        if (ready.version !== 1 ||
+            ready.type !== "READY" ||
+            ready.rootDev !== root.dev ||
+            ready.rootIno !== root.ino ||
+            ready.nonce !== nonce)
+            throw new Error("knodin diagnostics helper READY identity mismatch");
+        if (mode === "append") {
+            const session = {
+                ...bootstrap,
+                outputBuffer: bootstrap.outputBuffer,
+                ready,
+            };
+            appendSessions.set(appendKey, session);
+            child.once("exit", () => {
+                if (appendSessions.get(appendKey) === session)
+                    appendSessions.delete(appendKey);
+                child.stdin?.destroy();
+                child.stdout?.destroy();
+            });
+            return appendWithSession(session, payload, deadline);
+        }
+        writeHelperPayload(input, payload, deadline);
+        const receipt = readPipeMessage(bootstrap, deadline);
+        if (receipt.type === "ERROR")
+            throw new Error(typeof receipt.message === "string" ? receipt.message : "diagnostics helper failed");
+        if (receipt.version !== 1 ||
+            receipt.type !== "RECEIPT" ||
+            receipt.dev !== ready.dev ||
+            receipt.ino !== ready.ino ||
+            receipt.nonce !== nonce ||
+            (mode !== "read" && receipt.bytes !== payload.byteLength))
+            throw new Error("knodin diagnostics helper receipt mismatch");
+        if (mode === "create" || mode === "replace" || mode === "read") {
+            if (!Number.isSafeInteger(receipt.targetDev) || !Number.isSafeInteger(receipt.targetIno))
+                throw new Error("knodin diagnostics helper target identity mismatch");
+            onBound?.({ dev: receipt.targetDev, ino: receipt.targetIno });
+        }
+        child.stdin.end();
+        if (mode === "read") {
+            if (typeof receipt.data !== "string" || typeof receipt.bytes !== "number")
+                throw new Error("knodin diagnostics helper read receipt mismatch");
+            const content = Buffer.from(receipt.data, "base64");
+            if (content.byteLength !== receipt.bytes || content.byteLength > maxBytes)
+                throw new Error("knodin diagnostics helper read bound mismatch");
+            return content;
+        }
+        return mode === "delete" && typeof receipt.deletedBytes === "number"
+            ? receipt.deletedBytes
+            : payload.byteLength;
+    }
+    finally {
+        if (mode !== "append" && child.exitCode === null)
+            child.kill("SIGKILL");
+    }
+}
+function privateDescriptorReplace(repo, target, data) {
+    repositoryBoundWrite(repo, target, data, "replace", MAX_PREVIEW_BYTES / 2);
+}
+function atomicPrivateWrite(repo, target, data) {
+    repositoryBoundWrite(repo, target, data, "replace", MAX_JOURNAL_BYTES);
+}
+function privateCreate(repo, target, data) {
+    repositoryBoundWrite(repo, target, data, "create", MAX_BUNDLE_BYTES);
+}
+function privateDelete(repo, target, token, kind = "file") {
+    let observed;
+    try {
+        observed = fs.lstatSync(target);
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return null;
+        throw error;
+    }
+    if (observed.isSymbolicLink() ||
+        (kind === "file" ? !observed.isFile() || observed.nlink !== 1 : !observed.isDirectory()))
+        throw new Error("knodin diagnostics delete: target is not a private file");
+    return repositoryBoundWrite(repo, target, JSON.stringify({ dev: observed.dev, ino: observed.ino, token, kind }), "delete", 4096);
+}
+function readPrivateFile(repo, target, maxBytes, purpose, onOpen) {
+    try {
+        return repositoryBoundWrite(repo, target, Buffer.alloc(0), "read", maxBytes, 0, onOpen);
+    }
+    catch (error) {
+        throw new Error(`knodin diagnostics ${purpose}: ${error.message}`);
+    }
+}
+function withJournalLock(repo, run) {
+    const { target: lock } = containedPath(repo, JOURNAL_LOCK_PATH, "record");
+    const ownerToken = crypto.randomBytes(16).toString("hex");
+    let ownedIdentity;
+    for (let attempt = 0;; attempt++) {
+        try {
+            repositoryBoundWrite(repo, lock, `${JSON.stringify({ token: ownerToken, acquiredAt: new Date().toISOString() })}\n`, "create", 4096, 0, (identity) => (ownedIdentity = identity));
+            const observed = fs.lstatSync(lock);
+            let readIdentity;
+            const owner = JSON.parse(readPrivateFile(repo, lock, 4096, "journal lock", (identity) => {
+                readIdentity = identity;
+            }).toString("utf8"));
+            if (!observed.isFile() ||
+                observed.nlink !== 1 ||
+                !ownedIdentity ||
+                !readIdentity ||
+                observed.dev !== ownedIdentity.dev ||
+                observed.ino !== ownedIdentity.ino ||
+                readIdentity.dev !== ownedIdentity.dev ||
+                readIdentity.ino !== ownedIdentity.ino ||
+                owner.token !== ownerToken)
+                throw new Error("knodin diagnostics record: unsafe journal lock");
+            break;
+        }
+        catch (error) {
+            if (import.meta.url.endsWith(".ts") &&
+                process.env.KNODIN_DIAGNOSTICS_TEST_FIXTURES === "1" &&
+                process.env.KNODIN_DIAGNOSTICS_TEST_LOCK_COMPONENT_SWAP_TO)
+                throw error;
+            try {
+                const first = fs.lstatSync(lock);
+                if (first.isDirectory() && Date.now() - first.mtimeMs > 30_000) {
+                    const legacyOwnerPath = containedPath(repo, path.join(JOURNAL_LOCK_PATH, "owner.json"), "legacy journal lock").target;
+                    const legacyOwner = JSON.parse(readPrivateFile(repo, legacyOwnerPath, 4096, "legacy journal lock").toString("utf8"));
+                    if (typeof legacyOwner.token === "string" &&
+                        /^[a-f0-9]{32}$/.test(legacyOwner.token) &&
+                        typeof legacyOwner.acquiredAt === "string" &&
+                        Date.now() - Date.parse(legacyOwner.acquiredAt) > 30_000) {
+                        privateDelete(repo, lock, legacyOwner.token, "directory");
+                        continue;
+                    }
+                }
+                if (!first.isFile() || first.nlink !== 1)
+                    throw error;
+                const owner = JSON.parse(readPrivateFile(repo, lock, 4096, "journal lock").toString("utf8"));
+                const acquired = typeof owner.acquiredAt === "string" ? Date.parse(owner.acquiredAt) : 0;
+                if (typeof owner.token === "string" &&
+                    /^[a-f0-9]{32}$/.test(owner.token) &&
+                    Number.isFinite(acquired) &&
+                    Date.now() - acquired > 30_000) {
+                    const second = fs.lstatSync(lock);
+                    if (first.dev === second.dev && first.ino === second.ino) {
+                        privateDelete(repo, lock, owner.token);
+                        continue;
+                    }
+                }
+            }
+            catch {
+                // A malformed or partially-created owner is busy until its bounded retry expires.
+            }
+            if (attempt >= JOURNAL_LOCK_ATTEMPTS)
+                throw new Error("knodin diagnostics record: journal is busy");
+            Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, JOURNAL_LOCK_POLL_MS);
+        }
+    }
+    try {
+        return run();
+    }
+    finally {
+        try {
+            privateDelete(repo, lock, ownerToken);
+        }
+        catch {
+            // Recording is best-effort; stale-lock recovery handles interrupted cleanup.
+        }
+    }
+}
+function validRetention(days) {
+    if (!Number.isInteger(days) || days < 1 || days > MAX_RETENTION_DAYS)
+        throw new Error(`knodin diagnostics: retention days must be an integer from 1 to ${MAX_RETENTION_DAYS}`);
+    return days;
+}
+function readConfig(repoPath) {
+    const { repo, target } = containedPath(repoPath, CONFIG_PATH, "status");
+    if (!fs.existsSync(target))
+        return null;
+    try {
+        const value = JSON.parse(readPrivateFile(repo, target, 64 * 1024, "config").toString("utf8"));
+        if (value.schemaVersion !== 1 || value.enabled !== true)
+            return null;
+        validRetention(value.retentionDays);
+        if (!Number.isInteger(value.generation) || value.generation < 1)
+            value.generation = 1;
+        if (typeof value.sessionId !== "string" || !/^[a-f0-9]{32}$/.test(value.sessionId))
+            value.sessionId = crypto
+                .createHash("sha256")
+                .update(value.enabledAt)
+                .digest("hex")
+                .slice(0, 32);
+        return value;
+    }
+    catch {
+        return null;
+    }
+}
+function safeLabel(value, fallback) {
+    return value && /^[A-Za-z0-9][A-Za-z0-9:._-]{0,63}$/.test(value) ? value : fallback;
+}
+function errorCode(error) {
+    const code = error?.code;
+    return typeof code === "string" &&
+        /^(?:E[A-Z0-9]+|ERR_[A-Z0-9_]+|SQLITE_[A-Z0-9_]+|KNODIN_[A-Z0-9_]+)$/.test(code)
+        ? code
+        : null;
+}
+function scrubText(raw, repo) {
+    let value = raw;
+    let redactions = 0;
+    const replace = (pattern, replacement) => {
+        value = value.replace(pattern, () => {
+            redactions++;
+            return replacement;
+        });
+    };
+    for (const exact of [repo, os.homedir()].filter(Boolean).sort((a, b) => b.length - a.length))
+        replace(new RegExp(exact.replace(/[.*+?^${}()|[\]\\]/g, String.raw `\$&`), "g"), "<path>");
+    replace(/\b(?:ghp|github_pat|sk|xox[baprs])-[-A-Za-z0-9_]{10,}\b/g, "<secret>");
+    replace(/\b(?:password|passwd|token|secret|api[_-]?key|authorization)\s*[=:]\s*[^\s,;]+/gi, "$1=<secret>");
+    replace(/\b[A-Z]:\\(?:[^\s<>:"|?*]+\\)*[^\s<>:"|?*]*/g, "<path>");
+    replace(/(?:^|[\s('"`])\/(?:[^\s)'"`]+\/)*[^\s)'"`]*/g, "<path>");
+    replace(/\b(?:[A-Za-z0-9_.-]+\/)+(?:[A-Za-z0-9_.-]+\.[A-Za-z0-9]{1,12})\b/g, "<path>");
+    replace(/\b[A-Za-z0-9_.+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}\b/g, "<email>");
+    return { value: value.slice(0, 2_000), redactions };
+}
+function sanitizeStack(error, repo) {
+    return (error.stack ?? "")
+        .split(/\r?\n/)
+        .slice(1, 9)
+        .map((line) => `at ${line.includes(repo) ? "<repository>" : "<runtime>"}`);
+}
+function readEvents(repoPath, retentionDays, since) {
+    const { target } = containedPath(repoPath, JOURNAL_PATH, "read");
+    if (!fs.existsSync(target))
+        return [];
+    const cutoff = Math.max(Date.now() - validRetention(retentionDays) * 86_400_000, since?.getTime() ?? Number.NEGATIVE_INFINITY);
+    let journal;
+    try {
+        journal = readPrivateFile(fs.realpathSync(repoPath), target, MAX_JOURNAL_BYTES, "read");
+    }
+    catch (error) {
+        if (error instanceof Error && /exceeds its safety limit/.test(error.message))
+            throw new Error("knodin diagnostics read: journal exceeds the 2 MiB safety limit");
+        throw error;
+    }
+    return journal
+        .toString("utf8")
+        .split(/\r?\n/)
+        .filter(Boolean)
+        .flatMap((line) => {
+        try {
+            const raw = JSON.parse(line);
+            const error = raw.error;
+            if (raw.schemaVersion !== 1 ||
+                typeof raw.at !== "string" ||
+                !Number.isFinite(Date.parse(raw.at)) ||
+                Date.parse(raw.at) < cutoff ||
+                typeof raw.correlationId !== "string" ||
+                !/^[a-f0-9]{16}$/.test(raw.correlationId) ||
+                !["cli", "mcp", "lifecycle"].includes(raw.surface) ||
+                typeof raw.operation !== "string" ||
+                !OPERATIONS.has(raw.operation) ||
+                typeof raw.phase !== "string" ||
+                safeLabel(raw.phase, "") !== raw.phase ||
+                !error ||
+                typeof error.name !== "string" ||
+                safeLabel(error.name, "") !== error.name ||
+                (error.code !== null && errorCode(error) === null) ||
+                typeof error.messageFingerprint !== "string" ||
+                !/^[a-f0-9]{16}$/.test(error.messageFingerprint) ||
+                !Array.isArray(error.stack) ||
+                error.stack.some((line) => line !== "at <repository>" && line !== "at <runtime>"))
+                return [];
+            const record = {
+                schemaVersion: 1,
+                at: raw.at,
+                correlationId: raw.correlationId,
+                surface: raw.surface,
+                operation: raw.operation,
+                phase: raw.phase,
+                error: {
+                    name: error.name,
+                    code: error.code,
+                    messageFingerprint: error.messageFingerprint,
+                    stack: error.stack.slice(0, 8),
+                },
+            };
+            return [record];
+        }
+        catch {
+            return [];
+        }
+    })
+        .slice(-MAX_RECORDS);
+}
+export function enableDiagnostics(repoPath, retentionDays = DEFAULT_RETENTION_DAYS) {
+    const { repo, target } = containedPath(repoPath, CONFIG_PATH, "enable");
+    withJournalLock(repo, () => {
+        const previous = readConfig(repo);
+        const config = {
+            schemaVersion: 1,
+            enabled: true,
+            retentionDays: validRetention(retentionDays),
+            enabledAt: new Date().toISOString(),
+            generation: (previous?.generation ?? 0) + 1,
+            sessionId: crypto.randomBytes(16).toString("hex"),
+        };
+        atomicPrivateWrite(repo, target, `${JSON.stringify(config, null, 2)}\n`);
+    });
+    return { ...diagnosticsStatus(repo), message: "Local diagnostics enabled; nothing is uploaded." };
+}
+export function disableDiagnostics(repoPath) {
+    const { repo, target } = containedPath(repoPath, CONFIG_PATH, "disable");
+    withJournalLock(repo, () => {
+        privateDelete(repo, target);
+    });
+    return {
+        ...diagnosticsStatus(repo),
+        message: "Local diagnostics disabled; retained events were not deleted.",
+    };
+}
+export function diagnosticsStatus(repoPath) {
+    const config = readConfig(repoPath);
+    const retentionDays = config?.retentionDays ?? DEFAULT_RETENTION_DAYS;
+    let events = [];
+    let journal = {
+        status: "healthy",
+        issue: null,
+    };
+    try {
+        events = readEvents(repoPath, retentionDays);
+    }
+    catch (error) {
+        journal = {
+            status: "unavailable",
+            issue: error instanceof Error ? error.message : "diagnostic journal is unavailable",
+        };
+    }
+    return {
+        schemaVersion: 1,
+        enabled: config !== null,
+        localOnly: true,
+        uploaded: false,
+        retentionDays,
+        records: events.length,
+        /**
+         * Failures that could not be written to the journal at all — for ANY
+         * reason. Lock contention is the expected one, but the marker is written
+         * from a bare `catch` around the whole write, so a read error, a malformed
+         * journal, or a full disk lands here too. Deliberately broad: the point is
+         * that nothing is lost silently, and narrowing it to lock-busy would let
+         * the other cases vanish exactly as before.
+         *
+         * Non-zero means `records` is an undercount — without this the two are
+         * indistinguishable.
+         */
+        droppedRecords: droppedRecordCount(repoPath),
+        oldestAt: events[0]?.at ?? null,
+        newestAt: events.at(-1)?.at ?? null,
+        journal,
+    };
+}
+export function recordDiagnosticFailure(repoPath, input) {
+    try {
+        const repo = fs.realpathSync(repoPath);
+        const observed = readConfig(repo);
+        if (!observed)
+            return { recorded: false, reason: "disabled" };
+        return withJournalLock(repo, () => {
+            const config = readConfig(repo);
+            if (!config)
+                return { recorded: false, reason: "disabled" };
+            if (config.sessionId !== observed.sessionId || config.generation !== observed.generation)
+                return { recorded: false, reason: "state-changed" };
+            const error = input.error instanceof Error ? input.error : new Error(String(input.error));
+            const message = scrubText(error.message, repo).value;
+            const event = {
+                schemaVersion: 1,
+                at: new Date().toISOString(),
+                correlationId: crypto.randomBytes(8).toString("hex"),
+                surface: input.surface,
+                operation: OPERATIONS.has(input.operation) ? input.operation : "unknown",
+                phase: safeLabel(input.phase, "operation"),
+                error: {
+                    name: safeLabel(error.name, "Error"),
+                    code: errorCode(input.error),
+                    messageFingerprint: crypto
+                        .createHash("sha256")
+                        .update(message)
+                        .digest("hex")
+                        .slice(0, 16),
+                    stack: sanitizeStack(error, repo),
+                },
+            };
+            const events = [...readEvents(repo, config.retentionDays), event].slice(-MAX_RECORDS);
+            const { target } = containedPath(repo, JOURNAL_PATH, "record");
+            atomicPrivateWrite(repo, target, `${events.map((record) => JSON.stringify(record)).join("\n")}\n`);
+            return { recorded: true, correlationId: event.correlationId };
+        });
+    }
+    catch {
+        // Every caller discards this return value, so a dropped record used to
+        // vanish without trace: the count in `status` was the only evidence, and it
+        // cannot distinguish "nothing failed" from "the failure was lost". Leave a
+        // durable marker so the two are always distinguishable.
+        noteDroppedRecord(repoPath);
+        return { recorded: false, reason: "unavailable" };
+    }
+}
+/**
+ * Records that a diagnostic could not be written.
+ *
+ * Cannot take the journal lock — failing to acquire it is precisely why we are
+ * here — so each dropping process writes its own uniquely named marker into a
+ * directory. Concurrent writers therefore never collide and no update can be
+ * lost, which is the property the shared journal could not offer under
+ * contention. Best-effort by necessity: if even this fails there is nowhere left
+ * to report, and throwing would turn a lost record into a crashed command.
+ */
+function noteDroppedRecord(repoPath) {
+    try {
+        const { repo, target } = containedPath(repoPath, DROPPED_PATH, "record");
+        fs.mkdirSync(target, { recursive: true, mode: 0o700 });
+        const marker = containedPath(repo, path.join(DROPPED_PATH, `${process.pid}-${crypto.randomBytes(8).toString("hex")}`), "record").target;
+        atomicPrivateWrite(repo, marker, `${new Date().toISOString()}\n`);
+    }
+    catch {
+        // Nowhere left to report; never escalate a lost record into a failure.
+    }
+}
+/** Count of records that were dropped rather than written. */
+function droppedRecordCount(repoPath) {
+    try {
+        const { target } = containedPath(repoPath, DROPPED_PATH, "status");
+        return fs.readdirSync(target).length;
+    }
+    catch {
+        return 0;
+    }
+}
+export function clearDiagnostics(repoPath) {
+    const { repo, target } = containedPath(repoPath, JOURNAL_PATH, "clear");
+    // Drop markers describe the journal being cleared, so they go with it.
+    try {
+        fs.rmSync(containedPath(repo, DROPPED_PATH, "clear").target, {
+            recursive: true,
+            force: true,
+        });
+    }
+    catch {
+        // Clearing must stay the recovery path even if markers are unreadable.
+    }
+    return withJournalLock(repo, () => {
+        if (!fs.existsSync(target))
+            return { removed: false, records: 0, bytes: 0 };
+        let records = null;
+        try {
+            records = readEvents(repo, MAX_RETENTION_DAYS).length;
+        }
+        catch {
+            // Deletion must remain the recovery path for an unreadable or oversized journal.
+        }
+        const bytes = privateDelete(repo, target);
+        if (bytes === null)
+            return { removed: false, records: 0, bytes: 0 };
+        const config = readConfig(repo);
+        if (config) {
+            atomicPrivateWrite(repo, containedPath(repo, CONFIG_PATH, "clear").target, `${JSON.stringify({ ...config, generation: config.generation + 1 }, null, 2)}\n`);
+        }
+        return { removed: true, records, bytes };
+    });
+}
+function defaultBundlePath() {
+    return `.knodin/diagnostics/knodin-diagnostics-${new Date().toISOString().replace(/[:.]/g, "-")}.json.gz`;
+}
+const MCP_LOG_PATHS = [".knodin/mcp-reliability.jsonl.1", ".knodin/mcp-reliability.jsonl"];
+const MCP_EVENTS = new Set([
+    "start",
+    "progress",
+    "failure",
+    "cleanup",
+    "success",
+    "restart",
+    "recovery",
+]);
+const MCP_FAILURES = new Set([
+    "cancelled",
+    "client-disconnected",
+    "deadline-exceeded",
+    "graph-locked",
+    "memory-pressure",
+    "worker-crashed",
+    "operation-failed",
+]);
+const BUNDLE_OMISSIONS = [
+    "repository-source-and-diffs",
+    "raw-and-external-paths",
+    "credentials-and-environment",
+    "usernames-and-identities",
+    "command-and-lifecycle-output",
+    "git-remotes-messages-and-arguments",
+    "telemetry-record-fields",
+];
+const UNAVAILABLE_REASONS = new Set([
+    "MCP trace journal is symlinked and was refused",
+    "MCP trace journal exceeds its documented bound",
+    "MCP trace journal could not be read safely",
+    "MCP traces unavailable",
+    "No MCP trace journal exists for this checkout",
+    "Diagnostic failure journal could not be read safely",
+    "Diagnostic journal is unavailable",
+    "Graph health was not supplied or recognized by the local caller",
+    "Repository scale was not supplied or recognized by the local caller",
+]);
+const GRAPH_STATUSES = ["healthy", "repair-needed", "unavailable", "degraded"];
+const FRESHNESS_STATES = ["fresh", "stale", "dirty", "unknown", "unavailable"];
+const COMMIT_RELATIONS = ["equal", "ahead", "behind", "diverged", "unknown"];
+const LIFECYCLE_STATUSES = ["healthy", "degraded", "unconfigured", "unavailable"];
+const PROCESSOR_STATES = ["idle", "running", "stale", "unavailable"];
+const INSTALLATION_STATUSES = [
+    "healthy",
+    "ready",
+    "attention-required",
+    "repair-needed",
+    "unavailable",
+];
+function safeEnum(value, allowed, fallback = "unknown") {
+    return typeof value === "string" && allowed.includes(value) ? value : fallback;
+}
+function safeCount(value) {
+    return typeof value === "number" && Number.isSafeInteger(value) && value >= 0 ? value : null;
+}
+function recordObject(value) {
+    return value && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : {};
+}
+function child(value, key) {
+    return recordObject(recordObject(value)[key]);
+}
+function readMcpTraces(repo, since) {
+    const records = [];
+    let found = false;
+    try {
+        for (const relative of MCP_LOG_PATHS) {
+            const { target } = containedPath(repo, relative, "preview");
+            if (!fs.existsSync(target))
+                continue;
+            found = true;
+            if (fs.lstatSync(target).isSymbolicLink())
+                return { records: [], unavailable: "MCP trace journal is symlinked and was refused" };
+            if (fs.statSync(target).size > MAX_MCP_LOG_BYTES)
+                return { records: [], unavailable: "MCP trace journal exceeds its documented bound" };
+            for (const line of fs.readFileSync(target, "utf8").split(/\r?\n/).filter(Boolean)) {
+                let raw;
+                try {
+                    raw = recordObject(JSON.parse(line));
+                }
+                catch {
+                    continue;
+                }
+                if (raw.schemaVersion !== 1 ||
+                    typeof raw.at !== "string" ||
+                    !Number.isFinite(Date.parse(raw.at)) ||
+                    Date.parse(raw.at) < since.getTime() ||
+                    typeof raw.requestId !== "string" ||
+                    !/^[-A-Za-z0-9:._]{1,128}$/.test(raw.requestId) ||
+                    typeof raw.traceId !== "string" ||
+                    !/^[-a-fA-F0-9]{8,64}$/.test(raw.traceId) ||
+                    typeof raw.operation !== "string" ||
+                    !OPERATIONS.has(raw.operation) ||
+                    !MCP_EVENTS.has(String(raw.event)) ||
+                    safeCount(raw.deadlineMs) === null)
+                    continue;
+                const trace = {
+                    at: raw.at,
+                    event: String(raw.event),
+                    requestId: raw.requestId,
+                    traceId: raw.traceId,
+                    operation: raw.operation,
+                    deadlineMs: safeCount(raw.deadlineMs),
+                };
+                if (typeof raw.kind === "string" && MCP_FAILURES.has(raw.kind))
+                    trace.kind = raw.kind;
+                for (const key of ["elapsedMs", "sequence"]) {
+                    const count = safeCount(raw[key]);
+                    if (count !== null)
+                        trace[key] = count;
+                }
+                if (typeof raw.predecessorTraceId === "string" &&
+                    /^[-a-fA-F0-9]{8,64}$/.test(raw.predecessorTraceId))
+                    trace.predecessorTraceId = raw.predecessorTraceId;
+                records.push(trace);
+            }
+        }
+    }
+    catch (error) {
+        return {
+            records: [],
+            unavailable: error instanceof Error
+                ? "MCP trace journal could not be read safely"
+                : "MCP traces unavailable",
+        };
+    }
+    return {
+        records: records.slice(-MAX_BUNDLE_RECORDS),
+        unavailable: found ? null : "No MCP trace journal exists for this checkout",
+    };
+}
+function fieldPaths(value, prefix = "$") {
+    if (Array.isArray(value)) {
+        const nested = new Set([`${prefix}[]`]);
+        for (const item of value)
+            for (const field of fieldPaths(item, `${prefix}[]`))
+                nested.add(field);
+        return [...nested].sort(compareBytes);
+    }
+    if (value && typeof value === "object") {
+        const output = [];
+        for (const [key, item] of Object.entries(value)) {
+            const next = `${prefix}.${key}`;
+            output.push(next, ...fieldPaths(item, next));
+        }
+        // Byte order: this field list is recorded in the support-bundle descriptor
+        // and later compared verbatim against a freshly computed one.
+        return [...new Set(output)].sort(compareBytes);
+    }
+    return [];
+}
+function recoveryFor(kind) {
+    switch (kind) {
+        case "graph-locked":
+            return "Wait for the current writer, then run `knodin status`; use `knodin repair` if health is not restored.";
+        case "deadline-exceeded":
+            return "Retry once with a narrower operation, then run `knodin status` if the next request does not succeed.";
+        case "memory-pressure":
+            return "Release local memory, restart the MCP client, and run `knodin status`.";
+        case "worker-crashed":
+        case "client-disconnected":
+            return "Restart the MCP client and run `knodin status`; do not claim recovery until a new request succeeds.";
+        default:
+            return "Run `knodin status`, then follow its repair steps; use `knodin repair` for graph damage.";
+    }
+}
+function renderSupportReport(generatedAt, health, traceRecords, failures) {
+    const traceFailures = traceRecords.filter((record) => record.event === "failure");
+    const recoveries = traceRecords.filter((record) => record.event === "recovery");
+    const reportLines = [
+        "knodin privacy-safe support report",
+        `Generated: ${generatedAt}`,
+        `Graph: ${health.graph.status}; freshness: ${health.graph.freshness.state}; lifecycle: ${health.lifecycle.status}.`,
+        `Recent classified MCP failures: ${traceFailures.length}; diagnostic failures: ${failures.length}.`,
+    ];
+    for (const failure of traceFailures.slice(-10)) {
+        const recovered = recoveries.find((record) => record.predecessorTraceId === failure.traceId);
+        reportLines.push(`Trace ${failure.traceId} / request ${failure.requestId}: ${failure.kind ?? "operation-failed"}; ${recovered
+            ? `next request ${recovered.traceId} recorded recovery.`
+            : "no subsequent recovery is recorded."}`, `Recovery: ${recoveryFor(failure.kind)}`);
+    }
+    if (traceFailures.length === 0)
+        reportLines.push("No classified MCP failure is available. Run `knodin status`; use `knodin repair` only when status reports graph damage.");
+    return `${reportLines.join("\n")}\n`;
+}
+function unavailableFieldSections(health, scale) {
+    const unavailable = [];
+    const healthFields = [
+        ["$.graph.status", health.graph.status],
+        ["$.graph.freshness.state", health.graph.freshness.state],
+        ["$.graph.freshness.commitRelation", health.graph.freshness.commitRelation],
+        ["$.graph.freshness.commitDistance", health.graph.freshness.commitDistance],
+        ["$.lifecycle.status", health.lifecycle.status],
+        ["$.lifecycle.queuedEvents", health.lifecycle.queuedEvents],
+        ["$.lifecycle.processorState", health.lifecycle.processorState],
+        ["$.installation.status", health.installation.status],
+    ];
+    for (const [field, value] of healthFields)
+        if (value === null || value === "unknown" || value === "unavailable")
+            unavailable.push(`health.json: ${field} unavailable`);
+    for (const [field, value] of Object.entries(scale))
+        if (value === null)
+            unavailable.push(`repository-scale.json: $.${field} unavailable`);
+    return unavailable;
+}
+function previewIdentity(value) {
+    return crypto.createHash("sha256").update(JSON.stringify(value)).digest("hex").slice(0, 32);
+}
+export function previewDiagnosticsBundle(repoPath, options = {}) {
+    const repo = fs.realpathSync(repoPath);
+    const sinceHours = options.sinceHours ?? 24;
+    if (!Number.isFinite(sinceHours) || sinceHours <= 0 || sinceHours > 24 * 365)
+        throw new Error("knodin diagnostics preview: --since must be from 1h through 8760h");
+    const generatedAt = options.generatedAt ?? new Date().toISOString();
+    if (!Number.isFinite(Date.parse(generatedAt)))
+        throw new Error("knodin diagnostics preview: invalid generation time");
+    const since = new Date(Date.parse(generatedAt) - sinceHours * 3_600_000);
+    const diagnostics = diagnosticsStatus(repo);
+    let failures = [];
+    let failuresUnavailable = null;
+    try {
+        failures = readEvents(repo, diagnostics.retentionDays, since).slice(-MAX_BUNDLE_RECORDS);
+    }
+    catch {
+        failuresUnavailable = "Diagnostic failure journal could not be read safely";
+    }
+    const traces = readMcpTraces(repo, since);
+    const graph = recordObject(options.graph);
+    const coverage = child(graph, "coverage");
+    const freshness = child(graph, "freshness");
+    const lifecycle = child(graph, "lifecycle");
+    const doctor = recordObject(options.doctor);
+    const graphStatus = safeEnum(graph.status, GRAPH_STATUSES, "unavailable");
+    const lifecycleStatus = safeEnum(lifecycle.status, LIFECYCLE_STATUSES, "unavailable");
+    const installationStatus = safeEnum(doctor.status, INSTALLATION_STATUSES, "unavailable");
+    const health = {
+        graph: {
+            status: options.graph === undefined ? "unavailable" : graphStatus,
+            freshness: {
+                state: safeEnum(freshness.state, FRESHNESS_STATES),
+                commitRelation: safeEnum(freshness.commitRelation, COMMIT_RELATIONS),
+                commitDistance: safeCount(freshness.commitDistance),
+            },
+        },
+        lifecycle: {
+            status: options.graph === undefined ? "unavailable" : lifecycleStatus,
+            queuedEvents: safeCount(lifecycle.queuedEvents),
+            processorState: safeEnum(child(lifecycle, "processor").state, PROCESSOR_STATES, "unavailable"),
+        },
+        installation: { status: options.doctor === undefined ? "unavailable" : installationStatus },
+    };
+    const repositoryScale = {
+        sourceFiles: safeCount(coverage.sourceFiles),
+        indexedFiles: safeCount(coverage.indexedFiles),
+        filesWithSymbols: safeCount(coverage.filesWithSymbols),
+        coveragePercent: typeof coverage.percent === "number" && coverage.percent >= 0 && coverage.percent <= 100
+            ? coverage.percent
+            : null,
+        missingFileCount: Array.isArray(child(graph, "missing").files)
+            ? child(graph, "missing").files.length
+            : null,
+        missingRecordCount: Array.isArray(child(graph, "missing").records)
+            ? child(graph, "missing").records.length
+            : null,
+    };
+    const runtime = {
+        knodin: typeof options.knodinVersion === "string" &&
+            /^\d+\.\d+\.\d+(?:[-+][A-Za-z0-9.-]+)?$/.test(options.knodinVersion)
+            ? options.knodinVersion
+            : "unavailable",
+        node: process.version,
+        platform: process.platform,
+        arch: process.arch,
+    };
+    const report = renderSupportReport(generatedAt, health, traces.records, failures);
+    const files = {
+        "runtime.json": runtime,
+        "health.json": health,
+        "repository-scale.json": repositoryScale,
+        "mcp-traces.json": { records: traces.records },
+        "failures.json": { records: failures },
+    };
+    const unavailableByPath = {};
+    if (traces.unavailable)
+        unavailableByPath["mcp-traces.json"] = traces.unavailable;
+    if (failuresUnavailable || diagnostics.journal.status === "unavailable")
+        unavailableByPath["failures.json"] = failuresUnavailable ?? "Diagnostic journal is unavailable";
+    const graphRecognized = options.graph !== undefined && graphStatus !== "unavailable";
+    const scaleRecognized = graphRecognized && Object.values(repositoryScale).some((value) => value !== null);
+    if (!graphRecognized) {
+        unavailableByPath["health.json"] =
+            "Graph health was not supplied or recognized by the local caller";
+    }
+    if (!scaleRecognized) {
+        unavailableByPath["repository-scale.json"] =
+            "Repository scale was not supplied or recognized by the local caller";
+    }
+    const ordered = [
+        "support-report.txt",
+        "runtime.json",
+        "health.json",
+        "repository-scale.json",
+        "mcp-traces.json",
+        "failures.json",
+    ];
+    const descriptor = (filePath) => {
+        const content = filePath === "support-report.txt" ? report : files[filePath];
+        let retention = "point-in-time snapshot; archive retained until user deletes it";
+        if (filePath === "failures.json")
+            retention = `${diagnostics.retentionDays} days; preview window ${sinceHours} hours`;
+        else if (filePath === "mcp-traces.json")
+            retention = `C89 journal maximum 7 days; preview window ${sinceHours} hours`;
+        return {
+            path: filePath,
+            bytes: Buffer.byteLength(typeof content === "string" ? content : `${JSON.stringify(content, null, 2)}\n`),
+            fields: typeof content === "string" ? ["$.text"] : fieldPaths(content),
+            retention,
+            redaction: ["explicit-allowlist"],
+            unavailable: unavailableByPath[filePath] ?? null,
+        };
+    };
+    const manifestFiles = ordered.map(descriptor);
+    const preview = {
+        schemaVersion: 2,
+        generatedAt,
+        manifest: {
+            schemaVersion: 2,
+            privacy: "explicit-allowlist-local-only",
+            localOnly: true,
+            uploaded: false,
+            maxArchiveBytes: MAX_BUNDLE_BYTES,
+            omissions: [...BUNDLE_OMISSIONS],
+            unavailableSections: [
+                ...manifestFiles
+                    .filter((file) => file.unavailable !== null)
+                    .map((file) => `${file.path}: ${file.unavailable}`),
+                ...unavailableFieldSections(health, repositoryScale),
+            ],
+            files: manifestFiles,
+        },
+        report,
+        files,
+    };
+    return { ...preview, previewId: previewIdentity(preview) };
+}
+export function persistDiagnosticsPreview(repoPath, options = {}) {
+    const preview = previewDiagnosticsBundle(repoPath, options);
+    const repo = fs.realpathSync(repoPath);
+    withJournalLock(repo, () => {
+        const current = readPreviewStores(repo).at(-1);
+        const now = Date.now();
+        let entries = [
+            { persistedAt: new Date(now).toISOString(), preview },
+            ...(current?.entries ?? []).filter((entry) => {
+                const persisted = Date.parse(entry.persistedAt);
+                return (entry.preview.previewId !== preview.previewId &&
+                    Number.isFinite(persisted) &&
+                    persisted <= now + 60_000 &&
+                    now - persisted <= MAX_PREVIEW_AGE_MS);
+            }),
+        ].slice(0, MAX_PREVIEW_COUNT);
+        const generation = (current?.generation ?? 0) + 1;
+        let serialized = "";
+        do {
+            serialized = `${JSON.stringify({ schemaVersion: 1, generation, entries }, null, 2)}\n`;
+            if (Buffer.byteLength(serialized) <= MAX_PREVIEW_BYTES / 2)
+                break;
+            entries = entries.slice(0, -1);
+        } while (entries.length > 0);
+        if (entries.length === 0 || Buffer.byteLength(serialized) > MAX_PREVIEW_BYTES / 2)
+            throw new Error("knodin diagnostics preview: one preview exceeds the store bound");
+        const target = containedPath(repo, PREVIEW_STORES[generation % 2], "preview").target;
+        privateDescriptorReplace(repo, target, serialized);
+    });
+    return preview;
+}
+function readPreviewStores(repo) {
+    return PREVIEW_STORES.flatMap((relative) => {
+        const target = containedPath(repo, relative, "preview store").target;
+        if (!fs.existsSync(target))
+            return [];
+        try {
+            const raw = JSON.parse(readPrivateFile(repo, target, MAX_PREVIEW_BYTES / 2, "preview store").toString("utf8"));
+            if (raw.schemaVersion !== 1 ||
+                !Number.isSafeInteger(raw.generation) ||
+                Number(raw.generation) < 1 ||
+                !Array.isArray(raw.entries))
+                return [];
+            const entries = raw.entries.flatMap((entry) => {
+                const candidate = recordObject(entry);
+                const persisted = typeof candidate.persistedAt === "string"
+                    ? Date.parse(candidate.persistedAt)
+                    : Number.NaN;
+                if (!Number.isFinite(persisted) || persisted > Date.now() + 60_000)
+                    return [];
+                try {
+                    return [
+                        {
+                            persistedAt: candidate.persistedAt,
+                            preview: validateInspectedBundle(candidate.preview),
+                        },
+                    ];
+                }
+                catch {
+                    return [];
+                }
+            });
+            return [{ generation: Number(raw.generation), entries }];
+        }
+        catch {
+            return [];
+        }
+    }).sort((a, b) => a.generation - b.generation);
+}
+function readPersistedPreview(repo, previewId) {
+    if (!/^[a-f0-9]{32}$/.test(previewId))
+        throw new Error("knodin diagnostics archive: invalid preview ID");
+    const retrievable = [...readPreviewStores(repo)]
+        .reverse()
+        .flatMap((store) => store.entries)
+        .filter((entry, index, entries) => entries.findIndex((candidate) => candidate.preview.previewId === entry.preview.previewId) === index)
+        .slice(0, MAX_PREVIEW_COUNT);
+    for (const entry of retrievable) {
+        const age = Date.now() - Date.parse(entry.persistedAt);
+        if (age < 0 || age > MAX_PREVIEW_AGE_MS)
+            continue;
+        if (entry.preview.previewId === previewId)
+            return entry.preview;
+    }
+    throw new Error("knodin diagnostics archive: preview is unavailable or expired");
+}
+export function collectDiagnostics(repoPath, options = {}) {
+    const { repo, target } = containedPath(repoPath, options.outputPath ?? defaultBundlePath(), "collect");
+    if (fs.existsSync(target))
+        throw new Error("knodin diagnostics collect: refusing to overwrite an existing bundle");
+    const bundle = options.previewId
+        ? readPersistedPreview(repo, options.previewId)
+        : previewDiagnosticsBundle(repo, options);
+    const archive = zlib.gzipSync(`${JSON.stringify(bundle, null, 2)}\n`, { level: 9 });
+    if (archive.byteLength > MAX_BUNDLE_BYTES) {
+        throw new Error("knodin diagnostics collect: bundle exceeds the 512 KiB safety limit");
+    }
+    privateCreate(repo, target, archive);
+    return {
+        schemaVersion: 2,
+        outputPath: path.relative(repo, target),
+        format: "gzip-json",
+        localOnly: true,
+        uploaded: false,
+        bytes: fs.statSync(target).size,
+        records: bundle.files["failures.json"].records.length,
+        manifest: bundle.manifest,
+        message: "Bundle created locally. Run `knodin diagnostics inspect <bundle>` before sharing it.",
+    };
+}
+function exactObject(value, keys, section) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new Error(`knodin diagnostics inspect: malformed ${section}`);
+    const object = value;
+    // Byte order: a collation that ties two distinct keys leaves their relative
+    // order arbitrary, which would fail this strict comparison spuriously.
+    const actual = Object.keys(object).sort(compareBytes);
+    const expected = [...keys].sort(compareBytes);
+    if (JSON.stringify(actual) !== JSON.stringify(expected))
+        throw new Error(`knodin diagnostics inspect: unallowlisted field in ${section}`);
+    return object;
+}
+function validBundleRetention(filePath, value) {
+    if (typeof value !== "string")
+        return false;
+    if (filePath === "failures.json") {
+        const match = /^(\d{1,3}) days; preview window (\d{1,4}) hours$/.exec(value);
+        return Boolean(match && Number(match[1]) <= MAX_RETENTION_DAYS && Number(match[2]) <= 8760);
+    }
+    if (filePath === "mcp-traces.json") {
+        const match = /^C89 journal maximum 7 days; preview window (\d{1,4}) hours$/.exec(value);
+        return Boolean(match && Number(match[1]) <= 8760);
+    }
+    return value === "point-in-time snapshot; archive retained until user deletes it";
+}
+function validateInspectedBundle(value) {
+    const root = exactObject(value, ["schemaVersion", "previewId", "generatedAt", "manifest", "report", "files"], "bundle");
+    if (root.schemaVersion !== 2 ||
+        typeof root.generatedAt !== "string" ||
+        !Number.isFinite(Date.parse(root.generatedAt)))
+        throw new Error("knodin diagnostics inspect: unsupported bundle version or time");
+    if (typeof root.previewId !== "string" || !/^[a-f0-9]{32}$/.test(root.previewId))
+        throw new Error("knodin diagnostics inspect: malformed preview identity");
+    const manifest = exactObject(root.manifest, [
+        "schemaVersion",
+        "privacy",
+        "localOnly",
+        "uploaded",
+        "maxArchiveBytes",
+        "omissions",
+        "unavailableSections",
+        "files",
+    ], "manifest");
+    if (manifest.schemaVersion !== 2 ||
+        manifest.privacy !== "explicit-allowlist-local-only" ||
+        manifest.localOnly !== true ||
+        manifest.uploaded !== false ||
+        manifest.maxArchiveBytes !== MAX_BUNDLE_BYTES ||
+        JSON.stringify(manifest.omissions) !== JSON.stringify(BUNDLE_OMISSIONS))
+        throw new Error("knodin diagnostics inspect: unsupported or unsafe bundle manifest");
+    const files = exactObject(root.files, ["runtime.json", "health.json", "repository-scale.json", "mcp-traces.json", "failures.json"], "files");
+    const runtime = exactObject(files["runtime.json"], ["knodin", "node", "platform", "arch"], "runtime");
+    if (typeof runtime.knodin !== "string" ||
+        !/^(?:unavailable|\d+\.\d+\.\d+(?:[-+][A-Za-z0-9.-]+)?)$/.test(runtime.knodin) ||
+        typeof runtime.node !== "string" ||
+        !/^v\d+\.\d+\.\d+$/.test(runtime.node) ||
+        typeof runtime.platform !== "string" ||
+        !/^[a-z0-9_-]{1,32}$/.test(runtime.platform) ||
+        typeof runtime.arch !== "string" ||
+        !/^[a-z0-9_-]{1,32}$/.test(runtime.arch))
+        throw new Error("knodin diagnostics inspect: malformed runtime fields");
+    const health = exactObject(files["health.json"], ["graph", "lifecycle", "installation"], "health");
+    const graph = exactObject(health.graph, ["status", "freshness"], "graph health");
+    const freshness = exactObject(graph.freshness, ["state", "commitRelation", "commitDistance"], "freshness");
+    const lifecycle = exactObject(health.lifecycle, ["status", "queuedEvents", "processorState"], "lifecycle health");
+    const installation = exactObject(health.installation, ["status"], "installation health");
+    if (typeof graph.status !== "string" ||
+        !GRAPH_STATUSES.includes(graph.status) ||
+        typeof freshness.state !== "string" ||
+        !FRESHNESS_STATES.includes(freshness.state) ||
+        typeof freshness.commitRelation !== "string" ||
+        !COMMIT_RELATIONS.includes(freshness.commitRelation) ||
+        (freshness.commitDistance !== null && safeCount(freshness.commitDistance) === null) ||
+        typeof lifecycle.status !== "string" ||
+        !LIFECYCLE_STATUSES.includes(lifecycle.status) ||
+        (lifecycle.queuedEvents !== null && safeCount(lifecycle.queuedEvents) === null) ||
+        typeof lifecycle.processorState !== "string" ||
+        !PROCESSOR_STATES.includes(lifecycle.processorState) ||
+        typeof installation.status !== "string" ||
+        !INSTALLATION_STATUSES.includes(installation.status))
+        throw new Error("knodin diagnostics inspect: malformed health fields");
+    const scale = exactObject(files["repository-scale.json"], [
+        "sourceFiles",
+        "indexedFiles",
+        "filesWithSymbols",
+        "coveragePercent",
+        "missingFileCount",
+        "missingRecordCount",
+    ], "repository scale");
+    for (const key of [
+        "sourceFiles",
+        "indexedFiles",
+        "filesWithSymbols",
+        "missingFileCount",
+        "missingRecordCount",
+    ])
+        if (scale[key] !== null && safeCount(scale[key]) === null)
+            throw new Error("knodin diagnostics inspect: malformed repository scale");
+    if (scale.coveragePercent !== null &&
+        (typeof scale.coveragePercent !== "number" ||
+            scale.coveragePercent < 0 ||
+            scale.coveragePercent > 100))
+        throw new Error("knodin diagnostics inspect: malformed repository coverage");
+    const traceFile = exactObject(files["mcp-traces.json"], ["records"], "MCP traces");
+    if (!Array.isArray(traceFile.records) || traceFile.records.length > MAX_BUNDLE_RECORDS)
+        throw new Error("knodin diagnostics inspect: malformed MCP traces");
+    for (const item of traceFile.records) {
+        const record = item;
+        const required = ["at", "event", "requestId", "traceId", "operation", "deadlineMs"];
+        const optional = ["kind", "elapsedMs", "sequence", "predecessorTraceId"];
+        if (!record ||
+            typeof record !== "object" ||
+            Object.keys(record).some((key) => ![...required, ...optional].includes(key)) ||
+            required.some((key) => !(key in record)))
+            throw new Error("knodin diagnostics inspect: unallowlisted MCP trace field");
+        if (typeof record.at !== "string" ||
+            !Number.isFinite(Date.parse(record.at)) ||
+            typeof record.event !== "string" ||
+            !MCP_EVENTS.has(record.event) ||
+            typeof record.requestId !== "string" ||
+            !/^[-A-Za-z0-9:._]{1,128}$/.test(record.requestId) ||
+            typeof record.traceId !== "string" ||
+            !/^[-a-fA-F0-9]{8,64}$/.test(record.traceId) ||
+            typeof record.operation !== "string" ||
+            !OPERATIONS.has(record.operation) ||
+            safeCount(record.deadlineMs) === null ||
+            (record.kind !== undefined &&
+                (typeof record.kind !== "string" || !MCP_FAILURES.has(record.kind))) ||
+            (record.predecessorTraceId !== undefined &&
+                (typeof record.predecessorTraceId !== "string" ||
+                    !/^[-a-fA-F0-9]{8,64}$/.test(record.predecessorTraceId))) ||
+            [record.elapsedMs, record.sequence].some((count) => count !== undefined && safeCount(count) === null))
+            throw new Error("knodin diagnostics inspect: malformed MCP trace field");
+    }
+    const failureFile = exactObject(files["failures.json"], ["records"], "failures");
+    if (!Array.isArray(failureFile.records) || failureFile.records.length > MAX_BUNDLE_RECORDS)
+        throw new Error("knodin diagnostics inspect: malformed failures");
+    for (const item of failureFile.records) {
+        const failure = exactObject(item, ["schemaVersion", "at", "correlationId", "surface", "operation", "phase", "error"], "failure");
+        const error = exactObject(failure.error, ["name", "code", "messageFingerprint", "stack"], "failure error");
+        if (failure.schemaVersion !== 1 ||
+            typeof failure.at !== "string" ||
+            !Number.isFinite(Date.parse(failure.at)) ||
+            typeof failure.correlationId !== "string" ||
+            !/^[a-f0-9]{16}$/.test(failure.correlationId) ||
+            !["cli", "mcp", "lifecycle"].includes(failure.surface) ||
+            typeof failure.operation !== "string" ||
+            !OPERATIONS.has(failure.operation) ||
+            typeof failure.phase !== "string" ||
+            safeLabel(failure.phase, "") !== failure.phase ||
+            typeof error.name !== "string" ||
+            safeLabel(error.name, "") !== error.name ||
+            (error.code !== null && errorCode(error) === null) ||
+            typeof error.messageFingerprint !== "string" ||
+            !/^[a-f0-9]{16}$/.test(error.messageFingerprint) ||
+            !Array.isArray(error.stack) ||
+            error.stack.some((line) => line !== "at <repository>" && line !== "at <runtime>"))
+            throw new Error("knodin diagnostics inspect: malformed failure field");
+    }
+    const typedHealth = health;
+    const traces = traceFile.records;
+    const failures = failureFile.records;
+    if (root.report !== renderSupportReport(root.generatedAt, typedHealth, traces, failures))
+        throw new Error("knodin diagnostics inspect: report does not match allowlisted evidence");
+    const descriptors = manifest.files;
+    if (!Array.isArray(descriptors) || descriptors.length !== 6)
+        throw new Error("knodin diagnostics inspect: malformed file manifest");
+    const ordered = [
+        "support-report.txt",
+        "runtime.json",
+        "health.json",
+        "repository-scale.json",
+        "mcp-traces.json",
+        "failures.json",
+    ];
+    for (const [index, descriptorValue] of descriptors.entries()) {
+        const descriptor = exactObject(descriptorValue, ["path", "bytes", "fields", "retention", "redaction", "unavailable"], "file descriptor");
+        const filePath = ordered[index];
+        const content = filePath === "support-report.txt" ? root.report : files[filePath];
+        const bytes = Buffer.byteLength(typeof content === "string" ? content : `${JSON.stringify(content, null, 2)}\n`);
+        if (descriptor.path !== filePath ||
+            descriptor.bytes !== bytes ||
+            JSON.stringify(descriptor.fields) !==
+                JSON.stringify(typeof content === "string" ? ["$.text"] : fieldPaths(content)) ||
+            JSON.stringify(descriptor.redaction) !== JSON.stringify(["explicit-allowlist"]) ||
+            !validBundleRetention(filePath, descriptor.retention) ||
+            (descriptor.unavailable !== null &&
+                (typeof descriptor.unavailable !== "string" ||
+                    !UNAVAILABLE_REASONS.has(descriptor.unavailable))))
+            throw new Error("knodin diagnostics inspect: file manifest does not match payload");
+    }
+    const unavailable = [
+        ...descriptors
+            .filter((file) => file.unavailable !== null)
+            .map((file) => `${file.path}: ${file.unavailable}`),
+        ...unavailableFieldSections(typedHealth, scale),
+    ];
+    if (JSON.stringify(manifest.unavailableSections) !== JSON.stringify(unavailable))
+        throw new Error("knodin diagnostics inspect: unavailable sections do not match manifest");
+    const typed = value;
+    const { previewId, ...withoutIdentity } = typed;
+    if (previewIdentity(withoutIdentity) !== previewId)
+        throw new Error("knodin diagnostics inspect: preview identity does not match contents");
+    return typed;
+}
+export function inspectDiagnosticsBundle(repoPath, bundlePath) {
+    const { repo, target } = containedPath(repoPath, bundlePath, "inspect");
+    if (!fs.existsSync(target))
+        throw new Error("knodin diagnostics inspect: bundle does not exist");
+    if (fs.statSync(target).size > MAX_BUNDLE_BYTES)
+        throw new Error("knodin diagnostics inspect: bundle exceeds the 512 KiB safety limit");
+    let raw;
+    try {
+        raw = JSON.parse(zlib
+            .gunzipSync(readPrivateFile(repo, target, MAX_BUNDLE_BYTES, "inspect"), {
+            maxOutputLength: MAX_BUNDLE_BYTES,
+        })
+            .toString("utf8"));
+    }
+    catch {
+        throw new Error("knodin diagnostics inspect: invalid gzip JSON bundle");
+    }
+    const parsed = validateInspectedBundle(raw);
+    return {
+        manifest: parsed.manifest,
+        report: parsed.report,
+        sections: parsed.manifest.files.map((file) => file.path),
+        bundle: parsed,
+    };
+}