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

package/dist/daemon-server.js

@@ -7,15 +7,24 @@
  */
 import { randomBytes, randomUUID } from "node:crypto";
 import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { createRequire } from "node:module";
+import { fileURLToPath } from "node:url";
 import { dirname, join } from "node:path";
+import WebSocket from "ws";
 import { loadConfig, rynxHome } from "@rynx-ai/core";
+import { LOCAL_MANAGEMENT_PROTOCOL, } from "@rynx-ai/protocol/control";
 import { REMOTE_RUNTIME_CORE_PROTOCOL } from "@rynx-ai/protocol/remote-runtime";
+import { RUNTIME_BROWSER_INSPECT_MAX_MESSAGE_BYTES, RUNTIME_BROWSER_INSPECT_SEMANTIC_CAPABILITY, } from "@rynx-ai/protocol/runtime-browser-inspect";
 import { RUNTIME_BROWSER_SURFACE_SEMANTIC_CAPABILITY } from "@rynx-ai/protocol/runtime-browser-surface";
 import { RUNTIME_EMULATOR_SURFACE_SEMANTIC_CAPABILITY } from "@rynx-ai/protocol/runtime-emulator-surface";
-import { createDaemonRuntimeHost, createDesktopFirstSessionBrowserHost, createRunnerSessionTerminalHost, createSessionRuntimeServices, DesktopBrowserHostRegistry, DirectRuntimeConnectionHub, MachineSessionService, RemoteRuntimeDispatcher, SessionBrowserService, SessionBrowserSurfaceCoordinator, SessionEmulatorService, startServer, startDirectRuntimeServer, } from "@rynx-ai/server";
+import { createDaemonRuntimeHost, createDesktopFirstSessionBrowserHost, createRunnerSessionTerminalHost, createSessionRuntimeServices, DesktopBrowserHostAbsentError, DesktopBrowserHostRegistry, DirectRuntimeConnectionHub, DirectRuntimeBrowserInspectHostError, MachineSessionService, RemoteRuntimeDispatcher, SessionBrowserService, SessionBrowserServiceError, SessionBrowserSurfaceCoordinator, SessionEmulatorService, startServer, startDirectRuntimeServer, } from "@rynx-ai/server";
+import { APP_BROWSER_HOST_BOOTSTRAP_TYPE, AppBrowserHostSupervisor, parseAppBrowserHostLaunchConfig, } from "./app-browser-host-supervisor.js";
 import { buildControlDeps } from "./control-deps.js";
+import { createBrowserArtifactManagementService } from "./browser-artifact-management.js";
+import { createDaemonBuildStatus } from "./daemon-build-status.js";
 import { BrowserRunnerSessionContextProvider } from "./browser-runner-session-context.js";
 import { isChromeForTestingHostSupported } from "./chrome-for-testing-store.js";
+import { ChromeInspectionManager, } from "./chrome-inspection-manager.js";
 import { createHeadlessBrowserHost } from "./headless-browser-host.js";
 import { acquireDaemonOwner } from "./daemon-owner.js";
 import { DaemonDirectRuntimeAuthenticator } from "./direct-runtime-authenticator.js";
@@ -23,15 +32,19 @@ import { DurableEmbeddedBrowserProfileHost } from "./embedded-browser-profile-cl
 import { loadDirectRuntimeConfig, } from "./direct-runtime-config.js";
 import { isDaemonDirectRuntimeHostingSupported, loadOrCreateDaemonDirectRuntimeEncryptionIdentity, loadOrCreateDaemonInstallationIdentity, } from "./installation-id.js";
 import { cleanupLegacySessions } from "./migrations/cleanup-legacy-sessions.js";
+import { createMaintenanceManagementService } from "./maintenance-management.js";
+import { PluginManagementService } from "./plugin-management-service.js";
 import { PluginSupervisor } from "./plugin-supervisor.js";
 import { pruneInactivePluginInstallations } from "./plugin-installer.js";
 import { runPluginCliCommand } from "./plugin-cli.js";
 import { getPlugin, isRunnablePluginRecord, listEnabledPlugins } from "./plugin-store.js";
 import { loadPlugins, resolveChannelInstances } from "./registry.js";
 import { SqliteSessionLogStore } from "./session-log-store.js";
+import { SqliteSessionResourceStore } from "./session-resource-store.js";
 import { SessionBrowserCapabilityStore } from "./session-browser-capability-store.js";
 import { SqliteSessionEmulatorBindingStore } from "./session-emulator-binding-store.js";
 import { sessionRegistry } from "./session-meta-store.js";
+import { sessionPendingMessageStore } from "./session-pending-message-store.js";
 import { RemoteRuntimeAccessStore } from "./remote-runtime-access-store.js";
 import { DaemonRemoteRuntimeAdmin } from "./remote-runtime-admin.js";
 import { FileRemoteRuntimeCredentialStore } from "./remote-runtime-credential-store.js";
@@ -40,7 +53,15 @@ import { DaemonRuntimeTargetControl } from "./remote-runtime-target-control.js";
 import { RemoteRuntimeTargetStore } from "./remote-runtime-target-store.js";
 import { ProviderCliService } from "./provider-cli-service.js";
 const PLUGIN_CLI_OUTPUT_MAX_BYTES = 256 * 1024;
