freeharness 0.4.2 → 0.4.3

package/dist/adapters/memory/paths.js

@@ -1,11 +1,11 @@
-// The CLI cannot import the engine: a copy of engine/shared/data-dir.ts and paths.ts resolveDbPath.
+// The CLI cannot import the engine: a copy of engine/shared/data-dir.ts resolveDataDir.
 import fs from "node:fs";
 import path from "node:path";
 export const FREE_DIR_NAME = ".free-mem";
+/** The pre-rename data directory: never read, only kept protected and named by doctor. */
 export const LEGACY_DIR_NAME = ".claude-mem";
 export const DB_FILENAME = "free-mem.db";
-export const LEGACY_DB_FILENAME = "claude-mem.db";
-const DATA_DIR_KEYS = ["FREE_MEM_DATA_DIR", "CLAUDE_MEM_DATA_DIR"];
+const DATA_DIR_KEY = "FREE_MEM_DATA_DIR";
 function expandHome(p, home) {
     if (p === "~")
         return home;
@@ -13,14 +13,6 @@ function expandHome(p, home) {
         return path.join(home, p.slice(2));
     return p;
 }
-function isDirectory(p) {
-    try {
-        return fs.statSync(p).isDirectory();
-    }
-    catch {
-        return false;
-    }
-}
 /** A settings file's keys as the engine reads them (BOM dropped, `env` first); null when unreadable. */
 export function readMemorySettings(settingsPath) {
     try {
@@ -34,52 +26,22 @@ export function readMemorySettings(settingsPath) {
         return null;
     }
 }
-// Either default directory is a seeded value, not a redirect; honoring it pins later starts.
+// A seeded or hand-copied default is no redirect; honoring it pins later starts.
 function settingsDataDir(settingsPath, home, defaultDirs) {
-    const settings = readMemorySettings(settingsPath);
-    if (!settings)
+    const value = readMemorySettings(settingsPath)?.[DATA_DIR_KEY];
+    if (typeof value !== "string" || !value)
         return undefined;
-    for (const key of DATA_DIR_KEYS) {
-        const value = settings[key];
-        if (typeof value !== "string" || !value)
-            continue;
-        const dir = expandHome(value, home);
-        if (!defaultDirs.includes(path.resolve(dir)))
-            return dir;
-    }
-    return undefined;
-}
-function dbFileIn(dataDir) {
-    const current = path.join(dataDir, DB_FILENAME);
-    const legacy = path.join(dataDir, LEGACY_DB_FILENAME);
-    return !fs.existsSync(current) && fs.existsSync(legacy) ? legacy : current;
+    const dir = expandHome(value, home);
+    return defaultDirs.includes(path.resolve(dir)) ? undefined : dir;
 }
-/**
- * Resolves the memory data directory and database from `env` and `home` alone, never from
- * process globals, so callers and tests can pass fake values.
- * @param env Environment to read `FREE_MEM_DATA_DIR` and `CLAUDE_MEM_DATA_DIR` from.
- * @param home Home directory that holds `.free-mem` and `.claude-mem` and expands `~`.
- */
+/** The data directory and database from `env` and `home` alone, never process globals, so tests pass fakes. */
 export function resolveMemoryPaths(env, home) {
     const freeDir = path.join(home, FREE_DIR_NAME);
-    const legacyDir = path.join(home, LEGACY_DIR_NAME);
-    const defaultDirs = [path.resolve(freeDir), path.resolve(legacyDir)];
-    const result = (dataDir, source) => ({
-        dataDir,
-        dbFile: dbFileIn(dataDir),
-        legacy: path.resolve(dataDir) === defaultDirs[1],
-        source,
-    });
-    for (const key of DATA_DIR_KEYS) {
-        const value = env[key];
-        if (value)
-            return result(expandHome(value, home), key);
-    }
-    for (const dir of [freeDir, legacyDir]) {
-        const redirect = settingsDataDir(path.join(dir, "settings.json"), home, defaultDirs);
-        if (redirect)
-            return result(redirect, "settings");
-    }
-    // An unmigrated install keeps serving its legacy directory until the copy creates ~/.free-mem.
-    return isDirectory(freeDir) || !isDirectory(legacyDir) ? result(freeDir, "default") : result(legacyDir, "fallback");
+    const defaultDirs = [path.resolve(freeDir), path.resolve(home, LEGACY_DIR_NAME)];
+    const result = (dataDir, source) => ({ dataDir, dbFile: path.join(dataDir, DB_FILENAME), source });
+    const value = env[DATA_DIR_KEY];
+    if (value)
+        return result(expandHome(value, home), DATA_DIR_KEY);
+    const redirect = settingsDataDir(path.join(freeDir, "settings.json"), home, defaultDirs);
+    return redirect ? result(redirect, "settings") : result(freeDir, "default");
 }

package/dist/adapters/memory/vendored.d.ts

@@ -116,7 +116,7 @@ export declare function isUpstreamRegistered(installed: {
 }, settings: {
     enabledPlugins?: Record<string, boolean>;
 }): boolean;
-/** Write the `.install-version` marker that tells our build apart; never writes through a symlink. `uv` stays for readers of the old shape. */
+/** Write the `.install-version` marker that tells our build apart; never writes through a symlink. */
 export declare function writeInstallMarker(dir: string, version: string, bun: string): string;
 /**
  * Version from a plugin dir's manifest ("0.0.0" when absent). The version names a cache
@@ -167,11 +167,6 @@ export declare class VendoredMemory implements MemoryPort {
      * An upstream registration (UPSTREAM_PLUGIN_KEY) is never written: doctor warns about it.
      */
     registerHooks(_scope: Scope, ctx: InstallContext): Promise<AdapterResult>;
-    /**
-     * Copy a legacy ~/.claude-mem forward into ~/.free-mem: pass 1 prints the plan, pass 2 applies
-     * it. A worker it stops is restarted by `update` once the bundle is staged, else at SessionStart.
-     * The copy is never recorded in `written`, since uninstall removes what the manifest lists.
-     */
-    migrateExisting(ctx: InstallContext): Promise<AdapterResult>;
+    migrateExisting(_ctx: InstallContext): Promise<AdapterResult>;
     private run;
 }

package/dist/adapters/memory/vendored.js

@@ -1,32 +1,22 @@
 // MemoryPort adapter for the vendored claude-mem engine (FreeHarness V3-P0 memory-runtime).
 //
-// Installs free-mem as a real Claude Code plugin from OUR build, reproducing the
-// upstream `npx claude-mem install` mechanics (src/npx-cli/commands/install.ts +
-// utils/paths.ts + install/setup-runtime.ts) in TypeScript:
+// Installs free-mem as a real Claude Code plugin from OUR build, reproducing the upstream `npx claude-mem
+// install` mechanics (src/npx-cli/commands/install.ts + utils/paths.ts + install/setup-runtime.ts) in TypeScript:
 //
 //   ensurePrerequisites  Bun probe (build + hook runtime), the only prerequisite.
-//   install              bun run build:plugin -> copyPluginToCache(version)
-//                        -> copyPluginToMarketplace -> plugin deps install
-//                        -> .install-version markers.
-//   registerHooks        known_marketplaces.json + installed_plugins.json +
-//                        settings.enabledPlugins["free-mem@freeharness"]=true,
-//                        all ADDITIVE merges (other entries survive). The upstream
-//                        key (UPSTREAM_PLUGIN_KEY) is never written; doctor warns
-//                        while it is live.
-//   migrateExisting      copies a legacy ~/.claude-mem forward into ~/.free-mem
-//                        (migrate.ts); the legacy directory is only read.
+//   install              bun run build:plugin -> copyPluginToCache(version) -> copyPluginToMarketplace
+//                        -> plugin deps install -> .install-version markers.
+//   registerHooks        known_marketplaces.json + installed_plugins.json + enabledPlugins
+//                        ["free-mem@freeharness"], all ADDITIVE merges; the upstream key
+//                        (UPSTREAM_PLUGIN_KEY) is never written; doctor warns while it is live.
 //
-// The FreeHarness build declares its own identity (marketplace freeharness, plugin
-// free-mem) so `doctor` and `cleanup` can tell it apart from an upstream or
-// pre-rename install. Every write honors ctx.dryRun (writes nothing, reports the plan).
+// The FreeHarness build declares its own identity (marketplace freeharness, plugin free-mem) so `doctor` and
+// `cleanup` can tell it apart from an upstream or pre-rename install. Every write honors ctx.dryRun.
 import crypto from "node:crypto";
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { spawnSync } from "node:child_process";
-import { cliVersion } from "../../infra/paths.js";
-import { applyMemoryMigration, bunIntegrityCheck, describePlan, describeResult, planMemoryMigration } from "./migrate.js";
-import { FREE_DIR_NAME, LEGACY_DIR_NAME, resolveMemoryPaths } from "./paths.js";
 const IS_WINDOWS = process.platform === "win32";
 /** Name of the digest marker written into the plugin cache directory after a copy. */
 const BUNDLE_MARKER_NAME = "bundle.sha256";
@@ -284,7 +274,7 @@ function writeJsonAtomic(file, value) {
     fs.writeFileSync(tmp, JSON.stringify(value, null, 2) + "\n", "utf-8");
     fs.renameSync(tmp, file);
 }
-/** Write the `.install-version` marker that tells our build apart; never writes through a symlink. `uv` stays for readers of the old shape. */
+/** Write the `.install-version` marker that tells our build apart; never writes through a symlink. */
 export function writeInstallMarker(dir, version, bun) {
     const marker = path.join(dir, ".install-version");
     fs.mkdirSync(dir, { recursive: true });
@@ -476,43 +466,8 @@ export class VendoredMemory {
         res.notes.push("Lifecycle hooks and the mem-search MCP come from the plugin's own hooks.json / .mcp.json (no settings.json hook entries are written).");
         return res;
     }
-    /**
-     * Copy a legacy ~/.claude-mem forward into ~/.free-mem: pass 1 prints the plan, pass 2 applies
-     * it. A worker it stops is restarted by `update` once the bundle is staged, else at SessionStart.
-     * The copy is never recorded in `written`, since uninstall removes what the manifest lists.
-     */
-    async migrateExisting(ctx) {
-        const res = this.result();
-        const home = os.homedir();
-        const plan = planMemoryMigration(home, process.env);
-        if (!plan) {
-            const p = resolveMemoryPaths(process.env, home);
-            const freeDir = path.join(home, FREE_DIR_NAME);
-            const db = fs.existsSync(p.dbFile) ? ` (${path.basename(p.dbFile)} present)` : "";
-            if (p.source !== "default")
-                res.notes.push(`Existing memory data kept at ${p.dataDir}${db}; the ${PLUGIN_NAME} plugin reads it through ${p.source}, so no copy is planned. Nothing deleted.`);
-            else if (fs.existsSync(freeDir))
-                res.notes.push(`Memory data already at ${freeDir}; no copy planned.`);
-            else
-                res.notes.push(`No legacy memory data at ${path.join(home, LEGACY_DIR_NAME)}; the worker creates ${freeDir} on first start.`);
-            return res;
-        }
-        if (ctx.dryRun) {
-            res.notes.push(...describePlan(plan));
-            return res;
-        }
-        const result = await applyMemoryMigration(plan, {
-            stopWorker: async () => (await import("./doctor.js")).stopWorker("shutdown"),
-            now: Date.now,
-            integrityCheck: bunIntegrityCheck(probeBun().path),
-            version: cliVersion(),
-        });
-        const lines = describeResult(plan, result);
-        res.notes.push(...lines);
-        // The executor prints only the preview's notes, so the outcome of pass 2 is printed here.
-        for (const l of lines)
-            console.log(`memory: ${l}`);
-        return res;
+    async migrateExisting(_ctx) {
+        return this.result();
     }
     run(cmd, args, cwd, label) {
         const r = spawnSync(cmd, args, { cwd, stdio: "inherit", windowsHide: true, env: process.env });

package/dist/adapters/memory/worker-control.d.ts

@@ -0,0 +1,9 @@
+import fs from "node:fs";
+export interface StopResult {
+    /** True when no worker answers and no live pid file remains. */
+    stopped: boolean;
+    wasRunning: boolean;
+    reason?: string;
+}
+/** True when `pidFile` exists and names a live process, or cannot be read as a pid record. */
+export declare function pidFileLive(pidFile: string, f?: typeof fs): boolean;

package/dist/adapters/memory/worker-control.js

@@ -0,0 +1,30 @@
+// The worker's pid-file check and the stop outcome shared by the doctor's stop and restart paths.
+import fs from "node:fs";
+function readJsonText(raw) {
+    try {
+        return JSON.parse(raw) ?? {};
+    }
+    catch {
+        return {};
+    }
+}
+/** True when `pidFile` exists and names a live process, or cannot be read as a pid record. */
+export function pidFileLive(pidFile, f = fs) {
+    let raw;
+    try {
+        raw = f.readFileSync(pidFile, "utf8");
+    }
+    catch {
+        return false;
+    }
+    const pid = Number(readJsonText(raw).pid);
+    if (!Number.isInteger(pid) || pid <= 0)
+        return true;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (e) {
+        return e.code === "EPERM";
+    }
+}

package/dist/cli/cleanup.d.ts

@@ -71,7 +71,7 @@ export declare function globalNpmPackages(): Record<string, string> | null;
 export declare function globalNpmFreeharnessBin(): string | undefined;
 /**
  * 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.
+ * Backups of the default directory count even while a redirected directory is in use.
  */
 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. */

package/dist/cli/cleanup.js

@@ -17,8 +17,8 @@ import path from "node:path";
 import { spawnSync } from "node:child_process";
 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, diagnoseMemory } from "../adapters/memory/doctor.js";
-import { FREE_DIR_NAME, LEGACY_DIR_NAME, resolveMemoryPaths } from "../adapters/memory/paths.js";
+import { configDir, diagnoseMemory, foreignWorkerStep } from "../adapters/memory/doctor.js";
+import { FREE_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";
@@ -113,11 +113,11 @@ export function globalNpmFreeharnessBin() {
 }
 /**
  * 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.
+ * Backups of the default directory count even while a redirected directory is in use.
  */
 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 dirs = [live, path.join(home, FREE_DIR_NAME)];
     const found = new Set();
     for (const data of dirs) {
         const parent = path.dirname(data);
@@ -160,6 +160,18 @@ function toArchive(item, 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}\``;
+/**
+ * Refusal while the build is not the sole active plugin. `memory activate` cannot clear a foreign
+ * worker beside our build, so that case names the doctor FAIL line's steps, as the mixed VERDICT does.
+ */
+function notOursRefusal(d) {
+    const verdictLine = d.lines.find((l) => l.includes("VERDICT")) ?? `verdict ${d.verdict}`;
+    const head = `the FreeHarness build is not the only active memory plugin yet (${verdictLine.replace(/^(OK|WARN)\s+/, "")})`;
+    const step = d.verdict === "mixed" ? foreignWorkerStep(d.worker) : null;
+    if (step === null)
+        return `${head}; run \`freeharness memory activate\` first`;
+    return `${head}; stop the foreign worker first (${step})`;
+}
 /** Computes the user-scope cleanup list; nothing is touched. */
 async function planUser(deps) {
     const archiveRoot = deps.archiveRoot ?? archiveRootFor(os.homedir(), new Date());
@@ -171,10 +183,8 @@ async function planUser(deps) {
     if (fs.existsSync(disabled)) {
         const d = deps.memory ?? (await diagnoseMemory());
         const item = { kind: "dir", target: disabled, reason: "upstream claude-mem parked by `memory activate`", group: "memory", bytes: dirBytes(disabled) };
-        if (d.verdict !== "ours") {
-            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`;
-        }
+        if (d.verdict !== "ours")
+            item.refused = notOursRefusal(d);
         plan.items.push(toArchive(item, cfg, archiveRoot));
     }
     // Superseded FreeHarness builds: our own cache versions (.install-version present) that are
@@ -232,8 +242,7 @@ async function planUser(deps) {
             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`;
+            refused = notOursRefusal(d);
         }
         if (fs.existsSync(oldCacheDir)) {
             plan.items.push(toArchive({ kind: "dir", target: oldCacheDir, reason: "previous registration, left in the plugin cache", group: "memory", bytes: dirBytes(oldCacheDir), refused }, cfg, archiveRoot));
@@ -282,17 +291,23 @@ 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: 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).
+    // Retired names: a skill, agent or file 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", ""));
+    const retiredReason = {
+        hook: (name) => `retired hook ${name} (removed from FreeHarness; update never deletes the installed copy)`,
+        file: () => "retired rules file (FreeHarness no longer emits it; update never deletes the installed copy)",
+        skill: () => "retired skill (renamed or folded elsewhere; kept on disk by update's additive manifest merge)",
+        agent: () => "retired agent (renamed or folded elsewhere; kept on disk by update's additive manifest merge)",
+    };
     for (const f of retiredFindings(path.join(os.homedir(), ".claude"), manifest)) {
         if (!f.recorded && f.kind !== "hook")
             continue;
         plan.items.push({
             kind: f.kind === "skill" ? "dir" : "file",
             target: f.path,
-            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)`,
+            reason: retiredReason[f.kind](f.name),
             group: "retired",
             bytes: f.kind === "skill" ? dirBytes(f.path) : undefined,
         });
@@ -347,7 +362,7 @@ function planProject(projectRoot, deps) {
     }
     const oldSafety = path.join(fhDir, "safety.md");
     if (fs.existsSync(oldSafety))
-        plan.items.push({ kind: "file", target: oldSafety, reason: "old project-scope safety.md (global since v0.3.0)", group: "duplicates" });
+        plan.items.push({ kind: "file", target: oldSafety, reason: "old project-scope safety.md (FreeHarness emits no safety.md)", group: "duplicates" });
     plan.notes.push(`kept: ${path.join(claude, "commands", "opsx")} and ${path.join(claude, "skills", "openspec-*")} (ours)`);
     return plan;
 }

package/dist/cli/cost.js

@@ -1948,7 +1948,7 @@ export function formatRoutingReport(result) {
     if (missingTasksFiles.length > 0)
         trailers.push(`tasks.md not found: ${missingTasksFiles.map(printable).join(", ")}`);
     if (skippedFiles.length > 0)
-        trailers.push(`skipped files (symlink or not a regular file, ledger over 16 MiB, brief over 1 MiB, brief past the 500-brief cap or with an over-cap header line, unlistable change directory, or unreadable): ${skippedFiles.map(printable).join(", ")}`);
+        trailers.push(`skipped files (symlink or not a regular file, ledger, tasks.md or follow-ups.md over 16 MiB, brief or review package over 1 MiB, brief past the 500-brief cap or with an over-cap header line, unlistable change directory, or unreadable): ${skippedFiles.map(printable).join(", ")}`);
     if (result.calibrationWarning)
         trailers.push(printable(result.calibrationWarning));
     if (rows.length === 0)
@@ -1996,7 +1996,7 @@ function formatRoutingFigures({ reviewRows = [], lead, totalsPerAccepted, follow
         }
     }
     if (lead) {
-        lines.push(`lead (main-session tokens of telemetry records tagged with the change; a session is attributed by its change tag only): ${lead.sessions} session${lead.sessions === 1 ? "" : "s"}`);
+        lines.push(`lead (main-session tokens of telemetry records; a session is attributed by its changes array, its tokens apportioned across the changes): ${lead.sessions} session${lead.sessions === 1 ? "" : "s"}`);
         for (const [family, g] of nonZero(lead.tokens))
             lines.push(`    ${family}: cache-read ${fmtTokens(g.cache_read)}, fresh ${fmtTokens(g.fresh)}`);
     }

package/dist/cli/doctor.d.ts

@@ -21,7 +21,7 @@ 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[];
 /**
- * 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.
+ * Skills, agents and retired files 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[];
@@ -71,17 +71,17 @@ export declare function openspecChangeLines(projectRoot: string): string[];
  */
 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.
+ * Warns when a guard hook entry exists and node is not resolvable: a guard that cannot run
+ * allows, so a missing runtime silently leaves every Edit, Write and Bash call unguarded and
+ * the owner must hear it. Any guard entry counts, whatever its onFailure field. 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.
+ * @returns One OK or WARN line, or none when no guard entry exists.
  */
 export declare function guardRuntimeLines(settingsPath: string, env?: NodeJS.ProcessEnv, timeoutMs?: number): string[];
 /**

package/dist/cli/doctor.js

@@ -98,14 +98,18 @@ export function hookConflictLines(settingsPath, pluginInstalled) {
     return lines;
 }
 /**
- * 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.
+ * Skills, agents and retired files 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, home));
-    const recordedRetired = new Set(retiredFindings(claudeDir, manifest).filter((f) => f.recorded).map((f) => f.path));
+    const retired = retiredFindings(claudeDir, manifest);
+    const recordedRetired = new Set(retired.filter((f) => f.recorded).map((f) => f.path));
     const lines = [];
+    for (const f of retired)
+        if (f.kind === "file" && !f.recorded)
+            lines.push(`INFO file ${f.name} not from FreeHarness (yours; kept)`);
     const skillsDir = path.join(claudeDir, "skills");
     if (fs.existsSync(skillsDir)) {
         for (const e of fs.readdirSync(skillsDir, { withFileTypes: true })) {
@@ -280,20 +284,20 @@ export function staleTreeLines(projectRoot) {
     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.
+ * Warns when a guard hook entry exists and node is not resolvable: a guard that cannot run
+ * allows, so a missing runtime silently leaves every Edit, Write and Bash call unguarded and
+ * the owner must hear it. Any guard entry counts, whatever its onFailure field. 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.
+ * @returns One OK or WARN line, or none when no 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";
+    const tail = "the guard hooks cannot run and allow every Edit, Write and Bash call";
     let settings;
     try {
         settings = JSON.parse(fs.readFileSync(settingsPath, "utf8"));
@@ -306,8 +310,8 @@ export function guardRuntimeLines(settingsPath, env = process.env, timeoutMs = 5
     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)
+    const guarded = events.some((groups) => asList(groups).some((g) => isRecord(g) && asList(g.hooks).some((h) => isRecord(h) && typeof h.command === "string" && /freeharness-(config|memory)-guard/.test(h.command))));
+    if (!guarded)
         return [];
     const names = process.platform === "win32" ? ["node.exe"] : ["node"];
     for (const dir of (env.PATH ?? "").split(path.delimiter)) {
@@ -511,15 +515,16 @@ export function autoMemoryLine(settingsFile, freeMemEnabled) {
         : `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
+ * With agent teams on, a named Agent dispatch launches as a teammate that inherits the session
+ * effort, except a plugin-defined agent spawned by name, which keeps its own; 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;
+    return on ? `${line}\nINFO agent teams on (CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1): a named Agent dispatch launches as a teammate at the session effort (a plugin-defined agent spawned by name keeps its own); SDD dispatches pass no name` : line;
 }
 /** ms; a local server that misses this is down. */
 export const PROBE_TIMEOUT_MS = 1500;

package/dist/cli/hard-cleanup.js

@@ -13,7 +13,7 @@ import { removeJsonKey } from "./json-key-edit.js";
 export const LOG_RETENTION_DAYS = 14;
 /** Build and OS junk moved out of a FreeHarness checkout's canonical/. */
 const CANONICAL_JUNK = new Set(["node_modules", "__pycache__", ".venv", ".DS_Store"]);
-const LOG_NAME = /^claude-mem-(\d{4})-(\d{2})-(\d{2})\.log$/;
+const LOG_NAME = /^free-mem-(\d{4})-(\d{2})-(\d{2})\.log$/;
 /** `<file>.<stamp>.bak`, the stamp being `toISOString()` (always with milliseconds) with `:` and `.` replaced by `-`. */
 const BACKUP_NAME = /^(.+)\.(\d{4}-\d{2}-\d{2}T\d{2}-\d{2}-\d{2}-\d{3}Z)\.bak$/;
 const REINSTALL = "freeharness init --scope user --only memory";

package/dist/cli/install-facts.d.ts

@@ -1,16 +1,17 @@
 import type { InstallManifest } from "../infra/manifest.js";
-/** Retired by a rename, a fold or a removal, bare names under `~/.claude` (hooks: script names under `freeharness/hooks`). */
+/** Retired by a rename, a fold or a removal, bare names under `~/.claude` (hooks: script names under `freeharness/hooks`; files: paths relative to `.claude`). */
 export declare const RETIRED: {
     readonly skills: readonly ["local-code-intel"];
     readonly agents: readonly ["mle-reviewer", "mle-evaluator", "implementer-medium", "implementer-high"];
     readonly hooks: readonly ["freeharness-auto-memory.mjs"];
+    readonly files: readonly ["freeharness/safety.md"];
 };
-export type RetiredKind = "skill" | "agent" | "hook";
+export type RetiredKind = "skill" | "agent" | "hook" | "file";
 export interface RetiredFinding {
     kind: RetiredKind;
     name: string;
     path: string;
-    /** Manifest lists `path` (agent, hook) or a file under it (skill dir). */
+    /** Manifest lists `path` (agent, hook, file) or a file under it (skill dir). */
     recorded: boolean;
 }
 /** Whether a settings hook command runs a retired hook script; the entries `cleanup` prunes beside the script. */

package/dist/cli/install-facts.js

@@ -1,11 +1,12 @@
 import fs from "node:fs";
 import path from "node:path";
 import { PLUGIN_KEY } from "../adapters/memory/vendored.js";
-/** Retired by a rename, a fold or a removal, bare names under `~/.claude` (hooks: script names under `freeharness/hooks`). */
+/** Retired by a rename, a fold or a removal, bare names under `~/.claude` (hooks: script names under `freeharness/hooks`; files: paths relative to `.claude`). */
 export const RETIRED = {
     skills: ["local-code-intel"],
     agents: ["mle-reviewer", "mle-evaluator", "implementer-medium", "implementer-high"],
     hooks: ["freeharness-auto-memory.mjs"],
+    files: ["freeharness/safety.md"],
 };
 /** Whether a settings hook command runs a retired hook script; the entries `cleanup` prunes beside the script. */
 export function runsRetiredHook(command) {
@@ -17,6 +18,7 @@ export function retiredFindings(claudeDir, manifest) {
         { kind: "skill", dir: "skills", names: RETIRED.skills },
         { kind: "agent", dir: "agents", names: RETIRED.agents },
         { kind: "hook", dir: path.join("freeharness", "hooks"), names: RETIRED.hooks },
+        { kind: "file", dir: "", names: RETIRED.files },
     ];
     const found = [];
     for (const { kind, dir, names } of groups) {

package/dist/cli/profile.d.ts

@@ -144,7 +144,7 @@ export declare function applyProviderProfile(profile: Profile, data: ProviderPro
  */
 export declare function mcpCatalogItems(data: McpProfileFile): SelectItem[];
 /**
- * The `claude mcp add` command for a catalog entry (same shape the `mcp` capability emits).
+ * The `claude mcp add` command guarded by `claude mcp get` (as the `mcp` capability emits).
  * @param s Catalog entry.
  * @param scope user -> `-s user`, project -> `-s local`.
  * @returns Shell command.

package/dist/cli/profile.js

@@ -1,10 +1,8 @@
-// Opt-in profiles (v4 P6): `init --profile <id>` applies one data file from
-// canonical/profiles/ to an existing target. Three kinds: a Claude Code env block
-// (local-ollama), an OpenCode provider block + notes file (local-llamacpp) and an MCP
-// catalog with a selection prompt (mcp). Every write is additive (a key the user set is
-// kept), previewed first, confirmed second, and recorded in the install manifest so
-// `--profile none` removes exactly the keys and files a profile wrote. index.ts composes
-// the two passes; nothing here prompts.
+// Opt-in profiles: `init --profile <id>` applies one data file from canonical/profiles/
+// to an existing target (Claude Code env block, OpenCode provider block + notes file, or
+// an MCP catalog). Every write is additive, previewed first, confirmed second, and
+// recorded in the install manifest so `--profile none` removes exactly what a profile
+// wrote. index.ts composes the two passes; nothing here prompts.
 import fs from "node:fs";
 import path from "node:path";
 import { PROFILES, PROFILE_NONE, getProfile, tierEnv } from "@freeharness/core";
@@ -211,7 +209,7 @@ export function mcpCatalogItems(data) {
     return data.servers.map((s) => ({ id: s.name, label: `~${s.tools_approx} tools — ${s.description} [${s.context_cost}]` }));
 }
 /**
- * The `claude mcp add` command for a catalog entry (same shape the `mcp` capability emits).
+ * The `claude mcp add` command guarded by `claude mcp get` (as the `mcp` capability emits).
  * @param s Catalog entry.
  * @param scope user -> `-s user`, project -> `-s local`.
  * @returns Shell command.
@@ -219,9 +217,11 @@ export function mcpCatalogItems(data) {
 export function mcpAddCommand(s, scope) {
     const sc = scope === "user" ? "user" : "local";
     const envFlags = Object.entries(s.env ?? {}).map(([k, v]) => `-e ${k}=${v}`).join(" ");
+    // `claude mcp add` exits 1 for a registered name, so get runs first.
+    const guard = `claude mcp get ${s.name} >/dev/null 2>&1 || `;
     if (s.type === "http" || s.type === "sse")
-        return `claude mcp add --transport ${s.type} ${s.name} -s ${sc} ${s.url}`;
-    return `claude mcp add ${s.name} -s ${sc}${envFlags ? ` ${envFlags}` : ""} -- ${s.command} ${(s.args ?? []).join(" ")}`;
+        return `${guard}claude mcp add --transport ${s.type} ${s.name} -s ${sc} ${s.url}`;
+    return `${guard}claude mcp add ${s.name} -s ${sc}${envFlags ? ` ${envFlags}` : ""} -- ${s.command} ${(s.args ?? []).join(" ")}`;
 }
 /**
  * Builds the MCP profile plan for a selection: one `claude mcp add` action per selected