@rynx-ai/daemon 0.1.0 → 0.1.10-beta.2

package/dist/plugin-installer.js

@@ -1,186 +1,552 @@
 /**
- * Plugin installation — from npm or a local directory.
+ * Transactional plugin installation.
  *
- * No trust mechanism: installing runs the plugin's code in the daemon process.
- * The user owns that risk.
- *
- *  - **npm**:   `npm install <spec>` into `~/.rynx/plugins`, then record it.
- *  - **local**: register an absolute directory and load it in place (no copy;
- *               supports local development / offline). The directory must be a
- *               ready package (built, deps installed, exporting `plugin`).
+ * Packages are first materialized in a host-owned staging directory. The
+ * installer reads only static JSON metadata, validates every declared entry,
+ * hashes the package, and atomically renames the validated tree into an
+ * immutable installation path. Plugin code is never imported here.
+ */
+import { randomUUID } from "node:crypto";
+import { existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, writeFileSync, } from "node:fs";
+import { basename, dirname, join, resolve } from "node:path";
+import { PLUGIN_ID_PATTERN, pluginCliInvocationLeasePid, readPluginRuntimeLeases, removePluginRuntimeLease, } from "@rynx-ai/plugin-sdk";
+import { rynxHome } from "@rynx-ai/core";
+import { getPlugin, isRunnablePluginRecord, removePlugin, upsertPlugin, } from "./plugin-store.js";
+import { detectPluginSource, inspectPluginPackage, materializePluginPackage, normalizePluginSpec, rebuildPluginPackage, } from "./plugin-package.js";
+import { pluginsDir } from "./registry.js";
+import { db } from "./db.js";
+const INSTALLATION_ID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+const STAGING_TRANSACTION_PATTERN = /^install-[A-Za-z0-9]{6}$/;
+const STAGING_OWNER_FILE = ".rynx-staging-owner.json";
+const PROMOTION_MARKER_SUFFIX = ".rynx-promoted";
+const MAX_HOST_MARKER_BYTES = 4 * 1024;
+const DEFAULT_STAGING_GC_AGE_MS = 24 * 60 * 60 * 1_000;
+/**
+ * Install or replace one arbitrary npm/local/git/URL plugin package.
  *
- * After recording, the channel-type catalog is rebuilt so a freshly-installed
- * plugin's types are usable without a daemon restart.
+ * A failed validation, materialization, atomic move, or registry update leaves
+ * the previously registered installation untouched.
  */
