freeharness 0.4.1

package/dist/adapters/prompt/readline.d.ts

@@ -0,0 +1,19 @@
+import type { PromptPort, SelectItem } from "@freeharness/core";
+export declare class ReadlinePrompt implements PromptPort {
+    confirm(message: string): Promise<boolean>;
+    /**
+     * Prints the items numbered and reads a comma-separated list of numbers or ids.
+     * @param message Prompt line printed above the list.
+     * @param items Selectable items.
+     * @returns The selected ids in list order; empty on no TTY, empty input or `none`.
+     */
+    select(message: string, items: SelectItem[]): Promise<string[]>;
+}
+/**
+ * Resolves a typed selection (`1,3`, `context7,github`, `all`) to item ids, ignoring
+ * unknown entries.
+ * @param answer Raw input.
+ * @param items Selectable items.
+ * @returns Selected ids in list order, deduplicated.
+ */
+export declare function parseSelection(answer: string, items: SelectItem[]): string[];

package/dist/adapters/prompt/readline.js

@@ -0,0 +1,53 @@
+// PromptPort adapter: a dependency-free y/N confirmation and a numbered multi-select over
+// stdin. When stdin is not a TTY and --yes / --select were not passed, confirm defaults to
+// No and select to nothing (safe: nothing runs, nothing is enabled).
+import readline from "node:readline";
+export class ReadlinePrompt {
+    async confirm(message) {
+        if (!process.stdin.isTTY)
+            return false;
+        const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+        const answer = await new Promise((resolve) => rl.question(`${message} [y/N] `, resolve));
+        rl.close();
+        return /^y(es)?$/i.test(answer.trim());
+    }
+    /**
+     * Prints the items numbered and reads a comma-separated list of numbers or ids.
+     * @param message Prompt line printed above the list.
+     * @param items Selectable items.
+     * @returns The selected ids in list order; empty on no TTY, empty input or `none`.
+     */
+    async select(message, items) {
+        if (!process.stdin.isTTY || items.length === 0)
+            return [];
+        console.log(message);
+        items.forEach((it, i) => console.log(`  ${String(i + 1).padStart(2)}) ${it.id.padEnd(14)} ${it.label}`));
+        const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+        const answer = await new Promise((resolve) => rl.question("Select (numbers or ids, comma-separated; empty = none): ", resolve));
+        rl.close();
+        return parseSelection(answer, items);
+    }
+}
+/**
+ * Resolves a typed selection (`1,3`, `context7,github`, `all`) to item ids, ignoring
+ * unknown entries.
+ * @param answer Raw input.
+ * @param items Selectable items.
+ * @returns Selected ids in list order, deduplicated.
+ */
+export function parseSelection(answer, items) {
+    const tokens = answer.split(",").map((t) => t.trim()).filter(Boolean);
+    if (tokens.length === 0 || tokens.some((t) => /^none$/i.test(t)))
+        return [];
+    if (tokens.some((t) => /^all$/i.test(t)))
+        return items.map((i) => i.id);
+    const chosen = new Set();
+    for (const t of tokens) {
+        const n = parseInt(t, 10);
+        if (Number.isFinite(n) && /^\d+$/.test(t) && items[n - 1])
+            chosen.add(items[n - 1].id);
+        else if (items.some((i) => i.id === t))
+            chosen.add(t);
+    }
+    return items.map((i) => i.id).filter((id) => chosen.has(id));
+}

package/dist/adapters/sync/diff.d.ts

