@foldspace_npm/harness 0.1.2 → 0.1.4

package/bin/attach.mjs

@@ -2,7 +2,7 @@
 /**
  * Attach to the Chrome launched by inject.mjs and serve local actions to it.
  *
- * Two modes, picked automatically:
+ * Three explicit page modes:
  *
  *  swap (default)  The client app already embeds Foldspace. We
  *                  intercept the remote-actions bundle request and fulfill it
@@ -11,7 +11,11 @@
  *                  page's own agent instead of creating a second one.
  *
  *  --bootstrap     The app has no Foldspace. Inject the SDK bootstrap from the
- *                  generated extension/index.js before page scripts run.
+ *                  harness bootstrap module before page scripts run.
+ *
+ *  --replace       The app embeds a different Foldspace product or agent.
+ *                  Rebind the page bootstrap to the configured product and
+ *                  make the configured agent the sole visible widget owner.
  *
  * Chrome 136+ removed --load-extension and does not run content scripts for
  * CDP-loaded extensions, so neither path uses the extension at runtime.
@@ -19,31 +23,85 @@
 import fs from "fs";
 import path from "path";
 import { fileURLToPath } from "url";
+import {
+  ATTACH_MODES,
+  attachModeFromArgs,
+  characterizePageAgents,
+  hostMatches,
+  hostPatternsFromTarget,
+  parseAgentId,
+} from "../src/attach-helpers.mjs";
+import {
+  buildReplacePrelude,
+  detectedProductIds,
+  guardScriptForHosts,
+  guardAttachMode,
+  isSdkScriptRequest,
+  rewriteSdkRequestKey,
+  shouldFulfillActionRequest,
+} from "../src/attach-preflight.mjs";
+import { serializeDiagnostic } from "../src/diagnostics.mjs";
+import {
+  ERROR_CODES,
+  createLifecycleResult,
+} from "../src/protocol.mjs";
+import { createCdpRequestManager } from "../src/cdp-request-manager.mjs";
+import { buildActionObserverScript } from "../src/action-observer.mjs";
+import { buildBootstrapScript } from "../src/bootstrap-script.mjs";
+import {
+  createSessionCollector,
+  formatActionObservation,
+  formatSessionSummary,
+} from "../src/session-summary.mjs";
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 // Resolve the CONSUMING repo, not this package. FOLDSPACE_PROJECT_DIR lets a
 // hosted builder point the harness at a workspace it controls.
 const root = process.env.FOLDSPACE_PROJECT_DIR || process.cwd();
-const extDir = path.join(root, ".foldspace-dev", "extension");
 const bundlePath = path.join(root, "dist", "index.js");
 
 // Prefer what inject actually launched, then an explicit override, then the
 // legacy default. Guessing here means attaching to the wrong browser.
-function portFromState() {
+function readDevState() {
   try {
-    return JSON.parse(fs.readFileSync(path.join(root, ".foldspace-dev", "state.json"), "utf8")).debugPort;
+    return JSON.parse(
+      fs.readFileSync(
+        path.join(root, ".foldspace-dev", "state.json"),
+        "utf8",
+      ),
+    );
   } catch {
-    return null;
+    return {};
   }
 }
+const devState = readDevState();
 const portArgIndex = process.argv.indexOf("--port");
+const targetArgIndex = process.argv.indexOf("--target");
+const explicitPort =
+  portArgIndex > -1 ? process.argv[portArgIndex + 1] : null;
+const explicitTarget =
+  targetArgIndex > -1 ? process.argv[targetArgIndex + 1] : null;
+const savedLaunchMatches =
+  !explicitTarget || explicitTarget === devState.target;
+const useSavedLaunch =
+  !explicitPort &&
+  !process.env.CDP_PORT &&
+  savedLaunchMatches;
 const port = String(
-  (portArgIndex > -1 && process.argv[portArgIndex + 1]) ||
+  explicitPort ||
     process.env.CDP_PORT ||
-    portFromState() ||
+    (useSavedLaunch ? devState.debugPort : null) ||
     "9222",
 );
-const bootstrap = process.argv.includes("--bootstrap");
+let attachMode;
+try {
+  attachMode = attachModeFromArgs(process.argv.slice(2));
+} catch (error) {
+  console.error(`attach: ${error instanceof Error ? error.message : String(error)}`);
+  process.exit(1);
+}
+const bootstrap = attachMode === ATTACH_MODES.BOOTSTRAP;
+const replace = attachMode === ATTACH_MODES.REPLACE;
 // Test mode keeps conversations out of the customer's default list. Turn it off
 // only when you WANT the conversations and action calls to show up in the
 // Foldspace dashboard — a brand-new agent during initial setup, where there is
@@ -53,18 +111,35 @@ const noTestMode = process.argv.includes("--no-test-mode");
 // string that asserts you are safe while you are not. It now states what is
 // actually true. --no-badge drops it entirely, for recording a demo.
 const noBadge = process.argv.includes("--no-badge");
-const badgeText = noTestMode
-  ? "FOLDSPACE DEV \u00b7 local actions \u00b7 LIVE"
-  : "FOLDSPACE DEV \u00b7 local actions \u00b7 TEST MODE";
-
 // Agent api name for setTestMode — from the same config inject.mjs used.
 const cfg = JSON.parse(fs.readFileSync(path.join(root, "foldspace.dev.json"), "utf8"));
-const cfgTarget = cfg.targets[cfg.defaultTarget] || {};
+const targetName =
+  explicitTarget ||
+  (useSavedLaunch ? devState.target : null) ||
+  cfg.defaultTarget;
+const configuredTarget = cfg.targets[targetName] || {};
+const cfgTarget =
+  !explicitTarget &&
+  useSavedLaunch &&
+  devState.target === targetName &&
+  devState.resolvedTarget &&
+  typeof devState.resolvedTarget === "object"
+    ? { ...configuredTarget, ...devState.resolvedTarget }
+    : configuredTarget;
 const agentApiName =
-  process.env.AGENT_API_NAME ||
   (process.argv.includes("--agent")
     ? process.argv[process.argv.indexOf("--agent") + 1]
-    : cfgTarget.agentApiName);
+    : null) ||
+  process.env.AGENT_API_NAME ||
+  cfgTarget.agentApiName;
+const productId = cfgTarget.productId;
+const agentMode = String(cfgTarget.mode || "OVERLAY").toUpperCase();
+const agentKey = cfgTarget.overrideKey || `EU-${productId}-1-1`;
+const sdkUrl = cfgTarget.sdkUrl || cfg.sdkUrl;
+const actionTarget = { productId, agentApiName };
+const badgeText = noTestMode
+  ? `FOLDSPACE DEV \u00b7 ${agentApiName} \u00b7 ${attachMode} \u00b7 LIVE`
+  : `FOLDSPACE DEV \u00b7 ${agentApiName} \u00b7 ${attachMode} \u00b7 TEST MODE`;
 
 // Refuse to run against an uninitialised template. Without this, attach injects
 // the literal placeholder as an agent api name and the page fails with an opaque
@@ -77,26 +152,38 @@ const unresolved = PLACEHOLDERS.filter((ph) =>
 if (unresolved.length) {
   console.error(
     `attach: foldspace.dev.json still contains placeholders: ${unresolved.join(", ")}\n` +
-    `        Run "node scripts/init.mjs" first, or pass --agent <apiName>.\n` +
+    `        Run "foldspace init" first, or pass --agent <apiName>.\n` +
     `        Refusing to run — injecting a placeholder breaks the app's agent.`
   );
   process.exit(1);
 }
-
-const manifest = JSON.parse(fs.readFileSync(path.join(extDir, "manifest.json"), "utf8"));
-const hostPatterns = manifest.content_scripts[0].matches.map((m) =>
-  m.replace("*://", "").replace("/*", "")
-);
-const hostMatches = (url) => {
-  let h;
-  try { h = new URL(url).hostname; } catch { return false; }
-  return hostPatterns.some((p) =>
-    p.startsWith("*.") ? h === p.slice(2) || h.endsWith(p.slice(1)) : h === p
+if (!productId || !agentApiName) {
+  console.error("attach: foldspace.dev.json must define productId and agentApiName.");
+  process.exit(1);
+}
+if (bootstrap && (!sdkUrl || typeof sdkUrl !== "string")) {
+  console.error("attach: foldspace.dev.json must define sdkUrl for --bootstrap.");
+  process.exit(1);
+}
+if (!fs.existsSync(bundlePath)) {
+  console.error(`attach: ${path.relative(root, bundlePath)} is missing — run "npm run build" first.`);
+  process.exit(1);
+}
+const hostPatterns = hostPatternsFromTarget(cfgTarget);
+if (!hostPatterns.length) {
+  console.error(
+    `attach: target "${targetName}" must define hosts or a valid startUrl.`,
   );
-};
+  process.exit(1);
+}
 
-// Any remote-actions bundle, dev or prod, for any product/agent.
+// CDP patterns are intentionally broad; the paused-request handler only
+// fulfills the configured product/agent and continues every unrelated request.
 const ACTIONS_PATTERN = "*/agent/actions/*";
+const SDK_PATTERNS = [
+  "*://*/*foldspace.js*",
+  "*://*/*eucera.js*",
+];
 
 const badgeSrc = `(() => {
   if (window.top !== window.self) return;
@@ -202,59 +289,438 @@ const testModeSrc = `(() => {
   }, 50);
 })();`;
 
-let nextId = 1;
-const pending = new Map();
-const prepared = new Set();
+const cdpRequests = createCdpRequestManager();
+const sessionCollector = createSessionCollector();
+// sessionId -> preparation state used for deterministic detach cleanup.
+const prepared = new Map();
+const preparing = new Set();
+// Rejections are scoped to the observed URL so a later navigation can retry.
+const rejected = new Map();
 // targetId -> sessionId, so a target that navigates INTO a matching host can be
 // prepared later. Without this, opening Chrome on a new tab and then browsing
 // to the app never arms the swap.
 const sessions = new Map();
+const sessionUrls = new Map();
 let served = 0;
+let shuttingDown = false;
+let reconnecting = false;
+let summaryPrinted = false;
+const call = cdpRequests.call;
+
+function logLifecycle(result) {
+  const detail = result.ok
+    ? `${result.operation}:${result.state}`
+    : `${result.operation}:${result.state} ${result.error.code}`;
+  console.log(`  [lifecycle] ${detail}`);
+  if (!result.ok && result.error?.message) {
+    console.log(`    ${result.error.message}`);
+  }
+  if (!result.ok && result.details?.suggestion) {
+    console.log(`    Next: ${result.details.suggestion}`);
+  }
+}
+
+async function runDiagnostic(ws, sessionId, name, args = {}) {
+  const evaluation = await call(
+    ws,
+    "Runtime.evaluate",
+    {
+      expression: serializeDiagnostic(name, args),
+      awaitPromise: true,
+      returnByValue: true,
+    },
+    sessionId,
+  );
+  if (evaluation?.exceptionDetails) {
+    throw new Error(
+      `Diagnostic ${name} failed in the page: ${
+        evaluation.exceptionDetails.text || "Unknown evaluation error"
+      }`,
+    );
+  }
+  return evaluation?.result?.value || null;
+}
+
+async function inspectPage(ws, sessionId) {
+  let state = null;
+  let stableNoSdkObservations = 0;
+  for (let attempt = 0; attempt < 40; attempt++) {
+    try {
+      state = await runDiagnostic(ws, sessionId, "inspectSdkState", {
+        expectedApiName: agentApiName,
+        expectedMode: agentMode,
+      });
+    } catch {
+      await new Promise((resolve) => setTimeout(resolve, 100));
+      continue;
+    }
+
+    const ready =
+      state?.documentReadyState === "interactive" ||
+      state?.documentReadyState === "complete";
+    const onConfiguredHost =
+      !state?.pageUrl || hostMatches(state.pageUrl, hostPatterns);
+    if (!ready || !onConfiguredHost) {
+      stableNoSdkObservations = 0;
+      await new Promise((resolve) => setTimeout(resolve, 100));
+      continue;
+    }
+
+    if (state.sdkPresent) {
+      if (
+        attachMode !== ATTACH_MODES.SWAP ||
+        (state.sdkReady && state.agentIds.length > 0)
+      ) {
+        return state;
+      }
+      stableNoSdkObservations = 0;
+    } else if (attachMode === ATTACH_MODES.BOOTSTRAP) {
+      stableNoSdkObservations += 1;
+      if (stableNoSdkObservations >= 5) return state;
+    }
+    await new Promise((resolve) => setTimeout(resolve, 100));
+  }
+  return state;
+}
 
-const call = (ws, method, params = {}, sessionId) =>
-  new Promise((resolve) => {
-    const id = nextId++;
-    pending.set(id, resolve);
-    ws.send(JSON.stringify({ id, method, params, sessionId }));
+async function verifyPreparedPage(ws, sessionId) {
+  const latest = {
+    state: null,
+    characterization: null,
+    products: [],
+    widget: null,
+    registration: null,
+    observation: null,
+    diagnosticError: null,
+  };
+  for (let attempt = 0; attempt < 40; attempt++) {
+    try {
+      const state = await runDiagnostic(ws, sessionId, "inspectSdkState", {
+        expectedApiName: agentApiName,
+        expectedMode: agentMode,
+      });
+      const characterization = characterizePageAgents({
+        sdkPresent: state?.sdkPresent === true,
+        agentIds: state?.agentIds || [],
+        expectedApiName: agentApiName,
+        expectedMode: agentMode,
+      });
+      const products = detectedProductIds(state);
+      latest.state = state;
+      latest.characterization = characterization;
+      latest.products = products;
+      const productMatches = products.includes(productId);
+      const widget = await runDiagnostic(
+        ws,
+        sessionId,
+        "verifyWidgetVisible",
+        { ownerAgentId: characterization.expectedAgentId },
+      );
+      latest.widget = widget;
+      const visibilityMatches =
+        attachMode !== ATTACH_MODES.REPLACE ||
+        (widget?.soleVisible === true && widget?.ownerMatches === true);
+      if (
+        characterization.status === "same-agent" &&
+        productMatches &&
+        visibilityMatches
+      ) {
+        const observation = await runDiagnostic(
+          ws,
+          sessionId,
+          "inspectActionObservation",
+          { ownerAgentId: characterization.expectedAgentId },
+        );
+        latest.observation = observation;
+        const expectedActionNames =
+          observation?.installed &&
+          observation?.ownerMatches &&
+          !observation?.actionNameLimitExceeded &&
+          Array.isArray(observation.expectedActionNames)
+            ? observation.expectedActionNames
+            : [];
+        const registration = await runDiagnostic(
+          ws,
+          sessionId,
+          "inspectRegistration",
+          {
+            apiName: agentApiName,
+            mode: agentMode,
+            ownerAgentId: characterization.expectedAgentId,
+            expectedActionNames,
+          },
+        );
+        latest.registration = registration;
+        if (
+          observation?.captureCount > 0 &&
+          expectedActionNames.length > 0 &&
+          registration?.agentFound &&
+          registration.missingActionNames?.length === 0 &&
+          registration.unexpectedActionNames?.length === 0
+        ) {
+          return {
+            ok: true,
+            state,
+            characterization,
+            products,
+            widget,
+            registration,
+            observation,
+          };
+        }
+      }
+    } catch (error) {
+      // Reload briefly destroys the execution context. Retry until the page and
+      // SDK settle instead of treating that expected transition as a mismatch.
+      latest.diagnosticError =
+        error instanceof Error ? error.message.slice(0, 500) : String(error);
+    }
+    await new Promise((resolve) => setTimeout(resolve, 250));
+  }
+  const state = await inspectPage(ws, sessionId);
+  latest.state = state;
+  latest.characterization = characterizePageAgents({
+    sdkPresent: state?.sdkPresent === true,
+    agentIds: state?.agentIds || [],
+    expectedApiName: agentApiName,
+    expectedMode: agentMode,
   });
+  latest.products = detectedProductIds(state);
+  return {
+    ok: false,
+    ...latest,
+  };
+}
 
 async function prepare(ws, sessionId, url) {
-  if (prepared.has(sessionId)) return;
-  prepared.add(sessionId);
-
-  await call(ws, "Page.enable", {}, sessionId);
-  await call(ws, "Runtime.enable", {}, sessionId);
-  await call(ws, "Page.setBypassCSP", { enabled: true }, sessionId);
-
-  // Workers spawned by this page attach through THIS session, not the browser
-  // one, so the browser-level setAutoAttach does not cover them and they start
-  // paused. Say so here too, or the app's workers freeze for the session.
-  await call(ws, "Target.setAutoAttach", {
-    autoAttach: true, waitForDebuggerOnStart: false, flatten: true,
-  }, sessionId);
-
-  await call(ws, "Fetch.enable", {
-    patterns: [{ urlPattern: ACTIONS_PATTERN, requestStage: "Request" }],
-  }, sessionId);
-
-  // The action bundle, injected rather than fetched. This is what lets the
-  // harness drop the dev server — and what makes a non-local browser possible,
-  // since a remote Chrome can never reach localhost.
-  const scripts = [];
-  if (fs.existsSync(bundlePath)) {
-    scripts.push(fs.readFileSync(bundlePath, "utf8"));
-  } else {
-    console.log(`  !! ${path.relative(root, bundlePath)} missing — run "npm run dev"`);
+  if (rejected.has(sessionId) && rejected.get(sessionId) !== url) {
+    rejected.delete(sessionId);
   }
-  if (!noBadge) scripts.push(badgeSrc);
-  if (!noTestMode) scripts.push(testModeSrc);
-  if (bootstrap) scripts.push(fs.readFileSync(path.join(extDir, "index.js"), "utf8"));
-  for (const source of scripts) {
-    await call(ws, "Page.addScriptToEvaluateOnNewDocument", { source, runImmediately: true }, sessionId);
+  if (
+    prepared.has(sessionId) ||
+    preparing.has(sessionId) ||
+    rejected.has(sessionId)
+  ) {
+    return;
   }
+  preparing.add(sessionId);
+
+  try {
+    await call(ws, "Page.enable", {}, sessionId);
+    await call(ws, "Runtime.enable", {}, sessionId);
+
+    const pageState = await inspectPage(ws, sessionId);
+    if (!pageState?.pageUrl || !hostMatches(pageState.pageUrl, hostPatterns)) {
+      return;
+    }
+    const characterization = characterizePageAgents({
+      sdkPresent: pageState?.sdkPresent === true,
+      agentIds: pageState?.agentIds || [],
+      expectedApiName: agentApiName,
+      expectedMode: agentMode,
+    });
+    const pageProductIds = detectedProductIds(pageState);
+    const guard = guardAttachMode({
+      mode: attachMode,
+      characterization,
+      expectedProductId: productId,
+      pageProductIds,
+    });
+    if (!guard.ok) {
+      rejected.set(sessionId, url);
+      logLifecycle(
+        createLifecycleResult({
+          operation: "prepare_page",
+          ok: false,
+          state: "rejected",
+          error: { code: guard.code, message: guard.message },
+          details: {
+            url,
+            mode: attachMode,
+            expectedAgentId: characterization.expectedAgentId,
+            detectedAgentIds: pageState?.agentIds || [],
+            expectedProductId: productId,
+            detectedProductIds: pageProductIds,
+            suggestion: guard.suggestion || "",
+          },
+        }),
+      );
+      return;
+    }
+
+    logLifecycle(
+      createLifecycleResult({
+        operation: "prepare_page",
+        ok: true,
+        state: "preflight_ok",
+        details: {
+          url,
+          mode: attachMode,
+          expectedAgentId: characterization.expectedAgentId,
+          detectedAgentIds: pageState?.agentIds || [],
+          expectedProductId: productId,
+          detectedProductIds: pageProductIds,
+        },
+      }),
+    );
+
+    await call(ws, "Page.setBypassCSP", { enabled: true }, sessionId);
+
+    // Workers spawned by this page attach through THIS session, not the browser
+    // one, so the browser-level setAutoAttach does not cover them and they start
+    // paused. Say so here too, or the app's workers freeze for the session.
+    await call(ws, "Target.setAutoAttach", {
+      autoAttach: true, waitForDebuggerOnStart: false, flatten: true,
+    }, sessionId);
+
+    const fetchPatterns = [
+      { urlPattern: ACTIONS_PATTERN, requestStage: "Request" },
+      ...(replace
+        ? SDK_PATTERNS.map((urlPattern) => ({
+            urlPattern,
+            requestStage: "Request",
+          }))
+        : []),
+    ];
+    await call(ws, "Fetch.enable", { patterns: fetchPatterns }, sessionId);
 
-  console.log(`  attached -> ${url}`);
-  await call(ws, "Page.reload", { ignoreCache: true }, sessionId);
+    // The action bundle, injected rather than fetched. This is what lets the
+    // harness drop the dev server — and what makes a non-local browser possible,
+    // since a remote Chrome can never reach localhost.
+    const scriptIds = [];
+    const observerResult = await call(
+      ws,
+      "Page.addScriptToEvaluateOnNewDocument",
+      {
+        source: guardScriptForHosts(
+          buildActionObserverScript({
+            agentApiName,
+            mode: agentMode,
+            namespace: pageState?.namespace || "foldspace",
+          }),
+          hostPatterns,
+        ),
+      },
+      sessionId,
+    );
+    if (observerResult?.identifier) {
+      scriptIds.push(observerResult.identifier);
+    }
+    if (replace) {
+      const aliases = characterization.agents
+        .map((agent) => agent.apiName)
+        .filter((apiName) => apiName !== agentApiName);
+      const result = await call(
+        ws,
+        "Page.addScriptToEvaluateOnNewDocument",
+        {
+          source: guardScriptForHosts(
+            buildReplacePrelude({
+              agentKey,
+              agentApiName,
+              mode: agentMode,
+              namespace: pageState?.namespace || "foldspace",
+              aliases,
+            }),
+            hostPatterns,
+          ),
+        },
+        sessionId,
+      );
+      if (result?.identifier) scriptIds.push(result.identifier);
+    }
+
+    const scripts = [];
+    scripts.push(fs.readFileSync(bundlePath, "utf8"));
+    if (!noBadge) scripts.push(badgeSrc);
+    if (!noTestMode) scripts.push(testModeSrc);
+    if (bootstrap) {
+      scripts.push(
+        buildBootstrapScript({
+          sdkUrl,
+          productId,
+          agentApiName,
+          mode: agentMode,
+          overrideKey: cfgTarget.overrideKey || null,
+          namespace: pageState?.namespace || "foldspace",
+        }),
+      );
+    }
+    for (const source of scripts) {
+      const result = await call(
+        ws,
+        "Page.addScriptToEvaluateOnNewDocument",
+        {
+          source: guardScriptForHosts(source, hostPatterns),
+          runImmediately: true,
+        },
+        sessionId,
+      );
+      if (result?.identifier) scriptIds.push(result.identifier);
+    }
+
+    prepared.set(sessionId, {
+      scriptIds,
+      mode: attachMode,
+      url,
+      observing: true,
+      fetchEnabled: true,
+      sdkScriptUrls: (pageState?.scripts || []).filter((source) =>
+        isSdkScriptRequest(source),
+      ),
+    });
+    console.log(`  attached -> ${url}`);
+    await call(ws, "Page.reload", { ignoreCache: true }, sessionId);
+
+    {
+      const verification = await verifyPreparedPage(ws, sessionId);
+      logLifecycle(
+        createLifecycleResult({
+          operation: "inspect_registration",
+          ok: verification.ok,
+          state: verification.ok ? "registration_ok" : "registration_mismatch",
+          error: verification.ok
+            ? undefined
+            : {
+                code: ERROR_CODES.REGISTRATION_MISMATCH,
+                message:
+                  "The local action registry did not match the configured page agent.",
+              },
+          details: {
+            mode: attachMode,
+            expectedAgentId: verification.characterization.expectedAgentId,
+            detectedAgentIds: verification.state?.agentIds || [],
+            expectedProductId: productId,
+            detectedProductIds: verification.products,
+            widget: verification.widget,
+            registeredActionNames:
+              verification.registration?.actionNames || [],
+            expectedActionNames:
+              verification.observation?.expectedActionNames || [],
+            missingActionNames:
+              verification.registration?.missingActionNames || [],
+            unexpectedActionNames:
+              verification.registration?.unexpectedActionNames || [],
+            actionObserverSubscribed:
+              verification.observation?.subscribed === true,
+            actionNameLimitExceeded:
+              verification.observation?.actionNameLimitExceeded === true,
+            diagnosticError: verification.diagnosticError,
+          },
+        }),
+      );
+      if (!verification.ok) {
+        const state = prepared.get(sessionId);
+        if (state) {
+          await cleanupPreparedSession(ws, sessionId, state);
+          prepared.delete(sessionId);
+        }
+        rejected.set(sessionId, url);
+      }
+    }
+  } finally {
+    preparing.delete(sessionId);
+  }
 }
 
 async function onEvent(ws, msg) {
@@ -264,7 +730,10 @@ async function onEvent(ws, msg) {
     const t = params.targetInfo;
     if (t.type === "page") {
       sessions.set(t.targetId, params.sessionId);
-      if (hostMatches(t.url)) await prepare(ws, params.sessionId, t.url);
+      sessionUrls.set(params.sessionId, t.url);
+      if (hostMatches(t.url, hostPatterns)) {
+        await prepare(ws, params.sessionId, t.url);
+      }
     } else {
       // Auto-attach pauses workers on start until the attaching client says go.
       // We do not instrument workers — but if we never release them they stay
@@ -281,17 +750,76 @@ async function onEvent(ws, msg) {
   // host, arm it now.
   if (method === "Target.targetInfoChanged") {
     const t = params.targetInfo;
-    if (t.type === "page" && hostMatches(t.url)) {
+    if (t.type === "page") {
       const sid = sessions.get(t.targetId);
-      if (sid) await prepare(ws, sid, t.url);
+      if (!sid) return;
+      sessionUrls.set(sid, t.url);
+      if (hostMatches(t.url, hostPatterns)) {
+        await prepare(ws, sid, t.url);
+      } else {
+        const state = prepared.get(sid);
+        if (state) {
+          await cleanupPreparedSession(ws, sid, state, { reload: false });
+          prepared.delete(sid);
+        }
+        rejected.delete(sid);
+      }
+    }
+    return;
+  }
+
+  if (method === "Target.detachedFromTarget") {
+    const sid = params.sessionId;
+    prepared.delete(sid);
+    preparing.delete(sid);
+    rejected.delete(sid);
+    sessionUrls.delete(sid);
+    for (const [targetId, mappedSessionId] of sessions) {
+      if (mappedSessionId === sid) sessions.delete(targetId);
     }
     return;
   }
 
   if (method === "Fetch.requestPaused") {
     const { requestId, request } = params;
-    if (!fs.existsSync(bundlePath)) {
-      console.log(`  !! dist/index.js missing — run "npm run dev"`);
+    if (!hostMatches(sessionUrls.get(sessionId) || "", hostPatterns)) {
+      await call(ws, "Fetch.continueRequest", { requestId }, sessionId);
+      return;
+    }
+    const preparation = prepared.get(sessionId);
+    if (
+      isSdkScriptRequest(
+        request.url,
+        preparation?.sdkScriptUrls || [],
+      )
+    ) {
+      if (replace) {
+        const rewrittenUrl = rewriteSdkRequestKey(
+          request.url,
+          agentKey,
+          preparation?.sdkScriptUrls || [],
+        );
+        console.log(
+          `  rebound SDK request to product ${productId} for ${agentApiName}`,
+        );
+        await call(
+          ws,
+          "Fetch.continueRequest",
+          { requestId, url: rewrittenUrl },
+          sessionId,
+        );
+      } else {
+        await call(
+          ws,
+          "Fetch.continueRequest",
+          { requestId },
+          sessionId,
+        );
+      }
+      return;
+    }
+    if (!shouldFulfillActionRequest(request.url, actionTarget)) {
+      console.log(`  continued unrelated actions request -> ${request.url.slice(0, 100)}`);
       await call(ws, "Fetch.continueRequest", { requestId }, sessionId);
       return;
     }
@@ -308,14 +836,42 @@ async function onEvent(ws, msg) {
       ],
       body: body.toString("base64"),
     }, sessionId);
+    logLifecycle(
+      createLifecycleResult({
+        operation: "load_artifact",
+        ok: true,
+        state: "artifact_served",
+        details: {
+          productId,
+          agentApiName,
+          bytes: body.length,
+          requestUrl: request.url.slice(0, 2_000),
+        },
+      }),
+    );
     return;
   }
 
   if (method === "Runtime.consoleAPICalled") {
+    const state = prepared.get(sessionId);
+    const currentUrl = sessionUrls.get(sessionId);
+    if (
+      state?.observing !== true ||
+      !currentUrl ||
+      !hostMatches(currentUrl, hostPatterns)
+    ) {
+      return;
+    }
     const text = (params.args || [])
       .map((a) => (a.value !== undefined ? a.value : a.description || ""))
       .join(" ");
-    if (/foldspace-dev|remote actions|identified|Error/i.test(text) && !/IO (entry|callback)/.test(text)) {
+    const actionEvent = sessionCollector.recordConsole({
+      level: params.type || "log",
+      text,
+    });
+    if (actionEvent) {
+      console.log(`  ${formatActionObservation(actionEvent)}`);
+    } else if (/foldspace-dev|remote actions|identified|Error/i.test(text) && !/IO (entry|callback)/.test(text)) {
       console.log(`  [page] ${text.slice(0, 160)}`);
     }
   }
@@ -330,33 +886,138 @@ const keepAlive = setInterval(() => {}, 1 << 30);
 
 async function connect() {
   const ver = await (await fetch(`http://localhost:${port}/json/version`)).json();
