codex-cleaner 0.0.1

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,193 @@
+#!/usr/bin/env node
+import { parseArgs } from "node:util";
+import { buildScanReport, archiveOrphanRollouts, checkpointWal, cleanCodex, compactMetadata, emitReport, pruneBackups, requireStoppedOrReadonlyAllowed, scanBackups, scheduleBackupPrune, } from "./cleaner.js";
+import { runWizard } from "./wizard.js";
+const USAGE = `
+codex-cleaner [command] [options]
+
+Commands:
+  (none)            Guided TUI: choose settings, dry-run, then optionally apply
+  clean             Unified dry-run/apply for metadata compaction and stale thread archiving
+  scan              Read-only size, protection, candidate, and optional rollout-linkage report
+  compact-metadata  Cap old threads.title/preview/first_user_message values
+  checkpoint-wal    Run PRAGMA wal_checkpoint(TRUNCATE) for state_5.sqlite
+  archive-orphan-rollouts
+                    Move old DB-unreferenced sessions JSONL into archived_sessions
+  backups scan      Inspect codex-cleaner backup files
+  backups prune     Delete codex-cleaner backup files after a dry-run
+  backups schedule-prune
+                    Schedule a one-shot future backups prune job
+
+Options:
+  --codex-home <path>             Codex home path; defaults to CODEX_HOME or ~/.codex
+  --allow-running-readonly        Allow read-only dry-runs while Codex processes are active
+  --allow-running-orphan-rollout-archive
+                                  Allow archive-orphan-rollouts --apply while Codex is active
+  --skip-archive-stale            Do not include stale thread archiving in clean/TUI flow
+  --archive-orphan-rollouts       clean: move old DB-unreferenced sessions JSONL into archived_sessions
+  --compact-recent-metadata       Also cap recent unprotected metadata; pinned/open/active stay protected
+  --include-logs                  scan: include expensive logs_2.sqlite table stats
+  --include-rollouts              scan: include sessions/archived_sessions linkage scan
+  --prune-logs                    clean: prune/cap logs_2.sqlite and vacuum it
+  --prune-tui-log                 clean: back up and truncate log/codex-tui.log
+  --keep-log-days <n>             log rows to keep when --prune-logs is used; default 7
+  --keep-tui-log-mib <n>          codex-tui.log tail to retain with --prune-tui-log; default 16
+  --older-than-hours <n>          backups prune age threshold; default 48
+  --after-hours <n>               backups schedule-prune delay; default 48
+  --max-log-body-chars <n>        log feedback_log_body cap; default 4096
+  --max-chars <n>                 compact cap; default 1024
+  --keep-recent-days <n>          protect recently updated threads; default 14
+  --archived-only                 compact only archived threads
+  --apply                         write changes; omitted means dry-run
+  --backup-dir <path>             backup destination for mutating commands
+  --codex-command <cmd>           codex executable/npm shim; arbitrary Windows batch wrappers are rejected
+  --confirm-archive-stale         required with clean --apply when archiving stale threads
+  --confirm-archive-orphan-rollouts
+                                  required with clean --apply --archive-orphan-rollouts
+  --confirm-lossy-metadata        required with compact-metadata --apply
+  --confirm-prune-logs            required with clean --apply --prune-logs
+  --confirm-prune-tui-log         required with clean --apply --prune-tui-log
+  --confirm-delete-backups        required with backups prune --apply
+  --confirm-schedule-backup-prune required with backups schedule-prune --apply
+  --json                          emit JSON
+  --help                          show help
+`;
+const COMMANDS = ["scan", "clean", "compact-metadata", "checkpoint-wal", "archive-orphan-rollouts", "backups"];
+const BACKUP_COMMANDS = ["scan", "prune", "schedule-prune"];
+async function main(argv = process.argv.slice(2)) {
+    const parsed = parseArgs({
+        args: argv,
+        allowPositionals: true,
+        options: {
+            "allow-running-readonly": { type: "boolean", default: false },
+            "allow-running-orphan-rollout-archive": { type: "boolean", default: false },
+            "after-hours": { type: "string", default: "48" },
+            apply: { type: "boolean", default: false },
+            "archive-orphan-rollouts": { type: "boolean", default: false },
+            "archived-only": { type: "boolean", default: false },
+            "backup-dir": { type: "string" },
+            "codex-command": { type: "string" },
+            "codex-home": { type: "string" },
+            "compact-recent-metadata": { type: "boolean", default: false },
+            "confirm-archive-stale": { type: "boolean", default: false },
+            "confirm-archive-orphan-rollouts": { type: "boolean", default: false },
+            "confirm-delete-backups": { type: "boolean", default: false },
+            "confirm-lossy-metadata": { type: "boolean", default: false },
+            "confirm-prune-logs": { type: "boolean", default: false },
+            "confirm-prune-tui-log": { type: "boolean", default: false },
+            "confirm-schedule-backup-prune": { type: "boolean", default: false },
+            help: { type: "boolean", short: "h", default: false },
+            "include-rollouts": { type: "boolean", default: false },
+            "include-logs": { type: "boolean", default: false },
+            json: { type: "boolean", default: false },
+            "keep-log-days": { type: "string", default: "7" },
+            "keep-recent-days": { type: "string", default: "14" },
+            "keep-tui-log-mib": { type: "string", default: "16" },
+            "max-log-body-chars": { type: "string", default: "4096" },
+            "max-chars": { type: "string", default: "1024" },
+            "older-than-hours": { type: "string", default: "48" },
+            "prune-logs": { type: "boolean", default: false },
+            "prune-tui-log": { type: "boolean", default: false },
+            "skip-archive-stale": { type: "boolean", default: false },
+        },
+    });
+    if (parsed.values.help) {
+        console.log(USAGE.trim());
+        return 0;
+    }
+    const command = parsed.positionals[0];
+    if (command && !COMMANDS.includes(command)) {
+        console.error(USAGE.trim());
+        return 2;
+    }
+    const options = {
+        allowRunningReadonly: Boolean(parsed.values["allow-running-readonly"]),
+        allowRunningOrphanRolloutArchive: Boolean(parsed.values["allow-running-orphan-rollout-archive"]),
+        afterHours: parsePositiveInt(String(parsed.values["after-hours"]), "--after-hours"),
+        archiveOrphanRollouts: Boolean(parsed.values["archive-orphan-rollouts"]),
+        archiveStale: !parsed.values["skip-archive-stale"],
+        apply: Boolean(parsed.values.apply),
+        archivedOnly: Boolean(parsed.values["archived-only"]),
+        backupDir: parsed.values["backup-dir"],
+        codexCommand: parsed.values["codex-command"],
+        codexHome: parsed.values["codex-home"],
+        compactRecentMetadata: Boolean(parsed.values["compact-recent-metadata"]),
+        confirmArchiveStale: Boolean(parsed.values["confirm-archive-stale"]),
+        confirmArchiveOrphanRollouts: Boolean(parsed.values["confirm-archive-orphan-rollouts"]),
+        confirmDeleteBackups: Boolean(parsed.values["confirm-delete-backups"]),
+        confirmLossyMetadata: Boolean(parsed.values["confirm-lossy-metadata"]),
+        confirmPruneLogs: Boolean(parsed.values["confirm-prune-logs"]),
+        confirmPruneTuiLog: Boolean(parsed.values["confirm-prune-tui-log"]),
+        confirmScheduleBackupPrune: Boolean(parsed.values["confirm-schedule-backup-prune"]),
+        includeLogs: Boolean(parsed.values["include-logs"]),
+        includeRollouts: Boolean(parsed.values["include-rollouts"]),
+        json: Boolean(parsed.values.json),
+        keepLogDays: parsePositiveInt(String(parsed.values["keep-log-days"]), "--keep-log-days"),
+        keepRecentDays: parsePositiveInt(String(parsed.values["keep-recent-days"]), "--keep-recent-days"),
+        keepTuiLogMib: parsePositiveInt(String(parsed.values["keep-tui-log-mib"]), "--keep-tui-log-mib"),
+        maxLogBodyChars: parsePositiveInt(String(parsed.values["max-log-body-chars"]), "--max-log-body-chars"),
+        maxChars: parsePositiveInt(String(parsed.values["max-chars"]), "--max-chars"),
+        olderThanHours: parsePositiveInt(String(parsed.values["older-than-hours"]), "--older-than-hours"),
+        pruneLogs: Boolean(parsed.values["prune-logs"]),
+        pruneTuiLog: Boolean(parsed.values["prune-tui-log"]),
+    };
+    if (!command) {
+        return runWizard(options);
+    }
+    if (command !== "backups") {
+        const mutating = isMutating(command, options);
+        if (!allowsRunningFileOnlyMutation(command, options)) {
+            await requireStoppedOrReadonlyAllowed({
+                allowRunningReadonly: options.allowRunningReadonly,
+                mutating,
+            });
+        }
+    }
+    if (command === "backups") {
+        const backupCommand = parseBackupCommand(parsed.positionals[1]);
+        const report = backupCommand === "scan"
+            ? scanBackups(options)
+            : backupCommand === "prune"
+                ? pruneBackups(options)
+                : await scheduleBackupPrune(options);
+        emitReport(report, options.json);
+        return 0;
+    }
+    const report = command === "scan"
+        ? buildScanReport(options)
+        : command === "clean"
+            ? await cleanCodex(options)
+            : command === "compact-metadata"
+                ? await compactMetadata(options)
+                : command === "archive-orphan-rollouts"
+                    ? archiveOrphanRollouts(options)
+                    : await checkpointWal(options);
+    emitReport(report, options.json);
+    return 0;
+}
+function parseBackupCommand(value) {
+    const command = (value ?? "scan");
+    if (!BACKUP_COMMANDS.includes(command)) {
+        throw new Error(`Unknown backups command: ${String(value)}\n${USAGE.trim()}`);
+    }
+    return command;
+}
+function isMutating(command, options) {
+    return command !== "scan" && options.apply;
+}
+function allowsRunningFileOnlyMutation(command, options) {
+    return command === "archive-orphan-rollouts" && options.apply && options.allowRunningOrphanRolloutArchive;
+}
+function parsePositiveInt(raw, name) {
+    const value = Number(raw);
+    if (!Number.isInteger(value) || value <= 0) {
+        throw new Error(`${name} must be a positive integer`);
+    }
+    return value;
+}
+main().then((code) => {
+    process.exitCode = code;
+}, (error) => {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exitCode = 1;
+});