@@ -0,0 +1,43 @@
+import type { AdoptOptions, AdoptReport, SyncPort, SyncReport } from "@freeharness/core";
+/**
+ * Renders a unified diff (3 lines of context) between two texts.
+ * @param oldText Vendored content ("" when missing).
+ * @param newText Upstream content ("" when missing).
+ * @param oldName Header name for the vendored side.
+ * @param newName Header name for the upstream side.
+ * @returns Unified diff text; a one-line summary when the inputs are too large.
+ */
+export declare function unifiedDiff(oldText: string, newText: string, oldName: string, newName: string): string;
+/** Read-only upstream check + explicit path-scoped adoption over the same tracked manifest. */
+export declare class DiffSync implements SyncPort {
+    private readonly canonicalDir;
+    constructor(canonicalDir: string);
+    private resolve;
+    check(target: string): Promise<SyncReport>;
+    /**
+     * Adopts upstream versions of the tracked paths (never engine code).
+     * Dry run: builds the previews and the would-be report, writes nothing.
+     * Write: copies the selected entries, then bumps the PROVENANCE baseline to the fork HEAD.
+     * @param target sdd | memory.
+     * @param options Label filter, dry-run, force-divergent.
+     * @returns The adoption report.
+     */
+    adopt(target: string, options: AdoptOptions): Promise<AdoptReport>;
+}
+/** PROVENANCE baseline vs the upstream fork checkout, for `doctor`. */
+export interface BaselineStatus {
+    target: string;
+    baseline: string;
+    fork: string;
+    forkFound: boolean;
+    /** Fork HEAD (short 8) when the fork is a git checkout. */
+    head?: string;
+}
+/**
+ * Reports where a vendored engine's PROVENANCE baseline stands against the fork HEAD,
+ * without comparing files (that is `sync check`).
+ * @param canonicalDir Resolved canonical directory (locates the repo and PROVENANCE).
+ * @param target sdd | memory.
+ * @returns The baseline status; `head` undefined when the fork is missing or not git.
+ */
+export declare function baselineStatus(canonicalDir: string, target: string): BaselineStatus;

package/dist/adapters/sync/diff.js

