humanish 0.105.0 → 0.106.0

package/dist/routes/scripted/route.js

@@ -0,0 +1,218 @@
+// The scripted route replays a committed scenario's browser steps with the registry-resolved
+// scripted-browser actor, against a loopback app the operator runs or one synthetic clone served
+// in E2B. A run reads top to bottom in runScriptedPlanInScope: setup's checks (setup.ts), startRun,
+// provision a clone subject (subject.ts), one browser session per surface (surface-sessions.ts),
+// each surface's trace, then finishScriptedRun (result.ts), which assembles the bundle and review.
+//
+// Spend: scripted steps make no model requests, and their traces record zero token usage. A local
+// app-url run spends no sandbox minutes; a live clone run spends E2B minutes to clone and serve the
+// subject. `scenario.mode: live` is required anyway, because a live run actuates a real browser
+// against a real app (it fills forms and clicks buttons). A dry run parses and digest-pins the
+// scenario and writes the contract bundle without touching anything.
+//
+// Subject provenance (invariant 5): an app-url run declares that the lab did not provision the
+// subject, so its build provenance is unpinned and the evidence binds to the scenario digest. A
+// clone run records commit, env names, state provenance and a host digest, never the raw getHost
+// URL or a secret value.
+import { randomBytes } from "node:crypto";
+import { realpath } from "node:fs/promises";
+import path from "node:path";
+import { completeAutomaticAnalysis } from "../../analysis/automatic-completion.js";
+import { resolveAutomaticAnalysis } from "../../analysis/automatic-config.js";
+import { redactText, toErrorMessage } from "../../evidence/redaction.js";
+import { buildRunSource } from "../../run/bundle.js";
+import { prepareSelectedOutputDirectory } from "../../run/contained-output.js";
+import { runScope } from "../../run/run.js";
+import { renderScriptedReviewMarkdown } from "./bundle.js";
+import { planScriptedLab } from "./plan.js";
+import { finishScriptedRun } from "./result.js";
+import { UnsafeScriptedSessionResultError } from "./session-result.js";
+import { prepareScriptedRun } from "./setup.js";
+import { ScriptedSubject } from "./subject.js";
+import { runScriptedSessions, writeSurfaceTraces } from "./surface-sessions.js";
+import { SCRIPTED_BROWSER_LAB_SCHEMA, } from "./types.js";
+/**
+ * The config-taking entry point. It plans, returns a refusal with the envelope the route has always
+ * returned at that refusal's stage, and otherwise runs the plan.
+ */
+export async function runScriptedBrowserLab(options) {
+    const { config, dryRun, lab, ...input } = options;
+    // planScriptedLab makes every configuration refusal, in the order this route always has.
+    const planned = planScriptedLab(config, {
+        dryRun,
+        ...(lab === undefined ? {} : { lab }),
+        ...(input.hooks === undefined ? {} : { hooks: input.hooks }),
+    });
+    if (planned.ok)
+        return runScriptedPlan(planned.plan, input);
+    return scriptedLabRefusal(options, planned.refusal);
+}
+/**
+ * A refused scripted lab's result, at the refusal's stage: a before-scope refusal has its own field
+ * order and no analysis record; the others come after the output directory checks.
+ */
+export async function scriptedLabRefusal(options, refusal) {
+    const { config, dryRun } = options;
+    const cwd = path.resolve(options.cwd);
+    const actorType = config.actors[0]?.type ?? "";
+    if (refusal.beforeScope)
+        return {
+            schema: SCRIPTED_BROWSER_LAB_SCHEMA,
+            ok: false,
+            cwd,
+            labId: config.id,
+            actor: actorType,
+            dryRun,
+            runId: options.runId ?? "not-created",
+            appUrl: config.subject.appUrl ?? "",
+            sessions: [],
+            warnings: [],
+            error: { code: refusal.code, message: refusal.message },
+        };
+    // The other refusals come after the output directory checks and carry the analysis record.
+    const physicalCwd = await realpath(cwd);
+    await prepareSelectedOutputDirectory(path.dirname(physicalCwd), physicalCwd);
+    const refused = {
+        schema: SCRIPTED_BROWSER_LAB_SCHEMA,
+        ok: false,
+        cwd,
+        labId: config.id,
+        actor: refusal.actor ?? actorType,
+        appUrl: refusal.appUrl ?? config.subject.appUrl ?? "",
+        dryRun,
+        runId: options.runId ?? "not-created",
+        sessions: [],
+        warnings: [],
+        error: { code: refusal.code, message: refusal.message },
+    };
+    const analysis = resolveAutomaticAnalysis(config.review?.analysis);
+    return completeAutomaticAnalysis(refused, undefined, analysis.ok ? analysis.config : undefined, options.automaticAnalysis, { trigger: config.review?.analysis === undefined ? "default" : "explicit" });
+}
+/**
+ * runLab's step for a scripted plan. It takes no scorer, and its local checks (keys, a browser)
+ * run inside the run, so it returns the run.
+ */
+export function admitScriptedPlan(plan, input) {
+    return {
+        ok: true,
+        run: async () => ({
+            route: "scripted",
+            backend: "scripted",
+            result: await runScriptedPlan(plan, input),
+        }),
+    };
+}
+/**
+ * Run a scripted plan. The run scope gives a direct library caller the same status-record lifetime
+ * the CLI gets: returning from this function finalizes any record the run opened, whichever of its
+ * fail-closed exits it took. Each route opens its own scope; `runLab` opens none. Without this a
+ * test or an adopter calling the route directly leaves
+ * the 5s cadence ticking into a directory something else is deleting, which surfaces as an
+ * unrelated ENOTEMPTY.
+ */
+export async function runScriptedPlan(plan, input) {
+    const { result, finished } = await runScope((scope) => runScriptedPlanInScope(plan, input, scope));
+    return completeAutomaticAnalysis(result, finished, plan.analysis?.config, input.automaticAnalysis, {
+        ...(plan.analysis === undefined ? {} : { trigger: plan.analysis.trigger }),
+        preferLargerOutput: plan.analysis?.preferLargerOutput === true,
+    });
+}
+async function runScriptedPlanInScope(plan, input, scope) {
+    const prepared = await prepareScriptedRun(plan, input);
+    if (!prepared.ok)
+        return prepared.result;
+    const { dryRun } = plan;
+    const { setup } = prepared;
+    const started = await scope.startRun({
+        cwd: setup.physicalCwd,
+        runId: input.runId,
+        mintRunId: makeScriptedRunId,
+        mode: dryRun ? "dry-run" : "live",
+        lab: plan.lab,
+        renderReview: renderScriptedReviewMarkdown,
+        observer: { open: input.open === true, render: setup.hooks.renderObserverFn },
+    });
+    if (!started.ok) {
+        return setup.failed(started.code, started.message);
+    }
+    const { run } = started;
+    const { createdAt, paths: runPaths } = run;
+    const artifactRoot = runPaths.physicalRunRoot;
+    const source = await buildRunSource({
+        capturedAt: createdAt,
+        cwd: setup.physicalCwd,
+        humanishSource: "present",
+        packageName: "humanish",
+    });
+    const scriptedSubject = setup.clone
+        ? new ScriptedSubject({
+            plan,
+            clone: setup.clone,
+            hooks: setup.hooks,
+            env: setup.env,
+            e2bApiKey: setup.e2bApiKey,
+            runPaths,
+            timeoutMs: setup.timeoutMs,
+            subjectEnvNames: setup.subjectEnvNames,
+            hasGithubToken: setup.hasGithubToken,
+            scrubKnownValues: setup.scrubKnownValues,
+            now: setup.hooks.now ?? Date.now,
+            warnings: setup.warnings,
+        })
+        : undefined;
+    let sessionResults = [];
+    let sessionError;
+    if (!dryRun) {
+        try {
+            const appUrl = scriptedSubject ? await scriptedSubject.provision() : setup.appUrl;
+            sessionResults = await runScriptedSessions({
+                appUrl,
+                evidenceAppUrl: setup.evidenceAppUrl,
+                urlPolicy: setup.urlPolicy,
+                journey: setup.journey,
+                persona: setup.persona,
+                timeoutMs: setup.timeoutMs,
+                artifactRoot,
+            }, {
+                surfaces: setup.surfaces,
+                hooks: setup.hooks,
+                browserCommand: setup.browserCommand,
+                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(setup.scrubKnownValues(toErrorMessage(error)));
+        }
+        finally {
+            await scriptedSubject?.teardown();
+        }
+        await writeSurfaceTraces(runPaths, sessionResults);
+    }
+    return finishScriptedRun({
+        plan,
+        cwd: setup.cwd,
+        evidenceAppUrl: setup.evidenceAppUrl,
+        run,
+        source,
+        journey: setup.journey,
+        scenario: setup.scenario,
+        persona: setup.persona,
+        surfaces: setup.surfaces,
+        sessionResults,
+        sessionError,
+        warnings: setup.warnings,
+        clone: setup.clone,
+        redactRepoLabel: setup.redactRepoLabel,
+        subjectEnvNames: setup.subjectEnvNames,
+        scriptedSubject,
+    });
+}
+function makeScriptedRunId() {
+    const stamp = new Date().toISOString().replace(/[:.]/g, "-");
+    return `scripted-${stamp}-${randomBytes(4).toString("hex")}`;
+}

package/dist/routes/scripted/scenario.d.ts

@@ -0,0 +1,21 @@
+import type { BrowserPersonaJourney } from "../../actors/scripted-browser/types.js";
+import { type PreparedSelectedOutputDirectory } from "../../run/contained-output.js";
+interface ResolvedScriptedScenario {
+    ok: true;
+    journey: BrowserPersonaJourney;
+    /** Repo-relative provenance path (clamped inside the target cwd, fail-closed). */
+    source: string;
+    sourceDigest: string;
+}
+/**
+ * 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. planScriptedLab
+ * has already refused a missing or blank ref.
+ */
+export declare function resolveScriptedScenario(projectRoot: PreparedSelectedOutputDirectory, ref: string): Promise<ResolvedScriptedScenario | {
+    ok: false;
+    message: string;
+}>;
+export {};

package/dist/routes/scripted/scenario.js

@@ -0,0 +1,102 @@
+// Resolve a scripted-browser lab's `scenario.ref` to a committed scenario file and parse its
+// `browser.steps` into the journey the actor runs. The ref is an id or a repo-relative path that must
+// stay inside the project; provenance records it repo-relative with the scenario's digest.
+import { parse as parseYaml } from "yaml";
+import path from "node:path";
+import { parseBrowserPersonaJourneyFromScenario } from "../../actors/scripted-browser/journey.js";
+import { digestText } from "../../evidence/redaction.js";
+import { readContainedRegularFile, } from "../../run/contained-output.js";
+// 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_.-]*$/;
+/**
+ * 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. planScriptedLab
+ * has already refused a missing or blank ref.
+ */
+export async function resolveScriptedScenario(projectRoot, ref) {
+    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.`,
+        };
+    }
+    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;
+}

package/dist/routes/scripted/session-result.d.ts

@@ -0,0 +1,8 @@
+import type { ScriptedBrowserSessionResult } from "../../actors/scripted-browser/actor.js";
+import type { BrowserSurface } from "../../actors/scripted-browser/types.js";
+import type { PreparedRunArtifactPaths } from "../../run/paths.js";
+export declare class UnsafeScriptedSessionResultError extends Error {
+    constructor(message: string);
+}
+export declare function existingScreenshots(runPaths: PreparedRunArtifactPaths, result: ScriptedBrowserSessionResult): Promise<string[]>;
+export declare function validateScriptedSessionResult(expectedSurface: BrowserSurface, result: ScriptedBrowserSessionResult): void;

package/dist/routes/scripted/session-result.js

@@ -0,0 +1,60 @@
+// Check a scripted-browser session result before the route persists it: every screenshot and trace
+// path it names must be a safe path inside the run's artifact root. A result that fails is unsafe,
+// and the route stops without writing a bundle from it.
+import path from "node:path";
+import { readContainedRegularFile } from "../../run/contained-output.js";
+export class UnsafeScriptedSessionResultError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "UnsafeScriptedSessionResultError";
+    }
+}
+export 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;
+}
+export 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 === "..");
+}

package/dist/routes/scripted/setup.d.ts

@@ -0,0 +1,45 @@
+import type { ActorPersonaRef } from "../../actors/contract.js";
+import type { BrowserPersonaJourney, ScriptedBrowserEvidenceUrlPolicy } from "../../actors/scripted-browser/types.js";
+import type { ScriptedPlan } from "../../lab/plan-types.js";
+import { type ScriptedBrowserLabHooks, type ScriptedBrowserLabResult, type ScriptedRunInput } from "./types.js";
+/** What setup hands the run: the plan's subject and scenario, keys and the browser to launch. */
+export interface ScriptedRunSetup {
+    cwd: string;
+    physicalCwd: string;
+    hooks: ScriptedBrowserLabHooks;
+    warnings: string[];
+    failed: (code: NonNullable<ScriptedBrowserLabResult["error"]>["code"], message: string) => ScriptedBrowserLabResult;
+    clone: Extract<ScriptedPlan["subject"], {
+        readonly kind: "clone";
+    }> | undefined;
+    evidenceAppUrl: string;
+    urlPolicy: ScriptedBrowserEvidenceUrlPolicy;
+    subjectEnvNames: string[];
+    env: Record<string, string | undefined>;
+    e2bApiKey: string;
+    hasGithubToken: boolean;
+    redactRepoLabel: boolean;
+    scrubKnownValues: (text: string) => string;
+    /** The loopback app URL, or the clone's serve URL until its getHost URL replaces it. */
+    appUrl: string;
+    scenario: {
+        source: string;
+        sourceDigest: string;
+    };
+    journey: BrowserPersonaJourney;
+    surfaces: ScriptedPlan["surfaces"];
+    timeoutMs: number;
+    persona: ActorPersonaRef;
+    browserCommand: string | undefined;
+}
+/**
+ * Checks what the plan cannot: the scenario file, the E2B key and subject env of a live clone,
+ * and a browser to launch. Returns the refusal, or what the run needs.
+ */
+export declare function prepareScriptedRun(plan: ScriptedPlan, input: ScriptedRunInput): Promise<{
+    ok: false;
+    result: ScriptedBrowserLabResult;
+} | {
+    ok: true;
+    setup: ScriptedRunSetup;
+}>;

package/dist/routes/scripted/setup.js

@@ -0,0 +1,126 @@
+// What a scripted run needs before it starts: the checks the plan cannot make (the scenario file,
+// the E2B key and subject env of a live clone, a browser to launch) and the values the run reads
+// (the evidence URL policy, the scrubber for clone values, the persona and the session budget).
+import { realpath } from "node:fs/promises";
+import path from "node:path";
+import { resolveBrowserCommand } from "../../actors/scripted-browser/browser-command.js";
+import { describeMissingKeys } from "../../keys/key-resolution.js";
+import { prepareSelectedOutputDirectory } from "../../run/contained-output.js";
+import { evidenceAppUrlOf } from "./plan.js";
+import { resolveScriptedScenario } from "./scenario.js";
+import { SCRIPTED_BROWSER_LAB_SCHEMA, } from "./types.js";
+// Journey wall-clock budget per surface: 5 minutes. 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;
+/**
+ * Checks what the plan cannot: the scenario file, the E2B key and subject env of a live clone,
+ * and a browser to launch. Returns the refusal, or what the run needs.
+ */
+export async function prepareScriptedRun(plan, input) {
+    const { dryRun } = plan;
+    const cwd = path.resolve(input.cwd);
+    const physicalCwd = await realpath(cwd);
+    const projectRoot = await prepareSelectedOutputDirectory(path.dirname(physicalCwd), physicalCwd);
+    const hooks = input.hooks ?? {};
+    const warnings = [];
+    const clone = plan.subject.kind === "clone" ? plan.subject : undefined;
+    const evidenceAppUrl = evidenceAppUrlOf(plan.subject);
+    const failed = (code, message) => ({
+        schema: SCRIPTED_BROWSER_LAB_SCHEMA,
+        ok: false,
+        cwd,
+        labId: plan.labId,
+        actor: plan.actor,
+        appUrl: evidenceAppUrl,
+        dryRun,
+        runId: input.runId ?? "not-created",
+        sessions: [],
+        warnings,
+        error: { code, message },
+    });
+    const urlPolicy = clone
+        ? { kind: "provisioned-subject", evidenceOrigin: evidenceAppUrl }
+        : { kind: "loopback" };
+    const subjectEnvNames = [...(clone?.env ?? [])];
+    const env = hooks.env ?? process.env;
+    const e2bApiKey = env.E2B_API_KEY?.trim() ?? "";
+    const hasGithubToken = subjectEnvNames.includes("GITHUB_TOKEN");
+    const redactRepoLabel = plan.residual.policies?.redactRepos ?? hasGithubToken;
+    const scrubSourceValues = [
+        ...(clone ? [clone.repo] : []),
+        ...subjectEnvNames.map((name) => env[name] ?? ""),
+    ].filter(Boolean);
+    const scrubKnownValues = (text) => scrubSourceValues.reduce((acc, value) => acc.split(value).join("[redacted]"), text);
+    // A clone's URL is replaced by its getHost URL once it is served.
+    let appUrl = plan.subject.kind === "clone" ? plan.subject.serve.url : plan.subject.appUrl;
+    const scenario = await resolveScriptedScenario(projectRoot, plan.scenarioRef);
+    if (!scenario.ok) {
+        return {
+            ok: false,
+            result: failed("HUMANISH_SCRIPTED_LAB_SCENARIO_INVALID", scenario.message),
+        };
+    }
+    const journey = scenario.journey;
+    if (!dryRun && clone) {
+        if (!e2bApiKey) {
+            return {
+                ok: false,
+                result: 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)}`),
+            };
+        }
+        const missingSubjectEnv = subjectEnvNames.filter((name) => !env[name]?.trim());
+        if (missingSubjectEnv.length > 0) {
+            return {
+                ok: false,
+                result: failed("HUMANISH_SCRIPTED_LAB_SUBJECT_ENV_MISSING", `Subject env values missing for live clone scripted-browser lab: ${missingSubjectEnv.join(", ")}.`),
+            };
+        }
+    }
+    const surfaces = plan.surfaces;
+    const timeoutMs = plan.sessionTimeoutMs ?? DEFAULT_SESSION_TIMEOUT_MS;
+    const persona = {
+        id: plan.personaId ?? "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 {
+                ok: false,
+                result: 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."),
+            };
+        }
+        browserCommand = resolved;
+    }
+    return {
+        ok: true,
+        setup: {
+            cwd,
+            physicalCwd,
+            hooks,
+            warnings,
+            failed,
+            clone,
+            evidenceAppUrl,
+            urlPolicy,
+            subjectEnvNames,
+            env,
+            e2bApiKey,
+            hasGithubToken,
+            redactRepoLabel,
+            scrubKnownValues,
+            appUrl,
+            scenario,
+            journey,
+            surfaces,
+            timeoutMs,
+            persona,
+            browserCommand,
+        },
+    };
+}

