freeharness 0.4.1 → 0.4.2

package/dist/cli/json-key-edit.js

@@ -0,0 +1,118 @@
+// The one path that edits another program's JSON config. The original bytes are archived and
+// verified before the file changes, and the new content replaces it by rename, so every failure
+// leaves the original whole and every success leaves a copy to restore from.
+import fs from "node:fs";
+import path from "node:path";
+import { freeDestination } from "./hard-cleanup.js";
+function isPlainObject(v) {
+    return v !== null && typeof v === "object" && !Array.isArray(v);
+}
+function own(obj, key) {
+    return Object.prototype.hasOwnProperty.call(obj, key);
+}
+function codeOf(e) {
+    return e?.code ?? (e instanceof Error ? e.message : String(e));
+}
+/** Reads the file behind `file`; a symlink is followed so the link itself survives the edit. */
+function readReal(file) {
+    try {
+        const real = fs.realpathSync.native(file);
+        // Checked before the open: opening a FIFO for reading would block.
+        if (!fs.statSync(real).isFile())
+            return { reason: "not-regular" };
+        const fd = fs.openSync(real, "r");
+        try {
+            const st = fs.fstatSync(fd);
+            if (!st.isFile())
+                return { reason: "not-regular" };
+            return { real, bytes: fs.readFileSync(fd), mode: st.mode & 0o777 };
+        }
+        finally {
+            fs.closeSync(fd);
+        }
+    }
+    catch (e) {
+        return { reason: codeOf(e) === "ENOENT" ? "missing" : `read-failed: ${codeOf(e)}` };
+    }
+}
+/** Archives the original bytes under a fresh name and proves the copy, before anything is edited. */
+function archiveCopy(bytes, mode, copyDest) {
+    try {
+        const copy = freeDestination(copyDest);
+        fs.mkdirSync(path.dirname(copy), { recursive: true });
+        fs.writeFileSync(copy, bytes, { flag: "wx" });
+        fs.chmodSync(copy, mode); // the `mode` option is masked by the umask
+        if (!fs.readFileSync(copy).equals(bytes))
+            return { reason: "copy-failed: EDIFFERS" };
+        return { copy };
+    }
+    catch (e) {
+        return { reason: `copy-failed: ${codeOf(e)}` };
+    }
+}
+/** Replaces `real` by rename; `wx` refuses a temp name another writer holds, so only our own temp file is ever removed. */
+function replaceByRename(real, text, mode, rename) {
+    const tmp = path.join(path.dirname(real), `.${path.basename(real)}.${process.pid}.tmp`);
+    let created = false;
+    try {
+        const fd = fs.openSync(tmp, "wx", mode);
+        created = true;
+        try {
+            fs.writeFileSync(fd, text);
+            fs.fsyncSync(fd);
+        }
+        finally {
+            fs.closeSync(fd);
+        }
+        fs.chmodSync(tmp, mode);
+        rename(tmp, real);
+        return undefined;
+    }
+    catch (e) {
+        if (created) {
+            try {
+                fs.rmSync(tmp, { force: true });
+            }
+            catch {
+                // The write failure is the one to report.
+            }
+        }
+        return `write-failed: ${codeOf(e)}`;
+    }
+}
+/**
+ * Removes `keyPath` from the JSON object in `file` after a verified copy of the unedited bytes
+ * lands at the first free name of `copyDest`. Every refusal leaves `file` byte-equal.
+ */
+export function removeJsonKey(file, keyPath, copyDest, options = {}) {
+    const read = readReal(file);
+    if ("reason" in read)
+        return { ok: false, reason: read.reason };
+    let root;
+    try {
+        root = JSON.parse(read.bytes.toString("utf8"));
+    }
+    catch {
+        return { ok: false, reason: "not-json" };
+    }
+    if (!isPlainObject(root))
+        return { ok: false, reason: "not-json" };
+    let parent = root;
+    for (const segment of keyPath.slice(0, -1)) {
+        const next = own(parent, segment) ? parent[segment] : undefined;
+        if (!isPlainObject(next))
+            return { ok: false, reason: "key-gone" };
+        parent = next;
+    }
+    const last = keyPath[keyPath.length - 1];
+    if (last === undefined || !own(parent, last))
+        return { ok: false, reason: "key-gone" };
+    if (options.stillMatches && !options.stillMatches(parent[last]))
+        return { ok: false, reason: "changed" };
+    const archived = archiveCopy(read.bytes, read.mode, copyDest);
+    if ("reason" in archived)
+        return { ok: false, reason: archived.reason };
+    delete parent[last];
+    const failed = replaceByRename(read.real, JSON.stringify(root, null, 2) + "\n", read.mode, options.rename ?? ((from, to) => fs.renameSync(from, to)));
+    return failed ? { ok: false, reason: failed } : { ok: true, copy: archived.copy };
+}

