@rynx-ai/daemon 0.1.11-beta.1 → 0.1.11-beta.3

package/dist/plugin-supervisor.js

@@ -1,1143 +1,795 @@
 import { randomUUID } from "node:crypto";
-import path from "node:path";
-import { resolveAllowedRoots, rynxHome, } from "@rynx-ai/core";
-import { PLUGIN_RUNNER_API_VERSION, spawnPluginRunner, } from "@rynx-ai/plugin-runner";
-import { normalizePluginConfig, } from "@rynx-ai/plugin-sdk";
+import { mkdirSync } from "node:fs";
+import { removePluginRuntimeLease, writePluginRuntimeLease, } from "@rynx-ai/plugin-sdk";
+import { spawnPluginRunner, } from "@rynx-ai/plugin-runner";
 import { MAX_PLUGIN_HOST_EVENT_BYTES, PluginHostRpc, } from "./plugin-host-rpc.js";
+import { pluginDataDir, pluginRuntimeCacheDir, } from "./plugin-installer.js";
+import { PLUGIN_HOST_RUNTIME_LEASE_IDS } from "./plugin-host-leases.js";
+import { isBuiltInPluginMarketplace } from "./plugin-marketplace.js";
+import { validatePluginPackageSnapshot } from "./plugin-package.js";
+import { setPluginRuntimeState, } from "./plugin-store.js";
 const DEFAULT_RESTART_BASE_MS = 1_000;
 const MAX_RESTART_DELAY_MS = 30_000;
