freeharness 0.4.1 → 0.4.2

package/dist/cli/cleanup-prompt.js

@@ -0,0 +1,68 @@
+import { applyCleanup } from "./cleanup.js";
+import { applyHard, printable } from "./hard-cleanup.js";
+/**
+ * Maps the answers to pass-2 actions; the hard answer counts only with --hard.
+ * @param offersMoves The cleanup plan holds an archive item, so the abort line names moves too.
+ */
+export function cleanupDecision(answers, withHard, offersMoves = false) {
+    const moveHard = withHard && answers.hard;
+    const nothing = !answers.main && !answers.backups && !moveHard;
+    let abort;
+    if (nothing)
+        abort = withHard || offersMoves ? "Aborted; nothing was removed or moved." : "Aborted; nothing was removed.";
+    return { abort, remove: (i) => (i.group === "backups" ? answers.backups : answers.main), moveHard };
+}
+/** The first cleanup confirmation; a zero remove or archive count is left out. */
+function mainPrompt(removeCount, archiveCount) {
+    if (archiveCount === 0)
+        return `\nRemove the ${removeCount} item(s) above (backups excluded)?`;
+    if (removeCount === 0)
+        return `\nArchive the ${archiveCount} item(s) above (backups excluded)?`;
+    return `\nRemove ${removeCount} and archive ${archiveCount} item(s) above (backups excluded)?`;
+}
+/** The third cleanup confirmation, for the hard items. */
+export function hardPrompt(count, archiveRoot) {
+    return `Move the ${count} item(s) to ${printable(archiveRoot)}?`;
+}
+/** Asks the three confirmations, then applies what was confirmed; undefined when all were no. */
+export async function runCleanupPass2(input) {
+    const { plan, hard, yes, prompt, log } = input;
+    const removable = plan.items.filter((i) => !i.refused);
+    const main = removable.filter((i) => i.group !== "backups");
+    const backups = removable.filter((i) => i.group === "backups");
+    const movable = hard?.items.filter((i) => !i.refused) ?? [];
+    const archive = main.filter((i) => i.archiveDest !== undefined).length;
+    let confirmMain = yes;
+    let confirmBackups = yes;
+    let confirmHard = yes;
+    if (!yes) {
+        if (main.length > 0)
+            confirmMain = await prompt.confirm(mainPrompt(main.length - archive, archive));
+        if (backups.length > 0) {
+            const total = backups.reduce((n, b) => n + (b.bytes ?? 0), 0);
+            confirmBackups = await prompt.confirm(`Also delete the ${backups.length} memory backup dir(s) (${total >= 1048576 ? `${(total / 1048576).toFixed(1)} MB` : `${total} B`})? They cannot be recovered.`);
+        }
+        if (hard && movable.length > 0)
+            confirmHard = await prompt.confirm(hardPrompt(movable.length, hard.archiveRoot));
+    }
+    const decision = cleanupDecision({ main: confirmMain, backups: confirmBackups, hard: confirmHard }, hard !== undefined, archive > 0);
+    if (decision.abort) {
+        log(decision.abort);
+        return undefined;
+    }
+    const done = applyCleanup(plan, decision.remove);
+    for (const r of done.removed)
+        log(`  removed: ${printable(r)}`);
+    for (const m of done.moved)
+        log(`  moved:   ${printable(m)}`);
+    for (const k of done.skipped)
+        log(`  kept:    ${printable(k)}`);
+    for (const w of done.warnings)
+        log(`  WARN     ${printable(w)}`);
+    const archived = hard && decision.moveHard ? applyHard(hard) : undefined;
+    for (const m of archived?.moved ?? [])
+        log(`  moved:   ${printable(m)}`);
+    for (const w of archived?.warnings ?? [])
+        log(`  WARN     ${printable(w)}`);
+    return { done, archived };
+}

package/dist/cli/cleanup.d.ts

@@ -1,6 +1,5 @@
 import type { Scope } from "@freeharness/core";
 import { UPSTREAM_PLUGIN_NAME } from "../adapters/memory/vendored.js";
