humanish 0.74.0 → 0.76.0

package/dist/cua-actor-lab.js

@@ -46,6 +46,7 @@ import { appendSandboxReceipt } from "./sandbox-receipts.js";
 import { assertScreenshotEvidence } from "./image-evidence.js";
 import { buildObserverData } from "./observer-data.js";
 import { corepackCommandFor, needsNodeRuntime, nodeBootstrapCommand } from "./subject-runtime.js";
+import { chromeCdpProbeCommand, parseChromeCdpProbeOutput } from "./chrome-cdp-probe.js";
 import { personaToDirectives, renderPersonaPromptSection } from "./persona.js";
 import { labPersonaIds, resolveCommittedPersonas } from "./persona-resolve.js";
 import { renderTaskPrompt } from "./tasks.js";
@@ -505,6 +506,37 @@ 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 });
 }
@@ -704,10 +736,13 @@ async function fillDesktopBrowserWindow(desktop, windowId, resolution, requestTi
     })
         .catch(() => undefined);
 }
-async function openDesktopBrowserTarget(desktop, targetUrl, requestTimeoutMs, browserPreference) {
+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 = []) {
     const requestedBrowser = browserPreference ?? "default";
     if (isHttpUrl(targetUrl)) {
-        const chromiumFlags = CHROMIUM_EVIDENCE_HYGIENE_FLAGS.map(shellSingleQuote).join(" ");
+        const chromiumFlags = [...CHROMIUM_EVIDENCE_HYGIENE_FLAGS, ...extraChromiumFlags].map(shellSingleQuote).join(" ");
         const browserLaunchCommand = [
             "set -euo pipefail",
             `target_url=${shellSingleQuote(targetUrl)}`,
@@ -839,164 +874,145 @@ export function desktopBrowserFamily(value) {
     return "unknown";
 }
 /**
- * Observe-time CDP port resolution lines (pure; exported for contract tests): cached
- * launch-time port first, then a re-read of the profile's DevToolsActivePort marker, then the
- * legacy fixed 9222. The re-read is a local best-effort file read inside the already
- * time-bounded observer command, so a missing/garbled marker degrades to the fallback,
- * never a hang.
- */
-export function chromeCdpPortResolutionScript(endpoint) {
-    return [
-        `let cdpPort = ${endpoint.cdpPort === undefined ? "undefined" : JSON.stringify(endpoint.cdpPort)};`,
-        `const cdpProfileDir = ${JSON.stringify(endpoint.profileDir ?? "")};`,
-        "if (cdpPort === undefined && cdpProfileDir) {",
-        "  try {",
-        "    const { readFileSync } = await import('node:fs');",
-        "    const marker = readFileSync(cdpProfileDir + '/DevToolsActivePort', 'utf8');",
-        "    const parsed = Number.parseInt(String(marker.split('\\n')[0] ?? ''), 10);",
-        "    if (Number.isInteger(parsed) && parsed > 0) cdpPort = parsed;",
-        "  } catch {}",
-        "}",
-        "if (cdpPort === undefined) cdpPort = 9222;"
-    ];
-}
-/** Shared CDP page-selection preamble: pinned target id first, then this lane's target URL,
- *  then a single-page fallback; never an arbitrary page from a multi-page endpoint. */
-function chromeCdpPageSelectionScript(endpoint, targetId, 
-/**
- * "pinned" (default): the launch-time target, for measurements about the ORIGINAL window
- * (geometry). "active": the tab the participant is driving NOW — Chrome's /json lists page
- * targets most-recently-focused first. The state observer must follow the participant: a
- * verification link that opens in a NEW tab left the pinned observer reading the old tab
- * forever, so the observed URL never changed again and stopWhen/task criteria went blind
- * (a live run's funnel read reach-dashboard 0/2 under a screenshot OF the dashboard).
+ * 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).
  */
-prefer = "pinned") {
-    return [
-        ...chromeCdpPortResolutionScript(endpoint),
-        "const pages = await fetch('http://127.0.0.1:' + cdpPort + '/json').then((r) => r.json()).catch(() => []);",
-        `const expectedTargetId = ${JSON.stringify(targetId ?? "")};`,
-        `const expectedTargetUrl = ${JSON.stringify(endpoint.targetUrl)};`,
-        "const normalizeUrl = (value) => String(value || '').replace(/\\/$/, '');",
-        "const httpPages = Array.isArray(pages) ? pages.filter((entry) => entry && entry.type === 'page' && /^https?:/.test(String(entry.url || ''))) : [];",
-        prefer === "active"
-            ? "const page = httpPages[0] || (expectedTargetId ? httpPages.find((entry) => entry.id === expectedTargetId) : undefined);"
-            : "const page = expectedTargetId ? httpPages.find((entry) => entry.id === expectedTargetId) : (httpPages.find((entry) => normalizeUrl(entry.url) === normalizeUrl(expectedTargetUrl)) || (httpPages.length === 1 ? httpPages[0] : undefined));"
-    ];
-}
-export function makeChromeBrowserStateObserver(desktop, requestTimeoutMs, endpoint, targetId) {
+export function makeChromeBrowserStateObserver(desktop, requestTimeoutMs, endpoint, targetId, onUnavailable) {
+    let reported = false;
+    const unavailable = (reason) => {
+        if (!reported) {
+            reported = true;
+            onUnavailable?.(reason);
+        }
+        return {};
+    };
     return async () => {
-        const script = [
-            // "active": follow the participant to whatever tab they are driving now — never pin the
-            // state observer to the launch tab (see chromeCdpPageSelectionScript).
-            ...chromeCdpPageSelectionScript(endpoint, targetId, "active"),
-            "if (!page) { console.log('{}'); process.exit(0); }",
-            "let text = '';",
-            "let scrollY = undefined;",
-            "let url = String(page.url || '');",
-            "let title = String(page.title || '');",
-            "if (typeof WebSocket === 'function' && page.webSocketDebuggerUrl) {",
-            "  const ws = new WebSocket(page.webSocketDebuggerUrl);",
-            "  const result = await new Promise((resolve) => {",
-            "    const timer = setTimeout(() => resolve(undefined), 1500);",
-            "    ws.onopen = () => ws.send(JSON.stringify({ id: 1, method: 'Runtime.evaluate', params: { returnByValue: true, expression: '({ url: location.href, title: document.title, text: (document.body && document.body.innerText || \"\").slice(0, 20000), scrollY: (window.scrollY || 0) })' } }));",
-            "    ws.onmessage = (event) => {",
-            "      try {",
-            "        const payload = JSON.parse(String(event.data));",
-            "        if (payload.id !== 1) return;",
-            "        clearTimeout(timer);",
-            "        resolve(payload.result && payload.result.result && payload.result.result.value);",
-            "      } catch { clearTimeout(timer); resolve(undefined); }",
-            "    };",
-            "    ws.onerror = () => { clearTimeout(timer); resolve(undefined); };",
-            "  }).finally(() => { try { ws.close(); } catch {} });",
-            "  if (result && typeof result === 'object') {",
-            "    url = typeof result.url === 'string' ? result.url : url;",
-            "    title = typeof result.title === 'string' ? result.title : title;",
-            "    text = typeof result.text === 'string' ? result.text : '';",
-            "    scrollY = typeof result.scrollY === 'number' ? result.scrollY : undefined;",
-            "  }",
-            "}",
-            "console.log(JSON.stringify({ url, title, text, scrollY }));"
-        ].join("\n");
-        const result = await desktop.commands.run(`node --input-type=module -e ${shellSingleQuote(script)}`, {
-            requestTimeoutMs,
-            timeoutMs: 5_000
-        });
+        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 {};
-        }
-        try {
-            const parsed = JSON.parse((result.stdout ?? "{}").trim() || "{}");
-            if (!parsed || typeof parsed !== "object") {
-                return {};
-            }
-            const record = parsed;
-            return {
-                ...(typeof record.url === "string" && record.url.length > 0 ? { url: record.url } : {}),
-                ...(typeof record.title === "string" && record.title.length > 0 ? { title: record.title } : {}),
-                ...(typeof record.text === "string" && record.text.length > 0 ? { text: record.text } : {}),
-                ...(typeof record.scrollY === "number" && Number.isFinite(record.scrollY) ? { scrollY: record.scrollY } : {})
-            };
-        }
-        catch {
-            return {};
+            return unavailable(`probe exited ${result.exitCode}: ${tailOf(result.stderr ?? result.stdout ?? "")}`);
         }
+        const parsed = parseChromeCdpProbeOutput(result.stdout);
+        if (parsed.unavailable !== undefined)
+            return unavailable(parsed.unavailable);
+        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.
+ * `undefined` carries the reason the measurement is missing via `onUnavailable`, so the geometry
+ * warning can name the cause (a dead CDP endpoint, no python3) instead of only the symptom.
  */
-export function makeChromeDesktopGeometryObserver(desktop, requestTimeoutMs, endpoint, targetId) {
+export function makeChromeDesktopGeometryObserver(desktop, requestTimeoutMs, endpoint, targetId, onUnavailable) {
     return async () => {
-        const script = [
-            ...chromeCdpPageSelectionScript(endpoint, targetId),
-            "if (!page || typeof WebSocket !== 'function' || !page.webSocketDebuggerUrl) { console.log('{}'); process.exit(0); }",
-            "const ws = new WebSocket(page.webSocketDebuggerUrl);",
-            "const result = await new Promise((resolve) => {",
-            "  const timer = setTimeout(() => resolve(undefined), 1500);",
-            "  ws.onopen = () => ws.send(JSON.stringify({ id: 1, method: 'Runtime.evaluate', params: { returnByValue: true, expression: '({ browserWindow: { x: window.screenX, y: window.screenY, width: window.outerWidth, height: window.outerHeight }, viewport: { width: window.innerWidth, height: window.innerHeight, deviceScaleFactor: window.devicePixelRatio } })' } }));",
-            "  ws.onmessage = (event) => {",
-            "    try {",
-            "      const payload = JSON.parse(String(event.data));",
-            "      if (payload.id !== 1) return;",
-            "      clearTimeout(timer);",
-            "      resolve(payload.result && payload.result.result && payload.result.result.value);",
-            "    } catch { clearTimeout(timer); resolve(undefined); }",
-            "  };",
-            "  ws.onerror = () => { clearTimeout(timer); resolve(undefined); };",
-            "}).finally(() => { try { ws.close(); } catch {} });",
-            "console.log(JSON.stringify(result ? { ...result, targetId: String(page.id || '') } : {}));"
-        ].join("\n");
-        const result = await desktop.commands.run(`node --input-type=module -e ${shellSingleQuote(script)}`, {
-            requestTimeoutMs,
-            timeoutMs: 5_000
-        });
+        const result = await desktop.commands.run(chromeCdpProbeCommand({ ...endpoint, ...(targetId === undefined ? {} : { targetId }), prefer: "pinned", 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;
         }
-        try {
-            const parsed = JSON.parse((result.stdout ?? "{}").trim() || "{}");
-            if (!parsed || typeof parsed !== "object")
-                return undefined;
-            const record = parsed;
-            const rawWindow = record.browserWindow;
-            const rawViewport = record.viewport;
-            if (!isMeasuredRect(rawWindow) || !isMeasuredViewport(rawViewport))
-                return undefined;
-            return {
-                browserWindow: { ...rawWindow, source: "cdp" },
-                viewport: { ...rawViewport, source: "cdp" },
-                ...(typeof record.targetId === "string" && record.targetId.length > 0 ? { targetId: record.targetId } : {})
-            };
+        const parsed = parseChromeCdpProbeOutput(result.stdout);
+        if (parsed.unavailable !== undefined) {
+            onUnavailable?.(parsed.unavailable);
+            return undefined;
         }
-        catch {
+        if (!isMeasuredRect(parsed.browserWindow) || !isMeasuredViewport(parsed.viewport)) {
+            onUnavailable?.("the page reported no usable window or viewport dimensions");
             return undefined;
         }
+        return {
+            browserWindow: { ...parsed.browserWindow, source: "cdp" },
+            viewport: { ...parsed.viewport, source: "cdp" },
+            ...(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;
+    const warnings = [];
+    // 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
+    };
+    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 };
+    }
+    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 };
+}
 function isMeasuredRect(value) {
     if (!value || typeof value !== "object")
         return false;
@@ -1063,25 +1079,37 @@ export async function captureDesktopBrowserGeometry(args) {
     else {
         warnings.push(`Browser window bounds could not be measured for lane ${args.laneId}; the live stream will use the full desktop.`);
     }
+    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)().catch(() => undefined)
+        }, args.browserTargetId, (reason) => {
+            cdpUnavailable = reason;
+        })().catch((error) => {
+            cdpUnavailable = toErrorMessage(error);
+            return undefined;
+        })
         : undefined;
     const browserWindow = chromeGeometry?.browserWindow ?? xdotoolWindow;
     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 = xdotoolWindow ?? browserWindow;
     if (!browserWindow) {
         warnings.push(`Browser outer bounds could not be measured for lane ${args.laneId}.`);
     }
-    else if (browserWindow.width !== args.requestedScreen[0] || browserWindow.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 outer bounds are ${browserWindow.width}x${browserWindow.height}.`);
+    else if (fillBounds !== undefined && (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 outer bounds are ${fillBounds.width}x${fillBounds.height}.`);
     }
     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.`);
+            : `Browser CSS viewport could not be measured for lane ${args.laneId}; stream.viewport is omitted instead of copying the requested screen resolution.${cause}`);
     }
     return {
         ...(browserWindowId === undefined ? {} : { browserWindowId }),
@@ -1216,8 +1244,17 @@ function hasBlockerLanguage(text) {
 // study completed without a participant-reported finding". Friction is the INCLUSIVE scan; a
 // false positive here adds a candidate a person then reads, which is the cheap direction.
 const REPORTED_DEFECT_LANGUAGE = /\b(defects?|bugs?|accessibilit(y|ies)|inaccessible|not (keyboard|screen.?reader)[- ]?accessible|confus(ed|ing)|hesitat(ed|ion)|unexpected(ly)?|unclear|hard to (find|tell|see|read|reach)|no (visible )?focus|overlap(ped|ping|s)?|truncat(ed|es|ion)|cut off|did nothing|nothing happened|no effect)\b/;
+// The friction scan's own negations (#614). "Nothing was confusing", "no defects", "not unclear"
+// are what a participant writes when it has NOTHING to report, and until 2026-09-03 each of them
+// counted as reported friction and became a feedback candidate whose "actual" was a sentence
+// reporting no problem. Only the report-shaped adjectives are negatable here: "no visible focus",
+// "not keyboard-accessible" and "did nothing" are defects and stay.
+const NEGATED_REPORT_LANGUAGE = /\b(?:nothing|no|not|never|without|none)\s+(?:was\s+|were\s+|felt\s+|seemed\s+|really\s+|particularly\s+|especially\s+|major\s+|real\s+|obvious\s+|noticeable\s+)*(?:confus(?:ed|ing|ion)|unclear|unexpected(?:ly)?|hesitat(?:ed|ion|ions)|surpris(?:ed|ing|es)|defects?|bugs?|overlap(?:ped|ping|s)?|truncat(?:ed|es|ion)|hard to (?:find|tell|see|read|reach))\b/g;
+function stripNegatedReportLanguage(text) {
+    return text.replace(NEGATED_REPORT_LANGUAGE, " ");
+}
 function completionReasonContradictsGoal(reason) {
-    const text = stripQuotedSpans(stripNegatedNonBlockerPhrases(reason.toLowerCase()));
+    const text = stripQuotedSpans(stripNegatedReportLanguage(stripNegatedNonBlockerPhrases(reason.toLowerCase())));
     return hasBlockerLanguage(text) || REPORTED_DEFECT_LANGUAGE.test(text);
 }
 /** The verdict scan (strict): like the friction scan, but resolved-arc segments are stripped
@@ -1422,6 +1459,7 @@ export async function runCuaLane(spec, deps) {
     let browserLaunchIdentity;
     let browserLaunched = false;
     let initialBrowserGeometry;
+    let appliedFidelity;
     let browserWindowId;
     let browserTargetId;
     const declaredScreen = declaredScreenForRender(spec.devicePreset, spec.deviceName, spec.resolution);
@@ -1613,12 +1651,44 @@ export async function runCuaLane(spec, deps) {
                 });
             }
             if (!desktopCliRoute) {
-                const browserLaunch = await openDesktopBrowserTarget(desktop, targetUrl, deps.requestTimeoutMs, config.execution?.desktop?.browser);
+                const requestedFidelity = config.execution?.desktop?.fidelity;
+                const browserLaunch = await openDesktopBrowserTarget(desktop, targetUrl, deps.requestTimeoutMs, config.execution?.desktop?.browser, requestedFidelity?.mobileEmulation && spec.devicePreset.isMobile
+                    ? [
+                        `--user-agent=${requestedFidelity.userAgent ?? DEFAULT_MOBILE_USER_AGENT}`,
+                        ...(requestedFidelity.touch === false ? [] : ["--touch-events=enabled"])
+                    ]
+                    : []);
                 desktopBrowser = browserLaunch.evidence;
                 launchedBrowserFamily = browserLaunch.family;
                 browserLaunchIdentity = browserLaunch.identity;
                 browserLaunched = true;
                 await desktop.wait(BROWSER_SETTLE_MS).catch(() => undefined);
+                // Mobile fidelity beyond viewport size (#221): applied to the launch page before the
+                // geometry capture and the participant's first observation, OUTSIDE the stream/geometry
+                // try below (whose catch degrades to a warning): a request that cannot be applied fails
+                // the lane closed with the reason.
+                // Only lanes on a mobile preset are emulated: a run-wide flag must not hand a desktop or
+                // tablet lane an iPhone user agent (the first live proof did exactly that to the desktop
+                // newcomer beside the phone lane). Those lanes carry no fidelity block, which is honest.
+                const fidelityRequest = config.execution?.desktop?.fidelity;
+                if (fidelityRequest?.mobileEmulation && spec.devicePreset.isMobile) {
+                    if (launchedBrowserFamily !== "chromium") {
+                        throw new Error(`execution.desktop.fidelity.mobileEmulation needs Chrome or Chromium on lane ${spec.laneId}; the launched browser family is ${launchedBrowserFamily}. Set execution.desktop.browser: chrome.`);
+                    }
+                    const applied = await applyMobileEmulation(desktop, deps.requestTimeoutMs, {
+                        ...(browserLaunchIdentity?.cdpPort === undefined ? {} : { cdpPort: browserLaunchIdentity.cdpPort }),
+                        ...(browserLaunchIdentity?.profileDir === undefined ? {} : { profileDir: browserLaunchIdentity.profileDir }),
+                        targetUrl
+                    }, browserTargetId, {
+                        width: spec.devicePreset.width,
+                        height: spec.devicePreset.height,
+                        deviceScaleFactor: fidelityRequest.deviceScaleFactor ?? spec.devicePreset.deviceScaleFactor,
+                        touch: fidelityRequest.touch ?? true,
+                        userAgent: fidelityRequest.userAgent ?? DEFAULT_MOBILE_USER_AGENT
+                    });
+                    appliedFidelity = applied.fidelity;
+                    warnings.push(...applied.warnings);
+                }
             }
             else {
                 // A terminal window, opened the way the browser is opened on every other route: the
@@ -1752,7 +1822,13 @@ export async function runCuaLane(spec, deps) {
                                 ...(browserLaunchIdentity?.cdpPort === undefined ? {} : { cdpPort: browserLaunchIdentity.cdpPort }),
                                 ...(browserLaunchIdentity?.profileDir === undefined ? {} : { profileDir: browserLaunchIdentity.profileDir }),
                                 targetUrl
-                            }, browserTargetId)
+                            }, browserTargetId, 
+                            // Once per lane: a dark observation channel is a gap in the instrument, and the
+                            // funnel's NEVER MEASURED count needs this line to explain itself (#514).
+                            (reason) => {
+                                warnings.push(`Browser-state observer unavailable for lane ${spec.laneId} (${redactText(deps.scrubKnownValues(reason))}); ` +
+                                    "urlIncludes/urlPathEquals/textIncludes stop conditions and task criteria are NOT being measured this session.");
+                            })
                         }
                     }
                     : {}),
@@ -1837,6 +1913,7 @@ export async function runCuaLane(spec, deps) {
                     screen: desktopGeometry.screen,
                     ...(chosenGeometry.browserWindow === undefined ? {} : { browserWindow: chosenGeometry.browserWindow }),
                     ...(chosenGeometry.viewport === undefined ? {} : { viewport: chosenGeometry.viewport }),
+                    ...(appliedFidelity === undefined ? {} : { fidelity: appliedFidelity }),
                     ...((desktopGeometry.warnings?.length ?? 0) + geometryWarnings.length === 0
                         ? {}
                         : { warnings: [...(desktopGeometry.warnings ?? []), ...geometryWarnings] })
@@ -3288,13 +3365,17 @@ async function runSubjectServePipeline(desktop, args) {
     if (needsNodeRuntime(serveCommands)) {
         const runtimeStartedAt = now();
         emitPhaseStarted(args.onPhase, now, "runtime", "providing the Node runtime the serve pipeline needs");
-        const bootstrap = await runDetachedStep(desktop, {
+        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
+            timers,
+            retryPhase: "runtime-retry",
+            retryMessage: "Node runtime bootstrap",
+            onPhase: args.onPhase,
+            now
         });
         let ok = bootstrap.ok;
         const corepack = ok ? corepackCommandFor(serveCommands) : undefined;
@@ -3311,23 +3392,39 @@ async function runSubjectServePipeline(desktop, args) {
         }
         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: ${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.`);
+            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 runDetachedStep(desktop, {
+        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
+            timers,
+            retryPhase: "install-retry",
+            retryMessage: "subject install",
+            onPhase: args.onPhase,
+            now
         });
-        emitPhaseCompleted(args.onPhase, now, installStartedAt, "install", install.ok, install.ok ? "subject dependencies installed" : "subject install failed");
+        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) {
-            throw new Error(`subject install ${install.timedOut ? "timed out" : `failed (exit ${install.exitCode})`}: ${tailOf(args.scrub(install.logTail))}`);
+            // 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();
     }