-  ws = new WebSocket(ver.webSocketDebuggerUrl);
+  const socket = new WebSocket(ver.webSocketDebuggerUrl);
   await new Promise((resolve, reject) => {
-    ws.onopen = resolve;
-    ws.onerror = reject;
+    socket.onopen = resolve;
+    socket.onerror = reject;
   });
-  ws.onmessage = (e) => {
+  ws = socket;
+  socket.onmessage = (e) => {
     const m = JSON.parse(e.data);
-    if (m.id && pending.has(m.id)) { pending.get(m.id)(m.result); pending.delete(m.id); }
-    else if (m.method) onEvent(ws, m);
+    if (cdpRequests.handleMessage(m)) return;
+    if (m.method) {
+      void onEvent(socket, m).catch((error) => {
+        console.error(
+          `  attach event failed: ${error instanceof Error ? error.message : String(error)}`,
+        );
+      });
+    }
+  };
+  socket.onclose = () => {
+    if (socket !== ws) return;
+    cdpRequests.failAll(new Error("CDP socket closed"));
+    if (!shuttingDown) void onDisconnect(socket);
   };
-  ws.onclose = () => { void onDisconnect(); };
-  await call(ws, "Target.setDiscoverTargets", { discover: true });
-  await call(ws, "Target.setAutoAttach", { autoAttach: true, waitForDebuggerOnStart: false, flatten: true });
+  await call(socket, "Target.setDiscoverTargets", { discover: true });
+  await call(socket, "Target.setAutoAttach", { autoAttach: true, waitForDebuggerOnStart: false, flatten: true });
   return ver;
 }
 
 const ver = await connect();
 
 console.log(`Attached to ${ver.Browser} on :${port}`);
