freeharness 0.4.1 → 0.4.2

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

@@ -0,0 +1,95 @@
+import fs from "node:fs";
+export declare const DISABLE_COMMAND = "claude plugin disable claude-mem@thedotmack";
+export declare const MARKER_NAME = ".migrated-from.json";
+export declare const PARTIAL_PATTERN: RegExp;
+export interface MigrationLink {
+    /** Path relative to the legacy directory. */
+    path: string;
+    target: string;
+    /** True when the target resolves outside the legacy tree, which aborts pass 2. */
+    outside: boolean;
+}
+export interface MigrationPlan {
+    home: string;
+    legacyDir: string;
+    freeDir: string;
+    bytes: number;
+    /** Bytes available on the HOME file system; null when `statfs` is unavailable. */
+    freeBytes: number | null;
+    links: MigrationLink[];
+    /** Leftover `.free-mem.partial-<stamp>` siblings, removed by the next pass 2. */
+    partials: string[];
+    unreadable: string[];
+    /** The WARN that refuses the copy while the upstream plugin is enabled; null otherwise. */
+    refusal: string | null;
+    /**
+     * Claude Code's transcript directory for the legacy observer cwd and the one for the free-mem
+     * observer cwd; set only when the legacy one exists, so a session open across the copy keeps it.
+     */
+    observerMove?: {
+        from: string;
+        to: string;
+    };
+}
+export interface StopResult {
+    /** True when no worker answers and no live pid file remains. */
+    stopped: boolean;
+    wasRunning: boolean;
+    reason?: string;
+}
+export interface SpawnLock {
+    refresh(): void;
+    /** True while the lock file still names this process. */
+    held(): boolean;
+    release(): void;
+}
+export interface MigrationPorts {
+    stopWorker(): Promise<StopResult>;
+    now(): number;
+    /** Null when the copied database passes `PRAGMA quick_check`, else the reason. */
+    integrityCheck(dbFile: string): Promise<string | null> | string | null;
+    version: string;
+    fs?: typeof fs;
+    acquireLock?(lockPath: string): SpawnLock | string;
+    /** The engine breaks a lock older than 90 s, so it is touched well inside that bound. */
+    lockRefreshMs?: number;
+}
+export interface MigrationResult {
+    status: "copied" | "aborted" | "refused";
+    reason?: string;
+    bytes: number;
+    durationMs: number;
+    skipped: string[];
+    warnings: string[];
+    /** True when the stop call stopped a running worker, which the post-install restart owes back. */
+    restartOwed: boolean;
+    /** The outcome line for the observer transcript directory, when the plan has one. */
+    observer?: string;
+}
+/**
+ * Plans the copy of `<home>/.claude-mem` into `<home>/.free-mem`, reading only.
+ * @param home The HOME that holds both directories.
+ * @param env Environment for the data-dir variables and `CLAUDE_CONFIG_DIR`.
+ * @returns The plan, or null when nothing is copied: no legacy directory, `~/.free-mem` exists,
+ *   or a data-dir variable or the legacy settings redirect names a custom directory.
+ */
+export declare function planMemoryMigration(home: string, env: Record<string, string | undefined>): MigrationPlan | null;
+/** 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;
+/** Takes the engine spawn lock with the engine's own `wx` create, so no launcher spawns a worker. */
+export declare function fileSpawnLock(lockPath: string, f: typeof fs, now: () => number): SpawnLock | string;
+/** Runs `PRAGMA quick_check` on a database through `bun -e`; Bun is already an install prerequisite. */
+export declare function bunIntegrityCheck(bunPath: string | null): (dbFile: string) => Promise<string | null>;
+/**
+ * Applies a plan: stop the worker, hold the spawn lock, copy into a sibling, rename the database
+ * trio, rewrite settings, check the copy, recheck the source, write the marker, rename the sibling.
+ * Every failure removes the sibling, so the resolver keeps serving the legacy directory.
+ * @param plan A plan from {@link planMemoryMigration}.
+ * @param ports The stop call, clock, integrity check, version and, for tests, file system and lock.
+ * @returns What happened; never throws.
+ */
+export declare function applyMemoryMigration(plan: MigrationPlan, ports: MigrationPorts): Promise<MigrationResult>;
+/** The pass-1 lines for a plan: the copy with its size and free space, links, leftovers, refusals. */
+export declare function describePlan(plan: MigrationPlan): string[];
+/** The pass-2 lines for an applied plan. */
+export declare function describeResult(plan: MigrationPlan, r: MigrationResult): string[];

