@faithfulalabi/agent-lens 0.1.0

package/dist/src/archive/report.js

@@ -0,0 +1,272 @@
+import { createHash } from 'node:crypto';
+import { closeSync, openSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { basename, join } from 'node:path';
+import { discover } from './discover.js';
+import { detectDivergence } from './mirror.js';
+import { canonicalizeTranscriptPath, lstatSafe, resolveArchiveRoot, resolveDataDir, resolveTranscriptRoot, statSafe, } from './paths.js';
+import { DEFAULT_MAX_BYTES, declaredContentSize, decompressSealedFrame } from './read.js';
+import { readSidecar, sidecarPath } from './sidecar.js';
+const CHUNK_BYTES = 1024 * 1024;
+const SEALED_SUFFIX = '.zst';
+export const NO_LIVE_SOURCE_REASON = 'no live source — no stored hash exists';
+export const SEALED_LEGACY_REASON = 'sealed — no stored hash on disk: sealed before sidecars existed, and there is nothing honest to backfill';
+export const SEALED_UNCHECKED_REASON = 'sealed — stored hash present but not read: pass --verify to re-hash the archived bytes';
+export function resolveClaudeSettingsPath(path) {
+    return (path ?? process.env.AGENT_LENS_CLAUDE_SETTINGS ?? join(homedir(), '.claude', 'settings.json'));
+}
+export function readRetentionSetting(path) {
+    let text;
+    try {
+        text = readFileSync(path, 'utf8');
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return { state: 'absent' };
+        return { state: 'unreadable', message: String(error.message ?? error) };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch (error) {
+        return { state: 'unreadable', message: String(error.message ?? error) };
+    }
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        return { state: 'unreadable', message: 'settings.json is not a JSON object' };
+    }
+    const days = parsed.cleanupPeriodDays;
+    if (typeof days !== 'number' || !Number.isFinite(days))
+        return { state: 'unset' };
+    return { state: 'set', days };
+}
+function archiveDiskPath(archivePath, sealed) {
+    return sealed ? `${archivePath}${SEALED_SUFFIX}` : archivePath;
+}
+function compareToSource(params) {
+    const sourceFd = openSync(params.sourcePath, 'r');
+    try {
+        const archiveFd = openSync(params.diskPath, 'r');
+        try {
+            return detectDivergence({
+                sourceFd,
+                archiveFd,
+                sourceSize: params.sourceSize,
+                archiveSize: params.archiveSize,
+                verify: params.verify,
+                buffer: params.buffer,
+            });
+        }
+        finally {
+            closeSync(archiveFd);
+        }
+    }
+    finally {
+        closeSync(sourceFd);
+    }
+}
+function sha256(buf) {
+    return createHash('sha256').update(buf).digest('hex');
+}
+function loadSealedFrame(diskPath) {
+    const frame = readFileSync(diskPath);
+    const declared = declaredContentSize(frame, diskPath);
+    if (declared > DEFAULT_MAX_BYTES)
+        return { state: 'over-bound', declared };
+    const buf = decompressSealedFrame(frame, declared, diskPath, DEFAULT_MAX_BYTES);
+    return { state: 'loaded', buf, declared };
+}
+function classifySealedThrow(error) {
+    const code = error.code;
+    if (typeof code === 'string' && /^E[A-Z0-9]+$/.test(code)) {
+        return {
+            state: 'unverifiable',
+            reason: `unreadable — ${String(error.message ?? error)}`,
+        };
+    }
+    return { state: 'diverged', reason: 'sealed-frame' };
+}
+function checkSealed(params) {
+    const legacy = {
+        verdict: { state: 'unverifiable', reason: SEALED_LEGACY_REASON },
+        bytesRead: 0,
+    };
+    const sidecar = sidecarPath(params.diskPath);
+    if (lstatSafe(sidecar)?.isFile() !== true)
+        return legacy;
+    const record = readSidecar(sidecar);
+    if (record === undefined)
+        return legacy;
+    if (record.file !== params.logicalName) {
+        return { verdict: { state: 'diverged', reason: 'sealed-attribution' }, bytesRead: 0 };
+    }
+    if (record.sealed_size !== params.archiveSize) {
+        return { verdict: { state: 'diverged', reason: 'sealed-size' }, bytesRead: 0 };
+    }
+    if (!params.verify) {
+        return {
+            verdict: { state: 'unverifiable', reason: SEALED_UNCHECKED_REASON },
+            bytesRead: 0,
+        };
+    }
+    let frame;
+    try {
+        frame = loadSealedFrame(params.diskPath);
+    }
+    catch (error) {
+        return { verdict: classifySealedThrow(error), bytesRead: 0 };
+    }
+    if (frame.state === 'over-bound') {
+        return {
+            verdict: {
+                state: 'unverifiable',
+                reason: `unreadable — ${params.diskPath} declares ${frame.declared} bytes, over the ${DEFAULT_MAX_BYTES}-byte bound`,
+            },
+            bytesRead: 0,
+        };
+    }
+    const bytesRead = frame.buf.length;
+    if (sha256(frame.buf) !== record.sha256) {
+        return { verdict: { state: 'diverged', reason: 'sealed-hash' }, bytesRead };
+    }
+    return { verdict: { state: 'verified' }, bytesRead };
+}
+export function buildDoctorReport(options = {}) {
+    const dataDir = resolveDataDir(options.dataDir);
+    const sourceRoot = canonicalizeTranscriptPath(resolveTranscriptRoot(options.transcriptRoot));
+    const archiveRoot = canonicalizeTranscriptPath(resolveArchiveRoot(dataDir));
+    const settingsPath = resolveClaudeSettingsPath(options.settingsPath);
+    const verify = options.verify === true;
+    const coverage = { found: 0, mirrored: 0, unmirrored: [], archiveOnly: 0 };
+    const bytes = {
+        hotFiles: 0,
+        hotBytes: 0,
+        sealedFiles: 0,
+        sealedBytes: 0,
+        totalBytes: 0,
+    };
+    const integrity = {
+        verify,
+        bytesRead: 0,
+        archivedFileCount: 0,
+        verified: [],
+        diverged: [],
+        unverifiable: [],
+    };
+    const buffer = Buffer.allocUnsafe(CHUNK_BYTES);
+    for (const entry of discover(sourceRoot, archiveRoot)) {
+        const diskPath = archiveDiskPath(entry.archivePath, entry.sealed);
+        const archiveStat = lstatSafe(diskPath);
+        const archiveSize = archiveStat?.isFile() === true ? archiveStat.size : 0;
+        const archived = archiveSize > 0;
+        if (entry.presence === 'archive-only') {
+            coverage.archiveOnly += 1;
+        }
+        else {
+            coverage.found += 1;
+            if (archived)
+                coverage.mirrored += 1;
+            else
+                coverage.unmirrored.push(entry.relPath);
+        }
+        if (!archived)
+            continue;
+        if (entry.sealed) {
+            bytes.sealedFiles += 1;
+            bytes.sealedBytes += archiveSize;
+        }
+        else {
+            bytes.hotFiles += 1;
+            bytes.hotBytes += archiveSize;
+        }
+        bytes.totalBytes += archiveSize;
+        integrity.archivedFileCount += 1;
+        if (entry.sealed) {
+            const sealed = checkSealed({
+                diskPath,
+                logicalName: basename(entry.archivePath),
+                archiveSize,
+                verify,
+            });
+            integrity.bytesRead += sealed.bytesRead;
+            if (sealed.verdict.state === 'verified') {
+                integrity.verified.push(entry.relPath);
+            }
+            else if (sealed.verdict.state === 'diverged') {
+                integrity.diverged.push({
+                    relPath: entry.relPath,
+                    archivePath: diskPath,
+                    reason: sealed.verdict.reason,
+                });
+            }
+            else {
+                integrity.unverifiable.push({
+                    relPath: entry.relPath,
+                    archivePath: diskPath,
+                    reason: sealed.verdict.reason,
+                });
+            }
+            continue;
+        }
+        const sourceStat = entry.presence === 'both' ? statSafe(entry.sourcePath) : undefined;
+        if (sourceStat === undefined || !sourceStat.isFile()) {
+            integrity.unverifiable.push({
+                relPath: entry.relPath,
+                archivePath: diskPath,
+                reason: NO_LIVE_SOURCE_REASON,
+            });
+            continue;
+        }
+        let compared;
+        try {
+            compared = compareToSource({
+                sourcePath: entry.sourcePath,
+                diskPath,
+                sourceSize: sourceStat.size,
+                archiveSize,
+                verify,
+                buffer,
+            });
+        }
+        catch (error) {
+            integrity.unverifiable.push({
+                relPath: entry.relPath,
+                archivePath: diskPath,
+                reason: error.code === 'ENOENT'
+                    ? NO_LIVE_SOURCE_REASON
+                    : `unreadable — ${String(error.message ?? error)}`,
+            });
+            continue;
+        }
+        integrity.bytesRead += compared.bytesRead;
+        if (compared.reason === undefined) {
+            integrity.verified.push(entry.relPath);
+        }
+        else {
+            integrity.diverged.push({
+                relPath: entry.relPath,
+                sourcePath: entry.sourcePath,
+                archivePath: diskPath,
+                reason: compared.reason,
+            });
+        }
+    }
+    assertPopulationsPartition(integrity);
+    return {
+        dataDir,
+        sourceRoot,
+        archiveRoot,
+        settingsPath,
+        coverage,
+        bytes,
+        integrity,
+        retention: readRetentionSetting(settingsPath),
+    };
+}
+function assertPopulationsPartition(integrity) {
+    const counted = integrity.verified.length + integrity.diverged.length + integrity.unverifiable.length;
+    if (counted !== integrity.archivedFileCount) {
+        throw new Error(`doctor integrity accounting is broken: ${counted} classified but ` +
+            `${integrity.archivedFileCount} archived files exist`);
+    }
+}

package/dist/src/archive/seal.js

@@ -0,0 +1,76 @@
+import { createHash } from 'node:crypto';
+import { closeSync, constants, fchmodSync, fstatSync, openSync, readFileSync, renameSync, unlinkSync, writeSync, } from 'node:fs';
+import { basename, dirname } from 'node:path';
+import { constants as zlibConstants, zstdCompressSync, zstdDecompressSync } from 'node:zlib';
+import { assertUnderArchiveRoot, canonicalizeTranscriptPath, refuseSymlinkedLeaf, } from './paths.js';
+import { serializeSidecar, sidecarPath, SIDECAR_VERSION } from './sidecar.js';
+const { O_NOFOLLOW, O_RDONLY } = constants;
+const SEALED_SUFFIX = '.zst';
+const ZSTD_PARAMS = {
+    [zlibConstants.ZSTD_c_compressionLevel]: 3,
+    [zlibConstants.ZSTD_c_checksumFlag]: 1,
+    [zlibConstants.ZSTD_c_contentSizeFlag]: 1,
+};
+function sha256(buf) {
+    return createHash('sha256').update(buf).digest('hex');
+}
+export function sealArchiveFile(archivePath, archiveRoot) {
+    const fd = refuseSymlinkedLeaf(archivePath, () => openSync(archivePath, O_RDONLY | O_NOFOLLOW));
+    let bytes;
+    let hotSize;
+    try {
+        hotSize = fstatSync(fd).size;
+        bytes = readFileSync(fd);
+    }
+    finally {
+        closeSync(fd);
+    }
+    if (bytes.length !== hotSize) {
+        throw new Error(`refusing to seal ${archivePath}: it holds ${bytes.length} bytes but stat said ${hotSize}`);
+    }
+    const archiveSha256 = sha256(bytes);
+    const compressed = zstdCompressSync(bytes, { params: ZSTD_PARAMS });
+    const roundTrip = zstdDecompressSync(compressed);
+    if (roundTrip.length !== hotSize || sha256(roundTrip) !== archiveSha256) {
+        throw new Error(`seal round-trip verify failed for ${archivePath}: ${roundTrip.length} bytes back from ${hotSize}`);
+    }
+    assertUnderArchiveRoot(canonicalizeTranscriptPath(dirname(archivePath)), archiveRoot);
+    const temp = `${archivePath}${SEALED_SUFFIX}.tmp.${process.pid}`;
+    const tempFd = refuseSymlinkedLeaf(temp, () => openSync(temp, 'wx', 0o600));
+    try {
+        fchmodSync(tempFd, 0o600);
+        writeSync(tempFd, compressed, 0, compressed.length, 0);
+    }
+    finally {
+        closeSync(tempFd);
+    }
+    const sealedAt = new Date().toISOString();
+    const sealedPath = `${archivePath}${SEALED_SUFFIX}`;
+    const sidecar = sidecarPath(sealedPath);
+    const sidecarTemp = `${sidecar}.tmp.${process.pid}`;
+    const sidecarBytes = Buffer.from(serializeSidecar({
+        v: SIDECAR_VERSION,
+        file: basename(archivePath),
+        sha256: archiveSha256,
+        hot_size: hotSize,
+        sealed_size: compressed.length,
+        sealed_at: sealedAt,
+    }), 'utf8');
+    const sidecarFd = refuseSymlinkedLeaf(sidecarTemp, () => openSync(sidecarTemp, 'wx', 0o600));
+    try {
+        fchmodSync(sidecarFd, 0o600);
+        writeSync(sidecarFd, sidecarBytes, 0, sidecarBytes.length, 0);
+    }
+    finally {
+        closeSync(sidecarFd);
+    }
+    renameSync(sidecarTemp, sidecar);
+    renameSync(temp, sealedPath);
+    unlinkSync(archivePath);
+    return {
+        archive_sha256: archiveSha256,
+        sealed_at: sealedAt,
+        sealed_size: compressed.length,
+        hot_size: hotSize,
+    };
+}

package/dist/src/archive/sidecar.js

@@ -0,0 +1,39 @@
+import { readFileSync } from 'node:fs';
+const SIDECAR_SUFFIX = '.sha256';
+export const SIDECAR_VERSION = 1;
+export function sidecarPath(sealedPath) {
+    return `${sealedPath}${SIDECAR_SUFFIX}`;
+}
+export function serializeSidecar(record) {
+    return `${JSON.stringify(record)}\n`;
+}
+export function readSidecar(path) {
+    let text;
+    try {
+        text = readFileSync(path, 'utf8');
+    }
+    catch {
+        return undefined;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+    return isSealSidecar(parsed) ? parsed : undefined;
+}
+const HEX_SHA256 = /^[0-9a-f]{64}$/;
+function isSealSidecar(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const record = value;
+    return (record.v === SIDECAR_VERSION &&
+        typeof record.file === 'string' &&
+        typeof record.sha256 === 'string' &&
+        HEX_SHA256.test(record.sha256) &&
+        Number.isInteger(record.hot_size) &&
+        Number.isInteger(record.sealed_size) &&
+        typeof record.sealed_at === 'string');
+}

package/dist/src/cli/args.js

@@ -0,0 +1,47 @@
+function normalise(flag) {
+    return flag.toLowerCase().replace(/[-_]/g, '');
+}
+function didYouMean(spec, name) {
+    const target = normalise(name);
+    return Object.keys(spec.flags).find((known) => normalise(known) === target);
+}
+export function validateArgs(spec, args) {
+    let seenPositional = false;
+    for (let i = 0; i < args.length; i += 1) {
+        const arg = args[i];
+        if (arg.startsWith('-')) {
+            const eq = arg.indexOf('=');
+            const name = eq === -1 ? arg : arg.slice(0, eq);
+            const kind = spec.flags[name];
+            if (kind === undefined) {
+                const meant = didYouMean(spec, name);
+                return {
+                    ok: false,
+                    message: `unknown argument ${arg}${meant === undefined ? '' : ` — did you mean ${meant}?`}`,
+                };
+            }
+            if (kind === 'boolean')
+                continue;
+            if (eq === -1) {
+                if (i + 1 >= args.length)
+                    return { ok: false, message: `${name} requires a value` };
+                i += 1;
+                continue;
+            }
+            if (eq === arg.length - 1)
+                return { ok: false, message: `${name} requires a value` };
+            continue;
+        }
+        if (spec.positional === 'none') {
+            return { ok: false, message: `unexpected argument ${arg}` };
+        }
+        if (seenPositional) {
+            return {
+                ok: false,
+                message: `unexpected argument ${arg} — ${spec.name} takes at most one session id`,
+            };
+        }
+        seenPositional = true;
+    }
+    return { ok: true };
+}

package/dist/src/cli/commands/archive.js

@@ -0,0 +1,65 @@
+import { archiveOnce } from '../../archive/index.js';
+export const EXIT_OK = 0;
+export const EXIT_INCOMPLETE = 1;
+export const EXIT_ARCHIVE_ERRORS = 3;
+export function exitCodeFor(result) {
+    return result.errors.some((e) => e.origin === 'archive') ? EXIT_ARCHIVE_ERRORS : EXIT_OK;
+}
+export function parseStringFlag(args, name) {
+    const long = `--${name}`;
+    const prefix = `${long}=`;
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === long) {
+            const value = args[i + 1];
+            if (value === undefined || value === '')
+                throw new Error(`${long} requires a value`);
+            return value;
+        }
+        if (arg.startsWith(prefix)) {
+            const value = arg.slice(prefix.length);
+            if (value === '')
+                throw new Error(`${long} requires a value`);
+            return value;
+        }
+    }
+    return undefined;
+}
+export function formatSummary(result) {
+    const diverged = result.files.filter((f) => f.source_state === 'diverged');
+    const expired = result.files.filter((f) => f.source_state === 'expired');
+    const leader = result.lock.state === 'held'
+        ? `another pass holds the lock (pid ${result.lock.holder_pid ?? '?'}) — copied nothing`
+        : `${result.filesSeen} files, ${result.bytesCopied} bytes copied`;
+    const count = result.errors.length;
+    const errorSuffix = count === 0 ? '' : `, ${count} error${count === 1 ? '' : 's'}`;
+    const lines = [`agent-lens archive: ${leader}${errorSuffix}`];
+    if (result.lock.state === 'reclaimed') {
+        lines.push(`  reclaimed a stale lock (${result.lock.reclaim_reason})`);
+    }
+    if (diverged.length > 0) {
+        lines.push(`  ${diverged.length} diverged (archived bytes kept, nothing overwritten):`);
+        for (const file of diverged)
+            lines.push(`    ${file.reason}  ${file.source_path}`);
+    }
+    if (expired.length > 0) {
+        lines.push(`  ${expired.length} expired at the source — the archive is now the only copy`);
+    }
+    for (const error of result.errors)
+        lines.push(`  error  ${error.path}: ${error.message}`);
+    return lines.join('\n');
+}
+export async function archive(args = []) {
+    const result = archiveOnce({
+        dataDir: parseStringFlag(args, 'dataDir'),
+        transcriptRoot: parseStringFlag(args, 'transcriptRoot'),
+        verify: args.includes('--verify'),
+    });
+    if (args.includes('--json')) {
+        console.log(JSON.stringify(result));
+    }
+    else {
+        console.log(formatSummary(result));
+    }
+    return exitCodeFor(result);
+}

