@nanhara/hara 0.126.0 → 0.127.0

package/dist/plugins/plugins.js

@@ -1,189 +1,526 @@
-// Plugins — a distribution unit that drops skills / roles / MCP servers onto disk; it owns nothing at
-// runtime. The existing loaders pick the contents up (skillsDirs/loadRoles append the resolvers below;
-// index.ts merges pluginMcpServers into the MCP set). Manifest is Claude-Code-compatible: we read
-// .claude-plugin/plugin.json, .hara-plugin/plugin.json, or a bare plugin.json at the plugin root.
-import { readFileSync, existsSync, mkdirSync, readdirSync, rmSync, cpSync, symlinkSync, chmodSync } from "node:fs";
-import { join, resolve, isAbsolute } from "node:path";
+// Plugins are untrusted distribution units. Installation validates every executable contribution,
+// activates a same-filesystem staging directory atomically, and records the exact directory/bin ownership
+// used by uninstall. Runtime loaders re-validate installed manifests instead of trusting installation time.
+import { chmodSync, cpSync, existsSync, lstatSync, readlinkSync, readdirSync, realpathSync, renameSync, rmSync, symlinkSync, } from "node:fs";
+import { randomUUID } from "node:crypto";
 import { homedir } from "node:os";
+import { dirname, isAbsolute, join, relative, resolve } from "node:path";
 import { execFileSync } from "node:child_process";
 import { readRawConfig, updateRawConfig } from "../config.js";
+import { bindPrivateHaraStateFile, ensurePrivateStateSubdirectory, readPrivateStateFileSnapshotSync, removePrivateStateFile, writePrivateStateFileSync, } from "../security/private-state.js";
+import { bindPluginMcpServers, readVerifiedPluginManifest, safePluginId, safePluginRelativePath, } from "./manifest.js";
 export function pluginsDir() {
     return join(homedir(), ".hara", "plugins");
 }
-/** Where plugin-contributed CLI commands are symlinked. Add to PATH to use them (e.g. `export PATH="$HOME/.hara/bin:$PATH"`). */
 export function haraBinDir() {
     return join(homedir(), ".hara", "bin");
 }
