amalgm 0.1.94 → 0.1.95

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "amalgm",
-  "version": "0.1.94",
+  "version": "0.1.95",
   "description": "Amalgm local computer runtime: login, MCP, chat, events, previews, and tunnels.",
   "license": "UNLICENSED",
   "private": false,

package/runtime/scripts/amalgm-mcp/browser/attach.js

@@ -4,36 +4,43 @@
  * Attached mode — drive the browser surface the user is watching.
  *
  * The desktop app advertises its chromium over CDP; the UI mounts the in-tab
- * split-view <webview> with a marker URL. This module owns the handshake:
+ * split-view <webview> with a marker URL. This module owns the attach
+ * handshake and the command transport, built around one rule:
  *
- *  1. Ask the UI to open the surface (a browser_surfaces state event — the
- *     renderer subscribes and mounts the webview; an event, not an RPC).
- *  2. Select the session's webview target by marker (fallbacks: previously
- *     selected target, then the only webview). Fail closed if none appears —
- *     never silently drive the outer app window, never silently go headless.
- *  3. One focus pass — chromium drops CDP Input.* events to a <webview>
- *     guest until the guest widget has focus (reads work unfocused; clicks
- *     would "succeed" without landing).
+ *   A session's identity is established ONCE at attach and VERIFIED on every
+ *   command — never re-asserted by switching tabs.
  *
