humanish 0.0.1 → 0.15.0

package/dist/cua-actor-lab.js

@@ -0,0 +1,2834 @@
+// The computer-use lab backend: a subject (an app-url the caller provisioned, or a repo the
+// lab clones AND serves in-sandbox) driven by a REGISTRY-RESOLVED computer-use actor inside a
+// hosted E2B desktop. This is the path that makes `actors[].type` load-bearing — the
+// descriptor returned by the registry runs the session; the lab provisions the desktop and
+// subject, composes the prompt from config, persists the evidence bundle, and tears down.
+//
+// Substrate notes:
+// - The desktop is created via the shared loader in e2b-desktop-launch.ts with kill-on-timeout
+//   lifecycle, so a dead host process can never orphan a sandbox past its server-side deadline.
+// - Env placement follows the doctrine (docs/principles/invariants-and-defaults.md): the
+//   ACTOR's key never enters the sandbox (the model drives from outside via the provider API);
+//   the SUBJECT's declared env NAMES are provisioned in on the clone route — values come from
+//   the caller's environment and are never logged or persisted.
+// - The live stream URL is runtime-only (carries an auth key) and is never persisted into run
+//   artifacts — only its presence is recorded, mirroring the meta lab's convention.
+// - Evidence redaction is mode-aware (docs/principles/invariants-and-defaults.md, the
+//   capture-vs-publish rule): screenshots persist RAW (full fidelity) by default into gitignored
+//   .humanish/; `policies.redactScreenshots: true` opts into blur-at-capture for a share-as-is
+//   bundle. Length-only typed text and text redaction of reasoning/messages are UNCONDITIONAL;
+//   harness errors are redacted at THIS boundary; the bundle's `stream.actor` carries the
+//   conformant humanish.actor-trace.v1 projection, whose `redaction.screenshots` records the
+//   run's actual mode ("raw" | "blurred" | "n/a") — every label downstream derives from it.
+import { randomBytes } from "node:crypto";
+import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { runDesktopCommandOrThrow, toErrorMessage } from "./command-failure.js";
+import { pathToFileURL } from "node:url";
+import { adapterScoreFailureMessage, applyBrowserAdapterHooks } from "./adapter-extension.js";
+import { actorRegistry, isCuaActorDescriptor } from "./actor-registry.js";
+import { CHROMIUM_EVIDENCE_HYGIENE_FLAGS, chromiumEvidenceProfilePreferencesJson } from "./browser-evidence-hygiene.js";
+import { createDesktopSandbox, loadE2BDesktopModule } from "./e2b-desktop-launch.js";
+import { probeUrl, readDetachedLog, runDetachedStep, startDetachedProcess } from "./e2b-detached.js";
+import { DEFAULT_DEVICE_PRESET, isDevicePresetName, resolveDevicePreset } from "./device-presets.js";
+import { cuaLaneValidationReason, isHttpUrl, isLoopbackUrl, MAX_CUA_LANES, subjectStateInvalidReason } from "./lab-config.js";
+import { mapWithConcurrency } from "./concurrency.js";
+import { assertScreenshotEvidence } from "./image-evidence.js";
+import { buildObserverData } from "./observer-data.js";
+import { attachObserverRuntimeStreamUrls, renderObserver } from "./observer.js";
+import { containsSensitive, digestText, redactedTail, redactText } from "./redaction.js";
+import { createLocalTreeArchive } from "./source-archive.js";
+import { buildRunSource, loadRunBundle, PUBLIC_TARGET_CWD, REVIEW_SCHEMA, RUN_BUNDLE_SCHEMA } from "./run.js";
+export const CUA_ACTOR_LAB_SCHEMA = "humanish.cua-lab-result.v2";
+// The only fan-out topology this slice ships: N lanes = N independent E2B desktop sandboxes,
+// each its own world (clone/serve + subject.state per lane). Shared-world is layer 7 (#164).
+export const CUA_FANOUT_STRATEGY = "per-lane-worlds";
+// Default in-flight lane bound when the config does not declare execution.concurrency.
+const DEFAULT_CUA_CONCURRENCY = 3;
+// Env override that may only LOWER the effective concurrency (never raise concurrent paid
+// desktops — invariant 3). Read names-only into a local; the value never persists.
+const CUA_MAX_CONCURRENCY_ENV = "HUMANISH_CUA_MAX_CONCURRENCY";
+export const CUA_ACTOR_LAB_PROVIDER_METADATA = {
+    mode: "cua-actor-lab",
+    tool: "humanish"
+};
+const DEFAULT_SESSION_TIMEOUT_MS = 300_000;
+// 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).
+const BROWSER_SETTLE_MS = 8_000;
+// Device/viewport comes from the named-preset registry (device-presets.ts), selectable per run
+// via execution.desktop.device (default `desktop`=1440x950). NOTE: this is run-wide for now; a
+// per-PERSONA device dimension (N personas × devices, as the bespoke sims author) lands with
+// fan-out. On this E2B-desktop route only width/height physically render — isMobile/DSF are
+// honest metadata + a prompt signal, not rendered (device-presets.ts FIDELITY NOTE).
+// Server-side reclamation buffer past the loop's own wall-clock stop.
+const SANDBOX_TIMEOUT_BUFFER_MS = 10 * 60_000;
+// Room the clone route adds to the sandbox deadline for clone/install/build/start/probe.
+const SUBJECT_PROVISION_BUDGET_MS = 30 * 60_000;
+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.
+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;
+const DEFAULT_MISSION = "You are testing a web application. The browser is already open at the subject URL. Explore it, accomplish what the scenario asks, and stop when done.";
+/** Compose one lane's actor prompt: persona line + device line + mission + per-lane steer.
+ *  At N=1 (homogeneous, no roster) this reproduces the prior composeInstructions byte-for-byte. */
+export function composeLaneInstructions(args) {
+    const { name, preset } = args.device;
+    const deviceLine = preset.isMobile
+        ? `You are a mobile user on a ${name} device (${preset.width}x${preset.height} @${preset.deviceScaleFactor}x). Expect a mobile/touch layout.`
+        : `You are a desktop user (${name}, ${preset.width}x${preset.height}).`;
+    const parts = [
+        args.persona ? `Persona: ${args.persona}.` : undefined,
+        deviceLine,
+        args.mission,
+        args.instruction ? `Lane focus: ${args.instruction}` : undefined
+    ].filter((part) => Boolean(part));
+    const instructions = parts.join("\n\n");
+    return {
+        instructions,
+        persona: {
+            id: args.persona ?? "cua-operator",
+            traitsApplied: [],
+            promptDigest: digestText(instructions, 16)
+        }
+    };
+}
+/**
+ * Resolve a lane's device + rendered resolution (most-specific wins, exactly as the single-lane
+ * path always has): a raw execution.desktop.resolution escape hatch (only legal when no lane
+ * sets a device — XOR enforced at parse) → the lane's named device → the run-wide
+ * execution.desktop.device → the default preset. A raw resolution is an unnamed custom desktop
+ * (non-mobile, DSF 1): we never claim a named preset's mobile/DPR for hand-set geometry.
+ */
+export function resolveLaneDevice(config, lane) {
+    const rawResolution = config.execution?.desktop?.resolution;
+    if (lane?.device === undefined && rawResolution) {
+        const preset = { width: rawResolution[0], height: rawResolution[1], isMobile: false, deviceScaleFactor: 1 };
+        return { name: "custom", preset, resolution: [rawResolution[0], rawResolution[1]] };
+    }
+    const candidate = lane?.device ?? config.execution?.desktop?.device;
+    const presetName = isDevicePresetName(candidate) ? candidate : DEFAULT_DEVICE_PRESET;
+    const preset = resolveDevicePreset(presetName);
+    return { name: presetName, preset, resolution: [preset.width, preset.height] };
+}
+/** Per-lane sandbox deadline (each lane owns its own desktop). Mirrors the single-lane formula
+ *  verbatim so N=1 stays byte-stable: explicit sandboxTimeoutMs, else session budget + (clone
+ *  or local-tree: provision budget + Σ state-step budgets) + the server-side
+ *  reclamation buffer. Local-tree shares the clone route's provisioning budget: it swaps a
+ *  git clone for an upload+extract, but the shared install/build/state/start/probe pipeline
+ *  costs the same wall-clock room either way. */
+function resolvePerLaneSandboxMs(config) {
+    const timeoutMs = config.execution?.timeoutMs ?? DEFAULT_SESSION_TIMEOUT_MS;
+    const provisionedRoute = config.subject.source === "clone" || config.subject.source === "local-tree";
+    const stateBudgetMs = provisionedRoute
+        ? (config.subject.state?.seed ?? []).reduce((sum, step) => sum + (step.timeoutMs ?? DEFAULT_STATE_STEP_TIMEOUT_MS), 0)
+        : 0;
+    return config.execution?.desktop?.sandboxTimeoutMs
+        ?? timeoutMs + (provisionedRoute ? SUBJECT_PROVISION_BUDGET_MS + stateBudgetMs : 0) + SANDBOX_TIMEOUT_BUFFER_MS;
+}
+/**
+ * Effective in-flight lane bound. Default min(laneCount, 3); a declared execution.concurrency
+ * clamps to [1, laneCount]; the env override may only LOWER it (never raise concurrent paid
+ * desktops — invariant 3). Pure given (config, laneCount, env).
+ */
+function resolveCuaConcurrency(config, laneCount, env) {
+    const declared = config.execution?.concurrency;
+    const base = declared !== undefined
+        ? Math.min(Math.max(1, declared), laneCount)
+        : Math.min(laneCount, DEFAULT_CUA_CONCURRENCY);
+    const envLower = readPositiveInt(env[CUA_MAX_CONCURRENCY_ENV], 0);
+    if (envLower > 0) {
+        return Math.max(1, Math.min(base, envLower, laneCount));
+    }
+    return Math.max(1, base);
+}
+/** Build the lane specs AND the public plan from a config (pure). countOverride is the CLI
+ *  --count for homogeneous fan-out (ignored when a `lanes` roster is declared). */
+function laneSpecsAndPlan(config, opts = {}) {
+    const env = opts.env ?? {};
+    const actor = config.actors[0];
+    const mission = actor?.mission ?? DEFAULT_MISSION;
+    const roster = actor?.lanes;
+    const laneCount = roster ? roster.length : Math.max(1, opts.countOverride ?? actor?.count ?? 1);
+    const lanes = [];
+    for (let i = 0; i < laneCount; i += 1) {
+        const lane = roster?.[i];
+        const laneId = lane?.id ?? `lane-${String(i + 1).padStart(2, "0")}`;
+        const simId = `sim-${String(i + 1).padStart(3, "0")}`;
+        const streamId = `stream-${String(i + 1).padStart(3, "0")}`;
+        const device = resolveLaneDevice(config, lane);
+        const composed = composeLaneInstructions({
+            mission,
+            ...(((roster ? lane?.persona : actor?.persona)) === undefined ? {} : { persona: (roster ? lane?.persona : actor?.persona) }),
+            ...(((roster ? lane?.instruction : actor?.laneFocus?.instruction)) === undefined ? {} : { instruction: (roster ? lane?.instruction : actor?.laneFocus?.instruction) }),
+            device: { name: device.name, preset: device.preset }
+        });
+        lanes.push({
+            laneId,
+            ...(lane?.actorType === undefined ? {} : { actorType: lane.actorType }),
+            ...(lane?.surface === undefined ? {} : { surface: lane.surface }),
+            ...(lane?.caseGroup === undefined ? {} : { caseGroup: lane.caseGroup }),
+            laneIndex: i,
+            simId,
+            streamId,
+            persona: composed.persona,
+            instructions: composed.instructions,
+            ...(lane?.target === undefined ? {} : { targetUrl: lane.target }),
+            ...((lane?.stopWhen ?? actor?.stopWhen) === undefined ? {} : { stopWhen: (lane?.stopWhen ?? actor?.stopWhen) }),
+            deviceName: device.name,
+            devicePreset: device.preset,
+            resolution: device.resolution,
+            screenshotDir: laneCount === 1 ? "" : laneId,
+            traceArtifactPath: laneCount === 1 ? "actor.json" : `actors/${streamId}.json`
+        });
+    }
+    const concurrency = resolveCuaConcurrency(config, laneCount, env);
+    const perLaneSessionBudgetMs = config.execution?.timeoutMs ?? DEFAULT_SESSION_TIMEOUT_MS;
+    const perLaneSandboxMs = resolvePerLaneSandboxMs(config);
+    const plan = {
+        strategy: CUA_FANOUT_STRATEGY,
+        laneCount,
+        concurrency,
+        waves: Math.ceil(laneCount / concurrency),
+        perLaneSessionBudgetMs,
+        worstCaseSandboxMinutes: Math.round((laneCount * perLaneSandboxMs) / 60_000),
+        dryRun: opts.dryRun === true,
+        lanes: lanes.map((spec) => ({
+            id: spec.laneId,
+            ...(spec.actorType === undefined ? {} : { actorType: spec.actorType }),
+            ...(spec.surface === undefined ? {} : { surface: spec.surface }),
+            ...(spec.caseGroup === undefined ? {} : { caseGroup: spec.caseGroup }),
+            index: spec.laneIndex + 1,
+            persona: spec.persona.id,
+            device: spec.deviceName,
+            resolution: spec.resolution,
+            instructionDigest: spec.persona.promptDigest,
+            ...(spec.targetUrl === undefined ? {} : { targetDigest: digestUrl(spec.targetUrl) })
+        }))
+    };
+    return { lanes, plan };
+}
+async function resolveCuaRerunSelection(args) {
+    const source = await loadRunBundle(args.cwd, args.sourceRunId);
+    if (!source) {
+        return { ok: false, message: `source run not found or invalid: ${args.sourceRunId}` };
+    }
+    const bundle = source.bundle;
+    if (bundle.mode !== "live") {
+        return { ok: false, message: `source run ${bundle.runId} is ${bundle.mode}; rerun selection only applies to live CUA fan-out evidence.` };
+    }
+    const fanoutEvent = bundle.events.some((event) => event.type === "cua-lab.fanout.plan");
+    if (!fanoutEvent || bundle.streams.length < 2) {
+        return { ok: false, message: `source run ${bundle.runId} is not a CUA fan-out run.` };
+    }
+    const prior = bundle.streams
+        .map(snapshotPriorCuaLane)
+        .filter((lane) => lane !== null);
+    const priorById = new Map(prior.map((lane) => [lane.laneId, lane]));
+    if (priorById.size < 2) {
+        return { ok: false, message: `source run ${bundle.runId} does not expose multiple lane ids.` };
+    }
+    const explicitLaneIds = uniqueLaneIds(args.laneIds ?? []);
+    const selectedLaneIds = explicitLaneIds.length > 0
+        ? explicitLaneIds
+        : prior.filter((lane) => lane.rerunnable).map((lane) => lane.laneId);
+    if (selectedLaneIds.length === 0) {
+        return { ok: false, message: `source run ${bundle.runId} has no failed, blocked, timed-out, or hollow lanes to rerun.` };
+    }
+    const missingPrior = selectedLaneIds.filter((laneId) => !priorById.has(laneId));
+    if (missingPrior.length > 0) {
+        return { ok: false, message: `selected lane id(s) were not present in source run ${bundle.runId}: ${missingPrior.join(", ")}` };
+    }
+    const specsById = new Map(args.laneSpecs.map((spec) => [spec.laneId, spec]));
+    const missingCurrent = selectedLaneIds.filter((laneId) => !specsById.has(laneId));
+    if (missingCurrent.length > 0) {
+        return { ok: false, message: `selected lane id(s) are not present in the current lab config ${args.config.id}: ${missingCurrent.join(", ")}` };
+    }
+    const selectedSpecs = selectedLaneIds.map((laneId) => specsById.get(laneId));
+    const selectedPlanLaneIds = new Set(selectedLaneIds);
+    const selectedPlanEntries = args.plan.lanes.filter((lane) => selectedPlanLaneIds.has(lane.id));
+    const concurrency = Math.max(1, Math.min(args.plan.concurrency, selectedSpecs.length));
+    const plan = {
+        ...args.plan,
+        laneCount: selectedSpecs.length,
+        concurrency,
+        waves: Math.ceil(selectedSpecs.length / concurrency),
+        worstCaseSandboxMinutes: Math.round((selectedSpecs.length * resolvePerLaneSandboxMs(args.config)) / 60_000),
+        lanes: selectedPlanEntries
+    };
+    const previous = selectedLaneIds.map((laneId) => priorById.get(laneId).previous);
+    return {
+        ok: true,
+        laneSpecs: selectedSpecs,
+        plan,
+        rerun: {
+            sourceRunId: bundle.runId,
+            selectedLaneIds,
+            previous
+        }
+    };
+}
+function uniqueLaneIds(values) {
+    const seen = new Set();
+    const result = [];
+    for (const value of values) {
+        const laneId = value.trim();
+        if (!laneId || seen.has(laneId))
+            continue;
+        seen.add(laneId);
+        result.push(laneId);
+    }
+    return result;
+}
+function snapshotPriorCuaLane(stream) {
+    if (stream.kind !== "browser" || typeof stream.laneId !== "string" || !stream.laneId.trim()) {
+        return null;
+    }
+    const actorStatus = stream.actor?.status;
+    const completionReason = stream.actor?.completionReason;
+    const reason = stream.ui?.state ?? stream.actor?.reason;
+    const actions = stream.actor?.counts.actions ?? 0;
+    const messages = stream.actor?.counts.messages ?? 0;
+    const hollow = completionReason === "goal_satisfied" && actions === 0 && messages === 0;
+    const rerunnable = stream.status !== "passed"
+        || actorStatus === "failed"
+        || actorStatus === "blocked"
+        || actorStatus === "timed_out"
+        || completionReason === "harness_error"
+        || hollow;
+    return {
+        laneId: stream.laneId,
+        previous: {
+            laneId: stream.laneId,
+            streamId: stream.id,
+            status: stream.status,
+            ...(reason === undefined ? {} : { reason }),
+            ...(actorStatus === undefined ? {} : { actorStatus }),
+            ...(completionReason === undefined ? {} : { completionReason })
+        },
+        rerunnable
+    };
+}
+/**
+ * Pure pre-flight plan resolver (runs in dry-run AND live). Returns the lane table, the
+ * effective concurrency, the wave count, the per-lane session budget, and the worst-case total
+ * sandbox-minutes — BEFORE any sandbox or provider call. The same plan appears in dry-run,
+ * marked $0 (dryRun: true).
+ */
+export function resolveCuaLanePlan(config, opts = {}) {
+    return laneSpecsAndPlan(config, opts).plan;
+}
+/** Print the lane plan to stderr BEFORE any sandbox/provider call (public-safe: ids, devices,
+ *  digests, and budgets only — no prompt text, no secrets). */
+function emitPreflightPlan(plan, labId) {
+    const lines = [];
+    lines.push(`humanish cua fan-out plan (${labId}): ${plan.laneCount} lane(s), strategy ${plan.strategy}, concurrency ${plan.concurrency}, ${plan.waves} wave(s).`);
+    lines.push(`  per-lane session budget ${Math.round(plan.perLaneSessionBudgetMs / 1000)}s; worst-case ~${plan.worstCaseSandboxMinutes} sandbox-minutes total${plan.dryRun ? " (dry-run: $0)" : ""}.`);
+    for (const lane of plan.lanes) {
+        lines.push(`  - ${formatLanePlanEntry(lane)}`);
+    }
+    process.stderr.write(`${lines.join("\n")}\n`);
+}
+function formatLanePlanEntry(lane) {
+    const taxonomy = [
+        lane.actorType ? `type=${lane.actorType}` : undefined,
+        lane.surface ? `surface=${lane.surface}` : undefined,
+        lane.caseGroup ? `case=${lane.caseGroup}` : undefined
+    ].filter((part) => part !== undefined);
+    return `${lane.id}: persona=${lane.persona}${taxonomy.length > 0 ? ` ${taxonomy.join(" ")}` : ""} device=${lane.device} ${lane.resolution[0]}x${lane.resolution[1]} prompt#${lane.instructionDigest}${lane.targetDigest ? ` target#${lane.targetDigest}` : ""}`;
+}
+/** 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). */
+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. */
+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`);
+}
+/** Short id-safe suffix for a subject-phase RunEvent: drops the shared prefix/suffix so each
+ *  phase gets a distinct bundle event id (e.g. "clone", "state-before-build"). */
+function phaseEventIdSuffix(type) {
+    return type
+        .replace(/^cua-lab\.subject\./, "")
+        .replace(/\.(started|completed)$/, "")
+        .replace(/\./g, "-");
+}
+/** Build a lane's writeScreenshot closure: writes under screenshots/<screenshotDir>/ and records
+ *  the relative path the trace references (screenshots/<name> at N=1; screenshots/<laneId>/<name>
+ *  at N>1). */
+export function makeLaneWriteScreenshot(artifactRoot, spec, screenshots) {
+    const dirParts = spec.screenshotDir ? ["screenshots", spec.screenshotDir] : ["screenshots"];
+    const relPrefix = spec.screenshotDir ? path.posix.join("screenshots", spec.screenshotDir) : "screenshots";
+    return async (name, bytes) => {
+        const rel = path.posix.join(relPrefix, name);
+        assertScreenshotEvidence(rel, bytes);
+        await mkdir(path.join(artifactRoot, ...dirParts), { recursive: true });
+        await writeFile(path.join(artifactRoot, ...dirParts, name), bytes);
+        screenshots.push(rel);
+        return rel;
+    };
+}
+/**
+ * Verify the desktop geometry IN-SANDBOX (the per-lane device claim is checked, never assumed).
+ * Returns a fail-closed DEVICE_GEOMETRY message on a PARSEABLE mismatch. When xdpyinfo is
+ * unavailable or unparseable (only in fakes — a real E2B desktop always answers), it cannot be
+ * verified, so the lane proceeds with the requested geometry (no false failure).
+ */
+async function checkLaneGeometry(desktop, spec, requestTimeoutMs) {
+    let out = "";
+    try {
+        const result = await desktop.commands.run("xdpyinfo 2>/dev/null | grep -i dimensions || true", { requestTimeoutMs });
+        out = (result.stdout ?? "").trim();
+    }
+    catch {
+        return undefined;
+    }
+    const match = out.match(/(\d+)\s*x\s*(\d+)\s*pixels/i);
+    if (!match) {
+        return undefined;
+    }
+    const width = Number(match[1]);
+    const height = Number(match[2]);
+    const [expectedWidth, expectedHeight] = spec.resolution;
+    if (width === expectedWidth && height === expectedHeight) {
+        return undefined;
+    }
+    return `HUMANISH_CUA_LAB_DEVICE_GEOMETRY: lane ${spec.laneId} requested a ${expectedWidth}x${expectedHeight} desktop but xdpyinfo reports ${width}x${height} in-sandbox; the per-lane device geometry is unverified (fail-closed).`;
+}
+/** A blocked lane outcome (pipeline gate / fail-fast skipped it before it ran). */
+function blockedLaneOutcome(spec, reason) {
+    return {
+        spec,
+        killed: false,
+        streamUrlPresent: false,
+        screenshots: [],
+        stateStepRecords: [],
+        phaseRecords: [],
+        warnings: [],
+        skippedReason: reason,
+        noEngagement: false,
+        selfReportedBlocker: false,
+        harnessError: false
+    };
+}
+async function findVisibleBrowserWindowId(desktop, requestTimeoutMs) {
+    const result = await desktop.commands.run([
+        "set -euo pipefail",
+        "export DISPLAY=\"${DISPLAY:-:0}\"",
+        "find_chrome_window() {",
+        "  timeout 2s xdotool search --onlyvisible --class 'google-chrome|Google-chrome|chromium|Chromium|chrome|Chrome' 2>/dev/null | tail -n 1 || true",
+        "}",
+        "find_firefox_window() {",
+        "  timeout 2s xdotool search --onlyvisible --class 'firefox|Firefox' 2>/dev/null | tail -n 1 || true",
+        "}",
+        "find_named_window() {",
+        "  timeout 2s xdotool search --onlyvisible --name 'Google Chrome|Chromium|Mozilla Firefox|127[.]0[.]0[.]1|localhost|e2b[.]app|e2b[.]dev' 2>/dev/null | tail -n 1 || true",
+        "}",
+        "window_id=",
+        "for _ in $(seq 1 10); do",
+        "  window_id=\"$(find_chrome_window)\"",
+        "  if [ -z \"$window_id\" ]; then window_id=\"$(find_firefox_window)\"; fi",
+        "  if [ -z \"$window_id\" ]; then window_id=\"$(find_named_window)\"; fi",
+        "  if [ -n \"$window_id\" ]; then break; fi",
+        "  sleep 0.5",
+        "done",
+        "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: resize the detected browser window to fill the lane's desktop
+ * resolution. A failure must never fail the lane (the actor can still run on a
+ * smaller window), so all errors are swallowed.
+ */
+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);
+}
+async function openDesktopBrowserTarget(desktop, targetUrl, requestTimeoutMs, browserPreference) {
+    const requestedBrowser = browserPreference ?? "default";
+    if (isHttpUrl(targetUrl)) {
+        const chromiumFlags = CHROMIUM_EVIDENCE_HYGIENE_FLAGS.map(shellSingleQuote).join(" ");
+        const browserLaunchCommand = [
+            "set -euo pipefail",
+            `target_url=${shellSingleQuote(targetUrl)}`,
+            `browser_preference=${shellSingleQuote(requestedBrowser)}`,
+            "chrome_profile_dir=/tmp/humanish-chrome-profile",
+            `chrome_preferences_json=${shellSingleQuote(chromiumEvidenceProfilePreferencesJson())}`,
+            "prepare_chrome_profile() {",
+            "  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 &",
+            "    printf 'HUMANISH_BROWSER_RESOLVED=%s\\n' \"$label\"",
+            "    return 0",
+            "  fi",
+            "  return 1",
+            "}",
+            `chrome_debug_flags=(--remote-debugging-address=127.0.0.1 --remote-debugging-port=9222 "--user-data-dir=$chrome_profile_dir" ${chromiumFlags})`,
+            "prepare_chrome_profile",
+            "open_target() {",
+            "  case \"$browser_preference\" in",
+            "    chrome)",
+            "      launch_browser google-chrome google-chrome --new-window \"${chrome_debug_flags[@]}\" && return 0",
+            "      launch_browser google-chrome-stable google-chrome-stable --new-window \"${chrome_debug_flags[@]}\" && return 0",
+            "      echo 'requested browser chrome was not found' >&2",
+            "      return 127",
+            "      ;;",
+            "    chromium)",
+            "      launch_browser chromium chromium --new-window \"${chrome_debug_flags[@]}\" && return 0",
+            "      launch_browser chromium-browser chromium-browser --new-window \"${chrome_debug_flags[@]}\" && return 0",
+            "      echo 'requested browser chromium was not found' >&2",
+            "      return 127",
+            "      ;;",
+            "    firefox)",
+            "      launch_browser firefox firefox --new-window && return 0",
+            "      echo 'requested browser firefox was not found' >&2",
+            "      return 127",
+            "      ;;",
+            "    default)",
+            "      launch_browser google-chrome google-chrome --new-window \"${chrome_debug_flags[@]}\" && return 0",
+            "      launch_browser google-chrome-stable google-chrome-stable --new-window \"${chrome_debug_flags[@]}\" && return 0",
+            "      launch_browser chromium chromium --new-window \"${chrome_debug_flags[@]}\" && return 0",
+            "      launch_browser chromium-browser chromium-browser --new-window \"${chrome_debug_flags[@]}\" && return 0",
+            "      launch_browser firefox firefox --new-window && 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,
+        }), ({ 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];
+        return browserPreference === undefined ? undefined : {
+            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 browserPreference === undefined ? undefined : { requested: requestedBrowser };
+    }
+    const launchTarget = requestedBrowser === "chrome" ? "google-chrome"
+        : requestedBrowser === "chromium" ? "chromium"
+            : requestedBrowser === "firefox" ? "firefox"
+                : "google-chrome";
+    await desktop.launch(launchTarget, targetUrl);
+    return { requested: requestedBrowser, resolved: launchTarget };
+}
+export function makeChromeBrowserStateObserver(desktop, requestTimeoutMs) {
+    return async () => {
+        const script = [
+            "const pages = await fetch('http://127.0.0.1:9222/json').then((r) => r.json()).catch(() => []);",
+            "const page = Array.isArray(pages) ? pages.find((entry) => entry && entry.type === 'page' && /^https?:/.test(String(entry.url || ''))) : undefined;",
+            "if (!page) { console.log('{}'); process.exit(0); }",
+            "let text = '';",
+            "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) })' } }));",
+            "    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 : '';",
+            "  }",
+            "}",
+            "console.log(JSON.stringify({ url, title, text }));"
+        ].join("\n");
+        const result = await desktop.commands.run(`node --input-type=module -e ${shellSingleQuote(script)}`, {
+            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 } : {})
+            };
+        }
+        catch {
+            return {};
+        }
+    };
+}
+function shellSingleQuote(value) {
+    return `'${value.replace(/'/g, "'\\''")}'`;
+}
+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 });
+    }
+}
+function completionReasonContradictsGoal(reason) {
+    const text = stripNegatedNonBlockerPhrases(reason.toLowerCase());
+    return /\b(can'?t|cannot|could not|unable|blocked|blocker|failed|invalid|not set)\b/.test(text)
+        || /\b(shows|showing|hit|encountered|returned|got)\b.{0,80}\berror\b/.test(text)
+        || /\berror[:.]/.test(text)
+        || /what would you like me to do|please tell me|need (the )?(task|credentials|instructions)/.test(text);
+}
+function stripNegatedNonBlockerPhrases(text) {
+    return text
+        .replace(/\bno\s+(?:real\s+|remaining\s+|actual\s+)?(?:blocker|blockers|blocking issue|blocking issues|error|errors|failure|failures)\s+(?:was\s+|were\s+)?(?:encountered|observed|found|hit|seen|reported|detected)\b/g, "")
+        .replace(/\bwithout\s+(?:a\s+|any\s+)?(?:real\s+|remaining\s+|actual\s+)?(?:blocker|blockers|blocking issue|blocking issues|error|errors|failure|failures)\b/g, "")
+        .replace(/\bnot\s+(?:blocked|a blocker|an error|failed)\b/g, "");
+}
+function traceHasStopWhenMatch(session) {
+    return session.trace.items.some((item) => item.kind === "notice"
+        && item.status === "matched"
+        && item.title.startsWith("stopWhen matched"));
+}
+/**
+ * Run ONE E2B desktop lane end-to-end: create the sandbox (per-lane metadata + the lane's device
+ * resolution), prepareDesktop, verify geometry, (clone+serve+seed the subject per lane), open the
+ * browser, run the session, and ALWAYS tear down THIS lane's sandbox BY ID in a finally. Never
+ * enumerates sandboxes. Extracted from the former single-lane block; at N=1 it writes the exact
+ * same artifacts (actor.json, screenshots/<name>) the bundle has always referenced.
+ */
+export async function runCuaLane(spec, deps) {
+    const { config, appUrl, cloneRoute, localTreeRoute, serve, subjectRepo, subjectEnvNames } = deps;
+    const targetUrl = spec.targetUrl ?? appUrl;
+    const env = deps.env;
+    const warnings = [];
+    const screenshots = [];
+    const writeScreenshot = makeLaneWriteScreenshot(deps.artifactRoot, spec, screenshots);
+    const stateStepRecords = [];
+    // Completed-only trail (durationMs/ok are set on completed events, never on started ones):
+    // this is what survives into bundle.events. The default/injected sink below sees EVERY event,
+    // started and completed alike, so an operator watching stderr sees both halves of each phase.
+    const phaseRecords = [];
+    const onSubjectPhase = (event) => {
+        if (event.ok !== undefined) {
+            phaseRecords.push(event);
+        }
+        (deps.hooks.onPhase ?? defaultSubjectPhaseSink)(event, { laneId: spec.laneId, laneCount: deps.laneCount });
+    };
+    let session;
+    let sessionError;
+    let failureCode;
+    let sandboxId;
+    let killed = false;
+    let streamUrl;
+    let subjectCommit;
+    let desktopBrowser;
+    let provisioned = false;
+    let signaled = false;
+    const signal = (ok) => {
+        if (!signaled && deps.signalProvisioned) {
+            signaled = true;
+            deps.signalProvisioned(ok);
+        }
+    };
+    let desktopModule;
+    let desktop;
+    try {
+        desktopModule = await (deps.hooks.loadDesktopModule ?? loadE2BDesktopModule)();
+        // Optional custom desktop template (image): present → Sandbox.create(template, opts); absent →
+        // the byte-stable Sandbox.create(opts) default (stock `desktop` template).
+        desktop = await createDesktopSandbox(desktopModule, {
+            apiKey: deps.e2bApiKey,
+            requestTimeoutMs: deps.requestTimeoutMs,
+            timeoutMs: deps.perLaneSandboxMs,
+            metadata: {
+                ...CUA_ACTOR_LAB_PROVIDER_METADATA,
+                labId: config.id,
+                simId: spec.simId,
+                laneId: spec.laneId,
+                laneIndex: String(spec.laneIndex),
+                laneCount: String(deps.laneCount)
+            },
+            // Env placement per the doctrine: the ACTOR's key never enters the sandbox (the model drives
+            // from outside). The SUBJECT's declared env NAMES are provisioned here on the clone route.
+            ...(subjectEnvNames.length > 0
+                ? { envs: Object.fromEntries(subjectEnvNames.map((name) => [name, env[name]])) }
+                : {}),
+            resolution: spec.resolution,
+            dpi: 96,
+            lifecycle: { onTimeout: "kill" }
+        }, config.execution?.desktop?.template);
+        sandboxId = desktop.sandboxId;
+        if (deps.hooks.prepareDesktop) {
+            await deps.hooks.prepareDesktop(desktop, { laneId: spec.laneId, laneIndex: spec.laneIndex, laneCount: deps.laneCount });
+        }
+        // Per-lane geometry assertion (fail-closed) — the device claim is verified in-sandbox.
+        const geometryError = await checkLaneGeometry(desktop, spec, deps.requestTimeoutMs);
+        if (geometryError) {
+            sessionError = geometryError;
+            failureCode = "HUMANISH_CUA_LAB_DEVICE_GEOMETRY";
+        }
+        else {
+            if (cloneRoute && serve && subjectRepo) {
+                subjectCommit = await provisionCloneSubject(desktop, {
+                    repo: subjectRepo,
+                    depth: config.subject.clone?.depth ?? 1,
+                    serve,
+                    ...(config.subject.state === undefined ? {} : { state: config.subject.state }),
+                    hasGithubToken: deps.hasGithubToken,
+                    requestTimeoutMs: deps.requestTimeoutMs,
+                    scrub: deps.scrubKnownValues,
+                    onCommit: (commit) => {
+                        subjectCommit = commit;
+                    },
+                    onStateStep: (record) => {
+                        stateStepRecords.push(record);
+                    },
+                    onPhase: onSubjectPhase,
+                    ...(deps.hooks.detachedTimers ?? {})
+                });
+            }
+            else if (localTreeRoute && serve && deps.localTreeArchiveBuffer) {
+                await provisionLocalTreeSubject(desktop, {
+                    archiveBuffer: deps.localTreeArchiveBuffer,
+                    serve,
+                    ...(config.subject.state === undefined ? {} : { state: config.subject.state }),
+                    requestTimeoutMs: deps.requestTimeoutMs,
+                    scrub: deps.scrubKnownValues,
+                    onStateStep: (record) => {
+                        stateStepRecords.push(record);
+                    },
+                    onPhase: onSubjectPhase,
+                    ...(deps.hooks.detachedTimers ?? {})
+                });
+            }
+            desktopBrowser = await openDesktopBrowserTarget(desktop, targetUrl, deps.requestTimeoutMs, config.execution?.desktop?.browser);
+            await desktop.wait(BROWSER_SETTLE_MS).catch(() => undefined);
+            // World is ready: release the pipeline gate so the remaining lanes may start.
+            provisioned = true;
+            signal(true);
+            try {
+                const browserWindowId = await findVisibleBrowserWindowId(desktop, deps.requestTimeoutMs)
+                    .catch((error) => {
+                    warnings.push(`Browser window lookup failed before live stream start (falling back to desktop stream): ${redactText(deps.scrubKnownValues(toErrorMessage(error)))}`);
+                    return undefined;
+                });
+                if (browserWindowId !== undefined) {
+                    await fillDesktopBrowserWindow(desktop, browserWindowId, spec.resolution, deps.requestTimeoutMs);
+                }
+                await startDesktopStream(desktop, browserWindowId);
+                const candidateStreamUrl = desktop.stream.getUrl({
+                    authKey: desktop.stream.getAuthKey(),
+                    autoConnect: true,
+                    viewOnly: true,
+                    resize: "scale"
+                });
+                if (typeof candidateStreamUrl === "string" && candidateStreamUrl.trim().length > 0) {
+                    streamUrl = candidateStreamUrl;
+                    await deps.hooks.onRuntimeStreamReady?.({
+                        laneId: spec.laneId,
+                        sandboxId: desktop.sandboxId,
+                        simId: spec.simId,
+                        streamId: spec.streamId,
+                        url: streamUrl
+                    });
+                }
+                else {
+                    warnings.push("Live desktop stream started but did not return a usable watch URL; Observer will fall back to screenshots.");
+                }
+            }
+            catch (error) {
+                warnings.push(`Live desktop stream unavailable (run continues; evidence still captured): ${redactText(deps.scrubKnownValues(toErrorMessage(error)))}`);
+            }
+            const sessionOptions = {
+                instructions: spec.instructions,
+                persona: spec.persona,
+                timeoutMs: deps.timeoutMs,
+                openai: {
+                    apiKey: deps.openaiApiKey,
+                    ...(config.actors[0]?.model ? { model: config.actors[0].model } : {})
+                },
+                desktop: desktop,
+                executorOptions: {
+                    observeBrowserState: makeChromeBrowserStateObserver(desktop, deps.requestTimeoutMs)
+                },
+                redactScreenshots: deps.redactScreenshots,
+                scrubText: deps.scrubKnownValues,
+                writeScreenshot,
+                ...(spec.stopWhen === undefined ? {} : { stopWhen: spec.stopWhen })
+            };
+            session = await deps.runSession(sessionOptions);
+        }
+    }
+    catch (error) {
+        sessionError = redactText(deps.scrubKnownValues(toErrorMessage(error)));
+    }
+    finally {
+        if (!provisioned) {
+            signal(false);
+        }
+        if (desktop && desktopModule) {
+            const failed = sessionError !== undefined || session === undefined;
+            // Each route's own keep flag gates its own lane only: a clone.keep can never leak into
+            // a local-tree lane's teardown decision, and vice versa.
+            const keepReason = cloneRoute && config.subject.clone?.keep === true
+                ? "subject.clone.keep"
+                : localTreeRoute && config.subject.localTree?.keep === true
+                    ? "subject.localTree.keep"
+                    : undefined;
+            const keepForDebug = keepReason !== undefined && failed;
+            if (keepForDebug) {
+                warnings.push(`Sandbox ${desktop.sandboxId} kept for debugging (${keepReason} on failure); reclaim it via E2B or it will be killed on its server-side timeout.`);
+            }
+            else if (typeof desktopModule.Sandbox.kill === "function") {
+                try {
+                    await desktopModule.Sandbox.kill(desktop.sandboxId, { requestTimeoutMs: 60_000 });
+                    killed = true;
+                }
+                catch (error) {
+                    warnings.push(`Sandbox teardown failed (server-side kill-on-timeout will reclaim it): ${redactText(deps.scrubKnownValues(toErrorMessage(error)))}`);
+                }
+            }
+            else {
+                warnings.push("Installed @e2b/desktop SDK does not expose Sandbox.kill; server-side kill-on-timeout will reclaim the sandbox.");
+            }
+        }
+    }
+    if (session) {
+        await mkdir(path.dirname(path.join(deps.artifactRoot, spec.traceArtifactPath)), { recursive: true });
+        await writeFile(path.join(deps.artifactRoot, spec.traceArtifactPath), `${JSON.stringify(session.trace, null, 2)}\n`, "utf8");
+        if (session.trace.redaction.screenshots === "raw") {
+            warnings.push("Screenshots are full-fidelity (raw) for local use — the bundle stays in gitignored .humanish and nothing scans these pixels; review them before sharing anywhere. Set policies.redactScreenshots: true to blur a share-as-is bundle.");
+        }
+    }
+    const noEngagement = session !== undefined
+        && session.completionReason === "goal_satisfied"
+        && (session.trace.counts.actions ?? 0) === 0
+        && (session.trace.counts.messages ?? 0) === 0
+        && !traceHasStopWhenMatch(session);
+    if (noEngagement) {
+        warnings.push("Actor returned goal_satisfied with ZERO actions and ZERO messages — it likely saw a blank or still-loading screen and stopped without engaging. NOT counted as a pass. Check the screenshot; raise execution.timeoutMs or confirm the subject painted before the first turn.");
+    }
+    const blockerReason = session?.completionReason === "goal_satisfied" && completionReasonContradictsGoal(session.reason)
+        ? session.reason
+        : undefined;
+    const selfReportedBlocker = blockerReason !== undefined;
+    if (selfReportedBlocker) {
+        warnings.push(`Actor returned goal_satisfied while its final message describes a blocker or asks for missing instructions — NOT counted as a pass: ${redactText(deps.scrubKnownValues(blockerReason))}`);
+    }
+    const harnessError = sessionError !== undefined || session?.completionReason === "harness_error";
+    return {
+        spec,
+        ...(session ? { session } : {}),
+        ...(sessionError === undefined ? {} : { sessionError }),
+        ...(sandboxId === undefined ? {} : { sandboxId }),
+        killed,
+        streamUrlPresent: streamUrl !== undefined,
+        screenshots,
+        ...(subjectCommit === undefined ? {} : { subjectCommit }),
+        ...(desktopBrowser === undefined ? {} : { desktopBrowser }),
+        stateStepRecords,
+        phaseRecords,
+        warnings,
+        noEngagement,
+        selfReportedBlocker,
+        harnessError,
+        ...(failureCode === undefined ? {} : { failureCode })
+    };
+}
+/** Run the single IN-PROCESS lane (a custom executor + provider; NO E2B). Always one lane. */
+async function runInProcessLane(spec, deps) {
+    const warnings = [];
+    const screenshots = [];
+    const writeScreenshot = makeLaneWriteScreenshot(deps.artifactRoot, spec, screenshots);
+    let session;
+    let sessionError;
+    try {
+        const executor = await deps.hooks.buildExecutor({ config: deps.config, actor: deps.descriptor, appUrl: deps.appUrl });
+        const provider = await deps.hooks.buildProvider({ config: deps.config, actor: deps.descriptor });
+        const sessionOptions = {
+            instructions: spec.instructions,
+            persona: spec.persona,
+            timeoutMs: deps.timeoutMs,
+            provider,
+            executor,
+            redactScreenshots: deps.redactScreenshots,
+            scrubText: deps.scrubKnownValues,
+            writeScreenshot,
+            ...(spec.stopWhen === undefined ? {} : { stopWhen: spec.stopWhen })
+        };
+        session = await deps.runSession(sessionOptions);
+    }
+    catch (error) {
+        sessionError = redactText(deps.scrubKnownValues(toErrorMessage(error)));
+    }
+    if (session) {
+        await mkdir(path.dirname(path.join(deps.artifactRoot, spec.traceArtifactPath)), { recursive: true });
+        await writeFile(path.join(deps.artifactRoot, spec.traceArtifactPath), `${JSON.stringify(session.trace, null, 2)}\n`, "utf8");
+        if (session.trace.redaction.screenshots === "raw") {
+            warnings.push("Screenshots are full-fidelity (raw) for local use — the bundle stays in gitignored .humanish and nothing scans these pixels; review them before sharing anywhere. Set policies.redactScreenshots: true to blur a share-as-is bundle.");
+        }
+    }
+    const noEngagement = session !== undefined
+        && session.completionReason === "goal_satisfied"
+        && (session.trace.counts.actions ?? 0) === 0
+        && (session.trace.counts.messages ?? 0) === 0
+        && !traceHasStopWhenMatch(session);
+    if (noEngagement) {
+        warnings.push("Actor returned goal_satisfied with ZERO actions and ZERO messages — it likely saw a blank or still-loading screen and stopped without engaging. NOT counted as a pass. Check the screenshot; raise execution.timeoutMs or confirm the subject painted before the first turn.");
+    }
+    const blockerReason = session?.completionReason === "goal_satisfied" && completionReasonContradictsGoal(session.reason)
+        ? session.reason
+        : undefined;
+    const selfReportedBlocker = blockerReason !== undefined;
+    if (selfReportedBlocker) {
+        warnings.push(`Actor returned goal_satisfied while its final message describes a blocker or asks for missing instructions — NOT counted as a pass: ${blockerReason}`);
+    }
+    return {
+        spec,
+        ...(session ? { session } : {}),
+        ...(sessionError === undefined ? {} : { sessionError }),
+        killed: false,
+        streamUrlPresent: false,
+        screenshots,
+        stateStepRecords: [],
+        phaseRecords: [],
+        warnings,
+        noEngagement,
+        selfReportedBlocker,
+        harnessError: sessionError !== undefined || session?.completionReason === "harness_error",
+        entryKind: "local-app"
+    };
+}
+/**
+ * Run N>1 E2B lanes with bounded concurrency, a pipeline gate (lane 1 provisions before the rest
+ * start), and session fail-fast on HARNESS errors only (queued lanes become `blocked` with a
+ * pinned reason + a fail-fast event; mission verdicts never trip it). Each lane tears down ITS
+ * OWN sandbox by id; nothing here ever enumerates.
+ */
+async function runCuaLanes(laneSpecs, deps, concurrency) {
+    const failFast = { tripped: false, reason: "" };
+    let resolveGate;
+    let rejectGate;
+    const gate = new Promise((resolve, reject) => {
+        resolveGate = resolve;
+        rejectGate = () => reject(new Error("gate"));
+    });
+    // The gate is rejected on lane-0 provisioning failure; swallow the unhandled rejection if no
+    // later lane ever awaits it (concurrency could let lane 0 finish alone).
+    gate.catch(() => undefined);
+    const outcomes = await mapWithConcurrency(laneSpecs, concurrency, async (spec, index) => {
+        if (index > 0) {
+            try {
+                await gate;
+            }
+            catch {
+                return blockedLaneOutcome(spec, `skipped: lane ${laneSpecs[0]?.laneId ?? "lane-01"} failed to provision its world (pipeline gate)`);
+            }
+        }
+        if (failFast.tripped) {
+            return blockedLaneOutcome(spec, `skipped: ${failFast.reason}`);
+        }
+        const outcome = await runCuaLane(spec, {
+            ...deps,
+            ...(index === 0
+                ? {
+                    signalProvisioned: (ok) => {
+                        if (ok) {
+                            resolveGate?.();
+                        }
+                        else {
+                            rejectGate?.();
+                        }
+                    }
+                }
+                : {})
+        });
+        if (outcome.harnessError && !failFast.tripped) {
+            failFast.tripped = true;
+            failFast.reason = `a prior lane (${outcome.spec.laneId}) ended in a harness error (fail-fast)`;
+        }
+        return outcome;
+    });
+    return { outcomes, ...(failFast.tripped ? { failFastReason: failFast.reason } : {}) };
+}
+/** Project one lane outcome (or a dry-run contract spec) into the public CuaLaneResult. */
+function toLaneResult(spec, outcome, subject, dryRun) {
+    const base = {
+        id: spec.laneId,
+        ...(spec.actorType === undefined ? {} : { actorType: spec.actorType }),
+        ...(spec.surface === undefined ? {} : { surface: spec.surface }),
+        ...(spec.caseGroup === undefined ? {} : { caseGroup: spec.caseGroup }),
+        index: spec.laneIndex + 1,
+        persona: spec.persona.id,
+        device: spec.deviceName,
+        resolution: spec.resolution,
+        subject
+    };
+    if (!outcome || dryRun) {
+        return { ...base, status: "contract_proof_only", ok: dryRun };
+    }
+    if (outcome.skippedReason !== undefined) {
+        return {
+            ...base,
+            status: "blocked",
+            ok: false,
+            skippedReason: outcome.skippedReason,
+            error: { code: "HUMANISH_CUA_LAB_FAILED", message: outcome.skippedReason }
+        };
+    }
+    const session = outcome.session;
+    const laneOk = laneOutcomeOk(outcome, dryRun);
+    const status = session ? session.status : "failed";
+    return {
+        ...base,
+        status,
+        ok: laneOk,
+        ...(session
+            ? {
+                session: {
+                    status: session.status,
+                    completionReason: session.completionReason,
+                    reason: session.reason,
+                    screenshots: outcome.screenshots.length
+                }
+            }
+            : {}),
+        ...(outcome.sandboxId === undefined
+            ? {}
+            : { sandbox: { sandboxId: outcome.sandboxId, killed: outcome.killed, streamUrlPresent: outcome.streamUrlPresent } }),
+        ...(laneOk
+            ? {}
+            : {
+                error: {
+                    code: outcome.failureCode ?? "HUMANISH_CUA_LAB_FAILED",
+                    message: outcome.sessionError
+                        ?? (outcome.noEngagement
+                            ? "Actor took no actions and produced no message (likely a blank/still-loading screen); not a credible goal_satisfied."
+                            : outcome.selfReportedBlocker
+                                ? "Actor reported goal_satisfied while its final message described a blocker or asked for missing instructions; not a credible pass."
+                                : session?.completionReason === "harness_error"
+                                    ? `Computer-use session ended with a harness error: ${session.reason}`
+                                    : session?.status !== "passed"
+                                        ? `Computer-use session ended with ${session?.status ?? "unknown"}: ${session?.reason ?? "no terminal reason"}`
+                                        : "Computer-use lab did not produce a terminal session.")
+                }
+            })
+    };
+}
+function laneOutcomeOk(outcome, dryRun) {
+    if (dryRun)
+        return true;
+    if (!outcome || outcome.skippedReason !== undefined)
+        return false;
+    return outcome.session !== undefined
+        && outcome.session.status === "passed"
+        && outcome.session.completionReason !== "harness_error"
+        && outcome.sessionError === undefined
+        && !outcome.noEngagement
+        && !outcome.selfReportedBlocker;
+}
+function fanoutReviewVerdict(args) {
+    if (args.dryRun)
+        return "contract_proof_only";
+    const outcomes = args.outcomes ?? [];
+    if (outcomes.length !== args.expectedLaneCount)
+        return "fail";
+    if (outcomes.some((outcome) => !laneOutcomeOk(outcome, false))) {
+        return outcomes.some((outcome) => outcome.session?.status === "timed_out")
+            ? "timed_out"
+            : "fail";
+    }
+    return "pass";
+}
+/** Build the per-lane subject projection (invariant 5). Local-tree lanes all share ONE
+ *  host-packed archive, so every lane's projection carries the identical archiveSha256/
+ *  commit/dirty (no per-lane divergence is possible, unlike the clone route's per-lane
+ *  in-sandbox commit). */
+function laneSubjectProjection(args) {
+    if (args.cloneRoute && args.publicRepo) {
+        return {
+            source: "clone",
+            repo: args.publicRepo,
+            ...(args.subjectCommit === undefined ? {} : { commit: args.subjectCommit }),
+            envNames: args.subjectEnvNames,
+            state: args.subjectState
+        };
+    }
+    if (args.localTreeRoute) {
+        const archive = args.localTreeArchive;
+        return {
+            source: "local-tree",
+            ...(archive === undefined ? {} : { archiveSha256: archive.archiveSha256 }),
+            ...(archive?.git === undefined ? {} : { commit: archive.git.commit, dirty: archive.git.dirty }),
+            envNames: args.subjectEnvNames,
+            state: args.subjectState
+        };
+    }
+    return { source: "app-url", state: args.subjectState };
+}
+/** Narrow a resolved CuaSubjectProjection into the shape buildCuaBundle/buildSingleLaneBundle's
+ *  subjectProvenance param wants (provisioned-route sources only; app-url stays undeclared, the
+ *  default branch buildCuaBundle already handles). */
+function subjectProvenanceArg(subject, publicRepo, subjectEnvNames) {
+    if (subject.source === "clone" && publicRepo) {
+        return {
+            source: "clone",
+            repo: publicRepo,
+            ...(subject.commit === undefined ? {} : { commit: subject.commit }),
+            envNames: subjectEnvNames,
+            state: subject.state
+        };
+    }
+    if (subject.source === "local-tree") {
+        return {
+            source: "local-tree",
+            ...(subject.archiveSha256 === undefined ? {} : { archiveSha256: subject.archiveSha256 }),
+            ...(subject.commit === undefined ? {} : { commit: subject.commit }),
+            ...(subject.dirty === undefined ? {} : { dirty: subject.dirty }),
+            envNames: subjectEnvNames,
+            state: subject.state
+        };
+    }
+    return undefined;
+}
+export async function runCuaActorLab(options) {
+    const { config, dryRun } = options;
+    const cwd = path.resolve(options.cwd);
+    const hooks = options.hooks ?? {};
+    let liveObserver;
+    const runtimeStreamUrls = [];
+    const liveHooks = {
+        ...hooks,
+        onRuntimeStreamReady: async (stream) => {
+            await hooks.onRuntimeStreamReady?.(stream);
+            runtimeStreamUrls.push({ streamId: stream.streamId, url: stream.url });
+            if (liveObserver) {
+                attachObserverRuntimeStreamUrls(liveObserver, runtimeStreamUrls);
+            }
+        }
+    };
+    const env = hooks.env ?? process.env;
+    const render = hooks.renderObserverFn ?? renderObserver;
+    const cloneRoute = config.subject.source === "clone";
+    const localTreeRoute = config.subject.source === "local-tree";
+    // Both routes provision the subject in-sandbox (clone via git, local-tree via pack+upload)
+    // and then share the identical install/build/state/start/probe pipeline, so every seam that
+    // gates on "does this route provision a subject" is keyed on this union, not on cloneRoute
+    // alone.
+    const provisionedRoute = cloneRoute || localTreeRoute;
+    const serve = config.subject.serve;
+    const appUrl = (provisionedRoute ? serve?.url : config.subject.appUrl) ?? "";
+    const subjectRepo = cloneRoute ? config.subject.repos?.[0] ?? "" : undefined;
+    const subjectEnvNames = provisionedRoute ? config.subject.env ?? [] : [];
+    const actor = config.actors[0];
+    const actorType = actor?.type ?? "";
+    const fail = (code, message, actorLabel) => ({
+        schema: CUA_ACTOR_LAB_SCHEMA,
+        ok: false,
+        cwd,
+        labId: config.id,
+        actor: actorLabel ?? actorType,
+        appUrl,
+        dryRun,
+        runId: options.runId ?? "not-created",
+        lanes: [],
+        warnings: [],
+        error: { code, message }
+    });
+    // Resolve the actor through the registry — the parse layer validated this, but the engine fails
+    // closed rather than trusting a config that arrived through another door.
+    const descriptor = actorRegistry[actorType];
+    if (!descriptor || !isCuaActorDescriptor(descriptor)) {
+        return fail("HUMANISH_CUA_LAB_ACTOR_UNSUPPORTED", `actors[0].type "${actorType}" is not a registered computer-use actor.`);
+    }
+    const runSession = hooks.runSession ?? descriptor.runSession;
+    const inProcessRoute = hooks.buildExecutor !== undefined;
+    const localAppSubject = config.subject.source === "local-app";
+    // Engine re-enforcement of the clone-route structure (library API surface).
+    if (cloneRoute && (!serve || !subjectRepo || !/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(subjectRepo))) {
+        return fail("HUMANISH_CUA_LAB_SUBJECT_INVALID", !serve
+            ? "clone subjects on the computer-use route require `subject.serve` (start + url) — the lab serves the app in-sandbox."
+            : `subject.repos[0] must be an owner/repo slug (got "${subjectRepo ?? ""}").`, descriptor.id);
+    }
+    // Engine re-enforcement of the local-tree-route structure (library API surface): a caller
+    // driving this function directly (bypassing parseLabConfig) still gets the same fail-closed
+    // shape the parser enforces, naming which requirement is missing.
+    if (localTreeRoute && (!serve || config.execution?.target !== "e2b-desktop")) {
+        return fail("HUMANISH_CUA_LAB_SUBJECT_INVALID", !serve
+            ? "local-tree subjects on the computer-use route require `subject.serve` (start + url): the lab packs and serves the working tree in-sandbox."
+            : "local-tree subjects require `execution.target: e2b-desktop`: the packed working tree is provisioned and served inside a hosted desktop sandbox.", descriptor.id);
+    }
+    // Engine re-enforcement of the state declaration (library API surface).
+    if (config.subject.state) {
+        const stateReason = !provisionedRoute
+            ? "`subject.state` applies only to clone subjects or local-tree subjects (the lab seeds the state it serves)."
+            : subjectStateInvalidReason(config.subject.state, config.subject.env);
+        if (stateReason) {
+            return fail("HUMANISH_CUA_LAB_SUBJECT_INVALID", stateReason, descriptor.id);
+        }
+    }
+    // Re-enforce the entry-target boundary (library API surface).
+    const allowPublicTargets = config.policies?.allowPublicTargets === true;
+    const declaredTargets = [appUrl, ...(actor?.lanes ?? []).map((lane) => lane.target).filter((target) => target !== undefined)];
+    const entryTargetSafe = declaredTargets.every((target) => provisionedRoute || localAppSubject
+        ? isLoopbackUrl(target)
+        : allowPublicTargets
+            ? isHttpUrl(target)
+            : isLoopbackUrl(target));
+    if (!entryTargetSafe) {
+        return fail("HUMANISH_CUA_LAB_SUBJECT_UNSAFE", provisionedRoute || localAppSubject || !allowPublicTargets
+            ? "subject.appUrl and any actors[0].lanes[].target entries must be loopback (127.0.0.1 or localhost) unless policies.allowPublicTargets is set for an app-url subject."
+            : "subject.appUrl and actors[0].lanes[].target entries must be valid http(s) URLs.", descriptor.id);
+    }
+    // In-process route pairing guard (boot-time, BEFORE key-gating): a custom executor needs a
+    // custom provider too (the default OpenAI provider is vision-based and would fail closed).
+    if (hooks.buildExecutor !== undefined && hooks.buildProvider === undefined) {
+        return fail("HUMANISH_CUA_LAB_EXECUTOR_NO_PROVIDER", "cuaHooks.buildExecutor requires cuaHooks.buildProvider — a state-driven executor returns no screenshot, so it must be paired with a NON-vision provider (the default OpenAI computer-use provider is vision-based and would fail closed).", descriptor.id);
+    }
+    // local-app fail-closed (BEFORE key-gating): there is no built-in in-process driver.
+    if (localAppSubject && !inProcessRoute) {
+        return fail("HUMANISH_CUA_LAB_LOCAL_APP_NO_EXECUTOR", "subject.source: local-app requires a library caller to supply cuaHooks.buildExecutor + buildProvider; there is no built-in driver for an in-process JS contract. (Drive the app via runLab(..., { cuaHooks: { buildExecutor, buildProvider } }).)", descriptor.id);
+    }
+    // Re-enforce the fan-out cross-validation (library API surface): lanes XOR count/laneFocus,
+    // device XOR raw resolution, cap, unique ids, allowPublicTargets+N>1, clone.fanout.
+    const fanoutReason = cuaLaneValidationReason(config);
+    if (fanoutReason) {
+        return fail("HUMANISH_CUA_LAB_FANOUT_INVALID", fanoutReason, descriptor.id);
+    }
+    // Resolve the lane plan (pure) — the SAME table for dry-run and live.
+    let { lanes: laneSpecs, plan } = laneSpecsAndPlan(config, {
+        ...(options.countOverride === undefined ? {} : { countOverride: options.countOverride }),
+        env,
+        dryRun
+    });
+    let laneCount = laneSpecs.length;
+    if (laneCount > MAX_CUA_LANES) {
+        return fail("HUMANISH_CUA_LAB_FANOUT_INVALID", `Computer-use fan-out is capped at ${MAX_CUA_LANES} lanes (resolved ${laneCount}); N concurrent paid desktops is real spend.`, descriptor.id);
+    }
+    if (inProcessRoute && laneCount > 1) {
+        return fail("HUMANISH_CUA_LAB_FANOUT_INVALID", "Multi-lane fan-out is not supported on the in-process route (cuaHooks.buildExecutor) — fan-out provisions one independent E2B desktop per lane, which the in-process route deliberately skips. Run a single in-process lane, or fan out on the E2B route.", descriptor.id);
+    }
+    let rerunLineage;
+    if (options.rerun) {
+        const selected = await resolveCuaRerunSelection({
+            cwd,
+            config,
+            sourceRunId: options.rerun.sourceRunId,
+            ...(options.rerun.laneIds === undefined ? {} : { laneIds: options.rerun.laneIds }),
+            laneSpecs,
+            plan
+        });
+        if (!selected.ok) {
+            return fail("HUMANISH_CUA_LAB_RERUN_INVALID", selected.message, descriptor.id);
+        }
+        laneSpecs = selected.laneSpecs;
+        plan = selected.plan;
+        laneCount = laneSpecs.length;
+        rerunLineage = selected.rerun;
+    }
+    // Pre-flight plan: BEFORE any sandbox or provider call (dry-run AND live). The hook fires for
+    // every N (observable + testable); the stderr table prints for fan-out (N>1) so single-lane
+    // runs stay as quiet as they always were.
+    if (laneCount > 1) {
+        emitPreflightPlan(plan, config.id);
+    }
+    hooks.onPreflight?.(plan);
+    // Read keys once into locals (names only; values never logged or persisted).
+    const openaiApiKey = env.OPENAI_API_KEY?.trim() ?? "";
+    const e2bApiKey = env.E2B_API_KEY?.trim() ?? "";
+    // Literal scrubber for every known provisioned value (no secret "shape" to pattern-match).
+    const knownSecretValues = [
+        openaiApiKey,
+        e2bApiKey,
+        ...subjectEnvNames.map((name) => env[name] ?? "")
+    ].filter((value) => value.length >= 4);
+    const scrubKnownValues = (text) => knownSecretValues.reduce((current, value) => current.split(value).join("[REDACTED_SECRET]"), text);
+    const redactRepoLabel = config.policies?.redactRepos ?? subjectEnvNames.includes("GITHUB_TOKEN");
+    const publicRepo = cloneRoute && subjectRepo ? (redactRepoLabel ? "repo-01" : subjectRepo) : undefined;
+    const hasGithubToken = subjectEnvNames.includes("GITHUB_TOKEN");
+    // Key-gating is route-aware: the in-process route uses the caller's OWN model + executor.
+    if (!dryRun && !inProcessRoute) {
+        const missingKeys = [
+            ...(openaiApiKey ? [] : ["OPENAI_API_KEY"]),
+            ...(e2bApiKey ? [] : ["E2B_API_KEY"])
+        ];
+        if (missingKeys.length > 0) {
+            return fail("HUMANISH_CUA_LAB_KEYS_MISSING", `Live computer-use labs need ${missingKeys.join(" and ")} in the environment (pass them via --env-file; values are never persisted).`, descriptor.id);
+        }
+        const missingSubjectEnv = subjectEnvNames.filter((name) => !env[name]?.trim());
+        if (missingSubjectEnv.length > 0) {
+            return fail("HUMANISH_CUA_LAB_SUBJECT_ENV_MISSING", `subject.env declares ${missingSubjectEnv.join(", ")} but the environment does not provide ${missingSubjectEnv.length === 1 ? "it" : "them"} (pass via --env-file; values are never persisted).`, descriptor.id);
+        }
+    }
+    const runId = options.runId ?? makeCuaRunId();
+    const artifactRoot = path.join(cwd, ".humanish", "runs", runId);
+    const createdAt = new Date().toISOString();
+    const timeoutMs = config.execution?.timeoutMs ?? DEFAULT_SESSION_TIMEOUT_MS;
+    const requestTimeoutMs = readPositiveInt(env.HUMANISH_E2B_REQUEST_TIMEOUT_MS, 60_000);
+    const redactScreenshots = config.policies?.redactScreenshots === true;
+    await mkdir(path.join(artifactRoot, "screenshots"), { recursive: true });
+    const source = await buildRunSource({
+        capturedAt: createdAt,
+        cwd,
+        humanishSource: "present",
+        packageName: "humanish"
+    });
+    // Pack the working tree ONCE per run, on the host, BEFORE any sandbox or provider call: every
+    // fan-out lane below uploads this SAME archive, so one archiveSha256 describes every lane's
+    // digest. Dry-run packs nothing (no fs side effects; the contract bundle carries no
+    // archiveSha256). A packing failure fails the run closed here, before createDesktopSandbox is
+    // ever reached.
+    let localTreeArchive;
+    let localTreeArchiveBuffer;
+    if (localTreeRoute && !dryRun) {
+        const packLocalTree = hooks.packLocalTree ?? defaultPackLocalTree;
+        try {
+            const packed = await packLocalTree({
+                root: cwd,
+                ...(config.subject.localTree?.exclude === undefined ? {} : { extraExclude: config.subject.localTree.exclude }),
+                ...(config.subject.localTree?.maxArchiveBytes === undefined ? {} : { maxArchiveBytes: config.subject.localTree.maxArchiveBytes })
+            });
+            localTreeArchive = packed.archive;
+            localTreeArchiveBuffer = packed.buffer;
+            // One operator-facing line (stderr, same channel as emitPreflightPlan): what left the
+            // host, by counts and digest only, never paths or file names.
+            process.stderr.write(`humanish local-tree: packed ${packed.archive.fileCount} entries, ${packed.archive.totalBytes} bytes, archiveSha256 ${packed.archive.archiveSha256}`
+                + `${packed.archive.git ? ` (commit ${packed.archive.git.commit.slice(0, 12)}, ${packed.archive.git.dirty ? "dirty" : "clean"} working tree)` : " (not a git work tree)"}\n`);
+        }
+        catch (error) {
+            return fail("HUMANISH_CUA_LAB_SUBJECT_INVALID", `local-tree packing failed: ${redactText(scrubKnownValues(toErrorMessage(error)))}`, descriptor.id);
+        }
+    }
+    const deps = {
+        config,
+        descriptor,
+        appUrl,
+        cloneRoute,
+        localTreeRoute,
+        ...(serve === undefined ? {} : { serve }),
+        ...(subjectRepo === undefined ? {} : { subjectRepo }),
+        subjectEnvNames,
+        hasGithubToken,
+        ...(localTreeArchiveBuffer === undefined ? {} : { localTreeArchiveBuffer }),
+        env,
+        openaiApiKey,
+        e2bApiKey,
+        requestTimeoutMs,
+        perLaneSandboxMs: resolvePerLaneSandboxMs(config),
+        timeoutMs,
+        laneCount,
+        artifactRoot,
+        redactScreenshots,
+        scrubKnownValues,
+        runSession,
+        hooks: liveHooks
+    };
+    const inProgressLaneSubjects = laneSpecs.map(() => laneSubjectProjection({
+        cloneRoute,
+        localTreeRoute,
+        ...(publicRepo === undefined ? {} : { publicRepo }),
+        subjectEnvNames,
+        ...(localTreeArchive === undefined ? {} : { localTreeArchive }),
+        subjectState: resolveSubjectState({
+            declared: provisionedRoute ? config.subject.state : undefined,
+            dryRun: false,
+            executed: []
+        })
+    }));
+    const inProgressAggregateSubject = inProgressLaneSubjects[0];
+    const inProgressProvenance = subjectProvenanceArg(inProgressAggregateSubject, publicRepo, subjectEnvNames);
+    if (!dryRun && options.onObserverReady) {
+        const inProgressBundle = laneCount === 1 && rerunLineage === undefined
+            ? buildSingleLaneBundle({
+                spec: laneSpecs[0],
+                outcome: undefined,
+                descriptor,
+                appUrl: laneSpecs[0].targetUrl ?? appUrl,
+                createdAt,
+                dryRun: false,
+                config,
+                runId,
+                source,
+                redactScreenshots,
+                inProgress: true,
+                ...(inProgressProvenance === undefined ? {} : { subjectProvenance: inProgressProvenance }),
+                inProcessRoute,
+                localAppSubject
+            })
+            : buildCuaFanoutBundle({
+                specs: laneSpecs,
+                laneSubjects: inProgressLaneSubjects,
+                aggregateSubject: inProgressAggregateSubject,
+                descriptor,
+                appUrl,
+                createdAt,
+                dryRun: false,
+                config,
+                runId,
+                source,
+                plan,
+                ...(rerunLineage === undefined ? {} : { rerun: rerunLineage }),
+                cloneRoute,
+                localTreeRoute,
+                ...(publicRepo === undefined ? {} : { publicRepo }),
+                subjectEnvNames,
+                inProgress: true
+            });
+        await writeCuaRunArtifacts(cwd, artifactRoot, inProgressBundle, createdAt);
+        liveObserver = observerResultForCuaArtifacts(cwd, runId, artifactRoot, [
+            "Live CUA Observer is attached before final verification; stream auth URLs are runtime-only and are not persisted."
+        ]);
+        await options.onObserverReady(liveObserver);
+    }
+    // Run lanes (dry-run runs none). In-process is always one lane.
+    let outcomes;
+    let failFastReason;
+    if (!dryRun) {
+        if (inProcessRoute) {
+            outcomes = [await runInProcessLane(laneSpecs[0], deps)];
+        }
+        else if (laneCount === 1) {
+            outcomes = [await runCuaLane(laneSpecs[0], deps)];
+        }
+        else {
+            const ran = await runCuaLanes(laneSpecs, deps, plan.concurrency);
+            outcomes = ran.outcomes;
+            failFastReason = ran.failFastReason;
+        }
+    }
+    // Per-lane subject projections (invariant 5).
+    const laneSubjects = laneSpecs.map((_spec, index) => {
+        const outcome = outcomes?.[index];
+        const subjectState = resolveSubjectState({
+            declared: provisionedRoute ? config.subject.state : undefined,
+            dryRun,
+            executed: outcome?.stateStepRecords ?? []
+        });
+        return laneSubjectProjection({
+            cloneRoute,
+            localTreeRoute,
+            ...(publicRepo === undefined ? {} : { publicRepo }),
+            subjectEnvNames,
+            ...(outcome?.subjectCommit === undefined ? {} : { subjectCommit: outcome.subjectCommit }),
+            ...(localTreeArchive === undefined ? {} : { localTreeArchive }),
+            subjectState
+        });
+    });
+    // Aggregate subject (top-level + bundle): unanimity-gated commit (+ divergence warning) on
+    // the clone route. Local-tree lanes all pack from the SAME once-per-run archive, so every
+    // lane's projection already carries the identical archiveSha256/commit/dirty: the
+    // `first.source !== "clone"` branch below returns it directly, with no unanimity math needed
+    // (there is nothing that could diverge).
+    const aggregateWarnings = [];
+    const aggregateSubject = (() => {
+        const first = laneSubjects[0];
+        if (first.source !== "clone") {
+            return first;
+        }
+        const commits = (outcomes ?? []).map((outcome) => outcome.subjectCommit).filter((commit) => commit !== undefined);
+        const unanimous = !dryRun && commits.length === laneCount && new Set(commits).size === 1;
+        if (!dryRun && laneCount > 1 && new Set(commits).size > 1) {
+            aggregateWarnings.push("Fan-out lanes resolved DIVERGENT subject commits — the top-level subject.commit is omitted; see per-lane provenance in result.lanes for each lane's pinned commit.");
+        }
+        // Build without commit, then add it only when unanimous (avoids an explicit commit:undefined
+        // under exactOptionalPropertyTypes).
+        return {
+            source: "clone",
+            ...(first.repo === undefined ? {} : { repo: first.repo }),
+            ...(first.envNames === undefined ? {} : { envNames: first.envNames }),
+            state: first.state,
+            ...(unanimous && commits[0] !== undefined ? { commit: commits[0] } : {})
+        };
+    })();
+    const finalProvenance = subjectProvenanceArg(aggregateSubject, publicRepo, subjectEnvNames);
+    const bundle = laneCount === 1 && rerunLineage === undefined
+        ? buildSingleLaneBundle({
+            spec: laneSpecs[0],
+            outcome: outcomes?.[0],
+            descriptor,
+            appUrl: laneSpecs[0].targetUrl ?? appUrl,
+            createdAt,
+            dryRun,
+            config,
+            runId,
+            source,
+            redactScreenshots,
+            ...(finalProvenance === undefined ? {} : { subjectProvenance: finalProvenance }),
+            inProcessRoute,
+            localAppSubject
+        })
+        : buildCuaFanoutBundle({
+            specs: laneSpecs,
+            ...(outcomes === undefined ? {} : { outcomes }),
+            laneSubjects,
+            aggregateSubject,
+            descriptor,
+            appUrl,
+            createdAt,
+            dryRun,
+            config,
+            runId,
+            source,
+            plan,
+            ...(rerunLineage === undefined ? {} : { rerun: rerunLineage }),
+            ...(failFastReason === undefined ? {} : { failFastReason }),
+            cloneRoute,
+            localTreeRoute,
+            ...(publicRepo === undefined ? {} : { publicRepo }),
+            subjectEnvNames
+        });
+    const adapterWarnings = [];
+    await applyBrowserAdapterHooks({
+        hooks,
+        bundle,
+        context: {
+            bundle,
+            runDir: artifactRoot,
+            labId: config.id,
+            runId,
+            actor: descriptor.id,
+            backend: "cua",
+            dryRun,
+            laneCount
+        },
+        sanitize: (text) => redactText(scrubKnownValues(text)),
+        warnings: adapterWarnings,
+        hookLabel: "cuaHooks"
+    });
+    await writeCuaRunArtifacts(cwd, artifactRoot, bundle, createdAt);
+    const observer = await render(cwd, runId, { open: options.open === true });
+    if (observer.ok && runtimeStreamUrls.length > 0) {
+        attachObserverRuntimeStreamUrls(observer, runtimeStreamUrls);
+    }
+    // Lane-level pass: dry-run lanes are contract-ok; live lanes need a passed, engaged session.
+    const laneOk = (outcome) => laneOutcomeOk(outcome, dryRun);
+    const allLanesOk = laneSpecs.every((_, index) => laneOk(outcomes?.[index]));
+    const adapterFailure = adapterScoreFailureMessage(bundle);
+    const ok = observer.ok && allLanesOk && adapterFailure === undefined;
+    const laneWarnings = (outcomes ?? []).flatMap((outcome) => outcome.warnings);
+    const warnings = [...laneWarnings, ...aggregateWarnings, ...adapterWarnings, ...observer.warnings];
+    const laneResults = laneSpecs.map((spec, index) => toLaneResult(spec, outcomes?.[index], laneSubjects[index], dryRun));
+    const laneSummary = buildLaneSummary(outcomes, laneCount, plan, dryRun);
+    const firstOutcome = outcomes?.[0];
+    const errorResult = (() => {
+        if (ok)
+            return undefined;
+        if (adapterFailure !== undefined) {
+            return {
+                code: "HUMANISH_CUA_LAB_FAILED",
+                message: adapterFailure
+            };
+        }
+        if (laneCount === 1) {
+            const outcome = firstOutcome;
+            return {
+                code: outcome?.failureCode ?? "HUMANISH_CUA_LAB_FAILED",
+                message: outcome?.sessionError
+                    ?? (outcome?.noEngagement
+                        ? "Actor took no actions and produced no message (likely a blank/still-loading screen); not a credible goal_satisfied."
+                        : observer.ok
+                            ? outcome?.session?.completionReason === "harness_error"
+                                ? `Computer-use session ended with a harness error: ${outcome.session.reason}`
+                                : outcome?.session?.status !== "passed"
+                                    ? `Computer-use session ended with ${outcome?.session?.status ?? "unknown"}: ${outcome?.session?.reason ?? "no terminal reason"}`
+                                    : "Computer-use lab did not produce a terminal session."
+                            : observer.error?.message ?? "Observer failed for the computer-use lab run.")
+            };
+        }
+        const failingLane = (outcomes ?? []).find((outcome) => !laneOk(outcome));
+        const geometryLane = (outcomes ?? []).find((outcome) => outcome.failureCode === "HUMANISH_CUA_LAB_DEVICE_GEOMETRY");
+        const code = geometryLane?.failureCode ?? "HUMANISH_CUA_LAB_FAILED";
+        return {
+            code,
+            message: observer.ok
+                ? `Fan-out run failed: ${laneSummary.passed}/${laneCount} lane(s) passed (${laneSummary.skipped} skipped, ${laneSummary.harnessErrors} harness error(s), ${laneSummary.hollow} hollow)${failingLane?.sessionError ? `; first failure: ${failingLane.sessionError}` : ""}.`
+                : observer.error?.message ?? "Observer failed for the computer-use fan-out run."
+        };
+    })();
+    return {
+        schema: CUA_ACTOR_LAB_SCHEMA,
+        ok,
+        cwd,
+        labId: config.id,
+        actor: descriptor.id,
+        appUrl,
+        dryRun,
+        runId,
+        ...(firstOutcome?.session
+            ? {
+                session: {
+                    status: firstOutcome.session.status,
+                    completionReason: firstOutcome.session.completionReason,
+                    reason: firstOutcome.session.reason,
+                    screenshots: firstOutcome.screenshots.length
+                }
+            }
+            : {}),
+        ...(firstOutcome?.sandboxId
+            ? { sandbox: { sandboxId: firstOutcome.sandboxId, killed: firstOutcome.killed, streamUrlPresent: firstOutcome.streamUrlPresent } }
+            : {}),
+        subject: aggregateSubject,
+        plan,
+        lanes: laneResults,
+        laneSummary,
+        ...(rerunLineage === undefined ? {} : { rerun: rerunLineage }),
+        observer,
+        warnings,
+        ...(errorResult === undefined ? {} : { error: errorResult })
+    };
+}
+/** Aggregate lane counts for the result projection. */
+function buildLaneSummary(outcomes, laneCount, plan, dryRun) {
+    if (dryRun || !outcomes) {
+        return {
+            strategy: CUA_FANOUT_STRATEGY,
+            total: laneCount,
+            passed: 0,
+            skipped: 0,
+            harnessErrors: 0,
+            hollow: 0,
+            concurrency: plan.concurrency,
+            waves: plan.waves
+        };
+    }
+    let passed = 0;
+    let skipped = 0;
+    let harnessErrors = 0;
+    let hollow = 0;
+    for (const outcome of outcomes) {
+        if (outcome.skippedReason !== undefined) {
+            skipped += 1;
+            continue;
+        }
+        if (outcome.harnessError)
+            harnessErrors += 1;
+        if (outcome.noEngagement)
+            hollow += 1;
+        if (laneOutcomeOk(outcome, dryRun))
+            passed += 1;
+    }
+    return {
+        strategy: CUA_FANOUT_STRATEGY,
+        total: laneCount,
+        passed,
+        skipped,
+        harnessErrors,
+        hollow,
+        concurrency: plan.concurrency,
+        waves: plan.waves
+    };
+}
+async function writeCuaRunArtifacts(cwd, artifactRoot, bundle, updatedAt) {
+    const publicBundle = {
+        ...bundle,
+        cwd: PUBLIC_TARGET_CWD
+    };
+    await writeFile(path.join(artifactRoot, "run.json"), `${JSON.stringify(publicBundle, null, 2)}\n`, "utf8");
+    await writeFile(path.join(artifactRoot, "review.json"), `${JSON.stringify(publicBundle.review, null, 2)}\n`, "utf8");
+    await writeFile(path.join(artifactRoot, "review.md"), renderCuaReviewMarkdown(publicBundle), "utf8");
+    await writeFile(path.join(artifactRoot, "events.ndjson"), `${publicBundle.events.map((event) => JSON.stringify(event)).join("\n")}\n`, "utf8");
+    await mkdir(path.join(artifactRoot, "observer"), { recursive: true });
+    await writeFile(path.join(artifactRoot, "observer", "observer-data.json"), `${JSON.stringify(buildObserverData(publicBundle), null, 2)}\n`, "utf8");
+    await writeFile(path.join(cwd, ".humanish", "runs", "latest.json"), `${JSON.stringify({
+        schema: "humanish.latest-run.v1",
+        runId: publicBundle.runId,
+        path: path.join(".humanish", "runs", publicBundle.runId),
+        updatedAt
+    }, null, 2)}\n`, "utf8");
+}
+function observerResultForCuaArtifacts(cwd, runId, artifactRoot, warnings = []) {
+    const observerPath = path.join(artifactRoot, "observer", "index.html");
+    const observerDataPath = path.join(artifactRoot, "observer", "observer-data.json");
+    const eventsPath = path.join(artifactRoot, "events.ndjson");
+    return {
+        schema: "humanish.observer-result.v1",
+        ok: true,
+        cwd,
+        run: runId,
+        observerPath: path.relative(cwd, observerPath),
+        observerDataPath: path.relative(cwd, observerDataPath),
+        eventsPath: path.relative(cwd, eventsPath),
+        observerUrl: pathToFileURL(observerPath).href,
+        bundlePath: path.join(artifactRoot, "run.json"),
+        opened: false,
+        warnings
+    };
+}
+/** Build the N=1 bundle via the unchanged buildCuaBundle (byte-stable). */
+function buildSingleLaneBundle(args) {
+    const { spec, outcome, config } = args;
+    return buildCuaBundle({
+        actorId: args.descriptor.id,
+        appUrl: args.appUrl,
+        laneId: spec.laneId,
+        ...(spec.actorType === undefined ? {} : { actorType: spec.actorType }),
+        ...(spec.surface === undefined ? {} : { surface: spec.surface }),
+        ...(spec.caseGroup === undefined ? {} : { caseGroup: spec.caseGroup }),
+        createdAt: args.createdAt,
+        dryRun: args.dryRun,
+        labId: config.id,
+        ...(config.title ? { labTitle: config.title } : {}),
+        mission: spec.instructions,
+        persona: spec.persona,
+        resolution: spec.resolution,
+        deviceScaleFactor: spec.devicePreset.deviceScaleFactor,
+        isMobile: spec.devicePreset.isMobile,
+        runId: args.runId,
+        screenshots: outcome?.screenshots ?? [],
+        captureRedaction: args.redactScreenshots ? "blurred" : "raw",
+        ...(outcome?.session ? { session: outcome.session } : {}),
+        ...(outcome?.sessionError ? { sessionError: outcome.sessionError } : {}),
+        source: args.source,
+        ...(args.inProgress === undefined ? {} : { inProgress: args.inProgress }),
+        ...(args.subjectProvenance === undefined ? {} : { subjectProvenance: args.subjectProvenance }),
+        ...(config.execution?.desktop?.template === undefined ? {} : { desktopTemplate: config.execution.desktop.template }),
+        ...(outcome?.desktopBrowser === undefined ? {} : { desktopBrowser: outcome.desktopBrowser }),
+        providerResources: providerResourcesForOutcome({
+            outcome,
+            createdAt: args.createdAt,
+            simId: spec.simId,
+            streamId: spec.streamId,
+            laneId: spec.laneId
+        }),
+        ...(args.localAppSubject || args.inProcessRoute ? { entryKind: "local-app" } : {}),
+        ...(outcome?.session ? { traceArtifactPath: spec.traceArtifactPath } : {}),
+        phaseEvents: outcome?.phaseRecords ?? []
+    });
+}
+/**
+ * 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})`);
+    };
+    if (args.serve.install) {
+        const installStartedAt = now();
+        emitPhaseStarted(args.onPhase, now, "install", "installing subject dependencies");
+        const install = await runDetachedStep(desktop, {
+            name: "subject-install",
+            command: args.serve.install,
+            cwd: SUBJECT_DIR,
+            timeoutMs: args.serve.installTimeoutMs ?? INSTALL_TIMEOUT_MS,
+            requestTimeoutMs: args.requestTimeoutMs,
+            ...timers
+        });
+        emitPhaseCompleted(args.onPhase, now, installStartedAt, "install", install.ok, install.ok ? "subject dependencies installed" : "subject install failed");
+        if (!install.ok) {
+            throw new Error(`subject install ${install.timedOut ? "timed out" : `failed (exit ${install.exitCode})`}: ${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 desktop.files.write(LOCAL_TREE_REMOTE_ARCHIVE_PATH, args.archiveBuffer, {
+            requestTimeoutMs: args.requestTimeoutMs,
+            useOctetStream: true
+        });
+    }
+    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
+    });
+}
+/**
+ * Default local-tree packing implementation: createLocalTreeArchive(root, opts) on the host,
+ * then a single read of the produced archive file into an ArrayBuffer for upload. The DI seam
+ * (CuaActorLabHooks.packLocalTree) overrides this in deterministic tests so they never require
+ * tar/git.
+ */
+export async function defaultPackLocalTree(args) {
+    const archive = createLocalTreeArchive(args.root, {
+        ...(args.extraExclude === undefined ? {} : { extraExclude: args.extraExclude }),
+        ...(args.maxArchiveBytes === undefined ? {} : { maxArchiveBytes: args.maxArchiveBytes })
+    });
+    const bytes = await readFile(archive.archivePath);
+    const buffer = bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength);
+    // The archive was written to a fresh mkdtemp dir (no outputPath passed above); once the
+    // bytes are buffered the on-disk copy is pure residue, and a packed working tree left in
+    // the host tmpdir is itself a small leak surface. Best-effort removal.
+    await rm(path.dirname(archive.archivePath), { recursive: true, force: true }).catch(() => undefined);
+    return { archive, buffer };
+}
+/** sha256 hex of the exact command string, first 16 chars (the promptDigest convention). */
+export function commandDigestOf(command) {
+    return digestText(command, 16);
+}
+/**
+ * Resolve the bundle's state marker from the declaration and what actually ran.
+ * Precedence: external declared → "unpinned" (seed records, if any, stay attached — a
+ * migrated external DB is still unpinned overall); else seed declared → "seeded" only when
+ * every declared step executed ok on a live run, otherwise "declared-not-run" (dry-run
+ * contract bundles and failed live provisioning); no declaration → "undeclared".
+ */
+export function resolveSubjectState(args) {
+    const declared = args.declared;
+    if (!declared) {
+        return { provenance: "undeclared" };
+    }
+    const declaredSeed = declared.seed ?? [];
+    const external = declared.external ?? [];
+    // Dry-run: nothing executes (no sandbox) — record the DECLARED recipe: name, phase, and
+    // command digest only, with NO execution fields.
+    const seed = args.dryRun
+        ? declaredSeed.map((step) => ({
+            name: step.name,
+            when: step.when ?? "before-start",
+            commandDigest: commandDigestOf(step.command)
+        }))
+        : args.executed;
+    const allRanOk = !args.dryRun
+        && declaredSeed.length > 0
+        && seed.length === declaredSeed.length
+        && seed.every((record) => record.ok === true);
+    const provenance = external.length > 0
+        ? "unpinned"
+        : declaredSeed.length === 0
+            ? "undeclared"
+            : allRanOk
+                ? "seeded"
+                : "declared-not-run";
+    return {
+        provenance,
+        ...(seed.length > 0 ? { seed } : {}),
+        ...(external.length > 0 ? { externalEnvNames: external } : {})
+    };
+}
+/** The human-readable state story appended to the provenance event (and review.md via it). */
+function describeSubjectState(state, dryRun) {
+    switch (state.provenance) {
+        case "seeded":
+            return `seeded (${state.seed?.length ?? 0} step(s): ${(state.seed ?? []).map((record) => record.name).join(", ")})`;
+        case "unpinned":
+            return `UNPINNED (external: ${(state.externalEnvNames ?? []).join(", ")})`;
+        case "declared-not-run":
+            return `declared, not run (${dryRun ? "dry-run contract" : "provisioning did not complete"})`;
+        case "undeclared":
+            return "undeclared";
+    }
+}
+// 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);
+}
+/**
+ * Project a computer-use session into a humanish.run-bundle.v1. The load-bearing line is
+ * `stream.actor = session.trace` — the provider-neutral ActorTrace seam the Observer renders.
+ * Exported for the bundle-builder tests.
+ */
+export function buildCuaBundle(args) {
+    const publicAppUrl = publicSafeAppUrlLabel(args.appUrl);
+    const status = args.inProgress === true
+        ? "running"
+        : args.session
+            ? args.session.status
+            : args.sessionError
+                ? "failed"
+                : "contract_proof_only";
+    const reason = args.inProgress === true
+        ? "Live computer-use session is running; stream auth URL is available only through the attached Observer server."
+        : args.session?.reason
+            ?? args.sessionError
+            ?? "Contract bundle only: dry-run produced the evidence shape without launching a desktop or spending provider tokens.";
+    const lastScreenshot = args.screenshots[args.screenshots.length - 1];
+    // Honest labels (invariant 6: claims match mechanism): every screenshot label names the
+    // run's ACTUAL mode. The session trace is the evidence-of-record; the capture policy covers
+    // frames written before a mid-session failure produced a trace.
+    const traceScreenshotMode = args.session?.trace.redaction.screenshots;
+    const screenshotMode = traceScreenshotMode === "raw" || traceScreenshotMode === "blurred"
+        ? traceScreenshotMode
+        : args.captureRedaction ?? "raw";
+    const simulation = {
+        id: "sim-001",
+        index: 1,
+        personaId: args.persona.id,
+        scenarioId: `cua-${args.labId}`,
+        status,
+        streamKind: "browser",
+        mode: "browser-sim",
+        progress: args.inProgress === true ? 20 : 100,
+        currentStep: reason,
+        summary: args.session
+            ? `Computer-use actor (${args.actorId}) drove the subject app in a hosted desktop browser; ${args.session.completionReason}.`
+            : args.inProgress === true
+                ? `Computer-use actor (${args.actorId}) is driving the subject app in a hosted desktop browser.`
+                : args.sessionError
+                    ? `Computer-use lab failed before a terminal session verdict: ${args.sessionError}`
+                    : `Contract lane for the computer-use actor (${args.actorId}) against ${publicAppUrl}.`,
+        streamIds: ["stream-001"],
+        startedAt: args.createdAt,
+        updatedAt: args.createdAt
+    };
+    const stream = {
+        id: "stream-001",
+        simId: "sim-001",
+        laneId: args.laneId ?? "lane-01",
+        ...(args.actorType === undefined ? {} : { actorType: args.actorType }),
+        ...(args.surface === undefined ? {} : { surface: args.surface }),
+        ...(args.caseGroup === undefined ? {} : { caseGroup: args.caseGroup }),
+        kind: "browser",
+        label: `CUA browser — ${args.labId}`,
+        status,
+        transport: "snapshot",
+        updatedAt: args.createdAt,
+        embed: lastScreenshot
+            ? { kind: "screenshot", url: lastScreenshot, title: `CUA desktop (${screenshotMode})` }
+            : { kind: "placeholder", title: "CUA desktop" },
+        viewport: {
+            width: args.resolution[0],
+            height: args.resolution[1],
+            deviceScaleFactor: args.deviceScaleFactor ?? 1,
+            ...(args.isMobile === undefined ? {} : { isMobile: args.isMobile })
+        },
+        ui: {
+            route: publicAppUrl,
+            intent: "Watch the computer-use actor drive the subject app in a hosted desktop browser.",
+            state: reason,
+            ...(args.session ? { actorStatus: args.session.status } : {}),
+            ...(lastScreenshot ? { screenshotUrl: lastScreenshot } : {})
+        },
+        // The seam this lab exists to fill: the provider-neutral actor evidence projection.
+        ...(args.session ? { actor: args.session.trace } : {}),
+        artifacts: [
+            { label: "run bundle", path: "run.json", kind: "bundle" },
+            { label: "review", path: "review.md", kind: "review" },
+            { label: "events", path: "events.ndjson", kind: "events" },
+            ...(args.traceArtifactPath
+                ? [{ label: "actor trace", path: args.traceArtifactPath, kind: "trace" }]
+                : []),
+            ...args.screenshots.map((screenshot, index) => ({
+                label: `screenshot ${String(index + 1).padStart(2, "0")} (${screenshotMode})`,
+                path: screenshot,
+                kind: "screenshot"
+            }))
+        ]
+    };
+    const events = [
+        {
+            id: "event-000-created",
+            at: args.createdAt,
+            level: "info",
+            type: "cua-lab.run.created",
+            message: `Created computer-use lab run for ${args.labId} (actor ${args.actorId}).`
+        },
+        args.subjectProvenance
+            ? {
+                id: "event-001-subject",
+                at: args.createdAt,
+                level: "info",
+                type: "cua-lab.subject.provenance",
+                // HONEST WORDING: claim "cloned/packed and served" only when it actually happened.
+                message: `${subjectProvenanceMessage(args.subjectProvenance, publicAppUrl, args.dryRun, args.session !== undefined)} (subject env names: ${args.subjectProvenance.envNames.length > 0 ? args.subjectProvenance.envNames.join(", ") : "none"}; values never persisted); state: ${describeSubjectState(args.subjectProvenance.state, args.dryRun)}.`,
+                simId: "sim-001",
+                streamId: "stream-001"
+            }
+            : {
+                id: "event-001-subject",
+                at: args.createdAt,
+                level: "info",
+                type: "cua-lab.subject.declared",
+                // Invariant 5: declare what the subject WAS, including the ABSENCE of a pin. A
+                // local-app / in-process subject is an already-running LOCAL dev server the caller
+                // provisioned; it cannot be commit-pinned, so its provenance is honestly UNPINNED and
+                // no E2B desktop was created. A plain app-url entry runs inside the desktop sandbox.
+                message: args.entryKind === "local-app"
+                    ? `Subject app declared at ${publicAppUrl} (already-running LOCAL dev server driven in-process; NO clone, NO E2B desktop). Provenance: caller-provisioned and UNPINNED — a running dev server cannot be commit-pinned.`
+                    : `Subject app declared at ${publicAppUrl} (loopback inside the desktop sandbox).`,
+                simId: "sim-001",
+                streamId: "stream-001"
+            },
+        args.session
+            ? {
+                id: "event-002-session",
+                at: args.createdAt,
+                level: args.session.status === "passed" ? "info" : "warn",
+                type: `cua-lab.session.${args.session.completionReason}`,
+                message: `${args.session.status}: ${args.session.reason}`,
+                simId: "sim-001",
+                streamId: "stream-001"
+            }
+            : args.inProgress === true
+                ? {
+                    id: "event-002-running",
+                    at: args.createdAt,
+                    level: "info",
+                    type: "cua-lab.session.running",
+                    message: "Live computer-use session is running; terminal evidence has not been written yet.",
+                    simId: "sim-001",
+                    streamId: "stream-001"
+                }
+                : args.sessionError
+                    ? {
+                        id: "event-002-session",
+                        at: args.createdAt,
+                        level: "error",
+                        type: "cua-lab.session.error",
+                        message: args.sessionError,
+                        simId: "sim-001",
+                        streamId: "stream-001"
+                    }
+                    : {
+                        id: "event-002-contract",
+                        at: args.createdAt,
+                        level: "info",
+                        type: "cua-lab.contract.ready",
+                        message: "Dry-run contract bundle ready; switch scenario.mode to live for a real desktop session.",
+                        simId: "sim-001",
+                        streamId: "stream-001"
+                    }
+    ];
+    // Persisted phase trail (real boot timing, not just a coarse provenance sentence): one
+    // RunEvent per COMPLETED phase boundary (started events never persist here; they carry no
+    // durationMs). ok:false phases warn rather than error, since the failing phase's own thrown
+    // error already becomes the terminal cua-lab.session.error event above.
+    let phaseEventSeq = 3;
+    for (const phase of args.phaseEvents ?? []) {
+        events.push({
+            id: `event-${String(phaseEventSeq++).padStart(3, "0")}-phase-${phaseEventIdSuffix(phase.type)}`,
+            at: phase.at,
+            level: phase.ok === false ? "warn" : "info",
+            type: phase.type,
+            message: phase.durationMs === undefined ? phase.message : `${phase.message} (${phase.durationMs}ms)`,
+            simId: "sim-001",
+            streamId: "stream-001"
+        });
+    }
+    const review = {
+        schema: REVIEW_SCHEMA,
+        verdict: args.inProgress === true
+            ? "contract_proof_only"
+            : args.session
+                ? verdictForStatus(args.session.status)
+                : args.sessionError
+                    ? "fail"
+                    : "contract_proof_only",
+        summary: reason,
+        gaps: args.session || args.sessionError
+            ? []
+            : args.inProgress === true
+                ? ["Live desktop session is still running."]
+                : ["Live desktop session not yet run (dry-run contract only)."]
+    };
+    return {
+        schema: RUN_BUNDLE_SCHEMA,
+        runId: args.runId,
+        mode: args.dryRun ? "dry-run" : "live",
+        simCount: 1,
+        createdAt: args.createdAt,
+        cwd: PUBLIC_TARGET_CWD,
+        artifactRoot: path.join(".humanish", "runs", args.runId),
+        source: args.source,
+        persona: {
+            id: args.persona.id,
+            name: `Computer-use operator (${args.persona.id})`,
+            source: `lab:${args.labId}`,
+            sourceDigest: args.persona.promptDigest
+        },
+        scenario: {
+            id: `cua-${args.labId}`,
+            title: args.labTitle ?? `Computer-use lab: ${args.labId}`,
+            goal: args.mission,
+            source: `lab:${args.labId}`,
+            sourceDigest: args.persona.promptDigest
+        },
+        lifecycle: [
+            {
+                at: args.createdAt,
+                event: "cua-lab.run.created",
+                message: `Created computer-use lab run with one desktop browser lane (actor ${args.actorId}).`
+            }
+        ],
+        simulations: [simulation],
+        streams: [stream],
+        events,
+        redaction: {
+            status: "passed",
+            notes: traceScreenshotMode === "raw"
+                ? "Typed text recorded as length only and reasoning/messages pass through text redaction. Screenshots are FULL-FIDELITY (raw), retained for local use — NOT redacted for publishing; set policies.redactScreenshots: true to blur a share-as-is bundle."
+                : traceScreenshotMode === "blurred"
+                    ? "Typed text recorded as length only and reasoning/messages pass through text redaction. Screenshots are blurred at capture (policies.redactScreenshots: true) for a share-as-is bundle."
+                    : args.screenshots.length > 0
+                        ? `Session ended before a trace was recorded; ${args.screenshots.length} already-written frame(s) follow the capture policy (${screenshotMode}). Typed text is recorded as length only and reasoning/messages pass through text redaction.`
+                        : "No screenshots captured. Typed text is recorded as length only and reasoning/messages pass through text redaction whenever a session runs."
+        },
+        artifacts: {
+            run: "run.json",
+            reviewJson: "review.json",
+            reviewMarkdown: "review.md",
+            observerData: "observer/observer-data.json",
+            events: "events.ndjson"
+        },
+        review,
+        feedbackCandidates: [],
+        // Custom desktop image provenance (omitted on the stock-template default → byte-stable).
+        ...(args.desktopTemplate === undefined ? {} : { desktopTemplate: args.desktopTemplate }),
+        ...(args.desktopBrowser === undefined ? {} : { desktopBrowser: args.desktopBrowser }),
+        ...(args.providerResources === undefined || args.providerResources.length === 0 ? {} : { providerResources: args.providerResources }),
+        // Structured subject provenance (invariant 5): code pin + state story. Uniform and
+        // honest on app-url bundles too — the caller minted the URL, its state is the caller's.
+        // CuaSubjectProvenanceArg's two variants (clone, local-tree) are already RunSubjectProvenance-
+        // shaped, so no reconstruction is needed beyond the app-url fallback.
+        subject: args.subjectProvenance ?? { source: "app-url", state: { provenance: "undeclared" } }
+    };
+}
+/** Human-readable provenance line for the single-lane subject.provenance event (invariant 5):
+ *  claims "cloned/packed and served" ONLY when it actually happened. */
+function subjectProvenanceMessage(provenance, publicAppUrl, dryRun, hasSession) {
+    if (provenance.source === "clone") {
+        if (dryRun) {
+            return `Subject declared: clone of ${provenance.repo}, to be served at ${publicAppUrl} in-sandbox (dry-run contract; nothing cloned)`;
+        }
+        if (provenance.commit) {
+            return hasSession
+                ? `Subject cloned from ${provenance.repo}@${provenance.commit} and served at ${publicAppUrl} in-sandbox`
+                : `Subject cloned from ${provenance.repo}@${provenance.commit}; serving at ${publicAppUrl} did not complete (see session error)`;
+        }
+        return `Subject clone attempted from ${provenance.repo}; commit unresolved (provisioning failed before resolution)`;
+    }
+    if (dryRun) {
+        return `Subject declared: local working tree, to be packed and served at ${publicAppUrl} in-sandbox (dry-run contract; nothing packed)`;
+    }
+    if (provenance.archiveSha256) {
+        const dirtyLabel = provenance.dirty === true ? ", dirty working tree" : provenance.dirty === false ? ", clean working tree" : "";
+        return hasSession
+            ? `Subject packed (archiveSha256 ${provenance.archiveSha256}${dirtyLabel}) and served at ${publicAppUrl} in-sandbox`
+            : `Subject packed (archiveSha256 ${provenance.archiveSha256}${dirtyLabel}); serving at ${publicAppUrl} did not complete (see session error)`;
+    }
+    return "Subject local-tree packing attempted; archive digest unresolved (provisioning failed before resolution)";
+}
+/**
+ * Project N>1 fan-out lanes into a humanish.run-bundle.v1 (the evidence schema is unchanged; this
+ * is a new producer for the multi-stream shape). One sim + one stream per lane; per-lane
+ * provenance/session events; a recorded `cua-lab.fanout.plan` event (and a `cua-lab.fanout.fail-fast`
+ * event when a harness error skipped queued lanes). N-ary verify/Observer already handle multiple
+ * streams. The N=1 path NEVER reaches here (buildCuaBundle owns it, byte-stable).
+ */
+export function buildCuaFanoutBundle(args) {
+    const { specs, outcomes, config } = args;
+    const simulations = [];
+    const streams = [];
+    const events = [];
+    events.push({
+        id: "event-000-created",
+        at: args.createdAt,
+        level: "info",
+        type: "cua-lab.run.created",
+        message: `Created computer-use fan-out run for ${config.id} (actor ${args.descriptor.id}, ${specs.length} lanes, per-lane worlds).`
+    });
+    events.push({
+        id: "event-001-fanout-plan",
+        at: args.createdAt,
+        level: "info",
+        type: "cua-lab.fanout.plan",
+        message: `Fan-out plan: ${args.plan.laneCount} lane(s) (${args.plan.strategy}), concurrency ${args.plan.concurrency}, ${args.plan.waves} wave(s); per-lane session budget ${Math.round(args.plan.perLaneSessionBudgetMs / 1000)}s; worst-case ~${args.plan.worstCaseSandboxMinutes} sandbox-minutes${args.dryRun ? " (dry-run: $0)" : ""}. Lanes: ${args.plan.lanes.map(formatLanePlanEntry).join(", ")}.`
+    });
+    let eventSeq = 2;
+    const nextEventId = (suffix) => `event-${String(eventSeq++).padStart(3, "0")}-${suffix}`;
+    if (args.rerun) {
+        events.push({
+            id: nextEventId("fanout-rerun"),
+            at: args.createdAt,
+            level: "info",
+            type: "cua-lab.fanout.rerun",
+            message: `Rerun selected ${args.rerun.selectedLaneIds.length} lane(s) from ${args.rerun.sourceRunId}: ${args.rerun.previous.map((lane) => `${lane.laneId} was ${lane.status}${lane.completionReason ? `/${lane.completionReason}` : ""}`).join(", ")}. This is a new linked run; the source run verdict is unchanged.`
+        });
+    }
+    specs.forEach((spec, index) => {
+        const outcome = outcomes?.[index];
+        const laneAppUrl = spec.targetUrl ?? args.appUrl;
+        const publicLaneAppUrl = publicSafeAppUrlLabel(laneAppUrl);
+        const subject = args.laneSubjects[index];
+        const session = outcome?.session;
+        const screenshots = outcome?.screenshots ?? [];
+        const lastScreenshot = screenshots[screenshots.length - 1];
+        const status = args.inProgress === true && outcome === undefined
+            ? "running"
+            : outcome?.skippedReason !== undefined
+                ? "blocked"
+                : session
+                    ? session.status
+                    : outcome?.sessionError
+                        ? "failed"
+                        : "contract_proof_only";
+        const reason = args.inProgress === true && outcome === undefined
+            ? "Live computer-use lane is running; stream auth URL is available only through the attached Observer server."
+            : outcome?.skippedReason
+                ?? session?.reason
+                ?? outcome?.sessionError
+                ?? "Contract bundle only: dry-run produced the evidence shape without launching a desktop or spending provider tokens.";
+        const traceScreenshotMode = session?.trace.redaction.screenshots;
+        const screenshotMode = traceScreenshotMode === "raw" || traceScreenshotMode === "blurred"
+            ? traceScreenshotMode
+            : config.policies?.redactScreenshots === true ? "blurred" : "raw";
+        simulations.push({
+            id: spec.simId,
+            index: index + 1,
+            personaId: spec.persona.id,
+            scenarioId: `cua-${config.id}`,
+            status,
+            streamKind: "browser",
+            mode: "browser-sim",
+            progress: args.inProgress === true && outcome === undefined ? 20 : 100,
+            currentStep: reason,
+            summary: session
+                ? `Lane ${spec.laneId} (${spec.persona.id}/${spec.deviceName}): computer-use actor (${args.descriptor.id}) drove the subject app; ${session.completionReason}.`
+                : args.inProgress === true && outcome === undefined
+                    ? `Lane ${spec.laneId} (${spec.persona.id}/${spec.deviceName}): computer-use actor (${args.descriptor.id}) is driving the subject app.`
+                    : outcome?.skippedReason !== undefined
+                        ? `Lane ${spec.laneId} ${outcome.skippedReason}.`
+                        : outcome?.sessionError
+                            ? `Lane ${spec.laneId} failed before a terminal session verdict: ${outcome.sessionError}`
+                            : `Contract lane ${spec.laneId} (${spec.persona.id}/${spec.deviceName}) for ${args.descriptor.id} against ${publicLaneAppUrl}.`,
+            streamIds: [spec.streamId],
+            startedAt: args.createdAt,
+            updatedAt: args.createdAt
+        });
+        streams.push({
+            id: spec.streamId,
+            simId: spec.simId,
+            laneId: spec.laneId,
+            ...(spec.actorType === undefined ? {} : { actorType: spec.actorType }),
+            ...(spec.surface === undefined ? {} : { surface: spec.surface }),
+            ...(spec.caseGroup === undefined ? {} : { caseGroup: spec.caseGroup }),
+            kind: "browser",
+            label: `CUA lane ${spec.laneId} — ${config.id}`,
+            status,
+            transport: "snapshot",
+            updatedAt: args.createdAt,
+            embed: lastScreenshot
+                ? { kind: "screenshot", url: lastScreenshot, title: `CUA desktop ${spec.laneId} (${screenshotMode})` }
+                : { kind: "placeholder", title: `CUA desktop ${spec.laneId}` },
+            viewport: {
+                width: spec.resolution[0],
+                height: spec.resolution[1],
+                deviceScaleFactor: spec.devicePreset.deviceScaleFactor,
+                isMobile: spec.devicePreset.isMobile
+            },
+            ui: {
+                route: publicLaneAppUrl,
+                intent: `Watch lane ${spec.laneId} (${spec.persona.id}/${spec.deviceName}) drive the subject app in its own hosted desktop.`,
+                state: reason,
+                ...(session ? { actorStatus: session.status } : {}),
+                ...(lastScreenshot ? { screenshotUrl: lastScreenshot } : {})
+            },
+            ...(session ? { actor: session.trace } : {}),
+            artifacts: [
+                { label: "run bundle", path: "run.json", kind: "bundle" },
+                { label: "review", path: "review.md", kind: "review" },
+                { label: "events", path: "events.ndjson", kind: "events" },
+                ...(session
+                    ? [{ label: `lane ${spec.laneId} actor trace`, path: spec.traceArtifactPath, kind: "trace" }]
+                    : []),
+                ...screenshots.map((screenshot, screenshotIndex) => ({
+                    label: `lane ${spec.laneId} screenshot ${String(screenshotIndex + 1).padStart(2, "0")} (${screenshotMode})`,
+                    path: screenshot,
+                    kind: "screenshot"
+                }))
+            ]
+        });
+        // Per-lane subject provenance (invariant 5).
+        if (args.cloneRoute && args.publicRepo) {
+            events.push({
+                id: nextEventId(`subject-${spec.laneId}`),
+                at: args.createdAt,
+                level: "info",
+                type: "cua-lab.subject.provenance",
+                message: `Lane ${spec.laneId}: ${args.dryRun
+                    ? `subject declared — clone of ${args.publicRepo}, served at ${publicLaneAppUrl} in-sandbox (dry-run contract; nothing cloned)`
+                    : subject.commit
+                        ? session
+                            ? `subject cloned from ${args.publicRepo}@${subject.commit} and served at ${publicLaneAppUrl} in-sandbox`
+                            : `subject cloned from ${args.publicRepo}@${subject.commit}; serving did not complete (see session error)`
+                        : `subject clone attempted from ${args.publicRepo}; commit unresolved`} (subject env names: ${args.subjectEnvNames.length > 0 ? args.subjectEnvNames.join(", ") : "none"}; values never persisted); state: ${describeSubjectState(subject.state, args.dryRun)}.`,
+                simId: spec.simId,
+                streamId: spec.streamId
+            });
+        }
+        else if (subject.source === "local-tree") {
+            events.push({
+                id: nextEventId(`subject-${spec.laneId}`),
+                at: args.createdAt,
+                level: "info",
+                type: "cua-lab.subject.provenance",
+                message: `Lane ${spec.laneId}: ${args.dryRun
+                    ? `subject declared: local working tree, to be packed and served at ${publicLaneAppUrl} in-sandbox (dry-run contract; nothing packed)`
+                    : subject.archiveSha256
+                        ? session
+                            ? `subject packed (archiveSha256 ${subject.archiveSha256}${subject.dirty === true ? ", dirty working tree" : subject.dirty === false ? ", clean working tree" : ""}) and served at ${publicLaneAppUrl} in-sandbox`
+                            : `subject packed (archiveSha256 ${subject.archiveSha256}); serving did not complete (see session error)`
+                        : "subject local-tree packing attempted; archive digest unresolved"} (subject env names: ${args.subjectEnvNames.length > 0 ? args.subjectEnvNames.join(", ") : "none"}; values never persisted); state: ${describeSubjectState(subject.state, args.dryRun)}.`,
+                simId: spec.simId,
+                streamId: spec.streamId
+            });
+        }
+        else {
+            events.push({
+                id: nextEventId(`subject-${spec.laneId}`),
+                at: args.createdAt,
+                level: "info",
+                type: "cua-lab.subject.declared",
+                message: `Lane ${spec.laneId}: subject app declared at ${publicLaneAppUrl} (loopback inside the lane's own desktop sandbox).`,
+                simId: spec.simId,
+                streamId: spec.streamId
+            });
+        }
+        // Per-lane session event.
+        if (session) {
+            events.push({
+                id: nextEventId(`session-${spec.laneId}`),
+                at: args.createdAt,
+                level: session.status === "passed" ? "info" : "warn",
+                type: `cua-lab.session.${session.completionReason}`,
+                message: `Lane ${spec.laneId}: ${session.status} — ${session.reason}`,
+                simId: spec.simId,
+                streamId: spec.streamId
+            });
+        }
+        else if (args.inProgress === true && outcome === undefined) {
+            events.push({
+                id: nextEventId(`running-${spec.laneId}`),
+                at: args.createdAt,
+                level: "info",
+                type: "cua-lab.session.running",
+                message: `Lane ${spec.laneId}: live computer-use session is running; terminal evidence has not been written yet.`,
+                simId: spec.simId,
+                streamId: spec.streamId
+            });
+        }
+        else if (outcome?.skippedReason !== undefined) {
+            events.push({
+                id: nextEventId(`blocked-${spec.laneId}`),
+                at: args.createdAt,
+                level: "warn",
+                type: "cua-lab.session.blocked",
+                message: `Lane ${spec.laneId} ${outcome.skippedReason}.`,
+                simId: spec.simId,
+                streamId: spec.streamId
+            });
+        }
+        else if (outcome?.sessionError) {
+            events.push({
+                id: nextEventId(`session-error-${spec.laneId}`),
+                at: args.createdAt,
+                level: "error",
+                type: "cua-lab.session.error",
+                message: `Lane ${spec.laneId}: ${outcome.sessionError}`,
+                simId: spec.simId,
+                streamId: spec.streamId
+            });
+        }
+        else {
+            events.push({
+                id: nextEventId(`contract-${spec.laneId}`),
+                at: args.createdAt,
+                level: "info",
+                type: "cua-lab.contract.ready",
+                message: `Lane ${spec.laneId}: dry-run contract lane ready; switch scenario.mode to live for a real desktop session.`,
+                simId: spec.simId,
+                streamId: spec.streamId
+            });
+        }
+        // Persisted per-lane phase trail (real boot timing): one RunEvent per COMPLETED phase
+        // boundary this lane recorded (started events never persist here; they carry no durationMs).
+        for (const phase of outcome?.phaseRecords ?? []) {
+            events.push({
+                id: nextEventId(`phase-${spec.laneId}-${phaseEventIdSuffix(phase.type)}`),
+                at: phase.at,
+                level: phase.ok === false ? "warn" : "info",
+                type: phase.type,
+                message: phase.durationMs === undefined
+                    ? `Lane ${spec.laneId}: ${phase.message}`
+                    : `Lane ${spec.laneId}: ${phase.message} (${phase.durationMs}ms)`,
+                simId: spec.simId,
+                streamId: spec.streamId
+            });
+        }
+    });
+    if (args.failFastReason) {
+        events.push({
+            id: nextEventId("fanout-fail-fast"),
+            at: args.createdAt,
+            level: "warn",
+            type: "cua-lab.fanout.fail-fast",
+            message: `Fan-out fail-fast: ${args.failFastReason}. In-flight lanes finished; queued lanes were skipped (blocked) — completed evidence is retained.`
+        });
+    }
+    // Worst-of review verdict across lanes; live fan-out must prove every lane.
+    const verdict = args.inProgress === true
+        ? "contract_proof_only"
+        : fanoutReviewVerdict({
+            dryRun: args.dryRun,
+            expectedLaneCount: specs.length,
+            outcomes
+        });
+    const passedLanes = (outcomes ?? []).filter((outcome) => outcome.skippedReason === undefined
+        && outcome.session !== undefined
+        && outcome.session.status === "passed"
+        && outcome.session.completionReason !== "harness_error"
+        && outcome.sessionError === undefined
+        && !outcome.noEngagement
+        && !outcome.selfReportedBlocker).length;
+    const review = {
+        schema: REVIEW_SCHEMA,
+        verdict,
+        summary: args.inProgress === true
+            ? `Live computer-use fan-out is running (${specs.length} per-lane worlds); terminal lane evidence has not been written yet.`
+            : args.dryRun
+                ? `${args.rerun ? `Rerun contract from ${args.rerun.sourceRunId}: ` : ""}Dry-run fan-out contract: ${specs.length} per-lane-world lanes composed for ${args.descriptor.id} against ${args.appUrl}; no desktops launched, $0 spend.`
+                : `${args.rerun ? `Rerun from ${args.rerun.sourceRunId}: ` : ""}Computer-use fan-out (${specs.length} per-lane worlds): ${passedLanes}/${specs.length} lane(s) reached a terminal, engaged verdict.`,
+        gaps: args.inProgress === true
+            ? ["Live fan-out session is still running."]
+            : args.dryRun
+                ? ["Live fan-out session not yet run (dry-run contract only)."]
+                : specs
+                    .map((spec, index) => ({ spec, outcome: outcomes?.[index] }))
+                    .filter(({ outcome }) => outcome === undefined
+                    || outcome.skippedReason !== undefined
+                    || outcome.sessionError !== undefined
+                    || outcome.noEngagement
+                    || outcome.selfReportedBlocker
+                    || outcome.session === undefined
+                    || outcome.session.status !== "passed")
+                    .map(({ spec, outcome }) => `${spec.laneId}: ${outcome?.skippedReason ?? outcome?.sessionError ?? outcome?.session?.reason ?? "did not pass"}`)
+    };
+    const anyRaw = (outcomes ?? []).some((outcome) => outcome.session?.trace.redaction.screenshots === "raw");
+    const ranLive = (outcomes ?? []).some((outcome) => outcome.session !== undefined || outcome.sessionError !== undefined);
+    const configuredBrowser = config.execution?.desktop?.browser;
+    const resolvedBrowsers = (outcomes ?? [])
+        .map((outcome) => outcome.desktopBrowser?.resolved)
+        .filter((value) => value !== undefined);
+    const unanimousResolvedBrowser = resolvedBrowsers.length > 0 && new Set(resolvedBrowsers).size === 1
+        ? resolvedBrowsers[0]
+        : undefined;
+    const providerResources = (outcomes ?? []).flatMap((outcome) => providerResourcesForOutcome({
+        outcome,
+        createdAt: args.createdAt,
+        simId: outcome.spec.simId,
+        streamId: outcome.spec.streamId,
+        laneId: outcome.spec.laneId
+    }));
+    return {
+        schema: RUN_BUNDLE_SCHEMA,
+        runId: args.runId,
+        mode: args.dryRun ? "dry-run" : "live",
+        simCount: specs.length,
+        createdAt: args.createdAt,
+        cwd: PUBLIC_TARGET_CWD,
+        artifactRoot: path.join(".humanish", "runs", args.runId),
+        source: args.source,
+        persona: {
+            id: specs[0].persona.id,
+            name: `Computer-use fan-out (${specs.length} lanes)`,
+            source: `lab:${config.id}`,
+            sourceDigest: specs[0].persona.promptDigest
+        },
+        scenario: {
+            id: `cua-${config.id}`,
+            title: config.title ?? `Computer-use fan-out: ${config.id}`,
+            goal: specs[0].instructions,
+            source: `lab:${config.id}`,
+            sourceDigest: specs[0].persona.promptDigest
+        },
+        lifecycle: [
+            {
+                at: args.createdAt,
+                event: "cua-lab.run.created",
+                message: `Created computer-use fan-out run with ${specs.length} per-lane desktop browser lanes (actor ${args.descriptor.id}).`
+            }
+        ],
+        simulations,
+        streams,
+        events,
+        ...(args.rerun === undefined ? {} : { rerun: args.rerun }),
+        redaction: {
+            status: "passed",
+            notes: ranLive
+                ? anyRaw
+                    ? "Typed text recorded as length only and reasoning/messages pass through text redaction. Some lanes captured FULL-FIDELITY (raw) screenshots, retained for local use — NOT redacted for publishing; set policies.redactScreenshots: true to blur a share-as-is bundle."
+                    : "Typed text recorded as length only and reasoning/messages pass through text redaction. Screenshots are blurred at capture (policies.redactScreenshots: true) for a share-as-is bundle."
+                : "Dry-run fan-out contract bundle: no desktops launched and no screenshots captured. Typed text is recorded as length only and reasoning/messages pass through text redaction whenever a session runs."
+        },
+        artifacts: {
+            run: "run.json",
+            reviewJson: "review.json",
+            reviewMarkdown: "review.md",
+            observerData: "observer/observer-data.json",
+            events: "events.ndjson"
+        },
+        review,
+        feedbackCandidates: [],
+        // Custom desktop image provenance (every lane launched on it); omitted on the stock default.
+        ...(config.execution?.desktop?.template === undefined ? {} : { desktopTemplate: config.execution.desktop.template }),
+        ...(configuredBrowser === undefined
+            ? {}
+            : { desktopBrowser: { requested: configuredBrowser, ...(unanimousResolvedBrowser === undefined ? {} : { resolved: unanimousResolvedBrowser }) } }),
+        ...(providerResources.length === 0 ? {} : { providerResources }),
+        subject: args.aggregateSubject
+    };
+}
+function providerResourcesForOutcome(args) {
+    if (args.outcome?.sandboxId === undefined) {
+        return [];
+    }
+    return [{
+            schema: "humanish.provider-resource.v1",
+            provider: "e2b-desktop",
+            kind: "sandbox",
+            id: args.outcome.sandboxId,
+            owner: "humanish",
+            status: args.outcome.killed ? "killed" : "running",
+            simId: args.simId,
+            streamId: args.streamId,
+            laneId: args.laneId,
+            createdAt: args.createdAt,
+            cleanup: {
+                killed: args.outcome.killed,
+                reason: args.outcome.killed
+                    ? "killed during normal lane teardown"
+                    : "not killed during normal lane teardown; cleanup may reclaim by exact recorded id"
+            }
+        }];
+}
+function verdictForStatus(status) {
+    switch (status) {
+        case "passed":
+            return "pass";
+        case "failed":
+            return "fail";
+        case "blocked":
+            return "blocked";
+        case "timed_out":
+            return "timed_out";
+    }
+}
+function renderCuaReviewMarkdown(bundle) {
+    const trace = bundle.streams[0]?.actor;
+    const provenance = bundle.events.find((event) => event.type === "cua-lab.subject.provenance");
+    return [
+        `# ${bundle.scenario.title}`,
+        "",
+        `- run: ${bundle.runId}`,
+        `- mode: ${bundle.mode}`,
+        `- verdict: ${bundle.review.verdict}`,
+        `- summary: ${bundle.review.summary}`,
+        ...(provenance ? [`- subject: ${provenance.message}`] : []),
+        ...(trace
+            ? [
+                `- actor: ${trace.provider} (${trace.lane}/${trace.protocol})`,
+                // Honest count: name the trace's actual screenshot mode ("raw" | "blurred"); say
+                // nothing when no frames exist ("n/a") rather than claim a redaction that never ran.
+                `- evidence: ${trace.items.length} trace item(s), ${trace.counts.screenshots ?? 0} ${trace.redaction.screenshots === "raw" || trace.redaction.screenshots === "blurred"
+                    ? `${trace.redaction.screenshots} screenshot(s)`
+                    : "screenshot(s)"}`
+            ]
+            : []),
+        ...(bundle.review.gaps.length > 0 ? ["", "## Gaps", ...bundle.review.gaps.map((gap) => `- ${gap}`)] : []),
+        ""
+    ].join("\n");
+}
+function makeCuaRunId() {
+    const stamp = new Date().toISOString().replace(/[:.]/g, "-");
+    return `cua-${stamp}-${randomBytes(4).toString("hex")}`;
+}
+function publicSafeAppUrlLabel(url) {
+    return containsSensitive(url) ? `[target-url:${digestUrl(url)}]` : url;
+}
+function digestUrl(url) {
+    return digestText(url, 16);
+}
+function readPositiveInt(value, fallback) {
+    if (value === undefined)
+        return fallback;
+    const parsed = Number.parseInt(value, 10);
+    return Number.isSafeInteger(parsed) && parsed > 0 ? parsed : fallback;
+}
+//# sourceMappingURL=cua-actor-lab.js.map