humanish 0.104.3 → 0.106.0

package/dist/scripted-browser-lab.js

@@ -1,852 +0,0 @@
-// The scripted-browser lab backend: either an app-url subject (a loopback app the operator
-// already runs) or one provisioned synthetic clone subject (served in E2B and exposed through
-// getHost) driven by the REGISTRY-RESOLVED scripted-browser actor.
-// Mirrors cua-actor-lab.ts: the descriptor returned by the registry runs the session; this
-// backend consumes `scenario.ref` (resolves the committed scenario whose browser steps ARE the
-// actor's behavior — no built-in fallback on the lab route, unlike `run --app-url`), composes
-// the per-surface sessions, persists the evidence bundle, and renders the Observer.
-//
-// Spend posture: scripted participant steps make no model requests, and their traces record
-// tokenUsage zeros. Post-run analysis has a separate model budget unless explicitly disabled. Local
-// app-url runs also spend no sandbox minutes; live provisioned clone runs can spend E2B
-// sandbox minutes to clone/serve the synthetic subject. `scenario.mode: live` is still
-// required because the gate's justification here is ACTUATION: a live scripted run drives a
-// real browser against a real running app (fills forms, clicks buttons — state-mutating
-// effects), which deserves the same affirmative declaration as spend. Dry-run (the default)
-// parses and digest-pins the scenario and emits the contract bundle without touching anything.
-//
-// Subject provenance (invariant 5): local app-url runs declare that the lab did NOT provision
-// the subject, so build/commit provenance is UNPINNED and the evidence binds to the scenario
-// digest instead. Provisioned clone runs persist structured commit/env-name/state provenance
-// plus a host digest while never writing the raw getHost URL or secret values into artifacts.
-import { resolveAutomaticAnalysis } from "./automatic-analysis-config.js";
-import { completeAutomaticAnalysis, markFinalizedStudyResult } from "./automatic-analysis-completion.js";
-import { desktopMediaValidationReason, taskProtocolValidationReason } from "./lab-config.js";
-import { randomBytes } from "node:crypto";
-import { describeMissingKeys } from "./key-resolution.js";
-import { beginRunStatus, withRunStatusScope } from "./run-status.js";
-import { realpath } from "node:fs/promises";
-import path from "node:path";
-import { parse as parseYaml } from "yaml";
-import { actorRegistry, isScriptedBrowserActorDescriptor } from "./actor-registry.js";
-import { toErrorMessage } from "./command-failure.js";
-import { commandDigestOf, provisionCloneSubject, resolveSubjectState } from "./cua-actor-lab.js";
-import { createDesktopSandbox, loadE2BDesktopModule } from "./e2b-desktop-launch.js";
-import { renderObserver } from "./observer.js";
-import { digestText, redactText } from "./redaction.js";
-import { prepareRunArtifactPaths, validatePreparedRunArtifactPaths } from "./run-paths.js";
-import { buildRunSource, PUBLIC_TARGET_CWD, REVIEW_SCHEMA, RUN_BUNDLE_SCHEMA } from "./run.js";
-import { browserSurfaces, normalizeLocalAppUrl, parseBrowserPersonaJourneyFromScenario, resolveBrowserCommand, runScriptedBrowserSessionInPreparedRoot } from "./scripted-browser-actor.js";
-import { prepareSelectedOutputDirectory, readContainedRegularFile, writeContainedOutputFile, writePreparedRunLatestPointer } from "./selected-output-paths.js";
-export const SCRIPTED_BROWSER_LAB_SCHEMA = "humanish.scripted-lab-result.v1";
-// Journey wall-clock budget per surface — same default as `run --app-url`.
-// 5 minutes (was 60s): a scripted surface has zero model cost and sandbox-seconds are pennies;
-// a short default only truncated slow-loading subjects.
-const DEFAULT_SESSION_TIMEOUT_MS = 300_000;
-const SANDBOX_TIMEOUT_BUFFER_MS = 10 * 60_000;
-const SUBJECT_PROVISION_BUDGET_MS = 30 * 60_000;
-const DEFAULT_STATE_STEP_TIMEOUT_MS = 5 * 60_000;
-// Default surface roster is 1 (desktop only): the defaults-table single-lane row governs;
-// `count: 2` is the declared override that adds the mobile surface.
-const DEFAULT_SURFACE_COUNT = 1;
-// Same public-safe token shape the lab id uses; an id-style scenario.ref must match it before
-// it is interpolated into a repo path.
-const SCENARIO_REF_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9_.-]*$/;
-class UnsafeScriptedSessionResultError extends Error {
-    constructor(message) {
-        super(message);
-        this.name = "UnsafeScriptedSessionResultError";
-    }
-}
-/**
- * Wrapped so a DIRECT library caller gets the same status-record lifetime the CLI does: returning
- * from this function finalizes any record the run opened, whichever of its fail-closed exits it
- * took. `runLab` establishes a scope too and nesting is harmless — the inner scope owns what it
- * opened. Without this a test or an adopter calling the backend directly leaves the 5s cadence
- * ticking into a directory something else is deleting, which surfaces as an unrelated ENOTEMPTY.
- */
-export async function runScriptedBrowserLab(options) {
-    if (String(options.config.comms?.email?.kind) === "real")
-        return {
-            schema: SCRIPTED_BROWSER_LAB_SCHEMA, ok: false, cwd: path.resolve(options.cwd), labId: options.config.id,
-            actor: options.config.actors[0]?.type ?? "", dryRun: options.dryRun,
-            runId: options.runId ?? "not-created", appUrl: options.config.subject.appUrl ?? "", sessions: [], warnings: [],
-            error: { code: "HUMANISH_SCRIPTED_LAB_SCENARIO_INVALID", message: "Real email receiving is unsupported on the scripted-browser backend. Use a supported hosted computer-use browser study." }
-        };
-    const analysisReason = resolveAutomaticAnalysis(options.config.review?.analysis);
-    const tasksReason = analysisReason.ok ? taskProtocolValidationReason(options.config, false) : analysisReason.message;
-    if (tasksReason)
-        return {
-            schema: SCRIPTED_BROWSER_LAB_SCHEMA, ok: false, cwd: path.resolve(options.cwd), labId: options.config.id,
-            actor: options.config.actors[0]?.type ?? "", dryRun: options.dryRun,
-            runId: options.runId ?? "not-created", appUrl: options.config.subject.appUrl ?? "", sessions: [], warnings: [],
-            error: { code: analysisReason.ok ? "HUMANISH_LAB_TASKS_UNSUPPORTED" : "HUMANISH_LAB_ANALYSIS_INVALID", message: tasksReason }
-        };
-    const analysis = resolveAutomaticAnalysis(options.config.review?.analysis);
-    const result = await withRunStatusScope(() => runScriptedBrowserLabInScope(options));
-    return completeAutomaticAnalysis(result, analysis.ok ? analysis.config : undefined, options.automaticAnalysis, options.config.review?.analysis === undefined ? "default" : "explicit", analysis.ok && analysis.preferLargerOutput === true);
-}
-async function runScriptedBrowserLabInScope(options) {
-    const { config, dryRun } = options;
-    const cwd = path.resolve(options.cwd);
-    const physicalCwd = await realpath(cwd);
-    const projectRoot = await prepareSelectedOutputDirectory(path.dirname(physicalCwd), physicalCwd);
-    const hooks = options.hooks ?? {};
-    const render = hooks.renderObserverFn ?? renderObserver;
-    const warnings = [];
-    const actorType = config.actors[0]?.type ?? "";
-    const failed = (code, message, extras) => ({
-        schema: SCRIPTED_BROWSER_LAB_SCHEMA,
-        ok: false,
-        cwd,
-        labId: config.id,
-        actor: extras?.actor ?? actorType,
-        appUrl: extras?.appUrl ?? config.subject.appUrl ?? "",
-        dryRun,
-        runId: options.runId ?? "not-created",
-        sessions: [],
-        warnings,
-        error: { code, message }
-    });
-    // Resolve the actor through the registry — the parse layer already validated this, but the
-    // engine fails closed rather than trusting a config that arrived through another door
-    // (runScriptedBrowserLab is itself exported npm surface).
-    const mediaReason = desktopMediaValidationReason(config);
-    if (mediaReason)
-        return failed("HUMANISH_SCRIPTED_LAB_SCENARIO_INVALID", mediaReason);
-    const descriptor = actorRegistry[actorType];
-    if (!descriptor || !isScriptedBrowserActorDescriptor(descriptor)) {
-        return failed("HUMANISH_SCRIPTED_LAB_ACTOR_UNSUPPORTED", `actors[0].type "${actorType}" is not a registered scripted-browser actor.`);
-    }
-    const runSession = hooks.runSession;
-    const provisionedRoute = config.subject.source === "clone";
-    const evidenceAppUrl = provisionedRoute ? "[provisioned-subject]" : normalizeLocalAppUrl(config.subject.appUrl ?? "") ?? "";
-    const urlPolicy = provisionedRoute
-        ? { kind: "provisioned-subject", evidenceOrigin: evidenceAppUrl }
-        : { kind: "loopback" };
-    const serve = config.subject.serve;
-    const subjectRepo = provisionedRoute ? config.subject.repos?.[0] ?? "" : undefined;
-    const subjectEnvNames = provisionedRoute ? config.subject.env ?? [] : [];
-    const env = hooks.env ?? process.env;
-    const e2bApiKey = env.E2B_API_KEY?.trim() ?? "";
-    const hasGithubToken = subjectEnvNames.includes("GITHUB_TOKEN");
-    const redactRepoLabel = config.policies?.redactRepos ?? hasGithubToken;
-    const publicRepo = provisionedRoute && subjectRepo ? (redactRepoLabel ? "repo-01" : subjectRepo) : undefined;
-    const scrubSourceValues = [
-        ...(subjectRepo ? [subjectRepo] : []),
-        ...subjectEnvNames.map((name) => env[name] ?? "")
-    ].filter(Boolean);
-    const scrubKnownValues = (text) => scrubSourceValues.reduce((acc, value) => acc.split(value).join("[redacted]"), text);
-    // Re-enforce the local loopback entry boundary at the engine. The provisioned clone route
-    // mints its own getHost URL later and persists only evidenceAppUrl.
-    let appUrl = provisionedRoute ? serve?.url ?? "" : evidenceAppUrl;
-    if (!provisionedRoute && !appUrl) {
-        return failed("HUMANISH_SCRIPTED_LAB_SUBJECT_UNSAFE", "subject.appUrl must be a loopback http(s) URL (127.0.0.1 or localhost) on the scripted-browser route.", { actor: descriptor.id });
-    }
-    if (provisionedRoute && (!serve || !subjectRepo || !publicRepo)) {
-        return failed("HUMANISH_SCRIPTED_LAB_SUBJECT_UNSAFE", "clone scripted-browser labs require one subject repo plus subject.serve; parseLabConfig should have rejected this config.", { actor: descriptor.id, appUrl: evidenceAppUrl });
-    }
-    // Consume scenario.ref (fail-closed: invariant 6 — the steps ARE the actor; there is no
-    // built-in journey fallback on the lab route).
-    const scenario = await resolveScriptedScenario(projectRoot, config.scenario?.ref);
-    if (!scenario.ok) {
-        return failed("HUMANISH_SCRIPTED_LAB_SCENARIO_INVALID", scenario.message, { actor: descriptor.id, appUrl: evidenceAppUrl });
-    }
-    const journey = scenario.journey;
-    if (!dryRun && provisionedRoute) {
-        if (!e2bApiKey) {
-            return failed("HUMANISH_SCRIPTED_LAB_KEYS_MISSING", `Live clone scripted-browser labs require E2B_API_KEY (dry-run remains $0 and does not provision a subject). ${describeMissingKeys(["E2B_API_KEY"], env)}`, { actor: descriptor.id, appUrl: evidenceAppUrl });
-        }
-        const missingSubjectEnv = subjectEnvNames.filter((name) => !env[name]?.trim());
-        if (missingSubjectEnv.length > 0) {
-            return failed("HUMANISH_SCRIPTED_LAB_SUBJECT_ENV_MISSING", `Subject env values missing for live clone scripted-browser lab: ${missingSubjectEnv.join(", ")}.`, { actor: descriptor.id, appUrl: evidenceAppUrl });
-        }
-    }
-    const surfaces = browserSurfaces.slice(0, config.actors[0]?.count ?? DEFAULT_SURFACE_COUNT);
-    const timeoutMs = config.execution?.timeoutMs ?? DEFAULT_SESSION_TIMEOUT_MS;
-    const persona = {
-        id: config.actors[0]?.persona ?? "scripted-journey",
-        traitsApplied: [],
-        // The step manifest IS the "prompt" on this lane; the digest binds the trace to the
-        // committed scenario text.
-        promptDigest: journey.sourceDigest.slice(0, 16)
-    };
-    // Live runs need a browser BEFORE any actuation (unless one is injected).
-    let browserCommand = hooks.browserCommand;
-    if (!dryRun && !hooks.launchBrowser && !browserCommand) {
-        const resolved = await resolveBrowserCommand();
-        if (!resolved) {
-            return failed("HUMANISH_SCRIPTED_LAB_BROWSER_MISSING", "No Chrome/Chromium browser command was found for the scripted-browser actor. Set HUMANISH_BROWSER_COMMAND to a browser binary playwright-core can launch.", { actor: descriptor.id, appUrl: evidenceAppUrl });
-        }
-        browserCommand = resolved;
-    }
-    const runId = options.runId ?? makeScriptedRunId();
-    const runPaths = await prepareRunArtifactPaths(physicalCwd, runId);
-    // Identity + liveness on disk (#455): every backend writes this, so a watcher can classify any
-    // run without parsing bundles and without depending on the interactive-observer path.
-    const runStatus = beginRunStatus(runPaths, {
-        runId,
-        mode: dryRun ? "dry-run" : "live",
-        ...(options.lab === undefined ? {} : { lab: options.lab })
-    });
-    const artifactRoot = runPaths.physicalRunRoot;
-    const createdAt = new Date().toISOString();
-    const source = await buildRunSource({
-        capturedAt: createdAt,
-        cwd: physicalCwd,
-        humanishSource: "present",
-        packageName: "humanish"
-    });
-    let sessionResults = [];
-    let sessionError;
-    const stateStepRecords = [];
-    let subjectCommit;
-    let subjectSandboxId;
-    let subjectKilled = false;
-    let hostDigest;
-    if (!dryRun) {
-        let subjectModule;
-        let subjectDesktop;
-        try {
-            if (provisionedRoute) {
-                const requestTimeoutMs = readPositiveInt(env.HUMANISH_E2B_REQUEST_TIMEOUT_MS, 60_000);
-                const timers = hooks.detachedTimers ?? {};
-                subjectModule = await (hooks.loadDesktopModule ?? loadE2BDesktopModule)();
-                await validatePreparedRunArtifactPaths(runPaths);
-                subjectDesktop = await createDesktopSandbox(subjectModule, {
-                    apiKey: e2bApiKey,
-                    requestTimeoutMs,
-                    timeoutMs: timeoutMs + SUBJECT_PROVISION_BUDGET_MS
-                        + (config.subject.state?.seed ?? []).reduce((sum, step) => sum + (step.timeoutMs ?? DEFAULT_STATE_STEP_TIMEOUT_MS), 0)
-                        + SANDBOX_TIMEOUT_BUFFER_MS,
-                    metadata: {
-                        mode: "scripted-browser-lab",
-                        tool: "humanish",
-                        labId: config.id,
-                        role: "subject",
-                        actor: descriptor.id
-                    },
-                    ...(subjectEnvNames.length > 0
-                        ? { envs: Object.fromEntries(subjectEnvNames.map((name) => [name, env[name]])) }
-                        : {}),
-                    dpi: 96,
-                    lifecycle: { onTimeout: "kill" }
-                }, config.execution?.desktop?.template);
-                subjectSandboxId = subjectDesktop.sandboxId;
-                if (hooks.prepareDesktop) {
-                    await hooks.prepareDesktop(subjectDesktop);
-                    await validatePreparedRunArtifactPaths(runPaths);
-                }
-                subjectCommit = await provisionCloneSubject(subjectDesktop, {
-                    repo: subjectRepo,
-                    depth: config.subject.clone?.depth ?? 1,
-                    serve: serve,
-                    ...(config.subject.state === undefined ? {} : { state: config.subject.state }),
-                    hasGithubToken,
-                    requestTimeoutMs,
-                    scrub: scrubKnownValues,
-                    onCommit: (commit) => {
-                        subjectCommit = commit;
-                    },
-                    onStateStep: (record) => {
-                        stateStepRecords.push(record);
-                    },
-                    ...timers
-                });
-                if (typeof subjectDesktop.getHost !== "function") {
-                    throw new Error("the installed @e2b/desktop SDK does not expose getHost(port); clone scripted-browser labs require it to reach the provisioned subject");
-                }
-                const rawHost = subjectDesktop.getHost(servePort(serve.url));
-                const hostUrl = /^https?:\/\//i.test(rawHost) ? rawHost : `https://${rawHost}`;
-                if (!isTokenlessHost(hostUrl)) {
-                    throw new Error("getHost returned a non-tokenless URL; refusing to persist or drive a host URL that may carry a credential");
-                }
-                appUrl = hostUrl;
-                hostDigest = hostOriginDigest(hostUrl);
-            }
-            // One session per surface, in parallel — parity with `run --app-url`.
-            sessionResults = await Promise.all(surfaces.map((surface) => {
-                const sessionOptions = {
-                    appUrl,
-                    evidenceAppUrl,
-                    urlPolicy,
-                    journey,
-                    surface,
-                    persona,
-                    timeoutMs,
-                    artifactRoot,
-                    ...(browserCommand === undefined ? {} : { browserCommand }),
-                    ...(hooks.launchBrowser === undefined ? {} : { launchBrowser: hooks.launchBrowser }),
-                    ...(hooks.now === undefined ? {} : { now: hooks.now })
-                };
-                return runSession
-                    ? runSession(sessionOptions).then(async (result) => {
-                        await validatePreparedRunArtifactPaths(runPaths);
-                        validateScriptedSessionResult(surface, result);
-                        return result;
-                    })
-                    : runScriptedBrowserSessionInPreparedRoot(sessionOptions, runPaths);
-            }));
-        }
-        catch (error) {
-            if (error instanceof UnsafeScriptedSessionResultError) {
-                throw error;
-            }
-            // The session itself maps launch failures to harness_error; reaching here means the
-            // harness around it failed. Redacted at this boundary before persisting anywhere.
-            sessionError = redactText(scrubKnownValues(toErrorMessage(error)));
-        }
-        finally {
-            if (subjectDesktop && subjectModule) {
-                if (typeof subjectModule.Sandbox.kill === "function") {
-                    try {
-                        await subjectModule.Sandbox.kill(subjectDesktop.sandboxId, { requestTimeoutMs: 60_000 });
-                        subjectKilled = true;
-                    }
-                    catch (error) {
-                        warnings.push(`Subject sandbox teardown failed (server-side kill-on-timeout will reclaim it): ${redactText(scrubKnownValues(toErrorMessage(error)))}`);
-                    }
-                }
-                else {
-                    warnings.push("Installed @e2b/desktop SDK does not expose Sandbox.kill; server-side kill-on-timeout will reclaim the subject sandbox.");
-                }
-            }
-        }
-        for (const result of sessionResults) {
-            // The backend writes the provider-neutral projection next to the session's native
-            // traces/<surface>.json (cua's actor.json convention, pluralized per surface).
-            await writeContainedOutputFile(runPaths, `actor-${result.capture.surface.id}.json`, `${JSON.stringify(result.trace, null, 2)}\n`, "utf8");
-        }
-    }
-    const screenshotsBySurface = new Map();
-    for (const result of sessionResults) {
-        screenshotsBySurface.set(result.capture.surface.id, await existingScreenshots(runPaths, result));
-    }
-    const subject = provisionedRoute
-        ? {
-            source: "clone",
-            repo: publicRepo,
-            ...(subjectCommit === undefined ? {} : { commit: subjectCommit }),
-            envNames: subjectEnvNames,
-            state: resolveSubjectState({ declared: config.subject.state, dryRun, executed: stateStepRecords })
-        }
-        : undefined;
-    const bundle = buildScriptedLabBundle({
-        ...(options.lab === undefined ? {} : { lab: options.lab }),
-        actorId: descriptor.id,
-        appUrl: evidenceAppUrl,
-        createdAt,
-        dryRun,
-        journey,
-        labId: config.id,
-        ...(config.title ? { labTitle: config.title } : {}),
-        persona,
-        runId,
-        scenarioSource: scenario.source,
-        scenarioSourceDigest: scenario.sourceDigest,
-        screenshotsBySurface,
-        sessionResults,
-        ...(sessionError === undefined ? {} : { sessionError }),
-        source,
-        surfaces,
-        ...(subject === undefined ? {} : { subject }),
-        ...(config.execution?.desktop?.template === undefined ? {} : { desktopTemplate: config.execution.desktop.template }),
-        ...(hostDigest === undefined ? {} : { hostDigest })
-    });
-    await writeContainedOutputFile(runPaths, "run.json", `${JSON.stringify(bundle, null, 2)}\n`, "utf8");
-    // Finalize identity+liveness from the bundle just written; a throw before this leaves the record
-    // stale, which reads as interrupted rather than as a false outcome (#455).
-    await runStatus.finish({
-        ...(bundle.review?.verdict === undefined ? {} : { verdict: bundle.review.verdict }),
-        ...(bundle.review?.participants === undefined
-            ? {}
-            : {
-                participants: {
-                    total: bundle.review.participants.total,
-                    reachedGoal: bundle.review.participants.reachedGoal,
-                    ...(bundle.review.participants.reportedFriction === undefined
-                        ? {}
-                        : { reportedFriction: bundle.review.participants.reportedFriction })
-                }
-            }),
-        ...(bundle.cost?.estimatedTotalUsd === undefined ? {} : { estimatedCostUsd: bundle.cost.estimatedTotalUsd })
-    });
-    await writeContainedOutputFile(runPaths, "review.json", `${JSON.stringify(bundle.review, null, 2)}\n`, "utf8");
-    await writeContainedOutputFile(runPaths, "review.md", renderScriptedReviewMarkdown(bundle), "utf8");
-    await writeContainedOutputFile(runPaths, "events.ndjson", `${bundle.events.map((event) => JSON.stringify(event)).join("\n")}\n`, "utf8");
-    // Keep `verify --run latest` honest: point it at THIS run (mirrors run.ts's RunPointer).
-    await writePreparedRunLatestPointer(runPaths, `${JSON.stringify({
-        schema: "humanish.latest-run.v1",
-        runId,
-        path: runPaths.relativeRunRoot,
-        updatedAt: createdAt
-    }, null, 2)}\n`, "utf8");
-    // Surface the local-fidelity posture so the operator knows the bundle is not publish-safe as-is.
-    if (sessionResults.some((result) => result.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. policies.redactScreenshots is not yet supported on the scripted route.");
-    }
-    const observer = await render(physicalCwd, runId, { open: options.open === true });
-    await validatePreparedRunArtifactPaths(runPaths);
-    const harnessError = sessionResults.some((result) => result.completionReason === "harness_error");
-    const ok = observer.ok
-        && sessionError === undefined
-        && (dryRun || (sessionResults.length === surfaces.length && !harnessError));
-    return markFinalizedStudyResult({
-        schema: SCRIPTED_BROWSER_LAB_SCHEMA,
-        ok,
-        cwd,
-        labId: config.id,
-        actor: descriptor.id,
-        appUrl: evidenceAppUrl,
-        dryRun,
-        runId,
-        ...(subject === undefined ? {} : { subject }),
-        ...(subjectSandboxId === undefined ? {} : { subjectSandbox: { sandboxId: subjectSandboxId, killed: subjectKilled } }),
-        ...(hostDigest === undefined ? {} : { hostDigest }),
-        scenario: {
-            id: journey.scenarioId,
-            source: scenario.source,
-            sourceDigest: scenario.sourceDigest,
-            steps: journey.steps.length
-        },
-        sessions: sessionResults.map((result) => ({
-            surface: result.capture.surface.id,
-            status: result.status,
-            completionReason: result.completionReason,
-            reason: result.reason,
-            screenshots: screenshotsBySurface.get(result.capture.surface.id)?.length ?? 0
-        })),
-        observer,
-        warnings: [...warnings, ...observer.warnings],
-        ...(ok
-            ? {}
-            : {
-                error: {
-                    code: "HUMANISH_SCRIPTED_LAB_FAILED",
-                    message: sessionError
-                        ?? (observer.ok
-                            ? harnessError
-                                ? `Scripted session ended with a harness error: ${sessionResults.find((result) => result.completionReason === "harness_error")?.reason ?? "unknown"}`
-                                : "Scripted lab did not produce terminal sessions for every surface."
-                            : observer.error?.message ?? "Observer failed for the scripted lab run.")
-                }
-            })
-    }, runPaths);
-}
-/**
- * Resolve and consume `scenario.ref`. Path-style refs (contain a separator or end .yaml/.yml)
- * resolve against cwd and are CLAMPED inside it — a ../../ escape is rejected, never recorded
- * as repo-relative provenance. Id-style refs must be public-safe tokens and resolve to
- * humanish/scenarios/<ref>.yaml (then .yml). Every failure mode is fail-closed.
- */
-async function resolveScriptedScenario(projectRoot, ref) {
-    if (!ref || !ref.trim()) {
-        return {
-            ok: false,
-            message: "scripted-browser labs require `scenario.ref` — the committed scenario's browser steps are what this actor executes."
-        };
-    }
-    const trimmed = ref.trim();
-    let absolutePath;
-    let source;
-    if (scenarioRefLooksLikePath(trimmed)) {
-        absolutePath = path.resolve(projectRoot.physicalPath, trimmed);
-        const relative = path.relative(projectRoot.physicalPath, absolutePath);
-        if (!relative || relative.startsWith("..") || path.isAbsolute(relative)) {
-            return {
-                ok: false,
-                message: `scenario.ref path must stay inside the target cwd (got "${trimmed}") — provenance is recorded repo-relative and an escaping path cannot be.`
-            };
-        }
-        source = relative.split(path.sep).join("/");
-    }
-    else {
-        if (!SCENARIO_REF_ID_PATTERN.test(trimmed)) {
-            return {
-                ok: false,
-                message: `scenario.ref must be a public-safe scenario id or a .yaml path inside the repo (got "${trimmed}").`
-            };
-        }
-        const candidates = [
-            path.posix.join("humanish", "scenarios", `${trimmed}.yaml`),
-            path.posix.join("humanish", "scenarios", `${trimmed}.yml`)
-        ];
-        const found = await firstExistingFile(projectRoot, candidates);
-        if (!found) {
-            return {
-                ok: false,
-                message: `scenario.ref "${trimmed}" was not found (looked for ${candidates.join(", ")}).`
-            };
-        }
-        source = found;
-        absolutePath = path.join(projectRoot.physicalPath, found);
-    }
-    const relativeScenarioPath = path.relative(projectRoot.physicalPath, absolutePath);
-    const scenarioBytes = await readContainedRegularFile(projectRoot, relativeScenarioPath);
-    if (!scenarioBytes) {
-        return { ok: false, message: `scenario.ref "${trimmed}" could not be read (${source}).` };
-    }
-    const text = scenarioBytes.toString("utf8");
-    let raw;
-    try {
-        raw = parseYaml(text);
-    }
-    catch {
-        return { ok: false, message: `${source} could not be parsed as YAML; the scripted scenario failed closed.` };
-    }
-    const sourceDigest = digestText(text);
-    const parsed = parseBrowserPersonaJourneyFromScenario({ raw, relativePath: source, sourceDigest });
-    if (parsed.failure) {
-        return { ok: false, message: parsed.failure };
-    }
-    if (!parsed.journey) {
-        return {
-            ok: false,
-            message: `${source} declares no executable browser steps — the scripted-browser actor needs a scenario with browser.steps (there is no built-in fallback on the lab route).`
-        };
-    }
-    return { ok: true, journey: parsed.journey, source, sourceDigest };
-}
-function scenarioRefLooksLikePath(ref) {
-    return ref.endsWith(".yaml")
-        || ref.endsWith(".yml")
-        || ref.includes("/")
-        || ref.includes("\\")
-        || ref.startsWith(".");
-}
-async function firstExistingFile(projectRoot, candidates) {
-    for (const candidate of candidates) {
-        if (await readContainedRegularFile(projectRoot, candidate) !== null) {
-            return candidate;
-        }
-    }
-    return null;
-}
-async function existingScreenshots(runPaths, result) {
-    const existing = [];
-    for (const step of result.capture.steps) {
-        // Blocked steps whose evidence is the failure itself recorded no screenshot path.
-        if (!step.screenshotPath) {
-            continue;
-        }
-        const screenshot = await readContainedRegularFile(runPaths, step.screenshotPath);
-        if (screenshot && screenshot.byteLength > 0) {
-            existing.push(step.screenshotPath);
-        }
-    }
-    return existing;
-}
-function validateScriptedSessionResult(expectedSurface, result) {
-    if (result.capture.surface.id !== expectedSurface.id || !isSafeOutputSegment(result.capture.surface.id)) {
-        throw new UnsafeScriptedSessionResultError("Scripted session returned an unexpected or unsafe surface id.");
-    }
-    const paths = [
-        result.capture.tracePath,
-        ...(result.capture.screenshotPath ? [result.capture.screenshotPath] : []),
-        ...result.capture.steps.flatMap((step) => step.screenshotPath ? [step.screenshotPath] : [])
-    ];
-    if (!paths.every(isSafeRelativeArtifactPath)) {
-        throw new UnsafeScriptedSessionResultError("Scripted session returned an unsafe artifact path.");
-    }
-}
-function isSafeOutputSegment(value) {
-    return value.length > 0
-        && value !== "."
-        && value !== ".."
-        && !value.includes("/")
-        && !value.includes("\\")
-        && !value.includes("\0");
-}
-function isSafeRelativeArtifactPath(value) {
-    if (!value || value.includes("\0") || path.isAbsolute(value) || path.posix.isAbsolute(value) || path.win32.isAbsolute(value)) {
-        return false;
-    }
-    return !value.replace(/\\/g, "/").split("/").some((part) => !part || part === "." || part === "..");
-}
-/**
- * Project the scripted lab run into a humanish.run-bundle.v1 (no schema change — a new
- * producer only). The load-bearing line is `stream.actor = result.trace`: the provider-neutral
- * ActorTrace seam the Observer renders and verifyRun's engagement check reads. Exported for
- * the bundle-builder tests.
- */
-export function buildScriptedLabBundle(args) {
-    const resultBySurface = new Map(args.sessionResults.map((result) => [result.capture.surface.id, result]));
-    const simulations = [];
-    const streams = [];
-    args.surfaces.forEach((surface, index) => {
-        const simId = `scripted-${surface.id}`;
-        const streamId = `${simId}-stream`;
-        const result = resultBySurface.get(surface.id);
-        const screenshots = args.screenshotsBySurface.get(surface.id) ?? [];
-        const lastScreenshot = screenshots.at(-1);
-        const status = result
-            ? result.status
-            : args.sessionError
-                ? "failed"
-                : "contract_proof_only";
-        const reason = result?.reason
-            ?? args.sessionError
-            ?? "Contract bundle only: dry-run pinned the scenario contract without launching a browser or touching the subject app.";
-        simulations.push({
-            id: simId,
-            index: index + 1,
-            personaId: args.persona.id,
-            scenarioId: args.journey.scenarioId,
-            status,
-            streamKind: "browser",
-            mode: "browser-sim",
-            progress: 100,
-            currentStep: reason,
-            summary: result
-                ? `Scripted-browser actor (${args.actorId}) replayed ${args.journey.scenarioId} on the ${surface.id} surface; ${result.completionReason}.`
-                : args.sessionError
-                    ? `Scripted lab failed before a terminal session verdict: ${args.sessionError}`
-                    : `Contract lane for the scripted-browser actor (${args.actorId}) against ${args.appUrl}.`,
-            streamIds: [streamId],
-            startedAt: args.createdAt,
-            updatedAt: result?.capture.capturedAt ?? args.createdAt
-        });
-        streams.push({
-            id: streamId,
-            simId,
-            kind: "browser",
-            label: `${surface.label} — ${args.labId}`,
-            status,
-            transport: "snapshot",
-            updatedAt: result?.capture.capturedAt ?? args.createdAt,
-            embed: lastScreenshot
-                ? { kind: "screenshot", url: `../${lastScreenshot}`, title: `${surface.label} (raw)` }
-                : { kind: "placeholder", title: surface.label },
-            // REAL emulated viewport: isMobile/deviceScaleFactor genuinely render on this route
-            // (playwright emulation), unlike the e2b-desktop route's prompt-signal-only fidelity.
-            viewport: surface.viewport,
-            ui: {
-                route: args.appUrl,
-                intent: args.journey.goal,
-                state: reason,
-                ...(result ? { actorStatus: result.status } : {}),
-                ...(lastScreenshot ? { screenshotUrl: `../${lastScreenshot}` } : {})
-            },
-            // The seam this registration exists to fill: the provider-neutral actor evidence.
-            ...(result ? { actor: result.trace } : {}),
-            artifacts: [
-                { label: "run bundle", path: "run.json", kind: "bundle" },
-                { label: "review", path: "review.md", kind: "review" },
-                { label: "events", path: "events.ndjson", kind: "events" },
-                ...(result
-                    ? [
-                        { label: `${surface.id} browser trace`, path: result.capture.tracePath, kind: "trace" },
-                        { label: `${surface.id} actor trace`, path: `actor-${surface.id}.json`, kind: "trace" }
-                    ]
-                    : []),
-                ...screenshots.map((screenshot, screenshotIndex) => ({
-                    label: `${surface.id} screenshot ${String(screenshotIndex + 1).padStart(2, "0")} (raw)`,
-                    path: screenshot,
-                    kind: "screenshot"
-                }))
-            ]
-        });
-    });
-    const events = [
-        {
-            id: "event-000-created",
-            at: args.createdAt,
-            level: "info",
-            type: "scripted-lab.run.created",
-            message: `Created scripted-browser lab run for ${args.labId} (actor ${args.actorId}, ${args.surfaces.length} surface${args.surfaces.length === 1 ? "" : "s"}).`
-        },
-        {
-            id: "event-001-subject",
-            at: args.createdAt,
-            level: "info",
-            type: "scripted-lab.subject.declared",
-            // Invariant 5: provenance recorded or its absence DECLARED. The lab did not provision
-            // this subject on app-url routes; clone routes carry structured subject provenance below.
-            message: args.subject
-                ? `Provisioned synthetic subject: clone of ${args.subject.repo}${args.subject.commit ? `@${args.subject.commit}` : ""}, served + getHost-exposed in-sandbox; env names: ${args.subject.envNames?.join(", ") || "none"} (values never persisted); state provenance: ${args.subject.state.provenance}; evidence host digest: ${args.hostDigest ?? "dry-run"}.`
-                : `Subject app declared at ${args.appUrl}; the lab did not provision it — subject build/commit provenance is UNPINNED; evidence binds to the scenario digest ${args.scenarioSourceDigest}.`
-        },
-        {
-            id: "event-002-spend",
-            at: args.createdAt,
-            level: "info",
-            type: "scripted-lab.spend",
-            message: args.subject
-                ? "Scripted participant steps make no model requests; post-run analysis has a separate budget unless disabled. Live provisioned runs may spend E2B sandbox minutes to clone/serve the synthetic subject."
-                : "Scripted participant steps make no model requests and use no sandbox on this route; post-run analysis has a separate budget unless disabled. scenario.mode: live gates real browser actuation against the declared app."
-        }
-    ];
-    if (args.sessionResults.length > 0) {
-        for (const result of args.sessionResults) {
-            events.push({
-                id: `event-${String(events.length).padStart(3, "0")}-session-${result.capture.surface.id}`,
-                at: result.capture.capturedAt,
-                level: result.status === "passed" ? "info" : "warn",
-                type: `scripted-lab.session.${result.completionReason}`,
-                message: `${result.capture.surface.id}: ${result.status} — ${result.reason}`,
-                simId: `scripted-${result.capture.surface.id}`,
-                streamId: `scripted-${result.capture.surface.id}-stream`
-            });
-        }
-    }
-    else if (args.sessionError) {
-        events.push({
-            id: "event-003-session-error",
-            at: args.createdAt,
-            level: "error",
-            type: "scripted-lab.session.error",
-            message: args.sessionError
-        });
-    }
-    else {
-        events.push({
-            id: "event-003-contract",
-            at: args.createdAt,
-            level: "info",
-            type: "scripted-lab.contract.ready",
-            message: `Dry-run contract bundle ready: scenario ${args.journey.scenarioId} @ ${args.scenarioSourceDigest} (${args.scenarioSource}, ${args.journey.steps.length} step${args.journey.steps.length === 1 ? "" : "s"}) parsed and digest-pinned; switch scenario.mode to live to actuate a real browser.`
-        });
-    }
-    const review = buildScriptedReview(args);
-    const ranLive = args.sessionResults.length > 0 || args.sessionError !== undefined;
-    return {
-        schema: RUN_BUNDLE_SCHEMA,
-        runId: args.runId,
-        mode: args.dryRun ? "dry-run" : "live",
-        simCount: args.surfaces.length,
-        createdAt: args.createdAt,
-        cwd: PUBLIC_TARGET_CWD,
-        ...(args.lab === undefined ? {} : { lab: args.lab }),
-        artifactRoot: path.join(".humanish", "runs", args.runId),
-        source: args.source,
-        persona: {
-            id: args.persona.id,
-            name: `Scripted journey persona (${args.persona.id})`,
-            source: `lab:${args.labId}`,
-            sourceDigest: args.persona.promptDigest
-        },
-        scenario: {
-            id: args.journey.scenarioId,
-            title: args.journey.scenarioTitle,
-            goal: redactText(args.journey.goal),
-            source: args.scenarioSource,
-            sourceDigest: args.scenarioSourceDigest
-        },
-        lifecycle: [
-            {
-                at: args.createdAt,
-                event: "scripted-lab.run.created",
-                message: `Created scripted-browser lab run with ${args.surfaces.length} surface lane${args.surfaces.length === 1 ? "" : "s"} (actor ${args.actorId}).`
-            }
-        ],
-        simulations,
-        streams,
-        events,
-        redaction: {
-            status: "passed",
-            notes: ranLive
-                ? "Scripted step URLs are sanitized to loopback origin+path (query/hash redacted) and step text passes text redaction. Screenshots are FULL-FIDELITY (raw), retained for local use in gitignored .humanish — NOT redacted for publishing; policies.redactScreenshots is not yet supported on this route."
-                : "Dry-run contract bundle: no browser ran and no screenshots were captured. The scenario contract is digest-pinned; live step text passes text redaction when a session runs."
-        },
-        artifacts: {
-            run: "run.json",
-            reviewJson: "review.json",
-            reviewMarkdown: "review.md",
-            observerData: "observer/observer-data.json",
-            events: "events.ndjson"
-        },
-        review,
-        feedbackCandidates: [],
-        ...(args.subject === undefined ? {} : { subject: args.subject }),
-        ...(args.desktopTemplate === undefined ? {} : { desktopTemplate: args.desktopTemplate })
-    };
-}
-function buildScriptedReview(args) {
-    if (args.sessionError) {
-        return {
-            schema: REVIEW_SCHEMA,
-            verdict: "fail",
-            summary: `Scripted lab failed before a terminal session verdict: ${args.sessionError}`,
-            gaps: []
-        };
-    }
-    if (args.sessionResults.length === 0) {
-        return {
-            schema: REVIEW_SCHEMA,
-            verdict: "contract_proof_only",
-            summary: `Dry-run contract for scenario ${args.journey.scenarioId} (${args.scenarioSource}, ${args.journey.steps.length} steps) against ${args.appUrl}: composition and scenario contract proven at $0; no browser ran.`,
-            gaps: ["Live scripted session not yet run (dry-run contract only)."]
-        };
-    }
-    // Worst-of across surfaces: harness/step failures outrank a timeout outranks a pass.
-    const reasons = args.sessionResults.map((result) => result.completionReason);
-    const verdict = reasons.some((reason) => reason === "harness_error" || reason === "step_failed")
-        ? "fail"
-        : reasons.some((reason) => reason === "timed_out")
-            ? "timed_out"
-            : "pass";
-    const passed = args.sessionResults.filter((result) => result.status === "passed").length;
-    return {
-        schema: REVIEW_SCHEMA,
-        verdict,
-        summary: `Scripted-browser actor replayed ${args.journey.scenarioId} on ${args.sessionResults.length} surface${args.sessionResults.length === 1 ? "" : "s"} against ${args.appUrl}: ${passed}/${args.sessionResults.length} satisfied the scenario predicate.`,
-        gaps: args.sessionResults
-            .filter((result) => result.status !== "passed")
-            .map((result) => `${result.capture.surface.id}: ${result.reason}`)
-    };
-}
-function renderScriptedReviewMarkdown(bundle) {
-    const subject = bundle.events.find((event) => event.type === "scripted-lab.subject.declared");
-    const spend = bundle.events.find((event) => event.type === "scripted-lab.spend");
-    const traces = bundle.streams
-        .map((stream) => ({ stream, trace: stream.actor }))
-        .filter((entry) => entry.trace !== undefined);
-    return [
-        `# ${bundle.scenario.title}`,
-        "",
-        `- run: ${bundle.runId}`,
-        `- mode: ${bundle.mode}`,
-        `- verdict: ${bundle.review.verdict}`,
-        `- summary: ${bundle.review.summary}`,
-        `- scenario: ${bundle.scenario.id} @ ${bundle.scenario.sourceDigest} (${bundle.scenario.source})`,
-        ...(subject ? [`- subject: ${subject.message}`] : []),
-        ...(spend ? [`- spend: ${spend.message}`] : []),
-        ...traces.map(({ stream, trace }) => `- ${stream.simId}: ${trace.provider} (${trace.lane}/${trace.protocol}) ${trace.status} (${trace.completionReason}); ${trace.counts.actions ?? 0} step action(s), ${trace.counts.screenshots ?? 0} raw screenshot(s)`),
-        ...(bundle.review.gaps.length > 0 ? ["", "## Gaps", ...bundle.review.gaps.map((gap) => `- ${gap}`)] : []),
-        ""
-    ].join("\n");
-}
-function makeScriptedRunId() {
-    const stamp = new Date().toISOString().replace(/[:.]/g, "-");
-    return `scripted-${stamp}-${randomBytes(4).toString("hex")}`;
-}
-function readPositiveInt(value, fallback) {
-    if (value === undefined)
-        return fallback;
-    const parsed = Number.parseInt(value, 10);
-    return Number.isSafeInteger(parsed) && parsed > 0 ? parsed : fallback;
-}
-function servePort(serveUrl) {
-    const url = new URL(serveUrl);
-    if (url.port)
-        return Number(url.port);
-    return url.protocol === "https:" ? 443 : 80;
-}
-function isTokenlessHost(value) {
-    try {
-        const url = new URL(value);
-        return url.username === "" && url.password === "" && url.search === "";
-    }
-    catch {
-        return false;
-    }
-}
-function hostOriginDigest(url) {
-    try {
-        return commandDigestOf(new URL(url).origin);
-    }
-    catch {
-        return commandDigestOf(url);
-    }
-}
-//# sourceMappingURL=scripted-browser-lab.js.map