- * run() is the command transport every verb uses: it ensures the handshake,
- * then shells out to agent-browser, re-attaching once if the connection was
- * lost (app restart, webview remount). In attached mode every call re-pins
- * the session's webview target inside the same batch — the daemon's tab
- * selection is process state that silently falls back to "the active tab"
- * when the selected target dies, and that fallback is how one session ends
- * up reading another session's page. A dead pin fails the call by name and
- * triggers one re-attach instead.
+ * Why: the daemon's tab selection silently falls back to "the active tab"
+ * when the selected target dies (how one session ends up reading another
+ * session's page), but re-selecting the tab per command resets the daemon's
+ * snapshot ref table — `click @e4` right after `snapshot` fails "Unknown
+ * ref". Both verified live. So instead of a per-command `tab` pin, attach:
+ *
+ *  1. Asks the UI to open the surface (a browser_surfaces state event).
+ *  2. Selects the session's webview in the daemon ONCE (refs don't exist yet).
+ *  3. Opens a persistent raw-CDP connection to the guest target and stamps it:
+ *     `window.__amalgmBsid = session` now, plus the same script on every new
+ *     document — the stamp survives navigation and dies with the target.
+ *  4. Prepends a guard eval to every batch: stamp mismatch throws, the batch
+ *     bails before the action runs, and the session re-attaches once. eval
+ *     does not reset refs, so @refs stay live across calls.
+ *
+ * The persistent guest connection doubles as the capture anchor: screenshots
+ * and recordings connect straight to the verified target instead of hunting
+ * the target list per capture (the hunt's "no webviews yet → first page
+ * target" fallback is how cua_screenshot once captured the app's own chat UI).
  */
 
 const cli = require('./cli');
 const backend = require('./backend');
 const cdp = require('./cdp');
-const { attachedSessions, knownSessions } = require('./sessions');
+const { surfaces, knownSessions } = require('./sessions');
 
 const SURFACE_EVENT_RESOURCE = 'browser_surfaces';
 const WEBVIEW_MARKER_PREFIX = 'amalgm-bsid-';
 const WEBVIEW_WAIT_MS = 15_000;
 const WEBVIEW_POLL_MS = 500;
+const GUARD_ERROR = 'amalgm-surface-guard';
 const SURFACE_HIDDEN_MESSAGE = 'The browser surface is hidden in the desktop app and did not reopen. '
   + 'Retry; if it keeps failing, close this browser session and open again '
   + '(a fresh surface will mount), or force a headless browser with AMALGM_BROWSER_BACKEND=cli.';
@@ -42,6 +49,15 @@ function marker(session) {
   return `${WEBVIEW_MARKER_PREFIX}${session}`;
 }
 
+function stampScript(session) {
+  return `window.__amalgmBsid = ${JSON.stringify(session)};`;
+}
+
+function guardCommand(session) {
+  return ['eval', `(() => { if (window.__amalgmBsid !== ${JSON.stringify(session)}) `
+    + `throw new Error(${JSON.stringify(GUARD_ERROR)}); })()`];
+}
+
 /** Options every cli call needs for the current backend. */
 function cliOptions(session, extra = {}) {
   const options = { session, ...extra };
@@ -70,12 +86,6 @@ function requestSurfaceOpen(session, context) {
   }
 }
 
-async function listWebviewTabs(session) {
-  const tabs = await cli.runCli(['tab'], cliOptions(session, { timeoutMs: 15_000 }));
-  const list = tabs?.data?.tabs || tabs?.tabs || [];
-  return list.filter((tab) => tab.type === 'webview');
-}
-
 /**
  * The session's webview rectangle in the app window, or null when the
  * splitview is hidden (0x0) or gone. Raw CDP, deadline-bounded.
@@ -111,64 +121,154 @@ async function ensureSurfaceVisible(session, hintUrl, context, waitMs = WEBVIEW_
 }
 
 /**
- * Pick this session's webview target from the daemon's tab list. Marker URL
- * (fresh surfaces), previously selected tab id (live surfaces), or the live
- * URL the embedder DOM reports for the session's marked element (surfaces
- * that navigated away from the marker — e.g. after an MCP restart).
- *
- * Never "the only webview". A displaced session adopting whatever surface
- * remains is how one chat's browser ends up reading another chat's page —
- * fail closed and let ensureReady reopen a marked surface instead.
+ * This session's candidate webviews out of a target/tab list. Marker in the
+ * url or title identifies fresh surfaces exactly; the live URL the embedder
+ * DOM reports for the session's marked element covers surfaces that
+ * navigated away from the marker (e.g. after an MCP restart) — but two
+ * sessions can browse the same URL, so URL matches are candidates to be
+ * confirmed by stamp, never picked blindly. And never "the only webview":
+ * a displaced session adopting whatever surface remains is how one chat's
+ * browser ends up reading another chat's page.
  */
-function matchWebview(webviews, session, domSrc) {
+function identityCandidates(list, session, domSrc) {
   const markerText = marker(session);
-  const byMarker = webviews.find((tab) => String(tab.url || '').includes(markerText)
-    || String(tab.title || '').includes(markerText));
-  if (byMarker) return byMarker;
-  if (domSrc) {
-    const byDom = webviews.find((tab) => String(tab.url || '') === domSrc);
-    if (byDom) return byDom;
+  const byMarker = list.filter((item) => String(item.url || '').includes(markerText)
+    || String(item.title || '').includes(markerText));
+  if (byMarker.length) return byMarker;
+  if (domSrc) return list.filter((item) => String(item.url || '') === domSrc);
+  return [];
+}
+
+/** The stamp a target's page carries, read over raw CDP; null if unreadable. */
+async function readStamp(wsUrl) {
+  const client = await cdp.connectCdp(wsUrl).catch(() => null);
+  if (!client) return null;
+  try {
+    const { result } = await client.call('Runtime.evaluate', {
+      expression: 'window.__amalgmBsid || null',
+      returnByValue: true,
+    }, 3_000);
+    return result?.value ?? null;
+  } catch {
+    return null;
+  } finally {
+    client.close();
   }
-  const previous = knownSessions.get(session)?.webviewTabId;
-  if (previous) {
-    const byPrevious = webviews.find((tab) => tab.tabId === previous);
-    if (byPrevious) return byPrevious;
+}
+
+/** Resolve same-URL ambiguity: the candidate whose page carries this
+ * session's stamp wins. A unique candidate stands on its own. */
+async function confirmGuestCandidates(candidates, session) {
+  if (candidates.length <= 1) return candidates[0] || null;
+  for (const candidate of candidates) {
+    if (await readStamp(candidate.webSocketDebuggerUrl) === session) return candidate;
   }
   return null;
 }
 
 /**
- * Connect the session to the advertised chromium on first use and select the
- * in-tab webview target so commands drive the surface the user is looking at.
+ * Stamp the guest and keep the connection open. The on-new-document script
+ * lives exactly as long as this CDP session — which is exactly as long as
+ * the stamp should live: the connection drops when the target dies (webview
+ * remount, app restart), the surface record is dropped with it, and the next
+ * command re-attaches against the new reality.
+ */
+async function stampGuest(session, wsUrl) {
+  const client = await cdp.connectCdp(wsUrl);
+  try {
+    await client.call('Page.enable').catch(() => {});
+    await client.call('Page.addScriptToEvaluateOnNewDocument', { source: stampScript(session) });
+    await client.call('Runtime.evaluate', { expression: stampScript(session), returnByValue: true });
+  } catch (err) {
+    client.close();
+    throw err;
+  }
+  return client;
+}
+
+/**
+ * Chromium drops CDP Input events to an Electron <webview> guest until the
+ * guest widget has focus (verified live: clicks report success but never
+ * land). One focus pass over raw CDP — the embedder focuses the element, the
+ * guest focuses its window. Best-effort: reads work unfocused regardless.
+ */
+async function focusSurface(session, surface) {
+  try {
+    if (surface.embedderWsUrl) {
+      const embedder = await cdp.connectCdp(surface.embedderWsUrl);
+      try {
+        await embedder.call('Runtime.evaluate', {
+          expression: `(() => {
+            const view = [...document.querySelectorAll('webview')]
+              .find((w) => (w.getAttribute('data-amalgm-surface') || '').includes(${JSON.stringify(marker(session))}));
+            if (view) view.focus();
+            return Boolean(view);
+          })()`,
+          returnByValue: true,
+        });
+      } finally {
+        embedder.close();
+      }
+    }
+    await surface.client.call('Runtime.evaluate', { expression: 'window.focus()', returnByValue: true });
+  } catch {
+    // Snapshot/eval still work without focus; input may need a retry.
+  }
+}
+
+/**
+ * Connect the session to the advertised chromium on first use: select the
+ * in-tab webview in the daemon, stamp the guest over a persistent raw-CDP
+ * connection, focus it. The returned record is the session's one source of
+ * identity — commands verify against the stamp, captures connect to the
+ * target it names.
  */
 async function ensureReady(session, context) {
-  if (backend.mode() !== 'attached' || attachedSessions.has(session)) return;
+  if (backend.mode() !== 'attached') return null;
+  const live = surfaces.get(session);
+  if (live) return live;
+
+  // Explicit external CDP endpoints (plain chromium) have page targets, not
+  // webviews — drive whatever the daemon selected; no surface, no stamp.
+  if (process.env.AMALGM_BROWSER_CDP_URL) {
+    const targets = await cdp.listTargets(backend.cdpEndpoint()).catch(() => []);
+    if (!targets.some((t) => t.type === 'webview')) {
+      const external = { external: true, client: null, tabId: null, wsUrl: null };
+      surfaces.set(session, external);
+      return external;
+    }
+  }
 
   // The embedder DOM can identify the session's element even after it
   // navigated away from the marker URL (data-amalgm-surface survives where
-  // target URLs do not) — its live src re-keys the daemon's tab list.
+  // target URLs do not).
   const domSrc = async () => (await surfaceRect(session, ''))?.rect?.src || null;
+  const webviewTabs = async () => {
+    const tabs = await cli.runCli(['tab'], cliOptions(session, { timeoutMs: 15_000 }));
+    return (tabs?.data?.tabs || tabs?.tabs || []).filter((tab) => tab.type === 'webview');
+  };
 
-  let webviews = await listWebviewTabs(session);
-  let selected = matchWebview(webviews, session, await domSrc());
-
-  if (!selected) {
+  let candidates = identityCandidates(await webviewTabs(), session, await domSrc());
+  if (!candidates.length) {
     requestSurfaceOpen(session, context);
-    const deadline = Date.now() + WEBVIEW_WAIT_MS;
-    while (!selected && Date.now() < deadline) {
+    const deadlineAt = Date.now() + WEBVIEW_WAIT_MS;
+    while (!candidates.length && Date.now() < deadlineAt) {
       await new Promise((resolve) => setTimeout(resolve, WEBVIEW_POLL_MS));
-      webviews = await listWebviewTabs(session);
-      selected = matchWebview(webviews, session, await domSrc());
+      candidates = identityCandidates(await webviewTabs(), session, await domSrc());
     }
   }
 
-  if (!selected && webviews.length === 0 && process.env.AMALGM_BROWSER_CDP_URL) {
-    // Explicit external CDP endpoints (plain chromium) have page targets,
-    // not webviews — drive whatever the daemon selected by default.
-    attachedSessions.add(session);
-    return;
+  // Same-URL candidates are told apart by the stamp their pages carry from a
+  // previous attach: pin each in turn and read it back through the daemon.
+  let selected = candidates.length === 1 ? candidates[0] : null;
+  for (const candidate of candidates) {
+    if (selected) break;
+    await cli.runCli(['tab', candidate.tabId], cliOptions(session, { timeoutMs: 15_000 }));
+    const probe = await cli.runCli(['eval', 'window.__amalgmBsid || null'], cliOptions(session, { timeoutMs: 15_000 }))
+      .catch(() => null);
+    const stampValue = probe?.data?.result ?? probe?.result ?? null;
+    if (stampValue === session) selected = candidate;
   }
-
   if (!selected) {
     throw new Error(
       'Browser surface did not open in the desktop app. '
@@ -177,74 +277,81 @@ async function ensureReady(session, context) {
     );
   }
 
-  await cli.runCli(['tab', selected.tabId], cliOptions(session, { timeoutMs: 15_000 }));
-
   // The webview target existing is not enough — the splitview panel must be
   // on screen, or input drops and captures have nothing to render. (The app
   // window itself may be hidden or minimized; that no longer matters — the
   // app keeps an attached surface compositing wherever the window is.)
   const visible = await ensureSurfaceVisible(session, selected.url, context);
-  if (!visible) {
-    throw new Error(SURFACE_HIDDEN_MESSAGE);
-  }
+  if (!visible) throw new Error(SURFACE_HIDDEN_MESSAGE);
 
-  await focusWebviewHost(session, selected);
+  // Select the session's webview in the daemon — once. Refs don't exist yet,
+  // so this is the one place a `tab` command is allowed.
+  await cli.runCli(['tab', selected.tabId], cliOptions(session, { timeoutMs: 15_000 }));
+
+  // The guest's raw-CDP target, by the same identity as the daemon tab —
+  // stamp-confirmed when several webviews share the URL.
+  const guest = await confirmGuestCandidates(identityCandidates(
+    (await cdp.listTargets(backend.cdpEndpoint()))
+      .filter((t) => t.type === 'webview' && t.webSocketDebuggerUrl),
+    session,
+    visible.rect?.src || null,
+  ), session);
+  if (!guest) throw new Error(SURFACE_HIDDEN_MESSAGE);
+
+  const client = await stampGuest(session, guest.webSocketDebuggerUrl);
+  const surface = {
+    tabId: selected.tabId,
+    targetId: guest.id,
+    wsUrl: guest.webSocketDebuggerUrl,
+    embedderWsUrl: visible.pageWsUrl || null,
+    client,
+    external: false,
+  };
+  // The connection dropping IS the detach signal: webview remount, app
+  // restart, surface close — all of them invalidate this identity at once.
+  client.onClose(() => {
+    if (surfaces.get(session) === surface) surfaces.delete(session);
+  });
+  surfaces.set(session, surface);
   knownSessions.set(session, { ...knownSessions.get(session), webviewTabId: selected.tabId });
-  attachedSessions.add(session);
+
+  await focusSurface(session, surface);
+  return surface;
 }
 
-/**
- * Chromium drops CDP Input events to an Electron <webview> guest until the
- * guest widget has focus (verified live: clicks report success but never
- * land). One focus pass after target selection fixes input for the session:
- * focus the <webview> element from the embedder page, then self-focus the
- * guest. Best-effort — failures leave snapshot/eval working regardless.
- */
-async function focusWebviewHost(session, selected) {
-  const markerText = marker(session);
-  try {
-    const tabs = await cli.runCli(['tab'], cliOptions(session, { timeoutMs: 15_000 }));
-    const list = tabs?.data?.tabs || tabs?.tabs || [];
-    const outer = list.find((tab) => tab.type === 'page');
-    if (outer) {
-      const script = `(() => {
-        const views = [...document.querySelectorAll('webview')];
-        const target = views.find((w) => (w.getAttribute('src') || '').includes(${JSON.stringify(markerText)}))
-          || views.find((w) => (w.src || '') === ${JSON.stringify(String(selected.url || ''))})
-          || views[views.length - 1];
-        if (target) target.focus();
-        return views.length;
-      })()`;
-      await cli.runCli(['tab', outer.tabId], cliOptions(session, { timeoutMs: 15_000 }));
-      await cli.runCli(['eval', script], cliOptions(session, { timeoutMs: 15_000 }));
-      await cli.runCli(['tab', selected.tabId], cliOptions(session, { timeoutMs: 15_000 }));
-    }
-    await cli.runCli(['eval', 'window.focus()'], cliOptions(session, { timeoutMs: 15_000 }));
-  } catch {
-    // Snapshot/eval still work without focus; input may need a retry.
-  }
+function detach(session) {
+  const surface = surfaces.get(session);
+  surfaces.delete(session);
+  if (surface?.client) { try { surface.client.close(); } catch {} }
 }
 
 function looksLikeLostConnection(err) {
-  return /clos|connect|target|socket|detach/i.test(String(err?.message || err || ''));
+  const message = String(err?.message || err || '');
+  return message.includes(GUARD_ERROR) || /clos|connect|target|socket|detach/i.test(message);
 }
 
 /**
- * A failed batch can surface two ways: a success envelope whose entries
- * carry per-step failures, or an envelope-level rejection whose message is
- * the serialized entries. Either way, when the failing step is the tab pin,
- * reclassify it as a lost surface target so the retry path re-attaches —
- * the raw "Tab tN not found" would otherwise read as a page error.
+ * Reduce a failed batch to the step that failed. agent-browser reports batch
+ * failures two ways — a rejection whose message is the serialized entries, or
+ * a success envelope with per-entry failures — and the serialized form
+ * contains every command's source text, including the guard's. Classify by
+ * the failing entry's error, never by the blob: a failing guard step means
+ * the daemon is not on this session's page (re-attach); anything else is
+ * that step's own error, reported by name.
  */
-function pinFailure(err, pin) {
-  if (!pin) return err;
+function batchFailure(failedEntry, guarded) {
+  const stepError = String(failedEntry?.error || 'failed');
+  if (guarded && stepError.includes(GUARD_ERROR)) {
+    return new Error(`surface target lost (${GUARD_ERROR})`);
+  }
+  return new Error(`${(failedEntry?.command || []).join(' ')}: ${stepError}`);
+}
+
+function thrownBatchFailure(err, guarded) {
   try {
     const entries = JSON.parse(String(err?.message || ''));
-    const failedPin = Array.isArray(entries) && entries.find((entry) => entry
-      && Array.isArray(entry.command) && entry.command[0] === 'tab' && entry.error);
-    if (failedPin) {
-      return new Error(`surface target lost (${failedPin.command.join(' ')}: ${failedPin.error})`);
-    }
+    const failed = Array.isArray(entries) && entries.find((entry) => entry && entry.success === false);
+    if (failed) return batchFailure(failed, guarded);
   } catch {
     // Not a serialized batch — leave the error as-is.
   }
@@ -253,18 +360,18 @@ function pinFailure(err, pin) {
 
 /**
  * Execute commands against the session's browser, re-attaching once on a
- * lost connection. In attached mode the session's webview target id is
- * re-asserted as a `tab` step inside the same batch, so every command runs
- * against the verified surface — never a daemon-side fallback. A dead pin
- * throws "surface target lost", which the retry path treats as a remount.
+ * lost surface. In attached mode every batch leads with the stamp guard —
+ * the daemon driving any page but this session's fails the batch before the
+ * action runs, instead of acting on the wrong page. The guard is an eval, so
+ * snapshot @refs survive across calls.
  */
 async function execute(session, commands, options = {}, single) {
   const { context, ...cliExtra } = options;
-  await ensureReady(session, context);
+  const surface = await ensureReady(session, context);
+  const guarded = Boolean(surface) && !surface.external;
 
   const attempt = async () => {
-    const pin = backend.mode() === 'attached' ? knownSessions.get(session)?.webviewTabId : null;
-    const batchCommands = pin ? [['tab', pin], ...commands] : commands;
+    const batchCommands = guarded ? [guardCommand(session), ...commands] : commands;
     if (batchCommands.length === 1 && single) {
       return cli.runCli(batchCommands[0], cliOptions(session, cliExtra));
     }
@@ -275,26 +382,23 @@ async function execute(session, commands, options = {}, single) {
         stdin: JSON.stringify(batchCommands.map((command) => command.map(String))),
       }));
     } catch (err) {
-      throw pinFailure(err, pin);
+      throw thrownBatchFailure(err, guarded);
     }
     let entries = Array.isArray(result) ? result : (result?.data || []);
     if (!Array.isArray(entries)) entries = [];
     const failed = entries.find((entry) => entry && entry.success === false);
-    if (failed) {
-      const message = `${(failed.command || []).join(' ')}: ${failed.error || 'failed'}`;
-      const pinFailed = pin && Array.isArray(failed.command) && failed.command[0] === 'tab';
-      throw new Error(pinFailed ? `surface target lost (${message})` : message);
-    }
-    if (pin) entries = entries.slice(1);
+    if (failed) throw batchFailure(failed, guarded);
+    if (guarded) entries = entries.slice(1);
     return single ? { success: true, data: entries[0]?.result } : entries;
   };
 
   try {
     return await attempt();
   } catch (err) {
-    if (backend.mode() === 'attached' && attachedSessions.has(session) && looksLikeLostConnection(err)) {
-      // The app restarted or the webview remounted; re-attach once.
-      attachedSessions.delete(session);
+    if (guarded && looksLikeLostConnection(err)) {
+      // The app restarted, the webview remounted, or the daemon drifted off
+      // this session's page; re-attach once against current reality.
+      detach(session);
       await ensureReady(session, context);
       return attempt();
     }
@@ -322,57 +426,20 @@ async function readText(session, commandArgs, timeoutMs) {
 }
 
 /**
- * The CDP target of this session's <webview>, for raster capture. Requires
- * the surface on screen (the one physical precondition for guest pixels) —
- * ensureSurfaceVisible self-heals a backgrounded tab first. Identity:
- * marker in the target url/title, else the live src the embedder DOM
- * reports for the session's marked element. When several webviews share
- * that url, a nonce planted through the session's own (pinned) daemon picks
- * the right one — never a guess.
+ * The CDP websocket url for raster capture — the surface's own guest target,
+ * established at attach. Requires the surface on screen (the one physical
+ * precondition for guest pixels); ensureSurfaceVisible self-heals a
+ * backgrounded tab first. Null for external plain-chromium endpoints.
  */
-async function guestTarget(session, context) {
-  const surface = await ensureSurfaceVisible(session, '', context);
-  if (!surface) throw new Error(SURFACE_HIDDEN_MESSAGE);
-
-  const markerText = marker(session);
-  const targets = await cdp.listTargets(backend.cdpEndpoint());
-  const webviews = targets.filter((t) => t.type === 'webview' && t.webSocketDebuggerUrl);
-
-  let candidates = webviews.filter((t) => String(t.url || '').includes(markerText)
-    || String(t.title || '').includes(markerText));
-  if (!candidates.length && surface.rect?.src) {
-    candidates = webviews.filter((t) => String(t.url || '') === surface.rect.src);
-  }
-  if (candidates.length > 1) candidates = await confirmGuestsByNonce(session, candidates, context);
-  if (candidates.length !== 1) {
-    throw new Error(
-      'Could not identify this session\'s browser surface among the app\'s webviews. '
-      + 'Close this browser session and open again (a fresh surface will mount).',
-    );
-  }
-  return candidates[0];
-}
-
-async function confirmGuestsByNonce(session, candidates, context) {
-  const nonce = `amalgm-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
-  await run(session, ['eval', `void (window.__amalgmSurfaceNonce = ${JSON.stringify(nonce)})`], { context });
-  const confirmed = [];
-  for (const candidate of candidates) {
-    const client = await cdp.connectCdp(candidate.webSocketDebuggerUrl).catch(() => null);
-    if (!client) continue;
-    try {
-      const { result } = await client.call('Runtime.evaluate', {
-        expression: 'window.__amalgmSurfaceNonce || null',
-        returnByValue: true,
-      }, 3_000);
-      if (result && result.value === nonce) confirmed.push(candidate);
-    } catch {
-      // Unreadable candidate — not ours.
-    } finally {
-      client.close();
-    }
-  }
-  return confirmed;
+async function guestWsUrl(session, context) {
+  let surface = await ensureReady(session, context);
+  if (surface?.external) return null;
+  const visible = await ensureSurfaceVisible(session, '', context);
+  if (!visible) throw new Error(SURFACE_HIDDEN_MESSAGE);
+  // The target may have died between ensureReady and now — the close handler
+  // clears the record, so a second look re-attaches against the new target.
+  surface = surfaces.get(session) || await ensureReady(session, context);
+  return surface.wsUrl;
 }
 
 /**
@@ -396,19 +463,22 @@ function requestSurfaceClose(session) {
 }
 
 module.exports = {
+  GUARD_ERROR,
   SURFACE_EVENT_RESOURCE,
   SURFACE_HIDDEN_MESSAGE,
   WEBVIEW_MARKER_PREFIX,
   cliOptions,
+  detach,
   ensureReady,
   ensureSurfaceVisible,
-  guestTarget,
+  guardCommand,
+  guestWsUrl,
   looksLikeLostConnection,
   marker,
-  matchWebview,
-  pinFailure,
+  identityCandidates,
   readText,
   requestSurfaceClose,
+  thrownBatchFailure,
   requestSurfaceOpen,
   run,
   runBatch,

package/runtime/scripts/amalgm-mcp/browser/capture.js

@@ -5,7 +5,10 @@
  *
  * Pixels come straight from the session's own page:
  *  - cli (headless) sessions capture their page target;
- *  - attached sessions capture the <webview> guest target itself.
+ *  - attached sessions capture the <webview> guest target whose identity was
+ *    established at attach (attach.guestWsUrl) — never a target-list hunt,
+ *    never a "first page target" fallback (that fallback is how
+ *    cua_screenshot once returned the app's own chat UI).
  *
  * The one physical law (verified live in all four states): a guest rasters
  * iff its <webview> is composited on-screen in the app's layout. The app
@@ -15,13 +18,6 @@
  * ensureSurfaceVisible self-heals that by asking the UI to refocus the
  * surface tab before any capture is attempted.
  *
- * History: an earlier revision captured the app window clipped to the
- * webview rectangle, believing guests could not raster at all. That belief
- * came from probing panel-hidden guests, and the clip math corrupted frames
- * whenever the splitview rect moved mid-animation. Guest-direct capture has
- * no rect math to get wrong and returns exactly the page — never the app
- * around it — in both screenshots and recordings.
- *
  * Every exchange carries a hard deadline (cdp.js): a capture may fail, it
  * can never wedge a session.
  */
@@ -42,6 +38,13 @@ async function daemonCdpUrl(session) {
   return result?.data?.cdpUrl || result?.cdpUrl || null;
 }
 
+/** First capturable page target on a CDP endpoint (browser-level url or port). */
+async function pageTargetWsUrl(endpoint) {
+  const page = cdp.pageTargets(await cdp.listTargets(endpoint))[0];
+  if (!page) throw new Error('No capturable page target on the CDP endpoint.');
+  return page.webSocketDebuggerUrl;
+}
+
 /**
  * Where to capture from for this session:
  *   { wsUrl, guest } — guest marks an attached <webview> target, whose output
@@ -51,32 +54,16 @@ async function plan(session, context) {
   if (backend.mode() !== 'attached') {
     const raw = await daemonCdpUrl(session);
     if (!raw) throw new Error('Could not resolve a CDP endpoint for this browser session.');
-    let wsUrl = raw;
-    if (/\/devtools\/browser\//.test(raw)) {
-      const page = cdp.pageTargets(await cdp.listTargets(raw))[0];
-      if (!page) throw new Error('No capturable page target on the browser endpoint.');
-      wsUrl = page.webSocketDebuggerUrl;
-    }
+    const wsUrl = /\/devtools\/browser\//.test(raw) ? await pageTargetWsUrl(raw) : raw;
     return { wsUrl, guest: false };
   }
 
-  await attach.ensureReady(session, context);
-  const endpoint = backend.cdpEndpoint();
-  const targets = await cdp.listTargets(endpoint);
-
-  if (!targets.some((t) => t.type === 'webview')) {
-    // Explicit external CDP endpoint (plain chromium): capture the driven
-    // page directly.
-    const page = cdp.pageTargets(targets)[0];
-    if (!page) throw new Error('No capturable page target on the CDP endpoint.');
-    return { wsUrl: page.webSocketDebuggerUrl, guest: false };
-  }
-
-  // Desktop app: capture this session's own webview target. The surface tab
-  // must be on screen for the guest to raster — ask the UI to refocus it
-  // (self-heal) rather than failing on a backgrounded panel.
-  const target = await attach.guestTarget(session, context);
-  return { wsUrl: target.webSocketDebuggerUrl, guest: true };
+  // Desktop app: the session's own webview guest, identity from attach.
+  // Null only for explicit external CDP endpoints (plain chromium) — there
+  // the driven page is the capture source.
+  const wsUrl = await attach.guestWsUrl(session, context);
+  if (wsUrl) return { wsUrl, guest: true };
+  return { wsUrl: await pageTargetWsUrl(backend.cdpEndpoint()), guest: false };
 }
 
 /** Why a guest capture starved, in words an agent can act on. */
@@ -119,6 +106,35 @@ async function assertCapturable(client, source) {
   }
 }
 
+/**
+ * Electron <webview> guests raster over a transparent base, so a page
+ * without its own background captures with alpha — which viewers and
+ * encoders composite as black. (CDP's background override is a no-op on
+ * guests; verified live.) Flatten guest PNGs onto white with the bundled
+ * ffmpeg — the pixels are intact under the alpha. Headless page targets
+ * raster opaque and skip this entirely.
+ */
+function flattenPng(buffer) {
+  const { spawn } = require('child_process');
+  return cdp.deadline(new Promise((resolve) => {
+    const child = spawn(cli.ffmpegBinary(), [
+      '-y', '-f', 'image2pipe', '-c:v', 'png', '-i', 'pipe:0',
+      '-filter_complex', '[0:v]format=rgba,split[fg1][fg2];[fg1]drawbox=color=white:t=fill[bg];'
+        + '[bg][fg2]overlay=format=auto,format=rgb24',
+      '-frames:v', '1', '-f', 'image2pipe', '-c:v', 'png', 'pipe:1',
+    ], { stdio: ['pipe', 'pipe', 'ignore'] });
+    const chunks = [];
+    child.stdout.on('data', (chunk) => chunks.push(chunk));
+    child.on('error', () => resolve(buffer)); // no ffmpeg — alpha beats no image
+    child.on('close', (code) => {
+      const out = Buffer.concat(chunks);
+      resolve(code === 0 && out.length ? out : buffer);
+    });
+    child.stdin.on('error', () => {});
+    child.stdin.end(buffer);
+  }), 10_000, 'screenshot flatten').catch(() => buffer);
+}
+
 async function screenshot(session, args = {}, context) {
   const fullPage = Boolean(args.fullPage);
   const source = await plan(session, context);
@@ -154,9 +170,12 @@ async function screenshot(session, args = {}, context) {
       throw err;
     }
     if (!data) throw new Error('Empty screenshot response');
+    const image = source.guest
+      ? await flattenPng(Buffer.from(data, 'base64'))
+      : Buffer.from(data, 'base64');
     return {
-      base64: data,
-      bytes: Buffer.byteLength(data, 'base64'),
+      base64: image.toString('base64'),
+      bytes: image.length,
       mode: source.guest ? 'visible surface' : (fullPage ? 'full page' : 'viewport'),
     };
   } finally {
@@ -169,6 +188,7 @@ module.exports = {
   connectCdp: cdp.connectCdp,
   cssViewportClip,
   deadline: cdp.deadline,
+  flattenPng,
   listTargets: cdp.listTargets,
   pageTargets: cdp.pageTargets,
   plan,

package/runtime/scripts/amalgm-mcp/browser/cdp.js

@@ -57,9 +57,11 @@ async function connectCdp(wsUrl) {
     }
     if (msg.method && listeners.has(msg.method)) listeners.get(msg.method)(msg.params || {});
   });
+  const closeHandlers = [];
   ws.on('close', () => {
     for (const entry of pending.values()) entry.reject(new Error('CDP connection closed'));
     pending.clear();
+    for (const handler of closeHandlers.splice(0)) { try { handler(); } catch {} }
   });
   ws.on('error', () => {});
 
@@ -80,6 +82,7 @@ async function connectCdp(wsUrl) {
       try { ws.send(JSON.stringify({ id: ++nextId, method, params })); } catch {}
     },
     on(method, handler) { listeners.set(method, handler); },
+    onClose(handler) { closeHandlers.push(handler); },
     close() { try { ws.close(); } catch {} },
   };
 }

package/runtime/scripts/amalgm-mcp/browser/cli.js

@@ -60,12 +60,18 @@ function socketDir() {
   return ensureDir(path.join(os.tmpdir(), 'amalgm-ab'));
 }
 
-function ffmpegDir() {
+function ffmpegBinary() {
+  if (process.env.AMALGM_FFMPEG) return process.env.AMALGM_FFMPEG;
   try {
     const resolved = require('ffmpeg-static');
-    if (resolved && fs.existsSync(resolved)) return path.dirname(resolved);
+    if (resolved && fs.existsSync(resolved)) return resolved;
   } catch {}
-  return null;
+  return 'ffmpeg';
+}
+
+function ffmpegDir() {
+  const binary = ffmpegBinary();
+  return binary === 'ffmpeg' ? null : path.dirname(binary);
 }
 
 /**
@@ -235,6 +241,7 @@ module.exports = {
   asText,
   browserRoot,
   ensureDir,
+  ffmpegBinary,
   ffmpegDir,
   profileDir,
   readText,

package/runtime/scripts/amalgm-mcp/browser/engine.js

@@ -317,10 +317,10 @@ async function close(args = {}, context) {
   // Tell the UI to unmount the splitview/tab. Each surface is a full
   // renderer process; ended sessions must not accumulate them (ten zombie
   // webviews were live in the app when this was written).
-  if (sessions.attachedSessions.has(session) || sessions.knownSessions.has(session)) {
+  if (sessions.surfaces.has(session) || sessions.knownSessions.has(session)) {
     attach.requestSurfaceClose(session);
   }
-  sessions.attachedSessions.delete(session);
+  attach.detach(session);
   sessions.knownSessions.delete(session);
 }
 

package/runtime/scripts/amalgm-mcp/browser/recorder-tools.js

@@ -50,7 +50,7 @@ module.exports = [
           content: [{
             type: 'text',
             text: `Recording saved: ${result.path}\n`
-              + `${result.frames} frames @ ${result.fps} fps, ${Math.round(result.durationMs / 1000)}s, ${result.bytes} bytes`
+              + `${result.frames} frames @ ${result.fps} fps — ${result.videoSeconds}s of video over ${result.wallSeconds}s, ${result.bytes} bytes`
               + (result.warning ? `\nWarning: ${result.warning}` : ''),
           }],
           metadata: {

package/runtime/scripts/amalgm-mcp/browser/recorder.js

@@ -89,15 +89,6 @@ function createSampler({ fps, write }) {
   return sampler;
 }
 
-function ffmpegBinary() {
-  if (process.env.AMALGM_FFMPEG) return process.env.AMALGM_FFMPEG;
-  try {
-    const resolved = require('ffmpeg-static');
-    if (resolved && fs.existsSync(resolved)) return resolved;
-  } catch {}
-  return 'ffmpeg';
-}
-
 let verifiedBinary = null;
 
 /**
@@ -109,7 +100,7 @@ let verifiedBinary = null;
  * server and every session's tools with it.
  */
 function ensureFfmpeg() {
-  const binary = ffmpegBinary();
+  const binary = cli.ffmpegBinary();
   if (binary === verifiedBinary) return binary;
   const probe = require('child_process').spawnSync(binary, ['-version'], { stdio: 'ignore', timeout: 10_000 });
   if (probe.error || probe.status !== 0) {
@@ -152,8 +143,8 @@ function recordingFile(args, context, session) {
 
 function ffmpegArgs({ fps, filters, file }) {
   return [
-    '-y', '-f', 'image2pipe', '-c:v', 'mjpeg', '-framerate', String(fps), '-i', 'pipe:0',
-    '-vf', filters,
+    '-y', '-f', 'image2pipe', '-c:v', 'png', '-framerate', String(fps), '-i', 'pipe:0',
+    '-filter_complex', filters,
     '-c:v', 'libvpx',
     '-deadline', 'realtime',
     '-cpu-used', '8',
@@ -161,7 +152,6 @@ function ffmpegArgs({ fps, filters, file }) {
     '-auto-alt-ref', '0',
     '-threads', '4',
     '-b:v', '1M',
-    '-pix_fmt', 'yuv420p',
     file,
   ];
 }
@@ -182,8 +172,13 @@ async function start(args = {}, context = {}) {
 
   const file = recordingFile(args, context, session);
   const fps = clampFps(args.fps);
-  // VP8 wants even dimensions; screencast frames can be odd-sized.
-  const filters = 'pad=ceil(iw/2)*2:ceil(ih/2)*2';
+  // Frames arrive as PNG with alpha: Electron <webview> guests raster over a
+  // transparent base, so a page without its own background would encode as
+  // black. Composite every frame onto white before the encoder sees it
+  // (opaque headless frames pass through unchanged), then pad to the even
+  // dimensions VP8 wants.
+  const filters = '[0:v]format=rgba,split[fg1][fg2];[fg1]drawbox=color=white:t=fill[bg];'
+    + '[bg][fg2]overlay=format=auto,pad=ceil(iw/2)*2:ceil(ih/2)*2,format=yuv420p';
 
   const ffmpeg = spawn(binary, ffmpegArgs({ fps, filters, file }), { stdio: ['pipe', 'ignore', 'pipe'] });
   let ffmpegErr = '';
@@ -230,12 +225,13 @@ async function start(args = {}, context = {}) {
     // A surface that cannot produce one pixel now will not produce a stream
     // either — refuse at start with the reason, not at stop with an empty file.
     await capture.assertCapturable(recording.cdp, source);
+
     recording.cdp.on('Page.screencastFrame', (params) => {
       recording.sampler.push(Buffer.from(params.data, 'base64'));
       recording.cdp.send('Page.screencastFrameAck', { sessionId: params.sessionId });
     });
     await recording.cdp.call('Page.enable').catch(() => {});
-    await recording.cdp.call('Page.startScreencast', { format: 'jpeg', quality: 70, everyNthFrame: 1 });
+    await recording.cdp.call('Page.startScreencast', { format: 'png', everyNthFrame: 1 });
     recording.sampler.start();
   } catch (err) {
     recording.sampler.stop();

package/runtime/scripts/amalgm-mcp/browser/sessions.js

@@ -12,8 +12,13 @@
 const cli = require('./cli');
 const backend = require('./backend');
 
-/** Sessions that completed the attached-mode handshake (webview selected + focused). */
-const attachedSessions = new Set();
+/**
+ * Attached surfaces: session -> { tabId, targetId, wsUrl, embedderWsUrl,
+ * client, external }. An entry exists exactly while its guest CDP connection
+ * is open — the connection's close handler removes it, so presence means
+ * live. attach.js owns the lifecycle.
+ */
+const surfaces = new Map();
 
 /** Per-session bookkeeping: webviewTabId, lastActiveAt, last url/title. */
 const knownSessions = new Map();
@@ -56,9 +61,9 @@ function sessionInfo(session, extra = {}) {
 }
 
 module.exports = {
-  attachedSessions,
   knownSessions,
   rememberProfile,
   sessionFor,
   sessionInfo,
+  surfaces,
 };

package/runtime/scripts/amalgm-mcp/tests/browser-recorder.test.js

@@ -91,10 +91,14 @@ test('sampler skips ticks under encoder backpressure and resumes on drain', () =
   assert.equal(sampler.stats.encoded, 2);
 });
 
-test('recording encoder uses realtime VP8 settings', () => {
+test('recording encoder uses realtime VP8 settings on PNG frames', () => {
   const { _test } = require('../browser/recorder');
-  const args = _test.ffmpegArgs({ fps: 12, filters: 'pad=ceil(iw/2)*2:ceil(ih/2)*2', file: '/tmp/out.webm' });
+  const args = _test.ffmpegArgs({ fps: 12, filters: 'null', file: '/tmp/out.webm' });
 
+  // PNG input keeps the alpha channel so the white underlay in the
+  // filtergraph can composite it (guests raster transparent backgrounds).
+  assert.equal(args[args.indexOf('-c:v') + 1], 'png');
+  assert.ok(args.includes('-filter_complex'));
   assert.ok(args.includes('-deadline'));
   assert.equal(args[args.indexOf('-deadline') + 1], 'realtime');
   assert.ok(args.includes('-cpu-used'));

package/runtime/scripts/amalgm-mcp/tests/browser-routing.test.js

@@ -138,28 +138,27 @@ test('entrypoint routing: candidate order is state dir, derived label dir, AMALG
 // a chat-tab switch) fell back to "the only webview" — someone else's.
 // ---------------------------------------------------------------------------
 
-test('surface routing: marker, embedder DOM src, then previously selected tab', () => {
+test('surface routing: marker first, then the embedder DOM src as candidates', () => {
   const attach = require('../browser/attach');
-  const { knownSessions } = require('../browser/sessions');
 
   const fresh = { tabId: 't2', type: 'webview', url: 'about:blank#amalgm-bsid-s1' };
   const navigated = { tabId: 't3', type: 'webview', url: 'https://example.com/' };
+  const twin = { tabId: 't5', type: 'webview', url: 'https://example.com/' };
   const other = { tabId: 't4', type: 'webview', url: 'https://other.test/' };
 
-  // Fresh surface: the marker URL identifies it.
-  assert.equal(attach.matchWebview([other, fresh], 's1', null), fresh);
+  // Fresh surface: the marker URL identifies it exactly.
+  assert.deepEqual(attach.identityCandidates([other, fresh], 's1', null), [fresh]);
 
   // Navigated surface: the embedder DOM (data-amalgm-surface element) reports
   // its live src — that re-keys the daemon's tab list after an MCP restart.
-  assert.equal(attach.matchWebview([other, navigated], 's1', 'https://example.com/'), navigated);
+  assert.deepEqual(attach.identityCandidates([other, navigated], 's1', 'https://example.com/'), [navigated]);
 
-  // Same surface, no DOM hint, but selected earlier in this process.
-  knownSessions.set('s1', { webviewTabId: 't3' });
-  try {
-    assert.equal(attach.matchWebview([other, navigated], 's1', null), navigated);
-  } finally {
-    knownSessions.delete('s1');
-  }
+  // Two sessions on the same URL: both are candidates — ensureReady confirms
+  // the right one by the stamp its page carries, never by list order.
+  assert.deepEqual(
+    attach.identityCandidates([other, navigated, twin], 's1', 'https://example.com/'),
+    [navigated, twin],
+  );
 });
 
 test('surface routing: an unidentified lone webview is never adopted', () => {
@@ -167,6 +166,6 @@ test('surface routing: an unidentified lone webview is never adopted', () => {
   // One webview left and it is not provably ours — that is the cross-chat
   // leak shape. Fail closed; ensureReady reopens a marked surface instead.
   const stranger = { tabId: 't9', type: 'webview', url: 'https://another-chats-page.test/' };
-  assert.equal(attach.matchWebview([stranger], 'displaced-session', null), null);
-  assert.equal(attach.matchWebview([], 'displaced-session', null), null);
+  assert.deepEqual(attach.identityCandidates([stranger], 'displaced-session', null), []);
+  assert.deepEqual(attach.identityCandidates([], 'displaced-session', null), []);
 });

package/runtime/scripts/amalgm-mcp/tests/browser-transport.test.js

@@ -3,14 +3,17 @@
 const assert = require('node:assert/strict');
 const test = require('node:test');
 
-// Transport semantics introduced after the 2026-06-11 stress tests: in
-// attached mode every command re-pins the session's webview target inside
-// the same batch. The daemon's tab selection is process state that silently
-// falls back to "the active tab" when the selected target dies — that
-// fallback is how one session read another session's page.
+// Transport semantics: in attached mode a session's identity is established
+// once at attach (daemon tab selection + a stamp on the guest document) and
+// VERIFIED on every command by a guard eval leading the batch. The previous
+// design re-pinned with a `tab` step per batch — but `tab` resets the
+// daemon's snapshot ref table (verified live, even re-selecting the same
+// tab), which broke the documented snapshot → click @ref flow. eval does not
+// touch refs, so the guard keeps them alive across calls while still failing
+// closed when the daemon drifts onto another page.
 
 const attach = require('../browser/attach');
-const { attachedSessions, knownSessions } = require('../browser/sessions');
+const { surfaces, knownSessions } = require('../browser/sessions');
 
 // Patch attach.run before engine destructures it (engine binds at require).
 const calls = [];
@@ -75,15 +78,15 @@ test('passthrough refuses tab hops in attached mode, allows listing', async () =
   }
 });
 
-// The pin itself: execute() turns every attached call into a batch that
-// re-selects the session's webview first, and maps the single-command result
-// back to its unbatched shape.
+// The guard itself: execute() turns every attached call into a batch that
+// leads with the stamp-check eval, and maps the single-command result back to
+// its unbatched shape. The guard never appears in caller-visible results.
 
-test('attached commands re-pin the webview target inside the batch', async (t) => {
+test('attached commands lead with the guard eval inside the batch', async (t) => {
   const fs = require('node:fs');
   const os = require('node:os');
   const path = require('node:path');
-  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'amalgm-pin-test-'));
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'amalgm-guard-test-'));
   const stub = path.join(dir, 'stub.sh');
   // The stub answers `batch` by echoing stdin back as batch entries.
   fs.writeFileSync(stub, `#!/bin/sh
@@ -100,18 +103,19 @@ console.log(JSON.stringify({ success: true, data: cmds.map((c) => ({ command: c,
   process.env.AMALGM_AGENT_BROWSER_BIN = stub;
   process.env.AMALGM_BROWSER_BACKEND = 'attached';
   process.env.AMALGM_BROWSER_CDP_URL = '9242';
-  attachedSessions.add('pin-test');
-  knownSessions.set('pin-test', { webviewTabId: 't7' });
+  // A live surface record makes ensureReady a no-op and turns the guard on.
+  surfaces.set('guard-test', { tabId: 't7', wsUrl: 'ws://x/guest', client: { close() {} }, external: false });
+  knownSessions.set('guard-test', { webviewTabId: 't7' });
   try {
-    const single = await attach.run('pin-test', ['get', 'url'], { timeoutMs: 5000 });
+    const single = await attach.run('guard-test', ['get', 'url'], { timeoutMs: 5000 });
     assert.deepEqual(single.data, { echoed: ['get', 'url'] }, 'single result keeps its unbatched shape');
 
-    const entries = await attach.runBatch('pin-test', [['open', 'https://example.com'], ['get', 'url']], { timeoutMs: 5000 });
-    assert.equal(entries.length, 2, 'the pin step is internal — callers see their own commands only');
+    const entries = await attach.runBatch('guard-test', [['open', 'https://example.com'], ['get', 'url']], { timeoutMs: 5000 });
+    assert.equal(entries.length, 2, 'the guard step is internal — callers see their own commands only');
     assert.deepEqual(entries[0].command, ['open', 'https://example.com']);
   } finally {
-    attachedSessions.delete('pin-test');
-    knownSessions.delete('pin-test');
+    surfaces.delete('guard-test');
+    knownSessions.delete('guard-test');
     if (savedBin === undefined) delete process.env.AMALGM_AGENT_BROWSER_BIN; else process.env.AMALGM_AGENT_BROWSER_BIN = savedBin;
     if (savedBackend === undefined) delete process.env.AMALGM_BROWSER_BACKEND; else process.env.AMALGM_BROWSER_BACKEND = savedBackend;
     if (savedCdp === undefined) delete process.env.AMALGM_BROWSER_CDP_URL; else process.env.AMALGM_BROWSER_CDP_URL = savedCdp;
@@ -119,37 +123,42 @@ console.log(JSON.stringify({ success: true, data: cmds.map((c) => ({ command: c,
   }
 });
 
-test('a dead pin is classified as a lost target; page errors are not', () => {
-  // The pin failure carries the "surface target lost" prefix so the retry
-  // path re-attaches. Ordinary page errors must NOT look like lost
-  // connections — a spurious re-attach on "Element not found" would tear
-  // down and rebuild the surface on every typo'd selector.
-  assert.equal(attach.looksLikeLostConnection(new Error('surface target lost (tab t7: tab not found)')), true);
+test('a guard failure is classified as a lost target; page errors are not', () => {
+  // Guard failures and dead connections re-attach. Ordinary page errors must
+  // NOT look like lost connections — a spurious re-attach on "Element not
+  // found" would tear down and rebuild the surface on every typo'd selector.
+  assert.equal(attach.looksLikeLostConnection(new Error(`surface target lost (${attach.GUARD_ERROR})`)), true);
   assert.equal(attach.looksLikeLostConnection(new Error('WebSocket connection closed')), true);
   assert.equal(attach.looksLikeLostConnection(new Error('Element not found: #submit')), false);
   assert.equal(attach.looksLikeLostConnection(new Error('Timed out waiting for selector')), false);
 });
 
-test('pinFailure reclassifies envelope-level batch rejections', () => {
+test('batch failures classify by the failing step, never by the serialized blob', () => {
   // agent-browser --bail rejects with the serialized entries as the message
-  // (live-verified shape). A failed pin step inside must become "surface
-  // target lost" so the retry path re-attaches.
-  const envelope = new Error(JSON.stringify([
-    { command: ['tab', 't16'], error: 'Tab t16 not found; run `agent-browser tab` to list open tabs', result: null },
+  // (live-verified shape) — and that serialization contains the guard
+  // command's own source text. Only a guard step that actually FAILED may
+  // re-attach; any other failing step is that step's own error.
+  const guard = attach.guardCommand('s1');
+
+  const guardFailed = new Error(JSON.stringify([
+    { command: guard, error: `Evaluation error: Error: ${attach.GUARD_ERROR}\n    at <anonymous>:1:54`, result: null, success: false },
   ]));
-  const classified = attach.pinFailure(envelope, 't16');
+  const classified = attach.thrownBatchFailure(guardFailed, true);
   assert.match(classified.message, /surface target lost/);
   assert.equal(attach.looksLikeLostConnection(classified), true);
 
-  // A failing page step inside the same shape stays a page error.
-  const pageError = new Error(JSON.stringify([
-    { command: ['tab', 't16'], error: null, result: { ok: true } },
-    { command: ['click', '#gone'], error: 'Element not found', result: null },
+  // A failing page step after a PASSING guard stays a page error — even
+  // though the blob contains the guard text.
+  const pageFailed = new Error(JSON.stringify([
+    { command: guard, error: null, result: { result: null }, success: true },
+    { command: ['eval', 'return 21 * 2'], error: 'Evaluation error: SyntaxError: Illegal return statement', result: null, success: false },
   ]));
-  assert.equal(attach.pinFailure(pageError, 't16'), pageError);
+  const page = attach.thrownBatchFailure(pageFailed, true);
+  assert.match(page.message, /Illegal return statement/);
+  assert.doesNotMatch(page.message, /surface target lost/);
+  assert.equal(attach.looksLikeLostConnection(page), false);
 
-  // Headless (no pin) and non-JSON messages pass through untouched.
+  // Non-JSON messages pass through untouched.
   const plain = new Error('agent-browser exited with code 1');
-  assert.equal(attach.pinFailure(plain, null), plain);
-  assert.equal(attach.pinFailure(plain, 't16'), plain);
+  assert.equal(attach.thrownBatchFailure(plain, true), plain);
 });