@@ -0,0 +1,380 @@
+// SyncPort adapter: report how our vendored trees differ from the current upstream
+// fork checkout, limited to the vendored paths, flagging stable-contract changes
+// (`check`, read-only), and adopt the upstream versions of those tracked paths on
+// explicit request (`adopt`: preview -> copy -> PROVENANCE baseline bump). Engine code
+// is never touched by either: it is a manual, build-verified port.
+import fs from "node:fs";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { UPSTREAM_PLUGIN_NAME } from "../memory/vendored.js";
+// packages/cli/canonical -> up 3 = the FreeHarness repo root.
+function repoRoot(canonicalDir) {
+    return path.resolve(canonicalDir, "..", "..", "..");
+}
+// Fork checkout: env override, else a sibling of the FreeHarness repo.
+function forkDir(target, repo) {
+    const env = process.env[`FREEHARNESS_UPSTREAM_${target.toUpperCase()}`];
+    if (env)
+        return env;
+    const sibling = target === "sdd" ? "OpenSpec" : UPSTREAM_PLUGIN_NAME;
+    return path.resolve(repo, "..", sibling);
+}
+function baselineFrom(provenance) {
+    if (!fs.existsSync(provenance))
+        return "unknown";
+    const m = /baseline_commit:\s*"?([0-9a-f]+)"?/i.exec(fs.readFileSync(provenance, "utf8"));
+    return m ? m[1] : "unknown";
+}
+function listFiles(dir) {
+    const out = [];
+    const walk = (rel) => {
+        const abs = path.join(dir, rel);
+        if (!fs.existsSync(abs))
+            return;
+        for (const e of fs.readdirSync(abs, { withFileTypes: true })) {
+            if (e.name === ".DS_Store")
+                continue;
+            const child = path.join(rel, e.name);
+            if (e.isDirectory())
+                walk(child);
+            else
+                out.push(child);
+        }
+    };
+    walk("");
+    return out;
+}
+function isDir(p) {
+    return fs.existsSync(p) && fs.statSync(p).isDirectory();
+}
+// Compare a file or a directory; return the sub-paths that differ (or are missing).
+function compare(entry) {
+    if (isDir(entry.vendored)) {
+        const rels = new Set([...listFiles(entry.vendored), ...listFiles(entry.upstream)]);
+        const diffs = [];
+        for (const rel of rels) {
+            const a = path.join(entry.vendored, rel);
+            const b = path.join(entry.upstream, rel);
+            if (!fs.existsSync(a) || !fs.existsSync(b) || fs.readFileSync(a, "utf8") !== fs.readFileSync(b, "utf8")) {
+                diffs.push(`${entry.label}/${rel}`);
+            }
+        }
+        return diffs;
+    }
+    if (!fs.existsSync(entry.vendored) || !fs.existsSync(entry.upstream))
+        return [entry.label];
+    return fs.readFileSync(entry.vendored, "utf8") !== fs.readFileSync(entry.upstream, "utf8") ? [entry.label] : [];
+}
+function provenanceFile(target, repo) {
+    return path.join(repo, target === "sdd" ? "packages/sdd/PROVENANCE.yaml" : "packages/memory/PROVENANCE.yaml");
+}
+function manifest(target, repo, fork) {
+    if (target === "sdd") {
+        const v = path.join(repo, "packages/sdd/vendor/openspec");
+        return [
+            { label: "schema.yaml", vendored: path.join(v, "assets/schema.upstream.yaml"), upstream: path.join(fork, "schemas/spec-driven/schema.yaml"), contract: true },
+            { label: "skills", vendored: path.join(v, "assets/skills"), upstream: path.join(fork, "skills"), contract: true },
+        ];
+    }
+    if (target === "memory") {
+        const v = path.join(repo, "packages/memory/vendor/claude-mem");
+        return [
+            {
+                label: "plugin/hooks/hooks.json", vendored: path.join(v, "plugin/hooks/hooks.json"), upstream: path.join(fork, "plugin/hooks/hooks.json"), contract: true,
+                divergent: "rewritten to a deterministic ${CLAUDE_PLUGIN_ROOT} command (memory-slim); compare upstream events/matchers/verbs by hand",
+            },
+            {
+                label: "plugin/.mcp.json", vendored: path.join(v, "plugin/.mcp.json"), upstream: path.join(fork, "plugin/.mcp.json"), contract: true,
+                divergent: "rewritten to spawn ${CLAUDE_PLUGIN_ROOT}/scripts/mcp-server.cjs directly (memory-slim)",
+            },
+            { label: "mem-search/SKILL.md", vendored: path.join(v, "plugin/skills/mem-search/SKILL.md"), upstream: path.join(fork, "plugin/skills/mem-search/SKILL.md"), contract: true },
+        ];
+    }
+    throw new Error(`Unknown sync target: ${target}. Valid: sdd, memory.`);
+}
+// ---- unified diff (in-process, dependency-free; files here are small text contracts) ----
+/** Above this many line-pairs the LCS table is skipped and the preview is a size summary. */
+const MAX_DIFF_CELLS = 4_000_000;
+const CONTEXT = 3;
+/**
+ * Computes an edit script between two line arrays via a classic LCS table.
+ * @param a Old lines.
+ * @param b New lines.
+ * @returns Ops in order (` ` equal, `-` removed, `+` added).
+ */
+function lineOps(a, b) {
+    const n = a.length;
+    const m = b.length;
+    // lcs[i][j] = LCS length of a[i..] and b[j..]; flat Uint32 to keep it cheap.
+    const w = m + 1;
+    const lcs = new Uint32Array((n + 1) * w);
+    for (let i = n - 1; i >= 0; i--) {
+        for (let j = m - 1; j >= 0; j--) {
+            lcs[i * w + j] = a[i] === b[j] ? lcs[(i + 1) * w + j + 1] + 1 : Math.max(lcs[(i + 1) * w + j], lcs[i * w + j + 1]);
+        }
+    }
+    const ops = [];
+    let i = 0;
+    let j = 0;
+    while (i < n && j < m) {
+        if (a[i] === b[j]) {
+            ops.push({ kind: " ", line: a[i] });
+            i++;
+            j++;
+        }
+        else if (lcs[(i + 1) * w + j] >= lcs[i * w + j + 1]) {
+            ops.push({ kind: "-", line: a[i] });
+            i++;
+        }
+        else {
+            ops.push({ kind: "+", line: b[j] });
+            j++;
+        }
+    }
+    while (i < n)
+        ops.push({ kind: "-", line: a[i++] });
+    while (j < m)
+        ops.push({ kind: "+", line: b[j++] });
+    return ops;
+}
+/**
+ * Renders a unified diff (3 lines of context) between two texts.
+ * @param oldText Vendored content ("" when missing).
+ * @param newText Upstream content ("" when missing).
+ * @param oldName Header name for the vendored side.
+ * @param newName Header name for the upstream side.
+ * @returns Unified diff text; a one-line summary when the inputs are too large.
+ */
+export function unifiedDiff(oldText, newText, oldName, newName) {
+    const lines = (t) => (t === "" ? [] : t.replace(/\n$/, "").split("\n"));
+    const a = lines(oldText);
+    const b = lines(newText);
+    const header = `--- ${oldName}\n+++ ${newName}\n`;
+    if (a.length * b.length > MAX_DIFF_CELLS)
+        return `${header}@@ large file: ${a.length} -> ${b.length} lines (diff omitted; compare by hand) @@\n`;
+    const ops = lineOps(a, b);
+    // Annotate each op with its old/new line numbers, then keep the ops within CONTEXT of a change.
+    const oldNo = [];
+    const newNo = [];
+    let ol = 1;
+    let nl = 1;
+    for (const op of ops) {
+        oldNo.push(ol);
+        newNo.push(nl);
+        if (op.kind !== "+")
+            ol++;
+        if (op.kind !== "-")
+            nl++;
+    }
+    const keep = new Array(ops.length).fill(false);
+    for (let k = 0; k < ops.length; k++) {
+        if (ops[k].kind === " ")
+            continue;
+        for (let c = Math.max(0, k - CONTEXT); c <= Math.min(ops.length - 1, k + CONTEXT); c++)
+            keep[c] = true;
+    }
+    const out = [];
+    let k = 0;
+    while (k < ops.length) {
+        if (!keep[k]) {
+            k++;
+            continue;
+        }
+        const start = k;
+        while (k < ops.length && keep[k])
+            k++;
+        const hunk = ops.slice(start, k);
+        const oldCount = hunk.filter((o) => o.kind !== "+").length;
+        const newCount = hunk.filter((o) => o.kind !== "-").length;
+        const oldStart = oldCount === 0 ? oldNo[start] - 1 : oldNo[start];
+        const newStart = newCount === 0 ? newNo[start] - 1 : newNo[start];
+        out.push(`@@ -${oldStart},${oldCount} +${newStart},${newCount} @@`);
+        for (const op of hunk)
+            out.push(`${op.kind}${op.line}`);
+    }
+    return header + out.join("\n") + (out.length > 0 ? "\n" : "");
+}
+/**
+ * Builds the previews for one tracked entry: one per differing file (dirs) or one for the file.
+ * @param entry Manifest entry.
+ * @returns Previews with `added` / `removed` markers for one-sided files.
+ */
+function previewsFor(entry) {
+    const one = (label, vendored, upstream) => {
+        const vExists = fs.existsSync(vendored);
+        const uExists = fs.existsSync(upstream);
+        const marker = !vExists ? " (added upstream)" : !uExists ? " (removed upstream — vendored copy will be deleted)" : "";
+        const diff = unifiedDiff(vExists ? fs.readFileSync(vendored, "utf8") : "", uExists ? fs.readFileSync(upstream, "utf8") : "", `vendored/${label}`, `upstream/${label}`);
+        return { label: `${label}${marker}`, diff };
+    };
+    if (isDir(entry.vendored) || isDir(entry.upstream)) {
+        return compare(entry).sort().map((full) => {
+            const rel = full.slice(entry.label.length + 1);
+            return one(full, path.join(entry.vendored, rel), path.join(entry.upstream, rel));
+        });
+    }
+    return compare(entry).length > 0 ? [one(entry.label, entry.vendored, entry.upstream)] : [];
+}
+/**
+ * Copies one entry from upstream over the vendored tree (dir: per file, deleting vendored
+ * files that no longer exist upstream). A single file missing upstream is left in place.
+ * @param entry Manifest entry.
+ * @returns A warning when the upstream side is missing, else undefined.
+ */
+function copyEntry(entry) {
+    if (isDir(entry.upstream)) {
+        const upstreamFiles = new Set(listFiles(entry.upstream));
+        for (const rel of listFiles(entry.vendored)) {
+            if (!upstreamFiles.has(rel))
+                fs.rmSync(path.join(entry.vendored, rel), { force: true });
+        }
+        for (const rel of upstreamFiles) {
+            const dest = path.join(entry.vendored, rel);
+            fs.mkdirSync(path.dirname(dest), { recursive: true });
+            fs.copyFileSync(path.join(entry.upstream, rel), dest);
+        }
+        return undefined;
+    }
+    if (!fs.existsSync(entry.upstream))
+        return `${entry.label}: removed upstream; vendored copy kept (delete by hand if intended)`;
+    fs.mkdirSync(path.dirname(entry.vendored), { recursive: true });
+    fs.copyFileSync(entry.upstream, entry.vendored);
+    return undefined;
+}
+/**
+ * Reads the fork's HEAD (short 8) and package.json version, when it is a git checkout.
+ * @param fork Fork checkout dir.
+ * @returns `{commit, version}`; commit undefined when not a git checkout.
+ */
+function forkHead(fork) {
+    const r = spawnSync("git", ["-C", fork, "rev-parse", "--short=8", "HEAD"], { encoding: "utf8" });
+    const commit = r.status === 0 ? r.stdout.trim() : undefined;
+    let version;
+    const pkg = path.join(fork, "package.json");
+    if (fs.existsSync(pkg)) {
+        try {
+            const v = JSON.parse(fs.readFileSync(pkg, "utf8")).version;
+            if (typeof v === "string" && /^\d+\.\d+\.\d+/.test(v))
+                version = v;
+        }
+        catch { /* not a package.json we can read; keep the version */ }
+    }
+    return { commit: commit && /^[0-9a-f]{7,40}$/.test(commit) ? commit : undefined, version };
+}
+/**
+ * Rewrites only the `baseline_commit` (and `baseline_version`) values in PROVENANCE.yaml,
+ * preserving the rest of the file byte-for-byte.
+ * @param file PROVENANCE.yaml path.
+ * @param commit New baseline commit.
+ * @param version New baseline version (optional).
+ */
+function bumpBaseline(file, commit, version) {
+    let text = fs.readFileSync(file, "utf8");
+    text = text.replace(/^(\s*baseline_commit:\s*)"?[0-9a-f]+"?/im, `$1"${commit}"`);
+    if (version)
+        text = text.replace(/^(\s*baseline_version:\s*)"?[^"\n]+"?/im, `$1"${version}"`);
+    fs.writeFileSync(file, text, "utf8");
+}
+/** Read-only upstream check + explicit path-scoped adoption over the same tracked manifest. */
+export class DiffSync {
+    canonicalDir;
+    constructor(canonicalDir) {
+        this.canonicalDir = canonicalDir;
+    }
+    resolve(target) {
+        const repo = repoRoot(this.canonicalDir);
+        const fork = forkDir(target, repo);
+        const entries = manifest(target, repo, fork); // unknown target errors before the fork lookup
+        if (!fs.existsSync(fork)) {
+            throw new Error(`Upstream fork not found for '${target}' at ${fork}. Set FREEHARNESS_UPSTREAM_${target.toUpperCase()} to the fork checkout.`);
+        }
+        return { repo, fork, entries, provenance: provenanceFile(target, repo) };
+    }
+    async check(target) {
+        const { entries, provenance } = this.resolve(target);
+        const baseline = baselineFrom(provenance);
+        const changedPaths = [];
+        const contractAffected = [];
+        const divergent = {};
+        for (const entry of entries) {
+            const diffs = compare(entry);
+            for (const d of diffs) {
+                changedPaths.push(d);
+                if (entry.divergent)
+                    divergent[d] = entry.divergent;
+                else if (entry.contract)
+                    contractAffected.push(d);
+            }
+        }
+        return { target, baseline, changedPaths, contractAffected, divergent };
+    }
+    /**
+     * Adopts upstream versions of the tracked paths (never engine code).
+     * Dry run: builds the previews and the would-be report, writes nothing.
+     * Write: copies the selected entries, then bumps the PROVENANCE baseline to the fork HEAD.
+     * @param target sdd | memory.
+     * @param options Label filter, dry-run, force-divergent.
+     * @returns The adoption report.
+     */
+    async adopt(target, options) {
+        const { fork, entries, provenance } = this.resolve(target);
+        const known = entries.map((e) => e.label);
+        for (const p of options.paths ?? []) {
+            if (!known.includes(p))
+                throw new Error(`Unknown tracked path '${p}' for '${target}'. Tracked: ${known.join(", ")}`);
+        }
+        const selected = entries.filter((e) => !options.paths || options.paths.includes(e.label));
+        const baselineBefore = baselineFrom(provenance);
+        const warnings = [];
+        const adopted = [];
+        const skippedDivergent = [];
+        const previews = [];
+        const toCopy = [];
+        for (const entry of selected) {
+            if (compare(entry).length === 0)
+                continue;
+            if (entry.divergent && !options.forceDivergent) {
+                skippedDivergent.push(entry.label);
+                continue;
+            }
+            previews.push(...previewsFor(entry));
+            adopted.push(entry.label);
+            toCopy.push(entry);
+        }
+        const head = forkHead(fork);
+        let baselineAfter = baselineBefore;
+        if (!head.commit)
+            warnings.push(`fork at ${fork} is not a git checkout; PROVENANCE baseline kept at ${baselineBefore}`);
+        else
+            baselineAfter = head.commit;
+        // Dry run reports the would-be baseline; nothing-to-adopt writes nothing (baseline kept).
+        if (options.dryRun)
+            return { target, adopted, skippedDivergent, baselineBefore, baselineAfter, previews, warnings };
+        if (adopted.length === 0)
+            return { target, adopted, skippedDivergent, baselineBefore, baselineAfter: baselineBefore, previews, warnings };
+        for (const entry of toCopy) {
+            const w = copyEntry(entry);
+            if (w)
+                warnings.push(w);
+        }
+        if (head.commit && fs.existsSync(provenance))
+            bumpBaseline(provenance, head.commit, head.version);
+        else if (head.commit)
+            warnings.push(`${provenance} not found; baseline not recorded`);
+        return { target, adopted, skippedDivergent, baselineBefore, baselineAfter, previews, warnings };
+    }
+}
+/**
+ * Reports where a vendored engine's PROVENANCE baseline stands against the fork HEAD,
+ * without comparing files (that is `sync check`).
+ * @param canonicalDir Resolved canonical directory (locates the repo and PROVENANCE).
+ * @param target sdd | memory.
+ * @returns The baseline status; `head` undefined when the fork is missing or not git.
+ */
+export function baselineStatus(canonicalDir, target) {
+    const repo = repoRoot(canonicalDir);
+    const fork = forkDir(target, repo);
+    const baseline = baselineFrom(provenanceFile(target, repo));
+    const forkFound = fs.existsSync(fork);
+    return { target, baseline, fork, forkFound, head: forkFound ? forkHead(fork).commit : undefined };
+}