-/** Symlink a plugin's `bin` entries into ~/.hara/bin (chmod +x the targets). Returns the command names linked. */
-function linkPluginBins(root, manifest) {
-    if (!manifest.bin)
-        return [];
-    const dir = haraBinDir();
-    mkdirSync(dir, { recursive: true });
-    const linked = [];
-    for (const [name, rel] of Object.entries(manifest.bin)) {
-        const target = join(root, rel);
-        if (!existsSync(target))
-            continue;
-        try {
-            chmodSync(target, 0o755);
-        }
-        catch {
-            /* best-effort */
-        }
-        const link = join(dir, name);
-        try {
-            rmSync(link, { force: true });
-            symlinkSync(target, link);
-            linked.push(name);
-        }
-        catch {
-            /* skip a bin we can't link */
-        }
+function pluginStorage() {
+    return ensurePrivateStateSubdirectory(homedir(), [".hara", "plugins"]).path;
+}
+function pluginBinStorage() {
+    return ensurePrivateStateSubdirectory(homedir(), [".hara", "bin"]).path;
+}
+function pluginRoot(name) {
+    const safe = safePluginId(name);
+    const root = join(pluginStorage(), safe);
+    if (resolve(root) !== join(pluginStorage(), safe))
+        throw new Error("plugin root escaped the Hara plugin directory");
+    return root;
+}
+function receiptBinding(name) {
+    return bindPrivateHaraStateFile(homedir(), ["plugin-receipts"], `${safePluginId(name)}.json`);
+}
+function rootIdentity(path) {
+    const info = lstatSync(path);
+    if (!info.isDirectory() || info.isSymbolicLink())
+        throw new Error(`plugin root '${path}' is not an owned real directory`);
+    return { rootDev: String(info.dev), rootIno: String(info.ino) };
+}
+function pluginBins(manifest) {
+    return { ...(manifest.bin ?? {}) };
+}
+function parseReceipt(raw, expectedName) {
+    let value;
+    try {
+        value = JSON.parse(raw);
+    }
+    catch {
+        throw new Error(`plugin '${expectedName}' ownership receipt is invalid JSON`);
+    }
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error(`plugin '${expectedName}' ownership receipt is invalid`);
+    }
+    const input = value;
+    const allowed = new Set(["schemaVersion", "name", "root", "rootDev", "rootIno", "manifestSha256", "bins"]);
+    if (Object.keys(input).some((key) => !allowed.has(key)) || input.schemaVersion !== 1) {
+        throw new Error(`plugin '${expectedName}' ownership receipt has an unsupported schema`);
     }
-    return linked;
+    const name = safePluginId(input.name, "receipt plugin name");
+    if (name !== expectedName)
+        throw new Error(`plugin '${expectedName}' ownership receipt belongs to '${name}'`);
+    if (typeof input.root !== "string"
+        || typeof input.rootDev !== "string"
+        || typeof input.rootIno !== "string"
+        || typeof input.manifestSha256 !== "string"
+        || !/^[a-f0-9]{64}$/u.test(input.manifestSha256)
+        || !input.bins
+        || typeof input.bins !== "object"
+        || Array.isArray(input.bins))
+        throw new Error(`plugin '${expectedName}' ownership receipt is incomplete`);
+    const bins = {};
+    for (const [rawName, rawPath] of Object.entries(input.bins)) {
+        const binName = safePluginId(rawName, "receipt command name");
+        bins[binName] = safePluginRelativePath(rawPath, `receipt command '${binName}'`);
+    }
+    return {
+        schemaVersion: 1,
+        name,
+        root: resolve(input.root),
+        rootDev: input.rootDev,
+        rootIno: input.rootIno,
+        manifestSha256: input.manifestSha256,
+        bins,
+    };
+}
+function readReceipt(name) {
+    const binding = receiptBinding(name);
+    const snapshot = readPrivateStateFileSnapshotSync(binding.path, 256 * 1024);
+    if (!snapshot)
+        return null;
+    return { binding, snapshot, raw: snapshot.text, receipt: parseReceipt(snapshot.text, name) };
+}
+function writeReceipt(name, root, verified) {
+    const identity = rootIdentity(root);
+    const receipt = {
+        schemaVersion: 1,
+        name,
+        root: resolve(root),
+        ...identity,
+        manifestSha256: verified.sha256,
+        bins: pluginBins(verified.manifest),
+    };
+    writePrivateStateFileSync(receiptBinding(name), `${JSON.stringify(receipt, null, 2)}\n`);
+    return receipt;
 }
-/** Remove a plugin's linked bins (on uninstall). */
-function unlinkPluginBins(manifest) {
-    if (!manifest?.bin)
+function restoreReceipt(name, raw) {
+    const binding = receiptBinding(name);
+    if (raw !== null) {
+        writePrivateStateFileSync(binding, raw);
         return;
-    for (const name of Object.keys(manifest.bin)) {
-        try {
-            rmSync(join(haraBinDir(), name), { force: true });
-        }
-        catch {
-            /* ignore */
-        }
     }
+    const current = readPrivateStateFileSnapshotSync(binding.path, 256 * 1024);
+    if (current)
+        removePrivateStateFile(binding.path, current, binding.directory);
 }
-const MANIFEST_PATHS = [".claude-plugin/plugin.json", ".hara-plugin/plugin.json", "plugin.json"];
-function readManifest(root) {
-    for (const rel of MANIFEST_PATHS) {
-        const p = join(root, rel);
-        if (!existsSync(p))
-            continue;
-        try {
-            return JSON.parse(readFileSync(p, "utf8"));
-        }
-        catch {
-            return null;
-        }
+function verifyReceipt(receipt, root, verified) {
+    const canonicalRoot = resolve(root);
+    const identity = rootIdentity(canonicalRoot);
+    if (receipt.root !== canonicalRoot
+        || receipt.rootDev !== identity.rootDev
+        || receipt.rootIno !== identity.rootIno
+        || receipt.manifestSha256 !== verified.sha256)
+        throw new Error(`plugin '${receipt.name}' changed after installation; refusing an ownership-sensitive operation`);
+}
+function resolvedLinkTarget(link) {
+    const target = readlinkSync(link);
+    return resolve(dirname(link), target);
+}
+function entryExists(path) {
+    try {
+        lstatSync(path);
+        return true;
+    }
+    catch (error) {
+        if (error?.code === "ENOENT")
+            return false;
+        throw error;
     }
-    return null;
 }
-/** Every installed plugin under ~/.hara/plugins (regardless of enabled state). */
+function expectedBinTarget(root, rel) {
+    const target = resolve(root, safePluginRelativePath(rel, "plugin command target"));
+    const relToRoot = relative(resolve(root), target);
+    if (relToRoot.startsWith("..") || isAbsolute(relToRoot))
+        throw new Error("plugin command target escaped its package root");
+    return target;
+}
+function preflightBinLink(root, name, rel, allowMissing = true) {
+    const link = join(pluginBinStorage(), safePluginId(name, "plugin command name"));
+    if (!entryExists(link)) {
+        if (allowMissing)
+            return;
+        throw new Error(`plugin command link '${name}' is missing`);
+    }
+    const info = lstatSync(link);
+    if (!info.isSymbolicLink() || resolvedLinkTarget(link) !== expectedBinTarget(root, rel)) {
+        throw new Error(`refusing to replace or remove foreign command entry '${link}'`);
+    }
+}
+function unlinkBinLink(root, name, rel) {
+    const link = join(pluginBinStorage(), safePluginId(name, "plugin command name"));
+    if (!entryExists(link))
+        return;
+    preflightBinLink(root, name, rel, false);
+    rmSync(link);
+}
+function ensureBinLink(root, name, rel) {
+    const dir = pluginBinStorage();
+    const link = join(dir, safePluginId(name, "plugin command name"));
+    const target = expectedBinTarget(root, rel);
+    const targetInfo = lstatSync(target);
+    if (!targetInfo.isFile() || targetInfo.isSymbolicLink() || targetInfo.nlink !== 1) {
+        throw new Error(`plugin command '${name}' is not a verified regular file`);
+    }
+    if (entryExists(link)) {
+        preflightBinLink(root, name, rel, false);
+        return;
+    }
+    try {
+        chmodSync(target, 0o755);
+    }
+    catch (error) {
+        if (process.platform !== "win32")
+            throw error;
+    }
+    symlinkSync(target, link, "file");
+}
+function restoreBinLinks(root, bins) {
+    for (const [name, rel] of Object.entries(bins))
+        ensureBinLink(root, name, rel);
+}
+function safeTemporaryRemove(path) {
+    if (!existsSync(path))
+        return;
+    const info = lstatSync(path);
+    if (info.isSymbolicLink()) {
+        rmSync(path);
+        return;
+    }
+    if (!info.isDirectory())
+        throw new Error(`refusing to recursively remove unexpected plugin staging entry '${path}'`);
+    rmSync(path, { recursive: true, force: true });
+}
+function readInstalled(root, expectedName, options = {}) {
+    const info = lstatSync(root);
+    if (!info.isDirectory() || info.isSymbolicLink())
+        throw new Error(`installed plugin root '${root}' is not a real directory`);
+    const verified = readVerifiedPluginManifest(root, options);
+    const name = safePluginId(verified.manifest.name);
+    if (expectedName && name !== expectedName)
+        throw new Error(`installed plugin '${expectedName}' claims the different name '${name}'`);
+    return {
+        plugin: { name, version: verified.manifest.version || "0.0.0", root: realpathSync.native(root), manifest: verified.manifest },
+        verified,
+    };
+}
+/** Every installed plugin under ~/.hara/plugins (regardless of enabled state). Invalid roots never execute.
+ * A structurally valid legacy root remains usable so an explicit reinstall can replace it and create a receipt;
+ * ownership-sensitive removal still refuses it until that migration happens. */
 export function listInstalled() {
-    const dir = pluginsDir();
-    if (!existsSync(dir))
-        return [];
+    const dir = pluginStorage();
     const out = [];
     for (const entry of readdirSync(dir)) {
-        const root = join(dir, entry);
-        const manifest = readManifest(root);
-        if (!manifest)
+        if (entry.startsWith(".") || entry.startsWith("_"))
             continue;
-        out.push({ name: manifest.name || entry, version: manifest.version || "0.0.0", root, manifest });
+        try {
+            const name = safePluginId(entry, "installed plugin directory");
+            // Installation and ownership-sensitive operations scan the complete package. Hot-path discovery only
+            // revalidates the manifest and every declared skill/agent/bin/MCP entry; unrelated package files cannot
+            // become executable contributions and must not add O(package-size) latency to each prompt/turn.
+            const { plugin } = readInstalled(join(dir, name), name, { scanTree: false });
+            out.push(plugin);
+        }
+        catch {
+            // Fail closed: a malformed root contributes no code, paths, hooks, MCP servers, or panels.
+        }
     }
     return out;
 }
-/** A plugin is active unless explicitly disabled in config (`plugins.enabled[name] === false`). */
 export function enabledPlugins() {
     const enabled = (readRawConfig().plugins?.enabled ?? {});
-    return listInstalled().filter((p) => enabled[p.name] !== false);
+    return listInstalled().filter((plugin) => enabled[plugin.name] !== false);
 }
-function resolveDirs(p, entries) {
-    return (entries ?? [])
-        .map((e) => (isAbsolute(e) ? e : resolve(p.root, e)))
-        .filter((d) => existsSync(d));
+function resolveDirs(plugin, entries) {
+    return (entries ?? []).map((entry) => {
+        const root = realpathSync.native(resolve(plugin.root));
+        const requested = resolve(root, safePluginRelativePath(entry, `plugin '${plugin.name}' contribution`));
+        const target = realpathSync.native(requested);
+        const rel = relative(root, target);
+        if (rel.startsWith("..") || isAbsolute(rel))
+            throw new Error(`plugin '${plugin.name}' contribution escaped its root`);
+        return target;
+    });
 }
-// --- Contribution resolvers (consumed by the existing loaders; lowest precedence) ---
-/** Skill search dirs from enabled plugins (each holds <name>/SKILL.md subdirs). */
 export function pluginSkillDirs() {
-    return enabledPlugins().flatMap((p) => resolveDirs(p, p.manifest.skills));
+    return enabledPlugins().flatMap((plugin) => resolveDirs(plugin, plugin.manifest.skills));
 }
-/** Role/subagent dirs from enabled plugins. */
 export function pluginRoleDirs() {
-    return enabledPlugins().flatMap((p) => resolveDirs(p, p.manifest.agents));
+    return enabledPlugins().flatMap((plugin) => resolveDirs(plugin, plugin.manifest.agents));
 }
-/** MCP servers contributed by enabled plugins (merged under user config, which wins). */
 export function pluginMcpServers() {
     const out = {};
-    for (const p of enabledPlugins())
-        Object.assign(out, p.manifest.mcpServers ?? {});
+    for (const plugin of enabledPlugins())
+        Object.assign(out, bindPluginMcpServers(plugin.root, plugin.manifest));
     return out;
 }
-/** Lifecycle hooks contributed by enabled plugins (appended after user-config hooks). */
 export function pluginHooks() {
     const out = { PreToolUse: [], PostToolUse: [] };
-    for (const p of enabledPlugins()) {
-        const h = p.manifest.hooks;
-        if (!h || typeof h !== "object")
+    for (const plugin of enabledPlugins()) {
+        const hooks = plugin.manifest.hooks;
+        if (!hooks)
             continue;
-        if (Array.isArray(h.PreToolUse))
-            out.PreToolUse.push(...h.PreToolUse);
-        if (Array.isArray(h.PostToolUse))
-            out.PostToolUse.push(...h.PostToolUse);
+        if (hooks.PreToolUse)
+            out.PreToolUse.push(...hooks.PreToolUse);
+        if (hooks.PostToolUse)
+            out.PostToolUse.push(...hooks.PostToolUse);
     }
     return out;
 }
-/** Install a plugin from `file:<path>`, `github:<owner/repo>`, or `git:<url>` into ~/.hara/plugins/<name>. */
+function validGitSource(source) {
+    const url = source.slice("git:".length);
+    if (!/^(?:https:\/\/|ssh:\/\/|git@)[^\s\0]+$/u.test(url)) {
+        throw new Error("git source must use an https://, ssh://, or git@ URL");
+    }
+    return url;
+}
+function populateStaging(source, staging) {
+    if (source.startsWith("file:")) {
+        const requested = resolve(source.slice("file:".length));
+        const info = lstatSync(requested);
+        if (!info.isDirectory() || info.isSymbolicLink())
+            throw new Error(`plugin source '${requested}' must be a real directory`);
+        const src = realpathSync.native(requested);
+        const store = realpathSync.native(pluginStorage());
+        const rel = relative(store, src);
+        if (rel === "" || (!rel.startsWith("..") && !isAbsolute(rel))) {
+            throw new Error("plugin source must not be inside Hara's installed plugin directory");
+        }
+        cpSync(src, staging, { recursive: true, dereference: false, errorOnExist: true, force: false });
+    }
+    else if (source.startsWith("github:")) {
+        const repo = source.slice("github:".length);
+        if (!/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/u.test(repo))
+            throw new Error("github source must be owner/repository");
+        execFileSync("git", ["clone", "--depth", "1", `https://github.com/${repo}.git`, staging], { stdio: "ignore" });
+    }
+    else if (source.startsWith("git:")) {
+        execFileSync("git", ["clone", "--depth", "1", validGitSource(source), staging], { stdio: "ignore" });
+    }
+    else {
+        throw new Error("source must be file:<path>, github:<owner/repo>, or git:<url>");
+    }
+    safeTemporaryRemove(join(staging, ".git"));
+    safeTemporaryRemove(join(staging, ".learnings"));
+}
+/** Install through a validated same-filesystem stage. Replacements preserve the previous directory and
+ * receipt until the new manifest, bin links, and ownership receipt have all committed successfully. */
 export function installPlugin(source) {
-    mkdirSync(pluginsDir(), { recursive: true });
-    const tmpName = `_install-${process.pid}-${Date.now()}`;
-    const tmp = join(pluginsDir(), tmpName);
-    rmSync(tmp, { recursive: true, force: true });
+    const store = pluginStorage();
+    const staging = join(store, `_install-${process.pid}-${randomUUID()}`);
+    const backup = join(store, `_backup-${process.pid}-${randomUUID()}`);
+    let destination = "";
+    let newActivated = false;
+    let oldMoved = false;
+    let oldManifest = null;
+    let oldReceipt = null;
+    let oldBins = {};
+    let oldIdentity = null;
+    let newManifest = null;
     try {
-        if (source.startsWith("file:")) {
-            const src = resolve(source.slice("file:".length));
-            if (!existsSync(src))
-                throw new Error(`no such path: ${src}`);
-            cpSync(src, tmp, { recursive: true });
-        }
-        else if (source.startsWith("github:")) {
-            execFileSync("git", ["clone", "--depth", "1", `https://github.com/${source.slice("github:".length)}.git`, tmp], { stdio: "ignore" });
-        }
-        else if (source.startsWith("git:")) {
-            execFileSync("git", ["clone", "--depth", "1", source.slice("git:".length), tmp], { stdio: "ignore" });
-        }
-        else {
-            throw new Error("source must be file:<path>, github:<owner/repo>, or git:<url>");
-        }
-        const manifest = readManifest(tmp);
-        if (!manifest || !manifest.name) {
-            rmSync(tmp, { recursive: true, force: true });
-            throw new Error("no valid plugin.json (need at least a name) at the source root");
-        }
-        const dest = join(pluginsDir(), manifest.name);
-        rmSync(dest, { recursive: true, force: true });
-        // move tmp → dest (rename within the same dir)
-        cpSync(tmp, dest, { recursive: true });
-        rmSync(tmp, { recursive: true, force: true });
-        linkPluginBins(dest, manifest); // expose any plugin CLI commands in ~/.hara/bin
-        return { name: manifest.name, version: manifest.version || "0.0.0", root: dest, manifest };
-    }
-    catch (e) {
-        rmSync(tmp, { recursive: true, force: true });
-        throw e;
-    }
-}
-export function uninstallPlugin(name) {
-    const dest = join(pluginsDir(), name);
-    if (!existsSync(dest))
+        populateStaging(source, staging);
+        newManifest = readVerifiedPluginManifest(staging);
+        const name = newManifest.manifest.name;
+        destination = pluginRoot(name);
+        if (existsSync(destination)) {
+            const installed = readInstalled(destination, name);
+            oldManifest = installed.verified;
+            oldBins = pluginBins(oldManifest.manifest);
+            oldReceipt = readReceipt(name);
+            if (oldReceipt)
+                verifyReceipt(oldReceipt.receipt, destination, oldManifest);
+            oldIdentity = rootIdentity(destination);
+        }
+        const newBins = pluginBins(newManifest.manifest);
+        for (const [name, rel] of Object.entries(oldBins))
+            preflightBinLink(destination, name, rel);
+        for (const [name, rel] of Object.entries(newBins)) {
+            const link = join(pluginBinStorage(), name);
+            if (!entryExists(link))
+                continue;
+            if (!oldBins[name])
+                throw new Error(`refusing to overwrite foreign command entry '${link}'`);
+            preflightBinLink(destination, name, oldBins[name], false);
+            // The new target itself was verified in staging; changed relative targets are replaced after activation.
+            void rel;
+        }
+        if (existsSync(destination)) {
+            renameSync(destination, backup);
+            oldMoved = true;
+            const moved = rootIdentity(backup);
+            if (!oldIdentity || moved.rootDev !== oldIdentity.rootDev || moved.rootIno !== oldIdentity.rootIno) {
+                throw new Error(`plugin '${name}' root identity changed during update`);
+            }
+        }
+        renameSync(staging, destination);
+        newActivated = true;
+        newManifest = readVerifiedPluginManifest(destination);
+        for (const [name, rel] of Object.entries(oldBins)) {
+            if (newBins[name] !== rel)
+                unlinkBinLink(destination, name, rel);
+        }
+        for (const [name, rel] of Object.entries(newBins))
+            ensureBinLink(destination, name, rel);
+        writeReceipt(name, destination, newManifest);
+        const result = {
+            name,
+            version: newManifest.manifest.version || "0.0.0",
+            root: realpathSync.native(destination),
+            manifest: newManifest.manifest,
+        };
+        // Activation and its receipt are committed. Cleanup is deliberately outside rollback: recursive backup
+        // removal can partially succeed, so a cleanup error must leave an inert `_backup-*` entry rather than
+        // restore a partially removed old package over the verified new one.
+        if (oldMoved) {
+            try {
+                safeTemporaryRemove(backup);
+            }
+            catch {
+                // A later bounded maintenance pass may remove the skipped, non-loadable backup after inspection.
+            }
+        }
+        return result;
+    }
+    catch (error) {
+        const rollbackErrors = [];
+        const failedManifest = newManifest;
+        const name = failedManifest?.manifest.name;
+        if (failedManifest && name && destination) {
+            try {
+                if (newActivated) {
+                    for (const [binName, rel] of Object.entries(pluginBins(failedManifest.manifest))) {
+                        if (entryExists(join(pluginBinStorage(), binName)))
+                            unlinkBinLink(destination, binName, rel);
+                    }
+                }
+            }
+            catch (rollbackError) {
+                rollbackErrors.push(`new command cleanup: ${rollbackError?.message ?? String(rollbackError)}`);
+            }
+            try {
+                if (newActivated && existsSync(destination))
+                    safeTemporaryRemove(destination);
+                if (oldMoved && existsSync(backup))
+                    renameSync(backup, destination);
+            }
+            catch (rollbackError) {
+                rollbackErrors.push(`directory restore: ${rollbackError?.message ?? String(rollbackError)}`);
+            }
+            try {
+                if (oldMoved && existsSync(destination))
+                    restoreBinLinks(destination, oldBins);
+            }
+            catch (rollbackError) {
+                rollbackErrors.push(`old command restore: ${rollbackError?.message ?? String(rollbackError)}`);
+            }
+            try {
+                restoreReceipt(name, oldReceipt?.raw ?? null);
+            }
+            catch (rollbackError) {
+                rollbackErrors.push(`receipt restore: ${rollbackError?.message ?? String(rollbackError)}`);
+            }
+        }
+        try {
+            safeTemporaryRemove(staging);
+            safeTemporaryRemove(backup);
+        }
+        catch (rollbackError) {
+            rollbackErrors.push(`staging cleanup: ${rollbackError?.message ?? String(rollbackError)}`);
+        }
+        const detail = error instanceof Error ? error.message : String(error);
+        throw new Error(rollbackErrors.length ? `${detail}; rollback warning: ${rollbackErrors.join("; ")}` : detail);
+    }
+}
+export function uninstallPlugin(rawName) {
+    const name = safePluginId(rawName);
+    const destination = pluginRoot(name);
+    if (!existsSync(destination))
         return false;
-    unlinkPluginBins(readManifest(dest)); // remove any linked CLI commands first
-    rmSync(dest, { recursive: true, force: true });
+    const installed = readInstalled(destination, name);
+    const stored = readReceipt(name);
+    if (!stored) {
+        throw new Error(`refusing to uninstall legacy plugin '${name}' without an ownership receipt; ` +
+            "reinstall the same source with this Hara version, then remove it");
+    }
+    verifyReceipt(stored.receipt, destination, installed.verified);
+    for (const [binName, rel] of Object.entries(stored.receipt.bins))
+        preflightBinLink(destination, binName, rel);
+    const quarantine = join(pluginStorage(), `_remove-${process.pid}-${randomUUID()}`);
+    renameSync(destination, quarantine);
+    const moved = rootIdentity(quarantine);
+    if (moved.rootDev !== stored.receipt.rootDev || moved.rootIno !== stored.receipt.rootIno) {
+        renameSync(quarantine, destination);
+        throw new Error(`plugin '${name}' root identity changed during uninstall`);
+    }
+    try {
+        for (const [binName, rel] of Object.entries(stored.receipt.bins))
+            unlinkBinLink(destination, binName, rel);
+        removePrivateStateFile(stored.binding.path, stored.snapshot, stored.binding.directory);
+    }
+    catch (error) {
+        const rollbackErrors = [];
+        try {
+            if (existsSync(quarantine) && !existsSync(destination))
+                renameSync(quarantine, destination);
+            restoreBinLinks(destination, stored.receipt.bins);
+        }
+        catch (rollbackError) {
+            rollbackErrors.push(rollbackError?.message ?? String(rollbackError));
+        }
+        try {
+            restoreReceipt(name, stored.raw);
+        }
+        catch (rollbackError) {
+            rollbackErrors.push(rollbackError?.message ?? String(rollbackError));
+        }
+        const detail = error instanceof Error ? error.message : String(error);
+        throw new Error(rollbackErrors.length ? `${detail}; rollback warning: ${rollbackErrors.join("; ")}` : detail);
+    }
+    // The namespace, executable links, and receipt are already removed. A cleanup failure leaves only an
+    // inert unpredictable quarantine directory and must not reactivate unreceipted code.
+    try {
+        safeTemporaryRemove(quarantine);
+    }
+    catch {
+        // A later bounded maintenance pass may remove it after inspecting ownership.
+    }
     return true;
 }
-/** Panels applicable to a project cwd — a panel matches when any of its `detect` markers exists under
- *  the cwd. Pure over the given plugin list (testable); `panelsForProject` binds it to enabled plugins. */
+function safeMarkerExists(cwd, marker) {
+    try {
+        const rel = safePluginRelativePath(marker, "plugin panel detect marker");
+        const canonicalRoot = realpathSync.native(resolve(cwd));
+        let current = canonicalRoot;
+        for (const part of rel.split("/")) {
+            current = join(current, part);
+            const info = lstatSync(current);
+            if (info.isSymbolicLink())
+                return false;
+        }
+        const relToRoot = relative(canonicalRoot, realpathSync.native(current));
+        return !relToRoot.startsWith("..") && !isAbsolute(relToRoot);
+    }
+    catch {
+        return false;
+    }
+}
 export function matchPanels(plugins, cwd) {
     const out = [];
-    for (const pl of plugins) {
-        for (const panel of pl.manifest.panels ?? []) {
+    for (const plugin of plugins) {
+        for (const panel of plugin.manifest.panels ?? []) {
             if (!panel.detect?.length)
-                continue; // global-only panels stay off project surfaces
-            if (panel.detect.some((m) => existsSync(join(cwd, m))))
-                out.push({ plugin: pl.name, panel });
+                continue;
+            if (panel.detect.some((marker) => safeMarkerExists(cwd, marker)))
+                out.push({ plugin: plugin.name, panel });
         }
     }
     return out;
@@ -191,8 +528,8 @@ export function matchPanels(plugins, cwd) {
 export function panelsForProject(cwd) {
     return matchPanels(enabledPlugins(), cwd);
 }
-/** Persist a plugin's enabled flag in ~/.hara/config.json (`plugins.enabled[name]`). */
-export function setPluginEnabled(name, on) {
+export function setPluginEnabled(rawName, on) {
+    const name = safePluginId(rawName);
     updateRawConfig((config) => {
         const plugins = (config.plugins && typeof config.plugins === "object" ? config.plugins : {});
         plugins.enabled = { ...(plugins.enabled ?? {}), [name]: on };