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

package/dist/db.js

@@ -91,6 +91,56 @@ function migrate(conn) {
       UNIQUE(session_id, position)
     );
     CREATE INDEX IF NOT EXISTS idx_session_items_session ON session_items(session_id, position);
+    CREATE TABLE IF NOT EXISTS session_resources (
+      id               TEXT PRIMARY KEY,
+      session_id       TEXT NOT NULL,
+      client_upload_id TEXT NOT NULL,
+      upload_id        TEXT NOT NULL UNIQUE,
+      filename         TEXT NOT NULL,
+      media_type       TEXT NOT NULL CHECK(media_type IN ('image/png', 'image/jpeg', 'image/webp')),
+      byte_length      INTEGER NOT NULL,
+      uploaded_bytes   INTEGER NOT NULL DEFAULT 0,
+      sha256           TEXT,
+      width            INTEGER,
+      height           INTEGER,
+      state            TEXT NOT NULL DEFAULT 'uploading'
+        CHECK(state IN ('uploading', 'staged', 'committed')),
+      message_item_id  TEXT,
+      created_at       INTEGER NOT NULL,
+      committed_at     INTEGER,
+      UNIQUE(session_id, client_upload_id)
+    );
+    CREATE INDEX IF NOT EXISTS idx_session_resources_session
+      ON session_resources(session_id, created_at);
+    CREATE INDEX IF NOT EXISTS idx_session_resources_message
+      ON session_resources(message_item_id);
+    CREATE TABLE IF NOT EXISTS session_message_operations (
+      session_id       TEXT NOT NULL,
+      client_message_id TEXT NOT NULL,
+      request_hash     TEXT NOT NULL,
+      state            TEXT NOT NULL DEFAULT 'prepared'
+        CHECK(state IN (
+          'prepared',
+          'injecting',
+          'injected',
+          'mirrored',
+          'outcome_unknown',
+          'failed_not_started'
+        )),
+      error            TEXT,
+      created_at       INTEGER NOT NULL,
+      updated_at       INTEGER NOT NULL,
+      PRIMARY KEY(session_id, client_message_id)
+    );
+    CREATE TABLE IF NOT EXISTS session_message_operation_resources (
+      session_id        TEXT NOT NULL,
+      client_message_id TEXT NOT NULL,
+      resource_id       TEXT NOT NULL UNIQUE REFERENCES session_resources(id) ON DELETE CASCADE,
+      PRIMARY KEY(session_id, client_message_id, resource_id),
+      FOREIGN KEY(session_id, client_message_id)
+        REFERENCES session_message_operations(session_id, client_message_id)
+        ON DELETE CASCADE
+    );
     CREATE TABLE IF NOT EXISTS sessions (
       id               TEXT PRIMARY KEY,
       provider         TEXT,
@@ -103,6 +153,12 @@ function migrate(conn) {
       created_at       TEXT NOT NULL,
       updated_at       TEXT
     );
+    CREATE TABLE IF NOT EXISTS session_pending_messages (
+      session_id TEXT PRIMARY KEY REFERENCES sessions(id) ON DELETE CASCADE,
+      message    TEXT NOT NULL,
+      state      TEXT NOT NULL DEFAULT 'queued' CHECK(state IN ('queued', 'outcome_unknown')),
+      created_at TEXT NOT NULL
+    );
     CREATE TABLE IF NOT EXISTS session_emulator_bindings (
       session_id  TEXT PRIMARY KEY REFERENCES sessions(id) ON DELETE CASCADE,
       binding_id  TEXT NOT NULL UNIQUE,

package/dist/desktop-browser-host-client.d.ts

@@ -1,9 +1,10 @@
-import { type DesktopBrowserHostCommandFrame, type DesktopBrowserHostErrorCode, type DesktopBrowserHostEvent, type DesktopBrowserHostLeaseFrame, type DesktopBrowserHostSurfaceCapability, type DesktopBrowserHostSurfaceFrame } from "@rynx-ai/protocol/desktop-browser-host";
+import { type DesktopBrowserHostCommandFrame, type DesktopBrowserHostErrorCode, type DesktopBrowserHostEvent, type DesktopBrowserHostLeaseFrame, type DesktopBrowserHostPresentation, type DesktopBrowserHostSurfaceCapability, type DesktopBrowserHostSurfaceFrame } from "@rynx-ai/protocol/desktop-browser-host";
 export interface ResidentDesktopBrowserHostConnectOptions {
     hostInstanceId: string;
     /** Advertise only handlers that are installed in this main-process Host. */
     capabilities: {
         semanticPageBinding: boolean;
+        presentation: DesktopBrowserHostPresentation;
         surface: DesktopBrowserHostSurfaceCapability;
     };
     signal?: AbortSignal;

package/dist/desktop-browser-host-client.js

@@ -12,6 +12,7 @@ export async function connectResidentDesktopBrowserHost(options) {
         hostInstanceId: options.hostInstanceId,
         capabilities: {
             semanticPageBinding: options.capabilities.semanticPageBinding,
+            presentation: options.capabilities.presentation,
             surface: options.capabilities.surface,
         },
     });
@@ -384,7 +385,8 @@ function rawDataBytes(data) {
 }
 function isMutatingCommand(command) {
     return command.command.method !== "browser.snapshot" &&
-        command.command.method !== "browser.cdp-endpoint";
+        command.command.method !== "browser.cdp-endpoint" &&
+        command.command.method !== "page.cdp-endpoint";
 }
 async function abortableTimeout(promise, timeoutMs, signal) {
     signal?.throwIfAborted();

package/dist/direct-runtime-authenticator.js

@@ -1,5 +1,5 @@
 import { createHash, createPublicKey, randomBytes, randomUUID, verify, } from "node:crypto";
-import { DIRECT_RUNTIME_BINDING_PROTOCOL, DIRECT_RUNTIME_BROWSER_SURFACE_BINDING_PROTOCOL, encodeClientAuthenticateCanonical, encodeClientAuthenticateProofPayload, encodeServerHelloCanonical, parseServerAccepted, parseServerHello, } from "@rynx-ai/protocol/direct-runtime";
+import { DIRECT_RUNTIME_BINDING_PROTOCOL, DIRECT_RUNTIME_BROWSER_INSPECT_BINDING_PROTOCOL, DIRECT_RUNTIME_BROWSER_SURFACE_BINDING_PROTOCOL, encodeClientAuthenticateCanonical, encodeClientAuthenticateProofPayload, encodeServerHelloCanonical, parseServerAccepted, parseServerHello, } from "@rynx-ai/protocol/direct-runtime";
 /** Daemon-side proof verification shared by Direct control and Browser Surface bindings. */
 export class DaemonDirectRuntimeAuthenticator {
     identity;
@@ -38,8 +38,8 @@ export class DaemonDirectRuntimeAuthenticator {
         if (clientAuthenticate.role !== role || serverHello.role !== role) {
             throw new Error("unsupported Direct Runtime channel role");
         }
-        if (role === "browser-surface" && clientAuthenticate.mode !== "connect") {
-            throw new Error("Browser Surface channels require an existing Direct Runtime grant");
+        if (role !== "control" && clientAuthenticate.mode !== "connect") {
+            throw new Error(`${role === "browser-surface" ? "Browser Surface" : "Browser Inspect"} channels require an existing Direct Runtime grant`);
         }
         if (clientAuthenticate.daemonId !== serverHello.daemonId ||
             clientAuthenticate.daemonInstanceId !== serverHello.daemonInstanceId ||
@@ -103,9 +103,14 @@ export class DaemonDirectRuntimeAuthenticator {
     }
 }
 function bindingProtocol(role) {
-    return role === "control"
-        ? DIRECT_RUNTIME_BINDING_PROTOCOL
-        : DIRECT_RUNTIME_BROWSER_SURFACE_BINDING_PROTOCOL;
+    switch (role) {
+        case "control":
+            return DIRECT_RUNTIME_BINDING_PROTOCOL;
+        case "browser-surface":
+            return DIRECT_RUNTIME_BROWSER_SURFACE_BINDING_PROTOCOL;
+        case "browser-inspect":
+            return DIRECT_RUNTIME_BROWSER_INSPECT_BINDING_PROTOCOL;
+    }
 }
 function withoutSignature(value) {
     const { signature: _signature, ...fields } = value;

package/dist/headless-browser-host.js

@@ -31,6 +31,7 @@ const MAX_SURFACE_QUALITY = 100;
 const MIN_SURFACE_FALLBACK_INTERVAL_MS = 200;
 const MIN_SURFACE_SCREENCAST_IDLE_MS = 250;
 const DEVTOOLS_BROWSER_PATH = /^\/devtools\/browser\/[A-Za-z0-9._~-]+$/;
+const DEVTOOLS_TARGET_ID_PATTERN = /^[A-Za-z0-9._~-]+$/;
 const CONTROL_CHARACTER_PATTERN = /[\u0000-\u001f\u007f]/;
 const CONTROL_CHARACTER_GLOBAL_PATTERN = /[\u0000-\u001f\u007f]/g;
 export function createHeadlessBrowserHost(options = {}) {
@@ -241,7 +242,23 @@ class HeadlessBrowserHandle {
     }
     async getCdpEndpoint() {
         this.ensureAvailable();
-        return { endpoint: this.host.endpoint, engineVersion: this.host.engineVersion };
+        return {
+            endpoint: this.host.endpoint,
+            engineVersion: this.host.engineVersion,
+            ...(this.activeTargetId ? { pageTargetId: this.activeTargetId } : {}),
+        };
+    }
+    async getPageCdpEndpoint(hostPageId) {
+        this.ensureAvailable();
+        const target = this.requireTarget(hostPageId);
+        if (!DEVTOOLS_TARGET_ID_PATTERN.test(target.targetId)) {
+            throw new SessionBrowserHostError("unavailable", "Headless Browser Page cannot be exposed for inspection");
+        }
+        const browserEndpoint = new URL(this.host.endpoint);
+        return {
+            endpoint: `${browserEndpoint.protocol}//${browserEndpoint.host}/devtools/page/${target.targetId}`,
+            engineVersion: this.host.engineVersion,
+        };
     }
     openSurface(input) {
         return this.exclusive(async () => {

package/dist/index-daemon.js

@@ -11,13 +11,28 @@ import { startRynxDaemonServer } from "./daemon-server.js";
 import { installStdioEpipeGuard } from "./stdio-epipe-guard.js";
 installStdioEpipeGuard();
 async function main() {
-    const server = await startRynxDaemonServer();
+    const followsApp = process.env.RYNX_DAEMON_LIFECYCLE === "follow-app";
+    let parentDisconnected = followsApp && !process.connected;
+    const recordParentDisconnect = () => {
+        parentDisconnected = true;
+    };
+    if (followsApp)
+        process.once("disconnect", recordParentDisconnect);
+    let server;
+    try {
+        server = await startRynxDaemonServer();
+    }
+    catch (error) {
+        process.off("disconnect", recordParentDisconnect);
+        throw error;
+    }
     let shutdownPromise;
     const shutdown = (signal) => {
         if (shutdownPromise)
             return shutdownPromise;
         process.off("SIGINT", onSigint);
         process.off("SIGTERM", onSigterm);
+        process.off("disconnect", onDisconnect);
         shutdownPromise = (async () => {
             console.log(JSON.stringify({ level: "info", type: "shutdown", signal }));
             await server.shutdown();
@@ -34,8 +49,20 @@ async function main() {
     const onSigterm = () => {
         void shutdown("SIGTERM");
     };
+    const onDisconnect = () => {
+        if (process.env.RYNX_DAEMON_LIFECYCLE === "follow-app") {
+            void shutdown("APP_DISCONNECT");
+        }
+    };
     process.once("SIGINT", onSigint);
     process.once("SIGTERM", onSigterm);
+    if (followsApp) {
+        process.once("disconnect", onDisconnect);
+        process.off("disconnect", recordParentDisconnect);
+        if (parentDisconnected || !process.connected) {
+            void shutdown("APP_DISCONNECT");
+        }
+    }
 }
 main().catch((err) => {
     console.error(`Fatal error: ${err instanceof Error ? (err.stack ?? err.message) : String(err)}`);

package/dist/maintenance-management.d.ts

@@ -0,0 +1,11 @@
+import type { DaemonCleanupSessionsInput, DaemonCleanupSessionsResult } from "@rynx-ai/protocol/control";
+import { type CleanupOptions } from "./migrations/cleanup-legacy-sessions.js";
+export interface MaintenanceManagementService {
+    cleanupSessions(input: DaemonCleanupSessionsInput): DaemonCleanupSessionsResult;
+}
+export interface MaintenanceManagementServiceOptions {
+    codexStorePath?: string;
+    cleanup?: (options: CleanupOptions) => DaemonCleanupSessionsResult;
+}
+/** Daemon-owned maintenance mutations kept behind authenticated local RPC. */
+export declare function createMaintenanceManagementService(options: MaintenanceManagementServiceOptions): MaintenanceManagementService;

package/dist/maintenance-management.js

@@ -0,0 +1,13 @@
+import { cleanupLegacySessions, } from "./migrations/cleanup-legacy-sessions.js";
+/** Daemon-owned maintenance mutations kept behind authenticated local RPC. */
+export function createMaintenanceManagementService(options) {
+    const cleanup = options.cleanup ?? cleanupLegacySessions;
+    return {
+        cleanupSessions: (input) => cleanup({
+            ...(options.codexStorePath
+                ? { codexStorePath: options.codexStorePath }
+                : {}),
+            dryRun: input.dryRun ?? false,
+        }),
+    };
+}

package/dist/plugin-installer.d.ts

@@ -21,6 +21,36 @@ export interface InstallPluginOptions {
     expectedId?: string;
     /** Explicitly allow package/dependency lifecycle build scripts in staging. */
     allowScripts?: boolean;
+    /** Pre-build package digest explicitly approved before any scripts execute. */
+    expectedDigest?: string;
+}
+export interface PreparePluginInstallationOptions {
+    signal?: AbortSignal;
+    /** Dependency injection for offline tests and alternate package fetchers. */
+    materializer?: PluginPackageMaterializer;
+    /** Require the inspected manifest to retain this id (used by update). */
+    expectedId?: string;
+    /** Explicitly allow package/dependency lifecycle build scripts in staging. */
+    allowScripts?: boolean;
+}
+export interface CommitPreparedPluginInstallationOptions {
+    grants: readonly PluginCapability[];
+    expectedDigest: string;
+    signal?: AbortSignal;
+}
+/**
+ * One daemon-owned, already materialized artifact. The handle is process-local
+ * and one-shot: commit or discard consumes it.
+ */
+export interface PreparedPluginInstallation {
+    readonly name: string;
+    readonly source: PluginSource;
+    readonly version?: string;
+    readonly manifest: PluginManifestV1;
+    readonly integrity: string;
+    readonly existing?: PluginRecord;
+    commit(options: CommitPreparedPluginInstallationOptions): Promise<InstallResult>;
+    discard(): void;
 }
 /**
  * Install or replace one arbitrary npm/local/git/URL plugin package.
@@ -29,6 +59,11 @@ export interface InstallPluginOptions {
  * the previously registered installation untouched.
  */
 export declare function installPlugin(spec: string, onProgress?: (line: string) => void, opts?: InstallPluginOptions): Promise<InstallResult>;
+/**
+ * Materialize, build (only when explicitly allowed), inspect, and hash one
+ * plugin into host-owned staging without mutating the registry.
+ */
+export declare function preparePluginInstallation(spec: string, onProgress?: (line: string) => void, opts?: PreparePluginInstallationOptions): Promise<PreparedPluginInstallation>;
 /**
  * Remove the registry row but retain the immutable package until the next
  * daemon boot. A currently running supervisor may still be executing it.

package/dist/plugin-installer.js

@@ -28,6 +28,67 @@ const DEFAULT_STAGING_GC_AGE_MS = 24 * 60 * 60 * 1_000;
  * the previously registered installation untouched.
  */
 export async function installPlugin(spec, onProgress = () => { }, opts = {}) {
+    const prepared = await preparePluginInstallation(spec, onProgress, opts);
+    try {
+        if (opts.expectedDigest !== undefined &&
+            !/^sha256-[A-Za-z0-9+/]{43}={0,2}$/.test(opts.expectedDigest)) {
+            throw new Error("expected plugin digest is invalid");
+        }
+        if (opts.expectedDigest !== undefined &&
+            opts.expectedDigest !== prepared.integrity) {
+            throw new Error(`prepared plugin digest ${prepared.integrity} does not match ` +
+                `expected digest ${opts.expectedDigest}`);
+        }
+        if (prepared.manifest.requiresBuildScripts) {
+            if (!opts.allowScripts) {
+                throw new Error(`plugin "${prepared.name}" requires package build scripts; review digest ` +
+                    `${prepared.integrity} and re-run with --allow-scripts ` +
+                    `--expect-digest ${prepared.integrity}`);
+            }
+            if (opts.expectedDigest === undefined) {
+                throw new Error(`build-script approval must be bound to the prepared artifact; ` +
+                    `re-run with --expect-digest ${prepared.integrity}`);
+            }
+        }
+        const existing = prepared.existing;
+        if (existing && opts.onConflict && !(await opts.onConflict(existing))) {
+            return {
+                name: prepared.name,
+                source: prepared.source,
+                ...(prepared.version ? { version: prepared.version } : {}),
+                skipped: true,
+            };
+        }
+        if (opts.signal?.aborted)
+            throw new Error("plugin installation aborted");
+        const requested = new Set(prepared.manifest.requestedCapabilities);
+        if (!opts.approveCapabilities &&
+            opts.grants === undefined &&
+            !existing &&
+            requested.size > 0) {
+            throw new Error(`plugin "${prepared.name}" requests host capabilities; explicit grants or approval are required`);
+        }
+        const grants = opts.approveCapabilities
+            ? await opts.approveCapabilities(prepared.manifest, existing)
+            : opts.grants ??
+                (existing
+                    ? existing.grants.filter((capability) => requested.has(capability))
+                    : []);
+        return await prepared.commit({
+            grants,
+            expectedDigest: opts.expectedDigest ?? prepared.integrity,
+            signal: opts.signal,
+        });
+    }
+    finally {
+        prepared.discard();
+    }
+}
+/**
+ * Materialize, build (only when explicitly allowed), inspect, and hash one
+ * plugin into host-owned staging without mutating the registry.
+ */
+export async function preparePluginInstallation(spec, onProgress = () => { }, opts = {}) {
     if (!spec.trim())
         throw new Error("plugin spec must not be empty");
     const progress = safeProgress(onProgress);
@@ -45,6 +106,7 @@ export async function installPlugin(spec, onProgress = () => { }, opts = {}) {
     const stagedPackage = join(transactionDir, "package");
     let finalPath;
     let registryUpdated = false;
+    let consumed = false;
     try {
         await (opts.materializer ?? materializePluginPackage)({
             spec: storedSpec,
@@ -53,123 +115,152 @@ export async function installPlugin(spec, onProgress = () => { }, opts = {}) {
             onProgress: progress,
             signal: opts.signal,
         });
-        let inspected = inspectPluginPackage(stagedPackage, { requireEntries: false });
-        if (inspected.manifest.requiresBuildScripts && !opts.allowScripts) {
-            throw new Error(`plugin "${inspected.manifest.id}" requires package build scripts; ` +
-                "review the package and re-run with --allow-scripts");
-        }
+        let inspected = await inspectPluginPackage(stagedPackage, {
+            requireEntries: false,
+            signal: opts.signal,
+        });
         if (opts.allowScripts && !inspected.manifest.requiresBuildScripts) {
             throw new Error(`plugin "${inspected.manifest.id}" does not declare requiresBuildScripts; ` +
                 "refusing unnecessary --allow-scripts approval");
         }
-        if (inspected.manifest.requiresBuildScripts) {
-            const manifestBeforeBuild = JSON.stringify(inspected.manifest);
-            const versionBeforeBuild = inspected.version;
-            progress(`running explicitly approved build scripts for plugin "${inspected.manifest.id}"`);
-            await rebuildPluginPackage(stagedPackage, progress, opts.signal);
-            const built = inspectPluginPackage(stagedPackage);
-            if (JSON.stringify(built.manifest) !== manifestBeforeBuild ||
-                built.version !== versionBeforeBuild) {
-                throw new Error("plugin build scripts changed static package identity or manifest metadata");
-            }
-            inspected = built;
-        }
-        else {
-            inspected = inspectPluginPackage(stagedPackage);
+        const requiresBuildScripts = Boolean(inspected.manifest.requiresBuildScripts);
+        if (!requiresBuildScripts) {
+            inspected = await inspectPluginPackage(stagedPackage, { signal: opts.signal });
         }
         const name = inspected.manifest.id;
         if (opts.expectedId && name !== opts.expectedId) {
             throw new Error(`plugin update id mismatch: expected "${opts.expectedId}", received "${name}"`);
         }
         const existing = getPlugin(name);
-        if (existing && opts.onConflict && !(await opts.onConflict(existing))) {
-            return {
-                name,
-                source,
-                ...(inspected.version ? { version: inspected.version } : {}),
-                skipped: true,
-            };
-        }
-        if (opts.signal?.aborted)
-            throw new Error("plugin installation aborted");
-        const requested = new Set(inspected.manifest.requestedCapabilities);
-        if (!opts.approveCapabilities &&
-            opts.grants === undefined &&
-            !existing &&
-            requested.size > 0) {
-            throw new Error(`plugin "${name}" requests host capabilities; explicit grants or approval are required`);
-        }
-        const grants = opts.approveCapabilities
-            ? await opts.approveCapabilities(inspected.manifest, existing)
-            : opts.grants ??
-                (existing
-                    ? existing.grants.filter((capability) => requested.has(capability))
-                    : []);
-        for (const grant of grants) {
-            if (!requested.has(grant)) {
-                throw new Error(`plugin capability was not requested: ${grant}`);
-            }
-        }
-        db().transaction(() => {
-            const current = getPlugin(name);
-            if (!samePluginGeneration(existing, current)) {
-                throw new Error(`plugin "${name}" changed concurrently; retry the installation`);
-            }
-            const leases = activeRuntimeLeases(name, storage.installationsRoot);
-            if (leases.length > 0) {
-                throw new Error(`plugin "${name}" has active runtime lease(s): ${leases
-                    .map((lease) => lease.leaseId)
-                    .join(", ")}; stop its managed services or CLI commands before updating`);
+        const cleanup = () => {
+            if (!registryUpdated && finalPath) {
+                removeOwnedInstallation(storage.installationsRoot, basename(dirname(finalPath)), finalPath);
             }
-            const idRoot = ensureDirectDirectory(storage.installationsRoot, name, "plugin id directory");
-            const installationId = randomUUID();
-            finalPath = join(idRoot, installationId);
-            const marker = promotionMarkerPath(idRoot, installationId);
-            writePromotionMarker(marker);
             try {
-                renameSync(stagedPackage, finalPath);
+                rmSync(transactionDir, { recursive: true, force: true });
             }
-            catch (error) {
-                rmSync(marker, { force: true });
-                finalPath = undefined;
-                throw error;
+            catch {
+                /* orphaned staging is inactive and can be collected later */
             }
-            progress(`staged validated plugin "${name}" → ${finalPath}`);
-            upsertPlugin({
-                name,
-                spec: storedSpec,
-                source,
-                version: inspected.version,
-                installPath: finalPath,
-                manifest: inspected.manifest,
-                integrity: inspected.integrity,
-                grants,
-                enabled: current?.enabled,
-            });
-        }).immediate();
-        registryUpdated = true;
-        if (existing?.installPath && existing.installPath !== finalPath) {
-            progress(`retained superseded installation until the daemon switches versions`);
-        }
-        progress(`installed plugin "${name}"${inspected.version ? `@${inspected.version}` : ""}`);
+        };
+        const preparedManifest = cloneManifest(inspected.manifest);
+        const preparedExisting = existing ? clonePluginRecord(existing) : undefined;
         return {
             name,
             source,
             ...(inspected.version ? { version: inspected.version } : {}),
+            manifest: cloneManifest(preparedManifest),
+            integrity: inspected.integrity,
+            ...(preparedExisting ? { existing: clonePluginRecord(preparedExisting) } : {}),
+            commit: async ({ grants, expectedDigest, signal }) => {
+                if (consumed)
+                    throw new Error("prepared plugin installation was already consumed");
+                consumed = true;
+                try {
+                    if (signal?.aborted)
+                        throw new Error("plugin installation aborted");
+                    if (expectedDigest !== inspected.integrity) {
+                        throw new Error("prepared plugin digest does not match expected digest");
+                    }
+                    const rechecked = await inspectPluginPackage(stagedPackage, {
+                        ...(requiresBuildScripts ? { requireEntries: false } : {}),
+                        signal,
+                    });
+                    if (rechecked.integrity !== inspected.integrity ||
+                        rechecked.version !== inspected.version ||
+                        JSON.stringify(rechecked.manifest) !== JSON.stringify(preparedManifest)) {
+                        throw new Error("prepared plugin artifact changed after approval");
+                    }
+                    let promoted = rechecked;
+                    if (requiresBuildScripts) {
+                        if (!opts.allowScripts) {
+                            throw new Error(`plugin "${name}" requires package build scripts; ` +
+                                `approve digest ${inspected.integrity} before running scripts`);
+                        }
+                        progress(`running digest-approved build scripts for plugin "${name}"`);
+                        await rebuildPluginPackage(stagedPackage, progress, signal);
+                        const built = await inspectPluginPackage(stagedPackage, { signal });
+                        if (JSON.stringify(built.manifest) !== JSON.stringify(preparedManifest) ||
+                            built.version !== inspected.version) {
+                            throw new Error("plugin build scripts changed static package identity or manifest metadata");
+                        }
+                        promoted = built;
+                    }
+                    const requested = new Set(preparedManifest.requestedCapabilities);
+                    for (const grant of grants) {
+                        if (!requested.has(grant)) {
+                            throw new Error(`plugin capability was not requested: ${grant}`);
+                        }
+                    }
+                    if (new Set(grants).size !== grants.length) {
+                        throw new Error("plugin grants must be unique");
+                    }
+                    db().transaction(() => {
+                        const current = getPlugin(name);
+                        if (!samePluginGeneration(existing, current)) {
+                            throw new Error(`plugin "${name}" changed concurrently; retry the installation`);
+                        }
+                        const leases = activeRuntimeLeases(name, storage.installationsRoot);
+                        if (leases.length > 0) {
+                            throw new Error(`plugin "${name}" has active runtime lease(s): ${leases
+                                .map((lease) => lease.leaseId)
+                                .join(", ")}; stop its managed services or CLI commands before updating`);
+                        }
+                        const idRoot = ensureDirectDirectory(storage.installationsRoot, name, "plugin id directory");
+                        const installationId = randomUUID();
+                        finalPath = join(idRoot, installationId);
+                        const marker = promotionMarkerPath(idRoot, installationId);
+                        writePromotionMarker(marker);
+                        try {
+                            renameSync(stagedPackage, finalPath);
+                        }
+                        catch (error) {
+                            rmSync(marker, { force: true });
+                            finalPath = undefined;
+                            throw error;
+                        }
+                        progress(`staged validated plugin "${name}" → ${finalPath}`);
+                        upsertPlugin({
+                            name,
+                            spec: storedSpec,
+                            source,
+                            version: promoted.version,
+                            installPath: finalPath,
+                            manifest: preparedManifest,
+                            integrity: promoted.integrity,
+                            grants,
+                            enabled: current?.enabled,
+                        });
+                    }).immediate();
+                    registryUpdated = true;
+                    if (existing?.installPath && existing.installPath !== finalPath) {
+                        progress("retained superseded installation until the daemon switches versions");
+                    }
+                    progress(`installed plugin "${name}"${promoted.version ? `@${promoted.version}` : ""}`);
+                    return {
+                        name,
+                        source,
+                        ...(promoted.version ? { version: promoted.version } : {}),
+                    };
+                }
+                finally {
+                    cleanup();
+                }
+            },
+            discard: () => {
+                if (consumed)
+                    return;
+                consumed = true;
+                cleanup();
+            },
         };
     }
-    finally {
-        // Once registered, finalPath is the active immutable installation and must
-        // outlive this transaction. Everything else under staging is disposable.
+    catch (error) {
         if (!registryUpdated && finalPath) {
             removeOwnedInstallation(storage.installationsRoot, basename(dirname(finalPath)), finalPath);
         }
-        try {
-            rmSync(transactionDir, { recursive: true, force: true });
-        }
-        catch {
-            /* orphaned staging is inactive and can be collected later */
-        }
+        rmSync(transactionDir, { recursive: true, force: true });
+        throw error;
     }
 }
 /**
@@ -312,6 +403,16 @@ function samePluginGeneration(before, current) {
         return before === current;
     return JSON.stringify(before) === JSON.stringify(current);
 }
+function cloneManifest(manifest) {
+    return JSON.parse(JSON.stringify(manifest));
+}
+function clonePluginRecord(record) {
+    return {
+        ...record,
+        ...(record.manifest ? { manifest: cloneManifest(record.manifest) } : {}),
+        grants: [...record.grants],
+    };
+}
 function writeStagingOwner(transactionDir) {
     writeFileSync(join(transactionDir, STAGING_OWNER_FILE), `${JSON.stringify({ schemaVersion: 1, pid: process.pid, createdAt: new Date().toISOString() })}\n`, { encoding: "utf8", mode: 0o600, flag: "wx" });
 }