-console.log(`Mode:  ${bootstrap ? "bootstrap (inject SDK)" : "swap (reuse the app's agent)"}`);
+console.log(`Mode:  ${attachMode}`);
+console.log(`Agent: ${agentApiName} (product ${productId}, ${agentMode})`);
 console.log(`Test:  ${noTestMode ? "OFF — conversations WILL appear in the dashboard" : "on"}`);
 console.log(`Hosts: ${hostPatterns.join(", ")}`);
 console.log(`Serving: ${path.relative(root, bundlePath)}\n`);
 
+function printSessionSummary() {
+  if (summaryPrinted) return;
+  summaryPrinted = true;
+  const summary = formatSessionSummary(sessionCollector.snapshot());
+  if (summary) console.log(`\n${summary}`);
+}
+
+async function cleanupPreparedSession(
+  socket,
+  sessionId,
+  state,
+  { reload = true } = {},
+) {
+  state.observing = false;
+  const failures = [];
+  if (state.fetchEnabled) {
+    try {
+      await call(socket, "Fetch.disable", {}, sessionId);
+      state.fetchEnabled = false;
+    } catch (error) {
+      failures.push(`Fetch.disable: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+  for (const identifier of state.scriptIds) {
+    try {
+      await call(
+        socket,
+        "Page.removeScriptToEvaluateOnNewDocument",
+        { identifier },
+        sessionId,
+      );
+    } catch (error) {
+      failures.push(
+        `remove preload ${identifier}: ${error instanceof Error ? error.message : String(error)}`,
+      );
+    }
+  }
+  state.scriptIds.length = 0;
+  try {
+    await call(
+      socket,
+      "Page.setBypassCSP",
+      { enabled: false },
+      sessionId,
+    );
+  } catch (error) {
+    failures.push(`restore CSP: ${error instanceof Error ? error.message : String(error)}`);
+  }
+  // Preload scripts have already executed in the current document. Reloading
+  // is the generic cleanup for swap handlers, bootstrap SDKs, and replacement
+  // identity aliases alike.
+  if (reload) {
+    try {
+      await call(socket, "Page.reload", { ignoreCache: true }, sessionId);
+    } catch (error) {
+      failures.push(`restore reload: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+  return failures;
+}
+
+async function cleanup() {
+  const failures = [];
+  for (const [sessionId, state] of prepared) {
+    failures.push(...(await cleanupPreparedSession(ws, sessionId, state)));
+  }
+  const result = createLifecycleResult({
+    operation: "cleanup",
+    ok: failures.length === 0,
+    state: failures.length === 0 ? "detached" : "cleanup_failed",
+    error:
+      failures.length === 0
+        ? undefined
+        : {
+            code: ERROR_CODES.TRANSPORT_ERROR,
+            message: failures.join("; "),
+          },
+    details: {
+      sessions: prepared.size,
+      served,
+      pagesReloaded: prepared.size,
+    },
+  });
+  logLifecycle(result);
+  printSessionSummary();
+  return result;
+}
+
 process.on("SIGINT", () => {
-  console.log(`\nDetached. Served the local bundle ${served} time(s).`);
-  process.exit(0);
+  if (shuttingDown) return;
+  shuttingDown = true;
+  void cleanup().finally(() => {
+    clearInterval(keepAlive);
+    console.log(`\nDetached. Served the local bundle ${served} time(s).`);
+    process.exit(0);
+  });
 });
 
 // A closed socket does not mean the browser closed. Chrome drops the CDP
@@ -373,27 +1034,38 @@ async function browserIsUp() {
   }
 }
 
-async function onDisconnect() {
+async function onDisconnect(closedSocket) {
+  if (closedSocket !== ws || reconnecting || shuttingDown) return;
+  reconnecting = true;
   prepared.clear();
+  preparing.clear();
+  rejected.clear();
   sessions.clear();
-  for (let attempt = 1; attempt <= 10; attempt++) {
-    await new Promise((r) => setTimeout(r, Math.min(500 * attempt, 3000)));
-    if (!(await browserIsUp())) {
-      clearInterval(keepAlive);
-      console.log("\nBrowser closed. Detaching.");
-      process.exit(0);
-    }
-    try {
-      console.log(`  connection lost — reconnecting (${attempt}/10)…`);
-      await connect();
-      console.log("  reconnected. Swap is live again.");
-      return;
-    } catch {
-      // fall through and retry
+  sessionUrls.clear();
+  try {
+    for (let attempt = 1; attempt <= 10; attempt++) {
+      await new Promise((r) => setTimeout(r, Math.min(500 * attempt, 3000)));
+      if (!(await browserIsUp())) {
+        clearInterval(keepAlive);
+      printSessionSummary();
+        console.log("\nBrowser closed. Detaching.");
+        process.exit(0);
+      }
+      try {
+        console.log(`  connection lost — reconnecting (${attempt}/10)…`);
+        await connect();
+        console.log(`  reconnected. ${attachMode} mode is live again.`);
+        return;
+      } catch {
+        // fall through and retry
+      }
     }
+    clearInterval(keepAlive);
+    printSessionSummary();
+    console.error("\nCould not reconnect after 10 attempts. Detaching — "
+      + "the page is now loading the DEPLOYED bundle, not your local build.");
+    process.exit(1);
+  } finally {
+    reconnecting = false;
   }
-  clearInterval(keepAlive);
-  console.error("\nCould not reconnect after 10 attempts. Detaching — "
-    + "the page is now loading the DEPLOYED bundle, not your local build.");
-  process.exit(1);
 }