humanish 0.105.0 → 0.106.0

package/dist/e2b-cua-provisioning.js

@@ -1,1219 +0,0 @@
-// Hosted desktop setup primitives. The lane adapter owns their lifecycle.
-import { readFile } from "node:fs/promises";
-import path from "node:path";
-import { CHROMIUM_EVIDENCE_HYGIENE_FLAGS, chromiumEvidenceProfilePreferencesJson } from "./browser-evidence-hygiene.js";
-import { chromeCdpProbeCommand, parseChromeCdpProbeOutput } from "./chrome-cdp-probe.js";
-import { runDesktopCommandOrThrow, toErrorMessage } from "./command-failure.js";
-import {} from "./device-presets.js";
-import { withOneRetryOnTransientE2BError } from "./e2b-desktop-launch.js";
-import { probeUrl, readDetachedLog, runDetachedStep, startDetachedProcess } from "./e2b-detached.js";
-import { isHttpUrl } from "./lab-config.js";
-import { digestText, redactText, redactedTail } from "./redaction.js";
-import {} from "./run.js";
-import { corepackCommandFor, needsNodeRuntime, nodeBootstrapCommand } from "./subject-runtime.js";
-import { TERMINAL_NODE_BOOTSTRAP_COMMAND } from "./terminal-node-bootstrap.js";
-export const CUA_ACTOR_LAB_PROVIDER_METADATA = {
-    mode: "cua-actor-lab",
-    tool: "humanish"
-};
-// Settle after opening the browser, before the first screenshot — long enough for a cold
-// browser + page load to paint (2s captured a blank desktop; the render empirically needs ~6-9s).
-export const BROWSER_SETTLE_MS = 8_000;
-/** Where a lane's synthetic camera feed lives inside the sandbox: a tmpfs the sandbox user can
- *  write, and a path that contains neither /tmp/ nor /home/, which the public-safety scan reads
- *  as an operator's local path (this one is the harness's own and belongs in the bundle). */
-export const SANDBOX_MEDIA_DIR = "/dev/shm/humanish-media";
-export const SANDBOX_CAMERA_PATH = `${SANDBOX_MEDIA_DIR}/camera.y4m`;
-/** The synthetic feed: ffmpeg's test pattern, 640x480 at 10 fps, six seconds (about 28 MB of
- *  raw Y4M on the tmpfs), looped by Chrome's fake capture device. */
-export const SYNTHETIC_CAMERA_COMMAND = `mkdir -p ${SANDBOX_MEDIA_DIR} && ffmpeg -y -loglevel error -f lavfi -i testsrc=size=640x480:rate=10 -t 6 -pix_fmt yuv420p ${SANDBOX_CAMERA_PATH}`;
-/**
- * Put the declared camera feed in the sandbox and return the Chromium flags that present it as a
- * capture device (#509). Fails CLOSED: a feed that cannot be produced (no ffmpeg on the image, an
- * unreadable host file) is named before the browser launches, because a participant told it has
- * a camera and finds none reports the instrument's gap as the product's.
- */
-export async function prepareDesktopMedia(desktop, media, permission, cwd, requestTimeoutMs, readHostFile = (absolutePath) => readFile(absolutePath)) {
-    if (media.microphone !== undefined) {
-        if (media.microphone.source !== "speech")
-            throw new Error("Microphone source-file injection is unsupported; use source: speech.");
-        if (media.camera !== undefined)
-            throw new Error("Hosted synthetic cameras cannot be combined with speech.");
-        // The lane starts and admits the speech worker before launching the browser.
-        return { microphone: { source: "speech" }, permission, flags: permission === "granted" ? ["--use-fake-ui-for-media-stream"] : [] };
-    }
-    const flags = [];
-    let camera;
-    if (media.camera !== undefined) {
-        if (media.camera.source === "synthetic") {
-            const made = await desktop.commands.run(SYNTHETIC_CAMERA_COMMAND, { requestTimeoutMs, timeoutMs: 60_000 });
-            if (made.exitCode !== undefined && made.exitCode !== 0) {
-                throw new Error(`the synthetic camera feed could not be generated on this desktop image (ffmpeg exited ${made.exitCode}: ${tailOf(made.stderr ?? made.stdout ?? "")}); give execution.desktop.media.camera.source a .y4m file instead`);
-            }
-            camera = { source: "synthetic", file: SANDBOX_CAMERA_PATH };
-        }
-        else {
-            const absolutePath = path.resolve(cwd, media.camera.source);
-            let bytes;
-            try {
-                bytes = await readHostFile(absolutePath);
-            }
-            catch (error) {
-                throw new Error(`execution.desktop.media.camera.source could not be read (${toErrorMessage(error)})`);
-            }
-            if (bytes.length > 64 * 1024 * 1024) {
-                throw new Error(`execution.desktop.media.camera.source is ${bytes.length} bytes; the camera feed is capped at 64 MiB`);
-            }
-            await desktop.commands.run(`mkdir -p ${SANDBOX_MEDIA_DIR}`, { requestTimeoutMs, timeoutMs: 15_000 });
-            const payload = bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength);
-            await desktop.files.write(SANDBOX_CAMERA_PATH, payload, { requestTimeoutMs, useOctetStream: true });
-            camera = { source: "file", file: SANDBOX_CAMERA_PATH };
-        }
-        flags.push("--use-fake-device-for-media-stream", `--use-file-for-fake-video-capture=${SANDBOX_CAMERA_PATH}`);
-    }
-    if (permission === "granted")
-        flags.push("--use-fake-ui-for-media-stream");
-    return { ...(camera === undefined ? {} : { camera }), permission, flags };
-}
-export const SUBJECT_DIR = "/home/user/subject";
-// Remote path for the once-per-run packed local-tree archive; removed by the extract step
-// after it unpacks into SUBJECT_DIR.
-const LOCAL_TREE_REMOTE_ARCHIVE_PATH = "/home/user/.humanish-source.tar.gz";
-const CLONE_TIMEOUT_MS = 5 * 60_000;
-const INSTALL_TIMEOUT_MS = 10 * 60_000;
-const BUILD_TIMEOUT_MS = 10 * 60_000;
-const DEFAULT_READY_TIMEOUT_MS = 180_000;
-// Per-step budget for subject.state seed steps; each step's declared (or default) budget is
-// also summed into the default sandbox deadline so seeding never eats the session's room.
-export const DEFAULT_STATE_STEP_TIMEOUT_MS = 5 * 60_000;
-// How much of a failing step's log tail rides the (redacted) error message.
-const ERROR_TAIL_CHARS = 2000;
-/** Mid-run inbox-surface render cadence (ms). Coarse enough that the per-tick `cat` + file writes stay
- *  cheap; fine enough that a verification email is visible seconds after the app sends it. */
-export const INBOX_SURFACE_CADENCE_MS = 2500;
-/**
- * The DECLARED preset to record alongside the rendered screen, or undefined when the preset
- * rendered faithfully.
- *
- * `desktopGeometry.screen.verified` compares the FLOORED number with itself, so on its own a
- * floored run is indistinguishable from a faithful one: a reader sees requested 500 / verified 500
- * and concludes a 500-wide screen was asked for. Recording the declared preset is what makes
- * "the preset width did not render" legible in the bundle.
- */
-export function declaredScreenForRender(preset, presetName, rendered) {
-    if (preset.width === rendered[0] && preset.height === rendered[1])
-        return undefined;
-    return { width: preset.width, height: preset.height, preset: presetName };
-}
-/** ISO timestamp from an injectable clock (tests freeze `now` for deterministic durationMs). */
-function isoNow(now) {
-    return new Date(now()).toISOString();
-}
-/** Emit a phase-started event (no ok/durationMs: those belong to the matching completed event). */
-/**
- * Run a provisioning step and, when it fails with an EXIT CODE, run it once more (#602). A cold
- * install of 0.74.0 lost its whole first live study to one transient TLS error inside the
- * sandbox's `npm install`; the parallel install twenty seconds later passed, as had the ten
- * before it. One retry clears that class. A TIMEOUT is not retried: its budget is already spent,
- * and a second wait would double it. The retry runs under its own step name so both logs stay.
- */
-async function runProvisioningStepWithOneRetry(desktop, args) {
-    const first = await runDetachedStep(desktop, {
-        name: args.name,
-        command: args.command,
-        cwd: args.cwd,
-        timeoutMs: args.timeoutMs,
-        requestTimeoutMs: args.requestTimeoutMs,
-        ...args.timers
-    });
-    if (first.ok || first.timedOut)
-        return { ...first, attempts: 1 };
-    const retryStartedAt = args.now();
-    emitPhaseStarted(args.onPhase, args.now, args.retryPhase, `${args.retryMessage} (first attempt exited ${first.exitCode ?? "null"}; retrying once)`);
-    const second = await runDetachedStep(desktop, {
-        name: `${args.name}-retry`,
-        command: args.command,
-        cwd: args.cwd,
-        timeoutMs: args.timeoutMs,
-        requestTimeoutMs: args.requestTimeoutMs,
-        ...args.timers
-    });
-    emitPhaseCompleted(args.onPhase, args.now, retryStartedAt, args.retryPhase, second.ok, second.ok ? `${args.retryMessage}: succeeded on the second attempt` : `${args.retryMessage}: failed twice`);
-    return { ...second, attempts: 2, ...(first.exitCode === undefined ? {} : { firstExitCode: first.exitCode }) };
-}
-function emitPhaseStarted(onPhase, now, phase, message) {
-    onPhase?.({ at: isoNow(now), type: `cua-lab.subject.${phase}.started`, message });
-}
-/** Emit the matching phase-completed event: always carries ok and durationMs (>= 0). */
-function emitPhaseCompleted(onPhase, now, startedAt, phase, ok, message) {
-    onPhase?.({
-        at: isoNow(now),
-        type: `cua-lab.subject.${phase}.completed`,
-        ok,
-        durationMs: Math.max(0, now() - startedAt),
-        message
-    });
-}
-/** Default phase-boundary sink (stderr): one line per event, prefixed with the lane id ONLY
- *  when laneCount > 1. Single-lane emission is unconditional: total single-lane silence for the
- *  whole clone/install/build/ready boot is the bug this event stream exists to close.
- *  Overridable via CuaActorLabHooks.onPhase so deterministic tests capture instead of writing to
- *  the real stderr. */
-export function defaultSubjectPhaseSink(event, ctx) {
-    const durationSuffix = event.durationMs === undefined ? "" : ` (${event.durationMs}ms)`;
-    const prefix = ctx.laneCount > 1 ? `humanish cua [${ctx.laneId}]` : "humanish cua";
-    process.stderr.write(`${prefix}: ${event.message}${durationSuffix}\n`);
-}
-/**
- * Verify the desktop screen geometry IN-SANDBOX (the per-lane device claim is checked, never
- * assumed). A parseable mismatch fails closed. Unavailable/unparseable evidence is returned as
- * an explicit warning: the lane may still run, but its bundle records only the requested screen
- * and never upgrades that request into a verified measurement.
- */
-export async function inspectDesktopScreenGeometry(args) {
-    let out = "";
-    try {
-        const result = await args.desktop.commands.run("xdpyinfo 2>/dev/null | grep -i dimensions || true", { requestTimeoutMs: args.requestTimeoutMs });
-        out = (result.stdout ?? "").trim();
-    }
-    catch {
-        return { warning: `Desktop screen geometry could not be measured for lane ${args.laneId}; requested geometry remains unverified.` };
-    }
-    const match = out.match(/(\d+)\s*x\s*(\d+)\s*pixels/i);
-    if (!match) {
-        return { warning: `Desktop screen geometry could not be parsed for lane ${args.laneId}; requested geometry remains unverified.` };
-    }
-    const width = Number(match[1]);
-    const height = Number(match[2]);
-    const [expectedWidth, expectedHeight] = args.requestedScreen;
-    if (width === expectedWidth && height === expectedHeight) {
-        return { verified: { width, height, source: "xdpyinfo" } };
-    }
-    return {
-        verified: { width, height, source: "xdpyinfo" },
-        error: `HUMANISH_CUA_LAB_DEVICE_GEOMETRY: lane ${args.laneId} requested a ${expectedWidth}x${expectedHeight} desktop but xdpyinfo reports ${width}x${height} in-sandbox; the per-lane device geometry is unverified (fail-closed).`
-    };
-}
-async function findVisibleBrowserWindowId(desktop, requestTimeoutMs, browserFamily, launchIdentity) {
-    if (browserFamily === "unknown")
-        return undefined;
-    // The candidate loop keeps the LAST identity match: with a launch identity the match is
-    // unique anyway, and without one every family candidate matches, so the newest visible
-    // window of the launched family wins (the window this lane just opened).
-    const finder = browserFamily === "firefox"
-        ? [
-            "find_firefox_window() {",
-            "  timeout 2s xdotool search --onlyvisible --class 'firefox|Firefox' 2>/dev/null || true",
-            "}",
-            "window_id=",
-            "for _ in $(seq 1 10); do",
-            "  for candidate in $(find_firefox_window); do",
-            "    window_pid=\"$(xdotool getwindowpid \"$candidate\" 2>/dev/null || true)\"",
-            "    if matches_launch_identity \"$window_pid\"; then window_id=\"$candidate\"; fi",
-            "  done",
-            "  if [ -n \"$window_id\" ]; then break; fi",
-            "  sleep 0.5",
-            "done"
-        ]
-        : [
-            "find_chrome_window() {",
-            "  timeout 2s xdotool search --onlyvisible --class 'google-chrome|Google-chrome|chromium|Chromium|chrome|Chrome' 2>/dev/null || true",
-            "}",
-            "window_id=",
-            "for _ in $(seq 1 10); do",
-            "  for candidate in $(find_chrome_window); do",
-            "    window_pid=\"$(xdotool getwindowpid \"$candidate\" 2>/dev/null || true)\"",
-            "    if matches_launch_identity \"$window_pid\"; then window_id=\"$candidate\"; fi",
-            "  done",
-            "  if [ -n \"$window_id\" ]; then break; fi",
-            "  sleep 0.5",
-            "done"
-        ];
-    const result = await desktop.commands.run([
-        "set -euo pipefail",
-        "export DISPLAY=\"${DISPLAY:-:0}\"",
-        `launch_pid=${shellSingleQuote(launchIdentity?.processId ?? "")}`,
-        `profile_dir=${shellSingleQuote(launchIdentity?.profileDir ?? "")}`,
-        "matches_launch_identity() {",
-        "  if [ -z \"$launch_pid\" ] && [ -z \"$profile_dir\" ]; then return 0; fi",
-        "  local current=\"${1:-}\"",
-        "  while [[ \"$current\" =~ ^[0-9]+$ ]] && [ \"$current\" -gt 1 ]; do",
-        "    cmdline=\"$(tr '\\0' ' ' < \"/proc/$current/cmdline\" 2>/dev/null || true)\"",
-        "    if [ -n \"$profile_dir\" ] && [[ \"$cmdline\" == *\"$profile_dir\"* ]]; then return 0; fi",
-        "    if [ \"$current\" = \"$launch_pid\" ]; then return 0; fi",
-        "    current=\"$(ps -o ppid= -p \"$current\" 2>/dev/null | tr -d ' ' || true)\"",
-        "  done",
-        "  return 1",
-        "}",
-        ...finder,
-        "if [ -n \"$window_id\" ]; then printf 'WINDOW_ID=%s\\n' \"$window_id\"; fi"
-    ].join("\n"), {
-        requestTimeoutMs,
-        timeoutMs: 15_000
-    });
-    return (result.stdout ?? "").match(/^WINDOW_ID=(\S+)$/m)?.[1];
-}
-/**
- * Build the xdotool command that makes a browser window fill the desktop.
- * Exported (pure) for contract tests. A window manager can ignore Chrome's
- * --window-size, so xdotool is the robust path: move the window to the origin,
- * then size it to the exact desktop resolution so Observer screenshots carry no
- * dead margin around the browser.
- */
-export function buildFillDesktopWindowCommand(windowId, width, height) {
-    return [
-        "set -euo pipefail",
-        `win=${shellSingleQuote(windowId)}`,
-        `xdotool windowactivate "$win" >/dev/null 2>&1 || true`,
-        `xdotool windowmove "$win" 0 0 >/dev/null 2>&1 || true`,
-        `xdotool windowsize "$win" ${width} ${height} >/dev/null 2>&1 || true`,
-    ].join("\n");
-}
-/**
- * Best-effort initial fill. A contained smaller window remains usable; the capture
- * below checks for clipping and refuses an uncorrectable window before the actor runs.
- */
-async function fillDesktopBrowserWindow(desktop, windowId, resolution, requestTimeoutMs) {
-    const [width, height] = resolution;
-    await desktop.commands
-        .run(buildFillDesktopWindowCommand(windowId, width, height), {
-        requestTimeoutMs,
-        timeoutMs: 10_000,
-    })
-        .catch(() => undefined);
-}
-export async function openDesktopBrowserTarget(desktop, targetUrl, requestTimeoutMs, browserPreference, 
-/** Launch-time flags that make mobile fidelity (#221) hold across every tab: the user agent and
- *  touch events are browser-wide here, where the CDP holder covers only the launch page. */
-extraChromiumFlags = [], environment) {
-    const requestedBrowser = browserPreference ?? "default";
-    if (isHttpUrl(targetUrl)) {
-        const chromiumFlags = [...CHROMIUM_EVIDENCE_HYGIENE_FLAGS, ...extraChromiumFlags].map(shellSingleQuote).join(" ");
-        const browserLaunchCommand = [
-            "set -euo pipefail",
-            `target_url=${shellSingleQuote(targetUrl)}`,
-            `browser_preference=${shellSingleQuote(requestedBrowser)}`,
-            "chrome_profile_dir=",
-            `chrome_preferences_json=${shellSingleQuote(chromiumEvidenceProfilePreferencesJson())}`,
-            "prepare_chrome_profile() {",
-            "  chrome_profile_dir=\"$(mktemp -d /tmp/humanish-chrome-profile.XXXXXX)\"",
-            "  mkdir -p \"$chrome_profile_dir/Default\"",
-            "  printf '%s\\n' \"$chrome_preferences_json\" > \"$chrome_profile_dir/Default/Preferences\"",
-            "}",
-            "launch_browser() {",
-            "  local label=\"$1\"",
-            "  local binary=\"$2\"",
-            "  shift 2",
-            "  if command -v \"$binary\" >/dev/null 2>&1; then",
-            "    nohup \"$binary\" \"$@\" \"$target_url\" >/tmp/humanish-browser-open.log 2>&1 &",
-            "    local launch_pid=$!",
-            "    printf 'HUMANISH_BROWSER_RESOLVED=%s\\n' \"$label\"",
-            "    printf 'HUMANISH_BROWSER_PID=%s\\n' \"$launch_pid\"",
-            "    printf 'HUMANISH_BROWSER_PROFILE_DIR=%s\\n' \"$chrome_profile_dir\"",
-            "    if [[ \"$label\" =~ ^(google-chrome|google-chrome-stable|chromium|chromium-browser)$ ]]; then",
-            "      for _ in $(seq 1 30); do",
-            "        if [ -s \"$chrome_profile_dir/DevToolsActivePort\" ]; then",
-            "          head -n 1 \"$chrome_profile_dir/DevToolsActivePort\" | sed 's/^/HUMANISH_BROWSER_CDP_PORT=/'",
-            "          break",
-            "        fi",
-            "        sleep 0.1",
-            "      done",
-            "    fi",
-            "    return 0",
-            "  fi",
-            "  return 1",
-            "}",
-            // Fixed CDP port (not :0/random): each seat has its OWN desktop sandbox, so a known port
-            // cannot conflict, and it makes the observer's port resolution deterministic. With :0 the
-            // real port lives only in DevToolsActivePort; when the launch-time capture misses on a cold
-            // start the observer falls back to 9222 and — being wrong — every CDP read fails for the
-            // whole run (the lobby-code handoff then never sees the host's /lobby URL). 9222 is already
-            // the fallback, so making it the actual port aligns launch, capture, and fallback.
-            `chrome_debug_flags=(--remote-debugging-address=127.0.0.1 --remote-debugging-port=9222 ${chromiumFlags})`,
-            "open_target() {",
-            "  case \"$browser_preference\" in",
-            "    chrome)",
-            "      prepare_chrome_profile",
-            "      launch_browser google-chrome google-chrome --new-window \"--user-data-dir=$chrome_profile_dir\" \"${chrome_debug_flags[@]}\" && return 0",
-            "      launch_browser google-chrome-stable google-chrome-stable --new-window \"--user-data-dir=$chrome_profile_dir\" \"${chrome_debug_flags[@]}\" && return 0",
-            "      echo 'requested browser chrome was not found' >&2",
-            "      return 127",
-            "      ;;",
-            "    chromium)",
-            "      prepare_chrome_profile",
-            "      launch_browser chromium chromium --new-window \"--user-data-dir=$chrome_profile_dir\" \"${chrome_debug_flags[@]}\" && return 0",
-            "      launch_browser chromium-browser chromium-browser --new-window \"--user-data-dir=$chrome_profile_dir\" \"${chrome_debug_flags[@]}\" && return 0",
-            "      echo 'requested browser chromium was not found' >&2",
-            "      return 127",
-            "      ;;",
-            "    firefox)",
-            "      prepare_chrome_profile",
-            "      launch_browser firefox firefox --new-instance --no-remote --new-window --profile \"$chrome_profile_dir\" && return 0",
-            "      echo 'requested browser firefox was not found' >&2",
-            "      return 127",
-            "      ;;",
-            "    default)",
-            "      prepare_chrome_profile",
-            "      launch_browser google-chrome google-chrome --new-window \"--user-data-dir=$chrome_profile_dir\" \"${chrome_debug_flags[@]}\" && return 0",
-            "      launch_browser google-chrome-stable google-chrome-stable --new-window \"--user-data-dir=$chrome_profile_dir\" \"${chrome_debug_flags[@]}\" && return 0",
-            "      launch_browser chromium chromium --new-window \"--user-data-dir=$chrome_profile_dir\" \"${chrome_debug_flags[@]}\" && return 0",
-            "      launch_browser chromium-browser chromium-browser --new-window \"--user-data-dir=$chrome_profile_dir\" \"${chrome_debug_flags[@]}\" && return 0",
-            "      launch_browser firefox firefox --new-instance --no-remote --new-window --profile \"$chrome_profile_dir\" && return 0",
-            "      launch_browser xdg-open xdg-open && return 0",
-            "      echo 'no browser opener found' >&2",
-            "      return 127",
-            "      ;;",
-            "  esac",
-            "}",
-            "open_target"
-        ].join("\n");
-        const result = await runDesktopCommandOrThrow(() => desktop.commands.run(browserLaunchCommand, {
-            requestTimeoutMs,
-            timeoutMs: 15_000,
-            ...(environment === undefined ? {} : { envs: { ...environment } }),
-        }), ({ exitCode, stderrTail }) => new Error(`browser launch failed${exitCode === undefined ? "" : ` with exit ${exitCode}`}: ${stderrTail}`));
-        if (result.exitCode !== undefined && result.exitCode !== 0) {
-            throw new Error(`browser launch failed with exit ${result.exitCode}: ${tailOf(result.stderr ?? result.stdout ?? "")}`);
-        }
-        const resolved = (result.stdout ?? "").match(/^HUMANISH_BROWSER_RESOLVED=(\S+)$/m)?.[1];
-        const processId = (result.stdout ?? "").match(/^HUMANISH_BROWSER_PID=(\d+)$/m)?.[1];
-        const profileDir = (result.stdout ?? "").match(/^HUMANISH_BROWSER_PROFILE_DIR=(\S+)$/m)?.[1];
-        const cdpPortRaw = (result.stdout ?? "").match(/^HUMANISH_BROWSER_CDP_PORT=(\d+)$/m)?.[1];
-        const cdpPort = cdpPortRaw === undefined ? undefined : Number(cdpPortRaw);
-        return {
-            family: desktopBrowserFamily(resolved ?? requestedBrowser),
-            ...(processId === undefined || profileDir === undefined
-                ? {}
-                : { identity: { processId, profileDir, targetUrl, ...(cdpPort === undefined ? {} : { cdpPort }) } }),
-            ...(browserPreference === undefined
-                ? {}
-                : { evidence: { requested: requestedBrowser, ...(resolved === undefined ? {} : { resolved }) } })
-        };
-    }
-    if (browserPreference === undefined || browserPreference === "default") {
-        if (desktop.open) {
-            await desktop.open(targetUrl);
-        }
-        else {
-            await desktop.launch("google-chrome", targetUrl);
-        }
-        return {
-            family: desktop.open ? "unknown" : "chromium",
-            ...(browserPreference === undefined ? {} : { evidence: { requested: requestedBrowser } })
-        };
-    }
-    const launchTarget = requestedBrowser === "chrome" ? "google-chrome"
-        : requestedBrowser === "chromium" ? "chromium"
-            : requestedBrowser === "firefox" ? "firefox"
-                : "google-chrome";
-    await desktop.launch(launchTarget, targetUrl);
-    return {
-        family: desktopBrowserFamily(launchTarget),
-        evidence: { requested: requestedBrowser, resolved: launchTarget }
-    };
-}
-export function desktopBrowserFamily(value) {
-    if (value === "firefox")
-        return "firefox";
-    if (value === "chrome" || value === "chromium" || value === "google-chrome" || value === "google-chrome-stable" || value === "chromium-browser") {
-        return "chromium";
-    }
-    return "unknown";
-}
-/**
- * The URL / title / page-text / scroll observer behind stopWhen and task criteria. One probe per
- * observation, run on the sandbox's python3 (see chrome-cdp-probe.ts for why not node: #514).
- *
- * "active": follow the participant to whatever tab they are driving now — never pin the state
- * observer to the launch tab (a verification link that opened in a NEW tab left a pinned observer
- * reading the old tab forever).
- *
- * `onUnavailable` fires ONCE, on the first probe that could not read the page, with the reason.
- * The observer still degrades to `{}` for the loop; the callback is how a lane says out loud that
- * url/text criteria are not being measured, instead of letting the funnel report 0/N (#514).
- */
-export function makeChromeBrowserStateObserver(desktop, requestTimeoutMs, endpoint, targetId, onUnavailable, 
-/**
- * Mobile emulation on later tabs (#623): the holder attaches to every page target Chrome opens
- * after the launch page, so a tab the participant opens later should lay out at the phone width
- * too. The first observation on each new target reads that page's OWN report; a target that
- * reports the requested width is recorded through `onCovered`, and one that does not (or cannot
- * be read) fires `onDrift` once, so a phone-labelled lane that spent part of its session at
- * desktop layout says so with the number the page gave.
- */
-drift) {
-    let reported = false;
-    let drifted = false;
-    const checkedTargets = new Set(drift === undefined ? [] : [drift.emulatedTargetId]);
-    const unavailable = (reason) => {
-        if (!reported) {
-            reported = true;
-            onUnavailable?.(reason);
-        }
-        return {};
-    };
-    const checkLaterTarget = async (newTargetId) => {
-        if (drift === undefined || checkedTargets.has(newTargetId))
-            return;
-        checkedTargets.add(newTargetId);
-        const read = await desktop.commands.run(chromeCdpProbeCommand({ ...endpoint, targetId: newTargetId, prefer: "pinned", mode: "fidelity" }), { requestTimeoutMs, timeoutMs: 5_000 });
-        const fidelity = read.exitCode !== undefined && read.exitCode !== 0 ? undefined : parseChromeCdpProbeOutput(read.stdout).fidelity;
-        if (fidelity !== undefined && fidelity.innerWidth === drift.expectedWidth) {
-            drift.onCovered?.(newTargetId, { innerWidth: fidelity.innerWidth, devicePixelRatio: fidelity.devicePixelRatio, maxTouchPoints: fidelity.maxTouchPoints });
-            if (drift.expectTouch === true && fidelity.maxTouchPoints === 0 && !drifted) {
-                // The viewport followed; touch did not (yet): the holder reloads a later tab once after its
-                // first navigation commits, and this observation may have landed before that reload.
-                drifted = true;
-                drift.onDrift(`a later page target reports the ${fidelity.innerWidth} px viewport but navigator.maxTouchPoints 0 on its first observation; touch reaches a document only when it loads under the override`);
-            }
-            return;
-        }
-        if (drifted)
-            return;
-        drifted = true;
-        drift.onDrift(fidelity === undefined
-            ? "the participant drove a page target other than the emulated launch tab and that page's own read-back could not be taken; whether it laid out at the phone width is not known"
-            : `the participant drove a page target other than the emulated launch tab and that page reports a ${fidelity.innerWidth} px viewport where ${drift.expectedWidth} px was requested (DPR ${fidelity.devicePixelRatio}); the mobile user agent and touch events are browser-wide, the viewport override was not re-applied to it`);
-    };
-    return async () => {
-        const result = await desktop.commands.run(chromeCdpProbeCommand({ ...endpoint, ...(targetId === undefined ? {} : { targetId }), prefer: "active", mode: "state" }), { requestTimeoutMs, timeoutMs: 5_000 });
-        if (result.exitCode !== undefined && result.exitCode !== 0) {
-            return unavailable(`probe exited ${result.exitCode}: ${tailOf(result.stderr ?? result.stdout ?? "")}`);
-        }
-        const parsed = parseChromeCdpProbeOutput(result.stdout);
-        if (parsed.unavailable !== undefined)
-            return unavailable(parsed.unavailable);
-        if (parsed.targetId !== undefined)
-            await checkLaterTarget(parsed.targetId);
-        return {
-            ...(parsed.url === undefined ? {} : { url: parsed.url }),
-            ...(parsed.title === undefined ? {} : { title: parsed.title }),
-            ...(parsed.text === undefined ? {} : { text: parsed.text }),
-            ...(parsed.scrollY === undefined ? {} : { scrollY: parsed.scrollY })
-        };
-    };
-}
-/**
- * Read the running browser's actual outer-window bounds and CSS layout viewport through the
- * already-enabled local Chrome DevTools endpoint. The returned values come from `window.*` in
- * the target page; requested E2B resolution is deliberately not an input to this function.
- * Missing channels report their reason via `onUnavailable`, so the geometry warning can name
- * the cause (a dead CDP endpoint, no python3) instead of only the symptom. Returns `undefined`
- * only when neither channel could be measured.
- * Outer bounds and CSS dimensions are independent channels: a background page can report zero
- * outer dimensions while still reporting a CSS viewport. Final captures follow the active tab;
- * launch captures and emulation attribution keep the pinned target.
- */
-export function makeChromeDesktopGeometryObserver(desktop, requestTimeoutMs, endpoint, targetId, onUnavailable, prefer = "pinned") {
-    return async () => {
-        const result = await desktop.commands.run(chromeCdpProbeCommand({ ...endpoint, ...(targetId === undefined ? {} : { targetId }), prefer, mode: "geometry" }), { requestTimeoutMs, timeoutMs: 5_000 });
-        if (result.exitCode !== undefined && result.exitCode !== 0) {
-            onUnavailable?.(`probe exited ${result.exitCode}: ${tailOf(result.stderr ?? result.stdout ?? "")}`);
-            return undefined;
-        }
-        const parsed = parseChromeCdpProbeOutput(result.stdout);
-        if (parsed.unavailable !== undefined) {
-            onUnavailable?.(parsed.unavailable);
-            return undefined;
-        }
-        const browserWindow = isMeasuredRect(parsed.browserWindow) ? { ...parsed.browserWindow, source: "cdp" } : undefined;
-        const viewport = isMeasuredViewport(parsed.viewport) ? { ...parsed.viewport, source: "cdp" } : undefined;
-        if (browserWindow === undefined && viewport === undefined) {
-            onUnavailable?.("the page reported no usable window or viewport dimensions");
-            return undefined;
-        }
-        if (browserWindow === undefined)
-            onUnavailable?.("the page reported no usable outer-window dimensions");
-        if (viewport === undefined)
-            onUnavailable?.("the page reported no usable CSS viewport dimensions");
-        return {
-            ...(browserWindow === undefined ? {} : { browserWindow }),
-            ...(viewport === undefined ? {} : { viewport }),
-            ...(parsed.targetId === undefined ? {} : { targetId: parsed.targetId })
-        };
-    };
-}
-/** The user agent a mobile-emulated lane presents unless the lab sets its own. */
-export const DEFAULT_MOBILE_USER_AGENT = "Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.0 Mobile/15E148 Safari/604.1";
-/**
- * Apply mobile emulation (#221) to the lane's launch page and read back what the page reports.
- * Fails CLOSED: a request that cannot be applied throws, because a desktop run labelled mobile is
- * the over-trust this feature exists to prevent. A read-back that cannot be taken is a warning
- * (the emulation was applied; only the proof is missing).
- */
-export async function applyMobileEmulation(desktop, requestTimeoutMs, endpoint, targetId, request) {
-    const command = (mode) => chromeCdpProbeCommand({ ...endpoint, ...(targetId === undefined ? {} : { targetId }), prefer: "pinned", mode, emulation: request });
-    const read = async () => {
-        const result = await desktop.commands.run(command("fidelity"), { requestTimeoutMs, timeoutMs: 15_000 });
-        if (result.exitCode !== undefined && result.exitCode !== 0) {
-            return { unavailable: `probe exited ${result.exitCode}: ${tailOf(result.stderr ?? result.stdout ?? "")}` };
-        }
-        return parseChromeCdpProbeOutput(result.stdout);
-    };
-    // The UA / touch / DPR overrides are bound to the DevTools session that set them and lapse the
-    // moment its socket closes (measured: only the viewport width survived a one-shot apply). So the
-    // applier stays attached for the lane's whole life as a detached process; the sandbox teardown
-    // ends it. Its first stdout line says what was applied.
-    const holderName = `mobile-emulation-${Date.now().toString(36)}`;
-    await startDetachedProcess(desktop, { name: holderName, command: command("hold"), requestTimeoutMs });
-    let announced;
-    for (let attempt = 0; attempt < 30 && announced === undefined; attempt += 1) {
-        await new Promise((resolve) => setTimeout(resolve, 500));
-        const log = await readDetachedLog(desktop, holderName, requestTimeoutMs).catch(() => "");
-        const line = log.split("\n").find((candidate) => candidate.trim().startsWith("{"));
-        if (line !== undefined)
-            announced = parseChromeCdpProbeOutput(line);
-    }
-    if (announced === undefined) {
-        throw new Error("mobile emulation could not be applied: the in-sandbox applier printed nothing within 15 s");
-    }
-    if (announced.unavailable !== undefined) {
-        throw new Error(`mobile emulation could not be applied (${announced.unavailable}); applied before failing: ${(announced.applied ?? []).join(", ") || "nothing"}`);
-    }
-    const applied = announced;
-    // Viewport/touch read-back proves context settings, not gesture equivalence. Two hosted
-    // replicas and a native-X conversion-toggle control reproduced reset click counts (#676).
-    const warnings = request.touch
-        ? ["Mobile emulation uses desktop pointer-to-touch conversion, which can differ for repeated taps. Confirm gesture failures with direct or native touch input before attributing them to the app."]
-        : [];
-    // The reload inside the applier takes a moment; the read-back is retried until the page reports
-    // the requested viewport and user agent, so a slow page does not read as "no proof".
-    let readBack = await read();
-    for (let attempt = 0; attempt < 20 && (readBack.fidelity === undefined || readBack.fidelity.innerWidth !== request.width || !readBack.fidelity.userAgent.includes(request.userAgent.slice(0, 24))); attempt += 1) {
-        await new Promise((resolve) => setTimeout(resolve, 500));
-        readBack = await read();
-    }
-    const fidelityRead = readBack;
-    const requested = {
-        width: request.width,
-        height: request.height,
-        deviceScaleFactor: request.deviceScaleFactor,
-        touch: request.touch,
-        userAgent: request.userAgent
-    };
-    const emulatedTargetId = applied.targetId ?? fidelityRead.targetId;
-    if (fidelityRead.fidelity === undefined) {
-        warnings.push(`Mobile emulation was applied but the page's own report could not be read (${fidelityRead.unavailable ?? "no fidelity read"}); desktopGeometry.fidelity carries the request without a resolved block.`);
-        return { fidelity: { tier: "mobile-emulated", requested, applied: applied.applied ?? [] }, warnings, holderName, ...(emulatedTargetId === undefined ? {} : { targetId: emulatedTargetId }) };
-    }
-    const resolved = { ...fidelityRead.fidelity, source: "cdp" };
-    if (resolved.innerWidth !== request.width) {
-        warnings.push(`Mobile emulation requested a ${request.width} px viewport; the page reports ${resolved.innerWidth} px.`);
-    }
-    if (resolved.devicePixelRatio !== request.deviceScaleFactor) {
-        warnings.push(`Mobile emulation requested devicePixelRatio ${request.deviceScaleFactor}; the page reports ${resolved.devicePixelRatio}.`);
-    }
-    if (request.touch && resolved.maxTouchPoints === 0) {
-        warnings.push("Mobile emulation requested touch; the page reports navigator.maxTouchPoints 0.");
-    }
-    if (!resolved.userAgent.includes("Mobile") && !resolved.userAgent.includes("Android") && !resolved.userAgent.includes("iPhone")) {
-        warnings.push("Mobile emulation requested a mobile user agent; the page reports a desktop one.");
-    }
-    return { fidelity: { tier: "mobile-emulated", requested, applied: applied.applied ?? [], resolved }, warnings, holderName, ...(emulatedTargetId === undefined ? {} : { targetId: emulatedTargetId }) };
-}
-function isMeasuredRect(value) {
-    if (!value || typeof value !== "object")
-        return false;
-    const record = value;
-    return Number.isFinite(record.x)
-        && Number.isFinite(record.y)
-        && isPositiveMeasurement(record.width)
-        && isPositiveMeasurement(record.height);
-}
-function isMeasuredViewport(value) {
-    if (!value || typeof value !== "object")
-        return false;
-    const record = value;
-    return isPositiveMeasurement(record.width)
-        && isPositiveMeasurement(record.height)
-        && isPositiveMeasurement(record.deviceScaleFactor);
-}
-function isPositiveMeasurement(value) {
-    return typeof value === "number" && Number.isFinite(value) && value > 0;
-}
-async function measureBrowserWindowWithXwininfo(desktop, windowId, requestTimeoutMs) {
-    const result = await desktop.commands.run([
-        "set -euo pipefail",
-        `win=${shellSingleQuote(windowId)}`,
-        // Older xdotool builds translate parent-relative offsets twice. With window
-        // decorations that falsely reports a visible client as clipped, triggering
-        // fullscreen and hiding the participant's address bar. Read root-relative
-        // client coordinates directly; never substitute emulated CDP outer bounds.
-        "LC_ALL=C xwininfo -id \"$win\" -stats 2>/dev/null"
-    ].join("\n"), { requestTimeoutMs, timeoutMs: 5_000 });
-    if (result.exitCode !== undefined && result.exitCode !== 0)
-        return undefined;
-    return parseXwininfoGeometry(result.stdout ?? "");
-}
-/** Root-relative physical client bounds from xwininfo's C-locale stats. */
-export function parseXwininfoGeometry(output) {
-    const read = (label) => {
-        const matches = [...output.matchAll(new RegExp(`^\\s*${label}:\\s*(-?\\d+)\\s*$`, "gm"))];
-        if (matches.length !== 1)
-            return undefined;
-        const value = Number(matches[0][1]);
-        return Number.isSafeInteger(value) ? value : undefined;
-    };
-    const x = read("Absolute upper-left X");
-    const y = read("Absolute upper-left Y");
-    const width = read("Width");
-    const height = read("Height");
-    const mapStates = [...output.matchAll(/^\s*Map State:\s*(\S+)\s*$/gm)];
-    if (mapStates.length !== 1 || mapStates[0][1] !== "IsViewable")
-        return undefined;
-    if (x === undefined || y === undefined || width === undefined || height === undefined || width <= 0 || height <= 0) {
-        return undefined;
-    }
-    return { x, y, width, height, source: "xwininfo" };
-}
-/** Physical X client bounds, never the page's emulated window.outerWidth/Height. */
-function isBrowserWindowContained(bounds, [width, height]) {
-    return bounds.x >= 0 && bounds.y >= 0
-        && bounds.x + bounds.width <= width && bounds.y + bounds.height <= height;
-}
-/** Bounded repair. Resizing can clear a window-manager maximize state and move the
- * client origin as decorations return, so remeasure before a second adjustment. */
-async function fitBrowserWindowWithinDesktop(desktop, windowId, resolution, requestTimeoutMs) {
-    const run = (command) => desktop.commands.run([
-        "set -euo pipefail",
-        `win=${shellSingleQuote(windowId)}`,
-        command
-    ].join("\n"), { requestTimeoutMs, timeoutMs: 5_000 }).catch(() => undefined);
-    await run('xdotool windowmove "$win" 0 0');
-    await desktop.wait(250).catch(() => undefined);
-    const moved = await measureBrowserWindowWithXwininfo(desktop, windowId, requestTimeoutMs).catch(() => undefined);
-    if (moved === undefined)
-        return moved;
-    let resized = moved;
-    // Resizing alone cannot fix an offscreen client origin. The window manager
-    // can also center a minimum-width client at a negative x on a narrow screen.
-    for (let attempt = 0; attempt < 2; attempt += 1) {
-        if (isBrowserWindowContained(resized, resolution))
-            return resized;
-        const width = resolution[0] - resized.x;
-        const height = resolution[1] - resized.y;
-        if (resized.x < 0 || resized.y < 0 || width <= 0 || height <= 0)
-            break;
-        await run(`xdotool windowsize "$win" ${width} ${height}`);
-        await desktop.wait(250).catch(() => undefined);
-        const measured = await measureBrowserWindowWithXwininfo(desktop, windowId, requestTimeoutMs).catch(() => undefined);
-        if (measured === undefined)
-            return measured;
-        resized = measured;
-    }
-    if (resized === undefined || isBrowserWindowContained(resized, resolution))
-        return resized;
-    // Chrome's minimum client width can equal the whole desktop. Window-manager
-    // borders then make a decorated window impossible to contain, even after a
-    // successful move/resize. Request fullscreen once and prove the physical result.
-    // xprop/xdotool ship with the desktop template; wmctrl is not required.
-    // Check state first so the fullscreen shortcut cannot toggle an existing state off.
-    await run([
-        'state=$(xprop -id "$win" _NET_WM_STATE)',
-        'case "$state" in',
-        '  *_NET_WM_STATE_FULLSCREEN*) ;;',
-        '  *) xdotool windowactivate --sync "$win"; xdotool key --clearmodifiers F11 ;;',
-        'esac'
-    ].join("\n"));
-    // The fullscreen animation may report its new origin before its final width.
-    // Give the window manager a bounded settling window, keeping missing reads unverified.
-    for (let attempt = 0; attempt < 4; attempt += 1) {
-        await desktop.wait(250).catch(() => undefined);
-        const measured = await measureBrowserWindowWithXwininfo(desktop, windowId, requestTimeoutMs).catch(() => undefined);
-        if (measured === undefined || isBrowserWindowContained(measured, resolution))
-            return measured;
-        resized = measured;
-    }
-    return resized;
-}
-/** Shared hosted-browser geometry capture used by per-lane and sequential shared-world routes. */
-export async function captureDesktopBrowserGeometry(args) {
-    const warnings = [];
-    let browserWindowId = args.browserWindowId;
-    if (browserWindowId === undefined && args.browserFamily !== "unknown") {
-        browserWindowId = await findVisibleBrowserWindowId(args.desktop, args.requestTimeoutMs, args.browserFamily, args.launchIdentity).catch((error) => {
-            warnings.push(`Browser window lookup failed for lane ${args.laneId}: ${redactText(toErrorMessage(error))}`);
-            return undefined;
-        });
-    }
-    let physicalWindow;
-    if (browserWindowId !== undefined) {
-        if (args.resize !== false) {
-            await fillDesktopBrowserWindow(args.desktop, browserWindowId, args.requestedScreen, args.requestTimeoutMs);
-            // Let the window manager apply the resize before querying both X and page layout geometry.
-            await args.desktop.wait(250).catch(() => undefined);
-        }
-        physicalWindow = await measureBrowserWindowWithXwininfo(args.desktop, browserWindowId, args.requestTimeoutMs)
-            .catch(() => undefined);
-    }
-    else {
-        warnings.push(`Browser window bounds could not be measured for lane ${args.laneId}; the live stream will use the full desktop.`);
-    }
-    let unusable;
-    if (physicalWindow !== undefined && !isBrowserWindowContained(physicalWindow, args.requestedScreen)) {
-        const before = physicalWindow;
-        if (args.resize !== false && browserWindowId !== undefined) {
-            physicalWindow = await fitBrowserWindowWithinDesktop(args.desktop, browserWindowId, args.requestedScreen, args.requestTimeoutMs);
-            if (physicalWindow === undefined) {
-                // Keep the last measured bad state; a missing observation cannot prove a successful fix.
-                physicalWindow = before;
-                unusable = `Physical browser containment could not be verified after correction for lane ${args.laneId}; the last measured window was clipped.`;
-            }
-            else if (isBrowserWindowContained(physicalWindow, args.requestedScreen)) {
-                warnings.push(`Browser window clipping corrected for lane ${args.laneId}; physical bounds are ${physicalWindow.width}x${physicalWindow.height} at (${physicalWindow.x}, ${physicalWindow.y}).`);
-            }
-        }
-        if (unusable === undefined && !isBrowserWindowContained(physicalWindow, args.requestedScreen)) {
-            unusable = `Browser window is outside the captured ${args.requestedScreen[0]}x${args.requestedScreen[1]} desktop for lane ${args.laneId}: physical bounds ${physicalWindow.width}x${physicalWindow.height} at (${physicalWindow.x}, ${physicalWindow.y}), right=${physicalWindow.x + physicalWindow.width}, bottom=${physicalWindow.y + physicalWindow.height}.`;
-        }
-        if (unusable !== undefined)
-            warnings.push(unusable);
-    }
-    if (physicalWindow === undefined) {
-        warnings.push(`Physical browser containment is unverified for lane ${args.laneId}; X window bounds could not be measured. Page-reported outer dimensions can be emulated and do not prove physical visibility.`);
-    }
-    let cdpUnavailable;
-    const chromeGeometry = args.browserFamily === "chromium"
-        ? await makeChromeDesktopGeometryObserver(args.desktop, args.requestTimeoutMs, {
-            ...(args.launchIdentity?.cdpPort === undefined ? {} : { cdpPort: args.launchIdentity.cdpPort }),
-            ...(args.launchIdentity?.profileDir === undefined ? {} : { profileDir: args.launchIdentity.profileDir }),
-            targetUrl: args.targetUrl
-        }, args.browserTargetId, (reason) => {
-            cdpUnavailable = reason;
-        }, args.pagePreference ?? "pinned")().catch((error) => {
-            cdpUnavailable = toErrorMessage(error);
-            return undefined;
-        })
-        : undefined;
-    const browserWindow = physicalWindow ?? chromeGeometry?.browserWindow;
-    const viewport = chromeGeometry?.viewport;
-    // The fill check reads the X window when it was measured: under mobile emulation (#221) the
-    // page's window.outerWidth reports the EMULATED screen (414), which is not a fill failure.
-    const fillBounds = physicalWindow;
-    if (!browserWindow) {
-        warnings.push(`Browser outer bounds could not be measured for lane ${args.laneId}.`);
-    }
-    else if (unusable === undefined && fillBounds !== undefined && (fillBounds.x !== 0 || fillBounds.y !== 0 || fillBounds.width !== args.requestedScreen[0] || fillBounds.height !== args.requestedScreen[1])) {
-        warnings.push(`Browser window fill did not reach the requested ${args.requestedScreen[0]}x${args.requestedScreen[1]} screen for lane ${args.laneId}; measured physical bounds are ${fillBounds.width}x${fillBounds.height} at (${fillBounds.x}, ${fillBounds.y}).`);
-    }
-    if (!viewport) {
-        // Name the cause, not only the symptom: the same dead DevTools channel that loses the viewport
-        // loses every url/text observation, and a reader of the bundle should learn that here (#514).
-        const cause = cdpUnavailable === undefined ? "" : ` DevTools probe: ${redactText(cdpUnavailable)}.`;
-        warnings.push(args.browserFamily === "firefox"
-            ? `Browser CSS viewport measurement is unavailable for Firefox on lane ${args.laneId}; stream.viewport is omitted instead of reading a different browser's CDP endpoint.`
-            : `Browser CSS viewport could not be measured for lane ${args.laneId}; stream.viewport is omitted instead of copying the requested screen resolution.${cause}`);
-    }
-    return {
-        ...(unusable === undefined ? {} : { unusable }),
-        ...(browserWindowId === undefined ? {} : { browserWindowId }),
-        ...(chromeGeometry?.targetId === undefined ? {} : { browserTargetId: chromeGeometry.targetId }),
-        ...(browserWindow === undefined ? {} : { browserWindow }),
-        ...(viewport === undefined ? {} : { viewport }),
-        warnings
-    };
-}
-function shellSingleQuote(value) {
-    return `'${value.replace(/'/g, "'\\''")}'`;
-}
-/**
- * Prepare a CLI study's runtime and, only when declared, its product (#495, #515).
- *
- * The install runs UNKEYED and before the session starts, for the same reason the clone route
- * provisions its subject first: what is being studied begins when the participant looks at the
- * screen. Omitting install deliberately studies product installation; Node/npm remain a
- * harness prerequisite so the participant can follow the product's public npm instructions.
- */
-export async function provisionDesktopCli(desktop, args) {
-    const install = args.install;
-    const now = () => Date.now();
-    if (install === undefined || needsNodeRuntime([install])) {
-        const startedAt = now();
-        emitPhaseStarted(args.onPhase, now, "runtime", "providing Node/npm for the desktop CLI study");
-        const bootstrap = await runDetachedStep(desktop, {
-            name: "desktop-cli-runtime-node",
-            command: TERMINAL_NODE_BOOTSTRAP_COMMAND,
-            cwd: "/home/user",
-            timeoutMs: INSTALL_TIMEOUT_MS,
-            requestTimeoutMs: args.requestTimeoutMs
-        });
-        emitPhaseCompleted(args.onPhase, now, startedAt, "runtime", bootstrap.ok, bootstrap.ok
-            ? "Node runtime ready"
-            : "Node runtime bootstrap failed");
-        if (!bootstrap.ok) {
-            throw new Error(`desktop-cli runtime bootstrap failed for "${args.product}"`);
-        }
-    }
-    if (install === undefined)
-        return;
-    const startedAt = now();
-    emitPhaseStarted(args.onPhase, now, "install", `installing ${args.product} on the desktop`);
-    const result = await runDetachedStep(desktop, {
-        name: "desktop-cli-install",
-        command: install,
-        cwd: "/home/user",
-        timeoutMs: INSTALL_TIMEOUT_MS,
-        requestTimeoutMs: args.requestTimeoutMs
-    });
-    emitPhaseCompleted(args.onPhase, now, startedAt, "install", result.ok, result.ok
-        ? `${args.product} installed`
-        : `installing ${args.product} failed`);
-    if (!result.ok) {
-        // Fail closed: a participant handed a desktop where the product is not installed would produce
-        // a transcript about a missing command, and that finding belongs to the harness, not the tool.
-        // The tail rides along, scrubbed before truncation like every other provisioning failure — a
-        // bare "install failed" is unactionable to whoever wrote the command.
-        throw new Error(args.scrub(`desktop-cli install failed for "${args.product}" (${result.timedOut ? "timed out" : `exit ${result.exitCode ?? "?"}`}): ${tailOf(args.scrub(result.logTail))}`));
-    }
-}
-/**
- * Open a terminal window on the desktop.
- *
- * The stock template is XFCE and ships xfce4-terminal (also aliased x-terminal-emulator), verified
- * live before this route was built. `x-terminal-emulator` is tried first so a template that swaps
- * the emulator still works; a desktop with neither is a template problem and fails closed rather
- * than handing a participant an empty screen and calling it a study.
- */
-export async function openDesktopTerminal(desktop, requestTimeoutMs, workdir) {
-    const dir = workdir ?? "/home/user";
-    const result = await runDetachedStep(desktop, {
-        name: "desktop-cli-terminal",
-        command: [
-            "for candidate in x-terminal-emulator xfce4-terminal gnome-terminal konsole xterm; do",
-            '  if command -v "$candidate" >/dev/null 2>&1; then',
-            // LANG is set on the terminal we open, not globally: the stock image declares no locale, and
-            // a study that measures our own mojibake against an unconfigured template would be measuring
-            // the template. The PRODUCT-side fix (an ASCII fallback when the locale is not UTF-8) is in
-            // src/terminal-encoding.ts, and it is the one that matters for real users.
-            `    (cd ${shellSingleQuote(dir)} 2>/dev/null || cd /home/user; DISPLAY=:0 LANG=C.UTF-8 LC_ALL=C.UTF-8 HUMANISH_STUDY_PARTICIPANT=1 nohup "$candidate" >/dev/null 2>&1 &)`,
-            "    sleep 3",
-            '    echo "humanish: opened $candidate"',
-            "    exit 0",
-            "  fi",
-            "done",
-            "echo 'humanish: no terminal emulator on this desktop template' >&2",
-            "exit 1"
-        ].join("\n"),
-        cwd: "/home/user",
-        timeoutMs: 60_000,
-        requestTimeoutMs
-    });
-    if (!result.ok) {
-        throw new Error("desktop-cli lane could not open a terminal on this desktop template");
-    }
-}
-export async function startDesktopStream(desktop, browserWindowId) {
-    if (!browserWindowId) {
-        await desktop.stream.start({ requireAuth: true });
-        return;
-    }
-    try {
-        await desktop.stream.start({ requireAuth: true, windowId: browserWindowId });
-    }
-    catch {
-        await desktop.stream.start({ requireAuth: true });
-    }
-}
-/**
- * Shared post-populate provisioning pipeline (clone AND local-tree routes): (install) ->
- * state(before-build) -> (build) -> state(before-start) -> detached start -> readiness probe ->
- * state(after-ready). Both provisioning routes populate SUBJECT_DIR by different means (git
- * clone vs. upload+extract) and then run this identical pipeline unchanged.
- *
- * State steps run through the same detached primitive as serve steps (author-trusted, the
- * "serve commands are author-trusted" corollary) under the reserved `subject-state-<name>`
- * label prefix, so a step name can never collide with subject-clone/subject-extract/install/
- * build/start. after-ready steps complete BEFORE the caller opens the browser: the actor never
- * drives a half-seeded subject and seeding never eats the session budget.
- */
-async function runSubjectServePipeline(desktop, args) {
-    const timers = {
-        ...(args.now === undefined ? {} : { now: args.now }),
-        ...(args.sleep === undefined ? {} : { sleep: args.sleep })
-    };
-    const now = args.now ?? Date.now;
-    const refresh = args.onPhaseComplete ?? (() => Promise.resolve());
-    const stateSteps = args.state?.seed ?? [];
-    const runStateSteps = async (when) => {
-        const steps = stateSteps.filter((step) => (step.when ?? "before-start") === when);
-        if (steps.length === 0) {
-            // No declared steps for this group: no boundary to report (avoids empty-group noise on
-            // every run, since before-build/before-start/after-ready are always called).
-            return;
-        }
-        const groupStartedAt = now();
-        emitPhaseStarted(args.onPhase, now, `state.${when}`, `running subject state seed steps (${when})`);
-        for (const step of steps) {
-            const stepTimeoutMs = step.timeoutMs ?? DEFAULT_STATE_STEP_TIMEOUT_MS;
-            const startedAt = now();
-            const result = await runDetachedStep(desktop, {
-                name: `subject-state-${step.name}`,
-                command: step.command,
-                cwd: SUBJECT_DIR,
-                timeoutMs: stepTimeoutMs,
-                requestTimeoutMs: args.requestTimeoutMs,
-                ...timers
-            });
-            args.onStateStep?.({
-                name: step.name,
-                when,
-                // Digest only (sha256-16): the command text never persists: the lab YAML in the
-                // consumer's repo is the plaintext source of truth.
-                commandDigest: commandDigestOf(step.command),
-                ok: result.ok,
-                ...(result.exitCode === undefined ? {} : { exitCode: result.exitCode }),
-                ...(result.timedOut ? { timedOut: true } : {}),
-                durationMs: Math.max(0, now() - startedAt)
-            });
-            if (!result.ok) {
-                emitPhaseCompleted(args.onPhase, now, groupStartedAt, `state.${when}`, false, `subject state seed steps failed (${when})`);
-                // Fail closed with the existing scrub-before-truncate tail chain: literal scrub of
-                // every provisioned value PRE-truncation, then pattern redaction + cap in tailOf.
-                throw new Error(`subject state step "${step.name}" ${result.timedOut ? `timed out after ${stepTimeoutMs}ms` : `failed (exit ${result.exitCode})`}: ${tailOf(args.scrub(result.logTail))}`);
-            }
-        }
-        emitPhaseCompleted(args.onPhase, now, groupStartedAt, `state.${when}`, true, `subject state seed steps complete (${when})`);
-    };
-    // Provide the runtime the pipeline needs before running it (#371). The stock desktop template
-    // ships python3 and curl but no Node, so an `npm install` here used to die at exit 127 after the
-    // sandbox was already paid for. Probe-first, so a template that ships its own Node pays nothing.
-    const serveCommands = [args.serve.install, args.serve.build, args.serve.start];
-    if (needsNodeRuntime(serveCommands)) {
-        const runtimeStartedAt = now();
-        emitPhaseStarted(args.onPhase, now, "runtime", "providing the Node runtime the serve pipeline needs");
-        const bootstrap = await runProvisioningStepWithOneRetry(desktop, {
-            name: "subject-runtime-node",
-            command: nodeBootstrapCommand(),
-            cwd: SUBJECT_DIR,
-            timeoutMs: args.serve.installTimeoutMs ?? INSTALL_TIMEOUT_MS,
-            requestTimeoutMs: args.requestTimeoutMs,
-            timers,
-            retryPhase: "runtime-retry",
-            retryMessage: "Node runtime bootstrap",
-            onPhase: args.onPhase,
-            now
-        });
-        let ok = bootstrap.ok;
-        const corepack = ok ? corepackCommandFor(serveCommands) : undefined;
-        if (corepack) {
-            const pm = await runDetachedStep(desktop, {
-                name: "subject-runtime-pm",
-                command: corepack,
-                cwd: SUBJECT_DIR,
-                timeoutMs: args.serve.installTimeoutMs ?? INSTALL_TIMEOUT_MS,
-                requestTimeoutMs: args.requestTimeoutMs,
-                ...timers
-            });
-            ok = pm.ok;
-        }
-        emitPhaseCompleted(args.onPhase, now, runtimeStartedAt, "runtime", ok, ok ? "Node runtime ready" : "could not provide a Node runtime");
-        if (!ok) {
-            throw new Error(`the subject's serve pipeline needs a Node runtime and this desktop template has none, and bootstrapping one failed${bootstrap.attempts === 2 ? " twice" : ""}: ${tailOf(args.scrub(bootstrap.logTail))}. Use execution.desktop.template with an image that ships Node, or change serve.install to a runtime the template provides.`);
-        }
-    }
-    if (args.serve.install) {
-        const installStartedAt = now();
-        emitPhaseStarted(args.onPhase, now, "install", "installing subject dependencies");
-        const install = await runProvisioningStepWithOneRetry(desktop, {
-            name: "subject-install",
-            command: args.serve.install,
-            cwd: SUBJECT_DIR,
-            timeoutMs: args.serve.installTimeoutMs ?? INSTALL_TIMEOUT_MS,
-            requestTimeoutMs: args.requestTimeoutMs,
-            timers,
-            retryPhase: "install-retry",
-            retryMessage: "subject install",
-            onPhase: args.onPhase,
-            now
-        });
-        emitPhaseCompleted(args.onPhase, now, installStartedAt, "install", install.ok, install.ok
-            ? install.attempts === 2
-                ? "subject dependencies installed (on the second attempt)"
-                : "subject dependencies installed"
-            : install.attempts === 2
-                ? "subject install failed twice"
-                : "subject install failed");
-        if (!install.ok) {
-            // Lead with the line a person can act on; npm's own trace follows it (#602).
-            const headline = install.timedOut
-                ? `subject install timed out after ${args.serve.installTimeoutMs ?? INSTALL_TIMEOUT_MS}ms`
-                : install.attempts === 2
-                    ? `subject install failed twice (exit ${install.firstExitCode ?? "null"}, then exit ${install.exitCode ?? "null"}); the sandbox could not complete serve.install`
-                    : `subject install failed (exit ${install.exitCode ?? "null"})`;
-            throw new Error(`${headline}: ${tailOf(args.scrub(install.logTail))}`);
-        }
-        await refresh();
-    }
-    // before-build: after install, before build (builds that read seeded state, e.g. SSG).
-    // When no build is declared this simply precedes start: equivalent to before-start.
-    await runStateSteps("before-build");
-    await refresh();
-    if (args.serve.build) {
-        const buildStartedAt = now();
-        emitPhaseStarted(args.onPhase, now, "build", "building subject");
-        const build = await runDetachedStep(desktop, {
-            name: "subject-build",
-            command: args.serve.build,
-            cwd: SUBJECT_DIR,
-            timeoutMs: args.serve.buildTimeoutMs ?? BUILD_TIMEOUT_MS,
-            requestTimeoutMs: args.requestTimeoutMs,
-            ...timers
-        });
-        emitPhaseCompleted(args.onPhase, now, buildStartedAt, "build", build.ok, build.ok ? "subject build complete" : "subject build failed");
-        if (!build.ok) {
-            throw new Error(`subject build ${build.timedOut ? "timed out" : `failed (exit ${build.exitCode})`}: ${tailOf(args.scrub(build.logTail))}`);
-        }
-        await refresh();
-    }
-    // before-start (the default phase): migrations, SQL/file fixtures, an in-sandbox DB server
-    // (`sudo service postgresql start && pg_isready` is a bounded step; the daemon it forks is
-    // reclaimed by the sandbox lifecycle like everything else).
-    await runStateSteps("before-start");
-    await refresh();
-    await startDetachedProcess(desktop, {
-        name: "subject-start",
-        command: args.serve.start,
-        cwd: SUBJECT_DIR,
-        requestTimeoutMs: args.requestTimeoutMs
-    });
-    // Fire-and-forget: startDetachedProcess never waits for the long-lived server to exit, so
-    // there is no matching completed event here (no ok/durationMs to report yet); readiness is
-    // the next boundary.
-    args.onPhase?.({ at: isoNow(now), type: "cua-lab.subject.serve.started", message: "subject server launched (detached)" });
-    const readyStartedAt = now();
-    emitPhaseStarted(args.onPhase, now, "ready", "waiting for subject to become ready");
-    const ready = await probeUrl(desktop, args.serve.url, {
-        timeoutMs: args.serve.readyTimeoutMs ?? DEFAULT_READY_TIMEOUT_MS,
-        requestTimeoutMs: args.requestTimeoutMs,
-        ...timers
-    });
-    emitPhaseCompleted(args.onPhase, now, readyStartedAt, "ready", ready, ready ? "subject is ready" : "subject did not become ready in time");
-    if (!ready) {
-        const startLog = await readDetachedLog(desktop, "subject-start", args.requestTimeoutMs).catch(() => "");
-        throw new Error(`subject did not answer at ${args.serve.url} within ${args.serve.readyTimeoutMs ?? DEFAULT_READY_TIMEOUT_MS}ms; server log tail: ${tailOf(args.scrub(startLog))}`);
-    }
-    // after-ready: fixture loading through the RUNNING app (loopback curl from in-sandbox:
-    // steps are author-trusted provisioning, not actors, so no new URL policy surface). These
-    // complete before the caller opens the browser and the session timer starts.
-    await runStateSteps("after-ready");
-    await refresh();
-}
-/**
- * Provision a clone subject inside the sandbox: clone → the shared serve pipeline
- * (install → state(before-build) → build → state(before-start) → start → readiness
- * probe → state(after-ready)). Returns the latest subject HEAD after successful
- * provisioning. Throws (with a capped log tail for the caller to redact) on any failing step:
- * the lab persists that as a failed-evidence bundle.
- *
- * Auth: when GITHUB_TOKEN is among the declared subject env names, the clone authenticates
- * via an Authorization header computed IN-SANDBOX from the provisioned env: the token never
- * appears in the script text, the process argv beyond the transient git call, the clone URL,
- * or .git/config.
- */
-export async function provisionCloneSubject(desktop, args) {
-    const timers = {
-        ...(args.now === undefined ? {} : { now: args.now }),
-        ...(args.sleep === undefined ? {} : { sleep: args.sleep })
-    };
-    const now = args.now ?? Date.now;
-    let latestCommit;
-    const refreshCommit = async () => {
-        const head = await desktop.commands.run(`git -C ${SUBJECT_DIR} rev-parse HEAD 2>/dev/null || true`, { requestTimeoutMs: args.requestTimeoutMs });
-        const commit = (head.stdout ?? "").trim() || undefined;
-        if (commit) {
-            latestCommit = commit;
-            args.onCommit?.(commit);
-        }
-    };
-    const cloneCommand = args.hasGithubToken
-        ? `auth=$(printf 'x-access-token:%s' "$GITHUB_TOKEN" | base64 -w0) && git -c http.extraHeader="Authorization: Basic $auth" clone --depth ${args.depth} https://github.com/${args.repo}.git ${SUBJECT_DIR}`
-        : `git clone --depth ${args.depth} https://github.com/${args.repo}.git ${SUBJECT_DIR}`;
-    const cloneStartedAt = now();
-    emitPhaseStarted(args.onPhase, now, "clone", "cloning subject repository");
-    const clone = await runDetachedStep(desktop, {
-        name: "subject-clone",
-        command: cloneCommand,
-        timeoutMs: CLONE_TIMEOUT_MS,
-        requestTimeoutMs: args.requestTimeoutMs,
-        ...timers
-    });
-    emitPhaseCompleted(args.onPhase, now, cloneStartedAt, "clone", clone.ok, clone.ok ? "subject repository cloned" : "subject clone failed");
-    if (!clone.ok) {
-        throw new Error(`subject clone ${clone.timedOut ? "timed out" : `failed (exit ${clone.exitCode})`}: ${tailOf(args.scrub(clone.logTail))}`);
-    }
-    await refreshCommit();
-    await runSubjectServePipeline(desktop, {
-        serve: args.serve,
-        ...(args.state === undefined ? {} : { state: args.state }),
-        requestTimeoutMs: args.requestTimeoutMs,
-        scrub: args.scrub,
-        ...(args.onStateStep === undefined ? {} : { onStateStep: args.onStateStep }),
-        ...(args.onPhase === undefined ? {} : { onPhase: args.onPhase }),
-        onPhaseComplete: refreshCommit,
-        ...timers
-    });
-    return latestCommit;
-}
-/**
- * Provision a local-tree subject inside the sandbox: upload the once-per-run packed archive
- * (identical bytes across every fan-out lane) → extract it into SUBJECT_DIR → the
- * same shared serve pipeline provisionCloneSubject uses. Unlike the clone route there is no
- * in-sandbox git refresh: the archive excludes .git entirely (see source-archive.ts), so
- * subject identity is the host-side LocalTreeArchive captured at pack time, never anything
- * resolved in-sandbox.
- */
-export async function provisionLocalTreeSubject(desktop, args) {
-    const timers = {
-        ...(args.now === undefined ? {} : { now: args.now }),
-        ...(args.sleep === undefined ? {} : { sleep: args.sleep })
-    };
-    const now = args.now ?? Date.now;
-    const uploadStartedAt = now();
-    emitPhaseStarted(args.onPhase, now, "upload", "uploading packed local-tree archive");
-    try {
-        await withOneRetryOnTransientE2BError(() => desktop.files.write(LOCAL_TREE_REMOTE_ARCHIVE_PATH, args.archiveBuffer, {
-            requestTimeoutMs: args.requestTimeoutMs,
-            useOctetStream: true
-        }), {
-            onRetry: (reason) => emitPhaseStarted(args.onPhase, now, "upload-retry", `local-tree archive upload retried once (${tailOf(args.scrub(reason))})`),
-            ...(args.sleep === undefined ? {} : { sleep: args.sleep })
-        });
-    }
-    catch (error) {
-        emitPhaseCompleted(args.onPhase, now, uploadStartedAt, "upload", false, "local-tree archive upload failed");
-        throw new Error(`subject-upload failed: ${tailOf(args.scrub(toErrorMessage(error)))}`);
-    }
-    emitPhaseCompleted(args.onPhase, now, uploadStartedAt, "upload", true, "local-tree archive uploaded");
-    const extractCommand = `rm -rf ${SUBJECT_DIR} && mkdir -p ${SUBJECT_DIR} && tar -xzf ${LOCAL_TREE_REMOTE_ARCHIVE_PATH} -C ${SUBJECT_DIR} && rm -f ${LOCAL_TREE_REMOTE_ARCHIVE_PATH}`;
-    const extractStartedAt = now();
-    emitPhaseStarted(args.onPhase, now, "extract", "extracting local-tree archive");
-    const extract = await runDetachedStep(desktop, {
-        name: "subject-extract",
-        command: extractCommand,
-        timeoutMs: CLONE_TIMEOUT_MS,
-        requestTimeoutMs: args.requestTimeoutMs,
-        ...timers
-    });
-    emitPhaseCompleted(args.onPhase, now, extractStartedAt, "extract", extract.ok, extract.ok ? "local-tree archive extracted" : "local-tree archive extraction failed");
-    if (!extract.ok) {
-        throw new Error(`subject extract ${extract.timedOut ? "timed out" : `failed (exit ${extract.exitCode})`}: ${tailOf(args.scrub(extract.logTail))}`);
-    }
-    await runSubjectServePipeline(desktop, {
-        serve: args.serve,
-        ...(args.state === undefined ? {} : { state: args.state }),
-        requestTimeoutMs: args.requestTimeoutMs,
-        scrub: args.scrub,
-        ...(args.onStateStep === undefined ? {} : { onStateStep: args.onStateStep }),
-        ...(args.onPhase === undefined ? {} : { onPhase: args.onPhase }),
-        ...timers
-    });
-}
-/** sha256 hex of the exact command string, first 16 chars (the promptDigest convention). */
-export function commandDigestOf(command) {
-    return digestText(command, 16);
-}
-// The in-sandbox `tail -c` upstream is a fundamental log-tail limit we cannot redact past.
-function tailOf(log) {
-    return redactedTail(log, ERROR_TAIL_CHARS);
-}
-//# sourceMappingURL=e2b-cua-provisioning.js.map