package/dist/adapters/memory/migrate.js

@@ -0,0 +1,497 @@
+// Copies a legacy ~/.claude-mem forward into ~/.free-mem once, through a temporary sibling whose
+// rename is the only commit point; the legacy tree is only read, apart from the engine spawn lock.
+import fs from "node:fs";
+import path from "node:path";
+import { execFile } from "node:child_process";
+import { DB_FILENAME, FREE_DIR_NAME, LEGACY_DB_FILENAME, LEGACY_DIR_NAME, resolveMemoryPaths } from "./paths.js";
+const UPSTREAM_KEY = "claude-mem@thedotmack";
+export const DISABLE_COMMAND = `claude plugin disable ${UPSTREAM_KEY}`;
+export const MARKER_NAME = ".migrated-from.json";
+export const PARTIAL_PATTERN = /^\.free-mem\.partial-[0-9TZ]+$/;
+const RUNTIME_FILES = new Set(["worker.pid", ".server-beta.pid", ".server-beta.port", ".server-beta.runtime.json", ".worker-start-attempted", ".worker-clean-shutdown", "spawn.lock"]);
+const LOCK_REFRESH_MS = 30_000;
+const OLD_PREFIX = "CLAUDE_MEM_";
+const NEW_PREFIX = "FREE_MEM_";
+class Abort extends Error {
+}
+function inside(p, root) {
+    return p === root || p.startsWith(root + path.sep);
+}
+function isSkipped(name) {
+    return name === "logs" || RUNTIME_FILES.has(name) || name.endsWith(".lock");
+}
+function readJson(file) {
+    try {
+        return JSON.parse(fs.readFileSync(file, "utf8").replace(/^/, ""));
+    }
+    catch {
+        return {};
+    }
+}
+function upstreamEnabled(configDir) {
+    const settingsFile = path.join(configDir, "settings.json");
+    const enabled = readJson(settingsFile).enabledPlugins?.[UPSTREAM_KEY];
+    if (enabled === false)
+        return null;
+    if (enabled !== true && !readJson(path.join(configDir, "plugins", "installed_plugins.json")).plugins?.[UPSTREAM_KEY])
+        return null;
+    return settingsFile;
+}
+function scanTree(legacyDir) {
+    const out = { bytes: 0, links: [], unreadable: [] };
+    const walk = (rel) => {
+        let names;
+        try {
+            names = fs.readdirSync(path.join(legacyDir, rel));
+        }
+        catch {
+            out.unreadable.push(rel || ".");
+            return;
+        }
+        for (const name of names.sort()) {
+            if (!rel && isSkipped(name))
+                continue;
+            const r = path.join(rel, name);
+            const abs = path.join(legacyDir, r);
+            try {
+                const st = fs.lstatSync(abs);
+                if (st.isSymbolicLink()) {
+                    const target = fs.readlinkSync(abs);
+                    out.links.push({ path: r, target, outside: !inside(path.resolve(path.dirname(abs), target), legacyDir) });
+                }
+                else if (st.isDirectory())
+                    walk(r);
+                else
+                    out.bytes += st.size;
+            }
+            catch {
+                out.unreadable.push(r);
+            }
+        }
+    };
+    walk("");
+    return out;
+}
+function freeSpace(dir) {
+    const statfs = fs.statfsSync;
+    try {
+        return statfs ? Number(statfs(dir).bavail) * Number(statfs(dir).bsize) : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Plans the copy of `<home>/.claude-mem` into `<home>/.free-mem`, reading only.
+ * @param home The HOME that holds both directories.
+ * @param env Environment for the data-dir variables and `CLAUDE_CONFIG_DIR`.
+ * @returns The plan, or null when nothing is copied: no legacy directory, `~/.free-mem` exists,
+ *   or a data-dir variable or the legacy settings redirect names a custom directory.
+ */
+export function planMemoryMigration(home, env) {
+    const resolved = resolveMemoryPaths(env, home);
+    if (resolved.source !== "fallback")
+        return null;
+    const legacyDir = resolved.dataDir;
+    const scan = scanTree(legacyDir);
+    const configDir = env.CLAUDE_CONFIG_DIR || path.join(home, ".claude");
+    const settingsFile = upstreamEnabled(configDir);
+    const refusal = settingsFile
+        ? `${UPSTREAM_KEY} is enabled, and its hooks would start an upstream worker on ${legacyDir} and the same port; the memory data copy is skipped and the rest of the install proceeds. Disable it with \`${DISABLE_COMMAND}\` (or set enabledPlugins["${UPSTREAM_KEY}"] to false in ${settingsFile}), then re-run.`
+        : null;
+    let partials = [];
+    try {
+        partials = fs.readdirSync(home).filter((n) => PARTIAL_PATTERN.test(n)).sort().map((n) => path.join(home, n));
+    }
+    catch {
+        /* an unreadable HOME has no leftovers to list */
+    }
+    const freeDir = path.join(home, FREE_DIR_NAME);
+    const plan = { home, legacyDir, freeDir, bytes: scan.bytes, freeBytes: freeSpace(home), links: scan.links, partials, unreadable: scan.unreadable, refusal };
+    const projects = path.join(configDir, "projects");
+    const from = path.join(projects, projectSlug(path.join(legacyDir, OBSERVER_DIR)));
+    try {
+        fs.lstatSync(from);
+        plan.observerMove = { from, to: path.join(projects, projectSlug(path.join(freeDir, OBSERVER_DIR))) };
+    }
+    catch {
+        /* no legacy transcripts, nothing to move */
+    }
+    return plan;
+}
+const OBSERVER_DIR = "observer-sessions";
+/** Claude Code names a projects directory after its cwd with every non-alphanumeric as `-`. */
+function projectSlug(cwd) {
+    return cwd.replace(/[^A-Za-z0-9]/g, "-");
+}
+/** Renames the legacy transcript directory only when it is a real directory and the target is absent. */
+function moveObserver(f, move) {
+    const keep = (why) => `observer transcripts left in place: ${why}; ${move.from} and ${move.to} both kept, nothing deleted`;
+    try {
+        if (!f.lstatSync(move.from).isDirectory())
+            return keep(`${move.from} is not a real directory`);
+        if (present(f, move.to))
+            return keep(`${move.to} already exists`);
+        f.renameSync(move.from, move.to);
+        return `Moved the observer transcripts from ${move.from} to ${move.to}.`;
+    }
+    catch (e) {
+        return keep(e.message);
+    }
+}
+/** lstat, so a dangling link at the target also counts as present and is never replaced. */
+function present(f, p) {
+    try {
+        f.lstatSync(p);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** 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";
+    }
+}
+function readJsonText(raw) {
+    try {
+        return JSON.parse(raw) ?? {};
+    }
+    catch {
+        return {};
+    }
+}
+/** Takes the engine spawn lock with the engine's own `wx` create, so no launcher spawns a worker. */
+export function fileSpawnLock(lockPath, f, now) {
+    try {
+        f.writeFileSync(lockPath, JSON.stringify({ pid: process.pid, startedAt: new Date(now()).toISOString() }), { flag: "wx" });
+    }
+    catch (e) {
+        const code = e.code;
+        return code === "EEXIST" ? `${lockPath} is held by another launcher; re-run once it is released` : `cannot take ${lockPath}: ${e.message}`;
+    }
+    const held = () => {
+        try {
+            return readJsonText(f.readFileSync(lockPath, "utf8")).pid === process.pid;
+        }
+        catch {
+            return false;
+        }
+    };
+    return {
+        refresh() {
+            const t = new Date(now());
+            f.utimesSync(lockPath, t, t);
+        },
+        held,
+        release() {
+            try {
+                if (held())
+                    f.unlinkSync(lockPath);
+            }
+            catch {
+                /* already gone */
+            }
+        },
+    };
+}
+/** Touches the lock on a timer, which fires only because every long step is asynchronous. */
+function keepFresh(lock, ms) {
+    let lost = null;
+    const timer = setInterval(() => {
+        try {
+            lock.refresh();
+        }
+        catch (e) {
+            lost ??= e.message;
+        }
+    }, ms);
+    return { stop: () => clearInterval(timer), lost: () => lost };
+}
+const QUICK_CHECK = `const { Database } = require("bun:sqlite");
+const db = new Database(process.env.FH_MIGRATE_DB);
+console.log(JSON.stringify(db.query("PRAGMA quick_check").all()));
+db.close();`;
+/** Runs `PRAGMA quick_check` on a database through `bun -e`; Bun is already an install prerequisite. */
+export function bunIntegrityCheck(bunPath) {
+    return (dbFile) => new Promise((resolve) => {
+        if (!bunPath)
+            return resolve(`Bun is not available to run PRAGMA quick_check on ${dbFile}`);
+        const opts = { env: { ...process.env, FH_MIGRATE_DB: dbFile }, encoding: "utf8", windowsHide: true, maxBuffer: 16 * 1024 * 1024 };
+        execFile(bunPath, ["-e", QUICK_CHECK], opts, (err, stdout, stderr) => {
+            const rows = readJsonText(stdout.trim().split("\n").pop() ?? "");
+            if (Array.isArray(rows) && rows.length === 1 && Object.values(rows[0])[0] === "ok")
+                return resolve(null);
+            resolve(`PRAGMA quick_check on ${dbFile} returned ${(stdout || stderr || err?.message || "no output").trim()}`);
+        });
+    });
+}
+function trioState(f, dir) {
+    const state = {};
+    for (const suffix of ["", "-wal", "-shm"]) {
+        const name = LEGACY_DB_FILENAME + suffix;
+        try {
+            const st = f.lstatSync(path.join(dir, name));
+            state[name] = `${st.size}:${st.mtimeMs}`;
+        }
+        catch {
+            state[name] = "absent";
+        }
+    }
+    return state;
+}
+function rebaseString(value, legacyDir, freeDir) {
+    for (const [from, to] of [[legacyDir, freeDir], [`~/${LEGACY_DIR_NAME}`, `~/${FREE_DIR_NAME}`]]) {
+        if (value === from || value.startsWith(from + "/"))
+            return to + value.slice(from.length);
+    }
+    return value;
+}
+function rebaseValues(value, legacyDir, freeDir) {
+    if (typeof value === "string")
+        return rebaseString(value, legacyDir, freeDir);
+    if (Array.isArray(value))
+        return value.map((v) => rebaseValues(v, legacyDir, freeDir));
+    if (value && typeof value === "object")
+        return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, rebaseValues(v, legacyDir, freeDir)]));
+    return value;
+}
+function renameKeys(settings) {
+    const out = {};
+    for (const [key, value] of Object.entries(settings)) {
+        const renamed = key.startsWith(OLD_PREFIX) ? NEW_PREFIX + key.slice(OLD_PREFIX.length) : key;
+        if (renamed !== key && Object.hasOwn(settings, renamed))
+            continue;
+        out[renamed] = value;
+    }
+    return out;
+}
+class Copier {
+    f;
+    plan;
+    skipped = [];
+    warnings = [];
+    constructor(f, plan) {
+        this.f = f;
+        this.plan = plan;
+    }
+    async copyDir(rel, dest) {
+        const src = path.join(this.plan.legacyDir, rel);
+        const mode = this.f.lstatSync(src).mode & 0o7777;
+        this.f.mkdirSync(dest, { mode: 0o700 });
+        for (const name of this.f.readdirSync(src).sort()) {
+            const r = path.join(rel, name);
+            if (!rel && isSkipped(name)) {
+                // A spawn.lock here is the one this copy holds: an existing one refuses the lock.
+                if (name !== "spawn.lock")
+                    this.skipped.push(r);
+                continue;
+            }
+            await this.copyEntry(r, path.join(dest, name));
+        }
+        this.f.chmodSync(dest, mode);
+    }
+    async copyEntry(rel, dest) {
+        const src = path.join(this.plan.legacyDir, rel);
+        const st = this.f.lstatSync(src);
+        if (st.isSymbolicLink()) {
+            const target = this.f.readlinkSync(src);
+            if (!inside(path.resolve(path.dirname(src), target), this.plan.legacyDir))
+                throw new Abort(`symbolic link ${rel} -> ${target} leaves ${this.plan.legacyDir}`);
+            this.f.symlinkSync(path.isAbsolute(target) ? rebaseString(target, this.plan.legacyDir, this.plan.freeDir) : target, dest);
+        }
+        else if (st.isDirectory())
+            await this.copyDir(rel, dest);
+        else if (st.isFile()) {
+            await this.f.promises.copyFile(src, dest);
+            this.f.chmodSync(dest, st.mode & 0o7777);
+        }
+        else
+            this.skipped.push(rel);
+    }
+    renameTrio(dir) {
+        for (const suffix of ["", "-wal", "-shm"]) {
+            const from = path.join(dir, LEGACY_DB_FILENAME + suffix);
+            const to = path.join(dir, DB_FILENAME + suffix);
+            if (this.f.existsSync(from) && !this.f.existsSync(to))
+                this.f.renameSync(from, to);
+        }
+    }
+    rewriteSettings(dir) {
+        const file = path.join(dir, "settings.json");
+        let st;
+        try {
+            st = this.f.lstatSync(file);
+        }
+        catch {
+            return;
+        }
+        if (!st.isFile())
+            return;
+        let raw;
+        try {
+            raw = JSON.parse(this.f.readFileSync(file, "utf8").replace(/^/, ""));
+            if (!raw || typeof raw !== "object" || Array.isArray(raw))
+                throw new Error("not an object");
+        }
+        catch {
+            this.warnings.push(`${path.join(this.plan.legacyDir, "settings.json")} is not JSON; copied unchanged, so readers fall back to ${OLD_PREFIX} keys and defaults`);
+            return;
+        }
+        const env = raw.env;
+        const renamed = env && typeof env === "object" && !Array.isArray(env) ? { ...raw, env: renameKeys(env) } : renameKeys(raw);
+        const mode = st.mode & 0o7777;
+        this.f.chmodSync(file, mode | 0o200);
+        this.f.writeFileSync(file, JSON.stringify(rebaseValues(renamed, this.plan.legacyDir, this.plan.freeDir), null, 2) + "\n");
+        this.f.chmodSync(file, mode);
+    }
+}
+function stamp(ms) {
+    return new Date(ms).toISOString().replace(/[-:.]/g, "");
+}
+function preflight(plan) {
+    const outside = plan.links.find((l) => l.outside);
+    if (outside)
+        return `symbolic link ${outside.path} -> ${outside.target} leaves ${plan.legacyDir}`;
+    if (plan.unreadable.length > 0)
+        return `cannot read ${plan.unreadable.map((r) => path.join(plan.legacyDir, r)).join(", ")}`;
+    if (plan.freeBytes !== null && plan.freeBytes < plan.bytes)
+        return `the copy needs ${plan.bytes} bytes and ${plan.freeBytes} are free`;
+    return null;
+}
+/**
+ * Applies a plan: stop the worker, hold the spawn lock, copy into a sibling, rename the database
+ * trio, rewrite settings, check the copy, recheck the source, write the marker, rename the sibling.
+ * Every failure removes the sibling, so the resolver keeps serving the legacy directory.
+ * @param plan A plan from {@link planMemoryMigration}.
+ * @param ports The stop call, clock, integrity check, version and, for tests, file system and lock.
+ * @returns What happened; never throws.
+ */
+export async function applyMemoryMigration(plan, ports) {
+    const f = ports.fs ?? fs;
+    const started = ports.now();
+    const result = { status: "aborted", bytes: plan.bytes, durationMs: 0, skipped: [], warnings: [], restartOwed: false };
+    const done = (status, reason) => ({ ...result, status, reason, durationMs: Math.max(0, ports.now() - started) });
+    if (plan.refusal)
+        return done("refused", plan.refusal);
+    const early = preflight(plan) ?? (f.existsSync(plan.freeDir) ? `${plan.freeDir} already exists` : null);
+    if (early)
+        return done("aborted", early);
+    const stop = await ports.stopWorker();
+    result.restartOwed = stop.wasRunning && stop.stopped;
+    if (!stop.stopped)
+        return done("aborted", `the worker did not stop: ${stop.reason ?? "unknown"}`);
+    const lockPath = path.join(plan.legacyDir, "spawn.lock");
+    const lock = ports.acquireLock ? ports.acquireLock(lockPath) : fileSpawnLock(lockPath, f, ports.now);
+    if (typeof lock === "string")
+        return done("aborted", lock);
+    const fresh = keepFresh(lock, ports.lockRefreshMs ?? LOCK_REFRESH_MS);
+    let partial = null;
+    try {
+        for (const leftover of plan.partials)
+            if (PARTIAL_PATTERN.test(path.basename(leftover)) && path.dirname(leftover) === plan.home)
+                await f.promises.rm(leftover, { recursive: true, force: true });
+        const before = trioState(f, plan.legacyDir);
+        partial = path.join(plan.home, `${FREE_DIR_NAME}.partial-${stamp(ports.now())}`);
+        const copier = new Copier(f, plan);
+        await copier.copyDir("", partial);
+        copier.renameTrio(partial);
+        copier.rewriteSettings(partial);
+        result.skipped = copier.skipped.sort();
+        result.warnings = copier.warnings;
+        const db = path.join(partial, DB_FILENAME);
+        const bad = f.existsSync(db) ? await ports.integrityCheck(db) : null;
+        if (bad)
+            throw new Abort(bad);
+        // The recheck sits right before the marker, so a write during the integrity check still aborts.
+        const after = trioState(f, plan.legacyDir);
+        const changed = Object.keys(before).find((k) => before[k] !== after[k]);
+        if (changed)
+            throw new Abort(`${path.join(plan.legacyDir, changed)} changed during the copy, so a worker wrote the legacy database`);
+        if (pidFileLive(path.join(plan.legacyDir, "worker.pid"), f))
+            throw new Abort(`${path.join(plan.legacyDir, "worker.pid")} appeared during the copy, so a worker started on the legacy directory`);
+        const lost = fresh.lost();
+        if (lost || !lock.held())
+            throw new Abort(`${lockPath} was not held for the whole copy${lost ? ` (refresh failed: ${lost})` : ""}, so a launcher may have started a worker`);
+        const at = new Date(ports.now()).toISOString();
+        f.writeFileSync(path.join(partial, MARKER_NAME), JSON.stringify({ source: plan.legacyDir, at, freeharness: ports.version, skipped: result.skipped }, null, 2) + "\n");
+        if (f.existsSync(plan.freeDir))
+            throw new Abort(`${plan.freeDir} appeared during the copy`);
+        f.renameSync(partial, plan.freeDir);
+        partial = null;
+        // Only after the commit: before it the engine still runs in the legacy observer cwd.
+        if (plan.observerMove)
+            result.observer = moveObserver(f, plan.observerMove);
+        return done("copied");
+    }
+    catch (e) {
+        return done("aborted", e instanceof Error ? e.message : String(e));
+    }
+    finally {
+        // A sibling that cannot be removed matches PARTIAL_PATTERN, so the next pass 2 removes it.
+        if (partial)
+            await f.promises.rm(partial, { recursive: true, force: true }).catch(() => undefined);
+        fresh.stop();
+        lock.release();
+    }
+}
+function formatBytes(n) {
+    const units = ["B", "KB", "MB", "GB", "TB"];
+    let i = 0;
+    let v = n;
+    while (v >= 1024 && i < units.length - 1) {
+        v /= 1024;
+        i++;
+    }
+    return `${i === 0 ? v : v.toFixed(1)} ${units[i]}`;
+}
+/** The pass-1 lines for a plan: the copy with its size and free space, links, leftovers, refusals. */
+export function describePlan(plan) {
+    if (plan.refusal)
+        return [`WARN ${plan.refusal}`];
+    const space = plan.freeBytes === null ? "unknown" : formatBytes(plan.freeBytes);
+    const lines = [
+        `Would copy the memory data from ${plan.legacyDir} to ${plan.freeDir} (${formatBytes(plan.bytes)}; free space ${space}) in pass 2: stop the worker, hold ${path.join(plan.legacyDir, "spawn.lock")}, copy without following links into a temporary sibling, rename ${LEGACY_DB_FILENAME}* to ${DB_FILENAME}*, rewrite ${OLD_PREFIX} settings keys and legacy path values, check the copy, write ${MARKER_NAME}; ${plan.legacyDir} is only read.`,
+    ];
+    for (const l of plan.links)
+        lines.push(l.outside ? `WARN symbolic link ${l.path} -> ${l.target} leaves ${plan.legacyDir}; pass 2 aborts the copy` : `symbolic link ${l.path} -> ${l.target} is copied as a link`);
+    if (plan.observerMove)
+        lines.push(`Would move the observer transcripts from ${plan.observerMove.from} to ${plan.observerMove.to} after the copy, only when the source is a real directory and the target is absent; otherwise both are kept with a note.`);
+    for (const p of plan.partials)
+        lines.push(`leftover partial copy ${p}; pass 2 removes it before copying`);
+    const blocked = preflight(plan);
+    if (blocked && !plan.links.some((l) => l.outside))
+        lines.push(`WARN pass 2 aborts the copy: ${blocked}`);
+    return lines;
+}
+/** The pass-2 lines for an applied plan. */
+export function describeResult(plan, r) {
+    if (r.status === "refused")
+        return [`WARN ${r.reason}`];
+    if (r.status === "aborted")
+        return [`WARN memory data copy aborted: ${r.reason}; no ${plan.freeDir} was created, so the worker keeps serving ${plan.legacyDir}`];
+    const lines = [`Copied the memory data from ${plan.legacyDir} to ${plan.freeDir} (${formatBytes(r.bytes)} in ${(r.durationMs / 1000).toFixed(1)} s); ${plan.legacyDir} is unchanged.`];
+    for (const w of r.warnings)
+        lines.push(`WARN ${w}`);
+    if (r.observer)
+        lines.push(r.observer);
+    if (r.restartOwed)
+        lines.push(`The stopped worker restarts on ${plan.freeDir} when \`freeharness update\` finishes staging the new plugin bundle; after \`freeharness init\`, the next Claude Code SessionStart starts it.`);
+    return lines;
+}

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

@@ -0,0 +1,22 @@
+export type MemoryPathSource = "FREE_MEM_DATA_DIR" | "CLAUDE_MEM_DATA_DIR" | "settings" | "default" | "fallback";
+export interface MemoryPaths {
+    dataDir: string;
+    /** Absolute path of the database the engine opens in `dataDir`. */
+    dbFile: string;
+    /** True when `dataDir` is `<home>/.claude-mem`. */
+    legacy: boolean;
+    source: MemoryPathSource;
+}
+export declare const FREE_DIR_NAME = ".free-mem";
+export declare const LEGACY_DIR_NAME = ".claude-mem";
+export declare const DB_FILENAME = "free-mem.db";
+export declare const LEGACY_DB_FILENAME = "claude-mem.db";
+/** A settings file's keys as the engine reads them (BOM dropped, `env` first); null when unreadable. */
+export declare function readMemorySettings(settingsPath: string): Record<string, unknown> | null;
+/**
+ * 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 `~`.
+ */
+export declare function resolveMemoryPaths(env: Record<string, string | undefined>, home: string): MemoryPaths;