package/dist/cli/memory-import.d.ts

@@ -0,0 +1,74 @@
+/** The worker's per-file text cap; a bigger file would be refused, so it is never sent. */
+export declare const MAX_FILE_BYTES = 262144;
+export declare const MAX_BATCH_FILES = 200;
+/** Below the worker's 5 MB JSON parser limit, which answers 413 before validation. */
+export declare const MAX_BATCH_BYTES: number;
+export type MemoryKind = "auto-memory" | "agent-memory";
+export interface ImportFile {
+    sourcePath: string;
+    kind: MemoryKind;
+    title: string;
+    text: string;
+    sha256: string;
+    mtimeEpochMs: number;
+}
+export interface ImportBatch {
+    project: string;
+    files: ImportFile[];
+}
+export interface CollectedFile extends ImportFile {
+    project: string;
+    size: number;
+}
+export interface SkippedFile {
+    sourcePath: string;
+    reason: string;
+}
+export interface Collection {
+    files: CollectedFile[];
+    skipped: SkippedFile[];
+}
+export interface CollectOptions {
+    home: string;
+    configDir: string;
+    projects: string[];
+}
+export interface ImportOptions {
+    home?: string;
+    configDir?: string;
+    projects: string[];
+    port?: number;
+    now: Date;
+    dryRun: boolean;
+    confirm: () => Promise<boolean>;
+    log: (line: string) => void;
+    error: (line: string) => void;
+    /** Lets a test stand in a cross-device rename. */
+    renameFile?: (from: string, to: string) => void;
+}
+export interface ImportOutcome {
+    exitCode: number;
+    stored: number;
+    skipped: number;
+    archived: string[];
+    failed: SkippedFile[];
+}
+/** Same name the engine derives for a cwd, so imported rows join the project's live ones. */
+export declare function engineProjectName(dir: string): string;
+/** Target project of an auto-memory directory name such as `-Users-u-Proj`. */
+export declare function autoMemoryProject(dirName: string, root?: string): string;
+/** First `# ` heading, else the file name, capped at the worker's title length. */
+export declare function titleOf(text: string, fileName: string): string;
+/** The user scope is walked first, so a project that is the home itself adds no second copy. */
+export declare function collectMemoryFiles(opts: CollectOptions): Collection;
+/** Splits one project's files by count and by serialized size, so no body reaches the parser limit. */
+export declare function batchFiles(project: string, files: CollectedFile[]): ImportBatch[];
+/** HOME-relative inside the home; anything else keeps its absolute path under `abs/`. */
+export declare function archiveTarget(home: string, archiveRoot: string, sourcePath: string): string;
+/** An earlier archived copy is never overwritten. */
+export declare function uniqueTarget(target: string): string;
+/**
+ * Previews, then posts and archives. File text is untrusted model output: only paths, sizes
+ * and counts are ever printed, and nothing moves until the worker has answered for the file.
+ */
+export declare function importMemoryFiles(opts: ImportOptions): Promise<ImportOutcome>;

package/dist/cli/memory-import.js