package/dist/cli/cleanup.d.ts

@@ -0,0 +1,86 @@
+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";
+/** A global link of it shadows the ~/.local/bin symlink. */
+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;
+/** One leftover the cleanup knows how to remove. */
+export interface CleanupItem {
+    kind: "dir" | "file" | "hooks" | "npm-global" | "settings-key";
+    /** Filesystem path, or the package name for `npm-global`. */
+    target: string;
+    reason: string;
+    group: CleanupGroup;
+    /** Dirs only. */
+    bytes?: number;
+    /** Set when detected but not removable now; the reason why. */
+    refused?: string;
+    /** `hooks` items: whose entries are pruned (default: FreeHarness). */
+    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;
+}
+/** What a cleanup pass would (or did) do. */
+export interface CleanupPlan {
+    scope: Scope;
+    items: CleanupItem[];
+    /** Informational lines: seen, but out of the fixed list. */
+    notes: string[];
+}
+/** Outcome of `applyCleanup`. */
+export interface CleanupResult {
+    removed: string[];
+    /** Refused, or not confirmed. */
+    skipped: string[];
+    /** Non-fatal failures (an npm uninstall that exited non-zero). */
+    warnings: string[];
+}
+/** Optional dependencies, injectable for tests. */
+export interface CleanupDeps {
+    /** Reuse: doctor already computed one. */
+    memory?: MemoryDiagnosis;
+    /** Names the agents/skills a project may duplicate. */
+    canonicalDir?: string;
+}
+/** Sums the size (bytes) of every file under a directory. */
+export declare function dirBytes(dir: string): number;
+/** Renders a byte count for the preview (e.g. "12.3 MB"). */
+export declare function humanBytes(n: number): string;
+/** Top-level packages of the global npm install: name -> version ("?" when unreported), null when npm is unavailable. */
+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[];
+/** 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. */
+export declare function applyCleanup(plan: CleanupPlan, confirmed?: (item: CleanupItem) => boolean): CleanupResult;
+/** Renders a plan item for the preview / doctor output, one line, without the OK/WARN prefix. */
+export declare function describeItem(item: CleanupItem): string;