amalgm 0.1.92 → 0.1.93

package/package.json

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

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

@@ -102,17 +102,30 @@ async function ensureSurfaceVisible(session, hintUrl, context, waitMs = WEBVIEW_
   return null;
 }
 
-function matchWebview(webviews, session) {
+/**
+ * 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.
+ */
+function matchWebview(webviews, 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 previous = knownSessions.get(session)?.webviewTabId;
   if (previous) {
     const byPrevious = webviews.find((tab) => tab.tabId === previous);
     if (byPrevious) return byPrevious;
   }
-  if (webviews.length === 1) return webviews[0];
   return null;
 }
 
@@ -123,8 +136,13 @@ function matchWebview(webviews, session) {
 async function ensureReady(session, context) {
   if (backend.mode() !== 'attached' || attachedSessions.has(session)) return;
 
+  // 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.
+  const domSrc = async () => (await surfaceRect(session, ''))?.rect?.src || null;
+
   let webviews = await listWebviewTabs(session);
-  let selected = matchWebview(webviews, session);
+  let selected = matchWebview(webviews, session, await domSrc());
 
   if (!selected) {
     requestSurfaceOpen(session, context);
@@ -132,7 +150,7 @@ async function ensureReady(session, context) {
     while (!selected && Date.now() < deadline) {
       await new Promise((resolve) => setTimeout(resolve, WEBVIEW_POLL_MS));
       webviews = await listWebviewTabs(session);
-      selected = matchWebview(webviews, session);
+      selected = matchWebview(webviews, session, await domSrc());
     }
   }
 
@@ -146,7 +164,8 @@ async function ensureReady(session, context) {
   if (!selected) {
     throw new Error(
       'Browser surface did not open in the desktop app. '
-      + 'Retry, or force a headless browser with AMALGM_BROWSER_BACKEND=cli.',
+      + '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.',
     );
   }
 
@@ -219,6 +238,26 @@ async function run(session, commandArgs, options = {}) {
   }
 }
 
+/**
+ * Several commands, one daemon round trip — composites (mouse click = move +
+ * down + up) cost one process spawn instead of three. Commands go as JSON on
+ * stdin (argv-quoting of nested commands is how arguments get eaten).
+ * --bail: a failed step fails the batch; its error is thrown with the step
+ * named. Returns the per-command result array.
+ */
+async function runBatch(session, commands, options = {}) {
+  const result = await run(session, ['batch', '--bail'], {
+    ...options,
+    stdin: JSON.stringify(commands.map((command) => command.map(String))),
+  });
+  const entries = Array.isArray(result) ? result : (result?.data || []);
+  const failed = Array.isArray(entries) ? entries.find((entry) => entry && entry.success === false) : null;
+  if (failed) {
+    throw new Error(`${(failed.command || []).join(' ')}: ${failed.error || 'failed'}`);
+  }
+  return entries;
+}
+
 async function readText(session, commandArgs, timeoutMs) {
   await ensureReady(session);
   return cli.readText(commandArgs, session, timeoutMs, backend.mode() === 'attached' ? backend.cdpEndpoint() : null);
@@ -235,4 +274,5 @@ module.exports = {
   readText,
   requestSurfaceOpen,
   run,
+  runBatch,
 };

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

@@ -29,21 +29,31 @@ const cli = require('./cli');
 const attach = require('./attach');
 const cdp = require('./cdp');
 
-const SCREENSHOT_TIMEOUT_MS = 20_000;
+// Visible surfaces answer captureScreenshot in well under 100ms (verified
+// live); a surface that has not answered in 4s is not going to. The short
+// deadline turns "compositor is off" from a 20s mystery into a fast, named
+// failure.
+const SCREENSHOT_TIMEOUT_MS = 4_000;
 const FULL_PAGE_MAX_PX = 16_384;
 
 /**
- * Page.captureScreenshot clip (CSS px) for a webview rectangle. The capture
- * renders at the device scale factor, so scale divides it back out — the
- * image is CSS-pixel sized and its coordinates map 1:1 onto cua_click/
+ * Page.captureScreenshot clip (CSS px) for a webview rectangle, clamped to
+ * the embedder viewport — a splitview mid-animation or mid-resize can report
+ * a rect that overhangs the window, and the overhang captures as black. The
+ * capture renders at the device scale factor, so scale divides it back out —
+ * the image is CSS-pixel sized and its coordinates map 1:1 onto cua_click/
  * cua_move input coordinates (the contract vision loops rely on).
  */
 function clipFor(rect) {
+  const x = Math.min(Math.max(0, Math.round(rect.x)), Math.max(0, Math.round(rect.vw || rect.x + rect.width) - 1));
+  const y = Math.min(Math.max(0, Math.round(rect.y)), Math.max(0, Math.round(rect.vh || rect.y + rect.height) - 1));
+  const maxW = Math.max(1, Math.round(rect.vw || rect.x + rect.width) - x);
+  const maxH = Math.max(1, Math.round(rect.vh || rect.y + rect.height) - y);
   return {
-    x: Math.max(0, Math.round(rect.x)),
-    y: Math.max(0, Math.round(rect.y)),
-    width: Math.max(1, Math.round(rect.width)),
-    height: Math.max(1, Math.round(rect.height)),
+    x,
+    y,
+    width: Math.min(Math.max(1, Math.round(rect.width)), maxW),
+    height: Math.min(Math.max(1, Math.round(rect.height)), maxH),
     scale: 1 / (rect.dpr || 1),
   };
 }
@@ -116,9 +126,43 @@ async function plan(session, context) {
     wsUrl: surface.pageWsUrl,
     clip: clipFor(surface.rect),
     crop: cropFilterFor(surface.rect),
+    embedderVisibility: surface.rect.embedderVisibility || null,
   };
 }
 
+/**
+ * Why a capture on this source just starved, in words an agent can act on.
+ * Geometry alone cannot tell: a hidden or minimized app window keeps full
+ * layout while the compositor draws nothing.
+ */
+function starvationReason(source) {
+  if (source.embedderVisibility === 'hidden') {
+    return 'the Amalgm app window is hidden or minimized, so the page is not rendering. '
+      + 'Bring the Amalgm window back on screen and retry';
+  }
+  return 'the surface stopped rendering (the app window may be hidden, minimized, or on another desktop). '
+    + 'Bring the Amalgm window forward and retry';
+}
+
+/**
+ * Prove the source can produce a pixel before committing to work that needs
+ * a stream of them (recording). One tiny capture, hard deadline, named
+ * failure — this is the difference between "0-frame file after 145s" and an
+ * actionable error at start.
+ */
+async function assertCapturable(client, source) {
+  if (!source.clip) return; // page targets raster unconditionally
+  try {
+    await client.call('Page.captureScreenshot', {
+      format: 'jpeg',
+      quality: 10,
+      clip: { x: source.clip.x, y: source.clip.y, width: 8, height: 8, scale: 1 },
+    }, SCREENSHOT_TIMEOUT_MS);
+  } catch (err) {
+    throw new Error(`Cannot capture this surface: ${starvationReason(source)}. (${err.message})`);
+  }
+}
+
 async function screenshot(session, args = {}, context) {
   const fullPage = Boolean(args.fullPage);
   const source = await plan(session, context);
@@ -141,7 +185,15 @@ async function screenshot(session, args = {}, context) {
         params.captureBeyondViewport = true;
       }
     }
-    const { data } = await client.call('Page.captureScreenshot', params, SCREENSHOT_TIMEOUT_MS);
+    let data;
+    try {
+      ({ data } = await client.call('Page.captureScreenshot', params, SCREENSHOT_TIMEOUT_MS));
+    } catch (err) {
+      if (source.clip && /timed out/i.test(String(err.message || ''))) {
+        throw new Error(`Screenshot starved: ${starvationReason(source)}.`);
+      }
+      throw err;
+    }
     if (!data) throw new Error('Empty screenshot response');
     return {
       base64: data,
@@ -154,6 +206,7 @@ async function screenshot(session, args = {}, context) {
 }
 
 module.exports = {
+  assertCapturable,
   clipFor,
   connectCdp: cdp.connectCdp,
   cropFilterFor,
@@ -163,5 +216,6 @@ module.exports = {
   plan,
   rectScript: cdp.rectScript,
   screenshot,
+  starvationReason,
   targetListUrl: cdp.targetListUrl,
 };

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

@@ -113,23 +113,33 @@ function pageTargets(targets) {
 }
 
 /**
- * Locate the session's <webview> element inside a candidate app window:
- * marker in the src attribute, exact current URL (the UI keeps src synced to
- * the visible URL), then "the only webview". Returns layout geometry only
- * when the element is actually visible — a hidden splitview reports 0x0 and
- * resolves to null.
+ * Locate the session's <webview> element inside a candidate app window.
+ * Identity, strongest first:
+ *  - data-amalgm-surface attribute — stamped once at mount, survives
+ *    navigation (the src attribute is rewritten on every navigate, so the
+ *    marker URL it starts with does not last);
+ *  - marker still in the src attribute — fresh, never-navigated surfaces;
+ *  - exact current URL — old-app fallback, needs a fresh hint.
+ * Never "the only webview": adopting an unidentified surface is how one
+ * chat's session ends up driving another chat's page.
+ *
+ * Returns layout geometry only when the element has on-screen size, plus the
+ * embedder's visibilityState (a hidden app window keeps full geometry while
+ * rastering nothing) and the webview's live URL (to re-find the daemon-side
+ * target after a restart).
  */
 function rectScript(markerText, currentUrl) {
   const urlLiteral = JSON.stringify(String(currentUrl || ''));
   return `(() => {
     const views = [...document.querySelectorAll('webview')];
+    const byAttr = views.find((w) => (w.getAttribute('data-amalgm-surface') || '').includes(${JSON.stringify(markerText)}));
     const byMarker = views.find((w) => (w.getAttribute('src') || '').includes(${JSON.stringify(markerText)}));
     const byUrl = ${urlLiteral} ? views.find((w) => (w.src || '') === ${urlLiteral}) : null;
-    const match = byMarker || byUrl || (views.length === 1 ? views[0] : null);
+    const match = byAttr || byMarker || byUrl;
     if (!match) return null;
     const r = match.getBoundingClientRect();
     if (!r.width || !r.height) return null;
-    return JSON.stringify({ x: r.x, y: r.y, width: r.width, height: r.height, vw: window.innerWidth, vh: window.innerHeight, dpr: window.devicePixelRatio || 1 });
+    return JSON.stringify({ x: r.x, y: r.y, width: r.width, height: r.height, vw: window.innerWidth, vh: window.innerHeight, dpr: window.devicePixelRatio || 1, src: match.src || '', embedderVisibility: document.visibilityState });
   })()`;
 }
 

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

@@ -68,15 +68,34 @@ function ffmpegDir() {
   return null;
 }
 
+/**
+ * agent-browser ships prebuilt native binaries next to its node wrapper; the
+ * wrapper only exists to pick one. Spawning the binary directly saves a node
+ * startup (~100ms) on every command — on the hot path, that is the tool's
+ * floor latency.
+ */
+function nativeAgentBrowser(wrapperPath) {
+  const platforms = { darwin: 'darwin', linux: 'linux', win32: 'win32' };
+  const arches = { x64: 'x64', arm64: 'arm64' };
+  const platform = platforms[os.platform()];
+  const arch = arches[os.arch()];
+  if (!platform || !arch) return null;
+  const musl = platform === 'linux'
+    && (fs.existsSync('/lib/ld-musl-x86_64.so.1') || fs.existsSync('/lib/ld-musl-aarch64.so.1'));
+  const name = `agent-browser-${platform}${musl ? '-musl' : ''}-${arch}${platform === 'win32' ? '.exe' : ''}`;
+  const candidate = path.join(path.dirname(wrapperPath), name);
+  return fs.existsSync(candidate) ? candidate : null;
+}
+
 function agentBrowserCommand() {
   if (process.env.AMALGM_AGENT_BROWSER_BIN) {
     return { command: process.env.AMALGM_AGENT_BROWSER_BIN, prefix: [] };
   }
   try {
-    return {
-      command: process.execPath,
-      prefix: [require.resolve('agent-browser/bin/agent-browser.js')],
-    };
+    const wrapper = require.resolve('agent-browser/bin/agent-browser.js');
+    const native = nativeAgentBrowser(wrapper);
+    if (native) return { command: native, prefix: [] };
+    return { command: process.execPath, prefix: [wrapper] };
   } catch {
     return { command: 'agent-browser', prefix: [] };
   }
@@ -167,8 +186,12 @@ function runCli(commandArgs, options = {}) {
     const child = spawn(bin.command, args, {
       cwd: os.homedir(),
       env,
-      stdio: ['ignore', 'pipe', 'pipe'],
+      stdio: [options.stdin != null ? 'pipe' : 'ignore', 'pipe', 'pipe'],
     });
+    if (options.stdin != null) {
+      child.stdin.on('error', () => {});
+      child.stdin.end(String(options.stdin));
+    }
 
     let stdout = '';
     let stderr = '';
@@ -207,6 +230,7 @@ async function readText(commandArgs, session, timeoutMs = 30_000, cdp = null) {
 
 module.exports = {
   DEFAULT_SESSION,
+  agentBrowserCommand,
   amalgmDir,
   asText,
   browserRoot,

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

@@ -22,7 +22,7 @@ const capture = require('./capture');
 const sessions = require('./sessions');
 
 const { sessionFor, sessionInfo } = sessions;
-const { run, readText } = attach;
+const { run, runBatch, readText } = attach;
 
 /**
  * Target grammar shared by click/fill:
@@ -41,26 +41,40 @@ function findArgs(target, action, value) {
   return command;
 }
 
+/** url + title in one daemon round trip, batchable onto any verb. */
+const STATE_COMMAND = ['eval', 'JSON.stringify({url: location.href, title: document.title})'];
+
+function parseState(entryOrResult) {
+  const data = entryOrResult?.result ?? entryOrResult?.data ?? entryOrResult;
+  const raw = data && typeof data === 'object' && 'result' in data ? data.result : data;
+  try {
+    const { url = '', title = '' } = JSON.parse(String(raw));
+    return { url, title };
+  } catch {
+    return { url: '', title: '' };
+  }
+}
+
 async function state(args = {}, context) {
   const session = sessionFor(args, context);
-  let url = '';
-  let title = '';
-  try { url = await readText(session, ['get', 'url']); } catch {}
-  try { title = await readText(session, ['get', 'title']); } catch {}
-  return sessionInfo(session, { url, title });
+  let current = { url: '', title: '' };
+  try { current = parseState(await run(session, STATE_COMMAND, { context })); } catch {}
+  return sessionInfo(session, current);
 }
 
 async function open(args = {}, context) {
   const session = sessionFor(args, context);
-  await run(session, ['open', args.url], { context });
-  return state(args, context);
+  const entries = await runBatch(session, [['open', args.url], STATE_COMMAND], { context });
+  return sessionInfo(session, parseState(entries[1]));
 }
 
 async function snapshot(args = {}, context) {
   const session = sessionFor(args, context);
-  const result = await run(session, ['snapshot', '-i'], { timeoutMs: 30_000, context });
-  const current = await state(args, context);
-  return { ...current, snapshotText: cli.asText(result) };
+  const entries = await runBatch(session, [['snapshot', '-i'], STATE_COMMAND], { timeoutMs: 30_000, context });
+  return {
+    ...sessionInfo(session, parseState(entries[1])),
+    snapshotText: cli.asText(entries[0]?.result ?? entries[0]),
+  };
 }
 
 async function screenshot(args = {}, context) {
@@ -82,10 +96,12 @@ async function fill(args = {}, context) {
   const session = sessionFor(args, context);
   const target = String(args.target || '');
   const text = String(args.text ?? '');
-  await run(session, target.startsWith('text=')
-    ? findArgs(target, 'fill', text)
-    : ['fill', target, text], { context });
-  if (args.submit) await run(session, ['press', 'Enter'], { context });
+  const fillCommand = target.startsWith('text=') ? findArgs(target, 'fill', text) : ['fill', target, text];
+  if (args.submit) {
+    await runBatch(session, [fillCommand, ['press', 'Enter']], { context });
+  } else {
+    await run(session, fillCommand, { context });
+  }
   return sessionInfo(session, { filled: target, submitted: Boolean(args.submit) });
 }
 
@@ -157,32 +173,38 @@ async function cua(action, args = {}, context) {
 
   const x = Math.round(Number(args.x || 0));
   const y = Math.round(Number(args.y || 0));
+  // Composites go as one batch — one daemon round trip per gesture, not one
+  // per mouse event.
   if (action === 'cua_move') await run(session, ['mouse', 'move', x, y], options);
   if (action === 'cua_click') {
     const button = mouseButton(args.button);
-    await run(session, ['mouse', 'move', x, y], options);
-    await run(session, ['mouse', 'down', button], options);
-    await run(session, ['mouse', 'up', button], options);
+    await runBatch(session, [
+      ['mouse', 'move', x, y],
+      ['mouse', 'down', button],
+      ['mouse', 'up', button],
+    ], options);
   }
   if (action === 'cua_double_click') {
-    await run(session, ['mouse', 'move', x, y], options);
-    for (let i = 0; i < 2; i += 1) {
-      await run(session, ['mouse', 'down', 'left'], options);
-      await run(session, ['mouse', 'up', 'left'], options);
-    }
     // agent-browser's mouse events always carry clickCount:1, so the renderer
-    // never coalesces the pair above into a native dblclick. Dispatch the
+    // never coalesces the two real clicks into a native dblclick. Dispatch the
     // dblclick event directly at the point; the two real clicks before it
     // keep focus/selection side effects honest.
-    await run(session, ['eval', `(() => {
-      const el = document.elementFromPoint(${x}, ${y});
-      if (!el) return false;
-      el.dispatchEvent(new MouseEvent('dblclick', {
-        bubbles: true, cancelable: true, view: window,
-        clientX: ${x}, clientY: ${y}, button: 0, detail: 2,
-      }));
-      return true;
-    })()`], options);
+    await runBatch(session, [
+      ['mouse', 'move', x, y],
+      ['mouse', 'down', 'left'],
+      ['mouse', 'up', 'left'],
+      ['mouse', 'down', 'left'],
+      ['mouse', 'up', 'left'],
+      ['eval', `(() => {
+        const el = document.elementFromPoint(${x}, ${y});
+        if (!el) return false;
+        el.dispatchEvent(new MouseEvent('dblclick', {
+          bubbles: true, cancelable: true, view: window,
+          clientX: ${x}, clientY: ${y}, button: 0, detail: 2,
+        }));
+        return true;
+      })()`],
+    ], options);
   }
   if (action === 'cua_scroll') await run(session, ['mouse', 'wheel', args.scrollY || 0, args.scrollX || 0], options);
   if (action === 'cua_type') await run(session, ['keyboard', 'type', args.text || ''], options);
@@ -190,10 +212,12 @@ async function cua(action, args = {}, context) {
   if (action === 'cua_drag') {
     const points = Array.isArray(args.path) ? args.path : [];
     if (points.length < 2) throw new Error('drag path must contain at least two points');
-    await run(session, ['mouse', 'move', points[0].x, points[0].y], options);
-    await run(session, ['mouse', 'down', 'left'], options);
-    for (const point of points.slice(1)) await run(session, ['mouse', 'move', point.x, point.y], options);
-    await run(session, ['mouse', 'up', 'left'], options);
+    await runBatch(session, [
+      ['mouse', 'move', points[0].x, points[0].y],
+      ['mouse', 'down', 'left'],
+      ...points.slice(1).map((point) => ['mouse', 'move', point.x, point.y]),
+      ['mouse', 'up', 'left'],
+    ], options);
   }
   return sessionInfo(session, { ok: true });
 }
@@ -246,10 +270,21 @@ async function loadState(args = {}, context) {
 
 async function close(args = {}, context) {
   const session = sessionFor(args, context);
-  // Attached mode drives the user's visible surface — never close it from
-  // the tool; just forget the session bookkeeping.
-  if (backend.mode() !== 'attached') {
-    await cli.runCli(['close'], { session });
+  // A recording keeps a CDP connection and an encoder alive — closing the
+  // session finalizes it (saving what was captured) rather than orphaning it.
+  const recorder = require('./recorder');
+  if (recorder.isActive(session)) {
+    try { await recorder.stop({ ...args, session }, context); } catch {}
+  }
+  // Tear down this session's daemon. In attached mode this only disconnects
+  // from the app's chromium (verified live: the app, its webviews, and other
+  // sessions' daemons survive) — the visible surface belongs to the UI and
+  // stays open for the user. Without this, every attached session leaks a
+  // daemon process for the life of the machine.
+  try {
+    await cli.runCli(['close'], attach.cliOptions(session, { timeoutMs: 15_000 }));
+  } catch {
+    // No daemon (never started, or already gone) — nothing to tear down.
   }
   sessions.attachedSessions.delete(session);
   sessions.knownSessions.delete(session);

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

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

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

@@ -30,10 +30,66 @@ const backend = require('./backend');
 const capture = require('./capture');
 const sessions = require('./sessions');
 
-const active = new Map(); // session -> { cdp, ffmpeg, file, frames, startedAt }
+const active = new Map(); // session -> { cdp, ffmpeg, file, frames, droppedFrames, startedAt }
 
 const FFMPEG_CLOSE_TIMEOUT_MS = 10_000;
 
+function clampFps(value) {
+  return Math.min(Math.max(Number(value) || 10, 1), 30);
+}
+
+/**
+ * Paint-on-change, encode-on-clock.
+ *
+ * The screencast only emits on visual damage: a static page yields one frame
+ * per minute, an animated canvas yields sixty per second. Feeding that
+ * stream to ffmpeg directly produces dishonest files at both extremes — a
+ * "145-second" recording holding one frame, or an encoder drowning in input
+ * and getting killed at stop. So frames land in a one-deep latest slot, and
+ * a clock writes the slot to ffmpeg at exactly fps: static pages get real
+ * duration, floods cost nothing (the slot just gets overwritten), and the
+ * encoder sees constant-rate input matching its -framerate.
+ *
+ * Ticks are skipped (and counted) while ffmpeg's stdin is backpressured —
+ * with realtime VP8 settings that should stay at zero.
+ */
+function createSampler({ fps, write }) {
+  const intervalMs = 1000 / clampFps(fps);
+  const stats = { received: 0, encoded: 0, skippedTicks: 0 };
+  let latest = null;
+  let blocked = false;
+  let timer = null;
+
+  const sampler = {
+    stats,
+    push(frame) {
+      stats.received += 1;
+      latest = frame;
+    },
+    tick() {
+      if (!latest) return false;
+      if (blocked) {
+        stats.skippedTicks += 1;
+        return false;
+      }
+      const ready = write(latest, () => { blocked = false; });
+      stats.encoded += 1;
+      if (ready === false) blocked = true;
+      return true;
+    },
+    start() {
+      if (timer) return;
+      timer = setInterval(() => sampler.tick(), intervalMs);
+      if (typeof timer.unref === 'function') timer.unref();
+    },
+    stop() {
+      if (timer) clearInterval(timer);
+      timer = null;
+    },
+  };
+  return sampler;
+}
+
 function ffmpegBinary() {
   if (process.env.AMALGM_FFMPEG) return process.env.AMALGM_FFMPEG;
   try {
@@ -95,6 +151,22 @@ function recordingFile(args, context, session) {
   return path.join(recordingDir(args, context, session), `${name}-${stamp}.webm`);
 }
 
+function ffmpegArgs({ fps, filters, file }) {
+  return [
+    '-y', '-f', 'image2pipe', '-c:v', 'mjpeg', '-framerate', String(fps), '-i', 'pipe:0',
+    '-vf', filters,
+    '-c:v', 'libvpx',
+    '-deadline', 'realtime',
+    '-cpu-used', '8',
+    '-lag-in-frames', '0',
+    '-auto-alt-ref', '0',
+    '-threads', '4',
+    '-b:v', '1M',
+    '-pix_fmt', 'yuv420p',
+    file,
+  ];
+}
+
 async function start(args = {}, context = {}) {
   const session = sessions.sessionFor(args, context);
   if (active.has(session)) {
@@ -110,22 +182,40 @@ async function start(args = {}, context = {}) {
   const source = await capture.plan(session, context);
 
   const file = recordingFile(args, context, session);
-  const fps = Math.min(Math.max(Number(args.fps) || 10, 1), 30);
+  const fps = clampFps(args.fps);
   const filters = [source.crop, 'pad=ceil(iw/2)*2:ceil(ih/2)*2'].filter(Boolean).join(',');
 
-  const ffmpeg = spawn(binary, [
-    '-y', '-f', 'image2pipe', '-c:v', 'mjpeg', '-framerate', String(fps), '-i', 'pipe:0',
-    '-vf', filters, '-c:v', 'libvpx', '-pix_fmt', 'yuv420p', file,
-  ], { stdio: ['pipe', 'ignore', 'pipe'] });
+  const ffmpeg = spawn(binary, ffmpegArgs({ fps, filters, file }), { stdio: ['pipe', 'ignore', 'pipe'] });
   let ffmpegErr = '';
   ffmpeg.stderr.on('data', (chunk) => { ffmpegErr = (ffmpegErr + chunk.toString()).slice(-2000); });
 
-  const recording = { cdp: null, ffmpeg, file, frames: 0, startedAt: Date.now(), ffmpegErr: () => ffmpegErr };
+  const recording = {
+    cdp: null,
+    ffmpeg,
+    file,
+    fps,
+    sampler: null,
+    startedAt: Date.now(),
+    ffmpegErr: () => ffmpegErr,
+  };
+  recording.sampler = createSampler({
+    fps,
+    write(frame, onDrain) {
+      try {
+        const ready = ffmpeg.stdin.write(frame);
+        if (!ready) ffmpeg.stdin.once('drain', onDrain);
+        return ready;
+      } catch {
+        return true; // stdin gone; stop() reports via exit code + stderr
+      }
+    },
+  });
 
   // Failures after the preflight (binary swapped out, EMFILE, ffmpeg dying
   // mid-recording and EPIPE-ing stdin) end this recording, not the server.
   ffmpeg.on('error', (err) => {
     ffmpegErr = `${err.message}${ffmpegErr ? ` ${ffmpegErr}` : ''}`;
+    recording.sampler.stop();
     if (active.get(session) === recording) active.delete(session);
     try { recording.cdp?.close(); } catch {}
   });
@@ -137,14 +227,18 @@ async function start(args = {}, context = {}) {
 
   try {
     recording.cdp = await capture.connectCdp(source.wsUrl);
+    // 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.frames += 1;
-      try { ffmpeg.stdin.write(Buffer.from(params.data, 'base64')); } catch {}
+      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 });
+    recording.sampler.start();
   } catch (err) {
+    recording.sampler.stop();
     active.delete(session);
     try { recording.cdp?.close(); } catch {}
     try { ffmpeg.kill('SIGKILL'); } catch {}
@@ -167,13 +261,16 @@ async function stop(args = {}, context = {}) {
   if (!recording) throw new Error(`No active recording for session "${session}".`);
   active.delete(session);
 
+  recording.sampler.stop();
   try { recording.cdp?.send('Page.stopScreencast'); } catch {}
   try { recording.cdp?.close(); } catch {}
 
   // ffmpeg gets a bounded window to flush and finalize the container; a
   // wedged encoder is killed rather than wedging record_stop.
+  let killed = false;
   const exitCode = await new Promise((resolve) => {
     const killTimer = setTimeout(() => {
+      killed = true;
       try { recording.ffmpeg.kill('SIGKILL'); } catch {}
     }, FFMPEG_CLOSE_TIMEOUT_MS);
     recording.ffmpeg.on('close', (code) => {
@@ -187,23 +284,38 @@ async function stop(args = {}, context = {}) {
   });
 
   const durationMs = Date.now() - recording.startedAt;
-  if (recording.frames === 0 || exitCode !== 0) {
+  const { received, encoded, skippedTicks } = recording.sampler.stats;
+  const bytes = fs.existsSync(recording.file) ? fs.statSync(recording.file).size : 0;
+
+  if (encoded === 0 || bytes === 0) {
     try { fs.rmSync(recording.file, { force: true }); } catch {}
-    throw new Error(recording.frames === 0
-      ? 'No frames captured — nothing repainted while recording (the screencast only emits on visual change).'
+    throw new Error(encoded === 0
+      ? 'No frames captured — the surface never produced a pixel while recording '
+        + '(it likely went off screen; in the desktop app the Amalgm window must stay on screen).'
       : `ffmpeg failed (exit ${exitCode}): ${recording.ffmpegErr()}`);
   }
 
-  const bytes = fs.existsSync(recording.file) ? fs.statSync(recording.file).size : 0;
-  return {
+  // WebM is cluster-streamed: even a force-killed encode leaves the frames
+  // written so far playable. Captured video beats a deleted file — return it
+  // and say what happened instead of throwing it away.
+  const result = {
     session,
     path: recording.file,
     relativePath: path.relative(cli.amalgmDir(), recording.file),
     bytes,
-    frames: recording.frames,
+    frames: encoded,
+    framesReceived: received,
+    skippedTicks,
+    fps: recording.fps,
     durationMs,
     mimeType: 'video/webm',
   };
+  if (exitCode !== 0) {
+    result.warning = killed
+      ? `Encoder was force-stopped after ${FFMPEG_CLOSE_TIMEOUT_MS / 1000}s; the file plays but may lack duration metadata.`
+      : `Encoder exited ${exitCode} (${recording.ffmpegErr().slice(-300)}); the file holds the frames written before that.`;
+  }
+  return result;
 }
 
 function list(args = {}, context = {}) {
@@ -227,4 +339,12 @@ function isActive(session) {
   return active.has(session);
 }
 
-module.exports = { isActive, list, recordingDir, resolveProjectPath, start, stop };
+module.exports = {
+  isActive,
+  list,
+  recordingDir,
+  resolveProjectPath,
+  start,
+  stop,
+  _test: { clampFps, createSampler, ffmpegArgs },
+};

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

@@ -7,10 +7,15 @@ const http = require('node:http');
 const capture = require('../browser/capture');
 
 test('clipFor turns a webview rect into integer CSS-px clip bounds', () => {
+  // 411.5 + 868.75 overhangs the 1280px viewport by a rounding hair — the
+  // clip clamps to the viewport edge (the overhang captures as a black bar).
   const clip = capture.clipFor({ x: 411.5, y: 52.25, width: 868.75, height: 781.5, vw: 1280, vh: 834 });
-  assert.deepEqual(clip, { x: 412, y: 52, width: 869, height: 782, scale: 1 });
+  assert.deepEqual(clip, { x: 412, y: 52, width: 868, height: 782, scale: 1 });
   // Negative origins (mid-animation surfaces) clamp to the viewport.
   assert.equal(capture.clipFor({ x: -4, y: 0, width: 100, height: 100 }).x, 0);
+  // A splitview sliding open can report a rect mostly past the right edge.
+  const sliding = capture.clipFor({ x: 1200, y: 0, width: 700, height: 600, vw: 1280, vh: 800 });
+  assert.deepEqual(sliding, { x: 1200, y: 0, width: 80, height: 600, scale: 1 });
   // Retina displays render captures at devicePixelRatio; scale divides it
   // back out so image pixels map 1:1 onto cua input coordinates.
   assert.equal(capture.clipFor({ x: 0, y: 0, width: 100, height: 100, dpr: 2 }).scale, 0.5);
@@ -35,13 +40,41 @@ test('pageTargets keeps only capturable page targets', () => {
   assert.deepEqual(capture.pageTargets(targets).map((t) => t.webSocketDebuggerUrl), ['ws://x/3']);
 });
 
-test('rectScript matches by marker, then current URL, then the only webview', () => {
+test('rectScript identifies the session surface and never guesses', () => {
   const script = capture.rectScript('amalgm-bsid-abc', 'https://example.com/');
+  // Strongest identity first: the data attribute stamped at mount survives
+  // navigation; the marker in src only exists until the first navigate.
+  assert.match(script, /data-amalgm-surface/);
   assert.match(script, /amalgm-bsid-abc/);
   assert.match(script, /https:\/\/example\.com\//);
   // No current URL → the byUrl branch is disabled, not matching everything.
   const bare = capture.rectScript('amalgm-bsid-abc', '');
   assert.match(bare, /"" \? views\.find/);
+  // "The only webview" is how one chat's capture reads another chat's page —
+  // an unidentified surface must resolve to null, never to a guess.
+  assert.doesNotMatch(script, /views\.length === 1/);
+  // The embedder's visibilityState rides along: full geometry with a hidden
+  // window is exactly the state captures must be able to name.
+  assert.match(script, /embedderVisibility/);
+  assert.match(script, /src: match\.src/);
+});
+
+test('starvationReason names the app window state', () => {
+  assert.match(capture.starvationReason({ embedderVisibility: 'hidden' }), /hidden or minimized/);
+  assert.match(capture.starvationReason({ embedderVisibility: null }), /stopped rendering/);
+});
+
+test('assertCapturable converts a starved probe into a named refusal', async () => {
+  const starvedClient = { call: () => new Promise(() => {}) };
+  // capture.js wraps the probe in its own deadline via cdp.call timeout — here
+  // the fake client never resolves, so rely on the call-site deadline shape:
+  const probe = capture.assertCapturable(
+    { call: (m, p, t) => capture.deadline(new Promise(() => {}), 50, m) },
+    { clip: { x: 0, y: 0, width: 10, height: 10 }, embedderVisibility: 'hidden' },
+  );
+  await assert.rejects(() => probe, /Cannot capture this surface: .*hidden or minimized/);
+  // Headless page targets raster unconditionally — no probe, no rejection.
+  await capture.assertCapturable(starvedClient, { clip: null });
 });
 
 test('targetListUrl accepts bare ports and ws urls', () => {

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

@@ -0,0 +1,58 @@
+'use strict';
+
+const assert = require('node:assert/strict');
+const test = require('node:test');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+const cli = require('../browser/cli');
+
+function withoutBinOverride(fn) {
+  const saved = process.env.AMALGM_AGENT_BROWSER_BIN;
+  delete process.env.AMALGM_AGENT_BROWSER_BIN;
+  try {
+    return fn();
+  } finally {
+    if (saved !== undefined) process.env.AMALGM_AGENT_BROWSER_BIN = saved;
+  }
+}
+
+test('agent-browser spawns the native binary directly when it exists', () => {
+  // The node wrapper exists only to pick a platform binary — spawning it adds
+  // a node startup (~100ms) to every command, which is the verb floor latency.
+  let wrapper;
+  try {
+    wrapper = require.resolve('agent-browser/bin/agent-browser.js');
+  } catch {
+    return; // checkout without agent-browser installed — nothing to assert
+  }
+  const { command, prefix } = withoutBinOverride(() => cli.agentBrowserCommand());
+  const dir = path.dirname(wrapper);
+  const hasNative = fs.readdirSync(dir).some((name) => name.startsWith(`agent-browser-${os.platform()}`));
+  if (hasNative) {
+    assert.notEqual(command, process.execPath, 'must not pay a node startup per command');
+    assert.match(command, /agent-browser-/);
+    assert.deepEqual(prefix, []);
+  } else {
+    assert.equal(command, process.execPath);
+  }
+});
+
+test('runCli forwards stdin for batch JSON commands', async () => {
+  // `batch` reads JSON command arrays from stdin — argv-quoting nested
+  // commands is exactly how arguments got eaten in the wild.
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'amalgm-cli-test-'));
+  const stub = path.join(dir, 'echo-stdin.sh');
+  fs.writeFileSync(stub, '#!/bin/sh\ncat\n', { mode: 0o755 });
+  const saved = process.env.AMALGM_AGENT_BROWSER_BIN;
+  process.env.AMALGM_AGENT_BROWSER_BIN = stub;
+  try {
+    const result = await cli.runCli([], { session: 'stdin-test', json: false, stdin: '[["get","url"]]', timeoutMs: 5000 });
+    assert.match(result.text, /\[\["get","url"\]\]/);
+  } finally {
+    if (saved === undefined) delete process.env.AMALGM_AGENT_BROWSER_BIN;
+    else process.env.AMALGM_AGENT_BROWSER_BIN = saved;
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});

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

@@ -38,3 +38,68 @@ test('ffmpeg ships with the published package', (t) => {
     'packages/amalgm must depend on ffmpeg-static — PATH ffmpeg does not exist on fresh machines',
   );
 });
+
+// The sampler is the recorder's honesty mechanism: paint-on-change,
+// encode-on-clock. Both 2026-06-10 stress failures live here — a "145s"
+// recording holding one frame (static page, damage-driven ingest) and
+// ffmpeg drowning under a 60fps animation then being killed at stop.
+
+test('sampler gives static pages honest duration: one frame, many ticks', () => {
+  const { _test } = require('../browser/recorder');
+  const written = [];
+  const sampler = _test.createSampler({ fps: 10, write: (frame) => { written.push(frame); return true; } });
+
+  sampler.tick(); // nothing captured yet — nothing to encode
+  assert.equal(written.length, 0);
+
+  sampler.push(Buffer.from('frame-1')); // the single repaint a static page emits
+  for (let i = 0; i < 30; i += 1) sampler.tick(); // 3 seconds of clock at 10fps
+
+  assert.equal(written.length, 30, 'the latest frame re-encodes every tick — 3s of video, not 1 frame');
+  assert.equal(sampler.stats.received, 1);
+  assert.equal(sampler.stats.encoded, 30);
+});
+
+test('sampler absorbs animation floods: encode rate is the clock, not the damage rate', () => {
+  const { _test } = require('../browser/recorder');
+  let writes = 0;
+  const sampler = _test.createSampler({ fps: 10, write: () => { writes += 1; return true; } });
+
+  for (let burst = 0; burst < 10; burst += 1) {
+    for (let i = 0; i < 60; i += 1) sampler.push(Buffer.from(`f${burst}-${i}`)); // 60fps canvas
+    sampler.tick();
+  }
+  assert.equal(writes, 10, 'ffmpeg sees fps ticks, never the 600 damage frames');
+  assert.equal(sampler.stats.received, 600);
+});
+
+test('sampler skips ticks under encoder backpressure and resumes on drain', () => {
+  const { _test } = require('../browser/recorder');
+  let drains = [];
+  const sampler = _test.createSampler({
+    fps: 10,
+    write: (frame, onDrain) => { drains.push(onDrain); return false; }, // stdin buffer full
+  });
+
+  sampler.push(Buffer.from('frame'));
+  assert.equal(sampler.tick(), true);
+  assert.equal(sampler.tick(), false, 'blocked while ffmpeg has not drained');
+  assert.equal(sampler.stats.skippedTicks, 1);
+
+  drains[0](); // ffmpeg drained
+  assert.equal(sampler.tick(), true);
+  assert.equal(sampler.stats.encoded, 2);
+});
+
+test('recording encoder uses realtime VP8 settings', () => {
+  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' });
+
+  assert.ok(args.includes('-deadline'));
+  assert.equal(args[args.indexOf('-deadline') + 1], 'realtime');
+  assert.ok(args.includes('-cpu-used'));
+  assert.equal(args[args.indexOf('-cpu-used') + 1], '8');
+  assert.ok(args.includes('-lag-in-frames'));
+  assert.equal(args[args.indexOf('-lag-in-frames') + 1], '0');
+  assert.equal(args[args.length - 1], '/tmp/out.webm');
+});

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

@@ -131,3 +131,42 @@ test('entrypoint routing: candidate order is state dir, derived label dir, AMALG
     assert.equal(candidates[3], path.join(os.homedir(), '.amalgm', 'electron-browser-bridge.json'));
   });
 });
+
+// ---------------------------------------------------------------------------
+// Session → surface routing. The 2026-06-10 stress tests caught two parallel
+// chats reading each other's pages: a displaced session (its webview died on
+// a chat-tab switch) fell back to "the only webview" — someone else's.
+// ---------------------------------------------------------------------------
+
+test('surface routing: marker, embedder DOM src, then previously selected tab', () => {
+  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 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);
+
+  // 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);
+
+  // 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');
+  }
+});
+
+test('surface routing: an unidentified lone webview is never adopted', () => {
+  const attach = require('../browser/attach');
+  // 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);
+});