@@ -0,0 +1,469 @@
+// One-time move of Claude Code's model-written memory files into free-mem.
+import crypto from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { configDir as defaultConfigDir, dataDir, workerPort } from "../adapters/memory/doctor.js";
+import { archiveRootFor, printable } from "./hard-cleanup.js";
+/** The worker's per-file text cap; a bigger file would be refused, so it is never sent. */
+export const MAX_FILE_BYTES = 262_144;
+export const MAX_BATCH_FILES = 200;
+/** Below the worker's 5 MB JSON parser limit, which answers 413 before validation. */
+export const MAX_BATCH_BYTES = 4 * 1024 * 1024;
+const MAX_TITLE = 200;
+function sha256(data) {
+    return crypto.createHash("sha256").update(data).digest("hex");
+}
+function lexists(p) {
+    try {
+        fs.lstatSync(p);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function isDir(p) {
+    try {
+        return fs.statSync(p).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+function errText(e) {
+    return e instanceof Error ? e.message : String(e);
+}
+/** Same name the engine derives for a cwd, so imported rows join the project's live ones. */
+export function engineProjectName(dir) {
+    const r = spawnSync("git", ["rev-parse", "--show-toplevel"], { cwd: dir, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] });
+    const root = r.status === 0 ? r.stdout.trim() : "";
+    return path.basename(root || dir) || "unknown-project";
+}
+/** Claude Code turns every non-alphanumeric character of the cwd into a dash; older names only the separators. */
+function dirNameEncodings(p) {
+    return new Set([p.replace(/[\\/]/g, "-"), p.replace(/[^A-Za-z0-9]/g, "-")]);
+}
+/**
+ * The encoding is lossy (a dash may stand for a separator or for a character of a name), so the
+ * cwd is recovered by walking the disk along the name rather than by string rewriting.
+ */
+function decodeProjectDir(name, root) {
+    let best = null;
+    const visit = (dir) => {
+        let entries;
+        try {
+            entries = fs.readdirSync(dir).sort();
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            const child = path.join(dir, entry);
+            for (const enc of dirNameEncodings(child)) {
+                if (enc === name) {
+                    if (isDir(child) && (best === null || child.length > best.length))
+                        best = child;
+                }
+                else if (name.startsWith(`${enc}-`) && isDir(child)) {
+                    visit(child);
+                }
+            }
+        }
+    };
+    visit(root);
+    return best;
+}
+/** Target project of an auto-memory directory name such as `-Users-u-Proj`. */
+export function autoMemoryProject(dirName, root = path.parse(os.homedir()).root) {
+    const cwd = decodeProjectDir(dirName, root);
+    return cwd ? engineProjectName(cwd) : dirName.replace(/^-/, "");
+}
+/** First `# ` heading, else the file name, capped at the worker's title length. */
+export function titleOf(text, fileName) {
+    const heading = /^# +(\S.*?)\s*$/m.exec(text)?.[1];
+    let title = heading ?? path.basename(fileName).replace(/\.md$/i, "");
+    if (title.length > MAX_TITLE) {
+        title = title.slice(0, MAX_TITLE);
+        if (/[\uD800-\uDBFF]$/.test(title))
+            title = title.slice(0, -1);
+    }
+    return title;
+}
+const UTF8 = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true });
+/**
+ * Walks one memory root without following any link: a linked file or directory could point
+ * anywhere, and moving its target into the archive is not this command's call.
+ */
+function walkMemoryDir(root, kind, project, seen, out) {
+    let st;
+    try {
+        st = fs.lstatSync(root);
+    }
+    catch {
+        return;
+    }
+    if (st.isSymbolicLink()) {
+        out.skipped.push({ sourcePath: root, reason: "symlink, not followed" });
+        return;
+    }
+    if (!st.isDirectory())
+        return;
+    let entries;
+    try {
+        entries = fs.readdirSync(root, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name));
+    }
+    catch (e) {
+        out.skipped.push({ sourcePath: root, reason: `unreadable directory (${errText(e)})` });
+        return;
+    }
+    for (const e of entries) {
+        const p = path.join(root, e.name);
+        if (e.isSymbolicLink()) {
+            out.skipped.push({ sourcePath: p, reason: "symlink, not followed" });
+        }
+        else if (e.isDirectory()) {
+            walkMemoryDir(p, kind, project, seen, out);
+        }
+        else if (e.isFile() && /\.md$/i.test(e.name) && !seen.has(p)) {
+            seen.add(p);
+            readMemoryFile(p, kind, project, out);
+        }
+    }
+}
+function readMemoryFile(p, kind, project, out) {
+    let st;
+    let bytes;
+    try {
+        st = fs.lstatSync(p);
+        if (st.size > MAX_FILE_BYTES) {
+            out.skipped.push({ sourcePath: p, reason: `${st.size} bytes, over the ${MAX_FILE_BYTES}-byte limit` });
+            return;
+        }
+        bytes = fs.readFileSync(p);
+    }
+    catch (e) {
+        out.skipped.push({ sourcePath: p, reason: `unreadable (${errText(e)})` });
+        return;
+    }
+    let text;
+    try {
+        text = UTF8.decode(bytes);
+    }
+    catch {
+        out.skipped.push({ sourcePath: p, reason: "not valid UTF-8" });
+        return;
+    }
+    out.files.push({
+        sourcePath: p,
+        kind,
+        project,
+        size: bytes.length,
+        title: titleOf(text, p),
+        text,
+        sha256: sha256(text),
+        mtimeEpochMs: Math.floor(st.mtimeMs),
+    });
+}
+const AGENT_DIRS = ["agent-memory", "agent-memory-local"];
+/**
+ * A cloned repository controls its own `.claude`, so a link there could aim the walk, and the
+ * archive move, at any directory of the machine.
+ */
+function projectClaudeDir(proj, out) {
+    const dir = path.join(proj, ".claude");
+    let st;
+    try {
+        st = fs.lstatSync(dir);
+    }
+    catch {
+        return undefined;
+    }
+    if (st.isSymbolicLink()) {
+        out.skipped.push({ sourcePath: dir, reason: "symlink, not followed" });
+        return undefined;
+    }
+    if (!st.isDirectory())
+        return undefined;
+    try {
+        const rel = path.relative(fs.realpathSync(proj), fs.realpathSync(dir));
+        if (rel === "" || rel.startsWith("..") || path.isAbsolute(rel)) {
+            out.skipped.push({ sourcePath: dir, reason: "resolves outside the project" });
+            return undefined;
+        }
+    }
+    catch (e) {
+        out.skipped.push({ sourcePath: dir, reason: `unresolvable (${errText(e)})` });
+        return undefined;
+    }
+    return dir;
+}
+/** The user scope is walked first, so a project that is the home itself adds no second copy. */
+export function collectMemoryFiles(opts) {
+    const out = { files: [], skipped: [] };
+    const seen = new Set();
+    const projectsDir = path.join(opts.configDir, "projects");
+    let autoDirs = [];
+    try {
+        autoDirs = fs.readdirSync(projectsDir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name));
+    }
+    catch {
+        /* no auto memory */
+    }
+    for (const d of autoDirs) {
+        const dir = path.join(projectsDir, d.name);
+        if (d.isSymbolicLink()) {
+            out.skipped.push({ sourcePath: dir, reason: "symlink, not followed" });
+            continue;
+        }
+        if (!d.isDirectory() || !lexists(path.join(dir, "memory")))
+            continue;
+        walkMemoryDir(path.join(dir, "memory"), "auto-memory", autoMemoryProject(d.name), seen, out);
+    }
+    for (const sub of AGENT_DIRS)
+        walkMemoryDir(path.join(opts.configDir, sub), "agent-memory", "user", seen, out);
+    for (const proj of opts.projects) {
+        const claude = projectClaudeDir(proj, out);
+        if (claude === undefined)
+            continue;
+        const name = engineProjectName(proj);
+        for (const sub of AGENT_DIRS)
+            walkMemoryDir(path.join(claude, sub), "agent-memory", name, seen, out);
+    }
+    return out;
+}
+function wireFile(f) {
+    return { sourcePath: f.sourcePath, kind: f.kind, title: f.title, text: f.text, sha256: f.sha256, mtimeEpochMs: f.mtimeEpochMs };
+}
+/** Splits one project's files by count and by serialized size, so no body reaches the parser limit. */
+export function batchFiles(project, files) {
+    const empty = Buffer.byteLength(JSON.stringify({ project, files: [] }), "utf8");
+    const batches = [];
+    let current = [];
+    let bytes = empty;
+    for (const f of files) {
+        const wire = wireFile(f);
+        const size = Buffer.byteLength(JSON.stringify(wire), "utf8") + 1;
+        if (current.length > 0 && (current.length >= MAX_BATCH_FILES || bytes + size > MAX_BATCH_BYTES)) {
+            batches.push({ project, files: current });
+            current = [];
+            bytes = empty;
+        }
+        current.push(wire);
+        bytes += size;
+    }
+    if (current.length > 0)
+        batches.push({ project, files: current });
+    return batches;
+}
+/** HOME-relative inside the home; anything else keeps its absolute path under `abs/`. */
+export function archiveTarget(home, archiveRoot, sourcePath) {
+    const rel = path.relative(home, sourcePath);
+    const inside = rel !== "" && !rel.startsWith("..") && !path.isAbsolute(rel);
+    const base = path.join(archiveRoot, "memory-import");
+    return inside ? path.join(base, rel) : path.join(base, "abs", sourcePath.replace(/^[\\/]+/, ""));
+}
+/** An earlier archived copy is never overwritten. */
+export function uniqueTarget(target) {
+    if (!lexists(target))
+        return target;
+    const ext = path.extname(target);
+    const stem = target.slice(0, target.length - ext.length);
+    for (let n = 1;; n++) {
+        const candidate = `${stem}-${n}${ext}`;
+        if (!lexists(candidate))
+            return candidate;
+    }
+}
+/**
+ * The bytes the worker stored are the bytes that must land in the archive, so a source edited
+ * since collection stays; a cross-device move is a verified copy before the source goes.
+ */
+function moveToArchive(file, dest, rename) {
+    let expected;
+    try {
+        const st = fs.lstatSync(file.sourcePath);
+        if (!st.isFile())
+            return "no longer a regular file";
+        expected = sha256(fs.readFileSync(file.sourcePath));
+    }
+    catch (e) {
+        return `unreadable before the move (${errText(e)})`;
+    }
+    if (expected !== sha256(Buffer.from(file.text, "utf8")))
+        return "changed since it was read";
+    let target;
+    try {
+        fs.mkdirSync(path.dirname(dest), { recursive: true, mode: 0o700 });
+        target = uniqueTarget(dest);
+    }
+    catch (e) {
+        return `archive directory failed (${errText(e)})`;
+    }
+    try {
+        rename(file.sourcePath, target);
+        return undefined;
+    }
+    catch (e) {
+        if (e.code !== "EXDEV")
+            return `move failed (${errText(e)})`;
+    }
+    try {
+        fs.copyFileSync(file.sourcePath, target, fs.constants.COPYFILE_EXCL);
+        const fd = fs.openSync(target, "r");
+        try {
+            fs.fsyncSync(fd);
+        }
+        finally {
+            fs.closeSync(fd);
+        }
+        if (sha256(fs.readFileSync(target)) !== expected) {
+            fs.rmSync(target, { force: true });
+            return "archive copy did not verify";
+        }
+        fs.unlinkSync(file.sourcePath);
+        return undefined;
+    }
+    catch (e) {
+        return `copy into the archive failed (${errText(e)})`;
+    }
+}
+function parseAnswer(body) {
+    const b = body;
+    if (!b || typeof b.stored !== "number" || typeof b.skipped !== "number" || !Array.isArray(b.errors))
+        return null;
+    const errors = b.errors.filter((e) => !!e && typeof e.sourcePath === "string");
+    return { stored: b.stored, skipped: b.skipped, errors: errors.map((e) => ({ sourcePath: e.sourcePath, reason: String(e.reason ?? "") })) };
+}
+/**
+ * Whatever listens on the port may not be the worker: unless its counts account for every file
+ * of the batch, and each error names a distinct file of it, nothing proves a file was stored.
+ */
+function answerAccountsFor(answer, batch) {
+    const count = (n) => Number.isSafeInteger(n) && n >= 0;
+    if (!count(answer.stored) || !count(answer.skipped))
+        return false;
+    const paths = new Set(batch.files.map((f) => f.sourcePath));
+    const named = new Set(answer.errors.map((e) => e.sourcePath).filter((p) => paths.has(p)));
+    return named.size === answer.errors.length && answer.stored + answer.skipped + answer.errors.length === batch.files.length;
+}
+async function workerHealthy(port) {
+    try {
+        const res = await fetch(`http://127.0.0.1:${port}/api/health`, { signal: AbortSignal.timeout(1500) });
+        return res.ok ? undefined : `health answered HTTP ${res.status}`;
+    }
+    catch (e) {
+        return errText(e);
+    }
+}
+async function postBatch(port, batch) {
+    try {
+        const res = await fetch(`http://127.0.0.1:${port}/api/import/observations`, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify(batch),
+            signal: AbortSignal.timeout(120_000),
+        });
+        if (!res.ok)
+            return `worker answered HTTP ${res.status}`;
+        return parseAnswer(await res.json().catch(() => null)) ?? "worker answer is not an import result";
+    }
+    catch (e) {
+        return `request failed (${errText(e)})`;
+    }
+}
+function groupByProject(files) {
+    const groups = new Map();
+    for (const f of files)
+        groups.set(f.project, [...(groups.get(f.project) ?? []), f]);
+    return new Map([...groups.entries()].sort(([a], [b]) => a.localeCompare(b)));
+}
+/**
+ * Previews, then posts and archives. File text is untrusted model output: only paths, sizes
+ * and counts are ever printed, and nothing moves until the worker has answered for the file.
+ */
+export async function importMemoryFiles(opts) {
+    const home = opts.home ?? os.homedir();
+    const outcome = { exitCode: 0, stored: 0, skipped: 0, archived: [], failed: [] };
+    for (const p of opts.projects) {
+        if (!isDir(p)) {
+            opts.error(`FAIL --project ${printable(p)} is not a directory`);
+            return { ...outcome, exitCode: 1 };
+        }
+    }
+    const collection = collectMemoryFiles({ home, configDir: opts.configDir ?? defaultConfigDir(), projects: opts.projects });
+    const groups = groupByProject(collection.files);
+    opts.log(`${opts.dryRun ? "[dry-run] " : ""}memory import plan:`);
+    for (const [project, files] of groups) {
+        for (const f of files)
+            opts.log(`  ${printable(f.sourcePath)}  ${f.size} bytes  ${f.kind}  -> ${printable(project)}`);
+    }
+    for (const s of collection.skipped)
+        opts.log(`  SKIP ${printable(s.sourcePath)}: ${s.reason}`);
+    opts.log(`${collection.files.length} file(s) to import into ${groups.size} project(s); ${collection.skipped.length} skipped`);
+    if (collection.files.length === 0) {
+        opts.log("no memory files to import");
+        return outcome;
+    }
+    if (opts.dryRun)
+        return outcome;
+    if (!(await opts.confirm())) {
+        opts.log("Aborted; nothing changed.");
+        return outcome;
+    }
+    const port = opts.port ?? workerPort(dataDir());
+    const down = await workerHealthy(port);
+    if (down !== undefined) {
+        opts.error(`FAIL free-mem worker not reachable on 127.0.0.1:${port} (${printable(down)}); nothing posted, nothing moved. Open a Claude Code session or run freeharness memory restart, then run this again.`);
+        return { ...outcome, exitCode: 1 };
+    }
+    const archiveRoot = archiveRootFor(home, opts.now);
+    const rename = opts.renameFile ?? fs.renameSync;
+    for (const [project, files] of groups) {
+        let stored = 0;
+        let skipped = 0;
+        let archived = 0;
+        for (const [i, batch] of batchFiles(project, files).entries()) {
+            const answer = await postBatch(port, batch);
+            const inBatch = files.filter((f) => batch.files.some((w) => w.sourcePath === f.sourcePath));
+            if (typeof answer === "string") {
+                for (const f of inBatch)
+                    outcome.failed.push({ sourcePath: f.sourcePath, reason: answer });
+                continue;
+            }
+            if (!answerAccountsFor(answer, batch)) {
+                const counts = `${answer.stored}/${answer.skipped}/${answer.errors.length}`;
+                opts.error(`FAIL ${printable(project)} batch ${i + 1}: counts ${printable(counts)} differ from ${batch.files.length}; left in place`);
+                for (const f of inBatch)
+                    outcome.failed.push({ sourcePath: f.sourcePath, reason: `worker counts do not cover batch ${i + 1}` });
+                continue;
+            }
+            stored += answer.stored;
+            skipped += answer.skipped;
+            const rejected = new Map(answer.errors.map((e) => [e.sourcePath, e.reason]));
+            for (const f of inBatch) {
+                const reason = rejected.get(f.sourcePath);
+                if (reason !== undefined) {
+                    outcome.failed.push({ sourcePath: f.sourcePath, reason: `worker error: ${reason.slice(0, 200)}` });
+                    continue;
+                }
+                const moveError = moveToArchive(f, archiveTarget(home, archiveRoot, f.sourcePath), rename);
+                if (moveError)
+                    outcome.failed.push({ sourcePath: f.sourcePath, reason: moveError });
+                else {
+                    archived++;
+                    outcome.archived.push(f.sourcePath);
+                }
+            }
+        }
+        outcome.stored += stored;
+        outcome.skipped += skipped;
+        opts.log(`OK   ${printable(project)}: stored ${stored}, skipped ${skipped}, archived ${archived} -> ${printable(path.join(archiveRoot, "memory-import"))}`);
+    }
+    for (const f of outcome.failed)
+        opts.error(`FAIL ${printable(f.sourcePath)}: ${printable(f.reason)} (left in place)`);
+    if (outcome.failed.length > 0)
+        outcome.exitCode = 1;
+    return outcome;
+}