package/dist/src/cli/commands/doctor.js

@@ -0,0 +1,191 @@
+import { join } from 'node:path';
+import { buildDoctorReport, readCronLogStatus, resolveDataDir, } from '../../archive/index.js';
+import { CACHE_DB_FILE, openReadOnlyDb } from '../../db/open.js';
+import { readDriftRows, readHealthCounts, readMeta } from '../../db/read.js';
+import { aggregateDrift } from '../../server/drift-report.js';
+import { parseStringFlag } from './archive.js';
+const MAX_LISTED = 20;
+export const COVERAGE_GAP_STATEMENT = 'agent-lens can only archive what exists while it runs — a gap in uptime is a gap in the record.';
+export const DURABILITY_STATEMENT = 'rm cache.db loses nothing. rm -rf ~/.agent-lens/archive loses data permanently.';
+function listCapped(items, indent) {
+    const shown = items.slice(0, MAX_LISTED).map((item) => `${indent}${item}`);
+    if (items.length > MAX_LISTED) {
+        shown.push(`${indent}… and ${items.length - MAX_LISTED} more (${items.length} in total)`);
+    }
+    return shown;
+}
+function files(n) {
+    return n === 1 ? '1 file' : `${n} files`;
+}
+export function readCacheStats(dataDir) {
+    const dir = resolveDataDir(dataDir);
+    const path = join(dir, CACHE_DB_FILE);
+    let db;
+    try {
+        db = openReadOnlyDb(dir);
+        if (db === undefined)
+            return { state: 'absent', path };
+        const counts = readHealthCounts(db);
+        const drift = aggregateDrift(readDriftRows(db));
+        const drifting = new Map();
+        for (const session of drift.sessions_with_drift) {
+            const version = session.harness_version ?? 'unknown';
+            drifting.set(version, (drifting.get(version) ?? 0) + 1);
+        }
+        return {
+            state: 'ready',
+            path,
+            stats: {
+                db_bytes: counts.db_bytes,
+                sessions_indexed: counts.sessions_indexed,
+                sessions_projected: counts.sessions_projected,
+                schema_version: readMeta(db, 'schema_version'),
+                projector_version: readMeta(db, 'projector_version'),
+                harness: Object.entries(drift.harness_versions)
+                    .map(([version, projected]) => ({
+                    version,
+                    projected,
+                    drifting: drifting.get(version) ?? 0,
+                }))
+                    .sort((a, b) => (a.version < b.version ? -1 : 1)),
+            },
+        };
+    }
+    catch (error) {
+        return { state: 'unreadable', path, message: String(error.message ?? error) };
+    }
+    finally {
+        if (db?.isOpen === true)
+            db.close();
+    }
+}
+export function formatCacheSection(cache) {
+    if (cache.state === 'absent') {
+        return ['', `cache: ${cache.path} — not created yet; \`agent-lens start\` builds it`];
+    }
+    if (cache.state === 'unreadable') {
+        return [
+            '',
+            `cache: ${cache.path} — stats unavailable: ${cache.message}`,
+            '  nothing is lost either way — `agent-lens rebuild` recreates the whole file',
+        ];
+    }
+    const { stats } = cache;
+    const lines = [
+        '',
+        `cache: ${cache.path}`,
+        `  ${stats.db_bytes} bytes`,
+        `  ${stats.sessions_indexed} sessions indexed, ${stats.sessions_projected} projected`,
+        `  schema_version ${stats.schema_version ?? 'unstamped'}, ` +
+            `projector_version ${stats.projector_version ?? 'unstamped'}`,
+    ];
+    if (stats.harness.length === 0) {
+        lines.push('  no projected session carries a harness version yet');
+        return lines;
+    }
+    lines.push('  drift by harness version (the census counts clean rows too):');
+    for (const row of stats.harness) {
+        lines.push(`    ${row.version}: ${row.projected} projected, ${row.drifting} drifting`);
+    }
+    return lines;
+}
+function formatAgo(elapsedMs) {
+    const minutes = Math.max(0, Math.floor(elapsedMs / 60_000));
+    if (minutes < 60)
+        return `${minutes}m ago`;
+    const hours = Math.floor(minutes / 60);
+    if (hours < 24)
+        return `${hours}h ${minutes % 60}m ago`;
+    return `${Math.floor(hours / 24)}d ${hours % 24}h ago`;
+}
+export function formatLastPassSection(report, now = Date.now()) {
+    if (report.state === 'absent') {
+        return ['', `archive job: ${report.path} — no cron.log; the job has never run here`];
+    }
+    if (report.state === 'empty') {
+        return ['', `archive job: ${report.path} — cron.log exists but records no pass`];
+    }
+    const lines = ['', `archive job: ${report.path}`];
+    lines.push(report.lastOk === undefined
+        ? '  no successful pass on record'
+        : `  last successful pass: ${formatAgo(now - report.lastOk.epochMs)}`);
+    if (report.lastEntry.status !== 'ok') {
+        lines.push(`  most recent attempt: ${report.lastEntry.status}, ` +
+            `${formatAgo(now - report.lastEntry.epochMs)} — ${report.lastEntry.summary}`);
+    }
+    return lines;
+}
+export function formatRetention(retention) {
+    switch (retention.state) {
+        case 'set':
+            return `Claude Code retention (cleanupPeriodDays): ${retention.days} days`;
+        case 'unset':
+            return 'Claude Code retention (cleanupPeriodDays): unset — default applies';
+        case 'absent':
+            return 'Claude Code retention: no settings file — unset — default applies';
+        case 'unreadable':
+            return `Claude Code retention: unreadable — ${retention.message}`;
+    }
+}
+export function formatDoctorReport(report, cache, lastPass) {
+    const { coverage, bytes, integrity, retention } = report;
+    const lines = [
+        'agent-lens doctor',
+        `  transcripts  ${report.sourceRoot}`,
+        `  archive      ${report.archiveRoot}`,
+        '',
+        `coverage: ${coverage.mirrored} of ${coverage.found} source files mirrored`,
+    ];
+    if (coverage.unmirrored.length > 0) {
+        lines.push(`  not yet mirrored (${coverage.unmirrored.length}):`);
+        lines.push(...listCapped(coverage.unmirrored, '    '));
+    }
+    if (coverage.archiveOnly > 0) {
+        lines.push(`  ${files(coverage.archiveOnly)} with no live source — the archive is the only copy left`);
+    }
+    lines.push('', `archive bytes: ${bytes.totalBytes} total — ${bytes.hotBytes} hot in ${files(bytes.hotFiles)}, ` +
+        `${bytes.sealedBytes} sealed in ${files(bytes.sealedFiles)}`, '', integrity.verify
+        ? 'integrity (--verify: full prefix hash over every checkable file):'
+        : 'integrity (head+seam probe, roughly 1% of bytes — pass --verify for the full prefix hash):', `  ${files(integrity.archivedFileCount)} archived = ${integrity.verified.length} verified + ` +
+        `${integrity.diverged.length} diverged + ${integrity.unverifiable.length} unverifiable`);
+    if (integrity.diverged.length > 0) {
+        lines.push(`  diverged (${integrity.diverged.length}) — the archived bytes and their reference disagree.`, '    Consistent with two readings, and this check cannot tell them apart: the', '    source was rewritten, or the archived bytes were corrupted. Nothing was', '    overwritten either way.');
+        if (integrity.diverged.some((file) => file.reason.startsWith('sealed-'))) {
+            lines.push('    A sealed row is narrower than that: its source is already gone, so it was', '    compared against the hash the seal recorded and one reading is left —', '    the archived bytes changed.');
+        }
+        for (const file of integrity.diverged) {
+            lines.push(`    ${file.reason}  ${file.archivePath}`);
+        }
+    }
+    if (integrity.unverifiable.length > 0) {
+        lines.push(`  unverifiable (${integrity.unverifiable.length}) — NOT checked, and NOT verified.`, '    Each row names its own reason. Nothing here was compared against anything.');
+        if (!integrity.verify) {
+            lines.push('    Pass --verify to re-hash every sealed file that has a stored hash.');
+        }
+        lines.push(...listCapped(integrity.unverifiable.map((file) => `${file.reason}  ${file.archivePath}`), '    '));
+    }
+    lines.push('', formatRetention(retention), `  read from ${report.settingsPath} — reported only; doctor never writes it`);
+    if (cache !== undefined)
+        lines.push(...formatCacheSection(cache));
+    if (lastPass !== undefined)
+        lines.push(...formatLastPassSection(lastPass));
+    lines.push('', COVERAGE_GAP_STATEMENT, DURABILITY_STATEMENT);
+    return lines.join('\n');
+}
+export async function doctor(args = []) {
+    const dataDir = parseStringFlag(args, 'dataDir');
+    const report = buildDoctorReport({
+        dataDir,
+        transcriptRoot: parseStringFlag(args, 'transcriptRoot'),
+        settingsPath: parseStringFlag(args, 'settingsPath'),
+        verify: args.includes('--verify'),
+    });
+    const cache = readCacheStats(dataDir);
+    const lastPass = readCronLogStatus(dataDir);
+    if (args.includes('--json')) {
+        console.log(JSON.stringify({ ...report, cache, lastPass }));
+    }
+    else {
+        console.log(formatDoctorReport(report, cache, lastPass));
+    }
+}