packlight-cli 0.0.0-stage → 0.1.1

package/dist/adapters/codex/logs.js

@@ -0,0 +1,151 @@
+// Reads Codex session logs (~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl): sessions, skill and MCP use, and what
+// each session started with (its world_state record and the input tokens of its first request).
+import { createReadStream, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { createInterface } from 'node:readline';
+function rollouts(dir) {
+    const out = [];
+    const walk = (d) => {
+        let names;
+        try {
+            names = readdirSync(d, { withFileTypes: true }).map(e => (e.isDirectory() ? `${e.name}/` : e.name));
+        }
+        catch {
+            return;
+        }
+        for (const n of names) {
+            if (n.endsWith('/'))
+                walk(join(d, n.slice(0, -1)));
+            else if (/^rollout-.*\.jsonl$/.test(n))
+                out.push(join(d, n));
+        }
+    };
+    walk(dir);
+    return out.sort();
+}
+const push = (m, k, u) => { const l = m.get(k); if (l)
+    l.push(u);
+else
+    m.set(k, [u]); };
+const textOf = (v) => (typeof v === 'string' ? v.length : v && typeof v === 'object' ? JSON.stringify(v).length : 0);
+/** Skills a tool call opened: Codex reads a skill by reading its SKILL.md. Plugin skills are "<plugin>:<skill>". */
+export function skillsIn(text) {
+    const out = new Set();
+    // Either separator, and doubled backslashes as they appear inside JSON-encoded arguments (Windows).
+    const sep = String.raw `[\\/]+`;
+    const seg = String.raw `[^\\/"'\s]+`;
+    const plugin = new RegExp(String.raw `${sep}plugins${sep}cache${sep}${seg}${sep}(${seg})${sep}${seg}${sep}skills${sep}(${seg})${sep}SKILL\.md`, 'g');
+    const own = new RegExp(String.raw `${sep}\.codex${sep}skills${sep}(?:\.system${sep})?(${seg})${sep}SKILL\.md`, 'g');
+    for (const m of text.matchAll(plugin))
+        out.add(`${m[1]}:${m[2]}`);
+    for (const m of text.matchAll(own))
+        out.add(m[1]);
+    return [...out];
+}
+/** MCP servers a tool call used: "mcp__<server>__<tool>" as the tool name, or called from Codex's code mode. */
+export function mcpServersIn(name, input) {
+    const out = new Set();
+    if (typeof name === 'string' && name.startsWith('mcp__'))
+        out.add(name.split('__')[1]);
+    for (const m of input.matchAll(/\bmcp__([A-Za-z0-9_-]+?)__[A-Za-z0-9_]/g))
+        out.add(m[1]);
+    return [...out];
+}
+const KNOWN = new Set(['session_meta', 'response_item', 'event_msg', 'turn_context', 'world_state', 'token_usage_record', 'compacted']);
+export async function scanCodexLogs(dir, opts) {
+    const scan = { sessions: [], skillUses: new Map(), mcpUses: new Map(), starts: [], linesTotal: 0, linesUnknownShape: 0, linesUnreadable: 0, unknownByVersion: {}, versions: [] };
+    const versions = new Set();
+    for (const file of rollouts(dir)) {
+        const s = { id: file, file, projectRoot: null, start: null, end: null, lines: 0, unknownShapeLines: 0, unreadableLines: 0, versions: [] };
+        let version = null;
+        let project = null;
+        let start = null;
+        let firstTokens = null;
+        const rl = createInterface({ input: createReadStream(file, { encoding: 'utf8' }), crlfDelay: Infinity });
+        for await (const line of rl) {
+            if (!line)
+                continue;
+            scan.linesTotal++;
+            s.lines++;
+            let e;
+            try {
+                e = JSON.parse(line);
+            }
+            catch {
+                scan.linesUnreadable++;
+                s.unreadableLines++;
+                continue;
+            }
+            const ts = typeof e?.timestamp === 'string' ? e.timestamp : null;
+            if (ts && opts.since && ts < opts.since)
+                continue;
+            if (ts) {
+                if (!s.start || ts < s.start)
+                    s.start = ts;
+                if (!s.end || ts > s.end)
+                    s.end = ts;
+            }
+            const p = e?.payload ?? {};
+            if (!KNOWN.has(e?.type)) {
+                scan.linesUnknownShape++;
+                if (version)
+                    scan.unknownByVersion[version] = (scan.unknownByVersion[version] ?? 0) + 1;
+                continue;
+            }
+            if (e.type === 'session_meta') {
+                if (typeof p.id === 'string')
+                    s.id = p.id;
+                if (typeof p.cli_version === 'string') {
+                    version = p.cli_version;
+                    versions.add(p.cli_version);
+                    s.versions = [p.cli_version];
+                }
+                if (typeof p.cwd === 'string') {
+                    project = opts.projectOf(p.cwd);
+                    s.projectRoot = project;
+                }
+            }
+            else if (e.type === 'turn_context' && typeof p.cwd === 'string' && !project) {
+                project = opts.projectOf(p.cwd);
+                s.projectRoot = project;
+            }
+            else if (e.type === 'world_state' && !start) {
+                const st = p.state ?? {};
+                const skills = typeof st.host_skills?.body === 'string' ? st.host_skills.body : '';
+                start = {
+                    sessionId: s.id, timestamp: ts, version, projectRoot: project,
+                    skillListingChars: skills.length,
+                    listedSkills: [...skills.matchAll(/^- ([^:\n]+(?::[^:\n ]+)?): /gm)].map(m => m[1].trim()),
+                    agentsMdChars: typeof st.agents_md?.text === 'string' ? st.agents_md.text.length : 0,
+                    pluginInstructionChars: st.plugins_instructions ? textOf(st.plugins_instructions) : 0,
+                    appInstructionChars: st.apps_instructions ? textOf(st.apps_instructions) : 0,
+                    firstRequestTokens: [],
+                };
+            }
+            else if (e.type === 'event_msg' && p.type === 'token_count' && firstTokens === null) {
+                const n = p.info?.last_token_usage?.input_tokens;
+                if (typeof n === 'number')
+                    firstTokens = n;
+            }
+            else if (e.type === 'response_item' && (p.type === 'function_call' || p.type === 'custom_tool_call' || p.type === 'local_shell_call')) {
+                const input = typeof p.input === 'string' ? p.input : typeof p.arguments === 'string' ? p.arguments : JSON.stringify(p.action ?? p.arguments ?? '');
+                const use = { ts, project };
+                for (const k of skillsIn(input))
+                    push(scan.skillUses, k, use);
+                for (const k of mcpServersIn(p.name, input))
+                    push(scan.mcpUses, k, use);
+            }
+        }
+        if (start) {
+            if (firstTokens !== null)
+                start.firstRequestTokens.push(firstTokens);
+            start.projectRoot = project;
+            scan.starts.push(start);
+        }
+        if (s.start)
+            scan.sessions.push(s);
+    }
+    scan.starts.sort((a, b) => (a.timestamp ?? '').localeCompare(b.timestamp ?? ''));
+    scan.versions = [...versions].sort();
+    return scan;
+}

package/dist/adapters/codex/toml.d.ts

@@ -0,0 +1,10 @@
+export type TomlValue = string | number | boolean | TomlValue[] | null;
+export interface TomlTable {
+    path: string[];
+    values: Record<string, TomlValue>;
+    line: number;
+}
+/** Splits a header like `plugins."pdf@openai"` or `mcp_servers.node_repl.env` into its keys. */
+export declare function headerKeys(header: string): string[];
+/** Every table in the file, in order, with its single-line `key = value` pairs. Multi-line values are skipped. */
+export declare function readToml(text: string): TomlTable[];

package/dist/adapters/codex/toml.js

@@ -0,0 +1,76 @@
+// A small reader for the parts of Codex's config.toml packlight needs: table headers and simple values.
+// It never writes TOML; turning a plugin or MCP server off is a step the person takes (removal method "manual").
+/** Splits a header like `plugins."pdf@openai"` or `mcp_servers.node_repl.env` into its keys. */
+export function headerKeys(header) {
+    const keys = [];
+    let i = 0;
+    while (i < header.length) {
+        const c = header[i];
+        if (c === '.' || c === ' ' || c === '\t') {
+            i++;
+            continue;
+        }
+        if (c === '"' || c === "'") {
+            let j = i + 1;
+            let key = '';
+            while (j < header.length && header[j] !== c) {
+                if (c === '"' && header[j] === '\\' && j + 1 < header.length) {
+                    key += header[j + 1];
+                    j += 2;
+                    continue;
+                }
+                key += header[j];
+                j++;
+            }
+            keys.push(key);
+            i = j + 1;
+        }
+        else {
+            let j = i;
+            while (j < header.length && header[j] !== '.')
+                j++;
+            keys.push(header.slice(i, j).trim());
+            i = j;
+        }
+    }
+    return keys;
+}
+function value(raw) {
+    const v = raw.trim();
+    if (v === 'true')
+        return true;
+    if (v === 'false')
+        return false;
+    if (/^-?\d+(\.\d+)?$/.test(v))
+        return Number(v);
+    if (v.startsWith('"') && v.endsWith('"') && v.length >= 2)
+        return v.slice(1, -1).replace(/\\"/g, '"').replace(/\\\\/g, '\\');
+    if (v.startsWith("'") && v.endsWith("'") && v.length >= 2)
+        return v.slice(1, -1);
+    if (v.startsWith('[') && v.endsWith(']')) {
+        const inner = v.slice(1, -1).trim();
+        return inner ? inner.split(/,(?=(?:[^"]*"[^"]*")*[^"]*$)/).map(x => value(x)) : [];
+    }
+    return null;
+}
+/** Every table in the file, in order, with its single-line `key = value` pairs. Multi-line values are skipped. */
+export function readToml(text) {
+    const tables = [{ path: [], values: {}, line: 0 }];
+    const lines = text.split(/\r?\n/);
+    lines.forEach((line, n) => {
+        const t = line.replace(/\s+#.*$/, '').trim();
+        if (!t || t.startsWith('#'))
+            return;
+        const h = /^\[\s*([^\[\]]+?)\s*\]$/.exec(t);
+        if (h) {
+            tables.push({ path: headerKeys(h[1]), values: {}, line: n + 1 });
+            return;
+        }
+        const kv = /^("[^"]+"|'[^']+'|[A-Za-z0-9_.-]+)\s*=\s*(.+)$/.exec(t);
+        if (!kv)
+            return;
+        const key = kv[1].replace(/^["']|["']$/g, '');
+        tables[tables.length - 1].values[key] = value(kv[2]);
+    });
+    return tables;
+}

package/dist/archive/apply.d.ts

@@ -0,0 +1,62 @@
+import type { Item, RemovalMethod } from '../core/types.js';
+import { type RecoveryResult } from './journal.js';
+import { type PacklightPaths } from './paths.js';
+export type PickAction = 'archive' | 'keep' | 'unkeep';
+export interface Picks {
+    scanId: string;
+    picks: {
+        id: string;
+        action: PickAction;
+    }[];
+}
+export declare const STALE_PICKS = "These picks are from an older scan. Re-open the newest report and save again.";
+/**
+ * A picks file is untrusted input (CEO F3): only a scan id and item ids with an action are read.
+ * Paths, commands or anything else in the file are ignored.
+ */
+export declare function parsePicks(text: string): Picks;
+/** The newest packlight-picks-*.json in a folder (the report saves there). */
+export declare function findPicksFile(dir: string | undefined): string | undefined;
+/** Claude Code may rewrite settings.json while packlight edits it (D21): warn when it is running. */
+export declare function claudeCodeRunning(): boolean;
+export interface ApplyOptions {
+    home: string;
+    packlightRoot?: string;
+    picksFile: string;
+    yes: boolean;
+    confirm: (question: string) => Promise<boolean>;
+    claudeRunning: () => boolean;
+    out: (line: string) => void;
+    now?: () => Date;
+    crash?: (point: string) => void;
+    /** Ask this one question for the whole plan instead of one per method group (packlight fix). */
+    singleQuestion?: string;
+}
+export interface ApplyResult {
+    exitCode: number;
+    archived: {
+        item: Item;
+        opIds: string[];
+    }[];
+    refused: {
+        item: Item;
+        reason: string;
+    }[];
+    unknownIds: string[];
+    declined: RemovalMethod[];
+    stillEffective: Item[];
+    kept: number;
+    unkept: number;
+}
+export declare function reportRecovery(r: RecoveryResult, out: (l: string) => void): void;
+export declare function apply(opts: ApplyOptions): Promise<ApplyResult>;
+interface KeepsFile {
+    version: 1;
+    keeps: Record<string, {
+        name: string;
+        keptAt: string;
+        fingerprintAtKeep: string;
+    }>;
+}
+export declare function readKeeps(paths: PacklightPaths): KeepsFile;
+export {};

package/dist/archive/apply.js

@@ -0,0 +1,284 @@
+import { execFileSync } from 'node:child_process';
+import { appendFileSync, existsSync, mkdirSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { claudePaths, collectInventory } from '../adapters/claude-code/inventory.js';
+import { codexPaths, collectCodexInventory } from '../adapters/codex/inventory.js';
+import { INVOKE } from '../core/messages.js';
+import { atomicWrite, fileHash } from './fsops.js';
+import { recover } from './journal.js';
+import { acquireLock } from './lock.js';
+import { archiveStep, comparePointersDesc } from './methods.js';
+import { newestScan, packlightPaths, readScan } from './paths.js';
+export const STALE_PICKS = 'These picks are from an older scan. Re-open the newest report and save again.';
+/**
+ * A picks file is untrusted input (CEO F3): only a scan id and item ids with an action are read.
+ * Paths, commands or anything else in the file are ignored.
+ */
+export function parsePicks(text) {
+    let raw;
+    try {
+        raw = JSON.parse(text);
+    }
+    catch {
+        throw new Error('The picks file is not valid JSON.');
+    }
+    if (!raw || typeof raw.scanId !== 'string' || !Array.isArray(raw.picks))
+        throw new Error('The picks file has no scanId or picks list.');
+    const picks = raw.picks
+        .filter((p) => p && typeof p.id === 'string' && ['archive', 'keep', 'unkeep'].includes(p.action))
+        .map((p) => ({ id: p.id, action: p.action }));
+    return { scanId: raw.scanId, picks };
+}
+/** The newest packlight-picks-*.json in a folder (the report saves there). */
+export function findPicksFile(dir) {
+    if (!dir)
+        return undefined;
+    let names;
+    try {
+        names = readdirSync(dir).filter(n => /^packlight-picks-.*\.json$/.test(n));
+    }
+    catch {
+        return undefined;
+    }
+    return names.map(n => join(dir, n)).sort((a, b) => statSync(b).mtimeMs - statSync(a).mtimeMs)[0];
+}
+/** Claude Code may rewrite settings.json while packlight edits it (D21): warn when it is running. */
+export function claudeCodeRunning() {
+    try {
+        const out = process.platform === 'win32'
+            ? execFileSync('tasklist', ['/FO', 'CSV', '/NH'], { encoding: 'utf8' })
+            : execFileSync('ps', ['-A', '-o', 'comm='], { encoding: 'utf8' });
+        return /(^|[\\/"])claude(\.exe)?("|\s|$)/im.test(out);
+    }
+    catch {
+        return false;
+    }
+}
+const KIND_PLURAL = { skill: 'skills', command: 'commands', agent: 'agents', hook: 'hooks', plugin: 'plugins', mcp: 'MCP servers', instructions: 'instruction files' };
+const GROUP_TEXT = {
+    move: n => `Move ${n} item${n === 1 ? '' : 's'} into packlight's archive`,
+    'hook-extract': n => `Cut ${n} hook${n === 1 ? '' : 's'} out of their settings files`,
+    'mcp-extract': n => `Cut ${n} MCP server${n === 1 ? '' : 's'} out of their config files`,
+    'plugin-disable': n => `Turn off ${n} plugin${n === 1 ? '' : 's'}`,
+    manual: n => `Record ${n} item${n === 1 ? '' : 's'} you remove by hand`,
+};
+export function reportRecovery(r, out) {
+    for (const x of r.completed)
+        out(`Recovered: finished an interrupted ${x}.`);
+    for (const x of r.rolledBack)
+        out(`Recovered: rolled back an interrupted ${x}.`);
+    for (const x of r.refused)
+        out(`Recovery stopped: ${x.direction} ${x.opId} left ${x.files.join(', ')} in a state packlight did not expect. Nothing was changed; check those files by hand.`);
+}
+const existingRoots = (inv) => inv.projects.filter(p => existsSync(p.root)).map(p => p.root);
+/** The setup as it is now, read by the same adapter that made the scan. */
+const readNow = (inv, home) => (inv.agent === 'codex' ? collectCodexInventory(codexPaths(home), existingRoots(inv)) : collectInventory(claudePaths(home), existingRoots(inv)));
+/** Builds the steps for one item from its current declarations (eng X2: every place it is switched on). */
+function stepsFor(item, home) {
+    switch (item.removal.method) {
+        case 'move': return item.path ? [{ method: 'move', item, path: item.path }] : [];
+        case 'hook-extract':
+        case 'mcp-extract':
+            return item.declarations.filter(d => d.pointer).map(d => ({ method: item.removal.method, item, file: d.file, pointer: d.pointer }));
+        case 'plugin-disable': {
+            const key = item.plugin ?? item.name;
+            const on = item.declarations.filter(d => d.pointer?.startsWith('/enabledPlugins/') && d.enabled !== false);
+            if (on.length)
+                return on.map(d => ({ method: 'plugin-disable', item, file: d.file, pointer: d.pointer, key }));
+            // Installed but never declared means enabled: turn it off in user settings.
+            return item.enabled ? [{ method: 'plugin-disable', item, file: join(claudePaths(home).claude, 'settings.json'), pointer: `/enabledPlugins/${key.replace(/~/g, '~0').replace(/\//g, '~1')}`, key }] : [];
+        }
+        case 'manual': return [{ method: 'manual', item, where: item.removal.where ?? 'the app it came from' }];
+    }
+}
+export async function apply(opts) {
+    const paths = packlightPaths(opts.home, opts.packlightRoot);
+    const now = opts.now ?? (() => new Date());
+    const out = opts.out;
+    const result = { exitCode: 0, archived: [], refused: [], unknownIds: [], declined: [], stillEffective: [], kept: 0, unkept: 0 };
+    // Recovery and every change happen under the lock, so one run never rolls back another's work in progress.
+    const release = acquireLock(paths.lock);
+    try {
+        return await applyLocked(opts, paths, now, out, result);
+    }
+    finally {
+        release();
+    }
+}
+async function applyLocked(opts, paths, now, out, result) {
+    const recovery = recover(paths);
+    reportRecovery(recovery, out);
+    if (recovery.refused.length)
+        return { ...result, exitCode: 1 };
+    const picks = parsePicks(readFileSync(opts.picksFile, 'utf8'));
+    const inv = readScan(paths, picks.scanId);
+    if (!inv)
+        throw new Error(`These picks name scan ${picks.scanId}, which packlight does not have. Run \`${INVOKE}\` and save your picks again.`);
+    if (newestScan(paths, inv.agent, inv.projectScope)?.scanId !== picks.scanId)
+        throw new Error(STALE_PICKS);
+    const byId = new Map(inv.items.map(i => [i.id, i]));
+    result.unknownIds = picks.picks.filter(p => !byId.has(p.id)).map(p => p.id);
+    for (const id of result.unknownIds)
+        out(`Skipped ${id}: not an item in scan ${picks.scanId}.`);
+    // The current state of every item, read fresh: a target that changed since the scan is refused (eng X1).
+    const fresh = new Map(readNow(inv, opts.home).map(i => [i.id, i]));
+    // Baseline hashes are taken now, with the inventory the plan is built from, not after the questions (CEO F2).
+    const baseline = new Map();
+    for (const i of fresh.values())
+        for (const d of i.declarations)
+            if (d.pointer && !baseline.has(d.file))
+                baseline.set(d.file, fileHash(d.file));
+    baseline.set(join(claudePaths(opts.home).claude, 'settings.json'), fileHash(join(claudePaths(opts.home).claude, 'settings.json')));
+    // Plugins are the removal unit for everything they bundle (CEO O3).
+    const pluginOf = (i) => (i.plugin && i.kind !== 'plugin' ? inv.items.find(p => p.kind === 'plugin' && p.plugin === i.plugin) ?? i : i);
+    const targets = new Map();
+    for (const p of picks.picks.filter(p => p.action === 'archive' && byId.has(p.id))) {
+        const t = pluginOf(byId.get(p.id));
+        targets.set(t.id, t);
+    }
+    const plan = [];
+    for (const t of targets.values()) {
+        const cur = fresh.get(t.id);
+        if (!cur) {
+            result.refused.push({ item: t, reason: 'It is no longer installed (already archived or removed).' });
+            continue;
+        }
+        if (cur.targetFingerprint !== t.targetFingerprint) {
+            result.refused.push({ item: t, reason: 'It changed since you reviewed it. Scan again and re-mark it.' });
+            continue;
+        }
+        const steps = stepsFor(cur, opts.home);
+        if (!steps.length) {
+            result.refused.push({ item: t, reason: 'It is already turned off everywhere.' });
+            continue;
+        }
+        plan.push({ item: cur, steps });
+    }
+    const keeps = picks.picks.filter(p => p.action === 'keep' && byId.has(p.id));
+    const unkeeps = picks.picks.filter(p => p.action === 'unkeep' && byId.has(p.id));
+    // Show the plan grouped by method.
+    const groups = new Map();
+    for (const p of plan) {
+        const m = p.item.removal.method;
+        groups.set(m, [...(groups.get(m) ?? []), p]);
+    }
+    out(`Plan for scan ${picks.scanId}:`);
+    for (const [method, list] of groups) {
+        out(`\n${GROUP_TEXT[method](list.length)}:`);
+        for (const { item, steps } of list) {
+            const impact = item.kind === 'plugin' && item.members && Object.keys(item.members).length ? ` (${Object.entries(item.members).map(([k, n]) => `${n} ${n === 1 ? k : KIND_PLURAL[k]}`).join(', ')})` : '';
+            const where = steps.map(s => ('file' in s ? s.file : 'path' in s ? s.path : s.where)).join('; ');
+            out(`  ${item.name}${impact}  ${where}`);
+        }
+    }
+    if (keeps.length || unkeeps.length)
+        out(`\nKeep: ${keeps.length} item${keeps.length === 1 ? '' : 's'}${unkeeps.length ? `, clear ${unkeeps.length} keep${unkeeps.length === 1 ? '' : 's'}` : ''} (no change to your setup)`);
+    for (const r of result.refused)
+        out(`\nNot archived: ${r.item.name}. ${r.reason}`);
+    const touchesSettings = plan.some(p => p.steps.some(s => 'file' in s));
+    if (touchesSettings && opts.claudeRunning()) {
+        out(`\n${inv.agent === 'codex' ? 'Codex' : 'Claude Code'} is running. It can rewrite its settings files while packlight edits them; packlight checks each file just before writing, but a write in the same instant could still be lost.`);
+        if (!opts.yes && !opts.singleQuestion && !(await opts.confirm('Continue anyway?'))) {
+            out('Stopped. Nothing was changed.');
+            return { ...result, exitCode: 1 };
+        }
+    }
+    if (opts.singleQuestion && plan.length && !opts.yes && !(await opts.confirm(`\n${opts.singleQuestion}`))) {
+        out('Stopped. Nothing was changed.');
+        return { ...result, exitCode: 1 };
+    }
+    // One question per method group (acceptance criterion 7); "no" leaves that group untouched.
+    const approved = [];
+    for (const [method, list] of groups) {
+        if (opts.yes || opts.singleQuestion || (await opts.confirm(`${GROUP_TEXT[method](list.length)}?`)))
+            approved.push(...list);
+        else
+            result.declined.push(method);
+    }
+    const refusedBeforeRun = result.refused.length;
+    {
+        const ctx = { paths, scanId: picks.scanId, now, expectedHash: new Map(), crash: opts.crash ?? (() => { }) };
+        const steps = approved.flatMap(p => p.steps);
+        for (const s of steps)
+            if ('file' in s && !ctx.expectedHash.has(s.file))
+                ctx.expectedHash.set(s.file, baseline.has(s.file) ? baseline.get(s.file) : fileHash(s.file));
+        // Settings edits first, per file with the deepest pointers first so array removals never shift later ones.
+        const ordered = [
+            ...steps.filter((s) => 'file' in s).sort((a, b) => a.file.localeCompare(b.file) || comparePointersDesc(a.pointer, b.pointer)),
+            ...steps.filter(s => s.method === 'move'),
+            ...steps.filter(s => s.method === 'manual'),
+        ];
+        const outcomes = new Map();
+        for (const s of ordered) {
+            const o = archiveStep(ctx, s);
+            const rec = outcomes.get(s.item.id) ?? { item: s.item, opIds: [], failures: [] };
+            if (o.ok)
+                rec.opIds.push(o.opId);
+            else
+                rec.failures.push(o.reason);
+            outcomes.set(s.item.id, rec);
+            log(paths, `${now().toISOString()} archive ${s.method} ${s.item.id} ${o.ok ? `ok ${o.opId}` : `refused: ${o.reason}`}`);
+        }
+        for (const r of outcomes.values()) {
+            if (r.opIds.length)
+                result.archived.push({ item: r.item, opIds: r.opIds });
+            for (const f of r.failures)
+                result.refused.push({ item: r.item, reason: f });
+        }
+        const k = writeKeeps(paths, keeps.map(p => byId.get(p.id)), unkeeps.map(p => p.id), now());
+        result.kept = k.kept;
+        result.unkept = k.unkept;
+    }
+    // Verify against a fresh read that each archived item is no longer in effect (eng X2).
+    const after = new Map(readNow(inv, opts.home).map(i => [i.id, i]));
+    for (const { item } of result.archived) {
+        const a = after.get(item.id);
+        if (!a || item.removal.method === 'manual')
+            continue;
+        const stillOn = item.removal.method === 'plugin-disable' ? a.enabled || a.declarations.some(d => d.pointer?.startsWith('/enabledPlugins/') && d.enabled !== false) : true;
+        if (stillOn)
+            result.stillEffective.push(item);
+    }
+    out('');
+    for (const a of result.archived)
+        out(`Archived ${a.item.name}${a.item.removal.method === 'manual' ? ' (remove it by hand: ' + (a.item.removal.where ?? '') + ')' : ''}. Restore: ${INVOKE} restore ${a.opIds.join(' ')}`);
+    for (const r of result.refused.slice(refusedBeforeRun))
+        out(`Refused ${r.item.name}: ${r.reason}`);
+    for (const s of result.stillEffective)
+        out(`Still in effect after apply: ${s.name}. Another settings file may switch it on; scan to see where.`);
+    if (result.kept || result.unkept)
+        out(`Kept ${result.kept} item${result.kept === 1 ? '' : 's'}${result.unkept ? `, cleared ${result.unkept} keep${result.unkept === 1 ? '' : 's'}` : ''}.${result.archived.length ? '' : ' Nothing archived.'}`);
+    if (result.declined.length)
+        out(`Skipped at your answer: ${result.declined.map(m => GROUP_TEXT[m](groups.get(m).length).toLowerCase()).join('; ')}.`);
+    result.exitCode = result.refused.length || result.stillEffective.length ? 1 : 0;
+    return result;
+}
+function log(paths, line) {
+    mkdirSync(paths.root, { recursive: true });
+    appendFileSync(paths.log, line + '\n');
+}
+export function readKeeps(paths) {
+    try {
+        return JSON.parse(readFileSync(paths.keeps, 'utf8'));
+    }
+    catch {
+        return { version: 1, keeps: {} };
+    }
+}
+/** Keeps are written without a prompt (DE3), keyed by item id with the fingerprint at keep time (DE2), and cleared by unkeep (DE10). */
+function writeKeeps(paths, keep, unkeep, now) {
+    if (!keep.length && !unkeep.length)
+        return { kept: 0, unkept: 0 };
+    const f = readKeeps(paths);
+    for (const i of keep)
+        f.keeps[i.id] = { name: i.name, keptAt: now.toISOString(), fingerprintAtKeep: i.targetFingerprint };
+    let unkept = 0;
+    for (const id of unkeep)
+        if (id in f.keeps) {
+            delete f.keeps[id];
+            unkept++;
+        }
+    atomicWrite(paths.keeps, JSON.stringify(f, null, 1) + '\n');
+    log(paths, `${now.toISOString()} keeps +${keep.length} -${unkept}`);
+    return { kept: keep.length, unkept };
+}

package/dist/archive/fsops.d.ts

@@ -0,0 +1,24 @@
+import { renameSync } from 'node:fs';
+/** rename with a bounded retry: Windows reports EPERM/EBUSY while another process briefly holds a file (eng SC1). */
+export declare function renameWithRetry(from: string, to: string, rename?: typeof renameSync): void;
+/** Settings writes go through write-file-atomic, which keeps the file's mode and owner (eng SC2). */
+export declare function atomicWrite(path: string, data: string | Buffer): void;
+export declare const fileHash: (path: string) => string | null;
+export declare const exists: (path: string) => boolean;
+/** Fingerprint of a path, or "missing" (journal states compare these). */
+export declare const stateOf: (path: string) => string;
+export declare class ChangedWhileMoving extends Error {
+}
+/** The verified copy is in place but the source could not be fully removed: both must be kept. */
+export declare class SourceNotRemoved extends Error {
+}
+/** Where a cross-volume move stages its copy: hidden, beside the destination, and recorded in the journal as scratch. */
+export declare const stagingPathFor: (to: string) => string;
+/**
+ * Moves a file, folder or link. Same volume: one rename. Across volumes (EXDEV): copy into a staging path
+ * beside the destination, check the copy against the source's fingerprint, re-check the source, then swap
+ * the staging copy in and remove the source (eng X4). A link is moved as a link, never followed.
+ */
+export declare function moveTree(from: string, to: string, opts?: {
+    rename?: typeof renameSync;
+}): void;