package/dist/types.d.ts

@@ -0,0 +1,47 @@
+export type BackupCommand = "scan" | "prune" | "schedule-prune";
+export type CleanerCommand = "scan" | "clean" | "compact-metadata" | "checkpoint-wal" | "archive-orphan-rollouts" | "backups";
+export type CleanerOptions = {
+    allowRunningOrphanRolloutArchive: boolean;
+    allowRunningReadonly: boolean;
+    afterHours: number;
+    archiveOrphanRollouts: boolean;
+    archiveStale: boolean;
+    apply: boolean;
+    archivedOnly: boolean;
+    backupDir?: string;
+    codexCommand?: string;
+    codexHome?: string;
+    compactRecentMetadata: boolean;
+    confirmArchiveStale: boolean;
+    confirmArchiveOrphanRollouts: boolean;
+    confirmDeleteBackups: boolean;
+    confirmLossyMetadata: boolean;
+    confirmPruneLogs: boolean;
+    confirmPruneTuiLog: boolean;
+    confirmScheduleBackupPrune: boolean;
+    includeLogs: boolean;
+    includeRollouts: boolean;
+    json: boolean;
+    keepLogDays: number;
+    keepRecentDays: number;
+    keepTuiLogMib: number;
+    maxLogBodyChars: number;
+    maxChars: number;
+    olderThanHours: number;
+    pruneLogs: boolean;
+    pruneTuiLog: boolean;
+};
+export type BlockingProcess = {
+    pid: number;
+    name: string;
+    commandLine: string;
+};
+export type ThreadProtection = {
+    pinnedIds: Set<string>;
+    heartbeatIds: Set<string>;
+    activeGoalIds: Set<string>;
+};
+export type CompactWhere = {
+    sql: string;
+    params: Record<string, string | number>;
+};

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/wizard.d.ts

