freeharness 0.4.1 → 0.4.2

package/dist/cli/doctor.d.ts

@@ -1,4 +1,5 @@
 import { type Scope } from "@freeharness/core";
+export { memoryPluginInstalled } from "./install-facts.js";
 /** A runtime dependency probe result. */
 export interface DepStatus {
     name: string;
@@ -19,13 +20,11 @@ export declare function probeDeps(): DepStatus[];
 export declare function depLines(deps: DepStatus[]): string[];
 /** Hook conflicts in a settings.json: duplicate commands, a foreign memory-injecting SessionStart hook, claude-mem hooks kept while the plugin is installed; empty when settings.json is absent. */
 export declare function hookConflictLines(settingsPath: string, pluginInstalled: boolean): string[];
-/** Canonical agent file names and skill dir names: what a project could duplicate, and what doctor tells apart from the user's own content. */
-export declare function canonicalNames(canonicalDir: string): {
-    agents: string[];
-    skills: string[];
-};
-/** Skills and agents under a Claude dir that FreeHarness did not emit (the user's own content); never a global `openspec-*` copy or a manifest-recorded retired name. */
-export declare function foreignContentLines(claudeDir: string, canonicalDir: string, scope: Scope, projectRoot: string): string[];
+/**
+ * Skills and agents under a Claude dir that FreeHarness did not emit (the user's own content); never a global `openspec-*` copy or a manifest-recorded retired name.
+ * @param home Home whose `.claude` holds the user-scope manifest; never derived from `claudeDir`.
+ */
+export declare function foreignContentLines(claudeDir: string, canonicalDir: string, scope: Scope, projectRoot: string, home?: string): string[];
 /**
  * Flags a CLI that runs from outside `~/.local/bin` while the install.sh symlink exists there:
  * the shell resolved an older link (a global `npm link`, a stale PATH entry) ahead of ours.
@@ -34,12 +33,8 @@ export declare function foreignContentLines(claudeDir: string, canonicalDir: str
  * @returns One WARN line, or none.
  */
 export declare function runningFromLines(argv1: string | undefined, home: string): string[];
-/**
- * Whether claude-mem is enabled in settings.json or registered in installed_plugins.json.
- * @param claudeDir The ~/.claude (or project .claude) dir.
- * @returns True when found in either place.
- */
-export declare function memoryPluginInstalled(claudeDir: string): boolean;
+/** Launchers in files cleanup never writes; only file and line are printed, never the other program's text. */
+export declare function reportOnlyLauncherLines(home: string): string[];
 /**
  * PROVENANCE baseline vs upstream fork HEAD for each vendored engine.
  * @param canonicalDir Resolved canonical directory.
@@ -67,6 +62,28 @@ export declare function openspecChangeStatus(projectRoot: string): OpenspecChang
  * @returns One line, or none when the project has no openspec/changes.
  */
 export declare function openspecChangeLines(projectRoot: string): string[];
+/**
+ * Warns about SDD worktrees whose change is no longer in flight; a tree kept after a blocked
+ * task or a refused removal must stay visible once its change is archived. Plain fs, so
+ * doctor never spawns git and never mutates the tree.
+ * @param projectRoot Project root.
+ * @returns One WARN line per stale <root>/.worktrees/<change>/<task> directory.
+ */
+export declare function staleTreeLines(projectRoot: string): string[];
+/**
+ * Warns when the guard hooks fail closed and node is not resolvable: with onFailure block a
+ * missing runtime denies every Edit, Write and Bash call, so the owner must hear it before
+ * being locked out. PATH is scanned for absolute entries only and no shell runs, so a
+ * relative entry cannot supply the binary; the settings file is only read. Only the first
+ * existing binary is probed because it is the one the hook shell runs; a later healthy node
+ * cannot rescue the hooks. win32 looks for node.exe alone, since spawnSync cannot run a .cmd
+ * without a shell.
+ * @param settingsPath The user settings.json.
+ * @param env Environment whose PATH is searched.
+ * @param timeoutMs Version probe limit; tests shorten it.
+ * @returns One OK or WARN line, or none when no blocking guard entry exists.
+ */
+export declare function guardRuntimeLines(settingsPath: string, env?: NodeJS.ProcessEnv, timeoutMs?: number): string[];
 /**
  * Install-manifest presence and drift (listed files that are gone).
  * @param manifestFile The manifest path for the scope.
@@ -114,6 +131,28 @@ export declare function budgetLines(inp: BudgetInputs): string[];
  * @returns One printable line.
  */
 export declare function contextWindowLine(userSettings: Record<string, unknown>, projectSettings: Record<string, unknown>): string;
+/** The orchestrating session's model and effort verdict, with its printable line. */
+export interface SessionModelFinding {
+    level: "OK" | "INFO";
+    line: string;
+}
+/**
+ * The lead's model and effort drive most of a change's cost and are the owner's settings, so
+ * the doctor reports them and never writes them. A full id (`claude-opus-5-5[1m]`) counts as
+ * its family when the alias is one of its whole segments.
+ */
+export declare function sessionModelFinding(settings: unknown, tierAlias: string): SessionModelFinding;
+/**
+ * A missing settings file is the all-default case, while an unreadable or invalid one is
+ * named, so the doctor never fails on it.
+ */
+export declare function sessionModelLine(settingsFile: string): string;
+/**
+ * free-mem is the only memory owner, so Claude Code auto memory beside it writes a second,
+ * unrecalled store; the key off without free-mem leaves the machine with no memory at all.
+ * The value is the owner's: the doctor names it and never writes it.
+ */
+export declare function autoMemoryLine(settingsFile: string, freeMemEnabled: boolean): string;
 /** Outcome of probing a local model server. */
 export interface ProbeResult {
     ok: boolean;

package/dist/cli/doctor.js

@@ -3,21 +3,24 @@
 // section (language lint + token budget, cache hygiene). Each returns
 // printable lines (OK/WARN/INFO prefixed); index.ts composes them with the scope checks.
 import fs from "node:fs";
+import os from "node:os";
 import path from "node:path";
 import { spawnSync } from "node:child_process";
 import { baselineStatus } from "../adapters/sync/diff.js";
-import { PLUGIN_KEY } from "../adapters/memory/vendored.js";
+import { PLUGIN_KEY, UPSTREAM_PLUGIN_NAME } from "../adapters/memory/vendored.js";
+import { scanReportOnly } from "./upstream-launchers.js";
+import { FREE_DIR_NAME, LEGACY_DIR_NAME } from "../adapters/memory/paths.js";
 import { manifestPath, readManifest } from "../infra/manifest.js";
-import { retiredFindings } from "./cleanup.js";
+import { canonicalNames, retiredFindings } from "./install-facts.js";
 import { languageLines, lintPaths } from "../adapters/content/language-lint.js";
 import { isOurHook } from "./uninstall.js";
 import { CLAUDE_MD_LINE_LIMIT, DEFAULT_PREFIX_BUDGET, cacheInvalidators, estimatePrefix, hookCount, lineCount, mcpRemoveCommand, mcpServerEntries, mcpServerNames, missingTtlKeys, readSettings } from "./prefix.js";
-import { ANTHROPIC_BASE_URL_ENV, CLAUDE_CODE_SUBAGENT_MODEL_ENV, tiersFromEnv } from "@freeharness/core";
+import { ANTHROPIC_BASE_URL_ENV, CLAUDE_CODE_SUBAGENT_MODEL_ENV, mapModel, tiersFromEnv } from "@freeharness/core";
+export { memoryPluginInstalled } from "./install-facts.js";
 const DEPS = [
     { name: "node", neededBy: "rules (memory/config guard, repeat-tool, session-start hooks), safety (security-guidance hook), cost (tracker, pruner, monitor hooks), skills (report-formatting docx)", version: ["node", "--version"] },
     { name: "npm", neededBy: "skills (report-formatting docx deps), sdd (vendored openspec build)", version: ["npm", "--version"] },
     { name: "bun", neededBy: "memory (worker build + plugin runtime)", version: ["bun", "--version"] },
-    { name: "uv", neededBy: "memory (Chroma vector store)", version: ["uv", "--version"] },
     { name: "python3", neededBy: "skills (report-formatting pptx)", version: ["python3", "--version"] },
     { name: "soffice", neededBy: "skills (report-formatting: pptx/docx -> pdf render)" },
     { name: "pdftoppm", neededBy: "skills (report-formatting: pdf -> thumbnails)" },
@@ -89,27 +92,18 @@ export function hookConflictLines(settingsPath, pluginInstalled) {
     }
     if (claudeMemHooks > 0) {
         lines.push(pluginInstalled
-            ? `WARN ${claudeMemHooks} claude-mem hook(s) in settings.json while the ${PLUGIN_KEY} plugin is installed — the plugin ships its own hooks.json; these duplicate it: run \`freeharness cleanup --scope user\``
-            : "OK   claude-mem hook detected in settings.json (coexists; no plugin registered)");
+            ? `WARN ${claudeMemHooks} upstream claude-mem hook(s) in settings.json while the ${PLUGIN_KEY} plugin is installed — the plugin ships its own hooks.json; these duplicate it: run \`freeharness cleanup --scope user\``
+            : "OK   upstream claude-mem hook detected in settings.json (coexists; no free-mem plugin registered)");
     }
     return lines;
 }
-/** Canonical agent file names and skill dir names: what a project could duplicate, and what doctor tells apart from the user's own content. */
-export function canonicalNames(canonicalDir) {
-    const list = (dir, dirsOnly) => {
-        if (!fs.existsSync(dir))
-            return [];
-        return fs
-            .readdirSync(dir, { withFileTypes: true })
-            .filter((e) => (dirsOnly ? e.isDirectory() : e.isFile() && e.name.endsWith(".md") && e.name !== "README.md"))
-            .map((e) => e.name);
-    };
-    return { agents: list(path.join(canonicalDir, "agents"), false), skills: list(path.join(canonicalDir, "skills"), true) };
-}
-/** Skills and agents under a Claude dir that FreeHarness did not emit (the user's own content); never a global `openspec-*` copy or a manifest-recorded retired name. */
-export function foreignContentLines(claudeDir, canonicalDir, scope, projectRoot) {
+/**
+ * Skills and agents under a Claude dir that FreeHarness did not emit (the user's own content); never a global `openspec-*` copy or a manifest-recorded retired name.
+ * @param home Home whose `.claude` holds the user-scope manifest; never derived from `claudeDir`.
+ */
+export function foreignContentLines(claudeDir, canonicalDir, scope, projectRoot, home = os.homedir()) {
     const names = canonicalNames(canonicalDir);
-    const manifest = readManifest(manifestPath(scope, projectRoot));
+    const manifest = readManifest(manifestPath(scope, projectRoot, home));
     const recordedRetired = new Set(retiredFindings(claudeDir, manifest).filter((f) => f.recorded).map((f) => f.path));
     const lines = [];
     const skillsDir = path.join(claudeDir, "skills");
@@ -157,25 +151,9 @@ export function runningFromLines(argv1, home) {
     }
     return [`WARN running from ${running}; ${ours} exists — open a new terminal or run \`freeharness cleanup --scope user\` (an old npm link may shadow it)`];
 }
-/**
- * Whether claude-mem is enabled in settings.json or registered in installed_plugins.json.
- * @param claudeDir The ~/.claude (or project .claude) dir.
- * @returns True when found in either place.
- */
-export function memoryPluginInstalled(claudeDir) {
-    const read = (f) => {
-        try {
-            return JSON.parse(fs.readFileSync(f, "utf8"));
-        }
-        catch {
-            return {};
-        }
-    };
-    const settings = read(path.join(claudeDir, "settings.json"));
-    if (settings.enabledPlugins?.[PLUGIN_KEY] === true)
-        return true;
-    const ip = read(path.join(claudeDir, "plugins", "installed_plugins.json"));
-    return Boolean(ip.plugins && PLUGIN_KEY in ip.plugins);
+/** Launchers in files cleanup never writes; only file and line are printed, never the other program's text. */
+export function reportOnlyLauncherLines(home) {
+    return scanReportOnly(home).map((m) => `WARN upstream ${UPSTREAM_PLUGIN_NAME} launcher at ~/${path.relative(home, m.file)}:${m.line} (remove this line by hand; cleanup never edits this file)`);
 }
 /**
  * PROVENANCE baseline vs upstream fork HEAD for each vendored engine.
@@ -264,6 +242,92 @@ export function openspecChangeLines(projectRoot) {
     const ids = `${shown.join(", ")}${s.complete.length > shown.length ? ", ..." : ""}`;
     return [`WARN complete changes not archived: ${ids} — ${s.complete.length} of ${tail}`];
 }
+/**
+ * Lists the subdirectory names of a directory, empty when it cannot be read.
+ * @param dir Directory to list.
+ * @returns Sorted directory names.
+ */
+function subdirNames(dir) {
+    try {
+        return fs.readdirSync(dir, { withFileTypes: true }).filter((e) => e.isDirectory()).map((e) => e.name).sort();
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Warns about SDD worktrees whose change is no longer in flight; a tree kept after a blocked
+ * task or a refused removal must stay visible once its change is archived. Plain fs, so
+ * doctor never spawns git and never mutates the tree.
+ * @param projectRoot Project root.
+ * @returns One WARN line per stale <root>/.worktrees/<change>/<task> directory.
+ */
+export function staleTreeLines(projectRoot) {
+    const trees = path.join(projectRoot, ".worktrees");
+    const changesDir = path.join(projectRoot, "openspec", "changes");
+    const inFlight = new Set(subdirNames(changesDir).filter((n) => n !== "archive"));
+    const archived = subdirNames(path.join(changesDir, "archive"));
+    const lines = [];
+    for (const change of subdirNames(trees)) {
+        if (inFlight.has(change))
+            continue;
+        const state = archived.some((a) => a === change || a.endsWith(`-${change}`)) ? "archived" : "absent";
+        for (const task of subdirNames(path.join(trees, change))) {
+            const p = path.join(trees, change, task);
+            lines.push(`WARN stale SDD worktree ${p}: change ${change} is ${state} — remove it with \`git worktree remove ${p}\``);
+        }
+    }
+    return lines;
+}
+/**
+ * Warns when the guard hooks fail closed and node is not resolvable: with onFailure block a
+ * missing runtime denies every Edit, Write and Bash call, so the owner must hear it before
+ * being locked out. PATH is scanned for absolute entries only and no shell runs, so a
+ * relative entry cannot supply the binary; the settings file is only read. Only the first
+ * existing binary is probed because it is the one the hook shell runs; a later healthy node
+ * cannot rescue the hooks. win32 looks for node.exe alone, since spawnSync cannot run a .cmd
+ * without a shell.
+ * @param settingsPath The user settings.json.
+ * @param env Environment whose PATH is searched.
+ * @param timeoutMs Version probe limit; tests shorten it.
+ * @returns One OK or WARN line, or none when no blocking guard entry exists.
+ */
+export function guardRuntimeLines(settingsPath, env = process.env, timeoutMs = 5000) {
+    const tail = "the guard hooks fail closed and block every Edit, Write and Bash call";
+    let settings;
+    try {
+        settings = JSON.parse(fs.readFileSync(settingsPath, "utf8"));
+    }
+    catch (e) {
+        if (e.code === "ENOENT")
+            return [];
+        return [`WARN guard runtime: ${settingsPath} unreadable or invalid JSON; check skipped`];
+    }
+    const asList = (v) => (Array.isArray(v) ? v : []);
+    const isRecord = (v) => !!v && typeof v === "object" && !Array.isArray(v);
+    const events = isRecord(settings) && isRecord(settings.hooks) ? Object.values(settings.hooks) : [];
+    const blocking = events.some((groups) => asList(groups).some((g) => isRecord(g) && asList(g.hooks).some((h) => isRecord(h) && typeof h.command === "string" && h.onFailure === "block" && /freeharness-(config|memory)-guard/.test(h.command))));
+    if (!blocking)
+        return [];
+    const names = process.platform === "win32" ? ["node.exe"] : ["node"];
+    for (const dir of (env.PATH ?? "").split(path.delimiter)) {
+        if (!path.isAbsolute(dir))
+            continue;
+        for (const name of names) {
+            const bin = path.join(dir, name);
+            if (!fs.existsSync(bin))
+                continue;
+            const r = spawnSync(bin, ["--version"], { encoding: "utf8", timeout: timeoutMs });
+            const version = r.status === 0 ? (r.stdout ?? "").trim() : "";
+            if (version)
+                return [`OK guard runtime: node ${version}`];
+            const code = r.error?.code;
+            const why = code === "ETIMEDOUT" ? "timed out" : `exit ${r.status ?? r.signal ?? code}`;
+            return [`WARN guard runtime: ${bin} did not report a version (${why}); ${tail}`];
+        }
+    }
+    return [`WARN guard runtime: node not found on PATH; ${tail}`];
+}
 /**
  * Install-manifest presence and drift (listed files that are gone).
  * @param manifestFile The manifest path for the scope.
@@ -339,10 +403,24 @@ export function budgetLines(inp) {
     const inv = cacheInvalidators(userSettings, projectSettings);
     lines.push(inv.length === 0
         ? "  OK   cache invalidators: none (project settings do not override model / effortLevel / permissions.deny)"
-        : `  FAIL cache invalidators: ${inv.map((i) => `${i.key}=${JSON.stringify(i.project)} (user: ${i.user === undefined ? "unset" : JSON.stringify(i.user)})`).join("; ")} — project overrides in ${projectSettingsFiles[0]} invalidate the prompt cache; set them at user scope`);
+        : `  FAIL cache invalidators: ${inv.map((i) => `${i.key}=${shownSetting(i.project)} (user: ${i.user === undefined ? "unset" : shownSetting(i.user)})`).join("; ")} — project overrides in ${projectSettingsFiles[0]} invalidate the prompt cache; set them at user scope`);
     lines.push(contextWindowLine(userSettings, projectSettings));
     return lines;
 }
+/** Settings strings come from a project's own files, so a value may carry terminal escapes or hidden text. */
+const UNSAFE_SHOWN = /[\u0000-\u001f\u007f-\u009f\p{Cf}\p{Zl}\p{Zp}]/gu;
+const SHOWN_MAX = 80;
+/** `s` with every control, format or separator character as `?`, cut to `max` code points; `?` when empty. */
+function safeShown(s, max = SHOWN_MAX) {
+    const shown = Array.from(s.replace(UNSAFE_SHOWN, "?")).slice(0, max).join("");
+    return shown === "" ? "?" : shown;
+}
+/** A cache invalidator value as JSON: a model or effort string filtered and cut first, anything else only filtered. */
+function shownSetting(value) {
+    if (typeof value === "string")
+        return JSON.stringify(safeShown(value));
+    return safeShown(JSON.stringify(value) ?? String(value), Infinity);
+}
 /**
  * Splits a model id on a trailing `[suffix]` tag (e.g. `claude-fable-5-1[1m]`).
  * @param model Model id as recorded in settings.json.
@@ -367,10 +445,81 @@ export function contextWindowLine(userSettings, projectSettings) {
     const projectSplit = projectModel ? splitModelSuffix(projectModel) : undefined;
     const longContext = userSplit?.suffix?.toLowerCase() === "1m" ? { scope: "user", ...userSplit } : projectSplit?.suffix?.toLowerCase() === "1m" ? { scope: "project", ...projectSplit } : undefined;
     if (longContext) {
-        return `  WARN context window: ${longContext.scope} settings.json model ${longContext.base}[${longContext.suffix}] (1M tokens); a week on [${longContext.suffix}] cost 1.69G cache-read tokens; standard window: ${longContext.base}`;
+        const base = safeShown(longContext.base);
+        const suffix = safeShown(longContext.suffix ?? "");
+        return `  WARN context window: ${longContext.scope} settings.json model ${base}[${suffix}] (1M tokens); a week on [${suffix}] cost 1.69G cache-read tokens; standard window: ${base}`;
     }
     const effective = projectModel ?? userModel;
-    return `  OK   context window: standard (${effective ?? "not set"})`;
+    return `  OK   context window: standard (${effective === undefined ? "not set" : safeShown(effective)})`;
+}
+const SESSION_DEFAULT = "absent (Claude Code default)";
+/**
+ * The lead's model and effort drive most of a change's cost and are the owner's settings, so
+ * the doctor reports them and never writes them. A full id (`claude-opus-5-5[1m]`) counts as
+ * its family when the alias is one of its whole segments.
+ */
+export function sessionModelFinding(settings, tierAlias) {
+    const s = settings && typeof settings === "object" && !Array.isArray(settings) ? settings : {};
+    const model = typeof s.model === "string" && s.model ? s.model : undefined;
+    const perModel = model && s.modelSettings && typeof s.modelSettings === "object" ? s.modelSettings[model] : undefined;
+    const scoped = perModel && typeof perModel === "object" ? perModel.effortLevel : undefined;
+    const effort = typeof scoped === "string" ? scoped : typeof s.effortLevel === "string" ? s.effortLevel : undefined;
+    const strong = model !== undefined && splitModelSuffix(model).base.toLowerCase().split(/[^a-z0-9]+/).includes(tierAlias.toLowerCase());
+    const found = `session model ${model === undefined ? SESSION_DEFAULT : safeShown(model)}, effort ${effort === undefined ? SESSION_DEFAULT : safeShown(effort)}`;
+    return strong && effort === "high" ? { level: "OK", line: `OK   ${found} (strong tier at high)` } : { level: "INFO", line: `INFO ${found}; the orchestrating session runs best on the strong tier at high` };
+}
+/**
+ * A missing settings file is the all-default case, while an unreadable or invalid one is
+ * named, so the doctor never fails on it.
+ */
+export function sessionModelLine(settingsFile) {
+    let text;
+    try {
+        text = fs.readFileSync(settingsFile, "utf8");
+    }
+    catch (e) {
+        const code = e.code;
+        if (code === "ENOENT")
+            return withAgentTeamsNotice(sessionModelFinding({}, mapModel("claude-code", "strong")).line, {});
+        return withAgentTeamsNotice(`INFO session model and effort not read: ${settingsFile} is unreadable (${code ?? String(e)})`, {});
+    }
+    let settings;
+    try {
+        settings = JSON.parse(text);
+    }
+    catch {
+        return withAgentTeamsNotice(`INFO session model and effort not read: ${settingsFile} is not valid JSON`, {});
+    }
+    return withAgentTeamsNotice(sessionModelFinding(settings, mapModel("claude-code", "strong")).line, settings);
+}
+/**
+ * free-mem is the only memory owner, so Claude Code auto memory beside it writes a second,
+ * unrecalled store; the key off without free-mem leaves the machine with no memory at all.
+ * The value is the owner's: the doctor names it and never writes it.
+ */
+export function autoMemoryLine(settingsFile, freeMemEnabled) {
+    const value = readSettings(settingsFile).autoMemoryEnabled;
+    if (value === false) {
+        return freeMemEnabled
+            ? "OK   auto memory off (autoMemoryEnabled false); free-mem owns memory"
+            : `WARN autoMemoryEnabled is false but ${PLUGIN_KEY} is not enabled: no memory is kept (enable free-mem or remove the key)`;
+    }
+    const shown = value === undefined ? "absent (Claude Code default: on)" : JSON.stringify(value);
+    const fix = value === undefined ? "run `freeharness update --scope user`" : "set it to false in settings.json";
+    return freeMemEnabled
+        ? `WARN auto memory on beside ${PLUGIN_KEY}: autoMemoryEnabled is ${shown}; ${fix} so free-mem stays the only memory`
+        : `INFO auto memory on (autoMemoryEnabled ${shown}); ${PLUGIN_KEY} not enabled`;
+}
+/**
+ * With agent teams on, a named Agent dispatch launches as a teammate at the lead's effort, so
+ * the owner is told why SDD dispatches carry no name. Either the settings `env` or the process
+ * environment turns the flag on.
+ */
+function withAgentTeamsNotice(line, settings) {
+    const s = settings && typeof settings === "object" && !Array.isArray(settings) ? settings : {};
+    const env = s.env && typeof s.env === "object" && !Array.isArray(s.env) ? s.env : {};
+    const on = env.CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS === "1" || process.env.CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS === "1";
+    return on ? `${line}\nINFO agent teams on (CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1): a named Agent dispatch launches as a teammate at the lead's effort; SDD dispatches pass no name` : line;
 }
 /** ms; a local server that misses this is down. */
 export const PROBE_TIMEOUT_MS = 1500;
@@ -571,7 +720,7 @@ export function installedContentCounts(claudeDir) {
 }
 /** Roots a hook command may point at without being flagged foreign. */
 export function trustedHookRoots(home) {
-    return [path.join(home, ".claude", "freeharness"), path.join(home, ".claude", "plugins"), path.join(home, ".claude-mem"), "${CLAUDE_PLUGIN_ROOT}", "${CLAUDE_PROJECT_DIR}"];
+    return [path.join(home, ".claude", "freeharness"), path.join(home, ".claude", "plugins"), path.join(home, FREE_DIR_NAME), path.join(home, LEGACY_DIR_NAME), "${CLAUDE_PLUGIN_ROOT}", "${CLAUDE_PROJECT_DIR}"];
 }
 /**
  * Extracts the script path of a hook command: the first quoted or bare token that looks

package/dist/cli/hard-cleanup.d.ts

@@ -0,0 +1,93 @@
+import type { Scope } from "@freeharness/core";
+/** Memory logs younger than this many days (by the date in the name) stay. */
+export declare const LOG_RETENTION_DAYS = 14;
+/** Where hard cleanup looks and when it runs; tests inject every field. */
+export interface HardContext {
+    readonly home: string;
+    readonly configDir: string;
+    readonly dataDir: string;
+    readonly now: Date;
+}
+interface HardItemBase {
+    /** The moved path, or `installed_plugins.json` for a `registry-entry`. */
+    readonly source: string;
+    /** Archive path of the moved item, or of the pre-edit registry copy. */
+    readonly destination: string;
+    readonly reason: string;
+    /** Set when the item stays; the reason why. */
+    readonly refused?: string;
+}
+/** A path moved into the archive. */
+export interface HardMoveItem extends HardItemBase {
+    readonly kind: "move";
+    readonly bytes: number;
+}
+/** A dead plugin key removed from `installed_plugins.json`. */
+export interface HardRegistryItem extends HardItemBase {
+    readonly kind: "registry-entry";
+    readonly key: string;
+}
+/** One artifact the hard pass moves (or, when `refused`, keeps). */
+export type HardItem = HardMoveItem | HardRegistryItem;
+/** What a hard pass would (or did) do. */
+export interface HardPlan {
+    readonly scope: Scope;
+    readonly archiveRoot: string;
+    readonly items: readonly HardItem[];
+    /** Informational lines: seen, but not moved. */
+    readonly notes: readonly string[];
+    /** The resolved context the plan was built with; `applyHard` re-checks protected paths against it. */
+    readonly ctx: HardContext;
+    readonly projectRoot: string;
+}
+/** Outcome of `applyHard`. */
+export interface HardResult {
+    /** One `source -> destination` line per moved item. */
+    moved: string[];
+    /** Refused, or not confirmed. */
+    skipped: string[];
+    /** Failed moves or edits; their sources stay in place. */
+    warnings: string[];
+}
+/** Filesystem primitives `applyHard` moves with, injectable for the cross-device path. */
+export interface HardFs {
+    rename(from: string, to: string): void;
+    copy(from: string, to: string): void;
+}
+/** Escapes C0/C1, format (bidi, zero-width) and line-separator controls, so a file name cannot drive or reorder the terminal. */
+export declare function printable(s: string): string;
+/** First free name of `dest`, `dest.2`, ...; locators never share a destination. */
+export declare function freeDestination(dest: string): string;
+/** Why a path must be neither removed nor moved as itself: it is, lies in, or holds the plugin cache. The last segment is not followed. */
+export declare function pluginCacheOverlap(target: string, cfg: string): string | undefined;
+/** Same resolution as the data-dir guard below. */
+export declare function isOrHolds(candidate: string, dir: string): boolean;
+/** The dated archive every cleanup move lands in: `<home>/Archive/freeharness-<local date>`. */
+export declare function archiveRootFor(home: string, now: Date): string;
+/**
+ * Why a plugin-cache item must stay: its realpath is not strictly inside the plugin cache.
+ * The hard list's guard refuses every cache path by design, so cache items get this check instead.
+ */
+export declare function pluginCacheEscape(source: string, cfg: string): string | undefined;
+/**
+ * Archive destination of a plugin-cache path, `<archiveRoot>/plugins-cache/<path below the cache>`; reads only.
+ * A source not spelled below the cache would map outside `plugins-cache`, so it is refused and gets
+ * the `plugins-cache` dir itself, which the apply-time check never accepts.
+ */
+export declare function pluginCacheArchive(source: string, cfg: string, archiveRoot: string): {
+    destination: string;
+    refused?: string;
+};
+/** Why a planned plugin-cache move must not run now: no archive root, a destination outside `<archiveRoot>/plugins-cache`, or a source escaping the cache. */
+export declare function pluginCacheRefusal(source: string, destination: string, cfg: string, archiveRoot: string | undefined): string | undefined;
+/** Builds the hard-item plan for a scope; reads only. */
+export declare function planHard(scope: Scope, projectRoot: string, ctx?: Partial<HardContext>): HardPlan;
+/** Moves one path to a reserved name at or after `destination` with the hard mover's guarantees; returns where it landed. */
+export declare function archiveMove(source: string, destination: string, fsOps?: Partial<HardFs>): string;
+/** The WARN line of a failed move: a source gone since planning reads as such, anything else keeps its error code. */
+export declare function moveWarning(source: string, e: unknown): string;
+/** Moves the confirmed items of a plan (`confirmed` defaults to all); refused items are always skipped. */
+export declare function applyHard(plan: HardPlan, confirmed?: (item: HardItem) => boolean, fsOps?: Partial<HardFs>): HardResult;
+/** Renders a hard item for the preview, one line, without the OK/WARN prefix; the caller escapes it. */
+export declare function describeHard(item: HardItem): string;
+export {};