claude-dev-env 8.28.1 → 8.29.1

package/.agents/skills/codex-cleanse/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: codex-cleanse
+description: Preview or archive local Codex sessions after seven days without activity. Use for an on-demand session cleanup or a local scheduled archive run across a selected Codex home.
+---
+
+# Codex cleanse
+
+Run `scripts/cleanse.mjs` with Node.js from this skill directory. Select the account with `--codex-home <absolute path>`. Without that flag, the command uses `CODEX_HOME`, then the current user's `.codex` directory. Use `--codex-path <absolute executable path>` when Codex is outside the supported native install locations.
+
+Preview first:
+
+```text
+node scripts/cleanse.mjs --stdio --codex-home <absolute path>
+```
+
+Archive the eligible sessions after reviewing the preview:
+
+```text
+node scripts/cleanse.mjs --stdio --codex-home <absolute path> --apply
+```
+
+The default cutoff is seven days. `--inactive-days <number>` changes it. When the local Codex app's task listing is available, repeat `--exclude-thread-id <UUID>` for the current task and each active desktop task. Run the command on demand when the user requests archiving. The command starts a separate local app-server process and cannot see other clients' runtime status. It checks the stored activity time and rollout file modification time before each archive request.
+
+The command lists indexed sessions through `thread/list` and discovers other session IDs from rollout filenames under the selected home's `sessions` directory.
+It reads their metadata through `thread/read` without opening conversation content.
+It re-reads each candidate, checks its activity time, rollout file modification time, exclusions, and unarchived descendants, then calls `thread/archive` for eligible leaves before parents.
+It confirms archived IDs through a final archived listing or a native read of the archived path for sessions omitted from that listing.
+After option parsing succeeds, the command writes one JSON report to stdout and progress to stderr. Option-parsing errors produce a stderr diagnostic and exit with code 1 before starting the Codex server.
+Zero-byte rollout files count as `emptyRollout` skips because the native API cannot read their metadata.
+Discovery failures stop archive writes and exit with a nonzero status.
+An archive candidate failure stops later archive requests. Earlier requests still receive readback.
+Archive and readback failures remain in the report and produce a nonzero exit status.
+
+After a successful apply run archives sessions, refresh the active task exclusions and run again. Stop when a successful run reports zero archives.
+
+Run the archive task on the local machine with the app and selected account available. A cloud task cannot read this machine's Codex home. Codex session archiving leaves managed worktrees in place. The desktop setting at Settings > Worktrees > General > Automatically delete old worktrees controls separate worktree cleanup by retained count.

package/.agents/skills/codex-cleanse/config/constants.mjs

@@ -0,0 +1,11 @@
+export const DEFAULT_INACTIVE_DAYS = 7;
+export const MILLISECONDS_PER_DAY = 86_400_000;
+export const MILLISECONDS_PER_SECOND = 1_000;
+export const PAGE_SIZE = 1_000;
+export const REQUEST_TIMEOUT_MILLISECONDS = 30_000;
+export const SOURCE_KINDS = [
+    'cli', 'vscode', 'exec', 'appServer', 'subAgent', 'subAgentReview',
+    'subAgentCompact', 'subAgentThreadSpawn', 'subAgentOther', 'unknown',
+];
+export const THREAD_ID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+export const ROLLOUT_FILENAME_PATTERN = /^rollout-\d{4}-\d{2}-\d{2}T\d{2}-\d{2}-\d{2}-([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})\.jsonl$/i;

package/.agents/skills/codex-cleanse/config/constants.test.mjs

@@ -0,0 +1,42 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+
+import {
+    DEFAULT_INACTIVE_DAYS,
+    MILLISECONDS_PER_DAY,
+    MILLISECONDS_PER_SECOND,
+    PAGE_SIZE,
+    REQUEST_TIMEOUT_MILLISECONDS,
+    ROLLOUT_FILENAME_PATTERN,
+    SOURCE_KINDS,
+    THREAD_ID_PATTERN,
+} from './constants.mjs';
+
+test('cleanse defaults to a seven-day cutoff and bounded requests', () => {
+    assert.equal(DEFAULT_INACTIVE_DAYS, 7);
+    assert.equal(MILLISECONDS_PER_DAY, 86_400_000);
+    assert.equal(MILLISECONDS_PER_SECOND, 1_000);
+    assert.equal(PAGE_SIZE, 1_000);
+    assert.equal(REQUEST_TIMEOUT_MILLISECONDS, 30_000);
+});
+
+test('session listing includes every supported source kind', () => {
+    assert.deepEqual(SOURCE_KINDS, [
+        'cli', 'vscode', 'exec', 'appServer', 'subAgent', 'subAgentReview',
+        'subAgentCompact', 'subAgentThreadSpawn', 'subAgentOther', 'unknown',
+    ]);
+});
+
+test('thread IDs accept UUID spelling and reject malformed IDs', () => {
+    assert.equal(THREAD_ID_PATTERN.test('12345678-1234-ABCD-1234-123456789ABC'), true);
+    assert.equal(THREAD_ID_PATTERN.test('12345678-1234-ABCD-1234-123456789AB'), false);
+    assert.equal(THREAD_ID_PATTERN.test('prefix-12345678-1234-ABCD-1234-123456789ABC'), false);
+});
+
+test('rollout filenames yield the thread ID and reject other files', () => {
+    const threadId = '12345678-1234-ABCD-1234-123456789ABC';
+    const filename = `rollout-2026-09-30T12-34-56-${threadId}.jsonl`;
+    assert.equal(ROLLOUT_FILENAME_PATTERN.exec(filename)?.[1], threadId);
+    assert.equal(ROLLOUT_FILENAME_PATTERN.test(`${filename}.bak`), false);
+    assert.equal(ROLLOUT_FILENAME_PATTERN.test(`other-${filename}`), false);
+});

package/.agents/skills/codex-cleanse/scripts/cleanse.mjs