+const BROWSER_INSPECT_OPEN_TIMEOUT_MS = 10_000;
+const BROWSER_INSPECT_CLOSE_TIMEOUT_MS = 1_000;
+const BROWSER_INSPECT_MAX_QUEUED_BYTES = 32 * 1024 * 1024;
 const DIRECT_RUNTIME_HOSTING_UNSUPPORTED = "Direct Runtime hosting is supported only on macOS and Linux until protected server-key storage is available on other operating systems";
+const require = createRequire(import.meta.url);
+const DAEMON_PACKAGE_VERSION = readDaemonPackageVersion();
+export function daemonActivityBlocksShutdown(activity) {
+    return activity.runningTurns > 0 || activity.pendingInteractions > 0;
+}
 function defaultWarn(message) {
     console.warn(JSON.stringify({ level: "warn", type: "channel-registry", msg: message }));
 }
@@ -53,6 +74,7 @@ function unsupportedRemoteRuntimeAdmin(reason) {
         createPairingOffer: unsupported,
         listClientGrants: unsupported,
         revokeClientGrant: unsupported,
+        deleteRevokedClientGrant: unsupported,
     };
 }
 function logLegacyCleanup(config) {
@@ -81,6 +103,14 @@ function logLegacyCleanup(config) {
 function dialableHost(host) {
     return host === "0.0.0.0" || host === "::" || host.trim() === "" ? "127.0.0.1" : host;
 }
+function daemonControlOrigin(config) {
+    const host = dialableHost(config.HOST);
+    const unwrappedHost = host.replace(/^\[|\]$/g, "");
+    const authorityHost = unwrappedHost.includes(":")
+        ? `[${unwrappedHost}]`
+        : unwrappedHost;
+    return `http://${authorityHost}:${config.PORT}`;
+}
 function controlEndpointFile() {
     return join(rynxHome(), "control.json");
 }
@@ -90,11 +120,13 @@ async function writeControlEndpoint(config, managementToken) {
     await mkdir(dirname(file), { recursive: true });
     try {
         await writeFile(temporary, `${JSON.stringify({
-            origin: `http://${dialableHost(config.HOST)}:${config.PORT}`,
+            origin: daemonControlOrigin(config),
             host: config.HOST,
             port: config.PORT,
             pid: process.pid,
             managementToken,
+            managementProtocol: LOCAL_MANAGEMENT_PROTOCOL,
+            ...controlEndpointDistributionMetadata(),
             updatedAt: new Date().toISOString(),
         }, null, 2)}\n`, { encoding: "utf8", mode: 0o600 });
         await rename(temporary, file);
@@ -103,6 +135,38 @@ async function writeControlEndpoint(config, managementToken) {
         await rm(temporary, { force: true });
     }
 }
+function controlEndpointDistributionMetadata() {
+    const distribution = process.env.RYNX_DISTRIBUTION === "app"
+        ? "app"
+        : "standalone";
+    const productVersion = boundedEnvironmentMetadata(process.env.RYNX_PRODUCT_VERSION, 128) ?? DAEMON_PACKAGE_VERSION;
+    const buildId = boundedEnvironmentMetadata(process.env.RYNX_BUILD_ID, 256) ?? `${distribution}:${productVersion}`;
+    const requestedLifecycle = process.env.RYNX_DAEMON_LIFECYCLE;
+    const daemonLifecycle = distribution === "standalone"
+        ? "standalone"
+        : requestedLifecycle === "resident"
+            ? "resident"
+            : "follow-app";
+    return { distribution, productVersion, buildId, daemonLifecycle };
+}
+function boundedEnvironmentMetadata(value, maxLength) {
+    if (!value ||
+        value.length > maxLength ||
+        value.trim() !== value ||
+        /[\u0000-\u001f\u007f]/.test(value)) {
+        return undefined;
+    }
+    return value;
+}
+function readDaemonPackageVersion() {
+    try {
+        const version = require("../package.json").version;
+        return boundedEnvironmentMetadata(typeof version === "string" ? version : undefined, 128) ?? "development";
+    }
+    catch {
+        return "development";
+    }
+}
 async function removeControlEndpointForCurrentProcess() {
     try {
         const file = controlEndpointFile();
@@ -115,13 +179,14 @@ async function removeControlEndpointForCurrentProcess() {
         // Best effort only; stale endpoint files are ignored by the client fallback.
     }
 }
-export async function startRynxDaemonServer({ config, warn = defaultWarn, writeEndpoint = writeControlEndpoint, acquireOwner = acquireDaemonOwner, loadDirectConfig = loadDirectRuntimeConfig, startDirectServer = startDirectRuntimeServer, } = {}) {
+export async function startRynxDaemonServer({ config, warn = defaultWarn, writeEndpoint = writeControlEndpoint, acquireOwner = acquireDaemonOwner, loadDirectConfig = loadDirectRuntimeConfig, startDirectServer = startDirectRuntimeServer, createChromeInspectionManager = (options) => ChromeInspectionManager.create(options), createBrowserHostSupervisor = (options) => new AppBrowserHostSupervisor(options), } = {}) {
     const owner = await acquireOwner();
     let ownerManagedByServer = false;
     try {
         const appConfig = config ?? loadConfig();
+        const appBrowserHostLaunch = parseAppBrowserHostLaunchConfig();
         const directHostingSupported = isDaemonDirectRuntimeHostingSupported();
-        const runtimeBrowserSupported = isChromeForTestingHostSupported();
+        const runtimeBrowserSupported = appBrowserHostLaunch !== undefined || isChromeForTestingHostSupported();
         const directConfig = directHostingSupported
             ? await loadDirectConfig()
             : undefined;
@@ -134,6 +199,7 @@ export async function startRynxDaemonServer({ config, warn = defaultWarn, writeE
             warn(DIRECT_RUNTIME_HOSTING_UNSUPPORTED);
         const daemonInstanceId = randomUUID();
         const daemonStartedAt = new Date();
+        const daemonBuildStatus = createDaemonBuildStatus(fileURLToPath(import.meta.url), daemonStartedAt.getTime());
         const remoteRuntime = createDaemonRuntimeHost({
             daemonId: installationIdentity.installationId,
             daemonInstanceId,
@@ -150,12 +216,17 @@ export async function startRynxDaemonServer({ config, warn = defaultWarn, writeE
                 "semantic.session.launch-options.v2",
                 "semantic.session.create.v1",
                 "semantic.session.message.v1",
+                "semantic.session.resources.v1",
+                "semantic.session.message-queue.v1",
                 "semantic.session.delete.v1",
                 "semantic.session.interaction.v1",
                 "semantic.provider-cli.status.v1",
                 ...(runtimeBrowserSupported ? ["semantic.browser.v1"] : []),
                 ...(runtimeBrowserSupported && directHostingSupported
-                    ? [RUNTIME_BROWSER_SURFACE_SEMANTIC_CAPABILITY]
+                    ? [
+                        RUNTIME_BROWSER_SURFACE_SEMANTIC_CAPABILITY,
+                        RUNTIME_BROWSER_INSPECT_SEMANTIC_CAPABILITY,
+                    ]
                     : []),
                 ...(control.emulator
                     ? ["semantic.emulator.unary.v1", "semantic.session.emulator.v1"]
@@ -167,6 +238,19 @@ export async function startRynxDaemonServer({ config, warn = defaultWarn, writeE
             startedAt: daemonStartedAt,
         });
         const managementToken = randomBytes(32).toString("base64url");
+        const desktopBrowserHosts = new DesktopBrowserHostRegistry();
+        const appBrowserHostSupervisor = appBrowserHostLaunch
+            ? createBrowserHostSupervisor({
+                launch: appBrowserHostLaunch,
+                bootstrap: {
+                    type: APP_BROWSER_HOST_BOOTSTRAP_TYPE,
+                    schemaVersion: 1,
+                    origin: daemonControlOrigin(appConfig),
+                    managementToken,
+                },
+                isDesktopHostConnected: () => desktopBrowserHosts.directConnected,
+            })
+            : undefined;
         try {
             for (const removed of pruneInactivePluginInstallations()) {
                 console.log(JSON.stringify({ level: "info", type: "plugin-gc", removed }));
@@ -186,6 +270,11 @@ export async function startRynxDaemonServer({ config, warn = defaultWarn, writeE
                 output(JSON.stringify(entry));
             },
         });
+        const pluginManagement = new PluginManagementService();
+        const browserArtifactManagement = createBrowserArtifactManagementService();
+        const maintenanceManagement = createMaintenanceManagementService({
+            codexStorePath: appConfig.AGENT_SESSION_STORE_PATH,
+        });
         await loadPlugins(pluginSupervisor, warn);
         logLegacyCleanup(appConfig);
         const reloadPluginRuntime = async (pluginId) => {
@@ -253,21 +342,12 @@ export async function startRynxDaemonServer({ config, warn = defaultWarn, writeE
             statusSnapshot: pluginSupervisor.statusSnapshot.bind(pluginSupervisor),
             dispose: pluginSupervisor.dispose.bind(pluginSupervisor),
         };
-        const daemonManagement = {
-            managementToken,
-            identity: () => ({
-                installationId: installationIdentity.installationId,
-                algorithm: installationIdentity.algorithm,
-                publicKey: installationIdentity.publicKey,
-            }),
-            invokePluginCli,
-        };
         const remoteRuntimeAccess = new RemoteRuntimeAccessStore();
         const directConnections = new DirectRuntimeConnectionHub();
         const sessionLog = new SqliteSessionLogStore();
+        const sessionResources = new SqliteSessionResourceStore();
         const providerClis = new ProviderCliService();
         const sessionBrowserCapabilities = new SessionBrowserCapabilityStore();
-        const desktopBrowserHosts = new DesktopBrowserHostRegistry();
         const durableDesktopBrowserHost = new DurableEmbeddedBrowserProfileHost(desktopBrowserHosts, { warn });
         const browserRunnerSessionContexts = new BrowserRunnerSessionContextProvider({
             rootDir: join(rynxHome(), "run", "browser-session-contexts"),
@@ -280,7 +360,9 @@ export async function startRynxDaemonServer({ config, warn = defaultWarn, writeE
             onMirrorError: (error, sessionId) => warn(`Session mirror failed for ${sessionId}: ${error instanceof Error ? error.message : String(error)}`),
         });
         const sessionBrowsers = new SessionBrowserService({
-            host: createDesktopFirstSessionBrowserHost(durableDesktopBrowserHost, createHeadlessBrowserHost()),
+            host: appBrowserHostSupervisor
+                ? createSupervisedAppSessionBrowserHost(durableDesktopBrowserHost, appBrowserHostSupervisor)
+                : createDesktopFirstSessionBrowserHost(durableDesktopBrowserHost, createHeadlessBrowserHost()),
             sessions: {
                 exists: async (sessionId) => Boolean(sessionRegistry.get(sessionId) ??
                     await sessionRuntimeServices.sessionStore.get(sessionId)),
@@ -356,6 +438,8 @@ export async function startRynxDaemonServer({ config, warn = defaultWarn, writeE
             agents: {
                 list: () => control.listAgents(),
             },
+            pendingMessages: sessionPendingMessageStore,
+            resources: sessionResources,
             execution: {
                 runtime: sessionRuntimeServices.conversationRuntime,
                 runner: sessionRuntimeServices.runnerManager,
@@ -377,6 +461,53 @@ export async function startRynxDaemonServer({ config, warn = defaultWarn, writeE
                 return { cwd };
             },
         });
+        let shutdownAccepted = false;
+        let requestServerShutdown;
+        const daemonManagement = {
+            managementToken,
+            identity: () => ({
+                installationId: installationIdentity.installationId,
+                algorithm: installationIdentity.algorithm,
+                publicKey: installationIdentity.publicKey,
+            }),
+            buildStatus: daemonBuildStatus,
+            pluginManagement: {
+                listPlugins: () => pluginManagement.list(),
+                setPluginEnabled: (pluginId, enabled) => pluginManagement.setEnabled(pluginId, enabled),
+                uninstallPlugin: (pluginId) => pluginManagement.uninstall(pluginId),
+                prepareInstallation: (input, context) => pluginManagement.prepareInstallation(input, context),
+                commitInstallation: (token, input, context) => pluginManagement.commitInstallation(token, input, context),
+                cancelPreparation: (token) => pluginManagement.cancelPreparation(token),
+                dispose: () => pluginManagement.dispose(),
+            },
+            browserArtifacts: browserArtifactManagement,
+            maintenance: maintenanceManagement,
+            shutdownIfIdle: () => {
+                if (shutdownAccepted)
+                    return { outcome: "accepted" };
+                const activity = {
+                    ...sessionRuntimeServices.sessionRuntimeIndex.activitySnapshot(),
+                    activeTerminals: sessionTerminals.activeTerminalCount(),
+                    activeBrowsers: sessionBrowsers.activeBrowserCount(),
+                };
+                if (daemonActivityBlocksShutdown(activity)) {
+                    return { outcome: "busy", activity };
+                }
+                shutdownAccepted = true;
+                const shutdown = requestServerShutdown;
+                if (!shutdown) {
+                    shutdownAccepted = false;
+                    throw new Error("idle daemon shutdown was requested before server lifecycle was ready");
+                }
+                // Start admission fences in this event-loop turn, before another
+                // request or Direct dispatch can be accepted.
+                void shutdown().catch((error) => {
+                    warn(`idle daemon shutdown failed: ${error instanceof Error ? error.message : String(error)}`);
+                });
+                return { outcome: "accepted" };
+            },
+            invokePluginCli,
+        };
         const remoteRuntimeDispatcher = new RemoteRuntimeDispatcher({
             runtime: remoteRuntime,
             emulator: control.emulator,
@@ -401,39 +532,57 @@ export async function startRynxDaemonServer({ config, warn = defaultWarn, writeE
             credentials: runtimeCredentials,
         });
         const runtimeTargetControl = new DaemonRuntimeTargetControl(remoteRuntime, runtimeTargets, runtimeCredentials, runtimeConnectionManager);
-        const server = await startServer({
-            config: appConfig,
-            loadInstances: () => resolveChannelInstances(warn),
-            control,
-            sessionLog,
-            sessionRegistry,
-            sessionRuntimeServices,
-            pluginRuntime,
-            daemonManagement,
-            remoteRuntime,
-            remoteRuntimeAdmin,
-            runtimeTargetControl,
-            runtimeConnectionResolver: runtimeConnectionManager,
-            providerClis,
-            sessionEmulators,
-            sessionLifecycle: sessionResourceLifecycle,
-            runtimeLocalBrowser: {
-                authorizeCredential: (credential) => sessionBrowserCapabilities.verify(credential.sessionId, credential.capability),
-                endpointForCredential: async (credential) => {
-                    if (!sessionBrowserCapabilities.verify(credential.sessionId, credential.capability))
-                        return undefined;
-                    return sessionBrowsers.getRuntimeLocalEndpoint(credential.sessionId);
-                },
-                endpointForSession: (sessionId) => sessionBrowsers.getRuntimeLocalEndpoint(sessionId),
-            },
-            desktopBrowserHost: {
-                registry: desktopBrowserHosts,
-                daemonInstanceId,
-            },
-        });
-        const baseShutdown = server.shutdown.bind(server);
+        const directBrowserInspectHost = createDirectRuntimeBrowserInspectHost(sessionBrowsers);
+        let chromeInspectionManager;
+        let server;
+        let baseShutdown;
         let directServer;
         try {
+            const initializedChromeInspectionManager = await createChromeInspectionManager({
+                localDaemonInstanceId: daemonInstanceId,
+                browsers: sessionBrowsers,
+                runtimeTargets,
+                runtimeConnections: runtimeConnectionManager,
+                onError: (error, context) => warn(`Chrome inspection ${context} failed: ${error.message}`),
+            });
+            chromeInspectionManager = initializedChromeInspectionManager;
+            daemonManagement.chromeInspection = {
+                status: async () => asDaemonChromeInspectionStatus(await initializedChromeInspectionManager.status()),
+                configure: async (input) => asDaemonChromeInspectionStatus(await initializedChromeInspectionManager.configure(input)),
+            };
+            server = await startServer({
+                config: appConfig,
+                loadInstances: () => resolveChannelInstances(warn),
+                control,
+                sessionLog,
+                sessionRegistry,
+                sessionRuntimeServices,
+                pluginRuntime,
+                daemonManagement,
+                remoteRuntime,
+                remoteRuntimeAdmin,
+                runtimeTargetControl,
+                runtimeConnectionResolver: runtimeConnectionManager,
+                localSessionResources: machineSessions,
+                providerClis,
+                sessionEmulators,
+                sessionLifecycle: sessionResourceLifecycle,
+                sessionTerminals,
+                runtimeLocalBrowser: {
+                    authorizeCredential: (credential) => sessionBrowserCapabilities.verify(credential.sessionId, credential.capability),
+                    endpointForCredential: async (credential) => {
+                        if (!sessionBrowserCapabilities.verify(credential.sessionId, credential.capability))
+                            return undefined;
+                        return sessionBrowsers.getRuntimeLocalEndpoint(credential.sessionId);
+                    },
+                    endpointForSession: (sessionId) => sessionBrowsers.getRuntimeLocalEndpoint(sessionId),
+                },
+                desktopBrowserHost: {
+                    registry: desktopBrowserHosts,
+                    daemonInstanceId,
+                },
+            });
+            baseShutdown = server.shutdown.bind(server);
             if (directConfig && directEncryptionIdentity) {
                 const startedDirect = await startDirectListener(startDirectServer, directConfig, {
                     e2ee: {
@@ -445,6 +594,9 @@ export async function startRynxDaemonServer({ config, warn = defaultWarn, writeE
                     isPeerActive: (peer) => remoteRuntimeAccess.isClientGrantActive(peer.grantId, peer.clientId),
                     connectionHub: directConnections,
                     browserSurface: { host: sessionBrowserSurfaces },
+                    ...(runtimeBrowserSupported
+                        ? { browserInspect: { host: directBrowserInspectHost } }
+                        : {}),
                     ...(sessionEmulatorSurface
                         ? { emulatorSurface: { host: sessionEmulatorSurface } }
                         : {}),
@@ -464,6 +616,15 @@ export async function startRynxDaemonServer({ config, warn = defaultWarn, writeE
         }
         catch (startupError) {
             const rollbackErrors = [startupError];
+            server?.stopAccepting();
+            if (chromeInspectionManager) {
+                try {
+                    await chromeInspectionManager.shutdown();
+                }
+                catch (shutdownError) {
+                    rollbackErrors.push(shutdownError);
+                }
+            }
             if (directServer) {
                 try {
                     await directServer.shutdown();
@@ -473,7 +634,7 @@ export async function startRynxDaemonServer({ config, warn = defaultWarn, writeE
                 }
             }
             try {
-                await baseShutdown();
+                await runtimeConnectionManager.close();
             }
             catch (shutdownError) {
                 rollbackErrors.push(shutdownError);
@@ -487,25 +648,47 @@ export async function startRynxDaemonServer({ config, warn = defaultWarn, writeE
             finally {
                 durableDesktopBrowserHost.dispose();
             }
-            try {
-                await runtimeConnectionManager.close();
+            if (appBrowserHostSupervisor) {
+                try {
+                    await appBrowserHostSupervisor.stop();
+                }
+                catch (shutdownError) {
+                    rollbackErrors.push(shutdownError);
+                }
             }
-            catch (shutdownError) {
-                rollbackErrors.push(shutdownError);
+            if (baseShutdown) {
+                try {
+                    await baseShutdown();
+                }
+                catch (shutdownError) {
+                    rollbackErrors.push(shutdownError);
+                }
             }
             if (rollbackErrors.length > 1) {
-                throw new AggregateError(rollbackErrors, "failed to start Direct Runtime and roll back the local server");
+                throw new AggregateError(rollbackErrors, "failed to start daemon resources and roll back the local server");
             }
             throw startupError;
         }
+        if (!server || !baseShutdown || !chromeInspectionManager) {
+            throw new Error("daemon startup completed without all required resources");
+        }
         let shutdownPromise;
         server.shutdown = () => {
             if (shutdownPromise)
                 return shutdownPromise;
+            // Fence Local admission without closing the Desktop Browser Host WS.
+            // Browser handles can therefore close gracefully before full teardown.
+            server.stopAccepting();
             shutdownPromise = (async () => {
                 let shutdownComplete = false;
                 try {
                     const shutdownErrors = [];
+                    try {
+                        await chromeInspectionManager.shutdown();
+                    }
+                    catch (error) {
+                        shutdownErrors.push(error);
+                    }
                     if (directServer) {
                         try {
                             await directServer.shutdown();
@@ -514,12 +697,6 @@ export async function startRynxDaemonServer({ config, warn = defaultWarn, writeE
                             shutdownErrors.push(error);
                         }
                     }
-                    try {
-                        await baseShutdown();
-                    }
-                    catch (error) {
-                        shutdownErrors.push(error);
-                    }
                     try {
                         await runtimeConnectionManager.close();
                     }
@@ -535,6 +712,20 @@ export async function startRynxDaemonServer({ config, warn = defaultWarn, writeE
                     finally {
                         durableDesktopBrowserHost.dispose();
                     }
+                    if (appBrowserHostSupervisor) {
+                        try {
+                            await appBrowserHostSupervisor.stop();
+                        }
+                        catch (error) {
+                            shutdownErrors.push(error);
+                        }
+                    }
+                    try {
+                        await baseShutdown();
+                    }
+                    catch (error) {
+                        shutdownErrors.push(error);
+                    }
                     try {
                         browserRunnerSessionContexts.closeAll();
                         sessionBrowserCapabilities.revokeAll();
@@ -558,6 +749,7 @@ export async function startRynxDaemonServer({ config, warn = defaultWarn, writeE
             })();
             return shutdownPromise;
         };
+        requestServerShutdown = server.shutdown.bind(server);
         ownerManagedByServer = true;
         try {
             await writeEndpoint(appConfig, managementToken);
@@ -579,6 +771,370 @@ export async function startRynxDaemonServer({ config, warn = defaultWarn, writeE
         throw error;
     }
 }
+export function createSupervisedAppSessionBrowserHost(desktop, supervisor) {
+    const withOnDemandSidecar = async (operation) => {
+        try {
+            return await operation();
+        }
+        catch (error) {
+            if (!(error instanceof DesktopBrowserHostAbsentError))
+                throw error;
+        }
+        try {
+            await supervisor.ensureConnected();
+        }
+        catch (startupError) {
+            try {
+                return await operation();
+            }
+            catch (retryError) {
+                if (retryError instanceof DesktopBrowserHostAbsentError)
+                    throw startupError;
+                throw retryError;
+            }
+        }
+        try {
+            return await operation();
+        }
+        catch (error) {
+            if (!(error instanceof DesktopBrowserHostAbsentError))
+                throw error;
+            await supervisor.restart();
+            return operation();
+        }
+    };
+    return {
+        createBrowser: (input) => withOnDemandSidecar(() => desktop.createBrowser(input)),
+        ...(desktop.deleteSessionData
+            ? {
+                deleteSessionData: (sessionId) => withOnDemandSidecar(() => desktop.deleteSessionData(sessionId)),
+            }
+            : {}),
+    };
+}
+function asDaemonChromeInspectionStatus(status) {
+    if (status.runtime.address !== "127.0.0.1:9333") {
+        throw new Error("resident Chrome inspection must use the fixed 127.0.0.1:9333 endpoint");
+    }
+    return {
+        ...status,
+        runtime: {
+            ...status.runtime,
+            address: "127.0.0.1:9333",
+        },
+    };
+}
+/**
+ * Resolve the authenticated semantic target inside its owning Runtime and
+ * attach directly to that Page's loopback CDP WebSocket. No endpoint is ever
+ * projected into the Direct protocol.
+ */
+export function createDirectRuntimeBrowserInspectHost(browsers, options = {}) {
+    const openTimeoutMs = options.openTimeoutMs ??
+        BROWSER_INSPECT_OPEN_TIMEOUT_MS;
+    if (!Number.isSafeInteger(openTimeoutMs) || openTimeoutMs <= 0) {
+        throw new TypeError("Browser Inspect open timeout must be a positive integer");
+    }
+    return {
+        open: async (target, context) => {
+            const deadline = AbortSignal.timeout(openTimeoutMs);
+            const openingSignal = AbortSignal.any([context.signal, deadline]);
+            let socket;
+            try {
+                const endpoint = await waitForBrowserInspectValue(browsers.getInspectionPageEndpoint(target), openingSignal);
+                const url = parseRuntimeLocalPageEndpoint(endpoint.endpoint);
+                socket = new WebSocket(url, {
+                    followRedirects: false,
+                    handshakeTimeout: openTimeoutMs,
+                    maxPayload: RUNTIME_BROWSER_INSPECT_MAX_MESSAGE_BYTES,
+                    perMessageDeflate: false,
+                });
+                await waitForBrowserInspectSocketOpen(socket, openingSignal);
+                return browserInspectAttachment(socket, context.signal);
+            }
+            catch (error) {
+                if (socket?.readyState !== WebSocket.CLOSED)
+                    socket?.terminate();
+                throw mapBrowserInspectOpenError(error, context.signal.aborted, deadline.aborted);
+            }
+        },
+    };
+}
+function browserInspectAttachment(socket, signal) {
+    const queue = new BrowserInspectMessageQueue(BROWSER_INSPECT_MAX_QUEUED_BYTES, () => socket.pause(), () => {
+        if (socket.readyState === WebSocket.OPEN)
+            socket.resume();
+    });
+    let closed = false;
+    const onMessage = (data, binary) => {
+        const message = binary
+            ? { binary: true, data: copyBrowserInspectBytes(data) }
+            : { binary: false, data: browserInspectText(data) };
+        if (!queue.push(message)) {
+            const error = new Error("Browser Inspect local Page output queue is full");
+            queue.fail(error);
+            void closeBrowserInspectSocket(socket, 1_009, "Browser Inspect output capacity exceeded");
+        }
+    };
+    const onError = (error) => queue.fail(error);
+    const onClose = () => queue.end();
+    const onAbort = () => {
+        queue.fail(signal.reason instanceof Error
+            ? signal.reason
+            : new Error("Browser Inspect attachment was cancelled"));
+        void closeBrowserInspectSocket(socket, 1_001, "Browser Inspect cancelled");
+    };
+    socket.on("message", onMessage);
+    socket.once("error", onError);
+    socket.once("close", onClose);
+    signal.addEventListener("abort", onAbort, { once: true });
+    if (signal.aborted)
+        onAbort();
+    const close = async (reason) => {
+        if (closed)
+            return;
+        closed = true;
+        signal.removeEventListener("abort", onAbort);
+        socket.removeListener("message", onMessage);
+        socket.removeListener("error", onError);
+        socket.removeListener("close", onClose);
+        queue.end();
+        await closeBrowserInspectSocket(socket, reason === "client_closed" ? 1_000 : 1_001, `Browser Inspect ${reason.replaceAll("_", " ")}`);
+    };
+    return {
+        messages: queue,
+        send: async (message) => {
+            if (closed || socket.readyState !== WebSocket.OPEN) {
+                throw new Error("Browser Inspect local Page is closed");
+            }
+            const byteLength = message.binary
+                ? message.data.byteLength
+                : Buffer.byteLength(message.data, "utf8");
+            if (byteLength > RUNTIME_BROWSER_INSPECT_MAX_MESSAGE_BYTES ||
+                socket.bufferedAmount + byteLength >
+                    BROWSER_INSPECT_MAX_QUEUED_BYTES) {
+                throw new Error("Browser Inspect local Page input capacity exceeded");
+            }
+            await new Promise((resolve, reject) => {
+                socket.send(message.data, { binary: message.binary, compress: false }, (error) => error ? reject(error) : resolve());
+            });
+        },
+        close,
+    };
+}
+class BrowserInspectMessageQueue {
+    maxBytes;
+    onBuffered;
+    onDrained;
+    values = [];
+    waiters = [];
+    queuedBytes = 0;
+    ended = false;
+    failure;
+    constructor(maxBytes, onBuffered, onDrained) {
+        this.maxBytes = maxBytes;
+        this.onBuffered = onBuffered;
+        this.onDrained = onDrained;
+    }
+    push(message) {
+        if (this.ended || this.failure !== undefined)
+            return false;
+        const byteLength = message.binary
+            ? message.data.byteLength
+            : Buffer.byteLength(message.data, "utf8");
+        if (byteLength > RUNTIME_BROWSER_INSPECT_MAX_MESSAGE_BYTES)
+            return false;
+        const waiter = this.waiters.shift();
+        if (waiter) {
+            waiter.resolve({ value: message, done: false });
+            return true;
+        }
+        if (this.queuedBytes + byteLength > this.maxBytes)
+            return false;
+        this.values.push({ message, byteLength });
+        this.queuedBytes += byteLength;
+        if (this.values.length === 1)
+            this.onBuffered();
+        return true;
+    }
+    end() {
+        if (this.ended || this.failure !== undefined)
+            return;
+        this.ended = true;
+        for (const waiter of this.waiters.splice(0)) {
+            waiter.resolve({ value: undefined, done: true });
+        }
+    }
+    fail(error) {
+        if (this.ended || this.failure !== undefined)
+            return;
+        this.failure = error;
+        this.values.length = 0;
+        this.queuedBytes = 0;
+        this.onDrained();
+        for (const waiter of this.waiters.splice(0))
+            waiter.reject(error);
+    }
+    [Symbol.asyncIterator]() {
+        return {
+            next: () => {
+                if (this.failure !== undefined)
+                    return Promise.reject(this.failure);
+                const entry = this.values.shift();
+                if (entry) {
+                    this.queuedBytes -= entry.byteLength;
+                    if (this.values.length === 0)
+                        this.onDrained();
+                    return Promise.resolve({ value: entry.message, done: false });
+                }
+                if (this.ended) {
+                    return Promise.resolve({ value: undefined, done: true });
+                }
+                return new Promise((resolve, reject) => this.waiters.push({ resolve, reject }));
+            },
+        };
+    }
+}
+function parseRuntimeLocalPageEndpoint(endpoint) {
+    let url;
+    try {
+        url = new URL(endpoint);
+    }
+    catch {
+        throw new Error("Browser Inspect local Page endpoint is invalid");
+    }
+    if (url.protocol !== "ws:" ||
+        url.hostname !== "127.0.0.1" ||
+        !url.port ||
+        url.username ||
+        url.password ||
+        url.search ||
+        url.hash ||
+        !/^\/devtools\/page\/[A-Za-z0-9._~%-]+$/.test(url.pathname)) {
+        throw new Error("Browser Inspect local Page endpoint must be an exact loopback Page WebSocket");
+    }
+    return url.href;
+}
+function waitForBrowserInspectValue(promise, signal) {
+    if (signal.aborted) {
+        return Promise.reject(signal.reason ?? new Error("Browser Inspect opening was cancelled"));
+    }
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        const finish = (callback) => {
+            if (settled)
+                return;
+            settled = true;
+            signal.removeEventListener("abort", onAbort);
+            callback();
+        };
+        const onAbort = () => finish(() => reject(signal.reason ?? new Error("Browser Inspect opening was cancelled")));
+        signal.addEventListener("abort", onAbort, { once: true });
+        promise.then((value) => finish(() => resolve(value)), (error) => finish(() => reject(error)));
+    });
+}
+function waitForBrowserInspectSocketOpen(socket, signal) {
+    if (socket.readyState === WebSocket.OPEN)
+        return Promise.resolve();
+    return new Promise((resolve, reject) => {
+        const cleanup = () => {
+            signal.removeEventListener("abort", onAbort);
+            socket.removeListener("open", onOpen);
+            socket.removeListener("error", onError);
+            socket.removeListener("unexpected-response", onUnexpectedResponse);
+        };
+        const onOpen = () => {
+            cleanup();
+            resolve();
+        };
+        const onError = (error) => {
+            cleanup();
+            reject(error);
+        };
+        const onUnexpectedResponse = (_request, response) => {
+            response.resume();
+            cleanup();
+            reject(new Error("Browser Inspect local Page rejected the connection"));
+        };
+        const onAbort = () => {
+            cleanup();
+            socket.terminate();
+            reject(signal.reason ?? new Error("Browser Inspect opening was cancelled"));
+        };
+        if (signal.aborted)
+            return onAbort();
+        signal.addEventListener("abort", onAbort, { once: true });
+        socket.once("open", onOpen);
+        socket.once("error", onError);
+        socket.once("unexpected-response", onUnexpectedResponse);
+    });
+}
+function closeBrowserInspectSocket(socket, code, reason) {
+    if (socket.readyState === WebSocket.CLOSED)
+        return Promise.resolve();
+    return new Promise((resolve) => {
+        let settled = false;
+        const finish = () => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            socket.removeListener("close", finish);
+            resolve();
+        };
+        const timer = setTimeout(() => {
+            if (socket.readyState !== WebSocket.CLOSED)
+                socket.terminate();
+            finish();
+        }, BROWSER_INSPECT_CLOSE_TIMEOUT_MS);
+        timer.unref?.();
+        socket.once("close", finish);
+        if (socket.readyState === WebSocket.OPEN) {
+            socket.close(code, reason.slice(0, 123));
+        }
+        else {
+            socket.terminate();
+        }
+    });
+}
+function copyBrowserInspectBytes(data) {
+    if (data instanceof ArrayBuffer)
+        return new Uint8Array(data.slice(0));
+    if (Array.isArray(data))
+        return new Uint8Array(Buffer.concat(data));
+    return new Uint8Array(Buffer.from(data));
+}
+function browserInspectText(data) {
+    return Buffer.from(copyBrowserInspectBytes(data)).toString("utf8");
+}
+function mapBrowserInspectOpenError(error, callerAborted, deadlineAborted) {
+    if (error instanceof DirectRuntimeBrowserInspectHostError)
+        return error;
+    if (callerAborted) {
+        return new DirectRuntimeBrowserInspectHostError("cancelled", "Browser Inspect attachment was cancelled", { cause: error });
+    }
+    if (deadlineAborted) {
+        return new DirectRuntimeBrowserInspectHostError("internal_error", "Browser Inspect local Page opening timed out", { cause: error });
+    }
+    if (error instanceof SessionBrowserServiceError) {
+        const reason = error.code === "generation_mismatch"
+            ? "generation_changed"
+            : error.code === "not_found" || error.code === "invalid_request"
+                ? "not_found"
+                : error.code === "capacity"
+                    ? "capacity"
+                    : error.code === "unavailable" &&
+                        error.message.includes("does not support")
+                        ? "unsupported"
+                        : error.code === "unavailable" || error.code === "shutting_down"
+                            ? "browser_closed"
+                            : "internal_error";
+        return new DirectRuntimeBrowserInspectHostError(reason, error.message, {
+            cause: error,
+        });
+    }
+    return new DirectRuntimeBrowserInspectHostError("internal_error", "Browser Inspect local Page is unavailable", { cause: error });
+}
 async function startDirectListener(start, config, options) {
     const candidates = [...new Set([config.port, ...(config.fallbackPorts ?? [])])];
     for (let index = 0; index < candidates.length; index += 1) {