-import { type InstallManifest } from "../infra/manifest.js";
 import { type MemoryDiagnosis } from "../adapters/memory/doctor.js";
 /** The vendored `openspec` bin replaces it. */
 export declare const LEGACY_OPENSPEC_PACKAGE = "@fission-ai/openspec";
@@ -8,25 +7,11 @@ export declare const LEGACY_OPENSPEC_PACKAGE = "@fission-ai/openspec";
 export declare const CLI_PACKAGE = "freeharness";
 /** Backups confirm separately. */
 export type CleanupGroup = "memory" | "backups" | "legacy" | "duplicates" | "npm" | "retired";
-/** Retired by a rename or a fold, bare names under `~/.claude`. */
-export declare const RETIRED: {
-    readonly skills: readonly ["local-code-intel"];
-    readonly agents: readonly ["mle-reviewer", "mle-evaluator"];
-};
-/** One retired name found on disk, with its manifest-recorded flag. */
-export interface RetiredFinding {
-    kind: "skill" | "agent";
-    name: string;
-    /** Skill dir or agent file. */
-    path: string;
-    /** Manifest lists `path` (agent) or a file under it (skill dir). */
-    recorded: boolean;
-}
-/** Whose entries a `hooks` item prunes. */
-export type HookOwner = "freeharness" | typeof UPSTREAM_PLUGIN_NAME;
+/** Whose entries a `hooks` item prunes; `retired` is only the entries running a retired hook script. */
+export type HookOwner = "freeharness" | typeof UPSTREAM_PLUGIN_NAME | "retired";
 /** One leftover the cleanup knows how to remove. */
 export interface CleanupItem {
-    kind: "dir" | "file" | "hooks" | "npm-global" | "settings-key";
+    kind: "dir" | "file" | "hooks" | "npm-global" | "json-key";
     /** Filesystem path, or the package name for `npm-global`. */
     target: string;
     reason: string;
@@ -39,8 +24,14 @@ export interface CleanupItem {
     hookOwner?: HookOwner;
     /** `npm-global` items: try `npm unlink -g` first, then `npm uninstall -g`. */
     unlink?: boolean;
-    /** `settings-key` items: the `enabledPlugins` key removed from `target`. */
-    settingsKey?: string;
+    /** `json-key` items: the key removed from the JSON object in `target`, outermost first. */
+    keyPath?: string[];
+    /** Plugin-cache and IDE-rule items: the archive path the item moves to instead of being removed; `json-key` items: where the pre-edit copy goes. */
+    archiveDest?: string;
+    /** Marks an IDE rule file, whose archive check differs from a plugin-cache item's. */
+    ideRule?: boolean;
+    /** Upstream launcher items, each kind with its own pass-2 check. */
+    launcher?: "mcp" | "marketplace";
 }
 /** What a cleanup pass would (or did) do. */
 export interface CleanupPlan {
@@ -48,10 +39,14 @@ export interface CleanupPlan {
     items: CleanupItem[];
     /** Informational lines: seen, but out of the fixed list. */
     notes: string[];
+    /** User scope: the dated archive every `archiveDest` lies in. */
+    archiveRoot?: string;
 }
 /** Outcome of `applyCleanup`. */
 export interface CleanupResult {
     removed: string[];
+    /** One `source -> destination` line per plugin-cache item moved into the archive. */
+    moved: string[];
     /** Refused, or not confirmed. */
     skipped: string[];
     /** Non-fatal failures (an npm uninstall that exited non-zero). */
@@ -63,6 +58,8 @@ export interface CleanupDeps {
     memory?: MemoryDiagnosis;
     /** Names the agents/skills a project may duplicate. */
     canonicalDir?: string;
+    /** The run's dated archive, shared with the hard plan (default: today's under the home dir). */
+    archiveRoot?: string;
 }
 /** Sums the size (bytes) of every file under a directory. */
 export declare function dirBytes(dir: string): number;
@@ -72,12 +69,13 @@ export declare function humanBytes(n: number): string;
 export declare function globalNpmPackages(): Record<string, string> | null;
 /** The `<npm prefix -g>/bin/freeharness` shadowing ours on PATH (an old `npm link -g`); undefined when absent, identical to ours, or npm is unavailable. */
 export declare function globalNpmFreeharnessBin(): string | undefined;
-/** Claude-mem data backups written by `freeharness memory backup` (`<dataDir>-backup-<stamp>`), oldest first. */
-export declare function memoryBackupDirs(): string[];
+/**
+ * Memory data backups written by `freeharness memory backup` (`<dataDir>-backup-<stamp>`), sorted.
+ * Backups of either default directory name count, whichever directory is in use now.
+ */
+export declare function memoryBackupDirs(env?: Record<string, string | undefined>, home?: string): string[];
 /** Drops install-manifest entries whose file no longer exists (else every removal is "drift"); 0 without a manifest. */
 export declare function pruneManifest(scope: Scope, projectRoot: string): number;
-/** Retired skill/agent names still present under a `.claude` dir: `update`'s additive merge never deletes them; an absent path is skipped. */
-export declare function retiredFindings(claudeDir: string, manifest: InstallManifest | undefined): RetiredFinding[];
 /** Builds the cleanup plan for a scope without touching anything; `items` is empty when there is nothing to do. */
 export declare function planCleanup(scope: Scope, projectRoot: string, deps?: CleanupDeps): Promise<CleanupPlan>;
 /** Removes the confirmed items of a plan (`confirmed` defaults to all); refused items are always skipped. */

package/dist/cli/cleanup.js

@@ -2,30 +2,48 @@
 // discovered by heuristics. User scope: parked upstream claude-mem + data backups, upstream
 // claude-mem hooks in settings.json (once the plugin is registered), legacy /openspec commands,
 // the global @fission-ai/openspec package, a global npm `freeharness` link, retired names
-// (RETIRED) still on disk after a rename or a fold when the manifest records them. Project
+// (RETIRED in install-facts.ts) still on disk after a rename or a fold when the manifest records them,
+// retired hook scripts and the settings entries that run them. Project
 // scope: legacy /openspec commands, project copies of canonical agents/skills, duplicate
 // FreeHarness hook entries. Never listed: the schema override, non-canonical skills/agents,
 // `openspec-*` skills, `.claude/commands/opsx/` (the user's or ours).
 //
 // Two-pass: `planCleanup` computes the list untouched; `applyCleanup` removes the confirmed items.
+// Items under the Claude Code plugin cache are never deleted: they move into the dated archive
+// through the hard-cleanup mover.
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { spawnSync } from "node:child_process";
-import { PLUGIN_KEY, PLUGIN_NAME, UPSTREAM_MARKETPLACE_OWNER, UPSTREAM_PLUGIN_KEY, UPSTREAM_PLUGIN_NAME } from "../adapters/memory/vendored.js";
+import { PLUGIN_KEY, UPSTREAM_MARKETPLACE_OWNER, UPSTREAM_PLUGIN_KEY, UPSTREAM_PLUGIN_NAME } from "../adapters/memory/vendored.js";
 import { manifestPath, readManifest } from "../infra/manifest.js";
-import { configDir, dataDir, diagnoseMemory } from "../adapters/memory/doctor.js";
-import { canonicalNames, memoryPluginInstalled } from "./doctor.js";
+import { configDir, diagnoseMemory } from "../adapters/memory/doctor.js";
+import { FREE_DIR_NAME, LEGACY_DIR_NAME, resolveMemoryPaths } from "../adapters/memory/paths.js";
+import { canonicalNames, memoryPluginInstalled, RETIRED, retiredFindings, runsRetiredHook } from "./install-facts.js";
 import { isClaudeMemHook, isOurHook, pruneHooksMatching } from "./uninstall.js";
+import { archiveMove, archiveRootFor, isOrHolds, moveWarning, pluginCacheArchive, pluginCacheOverlap, pluginCacheRefusal } from "./hard-cleanup.js";
+import { removeJsonKey } from "./json-key-edit.js";
+import { configCopyArchive, launcherStillMatches, launcherText, marketplaceRefusal, planUpstreamLaunchers } from "./upstream-launchers.js";
 /** The vendored `openspec` bin replaces it. */
 export const LEGACY_OPENSPEC_PACKAGE = "@fission-ai/openspec";
 /** A global link of it shadows the ~/.local/bin symlink. */
 export const CLI_PACKAGE = "freeharness";
-/** Retired by a rename or a fold, bare names under `~/.claude`. */
-export const RETIRED = {
-    skills: ["local-code-intel"],
-    agents: ["mle-reviewer", "mle-evaluator"],
-};
+/** An entry mixing a retired script with another command is not one we emitted, so it stays. */
+function isRetiredHook(e) {
+    const commands = (e.hooks ?? []).map((h) => h.command ?? "");
+    return commands.length > 0 && commands.every(runsRetiredHook);
+}
+function hookPredicate(owner) {
+    if (owner === UPSTREAM_PLUGIN_NAME)
+        return isClaudeMemHook;
+    return owner === "retired" ? isRetiredHook : isOurHook;
+}
+/** Upstream IDE rule files under the home dir, relative; fixed list. */
+const IDE_RULE_FILES = [
+    path.join(".agent", "rules", `${UPSTREAM_PLUGIN_NAME}-context.md`),
+    path.join(".agents", "rules", `${UPSTREAM_PLUGIN_NAME}-context.md`),
+    path.join(".agent", "rules", "free-mem-context.md"),
+];
 /** Sums the size (bytes) of every file under a directory. */
 export function dirBytes(dir) {
     let total = 0;
@@ -93,18 +111,26 @@ export function globalNpmFreeharnessBin() {
     }
     return bin;
 }
-/** Claude-mem data backups written by `freeharness memory backup` (`<dataDir>-backup-<stamp>`), oldest first. */
-export function memoryBackupDirs() {
-    const data = dataDir();
-    const parent = path.dirname(data);
-    const prefix = `${path.basename(data)}-backup-`;
-    if (!fs.existsSync(parent))
-        return [];
-    return fs
-        .readdirSync(parent, { withFileTypes: true })
-        .filter((e) => e.isDirectory() && e.name.startsWith(prefix))
-        .map((e) => path.join(parent, e.name))
-        .sort();
+/**
+ * Memory data backups written by `freeharness memory backup` (`<dataDir>-backup-<stamp>`), sorted.
+ * Backups of either default directory name count, whichever directory is in use now.
+ */
+export function memoryBackupDirs(env = process.env, home = os.homedir()) {
+    const live = resolveMemoryPaths(env, home).dataDir;
+    const dirs = [live, path.join(home, FREE_DIR_NAME), path.join(home, LEGACY_DIR_NAME)];
+    const found = new Set();
+    for (const data of dirs) {
+        const parent = path.dirname(data);
+        const prefix = `${path.basename(data)}-backup-`;
+        if (!fs.existsSync(parent))
+            continue;
+        for (const e of fs.readdirSync(parent, { withFileTypes: true })) {
+            const candidate = path.join(parent, e.name);
+            if (e.isDirectory() && e.name.startsWith(prefix) && !isOrHolds(candidate, live))
+                found.add(candidate);
+        }
+    }
+    return [...found].sort();
 }
 /** Plugin keys registered in Claude Code's installed_plugins.json (e.g. "name@marketplace"); empty when absent or unreadable. */
 function installedPluginKeys(cfg) {
@@ -128,29 +154,16 @@ export function pruneManifest(scope, projectRoot) {
         fs.writeFileSync(file, JSON.stringify({ ...m, files: kept, updatedAt: new Date().toISOString() }, null, 2) + "\n");
     return dropped;
 }
-/** Retired skill/agent names still present under a `.claude` dir: `update`'s additive merge never deletes them; an absent path is skipped. */
-export function retiredFindings(claudeDir, manifest) {
-    const groups = [
-        { kind: "skill", dir: "skills", names: RETIRED.skills },
-        { kind: "agent", dir: "agents", names: RETIRED.agents },
-    ];
-    const found = [];
-    for (const { kind, dir, names } of groups) {
-        for (const name of names) {
-            const fileName = kind === "agent" ? `${name}.md` : name;
-            const p = path.join(claudeDir, dir, fileName);
-            if (!fs.existsSync(p))
-                continue;
-            const under = `${p}${path.sep}`;
-            const recorded = manifest?.files.some((f) => f.path === p || f.path.startsWith(under)) ?? false;
-            found.push({ kind, name, path: p, recorded });
-        }
-    }
-    return found;
+/** Routes a plugin-cache item into the dated archive; an earlier refusal wins over the containment one. */
+function toArchive(item, cfg, archiveRoot) {
+    const archive = pluginCacheArchive(item.target, cfg, archiveRoot);
+    return { ...item, archiveDest: archive.destination, refused: item.refused ?? archive.refused };
 }
+const UPSTREAM_ENABLED_REFUSAL = `the ${UPSTREAM_PLUGIN_KEY} key is still enabled — disable it first: \`claude plugin disable ${UPSTREAM_PLUGIN_KEY}\``;
 /** Computes the user-scope cleanup list; nothing is touched. */
 async function planUser(deps) {
-    const plan = { scope: "user", items: [], notes: [] };
+    const archiveRoot = deps.archiveRoot ?? archiveRootFor(os.homedir(), new Date());
+    const plan = { scope: "user", items: [], notes: [], archiveRoot };
     const cfg = configDir();
     // `memory activate` parks foreign versions under the upstream root (doctor.ts's
     // disabledRoot): an upstream install or a pre-rename FreeHarness build, never ours.
@@ -162,7 +175,7 @@ async function planUser(deps) {
             const verdictLine = d.lines.find((l) => l.includes("VERDICT")) ?? `verdict ${d.verdict}`;
             item.refused = `the FreeHarness build is not the only active memory plugin yet (${verdictLine.replace(/^(OK|WARN)\s+/, "")}); run \`freeharness memory activate\` first`;
         }
-        plan.items.push(item);
+        plan.items.push(toArchive(item, cfg, archiveRoot));
     }
     // Superseded FreeHarness builds: our own cache versions (.install-version present) that are
     // not the registered installPath, left behind by a version bump. A legacy-root build that
@@ -171,7 +184,7 @@ async function planUser(deps) {
         const d = deps.memory ?? (await diagnoseMemory());
         if (d.activeInstallPath) {
             for (const c of d.cache.filter((c) => c.ours && !c.legacy && path.resolve(c.dir) !== path.resolve(d.activeInstallPath))) {
-                plan.items.push({ kind: "dir", target: c.dir, reason: `superseded FreeHarness memory build ${c.version} (registered: ${d.activeVersion ?? "?"})`, group: "memory", bytes: dirBytes(c.dir) });
+                plan.items.push(toArchive({ kind: "dir", target: c.dir, reason: `superseded FreeHarness memory build ${c.version} (registered: ${d.activeVersion ?? "?"})`, group: "memory", bytes: dirBytes(c.dir) }, cfg, archiveRoot));
             }
         }
     }
@@ -184,7 +197,21 @@ async function planUser(deps) {
     if (fs.existsSync(userSettings) && memoryPluginInstalled(cfg) && pruneHooksMatching(userSettings, isClaudeMemHook, true) > 0) {
         plan.items.push({ kind: "hooks", target: userSettings, reason: `upstream claude-mem hook entries (the ${PLUGIN_KEY} plugin ships its own hooks.json; these run every hook twice)`, group: "memory", hookOwner: UPSTREAM_PLUGIN_NAME });
     }
-    // Leftovers of a `registerHooks` migration: the pre-rename cache dir (gated on its own
+    // Rule stubs the upstream Gemini/Antigravity installer wrote into IDE rule dirs; no engine
+    // updates them. Fixed list, no glob; a directory at the path is not ours to move.
+    for (const rel of IDE_RULE_FILES) {
+        const file = path.join(os.homedir(), rel);
+        try {
+            const st = fs.lstatSync(file);
+            if (!st.isFile() && !st.isSymbolicLink())
+                continue;
+        }
+        catch {
+            continue;
+        }
+        plan.items.push({ kind: "file", target: file, reason: "upstream IDE rule file (no engine updates it)", group: "memory", ideRule: true, archiveDest: path.join(archiveRoot, "ide-rules", rel) });
+    }
+    // Leftovers of the old key: the pre-rename cache dir (gated on its own
     // existence, not the key's) and the disabled key (listed only while present). Both stay
     // refused while the old key is enabled, or (same VERDICT check as above) while the build is
     // not verified as sole active plugin — installed_plugins.json alone can register the
@@ -202,18 +229,23 @@ async function planUser(deps) {
         }
         let refused;
         if (oldKeyValue === true) {
-            refused = `the ${UPSTREAM_PLUGIN_KEY} key is still enabled — migrate first: \`freeharness init --scope user --only memory\``;
+            refused = UPSTREAM_ENABLED_REFUSAL;
         }
         else if (d.verdict !== "ours") {
             const verdictLine = d.lines.find((l) => l.includes("VERDICT")) ?? `verdict ${d.verdict}`;
             refused = `the FreeHarness build is not the only active memory plugin yet (${verdictLine.replace(/^(OK|WARN)\s+/, "")}); run \`freeharness memory activate\` first`;
         }
         if (fs.existsSync(oldCacheDir)) {
-            plan.items.push({ kind: "dir", target: oldCacheDir, reason: `previous registration, migrated to ${PLUGIN_NAME}`, group: "memory", bytes: dirBytes(oldCacheDir), refused });
+            plan.items.push(toArchive({ kind: "dir", target: oldCacheDir, reason: "previous registration, left in the plugin cache", group: "memory", bytes: dirBytes(oldCacheDir), refused }, cfg, archiveRoot));
         }
         if (oldKeyValue !== undefined) {
-            plan.items.push({ kind: "settings-key", target: userSettings, reason: `disabled ${UPSTREAM_PLUGIN_KEY} key left in enabledPlugins after migrating to ${PLUGIN_KEY}`, group: "memory", settingsKey: UPSTREAM_PLUGIN_KEY, refused });
+            const copy = configCopyArchive(userSettings, os.homedir(), archiveRoot);
+            plan.items.push({ kind: "json-key", target: userSettings, reason: `disabled ${UPSTREAM_PLUGIN_KEY} key left in enabledPlugins`, group: "memory", keyPath: ["enabledPlugins", UPSTREAM_PLUGIN_KEY], archiveDest: copy.destination, refused: refused ?? copy.refused });
         }
+        // An enabled upstream plugin still installs from its marketplace; other clients' launchers are not that plugin.
+        const launchers = planUpstreamLaunchers({ home: os.homedir(), cfg, archiveRoot, marketplaceRefusal: oldKeyValue === true ? UPSTREAM_ENABLED_REFUSAL : undefined });
+        plan.items.push(...launchers.items);
+        plan.notes.push(...launchers.notes);
     }
     const legacy = path.join(cfg, "commands", "openspec");
     if (fs.existsSync(legacy)) {
@@ -250,20 +282,24 @@ async function planUser(deps) {
             plan.items.push({ kind: "npm-global", target: CLI_PACKAGE, reason: `npm -g ${CLI_PACKAGE} (old npm link; shadows ~/.local/bin)${linkedBin ? ` at ${linkedBin}` : ""}`, group: "npm", unlink: true });
         }
     }
-    // Retired names: listed only when the manifest records the path, so a same-named
-    // user-owned skill/agent stays untouched (doctor reports that case as INFO, never here).
+    // Retired names: a skill or agent is listed only when the manifest records the path, so a
+    // same-named user-owned one stays untouched (doctor reports that case as INFO, never here).
+    // A hook script lives in FreeHarness's own hooks dir, so its presence is enough.
     const manifest = readManifest(manifestPath("user", ""));
     for (const f of retiredFindings(path.join(os.homedir(), ".claude"), manifest)) {
-        if (!f.recorded)
+        if (!f.recorded && f.kind !== "hook")
             continue;
         plan.items.push({
             kind: f.kind === "skill" ? "dir" : "file",
             target: f.path,
-            reason: `retired ${f.kind} (renamed or folded elsewhere; kept on disk by update's additive manifest merge)`,
+            reason: f.kind === "hook" ? `retired hook ${f.name} (removed from FreeHarness; update never deletes the installed copy)` : `retired ${f.kind} (renamed or folded elsewhere; kept on disk by update's additive manifest merge)`,
             group: "retired",
             bytes: f.kind === "skill" ? dirBytes(f.path) : undefined,
         });
     }
+    if (fs.existsSync(userSettings) && pruneHooksMatching(userSettings, isRetiredHook, true) > 0) {
+        plan.items.push({ kind: "hooks", target: userSettings, reason: `settings hook entries running a retired hook script (${RETIRED.hooks.join(", ")})`, group: "retired", hookOwner: "retired" });
+    }
     plan.notes.push(`kept: ${path.join(os.homedir(), ".local", "share", "openspec", "schemas", "spec-driven")} (the FreeHarness schema override)`);
     return plan;
 }
@@ -319,9 +355,61 @@ function planProject(projectRoot, deps) {
 export async function planCleanup(scope, projectRoot, deps = {}) {
     return scope === "user" ? planUser(deps) : planProject(projectRoot, deps);
 }
+function inInbox(dest, inbox) {
+    const rel = path.relative(inbox, dest);
+    return !(rel === "" || rel === ".." || rel.startsWith(`..${path.sep}`) || path.isAbsolute(rel));
+}
+/**
+ * The destination stays in the `ide-rules` inbox so no plan item lands over other archive content;
+ * a source that became a directory since pass 1 is no longer the stub it listed, and moving it would take what the user put there.
+ */
+function ideRuleRefusal(source, dest, archiveRoot) {
+    if (archiveRoot === undefined)
+        return "no archive root in the plan";
+    const inbox = path.join(archiveRoot, "ide-rules");
+    if (!inInbox(dest, inbox))
+        return `destination ${dest} is outside ${inbox}`;
+    try {
+        if (fs.lstatSync(source).isDirectory())
+            return "is a directory now";
+    }
+    catch {
+        // gone: the move reports it
+    }
+    return undefined;
+}
+/** A pre-edit copy outside the `configs` inbox could land over other archive content, so pass 2 refuses it. */
+function jsonKeyRefusal(item, archiveRoot) {
+    if (archiveRoot === undefined)
+        return "no archive root in the plan";
+    if (!item.keyPath?.length || item.archiveDest === undefined)
+        return "no key path or copy destination in the plan";
+    const inbox = path.join(archiveRoot, "configs");
+    return inInbox(item.archiveDest, inbox) ? undefined : `destination ${item.archiveDest} is outside ${inbox}`;
+}
+/** Moving rather than deleting keeps a wrong match recoverable; each kind has its own pass-2 check, as what makes its move unsafe differs. */
+function archiveItem(item, dest, cfg, archiveRoot, out) {
+    const refused = item.ideRule
+        ? ideRuleRefusal(item.target, dest, archiveRoot)
+        : item.launcher === "marketplace"
+            ? marketplaceRefusal(item.target, dest, archiveRoot)
+            : pluginCacheRefusal(item.target, dest, cfg, archiveRoot);
+    if (refused) {
+        out.skipped.push(item.target);
+        out.warnings.push(`${item.target}: refused (${refused})`);
+        return;
+    }
+    try {
+        out.moved.push(`${item.target} -> ${archiveMove(item.target, dest)}`);
+    }
+    catch (e) {
+        out.warnings.push(moveWarning(item.target, e));
+    }
+}
 /** Removes the confirmed items of a plan (`confirmed` defaults to all); refused items are always skipped. */
 export function applyCleanup(plan, confirmed = () => true) {
-    const out = { removed: [], skipped: [], warnings: [] };
+    const out = { removed: [], moved: [], skipped: [], warnings: [] };
+    const cfg = configDir();
     for (const item of plan.items) {
         if (item.refused || !confirmed(item)) {
             out.skipped.push(item.target);
@@ -329,14 +417,26 @@ export function applyCleanup(plan, confirmed = () => true) {
         }
         switch (item.kind) {
             case "dir":
-            case "file":
+            case "file": {
+                if (item.archiveDest !== undefined) {
+                    archiveItem(item, item.archiveDest, cfg, plan.archiveRoot, out);
+                    break;
+                }
+                // Nothing in, at or above the plugin cache is ever deleted; a link to it is unlinked only.
+                const cached = pluginCacheOverlap(item.target, cfg);
+                if (cached) {
+                    out.skipped.push(item.target);
+                    out.warnings.push(`${item.target}: refused (${cached})`);
+                    break;
+                }
                 fs.rmSync(item.target, { recursive: true, force: true });
                 out.removed.push(item.target);
                 break;
+            }
             case "hooks": {
-                const claudeMem = item.hookOwner === UPSTREAM_PLUGIN_NAME;
-                pruneHooksMatching(item.target, claudeMem ? isClaudeMemHook : isOurHook, false);
-                out.removed.push(`${item.target} (${claudeMem ? UPSTREAM_PLUGIN_NAME : "FreeHarness"} hook entries)`);
+                pruneHooksMatching(item.target, hookPredicate(item.hookOwner), false);
+                const whose = item.hookOwner === UPSTREAM_PLUGIN_NAME ? `upstream ${UPSTREAM_PLUGIN_NAME}` : item.hookOwner === "retired" ? "retired FreeHarness" : "FreeHarness";
+                out.removed.push(`${item.target} (${whose} hook entries)`);
                 break;
             }
             case "npm-global": {
@@ -358,12 +458,16 @@ export function applyCleanup(plan, confirmed = () => true) {
                     out.warnings.push(`npm ${verb} -g ${item.target} failed (exit ${r.status ?? "?"}): ${(r.stderr || r.stdout || "").trim().split("\n")[0]}`);
                 break;
             }
-            case "settings-key": {
-                const settings = JSON.parse(fs.readFileSync(item.target, "utf8"));
-                if (item.settingsKey && settings.enabledPlugins)
-                    delete settings.enabledPlugins[item.settingsKey];
-                fs.writeFileSync(item.target, JSON.stringify(settings, null, 2) + "\n", "utf8");
-                out.removed.push(`${item.target} (removed ${item.settingsKey} from enabledPlugins)`);
+            case "json-key": {
+                const refused = jsonKeyRefusal(item, plan.archiveRoot);
+                const r = refused ? { ok: false, reason: refused } : removeJsonKey(item.target, item.keyPath ?? [], item.archiveDest ?? "", { stillMatches: launcherStillMatches(item) });
+                if (r.ok) {
+                    out.removed.push(`${item.target} (removed ${keyLabel(item)}; copy at ${r.copy})`);
+                }
+                else {
+                    out.skipped.push(item.target);
+                    out.warnings.push(`${item.target}: refused (${r.reason})`);
+                }
                 break;
             }
         }
@@ -373,10 +477,20 @@ export function applyCleanup(plan, confirmed = () => true) {
 /** Renders a plan item for the preview / doctor output, one line, without the OK/WARN prefix. */
 export function describeItem(item) {
     const size = item.bytes !== undefined ? ` (${humanBytes(item.bytes)})` : "";
-    const what = item.kind === "npm-global"
-        ? `npm ${item.unlink ? "unlink" : "uninstall"} -g ${item.target}`
-        : item.kind === "hooks" || item.kind === "settings-key"
-            ? `edit: ${item.target}`
-            : `rm: ${item.target}`;
-    return `${what}${size} — ${item.reason}${item.refused ? ` — REFUSED: ${item.refused}` : ""}`;
+    return `${itemAction(item)}${size} — ${item.reason}${item.refused ? ` — REFUSED: ${item.refused}` : ""}`;
+}
+/** Doctor prints these lines unescaped, and a launcher's key is a server name another program wrote. */
+function keyLabel(item) {
+    return item.keyPath?.map(launcherText).join(".") ?? "?";
+}
+function itemAction(item) {
+    if (item.kind === "npm-global")
+        return `npm ${item.unlink ? "unlink" : "uninstall"} -g ${item.target}`;
+    if (item.kind === "json-key")
+        return `edit: ${item.target} (remove ${keyLabel(item)}; original to ${item.archiveDest ?? "?"})`;
+    if (item.kind === "hooks")
+        return `edit: ${item.target}`;
+    if (item.archiveDest !== undefined)
+        return `mv: ${item.target} -> ${item.archiveDest}`;
+    return `rm: ${item.target}`;
 }