@elementspanel/epanel-plugin-instance 1.0.5 → 1.0.7

package/daemon/backend/index.cjs

@@ -226,9 +226,26 @@ function commandStringToArray(cmd) {
 
 Object.defineProperty(exports, "__esModule", ({ value: true }));
 exports.ChildProcessAdapter = void 0;
+exports.instanceProcessHost = instanceProcessHost;
+exports.spawnInstanceProcess = spawnInstanceProcess;
 exports.waitForSpawn = waitForSpawn;
 const events_1 = __webpack_require__("events");
 const mcsmanager_common_1 = __webpack_require__("../common/src/index.ts");
+const INSTANCE_HOST = Symbol.for("elementspanel.instance-process-host");
+function instanceProcessHost() {
+    return globalThis[INSTANCE_HOST];
+}
+function spawnInstanceProcess(instance, fallback, file, args, options, metadata = {}) {
+    const host = instanceProcessHost();
+    return host
+        ? host.spawn(instance.instanceUuid, file, args, options, {
+            startTimestamp: instance.startTimestamp,
+            startCount: instance.startCount,
+            autoRestartCount: instance.autoRestartCount,
+            ...metadata
+        })
+        : fallback(file, args, options);
+}
 /** spawn() reports failures asynchronously, including a missing executable. */
 function waitForSpawn(process) {
     return new Promise((resolve, reject) => {
@@ -266,7 +283,9 @@ class ChildProcessAdapter extends events_1.EventEmitter {
         super();
         this.child = child;
         this.pid = child.pid;
-        child.once("close", () => { this.closed = true; });
+        child.once("close", () => {
+            this.closed = true;
+        });
         // close follows the final stdout/stderr data; exit can arrive before it.
         child.on("close", this.onExit);
         child.on("error", this.onError);
@@ -292,6 +311,9 @@ class ChildProcessAdapter extends events_1.EventEmitter {
         if (this.pid)
             return (0, mcsmanager_common_1.killProcess)(this.pid, this.child, signal);
     }
+    snapshot(metadata) {
+        this.child.setMetadata?.(metadata);
+    }
     destroy() {
         if (this.disposed)
             return;
@@ -326,6 +348,7 @@ class ChildProcessAdapter extends events_1.EventEmitter {
             this.child.stdin?.destroy();
             this.child.stdout?.destroy();
             this.child.stderr?.destroy();
+            this.child.release?.();
         }
     }
 }
@@ -1030,20 +1053,19 @@ class GeneralStartCommand extends start_1.default {
             instance.println("INFO", (0, i18n_1.$t)("TXT_CODE_ba09da46", { name: runAsConfig.runAsName }));
         }
         // create child process
-        const subProcess = (0, child_process_1.spawn)(commandExeFile, commandParameters, {
+        const subProcess = (0, process_adapter_1.spawnInstanceProcess)(instance, child_process_1.spawn, commandExeFile, commandParameters, {
             ...runAsConfig,
             cwd: instance.absoluteCwdPath(),
             stdio: "pipe",
             windowsHide: true,
             env: instance.generateEnv(),
-            // Do not detach the child process;
-            // otherwise, an abnormal exit of the parent process may cause the child process to continue running,
-            // leading to an abnormal instance state.
             detached: false
         });
         const processAdapter = new process_adapter_1.ChildProcessAdapter(subProcess);
         try {
             await (0, process_adapter_1.waitForSpawn)(subProcess);
+            processAdapter.pid = subProcess.pid;
+            subProcess.setMetadata?.({ pid: subProcess.pid });
             instance.started(processAdapter);
         }
         catch (error) {
@@ -1470,17 +1492,14 @@ class PtyStartCommand extends start_1.default {
         }
         instance.println("INFO", "> " + commandList.join(" "));
         // create pty child process
-        const subProcess = (0, child_process_1.spawn)(const_1.PTY_PATH, ptyParameter, {
+        const subProcess = (0, process_adapter_1.spawnInstanceProcess)(instance, child_process_1.spawn, const_1.PTY_PATH, ptyParameter, {
             ...runAsConfig,
             cwd: path_1.default.dirname(const_1.PTY_PATH),
             stdio: "pipe",
             windowsHide: true,
             env: instance.generateEnv(),
-            // Do not detach the child process;
-            // otherwise, an abnormal exit of the parent process may cause the child process to continue running,
-            // leading to an abnormal instance state.
             detached: false
-        });
+        }, { pipeName });
         const processAdapter = new GoPtyProcessAdapter(subProcess, subProcess.pid, pipeName);
         try {
             const [, config] = await Promise.all([
@@ -1488,6 +1507,7 @@ class PtyStartCommand extends start_1.default {
                 this.readPtySubProcessConfig(subProcess)
             ]);
             processAdapter.pid = config.pid;
+            subProcess.setMetadata?.({ pid: config.pid });
             if (subProcess.exitCode !== null || subProcess.signalCode !== null)
                 throw new StartupError((0, i18n_1.$t)("TXT_CODE_pty_start.instanceStartErr"));
             instance.started(processAdapter);
@@ -1547,6 +1567,17 @@ class AbsStartCommand extends command_1.default {
         // Claim the state before the first await so two starts cannot both proceed.
         instance.setLock(true);
         instance.status(instance_1.default.STATUS_STARTING);
+        const starting = this.start(instance);
+        instance.starting = starting;
+        try {
+            return await starting;
+        }
+        finally {
+            instance.starting = undefined;
+            instance.setLock(false);
+        }
+    }
+    async start(instance) {
         try {
             if (!fs_extra_1.default.existsSync(instance.absoluteCwdPath())) {
                 await fs_extra_1.default.mkdirs(instance.absoluteCwdPath());
@@ -1595,9 +1626,6 @@ class AbsStartCommand extends command_1.default {
             instance.startTimestamp = 0;
             instance.failure(error);
         }
-        finally {
-            instance.setLock(false);
-        }
     }
 }
 exports["default"] = AbsStartCommand;
@@ -2138,6 +2166,7 @@ class Instance extends events_1.EventEmitter {
     };
     watchers = new Map();
     process;
+    starting;
     outputLoopTask;
     outputBuffer;
     stopping;
@@ -2336,9 +2365,22 @@ class Instance extends events_1.EventEmitter {
     }
     // function that must be executed after the instance starts
     // Trigger the open event and bind the data and exit events, etc.
-    started(process) {
-        this.startTimestamp = this.config.lastDatetime = Date.now();
-        this.userRequestedStop = false;
+    started(process, previous) {
+        this.startTimestamp = this.config.lastDatetime = previous?.startTimestamp || Date.now();
+        if (previous) {
+            this.startCount = previous.startCount;
+            this.autoRestartCount = previous.autoRestartCount;
+        }
+        this.userRequestedStop = previous?.userRequestedStop ?? false;
+        if (this.userRequestedStop)
+            this.ignoreEventTaskOnce();
+        process.snapshot?.({
+            pid: Number(process.pid),
+            startTimestamp: this.startTimestamp,
+            startCount: this.startCount,
+            autoRestartCount: this.autoRestartCount,
+            userRequestedStop: this.userRequestedStop
+        });
         const outputCode = this.config.terminalOption.pty ? "utf-8" : this.config.oe;
         process.on("data", (text) => {
             this.pushOutput(iconv_lite_1.default.decode(text, outputCode));
@@ -2442,6 +2484,7 @@ class Instance extends events_1.EventEmitter {
         this.stopOutputLoop();
         this.reloading = true;
         this.watchers.clear();
+        await this.starting?.catch(() => { });
         await this.lifeCycleTaskManager.clearLifeCycleTask();
     }
     async resumeAfterReload(dispatcher) {
@@ -2479,6 +2522,7 @@ class Instance extends events_1.EventEmitter {
     }
     setUserRequestedStop(value) {
         this.userRequestedStop = value;
+        this.process?.snapshot?.({ userRequestedStop: value });
     }
     getUserRequestedStop() {
         return this.userRequestedStop;
@@ -2995,6 +3039,17 @@ function apply(ctx) {
     let preserving = false;
     let subsystem;
     let disposeSchedules;
+    let initializing;
+    ctx.on("process/starting", async () => {
+        if (!initializing)
+            throw new Error("Instance services failed to initialize.");
+        await initializing;
+        await subsystem?.waitForTakeover();
+    });
+    ctx.on("process/restarting", async () => {
+        disposeSchedules?.();
+        await subsystem?.prepareForRestart();
+    });
     ctx.on("plugins/reloading", async () => {
         const inventory = ctx.get("plugins")?.inventory();
         preserving = inventory?.some((plugin) => plugin.id === "instance" && plugin.enabled) ?? true;
@@ -3009,7 +3064,11 @@ function apply(ctx) {
     // are available on the next turn rather than synchronously in this function.
     // Restoring instances before that point makes the legacy dispatcher read
     // missing `presets` and `instanceLifecycle` services and emit warnings.
-    ctx.inject(["tasks", "instanceLifecycle", "presets", "schedules"], async (instanceCtx) => {
+    ctx.inject(["tasks", "instanceLifecycle", "presets", "schedules"], (instanceCtx) => {
+        initializing = initialize(instanceCtx);
+        return initializing;
+    });
+    async function initialize(instanceCtx) {
         // The modules are required only after the context has been set and the
         // instance registries are ready. Keeping these synchronous requires keeps
         // webpack's output self-contained and avoids a second copy of the context.
@@ -3063,7 +3122,12 @@ function apply(ctx) {
             await disposeInstanceEvents?.();
             InstanceControlSubsystem.dispose();
             router_1.routerApp.dispose();
-            if ((preserving || recovering) && !runtime.stopping && ctx.root.scope.isActive) {
+            if (runtime.restarting) {
+                // The launcher owns general/PTY processes; Docker is reattached at
+                // startup. Disposing adapters here would terminate those live owners.
+                await InstanceSubsystem.prepareForRestart();
+            }
+            else if ((preserving || recovering) && !runtime.stopping && ctx.root.scope.isActive) {
                 await InstanceSubsystem.suspendForReload();
                 retain();
             }
@@ -3161,7 +3225,7 @@ function apply(ctx) {
             // Also allow recovery by enabling/retrying only the instance plugin.
             instanceCtx.on("ready", resume);
         }
-    });
+    }
 }
 
 
@@ -5551,14 +5615,19 @@ function setPluginContext(value) {
             context: value,
             settings: value.settings,
             storage: value.storage,
-            stopping: false
+            stopping: false,
+            restarting: false
         };
         host[INSTANCE_RUNTIME] = runtime = state;
+        host.on("process/restarting", () => {
+            state.restarting = true;
+        });
         host.on("dispose", async () => {
             state.stopping = true;
             // A replacement may fail before it can claim the retained processes.
             // The daemon still owns them and must stop them during real shutdown.
-            await state.handover?.shutdown();
+            if (!state.restarting)
+                await state.handover?.shutdown();
             state.handover = undefined;
         });
     }
@@ -7356,6 +7425,7 @@ const sleep_1 = __webpack_require__("../../plugins/instance/daemon/src/backend/u
 const log_1 = __importDefault(__webpack_require__("../../plugins/instance/daemon/src/backend/service/log.ts"));
 const system_instance_control_1 = __importDefault(__webpack_require__("../../plugins/instance/daemon/src/backend/service/system_instance_control.ts"));
 const takeover_container_1 = __importDefault(__webpack_require__("../../plugins/instance/daemon/src/backend/service/takeover_container.ts"));
+const takeover_processes_1 = __importDefault(__webpack_require__("../../plugins/instance/daemon/src/backend/service/takeover_processes.ts"));
 class InstanceSubsystem extends events_1.default {
     GLOBAL_INSTANCE = "__MCSM_GLOBAL_INSTANCE__";
     GLOBAL_INSTANCE_UUID = "global0001";
@@ -7464,14 +7534,26 @@ class InstanceSubsystem extends events_1.default {
             processType: globalConfig.processType
         }, true, // allow persistence
         this.GLOBAL_INSTANCE_UUID);
-        this.takeover = (0, takeover_container_1.default)(() => !this.startupCancelled).catch((error) => {
-            const reason = error.message || error;
-            if (typeof reason == "string" && reason.includes("connect ENOENT")) {
-                return;
+        this.takeover = (async () => {
+            await (0, takeover_processes_1.default)(() => !this.startupCancelled);
+            try {
+                await (0, takeover_container_1.default)(() => !this.startupCancelled);
             }
-            log_1.default.error(`${(0, i18n_1.$t)("TXT_CODE_8d4c8f7e")}: ${reason}`);
-        });
-        void this.takeover.then(() => this.autoStart());
+            catch (error) {
+                const reason = error.message || error;
+                if (typeof reason == "string" && reason.includes("connect ENOENT"))
+                    return;
+                log_1.default.error(`${(0, i18n_1.$t)("TXT_CODE_8d4c8f7e")}: ${reason}`);
+            }
+        })();
+        void this.takeover
+            .then(() => {
+            // A worker replacement must also preserve intentionally stopped
+            // instances, even when their next full launcher startup is automatic.
+            if (process.env.EPANEL_RESTARTED !== "1")
+                return this.autoStart();
+        })
+            .catch((error) => log_1.default.error(error));
     }
     createInstance(cfg, persistence = true, uuid) {
         const newUuid = uuid || (0, uuid_1.v4)().replace(/-/gim, "");
@@ -7546,6 +7628,22 @@ class InstanceSubsystem extends events_1.default {
         await Promise.all([...this.instances.values()].map((instance) => instance.suspendForReload()));
         await this.takeover;
     }
+    async waitForTakeover() {
+        await this.takeover;
+    }
+    async prepareForRestart() {
+        await this.suspendForReload();
+        for (const instance of this.instances.values()) {
+            system_storage_1.default.store("InstanceConfig", instance.instanceUuid, instance.config);
+            instance.process?.snapshot?.({
+                pid: Number(instance.process.pid),
+                startTimestamp: instance.startTimestamp,
+                startCount: instance.startCount,
+                autoRestartCount: instance.autoRestartCount,
+                userRequestedStop: instance.getUserRequestedStop()
+            });
+        }
+    }
     /** Transfer the existing owners, including ordinary child/PTY/Docker handles. */
     adoptInstances(instances) {
         this.startupCancelled = true;
@@ -8131,6 +8229,46 @@ async function takeoverContainer(isActive = () => true) {
 }
 
 
+/***/ },
+
+/***/ "../../plugins/instance/daemon/src/backend/service/takeover_processes.ts"
+(__unused_webpack_module, exports, __webpack_require__) {
+
+"use strict";
+
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", ({ value: true }));
+exports["default"] = takeoverProcesses;
+const process_adapter_1 = __webpack_require__("../../plugins/instance/daemon/src/backend/entity/commands/base/process_adapter.ts");
+const pty_start_1 = __webpack_require__("../../plugins/instance/daemon/src/backend/entity/commands/pty/pty_start.ts");
+const system_instance_1 = __importDefault(__webpack_require__("../../plugins/instance/daemon/src/backend/service/system_instance.ts"));
+/** Reattach the launcher's live pipes; do not execute the instance start command. */
+async function takeoverProcesses(isActive = () => true) {
+    const host = (0, process_adapter_1.instanceProcessHost)();
+    if (!host)
+        return;
+    for (const snapshot of await host.list()) {
+        if (!isActive())
+            return;
+        const instance = system_instance_1.default.getInstance(snapshot.id);
+        const child = host.connect(snapshot);
+        const { pipeName, pid } = snapshot.metadata;
+        const adapter = pipeName
+            ? new pty_start_1.GoPtyProcessAdapter(child, pid, pipeName)
+            : new process_adapter_1.ChildProcessAdapter(child);
+        if (!instance || instance.process) {
+            await adapter.destroy();
+            continue;
+        }
+        instance.started(adapter, snapshot.metadata);
+        if (pipeName)
+            adapter.attachOutput();
+    }
+}
+
+
 /***/ },
 
 /***/ "../../plugins/instance/daemon/src/backend/service/version_adapter.ts"
@@ -8634,6 +8772,7 @@ Object.defineProperty(exports, "arrayUnique", ({ enumerable: true, get: function
 __exportStar(__webpack_require__("../common/src/plugin_contract.ts"), exports);
 __exportStar(__webpack_require__("../common/src/plugin_overrides.ts"), exports);
 __exportStar(__webpack_require__("../common/src/plugin_lifecycle.ts"), exports);
+__exportStar(__webpack_require__("../common/src/process_restart.ts"), exports);
 __exportStar(__webpack_require__("../common/src/plugin_revision.ts"), exports);
 __exportStar(__webpack_require__("../common/src/plugin_modules.ts"), exports);
 __exportStar(__webpack_require__("../common/src/plugin_watch.ts"), exports);
@@ -9529,6 +9668,39 @@ async function loadPluginModule(entry, directory, revision) {
 
 "use strict";
 
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
@@ -9547,6 +9719,8 @@ const path_1 = __importDefault(__webpack_require__("path"));
 const module_1 = __webpack_require__("module");
 const plugin_manifest_1 = __webpack_require__("../common/src/plugin_manifest.ts");
 const plugin_contract_1 = __webpack_require__("../common/src/plugin_contract.ts");
+// @ts-ignore Shared by the source runtime and the published npm launcher.
+const npmPlugins = __importStar(__webpack_require__("../../scripts/runtime/npm-plugins.cjs"));
 const PLUGIN_ID = /^[a-z][a-z0-9_-]{1,63}$/;
 const PACKAGE_NAME = /^(?:@[a-z0-9_.-]+\/)?epanel-plugin-[a-z0-9_.-]+$/;
 const VERSION = /^[a-zA-Z0-9][a-zA-Z0-9._+-]{0,63}$/;
@@ -9589,9 +9763,18 @@ function currentProjectRoot(packageRoot = currentPackageRoot()) {
 }
 function npmPluginRoots(options = {}) {
     const packageRoot = path_1.default.resolve(options.packageRoot ?? currentPackageRoot());
+    const projectRoot = path_1.default.resolve(options.projectRoot ?? currentProjectRoot(packageRoot));
+    const host = readJson(path_1.default.join(packageRoot, "package.json"));
+    const side = options.side ||
+        stringValue(objectValue(host?.elementspanel)?.side) ||
+        path_1.default.basename(packageRoot);
     return {
         packageRoot,
-        projectRoot: path_1.default.resolve(options.projectRoot ?? currentProjectRoot(packageRoot))
+        projectRoot,
+        dependencyRoot: path_1.default.dirname(npmPlugins.projectManifestFile(packageRoot, side, {
+            projectRoot,
+            runtimeDirectory: process.env.EPANEL_RUNTIME_ROOT
+        }))
     };
 }
 function projectManifestFile(projectRoot) {
@@ -9619,15 +9802,10 @@ function pluginRecord(pluginId, name, source, packageRoot, directory, folder, ve
 function readPackageEntry(packageRoot, name) {
     // Read package boundaries directly: Node caches require.resolve() paths even
     // after npm moves an installation between nested and hoisted node_modules.
-    let manifestPath;
-    for (const root of [packageRoot, currentProjectRoot(packageRoot)]) {
-        const localRequire = (0, module_1.createRequire)(path_1.default.join(root, "package.json"));
-        manifestPath = (localRequire.resolve.paths(name) || [])
-            .map((directory) => path_1.default.join(directory, name, "package.json"))
-            .find((filename) => fs_extra_1.default.existsSync(filename));
-        if (manifestPath)
-            break;
-    }
+    const localRequire = (0, module_1.createRequire)(path_1.default.join(packageRoot, "package.json"));
+    let manifestPath = (localRequire.resolve.paths(name) || [])
+        .map((directory) => path_1.default.join(directory, name, "package.json"))
+        .find((filename) => fs_extra_1.default.existsSync(filename));
     if (!manifestPath)
         throw new Error(`Missing npm plugin package: ${name}.`);
     manifestPath = fs_extra_1.default.realpathSync(manifestPath);
@@ -9674,83 +9852,26 @@ function recordFromPackage(pluginId, name, source, packageRoot, metadata, side)
 /**
  * Every npm plugin the runtime can load for a side, built-in and project-installed.
  *
- * Built-in package names win over a project mapping for the same id. An explicit
- * project dependency on that same package selects the user's installed version.
- * A project package that does not describe the requested side is skipped instead of failing, which
- * is what lets a two-sided project share one dependency list between sides.
+ * Built-in package names reserve their plugin ids. The side manifest selects
+ * the installed versions; a package without that side is skipped.
  */
 function listNpmPlugins(side, options = {}) {
-    const { packageRoot, projectRoot } = npmPluginRoots(options);
-    const host = readJson(path_1.default.join(packageRoot, "package.json"));
-    if (!host)
-        throw new Error(`Missing runtime package metadata: ${packageRoot}`);
-    const project = path_1.default.resolve(projectRoot) === path_1.default.resolve(packageRoot)
-        ? null
-        : readProjectManifest(projectRoot);
-    const hostMappings = mappingsOf(host);
-    const projectMappings = { ...mappingsOf(project) };
-    for (const name of Object.keys(dependenciesOf(project))) {
-        if (!PACKAGE_NAME.test(name) || Object.values(projectMappings).includes(name))
-            continue;
-        try {
-            const entry = readPackageEntry(projectRoot, name);
-            const id = stringValue(objectValue(entry.metadata.elementspanel)?.id);
-            if (PLUGIN_ID.test(id) && projectMappings[id] === undefined)
-                projectMappings[id] = name;
-        }
-        catch {
-            /* npm may still be writing the package. */
-        }
-    }
-    const mappings = new Map();
-    for (const [pluginId, name] of Object.entries(projectMappings)) {
-        if (!PLUGIN_ID.test(pluginId) || typeof name !== "string" || !PACKAGE_NAME.test(name))
-            continue;
-        mappings.set(pluginId, { name, source: "project" });
-    }
-    for (const [pluginId, name] of Object.entries(hostMappings)) {
-        if (!PLUGIN_ID.test(pluginId) || typeof name !== "string" || !PACKAGE_NAME.test(name))
-            continue;
-        if (dependenciesOf(host)[name] === undefined)
-            continue;
-        mappings.set(pluginId, {
-            name,
-            source: dependenciesOf(project)[name] === undefined ? "bundled" : "project"
-        });
-    }
-    const hostDependencies = dependenciesOf(host);
-    const projectDependencies = dependenciesOf(project);
-    const folders = new Set();
+    const { packageRoot, projectRoot, dependencyRoot } = npmPluginRoots({ ...options, side });
     const records = [];
-    for (const [pluginId, mapping] of mappings) {
-        const declared = hostDependencies[mapping.name] ?? projectDependencies[mapping.name];
-        if (declared === undefined) {
-            if (options.skipInvalid)
-                continue;
-            throw new Error(`Missing npm plugin dependency: ${mapping.name}. Run npm install in the project directory.`);
-        }
-        let entry;
-        try {
-            entry = readPackageEntry(mapping.source === "project" ? projectRoot : packageRoot, mapping.name);
-        }
-        catch (error) {
-            if (options.skipInvalid)
-                continue;
-            throw error;
-        }
-        const record = recordFromPackage(pluginId, mapping.name, mapping.source, entry.root, entry.metadata, side);
+    for (const item of npmPlugins.resolveNpmPlugins(packageRoot, side, {
+        projectRoot,
+        runtimeDirectory: dependencyRoot,
+        skipInvalid: options.skipInvalid
+    })) {
+        const metadata = readJson(path_1.default.join(item.packageRoot, "package.json"));
+        if (!metadata)
+            continue;
+        const record = recordFromPackage(item.id, item.name, item.source, item.packageRoot, metadata, side);
         if (!record) {
-            if (options.skipInvalid || mapping.source === "project")
-                continue;
-            throw new Error(`Invalid ${side ?? "plugin"} entry in npm plugin ${mapping.name}.`);
-        }
-        const folder = record.folder;
-        if (folders.has(folder)) {
             if (options.skipInvalid)
                 continue;
-            throw new Error(`Duplicate npm plugin asset directory: ${folder}.`);
+            throw new Error(`Invalid ${side ?? "plugin"} entry in npm plugin ${item.name}.`);
         }
-        folders.add(folder);
         records.push(record);
     }
     return records;
@@ -9847,10 +9968,9 @@ async function acquireProjectLock(projectRoot) {
         }
     }
 }
-function npmPluginOperationPending() {
-    const { packageRoot, projectRoot } = npmPluginRoots();
-    return (operations.size > 0 ||
-        [packageRoot, projectRoot].some((root) => fs_extra_1.default.existsSync(path_1.default.join(root, LOCK_NAME))));
+function npmPluginOperationPending(side) {
+    const { dependencyRoot } = npmPluginRoots({ side });
+    return operations.size > 0 || fs_extra_1.default.existsSync(path_1.default.join(dependencyRoot, LOCK_NAME));
 }
 function withProjectLock(projectRoot, operation) {
     const key = process.platform === "win32" ? projectRoot.toLowerCase() : projectRoot;
@@ -9885,18 +10005,15 @@ async function installNpmPlugin(options) {
         throw new Error(`Invalid plugin id: ${options.pluginId}`);
     if (!VERSION.test(version))
         throw new Error(`Invalid plugin version: ${version}`);
-    const { packageRoot, projectRoot } = npmPluginRoots(options);
-    return withProjectLock(projectRoot, async () => {
+    const { packageRoot, projectRoot, dependencyRoot } = npmPluginRoots(options);
+    return withProjectLock(dependencyRoot, async () => {
         const host = readJson(path_1.default.join(packageRoot, "package.json"));
         if (!host)
             throw new Error(`Missing runtime package metadata: ${packageRoot}`);
-        const hostId = Object.entries(mappingsOf(host)).find(([, value]) => value === name && dependenciesOf(host)[name] !== undefined)?.[0];
-        const targetRoot = hostId && dependenciesOf(readProjectManifest(projectRoot))[name] === undefined
-            ? packageRoot
-            : projectRoot;
+        const hostId = Object.entries(mappingsOf(host)).find(([, value]) => value === name)?.[0];
+        const targetRoot = dependencyRoot;
         if (options.pluginId &&
             mappingsOf(host)[options.pluginId] &&
-            dependenciesOf(host)[String(mappingsOf(host)[options.pluginId])] !== undefined &&
             mappingsOf(host)[options.pluginId] !== name)
             throw new Error(`BUNDLED:${options.pluginId}`);
         const original = readProjectManifest(targetRoot);
@@ -9925,24 +10042,33 @@ async function installNpmPlugin(options) {
                 "--save-exact",
                 "--no-fund",
                 "--no-audit",
-                "--ignore-scripts"
+                "--ignore-scripts",
+                "--workspaces=false"
             ], targetRoot);
             const entry = readPackageEntry(targetRoot, name);
             const pluginId = options.pluginId || stringValue(objectValue(entry.metadata.elementspanel)?.id);
             if (!PLUGIN_ID.test(pluginId))
                 throw new Error(`Invalid plugin id in ${name}.`);
-            if (mappingsOf(host)[pluginId] &&
-                dependenciesOf(host)[String(mappingsOf(host)[pluginId])] !== undefined &&
-                mappingsOf(host)[pluginId] !== name)
+            if (mappingsOf(host)[pluginId] && mappingsOf(host)[pluginId] !== name)
                 throw new Error(`Plugin id ${pluginId} belongs to a bundled dependency.`);
             if (hostId && pluginId !== hostId)
                 throw new Error(`The package ${name} changed its plugin id from ${hostId} to ${pluginId}.`);
             const mapped = mappingsOf(readProjectManifest(targetRoot))[pluginId];
             if (mapped !== undefined && mapped !== name)
                 throw new Error(`Plugin id ${pluginId} is already installed as ${String(mapped)}.`);
-            const record = recordFromPackage(pluginId, name, targetRoot === packageRoot ? "bundled" : "project", entry.root, entry.metadata, side);
+            const record = recordFromPackage(pluginId, name, hostId ? "bundled" : "project", entry.root, entry.metadata, side);
             if (!record)
                 throw new Error(`The package ${name} does not provide a ${side} plugin named ${pluginId}.`);
+            if (side === "panel") {
+                const expected = objectValue(objectValue(entry.metadata.elementspanel)?.panel)
+                    ?.frontendAssets;
+                const available = objectValue(host.elementspanel)?.frontendAssets;
+                if ((hostId || expected !== undefined) &&
+                    (!Array.isArray(expected) ||
+                        !Array.isArray(available) ||
+                        expected.some((file) => typeof file !== "string" || !available.includes(file))))
+                    throw new Error(`Frontend assets in ${name} do not match this panel. Update the panel or install a matching plugin version.`);
+            }
             if (/^[0-9]/.test(version) && record.version !== version)
                 throw new Error(`The installed package ${name} is ${record.version}, expected ${version}.`);
             if (!process.env.EPANEL_PACKAGE_ROOT &&
@@ -9986,7 +10112,8 @@ async function installNpmPlugin(options) {
                         "--save",
                         "--no-fund",
                         "--no-audit",
-                        "--ignore-scripts"
+                        "--ignore-scripts",
+                        "--workspaces=false"
                     ]
                     : [
                         "--prefix",
@@ -9995,7 +10122,8 @@ async function installNpmPlugin(options) {
                         name,
                         "--no-fund",
                         "--no-audit",
-                        "--ignore-scripts"
+                        "--ignore-scripts",
+                        "--workspaces=false"
                     ], targetRoot);
             }
             catch (rollback) {
@@ -10019,22 +10147,29 @@ async function uninstallNpmPlugin(pluginId, options = {}) {
         throw new Error(`Invalid plugin id: ${pluginId}`);
     if (isEssentialNpmPlugin(pluginId))
         throw new Error(`The essential plugin "${pluginId}" cannot be uninstalled.`);
-    const { packageRoot, projectRoot } = npmPluginRoots(options);
-    return withProjectLock(projectRoot, async () => {
-        const host = readJson(path_1.default.join(packageRoot, "package.json"));
-        const bundledName = mappingsOf(host)[pluginId];
-        const targetRoot = typeof bundledName === "string" &&
-            dependenciesOf(host)[bundledName] !== undefined &&
-            dependenciesOf(readProjectManifest(projectRoot))[bundledName] === undefined
-            ? packageRoot
-            : projectRoot;
+    const { packageRoot, projectRoot, dependencyRoot } = npmPluginRoots(options);
+    return withProjectLock(dependencyRoot, async () => {
+        const targetRoot = dependencyRoot;
         const manifest = readProjectManifest(targetRoot);
         const name = mappingsOf(manifest)[pluginId] ??
-            listNpmPlugins(undefined, { packageRoot, projectRoot, skipInvalid: true }).find((item) => item.pluginId === pluginId)?.name;
+            listNpmPlugins(options.side, { packageRoot, projectRoot, skipInvalid: true }).find((item) => item.pluginId === pluginId)?.name;
         if (typeof name !== "string" || !PACKAGE_NAME.test(name))
             return null;
-        const record = listNpmPlugins(undefined, { packageRoot, projectRoot, skipInvalid: true }).find((item) => item.pluginId === pluginId);
-        await runNpm(["--prefix", targetRoot, "uninstall", name, "--no-fund", "--no-audit", "--ignore-scripts"], targetRoot);
+        const record = listNpmPlugins(options.side, {
+            packageRoot,
+            projectRoot,
+            skipInvalid: true
+        }).find((item) => item.pluginId === pluginId);
+        await runNpm([
+            "--prefix",
+            targetRoot,
+            "uninstall",
+            name,
+            "--no-fund",
+            "--no-audit",
+            "--ignore-scripts",
+            "--workspaces=false"
+        ], targetRoot);
         const updated = readProjectManifest(targetRoot);
         const plugins = { ...mappingsOf(updated) };
         delete plugins[pluginId];
@@ -10208,11 +10343,11 @@ const plugin_npm_1 = __webpack_require__("../common/src/plugin_npm.ts");
 /** Poll package boundaries, allowing npm to finish replacing files before reconciliation. */
 function watchNpmPlugins(ctx, side, reload, changed) {
     const stamp = () => {
-        const { packageRoot, projectRoot } = (0, plugin_npm_1.npmPluginRoots)();
+        const { packageRoot, dependencyRoot } = (0, plugin_npm_1.npmPluginRoots)({ side });
         if (!node_fs_1.default.existsSync(node_path_1.default.join(packageRoot, "package.json")))
             return "";
         const files = [];
-        for (const root of [packageRoot, projectRoot])
+        for (const root of [packageRoot, dependencyRoot])
             for (const name of [
                 "package.json",
                 "package-lock.json",
@@ -10236,7 +10371,7 @@ function watchNpmPlugins(ctx, side, reload, changed) {
     let candidate = applied;
     let busy = false;
     ctx.setInterval(() => {
-        if (busy || (0, plugin_npm_1.npmPluginOperationPending)())
+        if (busy || (0, plugin_npm_1.npmPluginOperationPending)(side))
             return;
         try {
             const next = stamp();
@@ -10267,6 +10402,50 @@ function watchNpmPlugins(ctx, side, reload, changed) {
 }
 
 
+/***/ },
+
+/***/ "../common/src/process_restart.ts"
+(__unused_webpack_module, exports) {
+
+"use strict";
+
+Object.defineProperty(exports, "__esModule", ({ value: true }));
+exports.isProcessRestartPending = isProcessRestartPending;
+exports.requestProcessRestart = requestProcessRestart;
+const RESTART = Symbol.for("elementspanel.process.restart");
+function isProcessRestartPending(ctx) {
+    return ctx.root[RESTART]?.pending === true;
+}
+/** The CLI retains instance processes and starts a fresh worker after this one exits. */
+function requestProcessRestart(ctx, settle, ready = async () => { }) {
+    if (isProcessRestartPending(ctx))
+        return true;
+    if (process.env.EPANEL_SUPERVISED !== "1" || !process.connected || !process.send)
+        return false;
+    const state = { pending: true };
+    ctx.root[RESTART] = state;
+    const retainProcesses = () => new Promise((resolve, reject) => process.send({ type: "elementspanel:prepare-restart" }, (error) => error ? reject(error) : resolve()));
+    setImmediate(() => {
+        void (async () => {
+            await ready();
+            // Detach output consumers before cleanup so output and exits during the
+            // restart are retained for the next daemon generation.
+            await retainProcesses();
+            await ctx.parallel("process/restarting");
+            // A pending start can finish while restart hooks are awaiting it.
+            await retainProcesses();
+            await ctx.stop();
+            await settle();
+            process.send({ type: "elementspanel:restart" }, (error) => process.exit(error ? 1 : 0));
+        })().catch((error) => {
+            ctx.logger.error("Failed to restart the process:", error);
+            process.exit(1);
+        });
+    });
+    return true;
+}
+
+
 /***/ },
 
 /***/ "../common/src/process_tools.ts"
@@ -11277,6 +11456,226 @@ module.exports = require("stream/promises");
 "use strict";
 module.exports = require("util");
 
+/***/ },
+
+/***/ "../../scripts/runtime/npm-plugins.cjs"
+(module, __unused_webpack_exports, __webpack_require__) {
+
+const fs = __webpack_require__("node:fs");
+const path = __webpack_require__("node:path");
+const { createRequire } = __webpack_require__("node:module");
+
+const readJson = (filename) => JSON.parse(fs.readFileSync(filename, "utf8"));
+const readOptional = (filename) => {
+  try {
+    return readJson(filename);
+  } catch (error) {
+    if (error.code === "ENOENT") return null;
+    throw error;
+  }
+};
+const validId = /^[a-z][a-z0-9_-]{1,63}$/;
+const validName = /^(?:@[a-z0-9_.-]+\/)?epanel-plugin-[a-z0-9_.-]+$/;
+
+function packageManifest(root, name) {
+  const localRequire = createRequire(path.join(root, "package.json"));
+  const filename = (localRequire.resolve.paths(name) || [])
+    .map((directory) => path.join(directory, name, "package.json"))
+    .find((candidate) => fs.existsSync(candidate));
+  if (!filename) throw new Error(`Missing npm package: ${name}`);
+  return fs.realpathSync(filename);
+}
+
+function within(root, filename) {
+  const relative = path.relative(root, filename);
+  return (
+    relative === "" ||
+    (relative !== ".." && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative))
+  );
+}
+
+function projectRoot(packageRoot) {
+  if (process.env.EPANEL_PROJECT_ROOT) return path.resolve(process.env.EPANEL_PROJECT_ROOT);
+  const parent = path.resolve(packageRoot, "..");
+  if (path.basename(parent) === "core") return path.dirname(parent);
+  // An installed runtime sits at <project>/node_modules/@scope/<side>; the
+  // project itself is three levels above the package. A development checkout
+  // sits below core/ and is handled above.
+  const scope = parent;
+  const nodeModules = path.dirname(scope);
+  if (path.basename(nodeModules) === "node_modules" && path.basename(scope).startsWith("@")) {
+    return path.dirname(nodeModules);
+  }
+  return parent;
+}
+
+function projectManifestFile(packageRoot, side, options = {}) {
+  const selectedSide =
+    side ||
+    readJson(path.join(packageRoot, "package.json")).elementspanel?.side ||
+    path.basename(packageRoot);
+  if (!["panel", "daemon"].includes(selectedSide)) throw new Error("Missing runtime side.");
+  const directory =
+    options.runtimeDirectory ||
+    (!options.projectRoot && process.env.EPANEL_RUNTIME_ROOT) ||
+    path.join(options.projectRoot || projectRoot(packageRoot), selectedSide);
+  return path.join(path.resolve(directory), "package.json");
+}
+
+function mappingOf(manifest) {
+  const plugins = manifest?.elementspanel?.plugins;
+  return plugins && typeof plugins === "object" && !Array.isArray(plugins) ? plugins : {};
+}
+
+function dependenciesOf(manifest) {
+  const dependencies = manifest?.dependencies;
+  return dependencies && typeof dependencies === "object" ? dependencies : {};
+}
+
+/**
+ * Resolve plugins declared in the side's package.json, including hoisted npm
+ * installations. The host catalogue reserves built-in ids without owning their
+ * versions. Other explicitly mapped plugins remain dormant until enabled.
+ * Runtime startup passes skipInvalid so an optional package being removed does
+ * not stop the host; the caller separately validates the small set of core
+ * plugins.
+ */
+function resolveNpmPlugins(packageRoot, side, options = {}) {
+  const skipInvalid = options.skipInvalid === true;
+  const host = readJson(path.join(packageRoot, "package.json"));
+  const selectedSide = side || host.elementspanel?.side || path.basename(packageRoot);
+  const projectFile = projectManifestFile(packageRoot, selectedSide, options);
+  const project = readOptional(projectFile);
+  const dependencyRoot = path.dirname(projectFile);
+
+  // The side manifest owns every dependency; the host only reserves identities.
+  const configured = new Map();
+  for (const [id, name] of Object.entries(mappingOf(project)))
+    configured.set(id, { name, source: "project" });
+  for (const name of Object.keys(dependenciesOf(project))) {
+    if (!validName.test(name) || [...configured.values()].some((item) => item.name === name))
+      continue;
+    try {
+      const metadata = readJson(packageManifest(dependencyRoot, name));
+      const id = metadata.elementspanel?.id;
+      if (validId.test(id) && !configured.has(id))
+        configured.set(id, { name, source: "project", automatic: true });
+    } catch {
+      /* Ignore incomplete npm installations until the next scan. */
+    }
+  }
+  for (const [id, name] of Object.entries(mappingOf(host))) {
+    if (dependenciesOf(project)[name] !== undefined)
+      configured.set(id, {
+        name,
+        source: "bundled",
+        automatic: true
+      });
+    else if (configured.has(id)) {
+      if (!skipInvalid) throw new Error(`Plugin id ${id} belongs to built-in package ${name}.`);
+      configured.delete(id);
+    }
+  }
+
+  const projectDependencies = dependenciesOf(project);
+  const folders = new Set();
+  const records = [];
+
+  for (const [id, mapping] of configured) {
+    const name = mapping.name;
+    if (
+      !validId.test(id) ||
+      typeof name !== "string" ||
+      !validName.test(name) ||
+      projectDependencies[name] === undefined
+    ) {
+      if (skipInvalid) continue;
+      throw new Error(`Invalid npm plugin dependency: ${id}.`);
+    }
+
+    let manifestPath;
+    let failure;
+    try {
+      manifestPath = packageManifest(dependencyRoot, name);
+    } catch (error) {
+      failure = error;
+    }
+    if (!manifestPath) {
+      if (skipInvalid) continue;
+      throw new Error(`Missing npm plugin ${name}. Run npm install in ${dependencyRoot}.`, {
+        cause: failure
+      });
+    }
+    let metadata;
+    try {
+      metadata = readJson(manifestPath);
+    } catch (error) {
+      if (skipInvalid) continue;
+      throw error;
+    }
+    const definition = metadata.elementspanel?.[selectedSide];
+    // A project dependency may only ship one side; the other side simply does
+    // not see it. A built-in plugin declared by the runtime must carry this side.
+    if (!definition) {
+      if (mapping.source === "project" || skipInvalid) continue;
+      throw new Error(`Invalid ${selectedSide} entry in npm plugin ${name}.`);
+    }
+    const pluginRoot = path.dirname(manifestPath);
+    if (
+      typeof definition.directory !== "string" ||
+      typeof definition.folder !== "string" ||
+      !validId.test(definition.folder) ||
+      path.isAbsolute(definition.directory)
+    ) {
+      if (skipInvalid) continue;
+      throw new Error(`Npm plugin entry escapes its package: ${name}.`);
+    }
+    const directory = path.resolve(pluginRoot, definition.directory);
+    if (directory === pluginRoot || !within(pluginRoot, directory)) {
+      if (skipInvalid) continue;
+      throw new Error(`Npm plugin entry escapes its package: ${name}.`);
+    }
+    let entries;
+    try {
+      entries = readJson(path.join(directory, "plugin.json"));
+    } catch (error) {
+      if (skipInvalid) continue;
+      throw error;
+    }
+    if (
+      metadata.elementspanel?.id !== id ||
+      typeof metadata.version !== "string" ||
+      !metadata.version.trim() ||
+      !entries ||
+      typeof entries !== "object" ||
+      Array.isArray(entries)
+    ) {
+      if (skipInvalid) continue;
+      throw new Error(`Invalid npm plugin identity or version in package.json: ${name}.`);
+    }
+    if (folders.has(definition.folder)) {
+      if (skipInvalid) continue;
+      throw new Error(`Duplicate npm plugin asset directory: ${definition.folder}.`);
+    }
+    folders.add(definition.folder);
+    records.push({
+      id,
+      name,
+      version: metadata.version,
+      source: mapping.source,
+      defaultEnabled: mapping.automatic === true || mapping.source !== "project",
+      packageRoot: pluginRoot,
+      directory,
+      folder: definition.folder,
+      dependencies: Object.keys(metadata.dependencies || {})
+    });
+  }
+  return records;
+}
+
+module.exports = { resolveNpmPlugins, projectManifestFile };
+
+
 /***/ },
 
 /***/ "../../scripts/workspace-layout.cjs"