freeharness 0.4.1 → 0.4.3

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

@@ -16,7 +16,7 @@ export declare const UPSTREAM_PLUGIN_KEY = "claude-mem@thedotmack";
  *   canonicalDir: The resolved FreeHarness canonical directory (packages/cli/canonical).
  *
  * Returns:
- *   Absolute engine path, or null when the vendored tree is absent (npx bridge).
+ *   Absolute engine path, or null when the vendored tree is absent (memory is then skipped).
  */
 export declare function vendoredMemoryEngineDir(canonicalDir: string): string | null;
 /**
@@ -49,19 +49,44 @@ export interface ClaudePluginPaths {
  *   The path set mirrored from upstream utils/paths.ts.
  */
 export declare function claudePluginPaths(version: string): ClaudePluginPaths;
+/** Built bundles a plugin dir needs before it may replace a cached build. */
+export declare const PLUGIN_BUNDLES: readonly ["bun-runner.js", "worker-service.cjs", "mcp-server.cjs"];
 /**
- * Content digest of a plugin bundle: every file's relative posix path and bytes, in
- * path order, so a same-version rebuild whose output is byte-identical digests the
- * same as the previous run. Skips `node_modules` (matches the copy filter) and the
- * marker file itself, so re-staging never invalidates its own guard.
+ * Digest of a plugin bundle over every entry's relpath, type, mode and content or link target,
+ * in path order. Walks with lstat and never follows a symlink. Skips `node_modules` and the
+ * unstaged entries, so the vendored plugin and its staged copy digest alike.
  *
  * Args:
  *   dir: Directory to digest recursively (absent dir digests as empty).
  *
  * Returns:
- *   Lowercase hex SHA-256 over `path + NUL + content + NUL` per file.
+ *   Lowercase hex SHA-256.
  */
 export declare function bundleDigest(dir: string): string;