@@ -0,0 +1,2 @@
+import type { CleanerOptions } from "./types.js";
+export declare function runWizard(options: CleanerOptions): Promise<number>;

package/dist/wizard.js

@@ -0,0 +1,412 @@
+import { confirm, input, select } from "@inquirer/prompts";
+import path from "node:path";
+import pc from "picocolors";
+import { buildScanReport, cleanCodex, findBlockingProcesses, requireStoppedOrReadonlyAllowed, scheduleBackupPrune, } from "./cleaner.js";
+export async function runWizard(options) {
+    if (!process.stdin.isTTY || !process.stdout.isTTY) {
+        throw new Error("The guided TUI needs an interactive terminal. Use `codex-cleaner scan` for noninteractive runs.");
+    }
+    printIntro();
+    const initialBlockers = await findBlockingProcesses();
+    if (initialBlockers.length) {
+        console.log(pc.yellow(`Codex appears to be running (${initialBlockers.length} matching processes).`));
+        console.log(pc.dim("This wizard can still dry-run, but apply will be disabled until Codex is fully closed.\n"));
+    }
+    const wizardMode = await askWizardMode();
+    const keepRecentDays = wizardMode === "recommended" ? options.keepRecentDays : await askKeepRecentDays(options.keepRecentDays);
+    const maxChars = wizardMode === "recommended" ? options.maxChars : await askMaxChars(options.maxChars);
+    const compactRecentMetadata = wizardMode === "recommended" ? false : await askCompactRecentMetadata();
+    const archiveStale = wizardMode === "recommended" ? true : await askArchiveStale();
+    const archiveOrphanRollouts = wizardMode === "recommended" ? true : await askArchiveOrphanRollouts();
+    const pruneLogs = wizardMode === "recommended" ? true : await askPruneLogs();
+    const pruneTuiLog = wizardMode === "recommended" ? true : await askPruneTuiLog();
+    const includeRollouts = wizardMode === "recommended"
+        ? false
+        : await confirm({
+            default: false,
+            message: "Also scan orphan rollout files? This is slower and stays dry-run only.",
+        });
+    const runDryRun = await confirm({
+        default: true,
+        message: "Run the dry-run scan now?",
+    });
+    const dryRunOptions = {
+        ...options,
+        allowRunningReadonly: true,
+        archiveOrphanRollouts,
+        archiveStale,
+        apply: false,
+        archivedOnly: false,
+        compactRecentMetadata,
+        confirmArchiveStale: false,
+        confirmArchiveOrphanRollouts: false,
+        confirmLossyMetadata: false,
+        confirmPruneLogs: false,
+        confirmPruneTuiLog: false,
+        includeLogs: false,
+        includeRollouts,
+        pruneLogs,
+        pruneTuiLog,
+        keepRecentDays,
+        maxChars,
+        json: false,
+    };
+    if (!runDryRun) {
+        printDryRunCommand(dryRunOptions);
+        return 0;
+    }
+    console.log(pc.dim("\nScanning Codex metadata..."));
+    const report = buildScanReport(dryRunOptions);
+    printDryRunSummary(report);
+    const compactRows = numberAt(report, "compactMetadataCandidates", "rows");
+    const archiveRows = numberAt(report, "staleArchiveCandidates", "archive_call_rows");
+    const orphanRolloutRows = numberAt(report, "orphanRolloutArchiveCandidates", "files");
+    const logRows = numberAt(report, "logCleanupCandidates", "delete_rows") + numberAt(report, "logCleanupCandidates", "cap_rows");
+    const tuiLogMib = numberAt(report, "tuiLogCleanupCandidates", "reclaimable_mib");
+    const vacuumMib = numberAt(report, "databaseSpace", "state_5.sqlite", "free_mib");
+    if (!compactRows && !archiveRows && !orphanRolloutRows && !logRows && !tuiLogMib && vacuumMib < 1) {
+        console.log(pc.green("\nNo cleanup candidates found under this policy."));
+        return 0;
+    }
+    const proceed = await waitForApplyConfirmation();
+    if (!proceed) {
+        console.log(pc.dim("\nNo changes made. To apply later, run:"));
+        printApplyCommand(dryRunOptions);
+        return 0;
+    }
+    await requireStoppedOrReadonlyAllowed({ allowRunningReadonly: false, mutating: true });
+    console.log(pc.dim("\nApplying cleanup..."));
+    const applyReport = await cleanCodex({
+        ...dryRunOptions,
+        apply: true,
+        confirmArchiveStale: true,
+        confirmArchiveOrphanRollouts: true,
+        confirmLossyMetadata: true,
+        confirmPruneLogs: true,
+        confirmPruneTuiLog: true,
+    });
+    printApplySummary(recordAt(applyReport, "compact"), nullableRecordAt(applyReport, "archive"), nullableRecordAt(applyReport, "orphanRollouts"), recordAt(applyReport, "vacuum"), nullableRecordAt(applyReport, "logs"), nullableRecordAt(applyReport, "tuiLog"), recordAt(applyReport, "checkpoint"));
+    await offerScheduledBackupCleanup(dryRunOptions, applyReport);
+    return 0;
+}
+async function waitForApplyConfirmation() {
+    while (true) {
+        const applyNow = await confirm({
+            default: false,
+            message: "Apply this cleanup now? Backups will be created first.",
+        });
+        if (!applyNow)
+            return false;
+        const blockers = await findBlockingProcesses();
+        if (!blockers.length)
+            return true;
+        console.log(pc.yellow(`\nCodex is still running (${blockers.length} matching processes). No changes were applied.`));
+        console.log(pc.dim("Close Codex completely before applying DB or WAL cleanup."));
+        const retry = await confirm({
+            default: true,
+            message: "Check again after closing Codex?",
+        });
+        if (!retry)
+            return false;
+    }
+}
+async function askWizardMode() {
+    return select({
+        choices: [
+            {
+                description: "Use the normal safe defaults, then dry-run before apply.",
+                name: "Run recommended cleanup",
+                value: "recommended",
+            },
+            {
+                description: "Choose retention windows, metadata cap, log cleanup, and archive behavior.",
+                name: "Customize settings",
+                value: "custom",
+            },
+        ],
+        default: "recommended",
+        message: "How do you want to run codex-cleaner?",
+    });
+}
+async function askKeepRecentDays(currentDefault) {
+    console.log(pc.bold("\nRecent thread protection"));
+    console.log(pc.dim("Threads updated inside this window are always kept untouched. Pinned, heartbeat/app-permission, and active-goal threads are also protected."));
+    const choices = [
+        { name: "14 days (recommended)", value: 14 },
+        { name: "30 days", value: 30 },
+        { name: "7 days", value: 7 },
+        { name: `Current flag default (${currentDefault} days)`, value: currentDefault },
+        { name: "Custom", value: "custom" },
+    ];
+    const selected = await select({
+        choices: dedupeChoiceValues(choices),
+        default: choices.some((choice) => choice.value === currentDefault) ? currentDefault : 14,
+        message: "How far back should active/recent threads be protected?",
+    });
+    if (selected !== "custom")
+        return selected;
+    return askPositiveInteger("Days to protect", String(currentDefault));
+}
+async function askMaxChars(currentDefault) {
+    console.log(pc.bold("\nMetadata cap"));
+    console.log(pc.dim("This caps only old thread display/search metadata: title, preview, first_user_message. It does not delete threads or rollout JSONL used by CodexMeter."));
+    const choices = [
+        { name: "1024 chars (recommended)", value: 1024 },
+        { name: "2048 chars", value: 2048 },
+        { name: "4096 chars", value: 4096 },
+        { name: `Current flag default (${currentDefault} chars)`, value: currentDefault },
+        { name: "Custom", value: "custom" },
+    ];
+    const selected = await select({
+        choices: dedupeChoiceValues(choices),
+        default: choices.some((choice) => choice.value === currentDefault) ? currentDefault : 1024,
+        message: "How much old metadata should each field keep?",
+    });
+    if (selected !== "custom")
+        return selected;
+    return askPositiveInteger("Characters to keep per metadata field", String(currentDefault));
+}
+async function askCompactRecentMetadata() {
+    console.log(pc.bold("\nRecent metadata compaction"));
+    console.log(pc.dim("This also caps recent unprotected thread display/search metadata. Pinned, app/heartbeat, and active-goal threads still stay untouched, and rollout JSONL context is not changed."));
+    return confirm({
+        default: false,
+        message: "Also compact recent unprotected metadata?",
+    });
+}
+async function askArchiveStale() {
+    console.log(pc.bold("\nStale thread archiving"));
+    console.log(pc.dim("Old unpinned threads outside the recent window can be moved from sessions to archived_sessions using Codex's own archive API. Rollout JSONL is retained for history and CodexMeter."));
+    return confirm({
+        default: true,
+        message: "Include stale thread archiving in this cleanup?",
+    });
+}
+async function askArchiveOrphanRollouts() {
+    console.log(pc.bold("\nOrphan rollout archiving"));
+    console.log(pc.dim("Old rollout JSONL files in sessions that are not referenced by SQLite can be moved to archived_sessions. This keeps active session scans lean and does not delete the files."));
+    return confirm({
+        default: true,
+        message: "Move old DB-unreferenced rollout files out of sessions?",
+    });
+}
+async function askPruneLogs() {
+    console.log(pc.bold("\nLog cleanup"));
+    console.log(pc.dim("This prunes old logs_2.sqlite rows and caps giant feedback_log_body payloads. It does not touch threads or rollout JSONL."));
+    return confirm({
+        default: true,
+        message: "Include logs_2.sqlite cleanup in this cleanup?",
+    });
+}
+async function askPruneTuiLog() {
+    console.log(pc.bold("\nTUI log file cleanup"));
+    console.log(pc.dim("This backs up log/codex-tui.log, then keeps only the newest log tail. It does not touch SQLite, threads, or rollout JSONL."));
+    return confirm({
+        default: true,
+        message: "Trim codex-tui.log to the newest log tail?",
+    });
+}
+async function askPositiveInteger(message, defaultValue) {
+    const value = await input({
+        default: defaultValue,
+        message,
+        validate: (raw) => {
+            const parsed = Number(raw);
+            return Number.isInteger(parsed) && parsed > 0 ? true : "Enter a positive integer.";
+        },
+    });
+    return Number(value);
+}
+function printIntro() {
+    console.log(pc.bold("codex-cleaner"));
+    console.log("Guided dry-run first. Apply only after you see exactly what would change.\n");
+}
+function printDryRunSummary(report) {
+    console.log(pc.bold("\nDry-run summary"));
+    const policy = recordAt(report, "policy");
+    const files = recordAt(report, "files");
+    const stateFile = recordAt(files, "state_5.sqlite");
+    const stateMain = recordAt(stateFile, "main");
+    const stateWal = recordAt(stateFile, "wal");
+    const protection = recordAt(report, "protection");
+    const threads = recordAt(report, "threads");
+    const candidates = recordAt(report, "compactMetadataCandidates");
+    console.log(`  Codex home: ${String(report.codexHome)}`);
+    console.log(`  Recent window: ${String(policy.keepRecentDays)} days`);
+    console.log(`  Metadata cap: ${String(policy.maxChars)} chars`);
+    console.log(`  Compact recent metadata: ${policy.compactRecentMetadata ? "yes" : "no"}`);
+    console.log(`  state_5.sqlite: ${formatMib(stateMain.mib)} main, ${formatMib(stateWal.mib)} WAL`);
+    console.log(`  Protected threads: ${String(protection.totalUniqueProtectedThreads)} (${String(protection.pinnedThreads)} pinned, ${String(protection.heartbeatThreads)} app/heartbeat, ${String(protection.activeGoalThreads)} active goals)`);
+    console.log(`  Thread rows: ${String(threads.rows)}`);
+    console.log(pc.green(`  Recommended metadata compaction: ${String(candidates.rows)} rows, about ${formatMib(candidates.estimated_savings_mib)} old metadata payload reduction`));
+    const archive = recordAt(report, "staleArchiveCandidates");
+    if (Object.keys(archive).length) {
+        console.log(pc.green(`  Stale archiving: ${String(archive.expected_archived_rows)} threads via ${String(archive.archive_call_rows)} Codex archive calls, moving about ${formatMib(archive.expected_archived_rollout_size_mib)} of rollout JSONL`));
+        if (Number(archive.blocked_by_descendant_safety) > 0) {
+            console.log(pc.yellow(`  Skipped ${String(archive.blocked_by_descendant_safety)} stale roots because their spawned descendants are still recent or protected.`));
+        }
+    }
+    const orphanRollouts = recordAt(report, "orphanRolloutArchiveCandidates");
+    if (Object.keys(orphanRollouts).length) {
+        console.log(pc.green(`  Orphan rollout archiving: move ${String(orphanRollouts.files)} old DB-unreferenced JSONL files (${formatMib(orphanRollouts.size_mib)}) from sessions to archived_sessions; remove ${String(orphanRollouts.empty_dir_candidates ?? 0)} empty dirs`));
+        if (Number(orphanRollouts.skipped_recent_files) > 0) {
+            console.log(pc.yellow(`  Skipped ${String(orphanRollouts.skipped_recent_files)} orphan rollouts inside the recent window.`));
+        }
+        if (Number(orphanRollouts.skipped_session_indexed_files) > 0) {
+            console.log(pc.yellow(`  Skipped ${String(orphanRollouts.skipped_session_indexed_files)} DB-orphaned rollouts still present in session_index.jsonl.`));
+        }
+    }
+    const stateSpace = recordAt(report, "databaseSpace", "state_5.sqlite");
+    if (Number(stateSpace.free_mib) >= 1) {
+        console.log(pc.green(`  State vacuum: reclaim about ${formatMib(stateSpace.free_mib)} from SQLite freelist`));
+    }
+    const logCleanup = recordAt(report, "logCleanupCandidates");
+    if (Object.keys(logCleanup).length) {
+        console.log(pc.green(`  Logs cleanup: delete ${String(logCleanup.delete_rows)} old rows and cap ${String(logCleanup.cap_rows)} oversized log payloads`));
+    }
+    const tuiLogCleanup = recordAt(report, "tuiLogCleanupCandidates");
+    if (Object.keys(tuiLogCleanup).length) {
+        console.log(pc.green(`  TUI log cleanup: reclaim about ${formatMib(tuiLogCleanup.reclaimable_mib)} while keeping newest ${formatMib(tuiLogCleanup.keep_mib)}`));
+    }
+    console.log(pc.dim("  Preserves thread rows and rollout JSONL; orphan rollout files are moved, not deleted."));
+    const rollouts = recordAt(report, "rollouts");
+    if (Object.keys(rollouts).length) {
+        console.log(pc.dim(`  Rollout scan: ${String(rollouts.orphanFiles)} orphan files (${formatMib(rollouts.orphanSizeMib)}); deletion is not part of this apply flow.`));
+    }
+}
+function printApplySummary(report, archiveReport, orphanRolloutsReport, vacuumReport, logsReport, tuiLogReport, checkpointReport) {
+    const before = recordAt(report, "before");
+    const after = recordAt(report, "after");
+    console.log(pc.bold("\nApply complete"));
+    if (archiveReport) {
+        const archiveBefore = recordAt(archiveReport, "before");
+        const appServer = recordAt(archiveReport, "appServerResult");
+        console.log(`  Archived stale threads: ${String(appServer.succeeded ?? 0)} archive calls for up to ${String(archiveBefore.expected_archived_rows ?? 0)} threads`);
+        if (Number(appServer.failed ?? 0) > 0) {
+            console.log(pc.yellow(`  Archive errors: ${String(appServer.failed)}; rerun dry-run to inspect remaining candidates.`));
+        }
+        console.log(`  Archive backup: ${String(archiveReport.backupPath)}`);
+    }
+    if (orphanRolloutsReport) {
+        console.log(`  Archived orphan rollouts: moved ${String(orphanRolloutsReport.movedFiles ?? 0)} files (${formatMib(orphanRolloutsReport.movedMib)})`);
+        if (orphanRolloutsReport.manifestPath) {
+            console.log(`  Orphan rollout manifest: ${String(orphanRolloutsReport.manifestPath)}`);
+        }
+        console.log(`  Empty session/archive dirs removed: ${String(orphanRolloutsReport.prunedEmptyDirs ?? 0)}`);
+    }
+    console.log(`  Changed rows: ${String(report.changedRows)}`);
+    if (report.backupPath)
+        console.log(`  Metadata backup: ${String(report.backupPath)}`);
+    console.log(`  Remaining eligible rows: ${String(after.rows)} (was ${String(before.rows)})`);
+    if (Object.keys(vacuumReport).length) {
+        const vacuumBefore = recordAt(vacuumReport, "before", "main");
+        const vacuumAfter = recordAt(vacuumReport, "after", "main");
+        console.log(`  State vacuum: ${formatMib(vacuumBefore.mib)} -> ${formatMib(vacuumAfter.mib)}`);
+    }
+    if (logsReport) {
+        console.log(`  Logs cleanup: deleted ${String(logsReport.deletedRows ?? 0)} rows, capped ${String(logsReport.cappedRows ?? 0)} rows`);
+    }
+    if (tuiLogReport) {
+        const tuiBefore = recordAt(tuiLogReport, "before");
+        const tuiAfter = recordAt(tuiLogReport, "after");
+        console.log(`  TUI log cleanup: ${formatMib(tuiBefore.current_mib)} -> ${formatMib(tuiAfter.current_mib)}`);
+    }
+    const checkpointBefore = recordAt(checkpointReport, "before", "wal");
+    const checkpointAfter = recordAt(checkpointReport, "after", "wal");
+    console.log(`  WAL checkpoint: ${formatMib(checkpointBefore.mib)} -> ${formatMib(checkpointAfter.mib)}`);
+    const backupPaths = [archiveReport, vacuumReport, logsReport, tuiLogReport, report]
+        .map((entry) => entry?.backupPath)
+        .filter((value) => typeof value === "string");
+    if (backupPaths.length) {
+        console.log(pc.dim(`  Backups are in ${path.dirname(String(backupPaths[0]))}. Keep them until Codex looks right, then delete them to reclaim disk.`));
+    }
+}
+async function offerScheduledBackupCleanup(options, applyReport) {
+    const backupPaths = [
+        nullableRecordAt(applyReport, "archive"),
+        recordAt(applyReport, "compact"),
+        recordAt(applyReport, "vacuum"),
+        nullableRecordAt(applyReport, "logs"),
+        nullableRecordAt(applyReport, "tuiLog"),
+    ]
+        .map((entry) => entry?.backupPath)
+        .filter((value) => typeof value === "string");
+    if (!backupPaths.length)
+        return;
+    const schedule = await confirm({
+        default: false,
+        message: `Schedule backup cleanup in ${options.afterHours} hours? You can cancel it before then.`,
+    });
+    if (!schedule)
+        return;
+    let report;
+    try {
+        report = await scheduleBackupPrune({
+            ...options,
+            apply: true,
+            confirmScheduleBackupPrune: true,
+        });
+    }
+    catch (error) {
+        console.log(pc.yellow(`Could not schedule backup cleanup: ${error instanceof Error ? error.message : String(error)}`));
+        return;
+    }
+    console.log(pc.bold("\nBackup cleanup scheduled"));
+    console.log(`  Runs: ${String(recordAt(report, "policy").runAtUtc)}`);
+    console.log(`  Command: ${String(report.command)}`);
+    if (report.taskName)
+        console.log(`  Task: ${String(report.taskName)}`);
+    if (report.jobId)
+        console.log(`  Job: ${String(report.jobId)}`);
+    console.log(`  Cancel: ${String(report.cancelCommand)}`);
+}
+function printDryRunCommand(options) {
+    const archiveFlag = options.archiveStale ? "" : " --skip-archive-stale";
+    const orphanFlag = options.archiveOrphanRollouts ? " --archive-orphan-rollouts" : "";
+    const logsFlag = options.pruneLogs ? " --prune-logs" : "";
+    const tuiLogFlag = options.pruneTuiLog ? " --prune-tui-log" : "";
+    const recentFlag = options.compactRecentMetadata ? " --compact-recent-metadata" : "";
+    console.log(`  npx codex-cleaner@latest --allow-running-readonly clean --max-chars ${options.maxChars} --keep-recent-days ${options.keepRecentDays}${archiveFlag}${orphanFlag}${logsFlag}${tuiLogFlag}${recentFlag}`);
+}
+function printApplyCommand(options) {
+    const archiveFlags = options.archiveStale ? " --confirm-archive-stale" : " --skip-archive-stale";
+    const orphanFlags = options.archiveOrphanRollouts
+        ? " --archive-orphan-rollouts --confirm-archive-orphan-rollouts"
+        : "";
+    const logsFlags = options.pruneLogs ? " --prune-logs --confirm-prune-logs" : "";
+    const tuiLogFlags = options.pruneTuiLog ? " --prune-tui-log --confirm-prune-tui-log" : "";
+    const recentFlag = options.compactRecentMetadata ? " --compact-recent-metadata" : "";
+    console.log(`  npx codex-cleaner@latest clean --max-chars ${options.maxChars} --keep-recent-days ${options.keepRecentDays} --apply --confirm-lossy-metadata${archiveFlags}${orphanFlags}${logsFlags}${tuiLogFlags}${recentFlag}`);
+}
+function recordAt(source, ...keys) {
+    let current = source;
+    for (const key of keys) {
+        if (!current || typeof current !== "object" || Array.isArray(current))
+            return {};
+        current = current[key];
+    }
+    return current && typeof current === "object" && !Array.isArray(current) ? current : {};
+}
+function nullableRecordAt(source, ...keys) {
+    const value = recordAt(source, ...keys);
+    return Object.keys(value).length ? value : null;
+}
+function numberAt(source, ...keys) {
+    const parent = recordAt(source, ...keys.slice(0, -1));
+    const value = parent[keys[keys.length - 1] ?? ""];
+    return typeof value === "number" && Number.isFinite(value) ? value : 0;
+}
+function formatMib(value) {
+    return typeof value === "number" && Number.isFinite(value) ? `${value.toLocaleString()} MiB` : "unknown";
+}
+function dedupeChoiceValues(choices) {
+    const seen = new Set();
+    const result = [];
+    for (const choice of choices) {
+        if (seen.has(choice.value))
+            continue;
+        seen.add(choice.value);
+        result.push(choice);
+    }
+    return result;
+}