package/dist/cli/plugin-validate.d.ts

@@ -17,6 +17,18 @@ export interface PluginValidation {
  * `scripts/simulate-session.mjs` checks every emitted event against the same list.
  */
 export declare const HOOK_EVENTS: Set<string>;
+/** Why a `${CLAUDE_PLUGIN_ROOT}` use is unsafe; the warning text names it. */
+export type PluginRootHazard = "unquoted" | "escaped";
+/**
+ * The first unsafe `${CLAUDE_PLUGIN_ROOT}` use in a shell-form command: `unquoted` outside a
+ * double-quoted span (bare, the shell splits it on a plugin path with spaces; single-quoted, the
+ * shell never expands it), `escaped` behind a backslash-escaped dollar in or out of double quotes
+ * (the shell never expands it). Tracks quote state left to right, honoring backslash escapes
+ * outside single quotes (so `\"` opens no span); no shell grammar beyond that.
+ * @param command Shell command string.
+ * @returns The hazard of the first unsafe occurrence, or undefined when every use is safe.
+ */
+export declare function pluginRootHazard(command: string): PluginRootHazard | undefined;
 /**
  * Validates a plugin directory (and, when present, the marketplace manifest in its parent).
  * @param dir The plugin directory (holds `.claude-plugin/plugin.json`).