-const DEFAULT_STABLE_RESET_MS = 60_000;
-const MAX_HOST_EVENT_QUEUE_ITEMS = 64;
-const MAX_HOST_EVENT_QUEUE_BYTES = 8 * 1024 * 1024;
-const MAX_STDERR_LINE_BYTES = 64 * 1024;
-const MAX_STATUS_ERROR_BYTES = 16 * 1024;
-const DEFAULT_READY_TIMEOUT_MS = 15_000;
-const MAX_READY_TIMEOUT_MS = 60_000;
-const RUNTIME_STATUS_POLL_MS = 50;
-const TARGET_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/;
+const STABLE_RESET_MS = 60_000;
+const DEFAULT_HEALTH_POLL_MS = 30_000;
+const [RUNTIME_LEASE_ID, SETTINGS_LEASE_ID] = PLUGIN_HOST_RUNTIME_LEASE_IDS;
 /**
- * Owns isolated plugin child processes and projects their static chat-channel
- * declarations onto trusted host-side ChannelManager handles.
- *
- * There is at most one resident child per enabled plugin. Chat-channel
- * instances are independent desired-state entries inside that child, so
- * stopping the final channel does not tear down the plugin runtime itself.
+ * Supervises exactly one language-neutral runtime process per enabled plugin.
+ * It has no channel-instance API and never interprets plugin-owned state.
  */
 export class PluginSupervisor {
     states = new Map();
-    services;
+    queues = new Map();
     spawnRunner;
-    logger;
+    log;
+    daemonInstanceId;
+    productVersion;
+    cliVersion;
     restartBaseMs;
     restartMaxMs;
-    stableResetMs;
-    daemonInstanceId;
-    runtimeOperations = new Map();
+    healthPollMs;
+    verifyPackage;
+    services;
     disposed = false;
-    constructor(plugins, options) {
+    disposePromise;
+    constructor(records, options = {}) {
         this.services = options.services;
         this.spawnRunner = options.spawnRunner ?? spawnPluginRunner;
-        this.logger = options.log;
-        this.restartBaseMs = Math.min(positiveDelay(options.restartBaseMs, DEFAULT_RESTART_BASE_MS), MAX_RESTART_DELAY_MS);
-        this.restartMaxMs = Math.max(this.restartBaseMs, Math.min(positiveDelay(options.restartMaxMs, MAX_RESTART_DELAY_MS), MAX_RESTART_DELAY_MS));
-        this.stableResetMs = positiveDelay(options.stableResetMs, DEFAULT_STABLE_RESET_MS);
-        this.daemonInstanceId = options.daemonInstanceId?.trim() || randomUUID();
-        for (const record of plugins) {
-            validateRecord(record);
-            if (this.states.has(record.manifest.id)) {
-                throw new Error(`duplicate runnable plugin id: ${record.manifest.id}`);
-            }
-            this.states.set(record.manifest.id, createPluginState(record));
-        }
+        this.log = options.log ?? (() => { });
+        this.daemonInstanceId = options.daemonInstanceId ?? randomUUID();
+        this.productVersion = options.productVersion ?? "development";
+        this.cliVersion = options.cliVersion ?? "development";
+        this.restartBaseMs = options.restartBaseMs ?? DEFAULT_RESTART_BASE_MS;
+        this.restartMaxMs = Math.min(options.restartMaxMs ?? MAX_RESTART_DELAY_MS, MAX_RESTART_DELAY_MS);
+        this.healthPollMs = options.healthPollMs ?? DEFAULT_HEALTH_POLL_MS;
+        this.verifyPackage = options.verifyPackage ?? verifyInstalledPackage;
+        if (!Number.isSafeInteger(this.healthPollMs) || this.healthPollMs <= 0) {
+            throw new Error("plugin health poll interval must be a positive safe integer");
+        }
+        for (const record of records)
+            this.upsertState(record);
     }
-    /** Static channel catalog. Calling this never loads or executes plugin code. */
-    createChannelTypeDescriptors() {
-        const descriptors = [];
-        for (const state of this.states.values()) {
-            for (const contribution of state.record.manifest.contributions?.chatChannels ?? []) {
-                descriptors.push(this.channelDescriptor(state, contribution));
-            }
-        }
-        return descriptors;
-    }
-    /** Bind the trusted host once, after the server composition root constructs it. */
     bindHostServices(services) {
-        this.assertOpen();
         if (this.services)
             throw new Error("plugin host services are already bound");
         this.services = services;
-        return this;
     }
-    /** Cached, non-blocking runner/contribution health for the generic control API. */
-    statusSnapshot() {
-        const plugins = [];
-        for (const state of this.states.values()) {
-            if (state.runner)
-                void this.refreshRuntimeStatus(state).catch(() => undefined);
-            for (const desired of state.desired.values()) {
-                if (state.runner && desired.startedGeneration === state.generation) {
-                    void this.refreshContributionStatus(state, desired).catch(() => undefined);
-                }
-            }
-            const contributions = [...state.desired.values()].map((desired) => ({
-                key: desired.key,
-                target: { ...desired.target },
-                desired: true,
-                ...(desired.startedGeneration === undefined
-                    ? {}
-                    : { generation: desired.startedGeneration }),
-                failureCount: desired.failureCount,
-                status: { ...desired.status },
-            }));
-            plugins.push({
-                pluginId: state.record.manifest.id,
-                runner: {
-                    state: runnerSnapshotState(state, this.disposed),
-                    generation: state.generation,
-                    failureCount: state.failureCount,
-                    ...(state.lastRunnerError ? { lastError: state.lastRunnerError } : {}),
-                },
-                runtimeStatus: { ...state.runtimeStatus },
-                contributions,
-            });
-        }
-        return { capturedAt: new Date().toISOString(), plugins };
-    }
-    /** Start one resident runner for every enabled runtime plugin. */
     async startPluginRuntimes() {
-        this.assertReady();
-        await Promise.all([...this.states.values()].map(async (state) => {
-            try {
-                await this.ensureRunner(state);
-                await this.refreshRuntimeStatus(state);
+        const starts = [...this.states.values()].map((state) => this.runSerialized(state.record.canonicalId, () => this.startState(state)));
+        await Promise.allSettled(starts);
+    }
+    async ensurePluginRuntime(record) {
+        return await this.runSerialized(record.canonicalId, async () => {
+            const state = this.upsertState(record);
+            if (!record.enabled) {
+                await this.stopState(state);
+                return "stopped";
             }
-            catch (error) {
-                this.writeLog({
-                    level: "error",
-                    event: "plugin.runner.start_failed",
-                    pluginId: state.record.manifest.id,
-                    message: messageOf(error),
-                });
+            if (!record.manifest.runtime) {
+                state.state = "absent";
+                setPluginRuntimeState(record.canonicalId, "absent");
+                return "absent";
             }
-        }));
+            if (!state.runner)
+                await this.startState(state);
+            return state.state;
+        });
     }
-    /**
-     * Atomically replace or add one plugin runtime, preserving its live chat
-     * desired state. Concurrent reloads of the same plugin are applied in call
-     * order; other plugins continue running independently.
-     */
-    reloadPluginRuntime(record, { readyTimeoutMs } = {}) {
-        this.assertReady();
-        validateRecord(record);
-        const pluginId = record.manifest.id;
-        return this.enqueueRuntimeOperation(pluginId, () => this.performPluginRuntimeReload(record, createRuntimeReadyDeadline(boundedReadyTimeout(readyTimeoutMs))));
+    /** Strict cutover: stop current generation, then start the supplied generation. */
+    async reloadPluginRuntime(record) {
+        return await this.runSerialized(record.canonicalId, async () => {
+            const state = this.upsertState(record);
+            await this.stopState(state);
+            await this.stopSettingsState(state);
+            state.record = record;
+            state.stopping = false;
+            if (!record.enabled || !record.manifest.runtime) {
+                state.state = record.manifest.runtime ? "stopped" : "absent";
+                setPluginRuntimeState(record.canonicalId, state.state);
+                return state.state;
+            }
+            await this.startState(state);
+            return state.state;
+        });
     }
-    /**
-     * Make one enabled plugin runtime ready without replacing an already healthy
-     * runner. This is the idempotent operation plugin CLIs use when their durable
-     * configuration has not changed.
-     */
-    ensurePluginRuntime(record, { readyTimeoutMs } = {}) {
-        this.assertReady();
-        validateRecord(record);
-        const pluginId = record.manifest.id;
-        return this.enqueueRuntimeOperation(pluginId, () => this.performPluginRuntimeEnsure(record, createRuntimeReadyDeadline(boundedReadyTimeout(readyTimeoutMs))));
+    async stopPluginRuntime(identity) {
+        await this.runSerialized(identity, async () => {
+            const state = this.states.get(identity);
+            if (state)
+                await this.stopState(state);
+        });
     }
-    enqueueRuntimeOperation(pluginId, execute) {
-        const preceding = this.runtimeOperations.get(pluginId);
-        const operation = (preceding ? preceding.catch(() => undefined) : Promise.resolve())
-            .then(execute);
-        this.runtimeOperations.set(pluginId, operation);
-        void operation.finally(() => {
-            if (this.runtimeOperations.get(pluginId) === operation) {
-                this.runtimeOperations.delete(pluginId);
+    async changeEnabled(record, enabled, mutateRegistry) {
+        return await this.runSerialized(record.canonicalId, async () => {
+            const state = this.upsertState(record);
+            if (!enabled) {
+                await this.stopState(state);
+                let updated;
+                try {
+                    updated = mutateRegistry();
+                }
+                catch (error) {
+                    state.stopping = false;
+                    if (state.record.enabled)
+                        await this.startState(state);
+                    throw error;
+                }
+                state.record = updated;
+                return state.state;
             }
-        }).catch(() => undefined);
-        return operation;
+            const updated = mutateRegistry();
+            state.record = updated;
+            state.stopping = false;
+            await this.startState(state);
+            return state.state;
+        });
     }
-    async performPluginRuntimeEnsure(record, deadline) {
-        this.assertReady();
-        const state = this.states.get(record.manifest.id);
-        if (!state || !sameRuntimeRecord(state.record, record)) {
-            return this.performPluginRuntimeReload(record, deadline);
-        }
-        if (!state.runner) {
-            return this.performPluginRuntimeReload(record, deadline);
-        }
-        const status = await this.refreshRuntimeStatus(state, deadline);
-        if (status.state === "unconfigured" ||
-            status.state === "failed" ||
-            status.state === "stopped") {
-            return this.performPluginRuntimeReload(record, deadline);
-        }
-        // A starting or degraded runtime may be recovering its own transport. Do
-        // not destroy it (and any active task leases) merely because the user ran
-        // the same connect command twice; wait for its bounded readiness result.
-        return this.waitForRuntimeReady(state, deadline);
+    async cutoverInstallation(identity, commitRegistry) {
+        return await this.runSerialized(identity, async () => {
+            const current = this.states.get(identity);
+            if (current) {
+                await this.stopState(current);
+                await this.stopSettingsState(current);
+            }
+            let installed;
+            try {
+                installed = await commitRegistry();
+            }
+            catch (error) {
+                if (current) {
+                    current.stopping = false;
+                    if (current.record.enabled)
+                        await this.startState(current);
+                }
+                throw error;
+            }
+            const state = this.upsertState(installed);
+            state.record = installed;
+            state.stopping = false;
+            if (installed.enabled)
+                await this.startState(state);
+            return state.state;
+        });
     }
-    async performPluginRuntimeReload(record, deadline) {
-        this.assertReady();
-        const pluginId = record.manifest.id;
-        let state = this.states.get(pluginId);
-        if (!state) {
-            state = createPluginState(record);
-            this.states.set(pluginId, state);
-        }
-        else {
-            await this.joinExitTransition(state);
-            const spawning = state.spawnPromise;
-            this.cancelRestart(state);
-            await this.closeRunner(state);
-            await spawning?.catch(() => undefined);
-            // A runner that was already spawning may have bound after the first
-            // close. Close once more before switching the immutable package record.
-            await this.closeRunner(state);
-            this.cancelRestart(state);
-            state.record = record;
-            state.failureCount = 0;
-            state.lastRunnerError = undefined;
-            state.runtimeStatusRefresh = undefined;
-            for (const desired of state.desired.values()) {
-                desired.startedGeneration = undefined;
-                desired.status = { state: "starting", connected: false, lastError: null };
-                state.channelStatus.set(desired.key, {
-                    ...(state.channelStatus.get(desired.key) ?? {}),
-                    connected: false,
-                    lastError: null,
-                });
+    async uninstallInstallation(identity, removeRegistry) {
+        return await this.runSerialized(identity, async () => {
+            const state = this.states.get(identity);
+            if (state) {
+                await this.stopState(state);
+                await this.stopSettingsState(state);
             }
-        }
-        state.runtimeStatus = { state: "starting", connected: false, lastError: null };
-        try {
-            const runner = await this.ensureRunner(state);
-            await this.restoreDesiredContributions(state, runner);
-        }
-        catch {
-            // ensureRunner already cached the failure and scheduled resident backoff.
-            // The bounded readiness loop remains authoritative and can observe a
-            // successful retry before the caller's timeout expires.
-        }
-        return this.waitForRuntimeReady(state, deadline);
+            let removed;
+            try {
+                removed = await removeRegistry();
+            }
+            catch (error) {
+                if (state) {
+                    state.stopping = false;
+                    if (state.record.enabled)
+                        await this.startState(state);
+                }
+                throw error;
+            }
+            if (!removed && state) {
+                state.stopping = false;
+                if (state.record.enabled)
+                    await this.startState(state);
+            }
+            if (removed)
+                this.states.delete(identity);
+            return removed;
+        });
     }
-    /** Permanently stop all children and cancel every pending automatic restart. */
-    async dispose() {
-        if (this.disposed)
-            return;
-        this.disposed = true;
-        const closes = [];
-        for (const state of this.states.values()) {
-            state.desired.clear();
-            for (const [key, status] of state.channelStatus) {
-                state.channelStatus.set(key, { ...status, connected: false });
+    async settingsCall(identity, expectedGeneration, method, params, options = {}) {
+        return await this.runSerialized(identity, async () => {
+            const state = this.states.get(identity);
+            if (!state)
+                throw new Error(`plugin "${identity}" is not installed`);
+            if (state.record.integrity !== expectedGeneration) {
+                throw new Error("plugin settings UI generation is stale");
             }
-            this.cancelRestart(state);
-            clearTimer(state.stableTimer);
-            state.stableTimer = undefined;
-            state.runtimeStatus = { state: "stopping", connected: false };
-            closes.push(this.disposeState(state));
-        }
-        await Promise.all(closes);
-        for (const state of this.states.values()) {
-            state.runtimeStatus = { state: "stopped", connected: false };
-        }
+            const runner = await this.startSettingsState(state);
+            if (!runner.handshake.features.settings) {
+                throw new Error(`plugin "${identity}" does not advertise a settings background`);
+            }
+            const result = await runner.client.settingsCall(method, params, options);
+            await state.runner?.client.emitHostEvent("plugin.settings.changed", {
+                method,
+                ...(params === undefined ? {} : { params }),
+            }).catch(() => undefined);
+            return result;
+        });
     }
-    channelDescriptor(state, contribution) {
-        return {
-            type: contribution.type,
-            factory: (context) => this.createRemoteChannel(state, contribution, context),
-            ...(contribution.configSchema ? { configSchema: contribution.configSchema } : {}),
-            ...(contribution.authorize
-                ? {
-                    authorize: (emit, signal, context) => this.authorize(state, contribution, emit, signal, context),
-                }
-                : {}),
-        };
+    supportsSettings(identity) {
+        return Boolean(this.states.get(identity)?.record.manifest.settings);
     }
-    createRemoteChannel(state, contribution, context) {
-        const instanceId = context.instanceId ?? contribution.type;
-        if (!TARGET_ID_PATTERN.test(instanceId)) {
-            throw new Error(`invalid plugin channel instance id: ${instanceId}`);
-        }
-        const key = channelKey(contribution.type, instanceId);
-        const target = {
-            kind: "chat-channel",
-            contributionId: contribution.type,
-            instanceId,
-        };
-        const request = {
-            ...target,
-            config: normalizeChatChannelConfig(contribution, context.options),
-            ...(context.defaultAgent ? { defaultAgent: context.defaultAgent } : {}),
-            executionDefaults: {
-                runtime: context.config.AGENT_RUNTIME,
-                ...(context.config.RYNX_DEFAULT_AGENT
-                    ? { defaultAgent: context.config.RYNX_DEFAULT_AGENT }
-                    : {}),
-                allowedRoots: resolveAllowedRoots(context.config),
-            },
-        };
+    statusSnapshot() {
         return {
-            id: contribution.type,
-            start: async () => {
-                this.assertReady();
-                const existing = state.desired.get(key);
-                const desired = existing ?? this.rememberDesired(state, { key, request, target });
-                if (existing && !sameStartRequest(existing.request, request)) {
-                    throw new Error(`plugin channel instance is already started with different config: ${instanceId}`);
-                }
-                await this.ensureDesiredStarted(state, desired);
-            },
-            stop: async () => {
-                const desired = state.desired.get(key);
-                if (!desired) {
-                    state.channelStatus.set(key, { connected: false, lastError: null });
-                    return;
-                }
-                await this.stopDesired(state, desired);
-            },
-            getStatus: () => {
-                const cached = state.channelStatus.get(key) ?? {
-                    connected: false,
-                    lastError: null,
-                    lastEventAt: null,
-                };
-                const desired = state.desired.get(key);
-                if (desired)
-                    void this.refreshContributionStatus(state, desired).catch(() => undefined);
-                return { ...cached };
-            },
+            plugins: [...this.states.values()].map((state) => ({
+                pluginId: state.record.canonicalId,
+                generation: state.generation,
+                state: state.state,
+                ...(state.health ? { health: structuredClone(state.health) } : {}),
+                ...(state.error ? { error: state.error } : {}),
+                settings: Boolean(state.record.manifest.settings),
+            })),
         };
     }
-    async authorize(state, contribution, emit, signal, context) {
-        this.assertReady();
-        const runner = await this.ensureRunner(state);
-        return runner.client.authorize({
-            kind: "chat-channel",
-            contributionId: contribution.type,
-            ...(context?.instanceId ? { instanceId: context.instanceId } : {}),
-            config: clonePluginConfig(context?.config),
-        }, (material) => emit(material), { signal });
-    }
-    rememberDesired(state, input) {
-        const desired = {
-            ...input,
-            status: { state: "stopped" },
-            failureCount: 0,
+    async dispose() {
+        if (this.disposePromise)
+            return this.disposePromise;
+        this.disposed = true;
+        const attempt = (async () => {
+            const stopped = await Promise.allSettled([...this.states.values()].map((state) => this.runSerialized(state.record.canonicalId, async () => {
+                await this.stopState(state);
+                await this.stopSettingsState(state);
+            })));
+            const failures = stopped
+                .filter((result) => result.status === "rejected")
+                .map((result) => result.reason);
+            if (failures.length > 0) {
+                throw new AggregateError(failures, "plugin supervisor could not stop every runtime");
+            }
+        })();
+        this.disposePromise = attempt;
+        void attempt.catch(() => {
+            if (this.disposePromise === attempt)
+                this.disposePromise = undefined;
+        });
+        return attempt;
+    }
+    upsertState(record) {
+        const current = this.states.get(record.canonicalId);
+        if (current) {
+            if (!current.runner && !current.settingsRunner)
+                current.record = record;
+            return current;
+        }
+        const state = {
+            record,
+            state: record.manifest.runtime ? "stopped" : "absent",
+            generation: 0,
+            restartFailures: 0,
+            stopping: false,
         };
-        state.desired.set(desired.key, desired);
-        if (desired.target.kind === "chat-channel") {
-            state.channelStatus.set(desired.key, { connected: false, lastError: null });
-        }
-        return desired;
-    }
-    async ensureDesiredStarted(state, desired) {
-        const runner = await this.ensureRunner(state);
-        if (state.desired.get(desired.key) !== desired) {
+        this.states.set(record.canonicalId, state);
+        return state;
+    }
+    async startState(state) {
+        if (this.disposed
+            || state.runner
+            || blockingCleanupError(state)
+            || !state.record.enabled)
             return;
-        }
-        await this.startDesiredOnRunner(state, desired, runner);
-        await this.refreshContributionStatus(state, desired);
-    }
-    async startDesiredOnRunner(state, desired, runner) {
-        const generation = state.generation;
-        if (desired.startedGeneration === generation)
-            return;
-        if (desired.starting && desired.startingGeneration === generation) {
-            await desired.starting;
+        const runtime = state.record.manifest.runtime;
+        if (!runtime) {
+            state.state = "absent";
+            setPluginRuntimeState(state.record.canonicalId, "absent");
             return;
         }
-        desired.status = { state: "starting" };
-        const operation = runner.client.startContribution(desired.request).then(() => {
-            if (state.runner === runner && state.desired.get(desired.key) === desired) {
-                desired.startedGeneration = generation;
-                desired.failureCount = 0;
-                desired.status = {
-                    state: "running",
-                    connected: false,
-                    lastError: null,
-                };
-                state.channelStatus.set(desired.key, {
-                    ...(state.channelStatus.get(desired.key) ?? {}),
-                    connected: state.channelStatus.get(desired.key)?.connected ?? false,
-                    lastError: null,
-                });
-            }
-        }, (error) => {
-            if (state.runner === runner && state.desired.get(desired.key) === desired) {
-                this.markContributionFailed(state, desired, error);
-            }
-            throw error;
-        });
-        desired.starting = operation;
-        desired.startingGeneration = generation;
+        if (!this.services)
+            throw new Error("plugin host services are not bound");
+        state.stopping = false;
+        state.state = "starting";
+        state.error = undefined;
+        state.generation += 1;
+        setPluginRuntimeState(state.record.canonicalId, "starting");
+        const dataDir = pluginDataDir(state.record.marketplaceId, state.record.pluginId);
+        const cacheDir = pluginRuntimeCacheDir(state.record.marketplaceId, state.record.pluginId, state.record.integrity);
+        let runner;
+        let hostRpc;
         try {
-            await operation;
-        }
-        finally {
-            if (desired.starting === operation) {
-                desired.starting = undefined;
-                desired.startingGeneration = undefined;
-            }
+            await this.verifyPackage(state.record);
+            mkdirSync(dataDir, { recursive: true, mode: 0o700 });
+            mkdirSync(cacheDir, { recursive: true, mode: 0o700 });
+            writePluginRuntimeLease({
+                dataDir,
+                pluginId: state.record.pluginId,
+                leaseId: RUNTIME_LEASE_ID,
+                installPath: state.record.installPath,
+            });
+            hostRpc = new PluginHostRpc({
+                pluginId: state.record.pluginId,
+                principalId: state.record.canonicalId,
+                daemonInstanceId: this.daemonInstanceId,
+                productVersion: this.productVersion,
+                cliVersion: this.cliVersion,
+                capabilities: state.record.manifest.capabilities,
+                services: this.services,
+                ...(state.record.pluginId === "workspace"
+                    && isBuiltInPluginMarketplace(state.record.marketplaceId)
+                    ? { managedWorkspaceRoot: dataDir }
+                    : {}),
+                emit: async (event) => {
+                    if (Buffer.byteLength(JSON.stringify(event), "utf8") > MAX_PLUGIN_HOST_EVENT_BYTES) {
+                        throw new Error("plugin host event exceeds transport budget");
+                    }
+                    await runner?.client.emitHostEvent(event.event, event.payload);
+                },
+            });
+            state.hostRpc = hostRpc;
+            runner = await this.spawnRunner({
+                pluginId: state.record.pluginId,
+                pluginVersion: state.record.version,
+                installationId: state.record.canonicalId,
+                packageRoot: state.record.installPath,
+                ...("entry" in runtime
+                    ? {
+                        entry: runtime.entry,
+                    }
+                    : {
+                        command: runtime.command,
+                        args: runtime.args,
+                    }),
+                role: "runtime",
+                dataDir,
+                cacheDir,
+                capabilities: state.record.manifest.capabilities,
+                handleHostCall: (method, params, signal) => hostRpc.call(method, params, signal),
+                onStderr: (line) => this.log({
+                    level: "info",
+                    event: "plugin-stderr",
+                    pluginId: state.record.canonicalId,
+                    message: line,
+                }),
+            });
+            state.runner = runner;
+            state.health = runner.initialHealth;
+            state.state = healthState(runner.initialHealth);
+            state.startedAt = Date.now();
+            state.error = undefined;
+            setPluginRuntimeState(state.record.canonicalId, state.state);
+            this.log({
+                level: "info",
+                event: "plugin-runtime-started",
+                pluginId: state.record.canonicalId,
+            });
+            this.scheduleHealthPoll(state, runner);
+            const generation = state.generation;
+            void runner.completion.then((exit) => {
+                void this.runSerialized(state.record.canonicalId, () => this.handleExit(state, runner, generation, exit));
+            }).catch((error) => {
+                void this.runSerialized(state.record.canonicalId, () => this.handleExit(state, runner, generation, {
+                    code: null,
+                    signal: null,
+                    error,
+                }));
+            });
         }
-    }
-    async stopDesired(state, desired) {
-        if (state.desired.get(desired.key) !== desired)
-            return;
-        state.desired.delete(desired.key);
-        state.channelStatus.set(desired.key, {
-            connected: false,
-            lastError: null,
-            lastEventAt: state.channelStatus.get(desired.key)?.lastEventAt ?? null,
-        });
-        let stopError;
-        const runner = state.runner;
-        if (runner) {
+        catch (error) {
             try {
-                await runner.client.stopContribution(desired.target);
-            }
-            catch (error) {
-                stopError = error;
+                await hostRpc?.dispose();
             }
-        }
-        if (stopError)
-            throw stopError;
-    }
-    async refreshContributionStatus(state, desired) {
-        if (desired.statusRefresh)
-            return desired.statusRefresh;
-        const runner = state.runner;
-        if (!runner || desired.startedGeneration !== state.generation)
-            return;
-        const refresh = runner.client.status(desired.target).then((status) => {
-            if (state.runner !== runner || state.desired.get(desired.key) !== desired)
-                return;
-            desired.status = boundedContributionStatus(status);
-            state.channelStatus.set(desired.key, statusToChannelStatus(desired.status));
-        }, (error) => {
-            if (state.runner !== runner || state.desired.get(desired.key) !== desired)
+            catch (cleanupError) {
+                const failure = new AggregateError([error, cleanupError], "plugin runtime startup failed and active-run cleanup was unproven");
+                state.runtimeCleanupError = failure;
+                this.failState(state, failure);
                 return;
-            desired.status = {
-                state: "degraded",
-                connected: false,
-                lastError: messageOf(error),
-            };
-            state.channelStatus.set(desired.key, {
-                ...(state.channelStatus.get(desired.key) ?? {}),
-                connected: false,
-                lastError: messageOf(error),
-            });
-        });
-        desired.statusRefresh = refresh;
-        try {
-            await refresh;
-        }
-        finally {
-            if (desired.statusRefresh === refresh)
-                desired.statusRefresh = undefined;
-        }
-    }
-    async refreshRuntimeStatus(state, deadline) {
-        if (deadline && deadline.expiresAt - Date.now() <= 0) {
-            throw this.runtimeReadyTimeoutError(state, deadline.timeoutMs);
-        }
-        const runner = state.runner;
-        if (!runner)
-            return state.runtimeStatus;
-        let refresh = state.runtimeStatusRefresh;
-        if (!refresh) {
-            refresh = runner.client.runtimeStatus().then((status) => {
-                if (state.runner !== runner)
-                    return state.runtimeStatus;
-                state.runtimeStatus = boundedRuntimeStatus(status);
-                return state.runtimeStatus;
-            }, (error) => {
-                if (state.runner !== runner)
-                    return state.runtimeStatus;
-                state.runtimeStatus = {
-                    state: "degraded",
-                    connected: false,
-                    lastError: messageOf(error),
-                };
-                return state.runtimeStatus;
-            });
-            state.runtimeStatusRefresh = refresh;
-            void refresh.finally(() => {
-                if (state.runtimeStatusRefresh === refresh)
-                    state.runtimeStatusRefresh = undefined;
-            }).catch(() => undefined);
-        }
-        return deadline
-            ? await settleBeforeDeadline(refresh, deadline.expiresAt, () => this.runtimeReadyTimeoutError(state, deadline.timeoutMs))
-            : await refresh;
-    }
-    async waitForRuntimeReady(state, deadline) {
-        while (true) {
-            this.assertOpen();
-            const remainingBeforeRefresh = deadline.expiresAt - Date.now();
-            if (remainingBeforeRefresh <= 0) {
-                throw this.runtimeReadyTimeoutError(state, deadline.timeoutMs);
             }
-            const status = state.runner
-                ? await this.refreshRuntimeStatus(state, deadline)
-                : state.runtimeStatus;
-            if (status.state === "running" && status.connected !== false)
-                return { ...status };
-            const remaining = deadline.expiresAt - Date.now();
-            if (remaining <= 0) {
-                throw this.runtimeReadyTimeoutError(state, deadline.timeoutMs);
+            state.hostRpc = undefined;
+            if (isUnprovenProcessCleanup(error)) {
+                state.runtimeCleanupError = error;
+                this.failState(state, error);
+                return;
             }
-            await delay(Math.min(RUNTIME_STATUS_POLL_MS, remaining));
+            removePluginRuntimeLease(dataDir, RUNTIME_LEASE_ID);
+            this.failState(state, error);
+            this.scheduleRestart(state);
         }
     }
-    runtimeReadyTimeoutError(state, timeoutMs) {
-        const status = state.runtimeStatus;
-        const detail = status.lastError ? `: ${status.lastError}` : ` (state=${status.state})`;
-        return new Error(`plugin runtime "${state.record.manifest.id}" did not become ready within ${timeoutMs}ms${detail}`);
-    }
-    ensureRunner(state) {
-        this.assertReady();
-        if (state.exitTransition) {
-            return this.joinExitTransition(state).then(() => this.ensureRunner(state));
+    async startSettingsState(state) {
+        if (this.disposed)
+            throw new Error("plugin supervisor is disposed");
+        const cleanupError = blockingCleanupError(state);
+        if (cleanupError)
+            throw cleanupError;
+        if (state.settingsRunner)
+            return state.settingsRunner;
+        const background = state.record.manifest.settings?.background;
+        if (!background) {
+            throw new Error(`plugin "${state.record.canonicalId}" has no settings background`);
         }
-        if (state.runner)
-            return Promise.resolve(state.runner);
-        if (state.spawnPromise)
-            return state.spawnPromise;
-        state.runtimeStatus = { state: "starting", connected: false, lastError: null };
-        const spawn = this.spawnAndBind(state).catch((error) => {
-            if (!this.disposed) {
-                state.failureCount += 1;
-                this.markRunnerUnavailable(state, `plugin runner failed to start: ${messageOf(error)}`);
-                this.scheduleRestart(state);
-            }
-            throw error;
-        });
-        state.spawnPromise = spawn;
-        void spawn.finally(() => {
-            if (state.spawnPromise === spawn)
-                state.spawnPromise = undefined;
-        }).catch(() => undefined);
-        return spawn;
-    }
-    async spawnAndBind(state) {
-        const pluginId = state.record.manifest.id;
-        const eventQueue = new BoundedHostEventQueue();
-        const host = new PluginHostRpc({
-            pluginId,
-            daemonInstanceId: this.daemonInstanceId,
-            grants: state.record.grants,
-            services: this.requireHostServices(),
-            emit: (event) => eventQueue.enqueue(event),
-        });
-        const stderr = this.stderrSink(pluginId);
+        if (!this.services)
+            throw new Error("plugin host services are not bound");
+        const dataDir = pluginDataDir(state.record.marketplaceId, state.record.pluginId);
+        const cacheDir = pluginRuntimeCacheDir(state.record.marketplaceId, state.record.pluginId, state.record.integrity);
         let runner;
+        let hostRpc;
         try {
+            await this.verifyPackage(state.record);
+            mkdirSync(dataDir, { recursive: true, mode: 0o700 });
+            mkdirSync(cacheDir, { recursive: true, mode: 0o700 });
+            writePluginRuntimeLease({
+                dataDir,
+                pluginId: state.record.pluginId,
+                leaseId: SETTINGS_LEASE_ID,
+                installPath: state.record.installPath,
+            });
+            hostRpc = new PluginHostRpc({
+                pluginId: state.record.pluginId,
+                principalId: state.record.canonicalId,
+                daemonInstanceId: this.daemonInstanceId,
+                productVersion: this.productVersion,
+                cliVersion: this.cliVersion,
+                capabilities: state.record.manifest.capabilities,
+                services: this.services,
+                ...(state.record.pluginId === "workspace"
+                    && isBuiltInPluginMarketplace(state.record.marketplaceId)
+                    ? { managedWorkspaceRoot: dataDir }
+                    : {}),
+                emit: async (event) => {
+                    if (Buffer.byteLength(JSON.stringify(event), "utf8") > MAX_PLUGIN_HOST_EVENT_BYTES) {
+                        throw new Error("plugin host event exceeds transport budget");
+                    }
+                    await runner?.client.emitHostEvent(event.event, event.payload);
+                },
+            });
             runner = await this.spawnRunner({
-                pluginId,
+                pluginId: state.record.pluginId,
+                pluginVersion: state.record.version,
+                installationId: state.record.canonicalId,
                 packageRoot: state.record.installPath,
-                runtimeEntry: path.resolve(state.record.installPath, state.record.manifest.runtimeEntry),
-                dataDir: path.join(rynxHome(), "plugin-data", pluginId),
-                config: {},
-                grantedCapabilities: [...state.record.grants],
-                handleHostCall: (method, params) => host.call(method, params),
-                onStderr: stderr.write,
+                ...("entry" in background
+                    ? {
+                        entry: background.entry,
+                    }
+                    : {
+                        command: background.command,
+                        args: background.args,
+                    }),
+                role: "settings",
+                dataDir,
+                cacheDir,
+                capabilities: state.record.manifest.capabilities,
+                handleHostCall: (method, params, signal) => hostRpc.call(method, params, signal),
+                onStderr: (line) => this.log({
+                    level: "info",
+                    event: "plugin-stderr",
+                    pluginId: state.record.canonicalId,
+                    message: line,
+                }),
             });
-            assertHandshake(pluginId, state.record.grants, runner.handshake);
+            if (!runner.handshake.features.settings) {
+                throw new Error(`plugin "${state.record.canonicalId}" does not advertise a settings background`);
+            }
+            state.settingsRunner = runner;
+            state.settingsHostRpc = hostRpc;
+            this.log({
+                level: "info",
+                event: "plugin-settings-started",
+                pluginId: state.record.canonicalId,
+            });
+            void runner.completion.then((exit) => {
+                void this.runSerialized(state.record.canonicalId, () => this.handleSettingsExit(state, runner, hostRpc, exit));
+            }).catch((error) => {
+                void this.runSerialized(state.record.canonicalId, () => this.handleSettingsExit(state, runner, hostRpc, {
+                    code: null,
+                    signal: null,
+                    error,
+                }));
+            });
+            return runner;
         }
         catch (error) {
-            eventQueue.close(error);
-            stderr.flush();
-            await runner?.close().catch(() => undefined);
-            await host.dispose();
+            const cleanupErrors = [];
+            if (runner) {
+                try {
+                    await runner.close();
+                }
+                catch (cleanupError) {
+                    state.settingsRunner = runner;
+                    cleanupErrors.push(cleanupError);
+                }
+            }
+            try {
+                await hostRpc?.dispose();
+            }
+            catch (cleanupError) {
+                state.settingsHostRpc = hostRpc;
+                cleanupErrors.push(cleanupError);
+            }
+            if (cleanupErrors.length > 0) {
+                const failure = new AggregateError([error, ...cleanupErrors], "plugin settings startup failed and cleanup was unproven");
+                state.settingsCleanupError = failure;
+                throw failure;
+            }
+            if (isUnprovenProcessCleanup(error)) {
+                state.settingsCleanupError = error;
+                throw error;
+            }
+            removePluginRuntimeLease(dataDir, SETTINGS_LEASE_ID);
             throw error;
         }
-        if (this.disposed) {
-            eventQueue.close(new Error("plugin supervisor is disposed"));
-            stderr.flush();
-            await runner.close().catch(() => undefined);
-            await host.dispose();
-            throw new Error("plugin supervisor is disposed");
+    }
+    async stopSettingsState(state) {
+        const runner = state.settingsRunner;
+        const hostRpc = state.settingsHostRpc;
+        if (state.settingsCleanupError && !runner && !hostRpc) {
+            throw state.settingsCleanupError;
         }
-        eventQueue.bind(runner.client);
-        state.runner = runner;
-        state.host = host;
-        state.eventQueue = eventQueue;
-        state.lastRunnerError = undefined;
-        state.generation += 1;
-        const generation = state.generation;
-        clearTimer(state.stableTimer);
-        state.stableTimer = setTimeout(() => {
-            if (state.runner === runner)
-                state.failureCount = 0;
-        }, this.stableResetMs);
-        state.stableTimer.unref?.();
-        void runner.completion.then((outcome) => {
-            eventQueue.close(new Error("plugin runner exited"));
-            stderr.flush();
-            this.trackRunnerExit(state, runner, host, generation, outcome);
-        }, (error) => {
-            eventQueue.close(error);
-            stderr.flush();
-            this.trackRunnerExit(state, runner, host, generation, undefined, error);
-        }).catch((error) => {
-            this.writeLog({
-                level: "error",
-                event: "plugin.runner.exit_handler_failed",
-                pluginId,
-                message: messageOf(error),
-            });
-        });
-        return runner;
+        const errors = [];
+        if (runner) {
+            try {
+                await runner.close();
+                if (state.settingsRunner === runner)
+                    state.settingsRunner = undefined;
+            }
+            catch (error) {
+                errors.push(error);
+            }
+        }
+        if (hostRpc) {
+            try {
+                await hostRpc.dispose();
+                if (state.settingsHostRpc === hostRpc)
+                    state.settingsHostRpc = undefined;
+            }
+            catch (error) {
+                errors.push(error);
+            }
+        }
+        if (errors.length > 0) {
+            const failure = cleanupFailure(errors, "plugin settings cleanup was unproven");
+            state.settingsCleanupError = failure;
+            throw failure;
+        }
+        state.settingsCleanupError = undefined;
+        removePluginRuntimeLease(pluginDataDir(state.record.marketplaceId, state.record.pluginId), SETTINGS_LEASE_ID);
     }
-    trackRunnerExit(state, runner, host, generation, outcome, error) {
-        const preceding = state.exitTransition;
-        const transition = (preceding
-            ? preceding.catch(() => undefined)
-            : Promise.resolve()).then(() => this.runnerExited(state, runner, host, generation, outcome, error));
-        state.exitTransition = transition;
-        void transition.then(() => {
-            if (state.exitTransition === transition)
-                state.exitTransition = undefined;
-        }, (transitionError) => {
-            if (state.exitTransition === transition)
-                state.exitTransition = undefined;
-            this.writeLog({
+    async handleSettingsExit(state, runner, hostRpc, exit) {
+        if (state.settingsRunner !== runner)
+            return;
+        try {
+            await runner.terminateTree();
+        }
+        catch (error) {
+            state.settingsCleanupError = error;
+            this.log({
                 level: "error",
-                event: "plugin.runner.exit_handler_failed",
-                pluginId: state.record.manifest.id,
-                message: messageOf(transitionError),
+                event: "plugin-settings-exited",
+                pluginId: state.record.canonicalId,
+                message: error instanceof Error ? error.message : String(error),
             });
-        }).catch(() => undefined);
-    }
-    async runnerExited(state, runner, host, generation, outcome, error) {
-        if (state.runner !== runner || state.generation !== generation)
             return;
-        state.runner = undefined;
-        if (state.host === host)
-            state.host = undefined;
-        state.eventQueue?.close(error ?? new Error("plugin runner exited"));
-        state.eventQueue = undefined;
-        state.runtimeStatusRefresh = undefined;
-        clearTimer(state.stableTimer);
-        state.stableTimer = undefined;
-        await host.dispose();
-        // Reload, explicit start, and dispose all join this transition. Keep the
-        // generation guard as a final defence against any future call path that
-        // can bind a successor without waiting for the old host cleanup.
-        if (this.disposed || state.runner || state.generation !== generation)
-            return;
-        const message = error
-            ? messageOf(error)
-            : `plugin runner exited (code=${String(outcome?.code)}, signal=${String(outcome?.signal)})`;
-        this.markRunnerUnavailable(state, message);
-        this.writeLog({
-            level: outcome?.code === 0 && !error ? "warn" : "error",
-            event: "plugin.runner.exited",
-            pluginId: state.record.manifest.id,
-            message,
-            code: outcome?.code,
-            signal: outcome?.signal,
-        });
-        state.failureCount += 1;
-        this.scheduleRestart(state);
-    }
-    async joinExitTransition(state) {
-        while (state.exitTransition) {
-            const transition = state.exitTransition;
-            await transition.catch(() => undefined);
-            if (state.exitTransition === transition)
-                state.exitTransition = undefined;
         }
-    }
-    scheduleRestart(state) {
-        if (this.disposed || state.restartTimer)
-            return;
-        const exponent = Math.min(Math.max(state.failureCount - 1, 0), 30);
-        const delayMs = Math.min(this.restartMaxMs, this.restartBaseMs * 2 ** exponent);
-        this.writeLog({
-            level: "warn",
-            event: "plugin.runner.restart_scheduled",
-            pluginId: state.record.manifest.id,
-            delayMs,
-        });
-        state.restartTimer = setTimeout(() => {
-            state.restartTimer = undefined;
-            void this.restart(state);
-        }, delayMs);
-        state.restartTimer.unref?.();
-    }
-    async restart(state) {
-        if (this.disposed)
-            return;
-        let runner;
+        state.settingsRunner = undefined;
         try {
-            runner = await this.ensureRunner(state);
+            await hostRpc.dispose();
+            if (state.settingsHostRpc === hostRpc)
+                state.settingsHostRpc = undefined;
         }
         catch (error) {
-            this.writeLog({
+            state.settingsCleanupError = error;
+            this.log({
                 level: "error",
-                event: "plugin.runner.restart_failed",
-                pluginId: state.record.manifest.id,
-                message: messageOf(error),
+                event: "plugin-settings-exited",
+                pluginId: state.record.canonicalId,
+                message: error instanceof Error ? error.message : String(error),
             });
             return;
         }
-        await this.refreshRuntimeStatus(state);
-        await this.restoreDesiredContributions(state, runner);
+        state.settingsCleanupError = undefined;
+        removePluginRuntimeLease(pluginDataDir(state.record.marketplaceId, state.record.pluginId), SETTINGS_LEASE_ID);
+        if (!this.disposed) {
+            this.log({
+                level: "warn",
+                event: "plugin-settings-exited",
+                pluginId: state.record.canonicalId,
+                message: exit.error instanceof Error
+                    ? exit.error.message
+                    : `settings background exited with code ${exit.code ?? "null"}${exit.signal ? ` (${exit.signal})` : ""}`,
+            });
+        }
     }
-    async restoreDesiredContributions(state, runner) {
-        for (const desired of [...state.desired.values()]) {
+    async stopState(state) {
+        state.stopping = true;
+        if (state.restartTimer)
+            clearTimeout(state.restartTimer);
+        state.restartTimer = undefined;
+        if (state.healthTimer)
+            clearTimeout(state.healthTimer);
+        state.healthTimer = undefined;
+        const runner = state.runner;
+        const hostRpc = state.hostRpc;
+        if (state.runtimeCleanupError && !runner && !hostRpc) {
+            throw state.runtimeCleanupError;
+        }
+        const errors = [];
+        if (runner) {
             try {
-                await this.startDesiredOnRunner(state, desired, runner);
-                await this.refreshContributionStatus(state, desired);
+                await runner.close();
+                if (state.runner === runner)
+                    state.runner = undefined;
             }
             catch (error) {
-                this.writeLog({
-                    level: "error",
-                    event: "plugin.contribution.restore_failed",
-                    pluginId: state.record.manifest.id,
-                    message: messageOf(error),
-                });
+                errors.push(error);
             }
         }
-    }
-    async closeRunner(state) {
-        const runner = state.runner;
-        const host = state.host;
-        const eventQueue = state.eventQueue;
-        state.runner = undefined;
-        state.host = undefined;
-        state.eventQueue = undefined;
-        state.runtimeStatusRefresh = undefined;
-        eventQueue?.close(new Error("plugin runner is closing"));
-        clearTimer(state.stableTimer);
-        state.stableTimer = undefined;
-        if (runner) {
+        if (hostRpc) {
             try {
-                await runner.close();
+                await hostRpc.dispose();
+                if (state.hostRpc === hostRpc)
+                    state.hostRpc = undefined;
             }
             catch (error) {
-                this.writeLog({
-                    level: "warn",
-                    event: "plugin.runner.close_failed",
-                    pluginId: state.record.manifest.id,
-                    message: messageOf(error),
-                });
+                errors.push(error);
             }
         }
-        await host?.dispose();
-    }
-    async disposeState(state) {
-        await this.joinExitTransition(state);
-        const spawning = state.spawnPromise;
-        await this.closeRunner(state);
-        await spawning?.catch(() => undefined);
-        // A spawn can bind between the first close and the disposed check inside
-        // spawnAndBind. A final idempotent close makes dispose a true join point.
-        await this.closeRunner(state);
-        await this.joinExitTransition(state);
-    }
-    cancelRestart(state) {
-        clearTimer(state.restartTimer);
-        state.restartTimer = undefined;
-    }
-    markRunnerUnavailable(state, message) {
-        state.lastRunnerError = message;
-        state.runtimeStatus = {
-            state: "failed",
-            connected: false,
-            lastError: message,
-        };
-        for (const desired of state.desired.values()) {
-            desired.startedGeneration = undefined;
-            desired.status = {
-                state: "failed",
-                connected: false,
-                lastError: message,
-            };
-            state.channelStatus.set(desired.key, {
-                ...(state.channelStatus.get(desired.key) ?? {}),
-                connected: false,
-                lastError: message,
-            });
+        if (errors.length > 0) {
+            const failure = cleanupFailure(errors, "plugin runtime cleanup was unproven");
+            state.runtimeCleanupError = failure;
+            this.failState(state, failure);
+            throw failure;
         }
+        state.runtimeCleanupError = undefined;
+        removePluginRuntimeLease(pluginDataDir(state.record.marketplaceId, state.record.pluginId), RUNTIME_LEASE_ID);
+        state.health = undefined;
+        state.error = undefined;
+        state.state = state.record.manifest.runtime ? "stopped" : "absent";
+        setPluginRuntimeState(state.record.canonicalId, state.state);
     }
-    markContributionFailed(state, desired, error) {
-        desired.startedGeneration = undefined;
-        desired.failureCount += 1;
-        desired.status = {
-            state: "failed",
-            connected: false,
-            lastError: messageOf(error),
-        };
-        state.channelStatus.set(desired.key, {
-            ...(state.channelStatus.get(desired.key) ?? {}),
-            connected: false,
-            lastError: messageOf(error),
-        });
-    }
-    stderrSink(pluginId) {
-        let buffered = "";
-        const continuation = " …[continued]";
-        const contentLimit = MAX_STDERR_LINE_BYTES - Buffer.byteLength(continuation, "utf8");
-        const emitLine = (line) => {
-            const message = line.trimEnd();
-            if (!message)
-                return;
-            this.writeLog({
-                level: "warn",
-                event: "plugin.runner.stderr",
-                pluginId,
-                message,
-            });
-        };
-        const appendSegment = (segment) => {
-            let remaining = segment;
-            while (remaining.length > 0) {
-                const bufferedBytes = Buffer.byteLength(buffered, "utf8");
-                const budget = Math.max(1, contentLimit - bufferedBytes);
-                const [prefix, rest] = splitUtf8AtMost(remaining, budget);
-                if (!prefix && rest) {
-                    if (buffered) {
-                        emitLine(`${buffered}${continuation}`);
-                        buffered = "";
-                        continue;
-                    }
-                    // `contentLimit` is much larger than a single UTF-8 code point, so
-                    // this branch is defensive only.
-                    const first = String.fromCodePoint(remaining.codePointAt(0));
-                    buffered = first;
-                    remaining = remaining.slice(first.length);
-                    continue;
-                }
-                buffered += prefix;
-                remaining = rest;
-                if (remaining.length > 0 || Buffer.byteLength(buffered, "utf8") >= contentLimit) {
-                    emitLine(`${buffered}${continuation}`);
-                    buffered = "";
-                }
-            }
-        };
-        return {
-            write: (chunk) => {
-                let offset = 0;
-                while (offset < chunk.length) {
-                    const newline = chunk.indexOf("\n", offset);
-                    if (newline < 0) {
-                        appendSegment(chunk.slice(offset));
-                        return;
-                    }
-                    appendSegment(chunk.slice(offset, newline));
-                    emitLine(buffered);
-                    buffered = "";
-                    offset = newline + 1;
-                }
-            },
-            flush: () => {
-                if (buffered)
-                    emitLine(buffered);
-                buffered = "";
-            },
-        };
-    }
-    writeLog(entry) {
-        if (this.logger) {
-            this.logger(entry);
+    async handleExit(state, runner, generation, exit) {
+        if (state.runner !== runner || state.generation !== generation)
             return;
-        }
-        console.error(JSON.stringify({ timestamp: new Date().toISOString(), ...entry }));
-    }
-    assertOpen() {
-        if (this.disposed)
-            throw new Error("plugin supervisor is disposed");
-    }
-    assertReady() {
-        this.assertOpen();
-        this.requireHostServices();
-    }
-    requireHostServices() {
-        if (!this.services)
-            throw new Error("plugin host services are not bound");
-        return this.services;
-    }
-}
-/** A single-writer queue: bounded buffering plus an awaitable delivery ack. */
-class BoundedHostEventQueue {
-    items = [];
-    client;
-    queuedBytes = 0;
-    draining = false;
-    closed = false;
-    closeError;
-    bind(client) {
-        if (this.client)
-            throw new Error("plugin host event queue is already bound");
-        if (this.closed)
-            throw this.closeError ?? new Error("plugin host event queue is closed");
-        this.client = client;
-        void this.drain();
-    }
-    enqueue(event) {
-        if (this.closed) {
-            return Promise.reject(this.closeError ?? new Error("plugin host event queue is closed"));
-        }
-        let bytes;
+        if (state.healthTimer)
+            clearTimeout(state.healthTimer);
+        state.healthTimer = undefined;
         try {
-            bytes = Buffer.byteLength(JSON.stringify(event), "utf8");
+            await runner.terminateTree();
         }
-        catch {
-            return Promise.reject(new Error("plugin host event must be JSON serializable"));
+        catch (error) {
+            state.runtimeCleanupError = error;
+            this.failState(state, error);
+            return;
         }
-        if (bytes > MAX_PLUGIN_HOST_EVENT_BYTES) {
-            return Promise.reject(new Error("plugin host event exceeds the bounded event budget"));
+        state.runner = undefined;
+        try {
+            await state.hostRpc?.dispose();
+            state.hostRpc = undefined;
         }
-        if (this.items.length + (this.draining ? 1 : 0) >= MAX_HOST_EVENT_QUEUE_ITEMS ||
-            this.queuedBytes + bytes > MAX_HOST_EVENT_QUEUE_BYTES) {
-            return Promise.reject(new Error("plugin host event queue is full"));
+        catch (error) {
+            state.runtimeCleanupError = error;
+            if (!state.stopping && !this.disposed)
+                this.failState(state, error);
+            return;
         }
-        const promise = new Promise((resolve, reject) => {
-            this.items.push({ event, bytes, resolve, reject });
-            this.queuedBytes += bytes;
+        state.runtimeCleanupError = undefined;
+        removePluginRuntimeLease(pluginDataDir(state.record.marketplaceId, state.record.pluginId), RUNTIME_LEASE_ID);
+        if (state.stopping || this.disposed)
+            return;
+        const stable = state.startedAt && Date.now() - state.startedAt >= STABLE_RESET_MS;
+        if (stable)
+            state.restartFailures = 0;
+        this.failState(state, exit.error ?? new Error(`runtime exited with code ${exit.code ?? "null"}${exit.signal ? ` (${exit.signal})` : ""}`));
+        this.scheduleRestart(state);
+    }
+    failState(state, error) {
+        state.restartFailures += 1;
+        state.health = undefined;
+        state.state = "failed";
+        state.error = error instanceof Error ? error.message : String(error);
+        setPluginRuntimeState(state.record.canonicalId, "failed", state.error);
+        this.log({
+            level: "error",
+            event: "plugin-runtime-failed",
+            pluginId: state.record.canonicalId,
+            message: state.error,
         });
-        void this.drain();
-        return promise;
     }
-    close(error) {
-        if (this.closed)
+    scheduleRestart(state) {
+        if (this.disposed || state.stopping || !state.record.enabled || state.restartTimer)
             return;
-        this.closed = true;
-        this.closeError = error instanceof Error
-            ? error
-            : new Error(error === undefined ? "plugin host event queue is closed" : String(error));
-        for (const item of this.items.splice(0)) {
-            this.queuedBytes -= item.bytes;
-            item.reject(this.closeError);
-        }
+        const delayMs = Math.min(this.restartMaxMs, this.restartBaseMs * 2 ** Math.max(0, state.restartFailures - 1));
+        state.restartTimer = setTimeout(() => {
+            state.restartTimer = undefined;
+            void this.runSerialized(state.record.canonicalId, () => this.startState(state));
+        }, delayMs);
+        state.restartTimer.unref?.();
+        this.log({
+            level: "warn",
+            event: "plugin-runtime-restart-scheduled",
+            pluginId: state.record.canonicalId,
+            delayMs,
+        });
     }
-    async drain() {
-        if (this.draining || this.closed || !this.client)
+    scheduleHealthPoll(state, runner) {
+        if (this.disposed || state.stopping || state.runner !== runner || state.healthTimer)
             return;
-        this.draining = true;
-        try {
-            while (!this.closed && this.client && this.items.length > 0) {
-                const item = this.items.shift();
+        state.healthTimer = setTimeout(() => {
+            state.healthTimer = undefined;
+            void this.runSerialized(state.record.canonicalId, async () => {
+                if (state.runner !== runner || state.stopping || this.disposed)
+                    return;
                 try {
-                    await this.client.emitHostEvent(item.event.event, item.event.payload);
-                    item.resolve();
+                    await this.refreshHealth(state);
+                    this.scheduleHealthPoll(state, runner);
                 }
                 catch (error) {
-                    const failure = error instanceof Error ? error : new Error(String(error));
-                    item.reject(failure);
-                    this.queuedBytes -= item.bytes;
-                    this.close(failure);
-                    return;
+                    await this.failRunningState(state, runner, error);
                 }
-                this.queuedBytes -= item.bytes;
-            }
+            });
+        }, this.healthPollMs);
+        state.healthTimer.unref?.();
+    }
+    async refreshHealth(state) {
+        const runner = state.runner;
+        if (!runner) {
+            throw new Error(`plugin runtime "${state.record.canonicalId}" is not running`);
         }
-        finally {
-            this.draining = false;
-            if (!this.closed && this.client && this.items.length > 0)
-                void this.drain();
+        const health = await runner.client.health();
+        if (state.runner !== runner)
+            return;
+        const nextState = healthState(health);
+        const changed = state.state !== nextState ||
+            state.error !== undefined ||
+            JSON.stringify(state.health) !== JSON.stringify(health);
+        state.health = health;
+        state.state = nextState;
+        state.error = undefined;
+        if (changed)
+            setPluginRuntimeState(state.record.canonicalId, state.state);
+    }
+    async failRunningState(state, runner, error) {
+        if (state.runner !== runner)
+            return;
+        if (state.healthTimer)
+            clearTimeout(state.healthTimer);
+        state.healthTimer = undefined;
+        try {
+            await runner.close();
         }
-    }
-}
-/** Convenience export for composition roots that only need the static catalog. */
-export function createChannelTypeDescriptors(supervisor) {
-    return supervisor.createChannelTypeDescriptors();
-}
-function createPluginState(record) {
-    return {
-        record,
-        desired: new Map(),
-        channelStatus: new Map(),
-        generation: 0,
-        failureCount: 0,
-        runtimeStatus: { state: "stopped", connected: false },
-    };
-}
-function validateRecord(record) {
-    if (record.name !== record.manifest.id) {
-        throw new Error(`runnable plugin id mismatch: ${record.name} != ${record.manifest.id}`);
-    }
-    if (!record.enabled) {
-        throw new Error(`plugin ${record.manifest.id} is disabled`);
-    }
-    const requested = new Set(record.manifest.requestedCapabilities);
-    for (const grant of record.grants) {
-        if (!requested.has(grant)) {
-            throw new Error(`plugin ${record.manifest.id} was granted an unrequested capability: ${grant}`);
+        catch (cleanupError) {
+            state.runtimeCleanupError = cleanupError;
+            this.failState(state, cleanupError);
+            return;
         }
+        state.runner = undefined;
+        try {
+            await state.hostRpc?.dispose();
+            state.hostRpc = undefined;
+        }
+        catch (cleanupError) {
+            state.runtimeCleanupError = cleanupError;
+            if (!state.stopping && !this.disposed)
+                this.failState(state, cleanupError);
+            return;
+        }
+        state.runtimeCleanupError = undefined;
+        removePluginRuntimeLease(pluginDataDir(state.record.marketplaceId, state.record.pluginId), RUNTIME_LEASE_ID);
+        if (state.stopping || this.disposed)
+            return;
+        this.failState(state, error);
+        this.scheduleRestart(state);
     }
-}
-function sameRuntimeRecord(left, right) {
-    return left.installPath === right.installPath &&
-        left.integrity === right.integrity &&
-        JSON.stringify(left.manifest) === JSON.stringify(right.manifest) &&
-        JSON.stringify(left.grants) === JSON.stringify(right.grants);
-}
-function assertHandshake(pluginId, grants, handshake) {
-    if (handshake.pluginId !== pluginId) {
-        throw new Error(`plugin runner identity mismatch: ${handshake.pluginId} != ${pluginId}`);
-    }
-    if (handshake.apiVersion !== PLUGIN_RUNNER_API_VERSION) {
-        throw new Error(`plugin runner API mismatch: ${handshake.apiVersion} != ${PLUGIN_RUNNER_API_VERSION}`);
-    }
-    if (handshake.grantedCapabilities.length !== grants.length ||
-        handshake.grantedCapabilities.some((capability, index) => capability !== grants[index])) {
-        throw new Error(`plugin runner capability handshake mismatch: ${pluginId}`);
-    }
-}
-function statusToChannelStatus(status) {
-    return {
-        connected: status.connected ?? status.state === "running",
-        lastError: status.lastError ?? null,
-        lastEventAt: status.lastEventAt ?? null,
-    };
-}
-function boundedContributionStatus(status) {
-    return {
-        ...status,
-        ...(typeof status.lastError === "string"
-            ? { lastError: boundedText(status.lastError, MAX_STATUS_ERROR_BYTES) }
-            : {}),
-        ...(typeof status.lastEventAt === "string"
-            ? { lastEventAt: boundedText(status.lastEventAt, 256) }
-            : {}),
-    };
-}
-function boundedRuntimeStatus(status) {
-    return {
-        ...status,
-        ...(typeof status.lastError === "string"
-            ? { lastError: boundedText(status.lastError, MAX_STATUS_ERROR_BYTES) }
-            : {}),
-        ...(typeof status.lastEventAt === "string"
-            ? { lastEventAt: boundedText(status.lastEventAt, 256) }
-            : {}),
-    };
-}
-function channelKey(contributionId, instanceId) {
-    return `channel:${contributionId}:${instanceId}`;
-}
-function positiveDelay(value, fallback) {
-    return value !== undefined && Number.isFinite(value) && value > 0 ? value : fallback;
-}
-function boundedReadyTimeout(value) {
-    if (value === undefined)
-        return DEFAULT_READY_TIMEOUT_MS;
-    if (!Number.isFinite(value) || value < 0) {
-        throw new Error("plugin runtime ready timeout must be a non-negative finite number");
-    }
-    return Math.min(value, MAX_READY_TIMEOUT_MS);
-}
-function createRuntimeReadyDeadline(timeoutMs) {
-    return { timeoutMs, expiresAt: Date.now() + timeoutMs };
-}
-function settleBeforeDeadline(promise, expiresAt, timeoutError) {
-    const remaining = expiresAt - Date.now();
-    if (remaining <= 0)
-        return Promise.reject(timeoutError());
-    return new Promise((resolve, reject) => {
-        const timer = setTimeout(() => reject(timeoutError()), remaining);
-        promise.then((value) => {
-            clearTimeout(timer);
-            resolve(value);
-        }, (error) => {
-            clearTimeout(timer);
-            reject(error);
-        });
-    });
-}
-function delay(milliseconds) {
-    return new Promise((resolve) => setTimeout(resolve, milliseconds));
-}
-function clearTimer(timer) {
-    if (timer)
-        clearTimeout(timer);
-}
-function runnerSnapshotState(state, disposed) {
-    if (state.runner)
-        return "running";
-    if (state.spawnPromise)
-        return "starting";
-    if (state.restartTimer)
-        return "backoff";
-    if (state.lastRunnerError && !disposed)
-        return "failed";
-    return "stopped";
-}
-function splitUtf8AtMost(value, maxBytes) {
-    if (Buffer.byteLength(value, "utf8") <= maxBytes)
-        return [value, ""];
-    let low = 0;
-    let high = value.length;
-    while (low < high) {
-        const middle = Math.ceil((low + high) / 2);
-        if (Buffer.byteLength(value.slice(0, middle), "utf8") <= maxBytes)
-            low = middle;
-        else
-            high = middle - 1;
+    runSerialized(identity, operation) {
+        const previous = this.queues.get(identity) ?? Promise.resolve();
+        const current = previous.catch(() => undefined).then(operation);
+        this.queues.set(identity, current);
+        void current.finally(() => {
+            if (this.queues.get(identity) === current)
+                this.queues.delete(identity);
+        }).catch(() => undefined);
+        return current;
     }
-    if (low > 0 && low < value.length && isHighSurrogate(value.charCodeAt(low - 1)))
-        low -= 1;
-    return [value.slice(0, low), value.slice(low)];
-}
-function isHighSurrogate(value) {
-    return value >= 0xd800 && value <= 0xdbff;
 }
-function messageOf(error) {
-    return boundedText(error instanceof Error ? error.message : String(error), MAX_STATUS_ERROR_BYTES);
+function cleanupFailure(errors, message) {
+    return errors.length === 1 ? errors[0] : new AggregateError(errors, message);
 }
-function boundedText(value, maxBytes) {
-    if (Buffer.byteLength(value, "utf8") <= maxBytes)
-        return value;
-    const marker = "…[truncated]";
-    const budget = maxBytes - Buffer.byteLength(marker, "utf8");
-    const [prefix] = splitUtf8AtMost(value, Math.max(1, budget));
-    return `${prefix}${marker}`;
+function blockingCleanupError(state) {
+    return state.runtimeCleanupError ?? state.settingsCleanupError;
 }
-function sameStartRequest(left, right) {
-    return JSON.stringify(left) === JSON.stringify(right);
+function isUnprovenProcessCleanup(error) {
+    return Boolean(error
+        && typeof error === "object"
+        && "code" in error
+        && error.code === "PROCESS_TREE_STUCK");
 }
-function clonePluginConfig(value) {
-    if (!value)
-        return {};
-    return cloneJsonValue(value, "options", new WeakSet());
+function healthState(health) {
+    return health.state;
 }
-function normalizeChatChannelConfig(contribution, value) {
-    const config = clonePluginConfig(value);
-    const schema = contribution.configSchema ?? [];
-    return schema.length > 0 ? normalizePluginConfig(schema, config) : config;
-}
-function cloneJsonValue(value, pathLabel, ancestors) {
-    if (value === null || typeof value === "string" || typeof value === "boolean")
-        return value;
-    if (typeof value === "number") {
-        if (!Number.isFinite(value))
-            throw new Error(`${pathLabel} must contain finite numbers`);
-        return value;
-    }
-    if (typeof value !== "object") {
-        throw new Error(`${pathLabel} must contain only JSON values`);
-    }
-    if (ancestors.has(value))
-        throw new Error(`${pathLabel} must not be cyclic`);
-    ancestors.add(value);
-    try {
-        if (Array.isArray(value)) {
-            return value.map((item, index) => cloneJsonValue(item, `${pathLabel}[${index}]`, ancestors));
-        }
-        if (Object.getPrototypeOf(value) !== Object.prototype && Object.getPrototypeOf(value) !== null) {
-            throw new Error(`${pathLabel} must contain only plain objects`);
-        }
-        const output = {};
-        for (const [key, item] of Object.entries(value)) {
-            output[key] = cloneJsonValue(item, `${pathLabel}.${key}`, ancestors);
-        }
-        return output;
-    }
-    finally {
-        ancestors.delete(value);
+async function verifyInstalledPackage(record) {
+    const integrity = await validatePluginPackageSnapshot(record.installPath);
+    if (integrity !== record.integrity) {
+        throw new Error(`plugin package integrity changed for "${record.canonicalId}"`);
     }
 }