@@ -0,0 +1,458 @@
+import { spawn } from 'node:child_process';
+import { accessSync, constants, existsSync, lstatSync, readdirSync, realpathSync, statSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { basename, delimiter, isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { createInterface } from 'node:readline';
+import { fileURLToPath } from 'node:url';
+
+import {
+    DEFAULT_INACTIVE_DAYS,
+    MILLISECONDS_PER_DAY,
+    MILLISECONDS_PER_SECOND,
+    PAGE_SIZE,
+    REQUEST_TIMEOUT_MILLISECONDS,
+    ROLLOUT_FILENAME_PATTERN,
+    SOURCE_KINDS,
+    THREAD_ID_PATTERN,
+} from '../config/constants.mjs';
+
+const scriptPath = fileURLToPath(import.meta.url);
+
+export function parseOptions(allArguments, environment = process.env) {
+    const options = {
+        apply: false,
+        inactiveDays: DEFAULT_INACTIVE_DAYS,
+        home: resolve(environment.CODEX_HOME || join(homedir(), '.codex')),
+        codexPath: null,
+        excludedThreadIds: new Set(),
+    };
+    for (let index = 0; index < allArguments.length; index += 1) {
+        const argument = allArguments[index];
+        if (argument === '--apply') {
+            options.apply = true;
+            continue;
+        }
+        if (argument === '--stdio') {
+            continue;
+        }
+        const argumentValue = allArguments[++index];
+        if (!argumentValue || argumentValue.startsWith('--')) throw new Error(`Missing value for ${argument}`);
+        if (argument === '--inactive-days') options.inactiveDays = Number(argumentValue);
+        else if (argument === '--codex-home') options.home = resolve(argumentValue);
+        else if (argument === '--codex-path') options.codexPath = resolve(argumentValue);
+        else if (argument === '--exclude-thread-id') options.excludedThreadIds.add(argumentValue.toLowerCase());
+        else throw new Error(`Unknown option: ${argument}`);
+    }
+    if (!Number.isFinite(options.inactiveDays) || options.inactiveDays < 0) {
+        throw new Error('--inactive-days must be a nonnegative number');
+    }
+    if (Number.isNaN(new Date(Date.now() - options.inactiveDays * MILLISECONDS_PER_DAY).getTime())) {
+        throw new Error('--inactive-days must produce a valid cutoff date');
+    }
+    for (const eachThreadId of options.excludedThreadIds) {
+        if (!THREAD_ID_PATTERN.test(eachThreadId)) throw new Error('Invalid excluded thread ID');
+    }
+    return options;
+}
+
+export function assertSelectedHome(serverHome, selectedHome) {
+    try {
+        if (serverHome && isSameCanonicalPath(serverHome, selectedHome)) return;
+    } catch (error) {
+        throw new Error('Codex server home differs from selected home', { cause: error });
+    }
+    throw new Error('Codex server home differs from selected home');
+}
+
+function isExecutableFile(executablePath) {
+    try {
+        if (!statSync(executablePath).isFile()) return false;
+        accessSync(executablePath, constants.X_OK);
+        return true;
+    } catch {
+        return false;
+    }
+}
+
+export function findCodexPath(options, environment = process.env) {
+    if (options.codexPath) {
+        if (!existsSync(options.codexPath)) throw new Error(`Codex executable not found: ${options.codexPath}`);
+        return options.codexPath;
+    }
+    const executableName = process.platform === 'win32' ? 'codex.exe' : 'codex';
+    const allCandidates = [
+        environment.APPDATA && join(environment.APPDATA, 'npm', 'node_modules', '@openai', 'codex',
+            'node_modules', '@openai', 'codex-win32-x64', 'vendor', 'x86_64-pc-windows-msvc', 'bin', executableName),
+        join(options.home, 'packages', 'standalone', 'current', 'bin', executableName),
+        environment.LOCALAPPDATA && join(environment.LOCALAPPDATA, 'Programs', 'OpenAI', 'Codex', 'bin', executableName),
+    ].filter(Boolean);
+    const pathKey = process.platform === 'win32'
+        ? Object.keys(environment).find(eachKey => eachKey.toUpperCase() === 'PATH') : 'PATH';
+    for (const eachDirectory of (environment[pathKey] || '').split(delimiter).filter(Boolean)) {
+        allCandidates.push(join(eachDirectory, executableName));
+        if (process.platform === 'win32') {
+            allCandidates.push(join(eachDirectory, 'node_modules', '@openai', 'codex',
+                'node_modules', '@openai', 'codex-win32-x64', 'vendor', 'x86_64-pc-windows-msvc', 'bin', executableName));
+        }
+    }
+    const codexPath = allCandidates.find(isExecutableFile);
+    if (!codexPath) throw new Error('Codex executable not found; pass --codex-path');
+    return codexPath;
+}
+
+export function openDaemon(options, environment = process.env) {
+    const codexPath = findCodexPath(options, environment);
+    const child = spawn(codexPath, ['app-server'], {
+        env: { ...environment, CODEX_HOME: options.home },
+        stdio: ['pipe', 'pipe', 'pipe'],
+        windowsHide: true,
+    });
+    const pendingById = new Map();
+    let nextId = 1;
+    let transportFailure = null;
+    let stderrTail = '';
+    const failPending = error => {
+        transportFailure = error;
+        for (const { reject, timer } of pendingById.values()) {
+            clearTimeout(timer);
+            reject(error);
+        }
+        pendingById.clear();
+    };
+    createInterface({ input: child.stdout }).on('line', line => {
+        let message;
+        try { message = JSON.parse(line); } catch { return; }
+        const pending = pendingById.get(message.id);
+        if (!pending) return;
+        clearTimeout(pending.timer);
+        pendingById.delete(message.id);
+        if (message.error) pending.reject(new Error(JSON.stringify(message.error)));
+        else pending.resolve(message.result);
+    });
+    child.stderr.on('data', chunk => { stderrTail = `${stderrTail}${chunk}`.slice(-2_000); });
+    child.stdin.on('error', failPending);
+    child.on('error', failPending);
+    child.on('exit', code => failPending(new Error(`Codex daemon proxy exited with code ${code}`)));
+    const request = (method, params = {}) => {
+        if (transportFailure) return Promise.reject(transportFailure);
+        const id = nextId++;
+        return new Promise((resolveRequest, rejectRequest) => {
+            const timer = setTimeout(() => {
+                failPending(new Error(`Codex daemon request timed out: ${method}; ${stderrTail.trim()}`));
+            }, REQUEST_TIMEOUT_MILLISECONDS);
+            pendingById.set(id, { resolve: resolveRequest, reject: rejectRequest, timer });
+            child.stdin.write(`${JSON.stringify({ jsonrpc: '2.0', id, method, params })}\n`);
+        });
+    };
+    return {
+        request,
+        async initialize() {
+            const handshake = await request('initialize', {
+                clientInfo: { name: 'codex_cleanse', title: 'Codex Cleanse', version: '1.0.0' },
+                capabilities: { experimentalApi: true },
+            });
+            assertSelectedHome(handshake?.codexHome, options.home);
+            child.stdin.write(`${JSON.stringify({ jsonrpc: '2.0', method: 'initialized', params: {} })}\n`);
+        },
+        close() {
+            child.stdin.end();
+            setTimeout(() => { if (child.exitCode === null) child.kill(); }, 2_000).unref();
+        },
+        isHealthy() { return !transportFailure; },
+    };
+}
+
+async function listThreads(request, archived, filters = {}) {
+    const allThreads = [];
+    const allCursors = new Set();
+    let cursor = null;
+    let pageCount = 0;
+    do {
+        const page = await request('thread/list', {
+            limit: PAGE_SIZE,
+            archived,
+            useStateDbOnly: true,
+            sourceKinds: SOURCE_KINDS,
+            sortKey: 'updated_at',
+            sortDirection: 'desc',
+            ...filters,
+            ...(cursor && { cursor }),
+        });
+        if (!Array.isArray(page?.data)) throw new Error('Invalid thread/list reply');
+        allThreads.push(...page.data);
+        pageCount += 1;
+        if (pageCount % 10 === 0) process.stderr.write(`Listed ${allThreads.length} threads\n`);
+        cursor = page.nextCursor;
+        if (cursor && allCursors.has(cursor)) throw new Error('Repeated thread/list cursor');
+        if (cursor) allCursors.add(cursor);
+    } while (cursor);
+    return allThreads;
+}
+
+function discoverRolloutPaths(home) {
+    const sessionsDirectory = join(home, 'sessions');
+    const pathById = new Map();
+    const failures = [];
+    const allDirectories = [sessionsDirectory];
+    try {
+        if (!lstatSync(sessionsDirectory).isDirectory()) throw new Error('Sessions path is not a directory');
+    } catch (error) {
+        if (error.code === 'ENOENT') return { pathById, failures };
+        return { pathById, failures: [{ id: null, error: String(error.message || error) }] };
+    }
+    while (allDirectories.length) {
+        const directory = allDirectories.pop();
+        let allEntries;
+        try { allEntries = readdirSync(directory, { withFileTypes: true }); }
+        catch (error) {
+            failures.push({ id: null, error: String(error.message || error) });
+            continue;
+        }
+        for (const eachEntry of allEntries) {
+            if (eachEntry.isSymbolicLink()) continue;
+            const entryPath = join(directory, eachEntry.name);
+            if (eachEntry.isDirectory()) allDirectories.push(entryPath);
+            if (!eachEntry.isFile()) continue;
+            const threadId = ROLLOUT_FILENAME_PATTERN.exec(eachEntry.name)?.[1]?.toLowerCase();
+            if (!threadId) continue;
+            if (pathById.has(threadId)) {
+                failures.push({ id: threadId, error: 'Duplicate rollout ID under sessions' });
+                continue;
+            }
+            pathById.set(threadId, entryPath);
+        }
+    }
+    return { pathById, failures };
+}
+
+function isSameCanonicalPath(leftPath, rightPath) {
+    const left = realpathSync.native(leftPath);
+    const right = realpathSync.native(rightPath);
+    return process.platform === 'win32' ? left.toLowerCase() === right.toLowerCase() : left === right;
+}
+
+async function discoverHiddenThreads(request, home, listedThreads, isHealthy) {
+    const { pathById, failures } = discoverRolloutPaths(home);
+    const listedIds = new Set(listedThreads.map(eachThread => eachThread.id.toLowerCase()));
+    const hiddenThreads = [];
+    let emptyRolloutCount = 0;
+    for (const [eachThreadId, rolloutPath] of pathById) {
+        if (listedIds.has(eachThreadId)) continue;
+        try {
+            if (statSync(rolloutPath).size === 0) {
+                emptyRolloutCount += 1;
+                continue;
+            }
+            const thread = (await request('thread/read', { threadId: eachThreadId, includeTurns: false })).thread;
+            if (thread?.id?.toLowerCase() !== eachThreadId || !thread.path
+                || !isSameCanonicalPath(thread.path, rolloutPath)) {
+                throw new Error('Native thread metadata differs from discovered rollout');
+            }
+            hiddenThreads.push(thread);
+        } catch (error) {
+            failures.push({ id: eachThreadId, error: String(error.message || error) });
+            if (!isHealthy()) break;
+        }
+    }
+    return { hiddenThreads, failures, emptyRolloutCount };
+}
+
+function isArchivedReadback(thread, threadId, home) {
+    if (thread?.id !== threadId || !thread.path) return false;
+    if (ROLLOUT_FILENAME_PATTERN.exec(basename(thread.path))?.[1]?.toLowerCase() !== threadId.toLowerCase()) return false;
+    try {
+        const archiveDirectory = realpathSync.native(join(home, 'archived_sessions'));
+        const archivedPath = realpathSync.native(thread.path);
+        const pathWithinArchive = relative(archiveDirectory, archivedPath);
+        return pathWithinArchive !== '' && pathWithinArchive !== '..'
+            && !pathWithinArchive.startsWith(`..${sep}`) && !isAbsolute(pathWithinArchive)
+            && statSync(archivedPath).isFile();
+    } catch {
+        return false;
+    }
+}
+
+function ineligibilityReason(thread, cutoffSeconds, excludedThreadIds) {
+    if (!THREAD_ID_PATTERN.test(thread?.id)) return 'invalidId';
+    if (excludedThreadIds.has(thread.id.toLowerCase())) return 'excluded';
+    if (thread.ephemeral) return 'ephemeral';
+    if (!Number.isSafeInteger(thread.updatedAt) || thread.updatedAt <= 0) return 'unknownActivity';
+    if (thread.updatedAt > cutoffSeconds) return 'recent';
+    if (thread.status?.type === 'active') return 'active';
+    if (!['idle', 'notLoaded'].includes(thread.status?.type)) return 'unknownStatus';
+    return null;
+}
+
+function rolloutWriteReason(thread, cutoffMilliseconds) {
+    if (!thread.path) return null;
+    try {
+        const fileStatus = statSync(thread.path);
+        if (fileStatus.size === 0) return 'emptyRollout';
+        return fileStatus.mtimeMs > cutoffMilliseconds ? 'recentRolloutWrite' : null;
+    } catch {
+        return 'missingRollout';
+    }
+}
+
+function candidateReason(thread, cutoffSeconds, excludedThreadIds) {
+    return ineligibilityReason(thread, cutoffSeconds, excludedThreadIds)
+        || rolloutWriteReason(thread, cutoffSeconds * MILLISECONDS_PER_SECOND);
+}
+
+function parentThreadId(thread) {
+    return thread.parentThreadId || thread.source?.subAgent?.thread_spawn?.parent_thread_id;
+}
+
+function sortChildrenBeforeParents(allThreads) {
+    const threadById = new Map(allThreads.map(eachThread => [eachThread.id, eachThread]));
+    const depthById = new Map();
+    const depthOf = (thread, visited = new Set()) => {
+        if (depthById.has(thread.id)) return depthById.get(thread.id);
+        if (visited.has(thread.id)) throw new Error('Thread parent cycle');
+        visited.add(thread.id);
+        const parent = threadById.get(parentThreadId(thread));
+        const depth = parent ? depthOf(parent, visited) + 1 : 0;
+        depthById.set(thread.id, depth);
+        visited.delete(thread.id);
+        return depth;
+    };
+    return [...allThreads].sort((left, right) => depthOf(right) - depthOf(left));
+}
+
+function findProtectedAncestors(allThreads, cutoffSeconds, excludedThreadIds) {
+    const threadById = new Map(allThreads.map(eachThread => [eachThread.id, eachThread]));
+    const protectedIds = new Set();
+    for (const eachThread of allThreads) {
+        if (!candidateReason(eachThread, cutoffSeconds, excludedThreadIds)) continue;
+        let parentId = parentThreadId(eachThread);
+        while (parentId && !protectedIds.has(parentId)) {
+            protectedIds.add(parentId);
+            const parent = threadById.get(parentId);
+            parentId = parent && parentThreadId(parent);
+        }
+    }
+    return protectedIds;
+}
+
+function createReport(options, cutoffSeconds) {
+    return {
+        home: options.home,
+        cutoff: new Date(cutoffSeconds * MILLISECONDS_PER_SECOND).toISOString(),
+        scanned: 0,
+        eligible: 0,
+        archived: 0,
+        skipped: 0,
+        skippedReasons: {},
+        failed: [],
+    };
+}
+
+export async function cleanseSessions(request, options, now = Date.now(), isHealthy = () => true) {
+    const cutoffSeconds = Math.floor((now - options.inactiveDays * MILLISECONDS_PER_DAY) / MILLISECONDS_PER_SECOND);
+    const report = createReport(options, cutoffSeconds);
+    let listedThreads;
+    try {
+        listedThreads = await listThreads(request, false);
+    } catch (error) {
+        report.failed.push({ id: null, error: String(error.message || error) });
+        return report;
+    }
+    const { hiddenThreads, failures, emptyRolloutCount } = await discoverHiddenThreads(
+        request, options.home, listedThreads, isHealthy);
+    const allThreads = [...hiddenThreads, ...listedThreads];
+    report.scanned = allThreads.length + emptyRolloutCount;
+    report.skipped = emptyRolloutCount;
+    report.skippedReasons = emptyRolloutCount ? { emptyRollout: emptyRolloutCount } : {};
+    report.failed = failures;
+    const recordSkip = reason => {
+        report.skipped += 1;
+        report.skippedReasons[reason] = (report.skippedReasons[reason] || 0) + 1;
+    };
+    const protectedIds = findProtectedAncestors(allThreads, cutoffSeconds, options.excludedThreadIds);
+    if (!options.apply) {
+        for (const eachThread of allThreads) {
+            const reason = candidateReason(eachThread, cutoffSeconds, options.excludedThreadIds);
+            if (reason || protectedIds.has(eachThread.id)) recordSkip(reason || 'descendant');
+            else report.eligible += 1;
+        }
+        return report;
+    }
+    if (report.failed.length) return report;
+    const allAttemptedArchiveIds = [];
+    for (const eachThread of sortChildrenBeforeParents(allThreads)) {
+        if (report.failed.length) break;
+        const reason = candidateReason(eachThread, cutoffSeconds, options.excludedThreadIds);
+        if (reason || protectedIds.has(eachThread.id)) {
+            recordSkip(reason || 'descendant');
+            continue;
+        }
+        try {
+            const freshThread = (await request('thread/read', { threadId: eachThread.id, includeTurns: false })).thread;
+            const freshReason = ineligibilityReason(freshThread, cutoffSeconds, options.excludedThreadIds);
+            const fileReason = rolloutWriteReason(freshThread, cutoffSeconds * MILLISECONDS_PER_SECOND);
+            if (freshReason || fileReason) {
+                recordSkip(freshReason || fileReason);
+                continue;
+            }
+            const allDescendants = await listThreads(request, false, { ancestorThreadId: eachThread.id });
+            if (allDescendants.length) {
+                recordSkip('descendant');
+                continue;
+            }
+            report.eligible += 1;
+            allAttemptedArchiveIds.push(eachThread.id);
+            await request('thread/archive', { threadId: eachThread.id });
+            if (allAttemptedArchiveIds.length % 250 === 0) {
+                process.stderr.write(`Sent ${allAttemptedArchiveIds.length} archive requests\n`);
+            }
+        } catch (error) {
+            report.failed.push({ id: eachThread.id, error: String(error.message || error) });
+        }
+    }
+    if (allAttemptedArchiveIds.length) {
+        const archivedIds = new Set();
+        try {
+            for (const eachThread of await listThreads(request, true)) archivedIds.add(eachThread.id);
+        } catch (error) {
+            report.failed.push({ id: null, error: String(error.message || error) });
+        }
+        for (const eachThreadId of allAttemptedArchiveIds) {
+            if (archivedIds.has(eachThreadId)) report.archived += 1;
+            else {
+                try {
+                    const thread = (await request('thread/read', { threadId: eachThreadId, includeTurns: false })).thread;
+                    if (isArchivedReadback(thread, eachThreadId, options.home)) report.archived += 1;
+                    else report.failed.push({ id: eachThreadId, error: 'Archive readback missing' });
+                } catch (error) {
+                    report.failed.push({ id: eachThreadId, error: String(error.message || error) });
+                }
+            }
+        }
+    }
+    return report;
+}
+
+async function main() {
+    const options = parseOptions(process.argv.slice(2));
+    const now = Date.now();
+    let daemon;
+    let report = createReport(options, Math.floor((now - options.inactiveDays * MILLISECONDS_PER_DAY) / MILLISECONDS_PER_SECOND));
+    try {
+        daemon = openDaemon(options);
+        await daemon.initialize();
+        report = await cleanseSessions(daemon.request, options, now, daemon.isHealthy);
+    } catch (error) {
+        report.failed.push({ id: null, error: String(error.message || error) });
+    } finally {
+        daemon?.close();
+    }
+    process.stdout.write(`${JSON.stringify(report)}\n`);
+    if (report.failed.length) process.exitCode = 1;
+}
+
+if (process.argv[1] && existsSync(process.argv[1]) && isSameCanonicalPath(process.argv[1], scriptPath)) {
+    main().catch(error => {
+        process.stderr.write(`${error.message || error}\n`);
+        process.exitCode = 1;
+    });
+}

package/.agents/skills/codex-cleanse/scripts/cleanse.test.mjs

@@ -0,0 +1,708 @@
+import assert from 'node:assert/strict';
+import { spawnSync } from 'node:child_process';
+import { chmodSync, mkdirSync, mkdtempSync, renameSync, rmSync, symlinkSync, utimesSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { basename, dirname, join } from 'node:path';
+import test from 'node:test';
+import { fileURLToPath } from 'node:url';
+
+import { assertSelectedHome, cleanseSessions, parseOptions } from './cleanse.mjs';
+import * as cleanse from './cleanse.mjs';
+
+const now = Date.parse('2026-09-30T12:00:00.000Z');
+const cutoff = Math.floor((now - 7 * 86_400_000) / 1_000);
+const threadId = number => `00000000-0000-4000-8000-${String(number).padStart(12, '0')}`;
+
+test('CLI starts through a directory link and reports a missing executable', () => {
+    const home = mkdtempSync(join(tmpdir(), 'codex-cleanse-entry-'));
+    try {
+        const linkedDirectory = join(home, 'scripts');
+        symlinkSync(dirname(fileURLToPath(import.meta.url)), linkedDirectory, process.platform === 'win32' ? 'junction' : 'dir');
+        const execution = spawnSync(process.execPath, [join(linkedDirectory, 'cleanse.mjs'),
+            '--codex-home', home, '--codex-path', join(home, 'missing')], { encoding: 'utf8', timeout: 10_000 });
+        assert.equal(execution.status, 1, execution.stderr);
+        const report = JSON.parse(execution.stdout);
+        assert.equal(report.archived, 0);
+        assert.equal(report.scanned, 0);
+        assert.match(report.failed[0].error, /executable not found/);
+    } finally {
+        rmSync(home, { recursive: true, force: true });
+    }
+});
+
+function makeThread(number, updatedAt, overrides = {}) {
+    return {
+        id: threadId(number),
+        updatedAt,
+        status: { type: 'idle' },
+        parentThreadId: null,
+        ephemeral: false,
+        ...overrides,
+    };
+}
+
+function makeOptions(overrides = {}) {
+    return {
+        home: join(tmpdir(), 'account-a'),
+        inactiveDays: 7,
+        apply: false,
+        excludedThreadIds: new Set(),
+        ...overrides,
+    };
+}
+
+function makeRequest(allThreads, archiveFailures = new Set(), missingReadback = new Set()) {
+    const archivedIds = new Set();
+    const allCalls = [];
+    const request = async (method, params) => {
+        allCalls.push({ method, params });
+        if (method === 'thread/list') {
+            const selectedThreads = allThreads.filter(eachThread =>
+                params.archived === archivedIds.has(eachThread.id)
+                && (!params.ancestorThreadId || eachThread.parentThreadId === params.ancestorThreadId)
+                && (!params.archived || !missingReadback.has(eachThread.id)));
+            const offset = Number(params.cursor || 0);
+            return { data: selectedThreads.slice(offset, offset + 2), nextCursor: offset + 2 < selectedThreads.length ? String(offset + 2) : null };
+        }
+        if (method === 'thread/read') {
+            return { thread: allThreads.find(eachThread => eachThread.id === params.threadId) };
+        }
+        if (method === 'thread/archive') {
+            if (archiveFailures.has(params.threadId)) throw new Error('archive rejected');
+            archivedIds.add(params.threadId);
+            return {};
+        }
+        throw new Error(`Unexpected method: ${method}`);
+    };
+    return { request, allCalls, archivedIds };
+}
+
+function makeRollout(home, number) {
+    const directory = join(home, 'sessions', '2026', '07', '01');
+    mkdirSync(directory, { recursive: true });
+    const rolloutPath = join(directory, `rollout-2026-07-01T00-00-00-${threadId(number)}.jsonl`);
+    writeFileSync(rolloutPath, 'session metadata');
+    utimesSync(rolloutPath, new Date(0), new Date(0));
+    return rolloutPath;
+}
+
+function makeHiddenRequest(home, allThreads, visibleIds, archiveDirectory = join(home, 'archived_sessions')) {
+    const archivedIds = new Set();
+    const allCalls = [];
+    const request = async (method, params) => {
+        allCalls.push({ method, params });
+        if (method === 'thread/read') {
+            return { thread: allThreads.find(eachThread => eachThread.id === params.threadId) };
+        }
+        if (method === 'thread/archive') {
+            const thread = allThreads.find(eachThread => eachThread.id === params.threadId);
+            mkdirSync(archiveDirectory, { recursive: true });
+            const archivedPath = join(archiveDirectory, basename(thread.path));
+            renameSync(thread.path, archivedPath);
+            thread.path = archivedPath;
+            archivedIds.add(thread.id);
+            return {};
+        }
+        const matchingThreads = allThreads.filter(eachThread =>
+            archivedIds.has(eachThread.id) === params.archived
+            && (params.ancestorThreadId
+                ? eachThread.parentThreadId === params.ancestorThreadId
+                : visibleIds.has(eachThread.id)));
+        return { data: matchingThreads, nextCursor: null };
+    };
+    return { request, allCalls, archivedIds };
+}
+
+test('preview counts every page and source without archiving', async () => {
+    const allThreads = [
+        makeThread(1, cutoff),
+        makeThread(2, cutoff - 1),
+        makeThread(3, cutoff + 1),
+    ];
+    const fixture = makeRequest(allThreads);
+    const report = await cleanseSessions(fixture.request, makeOptions(), now);
+    assert.deepEqual([report.scanned, report.eligible, report.skipped, report.archived], [3, 2, 1, 0]);
+    assert.equal(fixture.allCalls.filter(eachCall => eachCall.method === 'thread/list').length, 2);
+    assert.equal(fixture.allCalls.filter(eachCall => eachCall.method === 'thread/archive').length, 0);
+});
+
+test('preview protects running sessions, excluded IDs, and parents with recent children', async () => {
+    const allThreads = [
+        makeThread(1, cutoff - 1, { status: { type: 'active' } }),
+        makeThread(2, cutoff - 1),
+        makeThread(3, cutoff - 1),
+        makeThread(4, cutoff + 1, { parentThreadId: threadId(3) }),
+        makeThread(5, cutoff - 1, { updatedAt: 0 }),
+    ];
+    const fixture = makeRequest(allThreads);
+    const options = makeOptions({ excludedThreadIds: new Set([threadId(2)]) });
+    const report = await cleanseSessions(fixture.request, options, now);
+    assert.equal(report.eligible, 0);
+    assert.equal(report.skipped, 5);
+});
+
+for (const eachProtection of ['recent', 'excluded']) {
+    test(`preview protects ancestors of a ${eachProtection} child with a source parent link`, async () => {
+        const allThreads = [makeThread(1, cutoff - 1),
+            makeThread(2, cutoff - 1, { source: { subAgent: { thread_spawn: { parent_thread_id: threadId(1) } } } }),
+            makeThread(3, eachProtection === 'recent' ? cutoff + 1 : cutoff - 1,
+                { source: { subAgent: { thread_spawn: { parent_thread_id: threadId(2) } } } })];
+        const fixture = makeRequest(allThreads);
+        const excludedThreadIds = new Set(eachProtection === 'excluded' ? [threadId(3)] : []);
+        const report = await cleanseSessions(fixture.request, makeOptions({ excludedThreadIds }), now);
+        assert.equal(report.eligible, 0);
+        assert.equal(report.skippedReasons.descendant, 2);
+        assert.equal(fixture.allCalls.filter(eachCall => eachCall.method === 'thread/archive').length, 0);
+    });
+}
+
+test('apply orders a stale child with a source parent link before its parent', async () => {
+    const fixture = makeRequest([makeThread(1, cutoff - 1), makeThread(2, cutoff - 1,
+        { source: { subAgent: { thread_spawn: { parent_thread_id: threadId(1) } } } })]);
+    const report = await cleanseSessions(fixture.request, makeOptions({ apply: true }), now);
+    assert.equal(report.archived, 2);
+    assert.deepEqual(fixture.allCalls.filter(eachCall => eachCall.method === 'thread/archive')
+        .map(eachCall => eachCall.params.threadId), [threadId(2), threadId(1)]);
+});
+
+test('preview prefers the top-level parent over a conflicting source parent link', async () => {
+    const fixture = makeRequest([makeThread(1, cutoff - 1), makeThread(2, cutoff - 1),
+        makeThread(3, cutoff + 1, { parentThreadId: threadId(1),
+            source: { subAgent: { thread_spawn: { parent_thread_id: threadId(2) } } } })]);
+    const report = await cleanseSessions(fixture.request, makeOptions(), now);
+    assert.equal(report.eligible, 1);
+    assert.equal(report.skippedReasons.descendant, 1);
+});
+
+test('apply archives a stale leaf and confirms archived listing', async () => {
+    const directory = mkdtempSync(join(tmpdir(), 'codex-cleanse-'));
+    try {
+        const rolloutPath = join(directory, 'rollout.jsonl');
+        writeFileSync(rolloutPath, 'session metadata');
+        utimesSync(rolloutPath, new Date(0), new Date(0));
+        const fixture = makeRequest([makeThread(1, cutoff - 1, { path: rolloutPath })]);
+        const report = await cleanseSessions(fixture.request, makeOptions({ apply: true }), now);
+        assert.equal(report.archived, 1);
+        assert.deepEqual(report.failed, []);
+        assert.deepEqual([...fixture.archivedIds], [threadId(1)]);
+    } finally {
+        rmSync(directory, { recursive: true, force: true });
+    }
+});
+
+test('apply archives a stale database-backed thread with no rollout path', async () => {
+    const fixture = makeRequest([makeThread(1, cutoff - 1, { path: null })]);
+    const report = await cleanseSessions(fixture.request, makeOptions({ apply: true }), now);
+    assert.equal(report.archived, 1);
+    assert.deepEqual(report.failed, []);
+});
+
+test('apply reads back earlier archives and stops after a rejected archive', async () => {
+    const directory = mkdtempSync(join(tmpdir(), 'codex-cleanse-'));
+    try {
+        const rolloutPath = join(directory, 'rollout.jsonl');
+        writeFileSync(rolloutPath, 'session metadata');
+        utimesSync(rolloutPath, new Date(0), new Date(0));
+        const allThreads = [1, 2, 3].map(number => makeThread(number, cutoff - 1, { path: rolloutPath }));
+        const fixture = makeRequest(allThreads, new Set([threadId(2)]), new Set([threadId(1)]));
+        const report = await cleanseSessions(fixture.request, makeOptions({ apply: true }), now);
+        assert.equal(report.archived, 0);
+        assert.deepEqual(report.failed.map(eachFailure => eachFailure.id), [threadId(2), threadId(1), threadId(2)]);
+        assert.deepEqual(fixture.allCalls.filter(eachCall => eachCall.method === 'thread/archive')
+            .map(eachCall => eachCall.params.threadId), [threadId(1), threadId(2)]);
+        assert.equal(fixture.allCalls.filter(eachCall => eachCall.method === 'thread/read'
+            && eachCall.params.threadId === threadId(1)).length, 2);
+    } finally {
+        rmSync(directory, { recursive: true, force: true });
+    }
+});
+
+test('apply skips a rollout file changed after the cutoff', async () => {
+    const directory = mkdtempSync(join(tmpdir(), 'codex-cleanse-'));
+    try {
+        const rolloutPath = join(directory, 'rollout.jsonl');
+        writeFileSync(rolloutPath, 'new activity');
+        const fixture = makeRequest([makeThread(1, cutoff - 1, { path: rolloutPath })]);
+        const report = await cleanseSessions(fixture.request, makeOptions({ apply: true }), now);
+        assert.equal(report.archived, 0);
+        assert.equal(report.skippedReasons.recentRolloutWrite, 1);
+        assert.equal(fixture.allCalls.filter(eachCall => eachCall.method === 'thread/archive').length, 0);
+    } finally {
+        rmSync(directory, { recursive: true, force: true });
+    }
+});
+
+test('apply protects a parent when the daemon finds a recent descendant absent from parent metadata', async () => {
+    const directory = mkdtempSync(join(tmpdir(), 'codex-cleanse-'));
+    try {
+        const rolloutPath = join(directory, 'rollout.jsonl');
+        writeFileSync(rolloutPath, 'session metadata');
+        utimesSync(rolloutPath, new Date(0), new Date(0));
+        const parent = makeThread(1, cutoff - 1, { path: rolloutPath });
+        const child = makeThread(2, cutoff + 1);
+        const fixture = makeRequest([parent, child]);
+        const request = async (method, params) => {
+            if (method === 'thread/list' && params.ancestorThreadId === parent.id) {
+                return { data: [child], nextCursor: null };
+            }
+            return fixture.request(method, params);
+        };
+        const report = await cleanseSessions(request, makeOptions({ apply: true }), now);
+        assert.equal(report.archived, 0);
+        assert.equal(report.skippedReasons.descendant, 1);
+        assert.equal(fixture.allCalls.filter(eachCall => eachCall.method === 'thread/archive').length, 0);
+    } finally {
+        rmSync(directory, { recursive: true, force: true });
+    }
+});
+
+test('selected Codex home follows the flag before the environment and rejects a mismatched server', () => {
+    const homeFromEnvironment = join(tmpdir(), 'account-a');
+    const homeFromFlag = join(tmpdir(), 'account-b');
+    const options = parseOptions(['--codex-home', homeFromFlag], { CODEX_HOME: homeFromEnvironment });
+    assert.equal(options.home, homeFromFlag);
+    assert.throws(() => assertSelectedHome(homeFromEnvironment, options.home), /differs from selected home/);
+});
+
+test('selected home accepts a directory alias and rejects missing or different homes', () => {
+    const directory = mkdtempSync(join(tmpdir(), 'codex-cleanse-home-'));
+    try {
+        const home = join(directory, 'account');
+        const alias = join(directory, 'alias');
+        const otherHome = join(directory, 'other');
+        mkdirSync(home);
+        mkdirSync(otherHome);
+        symlinkSync(home, alias, process.platform === 'win32' ? 'junction' : 'dir');
+        assert.doesNotThrow(() => assertSelectedHome(home, alias));
+        assert.doesNotThrow(() => assertSelectedHome(alias, home));
+        if (process.platform === 'win32') {
+            assert.doesNotThrow(() => assertSelectedHome(home.toUpperCase(), alias));
+        }
+        assert.throws(() => assertSelectedHome(otherHome, alias), /differs from selected home/);
+        assert.throws(() => assertSelectedHome(undefined, home));
+        assert.throws(() => assertSelectedHome(join(directory, 'missing'), home));
+    } finally {
+        rmSync(directory, { recursive: true, force: true });
+    }
+});
+
+test('transport loss preserves acknowledged archives as unverified and stops later writes', async () => {
+    const fixture = makeRequest([1, 2, 3].map(number => makeThread(number, cutoff - 1)));
+    const allAttempts = [];
+    let isHealthy = true;
+    const request = async (method, params) => {
+        allAttempts.push({ method, params });
+        if (method === 'thread/archive' && params.threadId === threadId(2)) isHealthy = false;
+        if (!isHealthy) throw new Error('daemon exited');
+        return fixture.request(method, params);
+    };
+    const report = await cleanseSessions(request, makeOptions({ apply: true }), now, () => isHealthy);
+    assert.deepEqual([report.scanned, report.eligible, report.archived], [3, 2, 0]);
+    assert.ok(report.failed.some(eachFailure => eachFailure.id === threadId(2) && /daemon exited/.test(eachFailure.error)));
+    assert.ok(report.failed.some(eachFailure => eachFailure.id === threadId(1) && /daemon exited/.test(eachFailure.error)));
+    assert.deepEqual(allAttempts.filter(eachCall => eachCall.method === 'thread/archive')
+        .map(eachCall => eachCall.params.threadId), [threadId(1), threadId(2)]);
+    assert.ok(allAttempts.some(eachCall => eachCall.method === 'thread/list' && eachCall.params.archived));
+    assert.deepEqual(allAttempts.filter(eachCall => eachCall.method === 'thread/read')
+        .map(eachCall => eachCall.params.threadId), [threadId(1), threadId(2), threadId(1), threadId(2)]);
+});
+
+test('archived listing failure retains its error and verifies available per-thread readback', async () => {
+    const home = mkdtempSync(join(tmpdir(), 'codex-cleanse-readback-'));
+    try {
+        const orphan = makeThread(1, cutoff - 1, { path: makeRollout(home, 1) });
+        const fixture = makeHiddenRequest(home, [orphan], new Set());
+        const request = async (method, params) => {
+            if (method === 'thread/list' && params.archived) throw new Error('archived listing failed');
+            return fixture.request(method, params);
+        };
+        const report = await cleanseSessions(request, makeOptions({ home, apply: true }), now);
+        assert.equal(report.archived, 1);
+        assert.deepEqual(report.failed, [{ id: null, error: 'archived listing failed' }]);
+    } finally {
+        rmSync(home, { recursive: true, force: true });
+    }
+});
+
+function assertCliTransportFailure(failureMethod) {
+    const home = mkdtempSync(join(tmpdir(), 'codex-cleanse-cli-'));
+    try {
+        const scriptUrl = new URL('./cleanse.mjs', import.meta.url).href;
+        const program = `
+            import childProcess from 'node:child_process';
+            import { EventEmitter } from 'node:events';
+            import { syncBuiltinESMExports } from 'node:module';
+            import { PassThrough, Writable } from 'node:stream';
+            import { fileURLToPath } from 'node:url';
+            const allThreads = ${JSON.stringify([1, 2, 3].map(number => makeThread(number, 1)))};
+            childProcess.spawn = () => {
+                const child = new EventEmitter();
+                child.stdout = new PassThrough();
+                child.stderr = new PassThrough();
+                child.exitCode = null;
+                child.stdin = new Writable({ write(chunk, encoding, done) {
+                    const message = JSON.parse(chunk.toString());
+                    if (!message.id) return done();
+                    if (message.method === ${JSON.stringify(failureMethod)} && (message.method !== 'thread/archive' || message.params.threadId === allThreads[1].id)) {
+                        child.exitCode = 7;
+                        child.emit('exit', 7);
+                        return done();
+                    }
+                    let reply = {};
+                    if (message.method === 'initialize') reply = { codexHome: ${JSON.stringify(failureMethod === 'wrong-home' ? tmpdir() : home)} };
+                    if (message.method === 'thread/archive') process.stderr.write('archive attempted\\n');
+                    if (message.method === 'thread/list') reply = { data: message.params.ancestorThreadId ? [] : allThreads };
+                    if (message.method === 'thread/read') reply = { thread: allThreads.find(eachThread => eachThread.id === message.params.threadId) };
+                    child.stdout.write(JSON.stringify({ id: message.id, result: reply }) + '\\n');
+                    done();
+                }});
+                child.stdin.on('finish', () => process.stderr.write('daemon closed\\n'));
+                return child;
+            };
+            syncBuiltinESMExports();
+            process.argv = [process.execPath, fileURLToPath(${JSON.stringify(scriptUrl)}), '--apply', '--codex-home', ${JSON.stringify(home)}, '--codex-path', ${failureMethod === 'missing-binary' ? JSON.stringify(join(home, 'missing')) : 'process.execPath'}];
+            await import(${JSON.stringify(scriptUrl)});
+        `;
+        const execution = spawnSync(process.execPath, ['--input-type=module', '--eval', program], { encoding: 'utf8', timeout: 10_000 });
+        assert.equal(execution.status, 1, execution.stderr);
+        const allLines = execution.stdout.trim().split('\n');
+        assert.equal(allLines.length, 1);
+        const report = JSON.parse(allLines[0]);
+        const isArchiveFailure = failureMethod === 'thread/archive';
+        assert.deepEqual([report.scanned, report.eligible, report.archived], isArchiveFailure ? [3, 2, 0] : [0, 0, 0]);
+        assert.deepEqual(report.failed.map(eachFailure => eachFailure.id), isArchiveFailure ? [threadId(2), null, threadId(1), threadId(2)] : [null]);
+        const expectedError = failureMethod === 'wrong-home' ? /differs from selected home/ : failureMethod === 'missing-binary' ? /executable not found/ : /exited with code 7/;
+        assert.ok(report.failed.every(eachFailure => expectedError.test(eachFailure.error)));
+        if (!isArchiveFailure) assert.doesNotMatch(execution.stderr, /archive attempted/);
+        if (failureMethod !== 'missing-binary') assert.match(execution.stderr, /daemon closed/);
+    } finally {
+        rmSync(home, { recursive: true, force: true });
+    }
+}
+
+for (const eachFailureMethod of ['thread/archive', 'thread/list', 'initialize', 'wrong-home', 'missing-binary']) {
+    test(`CLI emits one JSON report and exits unsuccessfully after ${eachFailureMethod} transport loss`, () => {
+        assertCliTransportFailure(eachFailureMethod);
+    });
+}
+
+test('native PATH discovery keeps explicit overrides and rejects missing explicit executables', () => {
+    const home = mkdtempSync(join(tmpdir(), 'codex-cleanse-path-'));
+    try {
+        const executableName = process.platform === 'win32' ? 'codex.exe' : 'codex';
+        const binaryPath = join(home, executableName);
+        writeFileSync(binaryPath, 'fixture');
+        chmodSync(binaryPath, 0o755);
+        const environment = { [process.platform === 'win32' ? 'Path' : 'PATH']: home };
+        assert.equal(cleanse.findCodexPath(makeOptions({ home }), environment), binaryPath);
+        const standalonePath = join(home, 'packages', 'standalone', 'current', 'bin', executableName);
+        mkdirSync(dirname(standalonePath), { recursive: true });
+        writeFileSync(standalonePath, 'fixture');
+        chmodSync(standalonePath, 0o755);
+        assert.equal(cleanse.findCodexPath(makeOptions({ home }), environment), standalonePath);
+        rmSync(standalonePath);
+        assert.equal(cleanse.findCodexPath(makeOptions({ home, codexPath: process.execPath }), environment), process.execPath);
+        assert.throws(() => cleanse.findCodexPath(makeOptions({ home, codexPath: join(home, 'missing') }), environment), /executable not found/);
+        if (process.platform !== 'win32') {
+            chmodSync(binaryPath, 0o644);
+            assert.throws(() => cleanse.findCodexPath(makeOptions({ home }), environment), /executable not found/);
+        }
+        rmSync(binaryPath);
+        writeFileSync(join(home, 'codex.cmd'), 'fixture');
+        assert.throws(() => cleanse.findCodexPath(makeOptions({ home }), environment), /executable not found/);
+        if (process.platform === 'win32') {
+            const vendorPath = join(home, 'node_modules', '@openai', 'codex', 'node_modules', '@openai',
+                'codex-win32-x64', 'vendor', 'x86_64-pc-windows-msvc', 'bin', executableName);
+            mkdirSync(dirname(vendorPath), { recursive: true });
+            writeFileSync(vendorPath, 'fixture');
+            assert.equal(cleanse.findCodexPath(makeOptions({ home }), environment), vendorPath);
+        }
+    } finally {
+        rmSync(home, { recursive: true, force: true });
+    }
+});
+
+test('initial listing failure returns a report without archive requests', async () => {
+    const allMethods = [];
+    const request = async method => {
+        allMethods.push(method);
+        throw new Error('initial listing failed');
+    };
+    const report = await cleanseSessions(request, makeOptions({ apply: true }), now);
+    assert.deepEqual([report.scanned, report.eligible, report.archived], [0, 0, 0]);
+    assert.deepEqual(report.failed, [{ id: null, error: 'initial listing failed' }]);
+    assert.deepEqual(allMethods, ['thread/list']);
+});
+
+test('lost archive reply still verifies the moved rollout and stops later writes', async () => {
+    const home = mkdtempSync(join(tmpdir(), 'codex-cleanse-lost-reply-'));
+    try {
+        const allThreads = [1, 2].map(number => makeThread(number, cutoff - 1, { path: makeRollout(home, number) }));
+        const fixture = makeHiddenRequest(home, allThreads, new Set());
+        const request = async (method, params) => {
+            const reply = await fixture.request(method, params);
+            if (method === 'thread/archive') throw new Error('archive reply lost');
+            return reply;
+        };
+        const report = await cleanseSessions(request, makeOptions({ home, apply: true }), now);
+        assert.equal(report.archived, 1);
+        assert.deepEqual(report.failed, [{ id: threadId(1), error: 'archive reply lost' }]);
+        assert.deepEqual(fixture.allCalls.filter(eachCall => eachCall.method === 'thread/archive')
+            .map(eachCall => eachCall.params.threadId), [threadId(1)]);
+    } finally {
+        rmSync(home, { recursive: true, force: true });
+    }
+});
+
+test('hidden discovery transport failure retains the listed count and returns a failure report', async () => {
+    const home = mkdtempSync(join(tmpdir(), 'codex-cleanse-discovery-'));
+    try {
+        makeRollout(home, 1);
+        const allMethods = [];
+        const request = async method => {
+            allMethods.push(method);
+            if (method === 'thread/read') throw new Error('discovery transport lost');
+            return { data: [makeThread(2, cutoff - 1)] };
+        };
+        const report = await cleanseSessions(request, makeOptions({ home, apply: true }), now, () => false);
+        assert.equal(report.scanned, 1);
+        assert.equal(report.archived, 0);
+        assert.deepEqual(report.failed, [{ id: threadId(1), error: 'discovery transport lost' }]);
+        assert.deepEqual(allMethods, ['thread/list', 'thread/read']);
+    } finally {
+        rmSync(home, { recursive: true, force: true });
+    }
+});
+
+test('inactivity days reject cutoffs outside the supported date range', () => {
+    for (const eachInactiveDays of ['1e308', '1e9']) {
+        assert.throws(() => parseOptions(['--inactive-days', eachInactiveDays]), /valid cutoff date/);
+    }
+    assert.equal(parseOptions(['--inactive-days', '7']).inactiveDays, 7);
+    assert.equal(parseOptions(['--inactive-days', '0']).inactiveDays, 0);
+});
+
+test('every value-taking option rejects a following flag or end of arguments', () => {
+    const allValueTakingFlags = ['--inactive-days', '--codex-home', '--codex-path', '--exclude-thread-id'];
+    for (const eachFlag of allValueTakingFlags) {
+        assert.throws(() => parseOptions([eachFlag, '--apply']), new RegExp(`Missing value for ${eachFlag}`));
+        assert.throws(() => parseOptions([eachFlag]), new RegExp(`Missing value for ${eachFlag}`));
+    }
+});
+
+test('uppercase CLI exclusion is stored as a lowercase UUID', () => {
+    const uppercaseId = 'ABCDEFAB-CDEF-4ABC-8DEF-ABCDEFABCDEF';
+    const options = parseOptions(['--exclude-thread-id', uppercaseId]);
+    assert.deepEqual([...options.excludedThreadIds], [uppercaseId.toLowerCase()]);
+});
+
+test('lowercase exclusion protects a native thread with an uppercase UUID', async () => {
+    const home = mkdtempSync(join(tmpdir(), 'codex-cleanse-'));
+    try {
+        const uppercaseId = 'ABCDEFAB-CDEF-4ABC-8DEF-ABCDEFABCDEF';
+        const options = parseOptions(['--codex-home', home, '--exclude-thread-id', uppercaseId.toLowerCase(), '--apply']);
+        const fixture = makeRequest([makeThread(1, cutoff - 1, { id: uppercaseId })]);
+        const report = await cleanseSessions(fixture.request, options, now);
+        assert.equal(report.skippedReasons.excluded, 1);
+        assert.equal(report.archived, 0);
+        assert.equal(fixture.allCalls.filter(eachCall => eachCall.method === 'thread/archive').length, 0);
+    } finally {
+        rmSync(home, { recursive: true, force: true });
+    }
+});
+
+test('apply finds an old hidden child and archives it before its visible parent', async () => {
+    const home = mkdtempSync(join(tmpdir(), 'codex-cleanse-'));
+    try {
+        const parent = makeThread(1, cutoff - 1, { path: makeRollout(home, 1) });
+        const child = makeThread(2, cutoff - 1, { path: makeRollout(home, 2), parentThreadId: parent.id });
+        const fixture = makeHiddenRequest(home, [parent, child], new Set([parent.id]));
+        const report = await cleanseSessions(fixture.request, makeOptions({ home, apply: true }), now);
+        assert.equal(report.scanned, 2);
+        assert.equal(report.archived, 2);
+        assert.deepEqual(report.failed, []);
+        assert.deepEqual(fixture.allCalls.filter(eachCall => eachCall.method === 'thread/archive')
+            .map(eachCall => eachCall.params.threadId), [child.id, parent.id]);
+    } finally {
+        rmSync(home, { recursive: true, force: true });
+    }
+});
+
+test('apply archives an old hidden orphan from the selected home only', async () => {
+    const home = mkdtempSync(join(tmpdir(), 'codex-cleanse-'));
+    const otherHome = mkdtempSync(join(tmpdir(), 'codex-cleanse-other-'));
+    try {
+        const orphan = makeThread(1, cutoff - 1, { path: makeRollout(home, 1) });
+        writeFileSync(join(home, 'sessions', 'notes.jsonl'), 'ignored');
+        makeRollout(otherHome, 2);
+        const fixture = makeHiddenRequest(home, [orphan], new Set());
+        const report = await cleanseSessions(fixture.request, makeOptions({ home, apply: true }), now);
+        assert.equal(report.scanned, 1);
+        assert.equal(report.archived, 1);
+        assert.deepEqual(report.failed, []);
+    } finally {
+        rmSync(home, { recursive: true, force: true });
+        rmSync(otherHome, { recursive: true, force: true });
+    }
+});
+
+test('a recent hidden child keeps its old parent unarchived', async () => {
+    const home = mkdtempSync(join(tmpdir(), 'codex-cleanse-'));
+    try {
+        const parent = makeThread(1, cutoff - 1, { path: makeRollout(home, 1) });
+        const child = makeThread(2, cutoff + 1, { path: makeRollout(home, 2), parentThreadId: parent.id });
+        const fixture = makeHiddenRequest(home, [parent, child], new Set([parent.id]));
+        const report = await cleanseSessions(fixture.request, makeOptions({ home, apply: true }), now);
+        assert.equal(report.archived, 0);
+        assert.equal(report.skippedReasons.descendant, 1);
+        assert.equal(fixture.allCalls.filter(eachCall => eachCall.method === 'thread/archive').length, 0);
+    } finally {
+        rmSync(home, { recursive: true, force: true });
+    }
+});
+
+test('hidden discovery reports native ID and path mismatches', async () => {
+    const home = mkdtempSync(join(tmpdir(), 'codex-cleanse-'));
+    try {
+        const rolloutPath = makeRollout(home, 1);
+        const wrongPath = makeRollout(home, 2);
+        for (const thread of [makeThread(2, cutoff - 1, { path: rolloutPath }),
+            makeThread(1, cutoff - 1, { path: wrongPath })]) {
+            const request = async (method, params) => method === 'thread/read'
+                ? { thread }
+                : { data: [], nextCursor: null };
+            const report = await cleanseSessions(request, makeOptions({ home, apply: true }), now);
+            assert.equal(report.archived, 0);
+            assert.ok(report.failed.some(eachFailure => eachFailure.id === threadId(1)));
+        }
+    } finally {
+        rmSync(home, { recursive: true, force: true });
+    }
+});
+
+test('hidden discovery reports a native read failure', async () => {
+    const home = mkdtempSync(join(tmpdir(), 'codex-cleanse-'));
+    try {
+        makeRollout(home, 1);
+        const request = async (method, params) => {
+            if (method === 'thread/read') throw new Error('native read failed');
+            return { data: [], nextCursor: null };
+        };
+        const report = await cleanseSessions(request, makeOptions({ home, apply: true }), now);
+        assert.equal(report.archived, 0);
+        assert.deepEqual(report.failed.map(eachFailure => eachFailure.id), [threadId(1)]);
+    } finally {
+        rmSync(home, { recursive: true, force: true });
+    }
+});
+
+test('a hidden child read failure stops its listed parent before archive', async () => {
+    const home = mkdtempSync(join(tmpdir(), 'codex-cleanse-'));
+    try {
+        const parent = makeThread(1, cutoff - 1, { path: makeRollout(home, 1) });
+        makeRollout(home, 2);
+        const allCalls = [];
+        const request = async (method, params) => {
+            allCalls.push({ method, params });
+            if (method === 'thread/list') {
+                return { data: params.ancestorThreadId ? [] : [parent], nextCursor: null };
+            }
+            if (method === 'thread/read' && params.threadId === threadId(2)) {
+                throw new Error('Hidden child metadata unreadable');
+            }
+            if (method === 'thread/read') return { thread: parent };
+            return {};
+        };
+        const report = await cleanseSessions(request, makeOptions({ home, apply: true }), now);
+        assert.equal(report.archived, 0);
+        assert.deepEqual(report.failed.map(eachFailure => eachFailure.id), [threadId(2)]);
+        assert.equal(allCalls.filter(eachCall => eachCall.method === 'thread/archive').length, 0);
+    } finally {
+        rmSync(home, { recursive: true, force: true });
+    }
+});
+
+test('a hidden child archive failure stops its listed parent with an incomplete ancestor listing', async () => {
+    const home = mkdtempSync(join(tmpdir(), 'codex-cleanse-'));
+    try {
+        const parent = makeThread(1, cutoff - 1, { path: makeRollout(home, 1) });
+        const child = makeThread(2, cutoff - 1, { path: makeRollout(home, 2), parentThreadId: parent.id });
+        const fixture = makeHiddenRequest(home, [parent, child], new Set([parent.id]));
+        const request = async (method, params) => {
+            if (method === 'thread/list' && params.ancestorThreadId) {
+                return { data: [], nextCursor: null };
+            }
+            if (method === 'thread/archive' && params.threadId === child.id) {
+                fixture.allCalls.push({ method, params });
+                throw new Error('child archive rejected');
+            }
+            return fixture.request(method, params);
+        };
+        const report = await cleanseSessions(request, makeOptions({ home, apply: true }), now);
+        assert.equal(report.archived, 0);
+        assert.deepEqual(report.failed.map(eachFailure => eachFailure.id), [child.id, child.id]);
+        assert.deepEqual(fixture.allCalls.filter(eachCall => eachCall.method === 'thread/archive')
+            .map(eachCall => eachCall.params.threadId), [child.id]);
+    } finally {
+        rmSync(home, { recursive: true, force: true });
+    }
+});
+
+test('empty rollout stubs skip native read and archive', async () => {
+    const home = mkdtempSync(join(tmpdir(), 'codex-cleanse-'));
+    try {
+        const rolloutPath = makeRollout(home, 1);
+        writeFileSync(rolloutPath, '');
+        const allMethods = [];
+        const request = async method => {
+            allMethods.push(method);
+            if (method !== 'thread/list') throw new Error('Empty rollout reached native session API');
+            return { data: [], nextCursor: null };
+        };
+        const report = await cleanseSessions(request, makeOptions({ home, apply: true }), now);
+        assert.equal(report.scanned, 1);
+        assert.equal(report.skippedReasons.emptyRollout, 1);
+        assert.equal(report.archived, 0);
+        assert.deepEqual(report.failed, []);
+        assert.deepEqual(allMethods, ['thread/list']);
+    } finally {
+        rmSync(home, { recursive: true, force: true });
+    }
+});
+
+test('hidden archive readback rejects a sibling directory with the archived name prefix', async () => {
+    const home = mkdtempSync(join(tmpdir(), 'codex-cleanse-'));
+    try {
+        const orphan = makeThread(1, cutoff - 1, { path: makeRollout(home, 1) });
+        const siblingDirectory = join(home, 'archived_sessions-copy');
+        const fixture = makeHiddenRequest(home, [orphan], new Set(), siblingDirectory);
+        const report = await cleanseSessions(fixture.request, makeOptions({ home, apply: true }), now);
+        assert.equal(report.archived, 0);
+        assert.deepEqual(report.failed.map(eachFailure => eachFailure.id), [orphan.id]);
+    } finally {
+        rmSync(home, { recursive: true, force: true });
+    }
+});
+
+test('hidden discovery and readback accept paths that resolve to the same rollout file', async () => {
+    const home = mkdtempSync(join(tmpdir(), 'codex-cleanse-'));
+    try {
+        const orphan = makeThread(1, cutoff - 1, { path: makeRollout(home, 1) });
+        orphan.path = process.platform === 'win32'
+            ? `\\\\?\\${orphan.path}`
+            : join(dirname(orphan.path), '..', '01', basename(orphan.path));
+        const fixture = makeHiddenRequest(home, [orphan], new Set());
+        const request = async (method, params) => {
+            const reply = await fixture.request(method, params);
+            if (method === 'thread/archive' && process.platform === 'win32') {
+                orphan.path = `\\\\?\\${orphan.path}`;
+            }
+            return reply;
+        };
+        const report = await cleanseSessions(request, makeOptions({ home, apply: true }), now);
+        assert.equal(report.archived, 1);
+        assert.deepEqual(report.failed, []);
+    } finally {
+        rmSync(home, { recursive: true, force: true });
+    }
+});

package/bin/ever-shipped-skills.mjs

@@ -17,6 +17,7 @@ export const EVER_SHIPPED_SKILL_NAMES = new Set([
     'comments',
     'condensing-instructions',
     'codex-review',
+    'codex-cleanse',
     'context7-mcp',
     'copilot-finding-triage',
     'copilot-review',

package/bin/install.mjs

@@ -197,6 +197,7 @@ export const CORE_INCLUDE_DIRECTORIES = [
 export const CORE_SKILLS = [
     'orchestrator', 'orchestrator-refresh', 'team-advisor',
     'grok-spawn',
+    'codex-cleanse',
     'everything-search',
     'test-runner',
     'privacy-hygiene',

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "claude-dev-env",
-    "version": "8.28.1",
+    "version": "8.29.1",
     "description": "Claude Code development standards — rules, hooks, agents, commands, and skills",
     "type": "module",
     "bin": {