freeharness 0.4.1

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

@@ -0,0 +1,150 @@
+import type { AdapterResult, ExecStep, InstallContext, Scope } from "@freeharness/core";
+import type { HarnessTarget } from "@freeharness/core";
+import type { MemoryPort } from "@freeharness/core";
+export declare const MARKETPLACE_OWNER = "freeharness";
+export declare const PLUGIN_NAME = "free-mem";
+export declare const PLUGIN_KEY = "free-mem@freeharness";
+/** The upstream marketplace owner (thedotmack/claude-mem), detected for the disable-only migration. */
+export declare const UPSTREAM_MARKETPLACE_OWNER = "thedotmack";
+/** The upstream plugin name; never used for our own registration, only upstream detection. */
+export declare const UPSTREAM_PLUGIN_NAME = "claude-mem";
+export declare const UPSTREAM_PLUGIN_KEY = "claude-mem@thedotmack";
+/**
+ * Locate the vendored claude-mem engine next to the canonical directory.
+ *
+ * Args:
+ *   canonicalDir: The resolved FreeHarness canonical directory (packages/cli/canonical).
+ *
+ * Returns:
+ *   Absolute engine path, or null when the vendored tree is absent (npx bridge).
+ */
+export declare function vendoredMemoryEngineDir(canonicalDir: string): string | null;
+/**
+ * Build step for harness adapters that only stage the build (OpenCode bridge path).
+ *
+ * Args:
+ *   engineDir: Absolute path of the vendored engine.
+ *
+ * Returns:
+ *   Gated ExecSteps that build the plugin bundles with Bun.
+ */
+export declare function memoryBuildActions(engineDir: string): ExecStep[];
+/** Claude Code config/plugin paths (upstream utils/paths.ts), honoring CLAUDE_CONFIG_DIR. */
+export interface ClaudePluginPaths {
+    configDir: string;
+    pluginsDir: string;
+    knownMarketplaces: string;
+    installedPlugins: string;
+    settings: string;
+    marketplaceDir: string;
+    cacheDir: string;
+}
+/**
+ * Resolve the Claude Code plugin paths for a plugin version.
+ *
+ * Args:
+ *   version: The plugin version (cache directory leaf).
+ *
+ * Returns:
+ *   The path set mirrored from upstream utils/paths.ts.
+ */
+export declare function claudePluginPaths(version: string): ClaudePluginPaths;
+/**
+ * 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.
+ *
+ * Args:
+ *   dir: Directory to digest recursively (absent dir digests as empty).
+ *
+ * Returns:
+ *   Lowercase hex SHA-256 over `path + NUL + content + NUL` per file.
+ */
+export declare function bundleDigest(dir: string): string;
+/** Probe result for one runtime tool. */
+export interface ToolProbe {
+    path: string | null;
+    version: string | null;
+}
+/**
+ * Probe Bun (upstream setup-runtime getBunPath: PATH first, then common install dirs).
+ *
+ * Returns:
+ *   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).
+ *
+ * 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.
+ */
+export declare function isUpstreamRegistered(installed: {
+    plugins?: Record<string, unknown>;
+}, settings: {
+    enabledPlugins?: Record<string, boolean>;
+}): boolean;
+/** MemoryPort implementation backed by the vendored claude-mem plugin build. */
+export declare class VendoredMemory implements MemoryPort {
+    readonly engineDir: string;
+    readonly vendorDir: string;
+    readonly pluginDir: string;
+    private readonly target;
+    /**
+     * Args:
+     *   engineDir: Absolute path of packages/memory/vendor/claude-mem/engine.
+     *   target: The harness this install is for (reported in results).
+     */
+    constructor(engineDir: string, target?: HarnessTarget);
+    /** Plugin version from the vendored manifest (upstream readPluginVersion). */
+    version(): string;
+    private result;
+    /**
+     * Probe Bun and uv; instruct when missing. Never installs them (user's machine).
+     *
+     * Returns:
+     *   Notes only. A missing Bun is reported as "MISSING" and blocks install().
+     */
+    ensurePrerequisites(_ctx: InstallContext): Promise<AdapterResult>;
+    /**
+     * Build the plugin bundles and stage the plugin in the Claude Code plugin cache
+     * and marketplace directories (upstream copyPluginToCache / copyPluginToMarketplace
+     * / installPluginDependencies / writeInstallMarker).
+     */
+    install(_scope: Scope, ctx: InstallContext): Promise<AdapterResult>;
+    /**
+     * 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.
+     */
+    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

@@ -0,0 +1,487 @@
+// 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:
+//
+//   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).
+//
+// 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).
+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";
+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";
+export const MARKETPLACE_OWNER = "freeharness";
+export const PLUGIN_NAME = "free-mem";
+export const PLUGIN_KEY = `${PLUGIN_NAME}@${MARKETPLACE_OWNER}`;
+/** The upstream marketplace owner (thedotmack/claude-mem), detected for the disable-only migration. */
+export const UPSTREAM_MARKETPLACE_OWNER = "thedotmack";
+/** The upstream plugin name; never used for our own registration, only upstream detection. */
+export const UPSTREAM_PLUGIN_NAME = "claude-mem";
+export const UPSTREAM_PLUGIN_KEY = `${UPSTREAM_PLUGIN_NAME}@${UPSTREAM_MARKETPLACE_OWNER}`;
+const CAPABILITY_ID = "memory";
+/**
+ * Locate the vendored claude-mem engine next to the canonical directory.
+ *
+ * Args:
+ *   canonicalDir: The resolved FreeHarness canonical directory (packages/cli/canonical).
+ *
+ * Returns:
+ *   Absolute engine path, or null when the vendored tree is absent (npx bridge).
+ */
+export function vendoredMemoryEngineDir(canonicalDir) {
+    const engineDir = path.join(canonicalDir, "..", "..", "memory", "vendor", UPSTREAM_PLUGIN_NAME, "engine");
+    return fs.existsSync(path.join(engineDir, "package.json")) ? path.resolve(engineDir) : null;
+}
+/**
+ * Build step for harness adapters that only stage the build (OpenCode bridge path).
+ *
+ * Args:
+ *   engineDir: Absolute path of the vendored engine.
+ *
+ * Returns:
+ *   Gated ExecSteps that build the plugin bundles with Bun.
+ */
+export function memoryBuildActions(engineDir) {
+    return [
+        {
+            description: "Build the vendored claude-mem plugin bundles (worker, mcp, context, watcher) with Bun",
+            command: "bun install && bun run build:plugin",
+            cwd: engineDir,
+            optional: true,
+        },
+    ];
+}
+/**
+ * Resolve the Claude Code plugin paths for a plugin version.
+ *
+ * Args:
+ *   version: The plugin version (cache directory leaf).
+ *
+ * Returns:
+ *   The path set mirrored from upstream utils/paths.ts.
+ */
+export function claudePluginPaths(version) {
+    const configDir = process.env.CLAUDE_CONFIG_DIR || path.join(os.homedir(), ".claude");
+    const pluginsDir = path.join(configDir, "plugins");
+    return {
+        configDir,
+        pluginsDir,
+        knownMarketplaces: path.join(pluginsDir, "known_marketplaces.json"),
+        installedPlugins: path.join(pluginsDir, "installed_plugins.json"),
+        settings: path.join(configDir, "settings.json"),
+        marketplaceDir: path.join(pluginsDir, "marketplaces", MARKETPLACE_OWNER),
+        cacheDir: path.join(pluginsDir, "cache", MARKETPLACE_OWNER, PLUGIN_NAME, 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.
+ *
+ * Args:
+ *   dir: Directory to digest recursively (absent dir digests as empty).
+ *
+ * Returns:
+ *   Lowercase hex SHA-256 over `path + NUL + content + NUL` per file.
+ */
+export function bundleDigest(dir) {
+    const files = [];
+    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)
+                continue;
+            const childRel = rel ? `${rel}/${entry.name}` : entry.name;
+            if (entry.isDirectory())
+                walk(childRel);
+            else if (entry.isFile())
+                files.push(childRel);
+        }
+    };
+    if (fs.existsSync(dir))
+        walk("");
+    files.sort();
+    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)));
+        hash.update("\0");
+    }
+    return hash.digest("hex");
+}
+function probeTool(command, commonPaths) {
+    const candidates = [command, ...commonPaths];
+    for (const candidate of candidates) {
+        if (candidate !== command && !fs.existsSync(candidate))
+            continue;
+        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.
+                const semver = r.stdout.match(/\d+\.\d+(?:\.\d+)?/);
+                return { path: candidate, version: semver ? semver[0] : r.stdout.trim() };
+            }
+        }
+        catch {
+            // try the next candidate
+        }
+    }
+    return { path: null, version: null };
+}
+/**
+ * Probe Bun (upstream setup-runtime getBunPath: PATH first, then common install dirs).
+ *
+ * Returns:
+ *   Path + version, or nulls when absent.
+ */
+export function probeBun() {
+    const home = os.homedir();
+    const common = IS_WINDOWS
+        ? [path.join(home, ".bun", "bin", "bun.exe")]
+        : [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).
+ *
+ * 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.
+ */
+export function isUpstreamRegistered(installed, settings) {
+    if (settings.enabledPlugins?.[UPSTREAM_PLUGIN_KEY] === false)
+        return false;
+    if (settings.enabledPlugins?.[UPSTREAM_PLUGIN_KEY] === true)
+        return true;
+    return Boolean(installed.plugins?.[UPSTREAM_PLUGIN_KEY]);
+}
+function readJsonSafe(file, fallback) {
+    if (!fs.existsSync(file))
+        return fallback;
+    const raw = fs.readFileSync(file, "utf-8").replace(/^\uFEFF/, "");
+    try {
+        return JSON.parse(raw);
+    }
+    catch (err) {
+        throw new Error(`Corrupt JSON file, refusing to overwrite: ${file}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+// Atomic write (temp + rename), as upstream shared/atomic-json.ts does.
+function writeJsonAtomic(file, value) {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    const tmp = `${file}.${process.pid}.${Date.now()}.tmp`;
+    fs.writeFileSync(tmp, JSON.stringify(value, null, 2) + "\n", "utf-8");
+    fs.renameSync(tmp, file);
+}
+function writeInstallMarker(dir, version, bun, uv) {
+    const marker = path.join(dir, ".install-version");
+    fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(marker, JSON.stringify({ version, bun, uv, installedAt: new Date().toISOString() }));
+    return marker;
+}
+/** MemoryPort implementation backed by the vendored claude-mem plugin build. */
+export class VendoredMemory {
+    engineDir;
+    vendorDir;
+    pluginDir;
+    target;
+    /**
+     * Args:
+     *   engineDir: Absolute path of packages/memory/vendor/claude-mem/engine.
+     *   target: The harness this install is for (reported in results).
+     */
+    constructor(engineDir, target = "claude-code") {
+        this.engineDir = engineDir;
+        this.vendorDir = path.resolve(engineDir, "..");
+        this.pluginDir = path.join(this.vendorDir, "plugin");
+        this.target = target;
+    }
+    /** 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";
+    }
+    result() {
+        return { capabilityId: CAPABILITY_ID, target: this.target, written: [], actions: [], notes: [] };
+    }
+    /**
+     * Probe Bun and uv; instruct when missing. Never installs them (user's machine).
+     *
+     * Returns:
+     *   Notes only. A missing Bun is reported as "MISSING" and blocks install().
+     */
+    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;
+    }
+    /**
+     * Build the plugin bundles and stage the plugin in the Claude Code plugin cache
+     * and marketplace directories (upstream copyPluginToCache / copyPluginToMarketplace
+     * / installPluginDependencies / writeInstallMarker).
+     */
+    async install(_scope, ctx) {
+        const res = this.result();
+        const version = this.version();
+        const P = claudePluginPaths(version);
+        const bun = probeBun();
+        if (!bun.path) {
+            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).
+        if (ctx.dryRun) {
+            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)));
+            if (reuse) {
+                res.notes.push(`Reused the built plugin bundles in ${scriptsDir} (FREEHARNESS_MEMORY_SKIP_BUILD=1).`);
+            }
+            else {
+                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}`);
+                }
+                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;
+        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");
+        }
+        // 3. copyPluginToMarketplace: plugin/ + marketplace manifest + package bits.
+        res.written.push(marketplacePlugin);
+        if (!ctx.dryRun) {
+            fs.mkdirSync(P.marketplaceDir, { recursive: true });
+            fs.rmSync(marketplacePlugin, { recursive: true, force: true });
+            fs.cpSync(this.pluginDir, marketplacePlugin, { recursive: true, force: true, filter: (src) => path.basename(src) !== "node_modules" });
+            for (const entry of [".claude-plugin", "PROVENANCE.yaml", "FIXUP.md"]) {
+                const src = path.join(this.vendorDir, entry);
+                if (!fs.existsSync(src))
+                    continue;
+                const dst = path.join(P.marketplaceDir, entry);
+                fs.rmSync(dst, { recursive: true, force: true });
+                fs.cpSync(src, dst, { recursive: true, force: true });
+            }
+        }
+        // 4. installPluginDependencies in the cache dir (the hooks run from there); skipped
+        // with the copy when the cache already matches the bundle digest.
+        if (cacheUpToDate) {
+            res.notes.push(`Plugin runtime deps already staged in ${P.cacheDir}.`);
+        }
+        else if (ctx.dryRun) {
+            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);
+            res.notes.push("Plugin runtime deps installed (zod resolvable from plugin/node_modules).");
+        }
+        // 5. Install markers (cache + marketplace + marketplace/plugin, as upstream); the
+        // cache marker is rewritten only when the cache itself was re-staged, so an unchanged
+        // bundle leaves every file under the cache directory untouched.
+        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");
+        }
+        res.written.push(path.join(P.cacheDir, ".install-version"));
+        if (!cacheUpToDate && !ctx.dryRun)
+            writeInstallMarker(P.cacheDir, version, bun.version ?? "unknown", uv.version ?? "unknown");
+        res.notes.push(`Plugin v${version} staged at ${P.cacheDir} (marketplace: ${P.marketplaceDir}).`);
+        return res;
+    }
+    /**
+     * 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.
+     */
+    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] = {
+            source: { source: "github", repo: `${MARKETPLACE_OWNER}/${PLUGIN_NAME}` },
+            installLocation: P.marketplaceDir,
+            lastUpdated: now,
+            autoUpdate: false, // our build is the source of truth; never let CC pull upstream over it
+        };
+        res.written.push(P.knownMarketplaces);
+        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;
+        if (!installed.plugins)
+            installed.plugins = {};
+        installed.plugins[PLUGIN_KEY] = [{ scope: "user", installPath: P.cacheDir, version, installedAt: now, lastUpdated: now }];
+        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.
+        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("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;
+    }
+    run(cmd, args, cwd, label) {
+        const r = spawnSync(cmd, args, { cwd, stdio: "inherit", windowsHide: true, env: process.env });
+        if (r.error)
+            throw new Error(`${label} failed: ${r.error.message}`);
+        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(", ")}`);
+    }
+}

package/dist/adapters/package/node.d.ts

@@ -0,0 +1,9 @@
+import type { ExecStep } from "@freeharness/core";
+import type { PackagePort } from "@freeharness/core";
+export declare class NodePackage implements PackagePort {
+    isPresent(tool: string): Promise<boolean>;
+    exec(step: ExecStep): Promise<{
+        ok: boolean;
+        code: number;
+    }>;
+}

package/dist/adapters/package/node.js

@@ -0,0 +1,20 @@
+// PackagePort adapter: probe tools and run side-effecting steps via the shell.
+// Commands are FreeHarness-constructed (not user input); run through `sh -c` with
+// inherited stdio so installs stream their own output.
+import { spawn } from "node:child_process";
+export class NodePackage {
+    async isPresent(tool) {
+        return new Promise((resolve) => {
+            const p = spawn("sh", ["-c", `command -v ${tool}`], { stdio: "ignore" });
+            p.on("close", (code) => resolve(code === 0));
+            p.on("error", () => resolve(false));
+        });
+    }
+    async exec(step) {
+        return new Promise((resolve) => {
+            const p = spawn("sh", ["-c", step.command], { cwd: step.cwd ?? process.cwd(), stdio: "inherit" });
+            p.on("close", (code) => resolve({ ok: code === 0, code: code ?? 1 }));
+            p.on("error", () => resolve({ ok: false, code: 1 }));
+        });
+    }
+}