+export interface StageResult {
+    staged: boolean;
+    digest: string;
+    notes: string[];
+}
+/**
+ * Stage a plugin dir into a cache dir unless the marker and the cache's own digest both equal
+ * the plugin digest and the declared deps resolve; `staged` is true for a (would-be) re-stage.
+ */
+export declare function stagePluginCache(pluginDir: string, cacheDir: string, opts: {
+    dryRun: boolean;
+}): StageResult;
+/** Identity of the cache marker file (absent: null); every re-stage writes a new one. */
+export declare function stageStamp(cacheDir: string): string | null;
+export declare function missingPluginBundles(pluginDir: string): string[];
+/** Whether a plugin dir's package.json declares runtime deps, which only Bun installs. */
+export declare function declaresPluginDeps(dir: string): boolean;
+/**
+ * Declared plugin deps that do not resolve from `<dir>/node_modules` (upstream
+ * verifyCriticalModules), plus the zod subpaths the worker requires when zod is declared.
+ */
+export declare function missingPluginDeps(dir: string): string[];
+/** Install a staged cache's runtime deps (the hooks run from there); throws when one stays missing. */
+export declare function installPluginDeps(dir: string, bunPath: string): void;
 /** Probe result for one runtime tool. */
 export interface ToolProbe {
     path: string | null;
@@ -74,31 +99,39 @@ export interface ToolProbe {
  *   Path + version, or nulls when absent.
  */
 export declare function probeBun(): ToolProbe;
-/**
- * Probe uv (Chroma vector store runtime; upstream setup-runtime getUvPath).
- *
- * Returns:
- *   Path + version, or nulls when absent.
- */
-export declare function probeUv(): ToolProbe;
 /**
  * Whether an upstream registration (UPSTREAM_PLUGIN_KEY) is still live: present in
- * installed_plugins.json, or enabledPlugins carries it at a value other than `false`. Once a
- * migration sets it to `false`, later `registerHooks` runs see it as already migrated and skip
- * the backup/disable branch (idempotent on re-run).
+ * installed_plugins.json, or enabledPlugins carries it at a value other than `false`. Read-only:
+ * doctor warns on it and the data copy refuses while it is live.
  *
  * Args:
  *   installed: Parsed installed_plugins.json (or `{}` when absent).
  *   settings: Parsed settings.json (or `{}` when absent).
  *
  * Returns:
- *   True when the upstream key still needs disabling.
+ *   True when the upstream plugin may still load beside free-mem.
  */
 export declare function isUpstreamRegistered(installed: {
     plugins?: Record<string, unknown>;
 }, settings: {
     enabledPlugins?: Record<string, boolean>;
 }): boolean;
+/** 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
+ * directory that staging removes, so an empty or path-like value must never reach a path.
+ *
+ * Args:
+ *   pluginDir: Plugin directory holding `.claude-plugin/plugin.json`.
+ *
+ * Returns:
+ *   The semver version.
+ *
+ * Raises:
+ *   Error: When the manifest version is not a semver version.
+ */
+export declare function pluginVersion(pluginDir: string): string;
 /** MemoryPort implementation backed by the vendored claude-mem plugin build. */
 export declare class VendoredMemory implements MemoryPort {
     readonly engineDir: string;
@@ -115,7 +148,7 @@ export declare class VendoredMemory implements MemoryPort {
     version(): string;
     private result;
     /**
-     * Probe Bun and uv; instruct when missing. Never installs them (user's machine).
+     * Probe Bun; instruct when missing. Never installs it (user's machine).
      *
      * Returns:
      *   Notes only. A missing Bun is reported as "MISSING" and blocks install().
@@ -131,20 +164,9 @@ export declare class VendoredMemory implements MemoryPort {
      * Register the plugin with Claude Code (upstream registerMarketplace / registerPlugin /
      * enablePluginInClaudeSettings). All three writes are additive merges: other
      * marketplaces, plugins, hooks and settings keys are preserved byte-for-byte in shape.
-     *
-     * When an upstream registration (UPSTREAM_PLUGIN_KEY) is found (installed_plugins.json
-     * or a still-true enabledPlugins entry), this also backs up the three files below with a
-     * shared timestamp before the first write and disables (never deletes) the old key; the
-     * old cache directory is left in place for `freeharness cleanup` to offer later.
+     * An upstream registration (UPSTREAM_PLUGIN_KEY) is never written: doctor warns about it.
      */
     registerHooks(_scope: Scope, ctx: InstallContext): Promise<AdapterResult>;
-    /**
-     * Keep an existing ~/.claude-mem data directory from a delegated install. The
-     * plugin resolves it by convention (CLAUDE_MEM_DATA_DIR or ~/.claude-mem), so no
-     * write is needed and nothing is deleted.
-     */
     migrateExisting(_ctx: InstallContext): Promise<AdapterResult>;
     private run;
-    private missingPluginDeps;
-    private verifyPluginDeps;
 }

package/dist/adapters/memory/vendored.js

@@ -1,26 +1,17 @@
 // 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 (build + hook runtime) and uv (Chroma) probes.
-//   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). When an
-//                        upstream registration (UPSTREAM_PLUGIN_KEY) is found, it
-//                        also backs up the three registration files, registers the
-//                        new key and disables (never deletes) the old one.
-//   migrateExisting      an existing ~/.claude-mem data dir is kept; the plugin
-//                        already resolves it by convention (nothing is deleted).
+//   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 + 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; the data directory stays ~/.claude-mem by convention on
-// both sides. 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";
@@ -45,7 +36,7 @@ const CAPABILITY_ID = "memory";
  *   canonicalDir: The resolved FreeHarness canonical directory (packages/cli/canonical).
  *
  * Returns:
- *   Absolute engine path, or null when the vendored tree is absent (npx bridge).
+ *   Absolute engine path, or null when the vendored tree is absent (memory is then skipped).
  */
 export function vendoredMemoryEngineDir(canonicalDir) {
     const engineDir = path.join(canonicalDir, "..", "..", "memory", "vendor", UPSTREAM_PLUGIN_NAME, "engine");
@@ -63,7 +54,7 @@ export function vendoredMemoryEngineDir(canonicalDir) {
 export function memoryBuildActions(engineDir) {
     return [
         {
-            description: "Build the vendored claude-mem plugin bundles (worker, mcp, context, watcher) with Bun",
+            description: "Build the free-mem plugin bundles (worker, mcp, context, watcher) from the vendored engine with Bun",
             command: "bun install && bun run build:plugin",
             cwd: engineDir,
             optional: true,
@@ -93,42 +84,127 @@ export function claudePluginPaths(version) {
     };
 }
 /**
- * Content digest of a plugin bundle: every file's relative posix path and bytes, in
- * path order, so a same-version rebuild whose output is byte-identical digests the
- * same as the previous run. Skips `node_modules` (matches the copy filter) and the
- * marker file itself, so re-staging never invalidates its own guard.
+ * Top-level entries the cache gets after the copy (our markers, the deps lockfile, Claude
+ * Code's in-use and orphan markers): never copied and never digested, so staging cannot write
+ * through a plugin symlink and an install never reads its own bookkeeping as tampering.
+ */
+const UNSTAGED_ENTRIES = new Set([BUNDLE_MARKER_NAME, ".install-version", "bun.lock", "bun.lockb", ".in_use", ".orphaned_at"]);
+const S_IFMT = 0o170000;
+/** Built bundles a plugin dir needs before it may replace a cached build. */
+export const PLUGIN_BUNDLES = ["bun-runner.js", "worker-service.cjs", "mcp-server.cjs"];
+/**
+ * Digest of a plugin bundle over every entry's relpath, type, mode and content or link target,
+ * in path order. Walks with lstat and never follows a symlink. Skips `node_modules` and the
+ * unstaged entries, so the vendored plugin and its staged copy digest alike.
  *
  * Args:
  *   dir: Directory to digest recursively (absent dir digests as empty).
  *
  * Returns:
- *   Lowercase hex SHA-256 over `path + NUL + content + NUL` per file.
+ *   Lowercase hex SHA-256.
  */
 export function bundleDigest(dir) {
-    const files = [];
+    const entries = [];
     const walk = (rel) => {
-        for (const entry of fs.readdirSync(path.join(dir, rel), { withFileTypes: true })) {
-            if (entry.name === "node_modules" || entry.name === BUNDLE_MARKER_NAME)
+        for (const name of fs.readdirSync(path.join(dir, rel))) {
+            if (name === "node_modules" || (!rel && UNSTAGED_ENTRIES.has(name)))
                 continue;
-            const childRel = rel ? `${rel}/${entry.name}` : entry.name;
-            if (entry.isDirectory())
+            const childRel = rel ? `${rel}/${name}` : name;
+            const abs = path.join(dir, childRel);
+            const stat = fs.lstatSync(abs);
+            if (!stat.isFile() && !stat.isDirectory() && !stat.isSymbolicLink())
+                continue;
+            entries.push({ rel: childRel, abs, stat });
+            if (stat.isDirectory())
                 walk(childRel);
-            else if (entry.isFile())
-                files.push(childRel);
         }
     };
     if (fs.existsSync(dir))
         walk("");
-    files.sort();
+    entries.sort((a, b) => (a.rel < b.rel ? -1 : a.rel > b.rel ? 1 : 0));
     const hash = crypto.createHash("sha256");
-    for (const rel of files) {
-        hash.update(rel, "utf-8");
-        hash.update("\0");
-        hash.update(fs.readFileSync(path.join(dir, rel)));
+    for (const { rel, abs, stat } of entries) {
+        const type = stat.isSymbolicLink() ? "l" : stat.isDirectory() ? "d" : "f";
+        // Windows has no exec bits and symlink permissions carry no meaning.
+        const mode = IS_WINDOWS || type === "l" ? stat.mode & S_IFMT : stat.mode;
+        for (const part of [rel, type, mode.toString(8)]) {
+            hash.update(part, "utf-8");
+            hash.update("\0");
+        }
+        if (type === "f")
+            hash.update(fs.readFileSync(abs));
+        else if (type === "l")
+            hash.update(fs.readlinkSync(abs), "utf-8");
         hash.update("\0");
     }
     return hash.digest("hex");
 }
+/**
+ * Stage a plugin dir into a cache dir unless the marker and the cache's own digest both equal
+ * the plugin digest and the declared deps resolve; `staged` is true for a (would-be) re-stage.
+ */
+export function stagePluginCache(pluginDir, cacheDir, opts) {
+    const digest = bundleDigest(pluginDir);
+    const short = digest.slice(0, 8);
+    const markerFile = path.join(cacheDir, BUNDLE_MARKER_NAME);
+    const marker = fs.existsSync(markerFile) ? fs.readFileSync(markerFile, "utf-8").trim() : null;
+    if (marker === digest && bundleDigest(cacheDir) === marker && missingPluginDeps(cacheDir).length === 0) {
+        return { staged: false, digest, notes: [`plugin cache up to date (bundle ${short})`] };
+    }
+    if (opts.dryRun)
+        return { staged: true, digest, notes: [`Would re-stage the plugin cache at ${cacheDir} (bundle ${short}).`] };
+    fs.rmSync(cacheDir, { recursive: true, force: true });
+    fs.mkdirSync(cacheDir, { recursive: true });
+    const root = path.resolve(pluginDir);
+    const unstaged = (src) => path.basename(src) === "node_modules" || (path.resolve(path.dirname(src)) === root && UNSTAGED_ENTRIES.has(path.basename(src)));
+    fs.cpSync(pluginDir, cacheDir, { recursive: true, force: true, verbatimSymlinks: true, filter: (src) => !unstaged(src) });
+    fs.writeFileSync(markerFile, `${digest}\n`, { encoding: "utf-8", flag: "wx" });
+    return { staged: true, digest, notes: [`Re-staged the plugin cache at ${cacheDir} (bundle ${short}).`] };
+}
+/** Identity of the cache marker file (absent: null); every re-stage writes a new one. */
+export function stageStamp(cacheDir) {
+    const markerFile = path.join(cacheDir, BUNDLE_MARKER_NAME);
+    if (!fs.existsSync(markerFile))
+        return null;
+    const st = fs.lstatSync(markerFile);
+    return `${st.ino}:${st.mtimeMs}:${fs.readFileSync(markerFile, "utf-8").trim()}`;
+}
+export function missingPluginBundles(pluginDir) {
+    return PLUGIN_BUNDLES.filter((f) => !fs.existsSync(path.join(pluginDir, "scripts", f)));
+}
+/** Whether a plugin dir's package.json declares runtime deps, which only Bun installs. */
+export function declaresPluginDeps(dir) {
+    const pkg = readJsonSafe(path.join(dir, "package.json"), {});
+    return Object.keys(pkg.dependencies ?? {}).length > 0;
+}
+/**
+ * Declared plugin deps that do not resolve from `<dir>/node_modules` (upstream
+ * verifyCriticalModules), plus the zod subpaths the worker requires when zod is declared.
+ */
+export function missingPluginDeps(dir) {
+    const pkg = readJsonSafe(path.join(dir, "package.json"), {});
+    const deps = Object.keys(pkg.dependencies ?? {});
+    const nm = path.join(dir, "node_modules");
+    const missing = deps.filter((dep) => !fs.existsSync(path.join(nm, dep, "package.json")));
+    if (deps.includes("zod")) {
+        for (const sub of ["v3", "v4", "v4-mini"]) {
+            if (!fs.existsSync(path.join(nm, "zod", sub)))
+                missing.push(`zod/${sub}`);
+        }
+    }
+    return missing;
+}
+/** Install a staged cache's runtime deps (the hooks run from there); throws when one stays missing. */
+export function installPluginDeps(dir, bunPath) {
+    const r = spawnSync(bunPath, ["install", "--ignore-scripts"], { cwd: dir, stdio: "inherit", windowsHide: true, env: process.env });
+    if (r.error)
+        throw new Error(`bun install (plugin deps) failed: ${r.error.message}`);
+    if (r.status !== 0)
+        throw new Error(`bun install (plugin deps) failed (exit ${r.status})`);
+    const missing = missingPluginDeps(dir);
+    if (missing.length > 0)
+        throw new Error(`plugin deps missing after install in ${dir}: ${missing.join(", ")}`);
+}
 function probeTool(command, commonPaths) {
     const candidates = [command, ...commonPaths];
     for (const candidate of candidates) {
@@ -137,7 +213,7 @@ function probeTool(command, commonPaths) {
         try {
             const r = spawnSync(candidate, ["--version"], { encoding: "utf-8", stdio: ["ignore", "pipe", "ignore"], windowsHide: true });
             if (r.status === 0) {
-                // "1.3.14" (bun) or "uv 0.9.2 (hash date)" -> first semver-looking token.
+                // "1.3.14" or "tool 0.9.2 (hash date)" -> first semver-looking token.
                 const semver = r.stdout.match(/\d+\.\d+(?:\.\d+)?/);
                 return { path: candidate, version: semver ? semver[0] : r.stdout.trim() };
             }
@@ -161,31 +237,17 @@ export function probeBun() {
         : [path.join(home, ".bun", "bin", "bun"), "/usr/local/bin/bun", "/opt/homebrew/bin/bun", "/home/linuxbrew/.linuxbrew/bin/bun"];
     return probeTool("bun", common);
 }
-/**
- * Probe uv (Chroma vector store runtime; upstream setup-runtime getUvPath).
- *
- * Returns:
- *   Path + version, or nulls when absent.
- */
-export function probeUv() {
-    const home = os.homedir();
-    const common = IS_WINDOWS
-        ? [path.join(home, ".local", "bin", "uv.exe"), path.join(home, ".cargo", "bin", "uv.exe")]
-        : [path.join(home, ".local", "bin", "uv"), path.join(home, ".cargo", "bin", "uv"), "/usr/local/bin/uv", "/opt/homebrew/bin/uv"];
-    return probeTool("uv", common);
-}
 /**
  * Whether an upstream registration (UPSTREAM_PLUGIN_KEY) is still live: present in
- * installed_plugins.json, or enabledPlugins carries it at a value other than `false`. Once a
- * migration sets it to `false`, later `registerHooks` runs see it as already migrated and skip
- * the backup/disable branch (idempotent on re-run).
+ * installed_plugins.json, or enabledPlugins carries it at a value other than `false`. Read-only:
+ * doctor warns on it and the data copy refuses while it is live.
  *
  * Args:
  *   installed: Parsed installed_plugins.json (or `{}` when absent).
  *   settings: Parsed settings.json (or `{}` when absent).
  *
  * Returns:
- *   True when the upstream key still needs disabling.
+ *   True when the upstream plugin may still load beside free-mem.
  */
 export function isUpstreamRegistered(installed, settings) {
     if (settings.enabledPlugins?.[UPSTREAM_PLUGIN_KEY] === false)
@@ -212,12 +274,36 @@ function writeJsonAtomic(file, value) {
     fs.writeFileSync(tmp, JSON.stringify(value, null, 2) + "\n", "utf-8");
     fs.renameSync(tmp, file);
 }
-function writeInstallMarker(dir, version, bun, uv) {
+/** 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 });
-    fs.writeFileSync(marker, JSON.stringify({ version, bun, uv, installedAt: new Date().toISOString() }));
+    fs.rmSync(marker, { force: true });
+    fs.writeFileSync(marker, JSON.stringify({ version, bun, uv: "unused", installedAt: new Date().toISOString() }), { flag: "wx" });
     return marker;
 }
+const PLUGIN_SEMVER = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/;
+/**
+ * Version from a plugin dir's manifest ("0.0.0" when absent). The version names a cache
+ * directory that staging removes, so an empty or path-like value must never reach a path.
+ *
+ * Args:
+ *   pluginDir: Plugin directory holding `.claude-plugin/plugin.json`.
+ *
+ * Returns:
+ *   The semver version.
+ *
+ * Raises:
+ *   Error: When the manifest version is not a semver version.
+ */
+export function pluginVersion(pluginDir) {
+    const manifest = path.join(pluginDir, ".claude-plugin", "plugin.json");
+    const version = readJsonSafe(manifest, {}).version ?? "0.0.0";
+    if (typeof version !== "string" || !PLUGIN_SEMVER.test(version)) {
+        throw new Error(`plugin version ${JSON.stringify(version)} in ${manifest} is not a semver version; refusing to stage the plugin cache`);
+    }
+    return version;
+}
 /** MemoryPort implementation backed by the vendored claude-mem plugin build. */
 export class VendoredMemory {
     engineDir;
@@ -237,15 +323,13 @@ export class VendoredMemory {
     }
     /** Plugin version from the vendored manifest (upstream readPluginVersion). */
     version() {
-        const manifest = path.join(this.pluginDir, ".claude-plugin", "plugin.json");
-        const parsed = readJsonSafe(manifest, {});
-        return parsed.version ?? "0.0.0";
+        return pluginVersion(this.pluginDir);
     }
     result() {
         return { capabilityId: CAPABILITY_ID, target: this.target, written: [], actions: [], notes: [] };
     }
     /**
-     * Probe Bun and uv; instruct when missing. Never installs them (user's machine).
+     * Probe Bun; instruct when missing. Never installs it (user's machine).
      *
      * Returns:
      *   Notes only. A missing Bun is reported as "MISSING" and blocks install().
@@ -253,11 +337,7 @@ export class VendoredMemory {
     async ensurePrerequisites(_ctx) {
         const res = this.result();
         const bun = probeBun();
-        const uv = probeUv();
         res.notes.push(bun.path ? `Bun ${bun.version} found (${bun.path}).` : "MISSING: Bun — install from https://bun.sh (curl -fsSL https://bun.sh/install | bash), then re-run.");
-        res.notes.push(uv.path
-            ? `uv ${uv.version} found (${uv.path}).`
-            : "MISSING: uv — Chroma vector search needs it at runtime (https://docs.astral.sh/uv). Install is not blocked; recall degrades to SQLite-only until uv is present.");
         return res;
     }
     /**
@@ -274,7 +354,6 @@ export class VendoredMemory {
             res.notes.push("Install skipped: Bun is required to build the plugin and to run its hooks.");
             return res;
         }
-        const uv = probeUv();
         const scriptsDir = path.join(this.pluginDir, "scripts");
         const marketplacePlugin = path.join(P.marketplaceDir, "plugin");
         // 1. Build (bun install once, then build:plugin).
@@ -282,8 +361,7 @@ export class VendoredMemory {
             res.notes.push(`Would build the plugin bundles: bun run build:plugin (in ${this.engineDir}).`);
         }
         else {
-            const bundles = ["bun-runner.js", "worker-service.cjs", "mcp-server.cjs"];
-            const reuse = process.env.FREEHARNESS_MEMORY_SKIP_BUILD === "1" && bundles.every((f) => fs.existsSync(path.join(scriptsDir, f)));
+            const reuse = process.env.FREEHARNESS_MEMORY_SKIP_BUILD === "1" && missingPluginBundles(this.pluginDir).length === 0;
             if (reuse) {
                 res.notes.push(`Reused the built plugin bundles in ${scriptsDir} (FREEHARNESS_MEMORY_SKIP_BUILD=1).`);
             }
@@ -291,34 +369,17 @@ export class VendoredMemory {
                 if (!fs.existsSync(path.join(this.engineDir, "node_modules")))
                     this.run(bun.path, ["install"], this.engineDir, "bun install (engine)");
                 this.run(bun.path, ["run", "build:plugin"], this.engineDir, "bun run build:plugin");
-                for (const f of bundles) {
-                    if (!fs.existsSync(path.join(scriptsDir, f)))
-                        throw new Error(`build:plugin did not produce ${f}`);
-                }
+                for (const f of missingPluginBundles(this.pluginDir))
+                    throw new Error(`build:plugin did not produce ${f}`);
                 res.notes.push(`Built plugin bundles v${version} into ${scriptsDir}.`);
             }
         }
-        // 2. copyPluginToCache: rm + cp plugin/ -> cache/<owner>/<name>/<version>/, skipped
-        // when the cache already holds this exact bundle (bundle.sha256 marker matches) AND
-        // its runtime deps still resolve; a matching marker over a broken or partial
-        // node_modules takes the full re-stage path instead of being reported healthy.
-        const digest = bundleDigest(this.pluginDir);
-        const markerFile = path.join(P.cacheDir, BUNDLE_MARKER_NAME);
-        const markerMatches = fs.existsSync(P.cacheDir) && fs.existsSync(markerFile) && fs.readFileSync(markerFile, "utf-8").trim() === digest;
-        const cacheUpToDate = markerMatches && fs.existsSync(path.join(P.cacheDir, "node_modules")) && this.missingPluginDeps(P.cacheDir).length === 0;
+        // 2. copyPluginToCache: rm + cp plugin/ -> cache/<owner>/<name>/<version>/, skipped when
+        // the cache already holds this exact bundle; a broken node_modules takes the re-stage path.
+        const stage = stagePluginCache(this.pluginDir, P.cacheDir, { dryRun: ctx.dryRun });
+        const cacheUpToDate = !stage.staged;
         res.written.push(P.cacheDir);
-        if (cacheUpToDate) {
-            res.notes.push(`plugin cache up to date (bundle ${digest.slice(0, 8)})`);
-        }
-        else if (ctx.dryRun) {
-            res.notes.push(`Would re-stage the plugin cache at ${P.cacheDir} (bundle ${digest.slice(0, 8)}).`);
-        }
-        else {
-            fs.rmSync(P.cacheDir, { recursive: true, force: true });
-            fs.mkdirSync(P.cacheDir, { recursive: true });
-            fs.cpSync(this.pluginDir, P.cacheDir, { recursive: true, force: true, filter: (src) => path.basename(src) !== "node_modules" });
-            fs.writeFileSync(markerFile, `${digest}\n`, "utf-8");
-        }
+        res.notes.push(...stage.notes);
         // 3. copyPluginToMarketplace: plugin/ + marketplace manifest + package bits.
         res.written.push(marketplacePlugin);
         if (!ctx.dryRun) {
@@ -343,8 +404,7 @@ export class VendoredMemory {
             res.notes.push(`Would install plugin runtime deps in ${P.cacheDir} (bun install --ignore-scripts).`);
         }
         else {
-            this.run(bun.path, ["install", "--ignore-scripts"], P.cacheDir, "bun install (plugin deps)");
-            this.verifyPluginDeps(P.cacheDir);
+            installPluginDeps(P.cacheDir, bun.path);
             res.notes.push("Plugin runtime deps installed (zod resolvable from plugin/node_modules).");
         }
         // 5. Install markers (cache + marketplace + marketplace/plugin, as upstream); the
@@ -353,11 +413,11 @@ export class VendoredMemory {
         for (const dir of [P.marketplaceDir, marketplacePlugin]) {
             res.written.push(path.join(dir, ".install-version"));
             if (!ctx.dryRun)
-                writeInstallMarker(dir, version, bun.version ?? "unknown", uv.version ?? "unknown");
+                writeInstallMarker(dir, version, bun.version ?? "unknown");
         }
         res.written.push(path.join(P.cacheDir, ".install-version"));
         if (!cacheUpToDate && !ctx.dryRun)
-            writeInstallMarker(P.cacheDir, version, bun.version ?? "unknown", uv.version ?? "unknown");
+            writeInstallMarker(P.cacheDir, version, bun.version ?? "unknown");
         res.notes.push(`Plugin v${version} staged at ${P.cacheDir} (marketplace: ${P.marketplaceDir}).`);
         return res;
     }
@@ -365,30 +425,13 @@ export class VendoredMemory {
      * Register the plugin with Claude Code (upstream registerMarketplace / registerPlugin /
      * enablePluginInClaudeSettings). All three writes are additive merges: other
      * marketplaces, plugins, hooks and settings keys are preserved byte-for-byte in shape.
-     *
-     * When an upstream registration (UPSTREAM_PLUGIN_KEY) is found (installed_plugins.json
-     * or a still-true enabledPlugins entry), this also backs up the three files below with a
-     * shared timestamp before the first write and disables (never deletes) the old key; the
-     * old cache directory is left in place for `freeharness cleanup` to offer later.
+     * An upstream registration (UPSTREAM_PLUGIN_KEY) is never written: doctor warns about it.
      */
     async registerHooks(_scope, ctx) {
         const res = this.result();
         const version = this.version();
         const P = claudePluginPaths(version);
         const now = new Date().toISOString();
-        const installedBefore = readJsonSafe(P.installedPlugins, {});
-        const settingsBefore = readJsonSafe(P.settings, {});
-        const migrating = isUpstreamRegistered(installedBefore, settingsBefore);
-        if (migrating && !ctx.dryRun) {
-            const stamp = now.replace(/[:.]/g, "-");
-            for (const f of [P.installedPlugins, P.knownMarketplaces, P.settings]) {
-                if (!fs.existsSync(f))
-                    continue;
-                const backup = `${f}.${stamp}.bak`;
-                fs.copyFileSync(f, backup);
-                res.written.push(backup);
-            }
-        }
         // known_marketplaces.json: { "<owner>": { source, installLocation, lastUpdated, autoUpdate } }
         const known = readJsonSafe(P.knownMarketplaces, {});
         known[MARKETPLACE_OWNER] = {
@@ -401,8 +444,6 @@ export class VendoredMemory {
         if (!ctx.dryRun)
             writeJsonAtomic(P.knownMarketplaces, known);
         // installed_plugins.json: { version: 2, plugins: { "<name>@<owner>": [ {scope, installPath, version, installedAt, lastUpdated} ] } }
-        // The upstream entry (if any) is never removed here: invariant 3 forbids deleting a
-        // foreign key, and the cache directory it points at stays reachable for a rollback.
         const installed = readJsonSafe(P.installedPlugins, {});
         if (!installed.version)
             installed.version = 2;
@@ -412,49 +453,21 @@ export class VendoredMemory {
         res.written.push(P.installedPlugins);
         if (!ctx.dryRun)
             writeJsonAtomic(P.installedPlugins, installed);
-        // settings.json: enabledPlugins[PLUGIN_KEY] = true (everything else kept); migrating
-        // also sets enabledPlugins[UPSTREAM_PLUGIN_KEY] = false so Claude Code stops loading it.
+        // settings.json: enabledPlugins[PLUGIN_KEY] = true (everything else kept).
         const settings = readJsonSafe(P.settings, {});
         if (!settings.enabledPlugins)
             settings.enabledPlugins = {};
         const already = settings.enabledPlugins[PLUGIN_KEY] === true;
         settings.enabledPlugins[PLUGIN_KEY] = true;
-        if (migrating)
-            settings.enabledPlugins[UPSTREAM_PLUGIN_KEY] = false;
         res.written.push(P.settings);
         if (!ctx.dryRun)
             writeJsonAtomic(P.settings, settings);
-        if (migrating) {
-            res.notes.push(ctx.dryRun
-                ? `Would migrate from ${UPSTREAM_PLUGIN_KEY}: back up installed_plugins.json, known_marketplaces.json and settings.json before writing, register ${PLUGIN_KEY} v${version}, and set enabledPlugins["${UPSTREAM_PLUGIN_KEY}"] to false. The old cache directory is left in place.`
-                : `Migrated from ${UPSTREAM_PLUGIN_KEY}: backed up installed_plugins.json, known_marketplaces.json and settings.json before the first write, registered ${PLUGIN_KEY} v${version}, and set enabledPlugins["${UPSTREAM_PLUGIN_KEY}"] to false. The old cache directory is left in place.`);
-        }
-        else {
-            res.notes.push(`${ctx.dryRun ? "Would register" : "Registered"} plugin ${PLUGIN_KEY} v${version}: marketplace + installed_plugins + enabledPlugins (additive)${already ? "; was already enabled" : ""}.`);
-        }
+        res.notes.push(`${ctx.dryRun ? "Would register" : "Registered"} plugin ${PLUGIN_KEY} v${version}: marketplace + installed_plugins + enabledPlugins (additive)${already ? "; was already enabled" : ""}.`);
         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;
     }
-    /**
-     * Keep an existing ~/.claude-mem data directory from a delegated install. The
-     * plugin resolves it by convention (CLAUDE_MEM_DATA_DIR or ~/.claude-mem), so no
-     * write is needed and nothing is deleted.
-     */
     async migrateExisting(_ctx) {
-        const res = this.result();
-        const dataDir = process.env.CLAUDE_MEM_DATA_DIR || path.join(os.homedir(), ".claude-mem");
-        if (!fs.existsSync(dataDir)) {
-            res.notes.push(`No existing claude-mem data dir at ${dataDir}; the worker creates it on first start.`);
-            return res;
-        }
-        const db = path.join(dataDir, "claude-mem.db");
-        const settings = readJsonSafe(path.join(dataDir, "settings.json"), {});
-        const redirected = typeof settings.CLAUDE_MEM_DATA_DIR === "string" ? settings.CLAUDE_MEM_DATA_DIR : null;
-        res.notes.push(`Existing claude-mem data kept at ${dataDir}${fs.existsSync(db) ? " (claude-mem.db present)" : ""}; the vendored plugin reads it by convention${redirected ? ` (settings redirect data to ${redirected})` : ""}. Nothing deleted.`);
-        const legacyMarker = path.join(dataDir, ".install-version");
-        if (fs.existsSync(legacyMarker))
-            res.notes.push("A legacy install marker exists in the data dir; the plugin markers now live in the plugin cache.");
-        return res;
+        return this.result();
     }
     run(cmd, args, cwd, label) {
         const r = spawnSync(cmd, args, { cwd, stdio: "inherit", windowsHide: true, env: process.env });
@@ -463,25 +476,4 @@ export class VendoredMemory {
         if (r.status !== 0)
             throw new Error(`${label} failed (exit ${r.status})`);
     }
-    // upstream verifyCriticalModules: every declared plugin dep must resolve from
-    // plugin/node_modules, plus the zod subpaths the worker bundle requires.
-    missingPluginDeps(dir) {
-        const pkg = readJsonSafe(path.join(dir, "package.json"), {});
-        const nm = path.join(dir, "node_modules");
-        const missing = [];
-        for (const dep of Object.keys(pkg.dependencies ?? {})) {
-            if (!fs.existsSync(path.join(nm, dep, "package.json")))
-                missing.push(dep);
-        }
-        for (const sub of ["v3", "v4", "v4-mini"]) {
-            if (!fs.existsSync(path.join(nm, "zod", sub)))
-                missing.push(`zod/${sub}`);
-        }
-        return missing;
-    }
-    verifyPluginDeps(dir) {
-        const missing = this.missingPluginDeps(dir);
-        if (missing.length > 0)
-            throw new Error(`plugin deps missing after install in ${dir}: ${missing.join(", ")}`);
-    }
 }