-import { spawn } from "node:child_process";
-import { cpSync, existsSync, mkdirSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
-import { homedir } from "node:os";
-import { basename, dirname, isAbsolute, join, resolve } from "node:path";
-import { fileURLToPath } from "node:url";
-import { getPlugin, removePlugin, upsertPlugin, } from "./plugin-store.js";
-import { importPluginManifest, pluginPkgDir, pluginsDir } from "./registry.js";
-/** A spec is "local" if it's a path/file: URL or an existing directory. */
-function detectSource(spec) {
-    if (spec.startsWith("file:"))
-        return "local";
-    if (spec.startsWith("~") || spec.startsWith("./") || spec.startsWith("../") || isAbsolute(spec)) {
-        return "local";
-    }
+export async function installPlugin(spec, onProgress = () => { }, opts = {}) {
+    const prepared = await preparePluginInstallation(spec, onProgress, opts);
     try {
-        if (existsSync(spec) && statSync(spec).isDirectory())
-            return "local";
+        if (opts.expectedDigest !== undefined &&
+            !/^sha256-[A-Za-z0-9+/]{43}={0,2}$/.test(opts.expectedDigest)) {
+            throw new Error("expected plugin digest is invalid");
+        }
+        if (opts.expectedDigest !== undefined &&
+            opts.expectedDigest !== prepared.integrity) {
+            throw new Error(`prepared plugin digest ${prepared.integrity} does not match ` +
+                `expected digest ${opts.expectedDigest}`);
+        }
+        if (prepared.manifest.requiresBuildScripts) {
+            if (!opts.allowScripts) {
+                throw new Error(`plugin "${prepared.name}" requires package build scripts; review digest ` +
+                    `${prepared.integrity} and re-run with --allow-scripts ` +
+                    `--expect-digest ${prepared.integrity}`);
+            }
+            if (opts.expectedDigest === undefined) {
+                throw new Error(`build-script approval must be bound to the prepared artifact; ` +
+                    `re-run with --expect-digest ${prepared.integrity}`);
+            }
+        }
+        const existing = prepared.existing;
+        if (existing && opts.onConflict && !(await opts.onConflict(existing))) {
+            return {
+                name: prepared.name,
+                source: prepared.source,
+                ...(prepared.version ? { version: prepared.version } : {}),
+                skipped: true,
+            };
+        }
+        if (opts.signal?.aborted)
+            throw new Error("plugin installation aborted");
+        const requested = new Set(prepared.manifest.requestedCapabilities);
+        if (!opts.approveCapabilities &&
+            opts.grants === undefined &&
+            !existing &&
+            requested.size > 0) {
+            throw new Error(`plugin "${prepared.name}" requests host capabilities; explicit grants or approval are required`);
+        }
+        const grants = opts.approveCapabilities
+            ? await opts.approveCapabilities(prepared.manifest, existing)
+            : opts.grants ??
+                (existing
+                    ? existing.grants.filter((capability) => requested.has(capability))
+                    : []);
+        return await prepared.commit({
+            grants,
+            expectedDigest: opts.expectedDigest ?? prepared.integrity,
+            signal: opts.signal,
+        });
     }
-    catch {
-        /* not a path */
+    finally {
+        prepared.discard();
     }
-    return "npm";
 }
-function toLocalDir(spec) {
-    let p = spec.startsWith("file:") ? fileURLToPath(spec) : spec;
-    if (p === "~" || p.startsWith("~/"))
-        p = join(homedir(), p.slice(1));
-    return resolve(p);
+/**
+ * Materialize, build (only when explicitly allowed), inspect, and hash one
+ * plugin into host-owned staging without mutating the registry.
+ */
+export async function preparePluginInstallation(spec, onProgress = () => { }, opts = {}) {
+    if (!spec.trim())
+        throw new Error("plugin spec must not be empty");
+    const progress = safeProgress(onProgress);
+    const source = detectPluginSource(spec);
+    const storedSpec = normalizePluginSpec(spec, source);
+    const storage = ensureStorageRoots();
+    const transactionDir = mkdtempSync(join(storage.stagingRoot, "install-"));
+    try {
+        writeStagingOwner(transactionDir);
+    }
+    catch (error) {
+        rmSync(transactionDir, { recursive: true, force: true });
+        throw error;
+    }
+    const stagedPackage = join(transactionDir, "package");
+    let finalPath;
+    let registryUpdated = false;
+    let consumed = false;
+    try {
+        await (opts.materializer ?? materializePluginPackage)({
+            spec: storedSpec,
+            source,
+            destination: stagedPackage,
+            onProgress: progress,
+            signal: opts.signal,
+        });
+        let inspected = await inspectPluginPackage(stagedPackage, {
+            requireEntries: false,
+            signal: opts.signal,
+        });
+        if (opts.allowScripts && !inspected.manifest.requiresBuildScripts) {
+            throw new Error(`plugin "${inspected.manifest.id}" does not declare requiresBuildScripts; ` +
+                "refusing unnecessary --allow-scripts approval");
+        }
+        const requiresBuildScripts = Boolean(inspected.manifest.requiresBuildScripts);
+        if (!requiresBuildScripts) {
+            inspected = await inspectPluginPackage(stagedPackage, { signal: opts.signal });
+        }
+        const name = inspected.manifest.id;
+        if (opts.expectedId && name !== opts.expectedId) {
+            throw new Error(`plugin update id mismatch: expected "${opts.expectedId}", received "${name}"`);
+        }
+        const existing = getPlugin(name);
+        const cleanup = () => {
+            if (!registryUpdated && finalPath) {
+                removeOwnedInstallation(storage.installationsRoot, basename(dirname(finalPath)), finalPath);
+            }
+            try {
+                rmSync(transactionDir, { recursive: true, force: true });
+            }
+            catch {
+                /* orphaned staging is inactive and can be collected later */
+            }
+        };
+        const preparedManifest = cloneManifest(inspected.manifest);
+        const preparedExisting = existing ? clonePluginRecord(existing) : undefined;
+        return {
+            name,
+            source,
+            ...(inspected.version ? { version: inspected.version } : {}),
+            manifest: cloneManifest(preparedManifest),
+            integrity: inspected.integrity,
+            ...(preparedExisting ? { existing: clonePluginRecord(preparedExisting) } : {}),
+            commit: async ({ grants, expectedDigest, signal }) => {
+                if (consumed)
+                    throw new Error("prepared plugin installation was already consumed");
+                consumed = true;
+                try {
+                    if (signal?.aborted)
+                        throw new Error("plugin installation aborted");
+                    if (expectedDigest !== inspected.integrity) {
+                        throw new Error("prepared plugin digest does not match expected digest");
+                    }
+                    const rechecked = await inspectPluginPackage(stagedPackage, {
+                        ...(requiresBuildScripts ? { requireEntries: false } : {}),
+                        signal,
+                    });
+                    if (rechecked.integrity !== inspected.integrity ||
+                        rechecked.version !== inspected.version ||
+                        JSON.stringify(rechecked.manifest) !== JSON.stringify(preparedManifest)) {
+                        throw new Error("prepared plugin artifact changed after approval");
+                    }
+                    let promoted = rechecked;
+                    if (requiresBuildScripts) {
+                        if (!opts.allowScripts) {
+                            throw new Error(`plugin "${name}" requires package build scripts; ` +
+                                `approve digest ${inspected.integrity} before running scripts`);
+                        }
+                        progress(`running digest-approved build scripts for plugin "${name}"`);
+                        await rebuildPluginPackage(stagedPackage, progress, signal);
+                        const built = await inspectPluginPackage(stagedPackage, { signal });
+                        if (JSON.stringify(built.manifest) !== JSON.stringify(preparedManifest) ||
+                            built.version !== inspected.version) {
+                            throw new Error("plugin build scripts changed static package identity or manifest metadata");
+                        }
+                        promoted = built;
+                    }
+                    const requested = new Set(preparedManifest.requestedCapabilities);
+                    for (const grant of grants) {
+                        if (!requested.has(grant)) {
+                            throw new Error(`plugin capability was not requested: ${grant}`);
+                        }
+                    }
+                    if (new Set(grants).size !== grants.length) {
+                        throw new Error("plugin grants must be unique");
+                    }
+                    db().transaction(() => {
+                        const current = getPlugin(name);
+                        if (!samePluginGeneration(existing, current)) {
+                            throw new Error(`plugin "${name}" changed concurrently; retry the installation`);
+                        }
+                        const leases = activeRuntimeLeases(name, storage.installationsRoot);
+                        if (leases.length > 0) {
+                            throw new Error(`plugin "${name}" has active runtime lease(s): ${leases
+                                .map((lease) => lease.leaseId)
+                                .join(", ")}; stop its managed services or CLI commands before updating`);
+                        }
+                        const idRoot = ensureDirectDirectory(storage.installationsRoot, name, "plugin id directory");
+                        const installationId = randomUUID();
+                        finalPath = join(idRoot, installationId);
+                        const marker = promotionMarkerPath(idRoot, installationId);
+                        writePromotionMarker(marker);
+                        try {
+                            renameSync(stagedPackage, finalPath);
+                        }
+                        catch (error) {
+                            rmSync(marker, { force: true });
+                            finalPath = undefined;
+                            throw error;
+                        }
+                        progress(`staged validated plugin "${name}" → ${finalPath}`);
+                        upsertPlugin({
+                            name,
+                            spec: storedSpec,
+                            source,
+                            version: promoted.version,
+                            installPath: finalPath,
+                            manifest: preparedManifest,
+                            integrity: promoted.integrity,
+                            grants,
+                            enabled: current?.enabled,
+                        });
+                    }).immediate();
+                    registryUpdated = true;
+                    if (existing?.installPath && existing.installPath !== finalPath) {
+                        progress("retained superseded installation until the daemon switches versions");
+                    }
+                    progress(`installed plugin "${name}"${promoted.version ? `@${promoted.version}` : ""}`);
+                    return {
+                        name,
+                        source,
+                        ...(promoted.version ? { version: promoted.version } : {}),
+                    };
+                }
+                finally {
+                    cleanup();
+                }
+            },
+            discard: () => {
+                if (consumed)
+                    return;
+                consumed = true;
+                cleanup();
+            },
+        };
+    }
+    catch (error) {
+        if (!registryUpdated && finalPath) {
+            removeOwnedInstallation(storage.installationsRoot, basename(dirname(finalPath)), finalPath);
+        }
+        rmSync(transactionDir, { recursive: true, force: true });
+        throw error;
+    }
 }
-/** Package name from an npm spec, dropping any version range (`x@^1` → `x`). */
-function npmPackageName(spec) {
-    const at = spec.lastIndexOf("@");
-    return at > 0 ? spec.slice(0, at) : spec;
+/**
+ * Remove the registry row but retain the immutable package until the next
+ * daemon boot. A currently running supervisor may still be executing it.
+ */
+export async function uninstallPlugin(name, onProgress = () => { }) {
+    const progress = safeProgress(onProgress);
+    let record;
+    const removed = db().transaction(() => {
+        record = getPlugin(name);
+        if (!record)
+            return false;
+        const leases = activeRuntimeLeases(name, ensureStorageRoots().installationsRoot);
+        if (leases.length > 0) {
+            throw new Error(`plugin "${name}" has active runtime lease(s): ${leases
+                .map((lease) => lease.leaseId)
+                .join(", ")}; stop its managed services or CLI commands before uninstalling`);
+        }
+        return removePlugin(name);
+    }).immediate();
+    if (!removed || !record)
+        return false;
+    if (record.installPath)
+        progress(`retained active package until the daemon stops using it`);
+    progress(`uninstalled plugin "${name}"`);
+    return true;
 }
 /**
- * Install (or re-install) a plugin from an npm spec or a local directory.
- *  - **local**: copy the package (minus `node_modules`) into `~/.rynx/plugins/<name>`
- *    and load it there. The plugin must be self-contained — it bundles its deps at
- *    build time (incl. the unpublished workspace `@rynx-ai/core`) and declares a
- *    `rynx.plugin` entry; the daemon installs nothing.
- *  - **npm**: `npm install` into `~/.rynx/plugins` (deps resolved by npm).
+ * Delete inactive immutable versions at a daemon-start safe point.
  *
- * `onConflict` is consulted when a plugin of the same `name` already exists; if it
- * returns false the install is aborted with `{ skipped: true }` (nothing changes).
- * `onProgress` streams human-readable lines.
+ * A short grace window prevents a concurrently materializing install (renamed
+ * just before its registry transaction) from being mistaken for an orphan.
  */
-export async function installPlugin(spec, onProgress = () => { }, opts = {}) {
-    const source = detectSource(spec);
-    let pkgDir;
-    let storedSpec;
-    if (source === "local") {
-        const srcDir = toLocalDir(spec);
-        if (!existsSync(join(srcDir, "package.json")))
-            throw new Error(`no package.json at ${srcDir}`);
-        const name = (await importPluginManifest(srcDir))?.name;
-        if (!name)
-            throw new Error(`package at ${srcDir} has no valid \`plugin\` export`);
-        if (await declined(name, opts.onConflict))
-            return { name, source, skipped: true };
-        const dest = join(pluginsDir(), name);
-        ensurePluginsRoot(pluginsDir());
-        rmSync(dest, { recursive: true, force: true });
-        // A self-contained plugin bundles its deps, so node_modules is never copied.
-        cpSync(srcDir, dest, { recursive: true, filter: (p) => basename(p) !== "node_modules" });
-        onProgress(`copied local plugin "${name}" → ${dest}`);
-        pkgDir = dest;
-        storedSpec = dest;
-    }
-    else {
-        const dir = pluginsDir();
-        ensurePluginsRoot(dir);
-        onProgress(`npm install ${spec}`);
-        await runNpm(["install", spec, "--prefix", dir, "--no-audit", "--no-fund", "--save"], onProgress, opts.signal);
-        storedSpec = npmPackageName(spec);
-        pkgDir = pluginPkgDir({ source, spec: storedSpec });
-        const name = (await importPluginManifest(pkgDir))?.name;
-        if (!name)
-            throw new Error(`package at ${pkgDir} has no valid \`plugin\` export`);
-        if (await declined(name, opts.onConflict))
-            return { name, source, skipped: true };
-    }
-    const manifest = await importPluginManifest(pkgDir);
-    if (!manifest || typeof manifest.name !== "string" || !manifest.name) {
-        throw new Error(`package at ${pkgDir} has no valid \`plugin\` export`);
-    }
-    const version = readVersion(pkgDir);
-    upsertPlugin({ name: manifest.name, spec: storedSpec, source, version });
-    onProgress(`installed plugin "${manifest.name}"${version ? `@${version}` : ""}`);
-    return { name: manifest.name, source, version };
-}
-/** A same-named plugin already exists and `onConflict` says don't overwrite. */
-async function declined(name, onConflict) {
-    if (!onConflict)
-        return false;
-    const existing = getPlugin(name);
-    if (!existing)
-        return false;
-    return !(await onConflict(existing));
+export function pruneInactivePluginInstallations({ minAgeMs = 60_000, stagingMinAgeMs = DEFAULT_STAGING_GC_AGE_MS, now = Date.now(), } = {}) {
+    const { stagingRoot, installationsRoot } = ensureStorageRoots();
+    const minimumAge = Math.max(0, minAgeMs);
+    const removed = [];
+    pruneStagingTransactions(stagingRoot, Math.max(0, stagingMinAgeMs), now, removed);
+    for (const pluginId of readdirSync(installationsRoot)) {
+        if (!PLUGIN_ID_PATTERN.test(pluginId))
+            continue;
+        db().transaction(() => {
+            const active = new Set();
+            const current = getPlugin(pluginId);
+            if (current && isRunnablePluginRecord(current))
+                active.add(resolve(current.installPath));
+            for (const lease of activeRuntimeLeases(pluginId, installationsRoot)) {
+                active.add(resolve(lease.installPath));
+            }
+            const idRoot = join(installationsRoot, pluginId);
+            let idStat;
+            try {
+                idStat = lstatSync(idRoot);
+            }
+            catch {
+                return;
+            }
+            if (!idStat.isDirectory() || idStat.isSymbolicLink())
+                return;
+            const entries = readdirSync(idRoot);
+            for (const installationId of entries) {
+                if (!INSTALLATION_ID_PATTERN.test(installationId))
+                    continue;
+                const candidate = join(idRoot, installationId);
+                if (active.has(resolve(candidate)))
+                    continue;
+                let candidateStat;
+                try {
+                    candidateStat = lstatSync(candidate);
+                }
+                catch {
+                    continue;
+                }
+                if (!candidateStat.isDirectory() ||
+                    candidateStat.isSymbolicLink() ||
+                    now - promotionTimestampMs(idRoot, installationId, candidateStat.ctimeMs) < minimumAge) {
+                    continue;
+                }
+                if (removeOwnedInstallation(installationsRoot, pluginId, candidate)) {
+                    removed.push(candidate);
+                }
+            }
+            for (const entry of entries) {
+                const installationId = promotionMarkerInstallationId(entry);
+                if (!installationId || existsSync(join(idRoot, installationId)))
+                    continue;
+                const marker = join(idRoot, entry);
+                try {
+                    const stat = lstatSync(marker);
+                    if (stat.isFile() &&
+                        !stat.isSymbolicLink() &&
+                        now - stat.mtimeMs >= minimumAge) {
+                        rmSync(marker, { force: true });
+                    }
+                }
+                catch {
+                    // A concurrently removed orphan marker needs no further work.
+                }
+            }
+        }).immediate();
+    }
+    return removed;
 }
-/** Uninstall a plugin: drop its record, npm-uninstall if applicable, refresh catalog. */
-export async function uninstallPlugin(name, onProgress = () => { }) {
-    const rec = getPlugin(name);
-    if (!rec)
-        return false;
-    if (rec.source === "npm") {
+function activeRuntimeLeases(pluginId, installationsRoot) {
+    const dataDir = join(rynxHome(), "plugin-data", pluginId);
+    return readPluginRuntimeLeases(dataDir).filter((lease) => {
+        if (lease.pluginId !== pluginId)
+            return false;
+        const invocationPid = pluginCliInvocationLeasePid(lease.leaseId);
+        if (invocationPid !== undefined && !isProcessAlive(invocationPid)) {
+            removePluginRuntimeLease(dataDir, lease.leaseId);
+            return false;
+        }
+        const candidate = resolve(lease.installPath);
+        if (dirname(candidate) !== join(installationsRoot, pluginId) ||
+            !INSTALLATION_ID_PATTERN.test(basename(candidate))) {
+            return false;
+        }
         try {
-            await runNpm(["uninstall", rec.spec, "--prefix", pluginsDir(), "--no-audit", "--no-fund"], onProgress);
+            const stat = lstatSync(candidate);
+            return stat.isDirectory() && !stat.isSymbolicLink() && realpathSync(candidate) === candidate;
         }
-        catch (error) {
-            onProgress(`npm uninstall warning: ${messageOf(error)}`);
+        catch {
+            return false;
         }
+    });
+}
+function isProcessAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
     }
-    else {
-        // local: remove the copied package dir — but only if it lives under our plugins
-        // root (older records may point at an in-place source tree; never delete that).
-        const dir = pluginPkgDir(rec);
-        if (dirname(dir) === pluginsDir()) {
-            try {
-                rmSync(dir, { recursive: true, force: true });
-                onProgress(`removed ${dir}`);
-            }
-            catch (error) {
-                onProgress(`remove warning: ${messageOf(error)}`);
+    catch (error) {
+        return error.code === "EPERM";
+    }
+}
+function samePluginGeneration(before, current) {
+    if (!before || !current)
+        return before === current;
+    return JSON.stringify(before) === JSON.stringify(current);
+}
+function cloneManifest(manifest) {
+    return JSON.parse(JSON.stringify(manifest));
+}
+function clonePluginRecord(record) {
+    return {
+        ...record,
+        ...(record.manifest ? { manifest: cloneManifest(record.manifest) } : {}),
+        grants: [...record.grants],
+    };
+}
+function writeStagingOwner(transactionDir) {
+    writeFileSync(join(transactionDir, STAGING_OWNER_FILE), `${JSON.stringify({ schemaVersion: 1, pid: process.pid, createdAt: new Date().toISOString() })}\n`, { encoding: "utf8", mode: 0o600, flag: "wx" });
+}
+function pruneStagingTransactions(stagingRoot, minAgeMs, now, removed) {
+    for (const entry of readdirSync(stagingRoot)) {
+        if (!STAGING_TRANSACTION_PATTERN.test(entry))
+            continue;
+        const candidate = join(stagingRoot, entry);
+        try {
+            const stat = lstatSync(candidate);
+            if (!stat.isDirectory() ||
+                stat.isSymbolicLink() ||
+                dirname(realpathSync(candidate)) !== realpathSync(stagingRoot)) {
+                continue;
             }
+            const owner = readStagingOwner(candidate);
+            if (owner?.pid && isProcessAlive(owner.pid))
+                continue;
+            const createdAt = owner?.createdAtMs ?? Math.max(stat.ctimeMs, stat.mtimeMs);
+            if (now - createdAt < minAgeMs)
+                continue;
+            rmSync(candidate, { recursive: true, force: true });
+            removed.push(candidate);
+        }
+        catch {
+            // Invalid or concurrently removed staging data is never followed.
         }
     }
-    removePlugin(name);
-    onProgress(`uninstalled plugin "${name}"`);
-    return true;
 }
-function ensurePluginsRoot(dir) {
-    mkdirSync(dir, { recursive: true });
-    const pkg = join(dir, "package.json");
-    if (!existsSync(pkg)) {
-        writeFileSync(pkg, `${JSON.stringify({ name: "rynx-plugins", private: true, version: "0.0.0" }, null, 2)}\n`);
+function readStagingOwner(transactionDir) {
+    const file = join(transactionDir, STAGING_OWNER_FILE);
+    try {
+        const stat = lstatSync(file);
+        if (!stat.isFile() || stat.isSymbolicLink() || stat.size > MAX_HOST_MARKER_BYTES)
+            return undefined;
+        const parsed = JSON.parse(readFileSync(file, "utf8"));
+        if (parsed.schemaVersion !== 1 ||
+            !Number.isSafeInteger(parsed.pid) ||
+            Number(parsed.pid) <= 0 ||
+            typeof parsed.createdAt !== "string" ||
+            !Number.isFinite(Date.parse(parsed.createdAt))) {
+            return undefined;
+        }
+        return { pid: Number(parsed.pid), createdAtMs: stat.mtimeMs };
+    }
+    catch {
+        return undefined;
     }
 }
-function readVersion(pkgDir) {
+function promotionMarkerPath(idRoot, installationId) {
+    return join(idRoot, `${installationId}${PROMOTION_MARKER_SUFFIX}`);
+}
+function writePromotionMarker(marker) {
+    writeFileSync(marker, `${JSON.stringify({ schemaVersion: 1, promotedAt: new Date().toISOString() })}\n`, { encoding: "utf8", mode: 0o600, flag: "wx" });
+}
+function promotionTimestampMs(idRoot, installationId, conservativeFallback) {
     try {
-        return JSON.parse(readFileSync(join(pkgDir, "package.json"), "utf8"))
-            .version;
+        const stat = lstatSync(promotionMarkerPath(idRoot, installationId));
+        if (stat.isFile() && !stat.isSymbolicLink() && stat.size <= MAX_HOST_MARKER_BYTES) {
+            return stat.mtimeMs;
+        }
     }
     catch {
-        return undefined;
+        // Installations predating promotion markers fall back to rename-sensitive ctime.
     }
+    return conservativeFallback;
 }
-function runNpm(args, onProgress, signal) {
-    return new Promise((resolveDone, reject) => {
-        const child = spawn("npm", args, { stdio: ["ignore", "pipe", "pipe"] });
-        const abort = () => child.kill();
-        signal?.addEventListener("abort", abort, { once: true });
-        const onData = (buf) => {
-            for (const line of buf.toString().split(/\r?\n/)) {
-                if (line.trim())
-                    onProgress(line);
-            }
-        };
-        child.stdout?.on("data", onData);
-        child.stderr?.on("data", onData);
-        child.on("error", reject);
-        child.on("close", (code) => {
-            signal?.removeEventListener("abort", abort);
-            if (code === 0)
-                resolveDone();
-            else
-                reject(new Error(`npm exited with code ${code ?? "null"}`));
-        });
-    });
+function promotionMarkerInstallationId(entry) {
+    const match = /^([0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12})\.rynx-promoted$/i.exec(entry);
+    return match?.[1];
+}
+function ensureStorageRoots() {
+    const configuredRoot = resolve(pluginsDir());
+    mkdirSync(configuredRoot, { recursive: true, mode: 0o700 });
+    const root = realpathSync(configuredRoot);
+    return {
+        stagingRoot: ensureDirectDirectory(root, "staging", "plugin staging directory"),
+        installationsRoot: ensureDirectDirectory(root, "installed", "plugin installations directory"),
+    };
+}
+/** Create/validate one non-symlink direct child of a canonical parent. */
+function ensureDirectDirectory(parent, child, label) {
+    const path = join(parent, child);
+    if (!existsSync(path))
+        mkdirSync(path, { mode: 0o700 });
+    const stat = lstatSync(path);
+    if (!stat.isDirectory() || stat.isSymbolicLink()) {
+        throw new Error(`${label} must be a host-owned directory, not a symlink`);
+    }
+    const real = realpathSync(path);
+    if (dirname(real) !== realpathSync(parent)) {
+        throw new Error(`${label} resolves outside its host-owned parent`);
+    }
+    return real;
+}
+/**
+ * Delete only `<installations>/<validated-id>/<host UUID>`.
+ * Legacy paths, source directories, traversal strings, and symlinks are kept.
+ */
+function removeOwnedInstallation(installationsRoot, pluginId, installPath) {
+    try {
+        if (!PLUGIN_ID_PATTERN.test(pluginId))
+            return false;
+        const root = realpathSync(installationsRoot);
+        const idRoot = join(root, pluginId);
+        const candidate = resolve(installPath);
+        if (dirname(candidate) !== idRoot || !INSTALLATION_ID_PATTERN.test(basename(candidate))) {
+            return false;
+        }
+        const idStat = lstatSync(idRoot);
+        const candidateStat = lstatSync(candidate);
+        if (!idStat.isDirectory() ||
+            idStat.isSymbolicLink() ||
+            !candidateStat.isDirectory() ||
+            candidateStat.isSymbolicLink()) {
+            return false;
+        }
+        if (realpathSync(idRoot) !== idRoot || realpathSync(candidate) !== candidate)
+            return false;
+        rmSync(candidate, { recursive: true, force: true });
+        rmSync(promotionMarkerPath(idRoot, basename(candidate)), { force: true });
+        return true;
+    }
+    catch {
+        return false;
+    }
 }
-function messageOf(error) {
-    return error instanceof Error ? error.message : String(error);
+function safeProgress(callback) {
+    return (line) => {
+        try {
+            callback(line);
+        }
+        catch {
+            /* progress reporting must never change installation state */
+        }
+    };
 }