libretto 0.6.11 → 0.6.13

package/src/cli/core/browser.ts

@@ -5,13 +5,17 @@ import {
   type CDPSession,
   type Page,
 } from "playwright";
-import { existsSync, writeFileSync, unlinkSync } from "node:fs";
+import { existsSync, readFileSync, writeFileSync, unlinkSync } from "node:fs";
+import { mkdir, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import { createServer } from "node:net";
 import type { LoggerApi } from "../../shared/logger/index.js";
 import type { SessionAccessMode } from "../../shared/state/index.js";
-import { PROFILES_DIR } from "./context.js";
+import type { Experiments } from "./experiments.js";
+import { getSessionProviderClosePath, PROFILES_DIR } from "./context.js";
 import { readLibrettoConfig } from "./config.js";
+import { librettoCommand } from "../../shared/package-manager.js";
+import { getCloudProviderApi } from "./providers/index.js";
 import {
   assertSessionAvailableForStart,
   clearSessionState,
@@ -22,13 +26,14 @@ import {
   readSessionState,
   writeSessionState,
 } from "./session.js";
-import type { ProviderApi } from "./providers/types.js";
-import { getCloudProviderApi } from "./providers/index.js";
-import { DaemonClient, spawnSessionDaemon } from "./daemon/index.js";
+import { DaemonClient } from "./daemon/ipc.js";
 
 const CLOSE_WAIT_MS = 1_500;
+const PROVIDER_CLOSE_WAIT_MS = 30_000;
 const FORCE_CLOSE_WAIT_MS = 300;
 
+type CloseResult = { replayUrl?: string };
+
 async function pickFreePort(): Promise<number> {
   return await new Promise((resolve, reject) => {
     const server = createServer();
@@ -230,14 +235,14 @@ export async function connect(
     if (state.provider) {
       throw new Error(
         `Could not connect to ${state.provider.name} session for "${session}" at ${endpoint}. ` +
-          `The remote session may still be active. Try again, or close with: libretto close --session ${session}`,
+          `The remote session may still be active. Try again, or close with: ${librettoCommand(`close --session ${session}`)}`,
       );
     }
 
     if (state.pid == null || !isPidRunning(state.pid)) {
       clearSessionState(session, logger);
       throw new Error(
-        `No browser running for session "${session}". Run 'libretto open <url> --session ${session}' first.`,
+        `No browser running for session "${session}". Run '${librettoCommand(`open <url> --session ${session}`)}' first.`,
       );
     }
 
@@ -273,7 +278,7 @@ export async function connect(
 
   if (options?.requireSinglePage && !options.pageId && pages.length > 1) {
     throw new Error(
-      `Multiple pages are open in session "${session}". Pass --page <id> to target a page (run "libretto pages --session ${session}" to list ids).`,
+      `Multiple pages are open in session "${session}". Pass --page <id> to target a page (run "${librettoCommand(`pages --session ${session}`)}" to list ids).`,
     );
   }
 
@@ -283,7 +288,7 @@ export async function connect(
     : pageRefs[pageRefs.length - 1]!;
   if (!pageRef) {
     throw new Error(
-      `Page "${options?.pageId}" was not found in session "${session}". Run "libretto pages --session ${session}" to list ids.`,
+      `Page "${options?.pageId}" was not found in session "${session}". Run "${librettoCommand(`pages --session ${session}`)}" to list ids.`,
     );
   }
   const page = pageRef.page;
@@ -325,11 +330,15 @@ export async function runPages(
   if (!state.daemonSocketPath) {
     throw new Error(
       `Session "${session}" has no daemon socket. The browser daemon may have crashed. ` +
-        `Close and reopen the session: libretto close --session ${session}`,
+        `Close and reopen the session: ${librettoCommand(`close --session ${session}`)}`,
     );
   }
-  const client = new DaemonClient(state.daemonSocketPath);
-  pageSummaries = await client.pages();
+  const client = await DaemonClient.connect(state.daemonSocketPath);
+  try {
+    pageSummaries = await client.pages();
+  } finally {
+    client.destroy();
+  }
 
   if (pageSummaries.length === 0) {
     console.log("No pages found.");
@@ -387,10 +396,11 @@ export async function runOpen(
   headed: boolean,
   session: string,
   logger: LoggerApi,
-  options?: {
+  options: {
     viewport?: { width: number; height: number };
     accessMode?: SessionAccessMode;
     authProfileDomain?: string;
+    experiments: Experiments;
   },
 ): Promise<void> {
   const parsedUrl = normalizeUrl(rawUrl);
@@ -423,8 +433,8 @@ export async function runOpen(
     if (!existsSync(authProfilePath)) {
       throw new Error(
         `No saved auth profile for "${authDomain}". ` +
-          `Save one first: libretto open https://${authDomain} --headed --session <name>, ` +
-          `log in, then run: libretto save ${authDomain} --session <name>`,
+          `Save one first: ${librettoCommand(`open https://${authDomain} --headed --session <name>`)}, ` +
+          `log in, then run: ${librettoCommand(`save ${authDomain} --session <name>`)}`,
       );
     }
   }
@@ -453,25 +463,30 @@ export async function runOpen(
   // Spawn daemon and wait for IPC readiness. The daemon launches
   // Chromium internally — IPC readiness implies the browser is up,
   // so no separate CDP polling is needed.
-  const { pid, socketPath: daemonSocketPath } = await spawnSessionDaemon({
-    config: {
-      port,
-      url,
-      session,
-      headed,
-      viewport,
-      storageStatePath: useProfile ? profilePath : undefined,
-      windowPosition,
-    },
-    session,
-    logger,
-    logPath: runLogPath,
-    // The daemon launches Chromium, installs telemetry, navigates to
-    // the URL, and only then starts IPC. Navigation alone can take up
-    // to 45s (page.setDefaultNavigationTimeout), so the IPC timeout
-    // must cover launch + navigation.
-    ipcTimeoutMs: 60_000,
-  });
+  const { pid, socketPath: daemonSocketPath, client } =
+    await DaemonClient.spawn({
+      config: {
+        session,
+        experiments: options.experiments,
+        browser: {
+          kind: "launch",
+          headed,
+          viewport,
+          storageStatePath: useProfile ? profilePath : undefined,
+          windowPosition,
+          remoteDebuggingPort: port,
+          initialUrl: url,
+        },
+      },
+      logger,
+      logPath: runLogPath,
+      // The daemon launches Chromium, installs telemetry, navigates to
+      // the URL, and only then starts IPC. Navigation alone can take up
+      // to 45s (page.setDefaultNavigationTimeout), so the IPC timeout
+      // must cover launch + navigation.
+      startupTimeoutMs: 60_000,
+    });
+  client.destroy();
 
   writeSessionState(
     {
@@ -500,10 +515,10 @@ export async function runOpen(
 export async function runOpenWithProvider(
   rawUrl: string,
   providerName: string,
-  provider: ProviderApi,
   session: string,
   logger: LoggerApi,
-  accessMode: SessionAccessMode = "write-access",
+  accessMode: SessionAccessMode,
+  experiments: Experiments,
 ): Promise<void> {
   const parsedUrl = normalizeUrl(rawUrl);
   const url = parsedUrl.href;
@@ -513,36 +528,48 @@ export async function runOpenWithProvider(
     `Creating ${providerName} browser session (session: ${session})...`,
   );
 
-  const providerSession = await provider.createSession();
-  logger.info("open-provider-session-created", {
-    provider: providerName,
-    sessionId: providerSession.sessionId,
-    cdpEndpoint: providerSession.cdpEndpoint,
-    liveViewUrl: providerSession.liveViewUrl,
-  });
-
-  if (providerSession.liveViewUrl) {
-    console.log(`View live session: ${providerSession.liveViewUrl}`);
-  }
-
   console.log(`Connecting to ${providerName} browser...`);
 
   const runLogPath = logFileForSession(session);
-  const { pid, socketPath: daemonSocketPath } = await spawnSessionDaemon({
+  const {
+    pid,
+    socketPath: daemonSocketPath,
+    provider: providerSession,
+    client,
+  } = await DaemonClient.spawn({
     config: {
-      mode: "connect" as const,
       session,
-      cdpEndpoint: providerSession.cdpEndpoint,
-      url,
+      experiments,
+      browser: {
+        kind: "provider",
+        providerName,
+        initialUrl: url,
+      },
     },
-    session,
     logger,
     logPath: runLogPath,
     // Remote CDP connection + navigation; must cover both.
-    ipcTimeoutMs: 60_000,
-    onFailure: () => provider.closeSession(providerSession.sessionId),
+    startupTimeoutMs: 60_000,
+  });
+  client.destroy();
+
+  if (!providerSession) {
+    throw new Error(
+      `Provider daemon did not return session metadata for ${providerName}.`,
+    );
+  }
+
+  logger.info("open-provider-session-created", {
+    provider: providerName,
+    sessionId: providerSession.sessionId,
+    cdpEndpoint: providerSession.cdpEndpoint,
+    liveViewUrl: providerSession.liveViewUrl,
   });
 
+  if (providerSession.liveViewUrl) {
+    console.log(`View live session: ${providerSession.liveViewUrl}`);
+  }
+
   writeSessionState(
     {
       port: 0,
@@ -631,9 +658,8 @@ export async function runSave(
     }
 
     const state = { cookies, origins };
-    const fs = await import("node:fs/promises");
-    await fs.mkdir(dirname(profilePath), { recursive: true });
-    await fs.writeFile(profilePath, JSON.stringify(state, null, 2));
+    await mkdir(dirname(profilePath), { recursive: true });
+    await writeFile(profilePath, JSON.stringify(state, null, 2));
 
     logger.info("save-success", {
       domain,
@@ -664,39 +690,62 @@ export async function runClose(
     return;
   }
 
-  // Kill local daemon process if present (applies to both local and
-  // provider sessions — the daemon disconnects without closing the
-  // external browser).
-  if (state.pid != null) {
+  let replayUrl: string | undefined;
+  if (state.daemonSocketPath && state.pid != null && isPidRunning(state.pid)) {
+    try {
+      const result = await closeDaemonSession(
+        {
+          session,
+          pid: state.pid,
+          port: state.port,
+          provider: state.provider,
+          daemonSocketPath: state.daemonSocketPath,
+        },
+        logger,
+      );
+      replayUrl = result.replayUrl;
+      if (!state.provider) {
+        await waitForCloseSignalWindow(CLOSE_WAIT_MS);
+      }
+    } catch (error) {
+      if (state.provider) {
+        writeSessionState({ ...state, status: "cleanup-failed" }, logger);
+      }
+      throw formatDaemonCloseFailure(session, state.provider?.name, error);
+    }
+  } else if (state.pid != null) {
     logger.info("close-killing", { session, pid: state.pid, port: state.port });
     sendSignalToProcessGroupOrPid(state.pid, "SIGTERM", logger, session);
-    await waitForCloseSignalWindow(CLOSE_WAIT_MS);
+    if (state.provider) {
+      await waitForProviderCloseResult(session, state.pid);
+    } else {
+      await waitForCloseSignalWindow(CLOSE_WAIT_MS);
+    }
   }
 
-  // Close provider session if applicable (tears down the remote browser).
-  let replayUrl: string | undefined;
   if (state.provider) {
-    logger.info("close-provider", {
+    logger.info("close-provider-daemon-owned", {
       session,
       provider: state.provider.name,
       sessionId: state.provider.sessionId,
     });
-    try {
-      const provider = getCloudProviderApi(state.provider.name);
-      const result = await provider.closeSession(state.provider.sessionId);
-      replayUrl = result.replayUrl;
-    } catch (err) {
-      logger.warn("close-provider-error", {
-        session,
-        provider: state.provider.name,
-        sessionId: state.provider.sessionId,
-        error: err,
-      });
-      writeSessionState({ ...state, status: "cleanup-failed" }, logger);
-      throw new Error(
-        `Failed to close remote ${state.provider.name} session "${state.provider.sessionId}" for session "${session}". ` +
-          `State preserved with status "cleanup-failed". Retry with: libretto close --session ${session}`,
-      );
+    if (!hasProviderCloseResult(session)) {
+      if (state.pid == null || !isPidRunning(state.pid)) {
+        try {
+          replayUrl = await closeProviderSessionDirectly(session, state.provider, logger);
+        } catch (error) {
+          writeSessionState({ ...state, status: "cleanup-failed" }, logger);
+          throw error;
+        }
+      } else {
+        writeSessionState({ ...state, status: "cleanup-failed" }, logger);
+        throw new Error(
+          `Failed to confirm remote ${state.provider.name} session cleanup for session "${session}". ` +
+            `State preserved with status "cleanup-failed". Retry with: ${librettoCommand(`close --session ${session}`)}`,
+        );
+      }
+    } else {
+      replayUrl = replayUrl ?? readProviderReplayUrl(session, logger);
     }
   }
 
@@ -717,10 +766,154 @@ type ClosableSession = {
   daemonSocketPath?: string;
 };
 
+async function closeDaemonSession(
+  target: ClosableSession,
+  logger: LoggerApi,
+): Promise<CloseResult> {
+  if (!target.daemonSocketPath) {
+    throw new Error("session has no daemon socket path");
+  }
+
+  const timeoutMs = target.provider ? PROVIDER_CLOSE_WAIT_MS : CLOSE_WAIT_MS;
+  logger.info("close-daemon-ipc-start", {
+    session: target.session,
+    pid: target.pid,
+    provider: target.provider?.name,
+    timeoutMs,
+  });
+
+  let client: DaemonClient | undefined;
+  try {
+    client = await DaemonClient.connect(target.daemonSocketPath);
+    const result = await withTimeout(
+      client.close(),
+      timeoutMs,
+      `Daemon did not respond to close within ${timeoutMs}ms.`,
+    );
+    logger.info("close-daemon-ipc-success", {
+      session: target.session,
+      replayUrl: result.replayUrl,
+    });
+    return result;
+  } finally {
+    client?.destroy();
+  }
+}
+
+async function withTimeout<T>(
+  promise: Promise<T>,
+  timeoutMs: number,
+  timeoutMessage: string,
+): Promise<T> {
+  let timeout: ReturnType<typeof setTimeout> | undefined;
+  const timeoutPromise = new Promise<never>((_resolve, reject) => {
+    timeout = setTimeout(() => reject(new Error(timeoutMessage)), timeoutMs);
+  });
+  try {
+    return await Promise.race([promise, timeoutPromise]);
+  } finally {
+    if (timeout) clearTimeout(timeout);
+  }
+}
+
+function formatDaemonCloseFailure(
+  session: string,
+  providerName: string | undefined,
+  error: unknown,
+): Error {
+  const message = error instanceof Error ? error.message : String(error);
+  const cleanupWarning = providerName
+    ? ` State preserved with status "cleanup-failed" because remote ${providerName} cleanup could not be confirmed.`
+    : " State preserved so you can retry or inspect the session.";
+  return new Error(
+    `Failed to close session "${session}" gracefully over daemon IPC: ${message}.${cleanupWarning} Retry with: ${librettoCommand(`close --session ${session}`)}`,
+  );
+}
+
 function waitForCloseSignalWindow(ms: number): Promise<void> {
   return new Promise((r) => setTimeout(r, ms));
 }
 
+async function waitForProviderCloseResult(
+  session: string,
+  pid: number,
+): Promise<void> {
+  const deadline = Date.now() + PROVIDER_CLOSE_WAIT_MS;
+  while (Date.now() < deadline) {
+    if (hasProviderCloseResult(session) || !isPidRunning(pid)) return;
+    await new Promise((resolve) => setTimeout(resolve, 100));
+  }
+}
+
+async function waitForCloseAllTargets(
+  targets: ReadonlyArray<ClosableSession>,
+): Promise<void> {
+  const hasProviderSession = targets.some((target) => target.provider);
+  const deadline =
+    Date.now() + (hasProviderSession ? PROVIDER_CLOSE_WAIT_MS : CLOSE_WAIT_MS);
+  while (Date.now() < deadline) {
+    const stillWaiting = targets.some((target) => {
+      if (target.pid == null || !isPidRunning(target.pid)) return false;
+      return target.provider ? !hasProviderCloseResult(target.session) : true;
+    });
+    if (!stillWaiting) return;
+    await new Promise((resolve) => setTimeout(resolve, 100));
+  }
+}
+
+async function closeProviderSessionDirectly(
+  session: string,
+  providerState: { name: string; sessionId: string },
+  logger: LoggerApi,
+): Promise<string | undefined> {
+  try {
+    const provider = getCloudProviderApi(providerState.name);
+    const result = await provider.closeSession(providerState.sessionId);
+    logger.info("close-provider-direct-fallback-success", {
+      session,
+      provider: providerState.name,
+      sessionId: providerState.sessionId,
+      replayUrl: result.replayUrl,
+    });
+    return result.replayUrl;
+  } catch (error) {
+    logger.warn("close-provider-direct-fallback-failed", {
+      session,
+      provider: providerState.name,
+      sessionId: providerState.sessionId,
+      error,
+    });
+    throw new Error(
+      `Failed to close remote ${providerState.name} session "${providerState.sessionId}" for session "${session}". ` +
+        `State preserved with status "cleanup-failed". Retry with: ${librettoCommand(`close --session ${session}`)}`,
+    );
+  }
+}
+
+function readProviderReplayUrl(session: string, logger: LoggerApi): string | undefined {
+  const closePath = getSessionProviderClosePath(session);
+  if (!existsSync(closePath)) return undefined;
+  try {
+    const parsed = JSON.parse(readFileSync(closePath, "utf8")) as {
+      replayUrl?: unknown;
+    };
+    return typeof parsed.replayUrl === "string" && parsed.replayUrl.length > 0
+      ? parsed.replayUrl
+      : undefined;
+  } catch (err) {
+    logger.warn("provider-close-result-read-failed", {
+      session,
+      path: closePath,
+      error: err,
+    });
+    return undefined;
+  }
+}
+
+function hasProviderCloseResult(session: string): boolean {
+  return existsSync(getSessionProviderClosePath(session));
+}
+
 function sendSignalToProcessGroupOrPid(
   pid: number,
   signal: NodeJS.Signals,
@@ -811,6 +1004,12 @@ function clearStoppedSessionStates(
   return cleared;
 }
 
+function markProviderCleanupFailed(session: string, logger: LoggerApi): void {
+  const state = readSessionState(session, logger);
+  if (!state) return;
+  writeSessionState({ ...state, status: "cleanup-failed" }, logger);
+}
+
 export async function runCloseAll(
   logger: LoggerApi,
   options?: { force?: boolean },
@@ -828,75 +1027,80 @@ export async function runCloseAll(
     return;
   }
 
-  // Close provider sessions via their APIs
   const failedProviderSessions = new Set<string>();
-  const replayUrls: Array<{ session: string; replayUrl: string }> = [];
-  for (const target of closable) {
-    if (target.provider) {
-      logger.info("close-all-provider", {
-        session: target.session,
-        provider: target.provider.name,
-        sessionId: target.provider.sessionId,
-      });
-      try {
-        const provider = getCloudProviderApi(target.provider.name);
-        const result = await provider.closeSession(target.provider.sessionId);
-        if (result.replayUrl) {
-          replayUrls.push({
+  const gracefulCloseFailures = new Map<string, Error>();
+
+  await Promise.all(
+    closable.map(async (target) => {
+      if (target.pid == null) return;
+      if (target.daemonSocketPath && isPidRunning(target.pid)) {
+        try {
+          await closeDaemonSession(target, logger);
+          return;
+        } catch (error) {
+          const closeError = formatDaemonCloseFailure(
+            target.session,
+            target.provider?.name,
+            error,
+          );
+          gracefulCloseFailures.set(target.session, closeError);
+          logger.warn("close-all-daemon-ipc-failed", {
             session: target.session,
-            replayUrl: result.replayUrl,
+            pid: target.pid,
+            error: closeError.message,
           });
-        }
-      } catch (err) {
-        logger.warn("close-all-provider-error", {
-          session: target.session,
-          provider: target.provider.name,
-          sessionId: target.provider.sessionId,
-          error: err,
-        });
-        failedProviderSessions.add(target.session);
-        // Mark as cleanup-failed, preserving provider.sessionId for retry
-        const state = readSessionState(target.session, logger);
-        if (state) {
-          writeSessionState({ ...state, status: "cleanup-failed" }, logger);
+          if (!force) return;
         }
       }
-    }
-  }
 
-  // Send SIGTERM to all daemon processes (both local and provider sessions).
+      logger.info("close-all-sigterm", {
+        session: target.session,
+        pid: target.pid,
+        port: target.port,
+      });
+      sendSignalToProcessGroupOrPid(
+        target.pid,
+        "SIGTERM",
+        logger,
+        target.session,
+      );
+    }),
+  );
+
+  await waitForCloseAllTargets(closable);
+
   for (const target of closable) {
-    if (target.pid == null) continue;
-    logger.info("close-all-sigterm", {
-      session: target.session,
-      pid: target.pid,
-      port: target.port,
-    });
-    sendSignalToProcessGroupOrPid(
-      target.pid,
-      "SIGTERM",
-      logger,
-      target.session,
-    );
+    if (!target.provider || hasProviderCloseResult(target.session)) continue;
+    if (target.pid != null && isPidRunning(target.pid)) continue;
+    try {
+      await closeProviderSessionDirectly(target.session, target.provider, logger);
+    } catch {
+      markProviderCleanupFailed(target.session, logger);
+      failedProviderSessions.add(target.session);
+    }
   }
 
-  await waitForCloseSignalWindow(CLOSE_WAIT_MS);
-
   let survivors = closable.filter(
     (target) => target.pid != null && isPidRunning(target.pid),
   );
-  if (survivors.length > 0 && !force) {
+  if ((survivors.length > 0 || gracefulCloseFailures.size > 0) && !force) {
     const closed = clearStoppedSessionStates(
       closable,
       logger,
       failedProviderSessions,
     );
+    const failedSessions = Array.from(
+      new Set([
+        ...survivors.map((survivor) => survivor.session),
+        ...gracefulCloseFailures.keys(),
+      ]),
+    ).map((sessionName) => ({ session: sessionName }));
 
     throw new Error(
       [
-        `Failed to close ${survivors.length} session(s) gracefully: ${formatSessionList(survivors)}.`,
+        `Failed to close ${failedSessions.length} session(s) gracefully: ${formatSessionList(failedSessions)}.`,
         `Closed ${closed} session(s).`,
-        `Retry with: libretto close --all --force`,
+        `Retry with: ${librettoCommand("close --all --force")}`,
       ].join("\n"),
     );
   }
@@ -937,13 +1141,14 @@ export async function runCloseAll(
     }
   }
 
-  clearStoppedSessionStates(closable, logger, failedProviderSessions);
+  const replayUrls = closable
+    .filter((target) => target.provider)
+    .flatMap((target) => {
+      const replayUrl = readProviderReplayUrl(target.session, logger);
+      return replayUrl ? [{ session: target.session, replayUrl }] : [];
+    });
 
-  if (failedProviderSessions.size > 0) {
-    console.log(
-      `Warning: ${failedProviderSessions.size} provider session(s) failed remote cleanup and were preserved with status "cleanup-failed".`,
-    );
-  }
+  clearStoppedSessionStates(closable, logger, failedProviderSessions);
 
   if (clearedUnreadableStates > 0) {
     console.log(
@@ -952,19 +1157,28 @@ export async function runCloseAll(
   }
   const closedCount = closable.length - failedProviderSessions.size;
   console.log(`Closed ${closedCount} session(s).`);
+  if (failedProviderSessions.size > 0) {
+    console.warn(
+      `Failed to confirm remote cleanup for ${failedProviderSessions.size} provider-backed session(s). ` +
+        `State preserved with status "cleanup-failed". Retry with: ${librettoCommand("close --all")}`,
+    );
+  }
+  for (const recording of replayUrls) {
+    console.log(
+      `View recording for session "${recording.session}": ${recording.replayUrl}`,
+    );
+  }
   if (forceKilled > 0) {
     console.log(`Force-killed ${forceKilled} session(s).`);
   }
-  for (const { session, replayUrl } of replayUrls) {
-    console.log(`View recording (${session}): ${replayUrl}`);
-  }
 }
 
 export async function runConnect(
   cdpUrl: string,
   session: string,
   logger: LoggerApi,
-  accessMode: SessionAccessMode = "write-access",
+  accessMode: SessionAccessMode,
+  experiments: Experiments,
 ): Promise<void> {
   logger.info("connect-start", { cdpUrl, session, accessMode });
   assertSessionAvailableForStart(session, logger);
@@ -978,11 +1192,11 @@ export async function runConnect(
         `Invalid CDP URL: ${cdpUrl}`,
         ``,
         `Expected an HTTP or WebSocket URL pointing to a Chrome DevTools Protocol endpoint, for example:`,
-        `  libretto connect http://127.0.0.1:9222`,
-        `  libretto connect http://remote-host:9222`,
-        `  libretto connect http://remote-host:9222/devtools/browser/<id>`,
-        `  libretto connect ws://remote-host:9222/devtools/browser/<id>`,
-        `  libretto connect wss://remote-host/cdp-endpoint`,
+        `  ${librettoCommand("connect http://127.0.0.1:9222")}`,
+        `  ${librettoCommand("connect http://remote-host:9222")}`,
+        `  ${librettoCommand("connect http://remote-host:9222/devtools/browser/<id>")}`,
+        `  ${librettoCommand("connect ws://remote-host:9222/devtools/browser/<id>")}`,
+        `  ${librettoCommand("connect wss://remote-host/cdp-endpoint")}`,
       ].join("\n"),
     );
   }
@@ -1024,12 +1238,15 @@ export async function runConnect(
 
   const runLogPath = logFileForSession(session);
   const { pid, socketPath: daemonSocketPath, client } =
-    await spawnSessionDaemon({
-      config: { mode: "connect" as const, session, cdpEndpoint: endpoint },
-      session,
+    await DaemonClient.spawn({
+      config: {
+        session,
+        experiments,
+        browser: { kind: "connect", cdpEndpoint: endpoint },
+      },
       logger,
       logPath: runLogPath,
-      ipcTimeoutMs: 10_000,
+      startupTimeoutMs: 10_000,
     });
 
   writeSessionState(
@@ -1047,7 +1264,12 @@ export async function runConnect(
   );
 
   // Query the daemon for discovered pages.
-  const pages = await client.pages();
+  let pages: OpenPageSummary[];
+  try {
+    pages = await client.pages();
+  } finally {
+    client.destroy();
+  }
 
   logger.info("connect-success", { cdpUrl: endpoint, session, port });
   console.log(`Connected to ${endpoint} (session: ${session})`);