package/dist/routes/scripted/subject.d.ts

@@ -0,0 +1,49 @@
+import type { ScriptedPlan } from "../../lab/plan-types.js";
+import { type PreparedRunArtifactPaths } from "../../run/paths.js";
+import type { RunSubjectStateStepRecord } from "../../run/bundle.js";
+import { type DesktopResourceObservation } from "../../substrates/e2b/desktop-resources.js";
+import type { ScriptedBrowserLabHooks } from "./types.js";
+type ScriptedCloneSubject = Extract<ScriptedPlan["subject"], {
+    readonly kind: "clone";
+}>;
+/** What the subject needs from the run. */
+export interface ScriptedSubjectInputs {
+    plan: ScriptedPlan;
+    clone: ScriptedCloneSubject;
+    hooks: ScriptedBrowserLabHooks;
+    env: Record<string, string | undefined>;
+    e2bApiKey: string;
+    runPaths: PreparedRunArtifactPaths;
+    timeoutMs: number;
+    subjectEnvNames: string[];
+    hasGithubToken: boolean;
+    scrubKnownValues: (text: string) => string;
+    now: () => number;
+    /** The run's warnings. Teardown appends to it. */
+    warnings: string[];
+}
+/** The subject sandbox and what provisioning it recorded. */
+export declare class ScriptedSubject {
+    sandboxId: string | undefined;
+    killed: boolean;
+    commit: string | undefined;
+    hostDigest: string | undefined;
+    readonly stateStepRecords: RunSubjectStateStepRecord[];
+    private readonly inputs;
+    private allocation;
+    private createdAtMs;
+    private tornDownAtMs;
+    private resources;
+    constructor(inputs: ScriptedSubjectInputs);
+    /** Acquires, provisions and serves the subject. Returns the tokenless getHost URL to drive. */
+    provision(): Promise<string>;
+    /** Releases the subject by exact id, when one was acquired. An unconfirmed release is reported. */
+    teardown(): Promise<void>;
+    /** The subject desktop's billed span and size, when one was acquired. */
+    desktopUsage(): {
+        durationMs: number | undefined;
+        observation: DesktopResourceObservation | undefined;
+        killed: boolean;
+    } | undefined;
+}
+export {};