humanish 0.106.1 → 0.107.0

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

@@ -2,15 +2,13 @@ import type { ActorPersonaRef } from "../../actors/contract.js";
 import type { ScriptedBrowserSessionResult } from "../../actors/scripted-browser/actor.js";
 import type { BrowserPersonaJourney, BrowserSurface } from "../../actors/scripted-browser/types.js";
 import type { DesktopResourceObservation } from "../../substrates/e2b/desktop-resources.js";
-import { type ReviewSummary, type RunBundle, type RunSubjectProvenance } from "../../run/bundle.js";
-import type { RunLabProvenance } from "../../run/status.js";
+import { type ReviewSummary, type RunBundle, type RunSubjectProvenance, type BundleRun } from "../../run/bundle.js";
 /** What the scripted lab's bundle is built from. */
 interface ScriptedBundleArgs {
-    /** Lab provenance for the bundle\'s own `lab` field (#455). */
-    lab?: RunLabProvenance;
+    /** The run this bundle belongs to; the bundle head reads its id, mode, start and lab. */
+    run: BundleRun;
     actorId: string;
     appUrl: string;
-    createdAt: string;
     desktopTemplate?: string;
     dryRun: boolean;
     hostDigest?: string;
@@ -18,7 +16,6 @@ interface ScriptedBundleArgs {
     labId: string;
     labTitle?: string;
     persona: ActorPersonaRef;
-    runId: string;
     scenarioSource: string;
     scenarioSourceDigest: string;
     screenshotsBySurface: Map<string, string[]>;

package/dist/routes/scripted/bundle.js

@@ -14,20 +14,15 @@ import { scriptedSurfaceIds, scriptedSurfaceRecords } from "./surface-records.js
  */
 export function buildScriptedLabBundle(args) {
     const resultBySurface = new Map(args.sessionResults.map((result) => [result.capture.surface.id, result]));
-    const records = args.surfaces.map((surface, index) => scriptedSurfaceRecords(args, surface, index, resultBySurface.get(surface.id), args.screenshotsBySurface.get(surface.id) ?? []));
+    // Each surface's records are stamped with the run's start.
+    const context = { ...args, createdAt: args.run.createdAt };
+    const records = args.surfaces.map((surface, index) => scriptedSurfaceRecords(context, surface, index, resultBySurface.get(surface.id), args.screenshotsBySurface.get(surface.id) ?? []));
     const events = scriptedEvents(args);
     const review = buildScriptedReview(args);
     const ranLive = args.sessionResults.length > 0 || args.sessionError !== undefined;
     const cost = args.dryRun ? undefined : scriptedCost(args.subjectDesktop);
     return {
-        ...bundleHead({
-            runId: args.runId,
-            mode: args.dryRun ? "dry-run" : "live",
-            participants: args.surfaces.length,
-            createdAt: args.createdAt,
-            ...(args.lab === undefined ? {} : { lab: args.lab }),
-            source: args.source,
-        }),
+        ...bundleHead(args.run, { participants: args.surfaces.length, source: args.source }),
         persona: {
             id: args.persona.id,
             name: `Scripted journey persona (${args.persona.id})`,
@@ -43,7 +38,7 @@ export function buildScriptedLabBundle(args) {
         },
         lifecycle: [
             {
-                at: args.createdAt,
+                at: args.run.createdAt,
                 event: "scripted-lab.run.created",
                 message: `Created scripted-browser lab run with ${args.surfaces.length} surface${args.surfaces.length === 1 ? "" : "s"} (actor ${args.actorId}).`,
             },
@@ -70,17 +65,17 @@ function scriptedEvents(args) {
     const events = [
         {
             id: "event-000-created",
-            at: args.createdAt,
+            at: args.run.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,
+            at: args.run.createdAt,
             level: "info",
             type: "scripted-lab.subject.declared",
-            // Invariant 5: provenance recorded or its absence DECLARED. The lab did not provision
+            // 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"}.`
@@ -88,7 +83,7 @@ function scriptedEvents(args) {
         },
         {
             id: "event-002-spend",
-            at: args.createdAt,
+            at: args.run.createdAt,
             level: "info",
             type: "scripted-lab.spend",
             message: args.subject
@@ -110,7 +105,7 @@ function scriptedEvents(args) {
     else if (args.sessionError !== undefined) {
         events.push({
             id: "event-003-session-error",
-            at: args.createdAt,
+            at: args.run.createdAt,
             level: "error",
             type: "scripted-lab.session.error",
             message: args.sessionError,
@@ -119,7 +114,7 @@ function scriptedEvents(args) {
     else {
         events.push({
             id: "event-003-contract",
-            at: args.createdAt,
+            at: args.run.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.`,

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

@@ -1,6 +1,6 @@
+import type { LabDeps } from "../../lab/lab-deps.js";
 import type { RoutePlanResult, RouteRefusal, ScriptedPlan } from "../../lab/plan-types.js";
 import type { LabConfig } from "../../lab/types.js";
-import type { RunLabProvenance } from "../../run/status.js";
 /** The error a scripted lab returns before a run starts. */
 export interface ScriptedRefusal extends RouteRefusal<"scripted", "HUMANISH_LAB_ANALYSIS_INVALID" | "HUMANISH_LAB_TASKS_UNSUPPORTED" | "HUMANISH_SCRIPTED_LAB_ACTOR_UNSUPPORTED" | "HUMANISH_SCRIPTED_LAB_SCENARIO_INVALID" | "HUMANISH_SCRIPTED_LAB_SUBJECT_UNSAFE"> {
     /**
@@ -15,16 +15,14 @@ export interface ScriptedRefusal extends RouteRefusal<"scripted", "HUMANISH_LAB_
 export type ScriptedPlanResult = RoutePlanResult<ScriptedPlan, ScriptedRefusal>;
 /** The app URL a run's evidence names: a provisioned subject's getHost URL is never persisted. */
 export declare function evidenceAppUrlOf(subject: ScriptedPlan["subject"]): string;
+/** Whether a test injected the browser, so a live run needs no host browser. */
+export declare function injectedBrowser(deps: LabDeps | undefined): boolean;
 /**
  * Plan a scripted-browser lab. It is called for any config handed to the scripted runner, not only
  * one routeOf sends here, so a config for another route gets this route's refusal.
  */
 export declare function planScriptedLab(config: LabConfig, input: {
     readonly dryRun: boolean;
-    readonly lab?: RunLabProvenance;
-    /** An injected browser means a live run needs no host browser. */
-    readonly hooks?: {
-        readonly launchBrowser?: unknown;
-        readonly browserCommand?: string;
-    };
+    /** A test's injected browser means a live run needs no host browser. */
+    readonly injectedBrowser?: boolean;
 }): ScriptedPlanResult;

package/dist/routes/scripted/plan.js

@@ -7,13 +7,17 @@ import { browserSurfaces } from "../../actors/scripted-browser/types.js";
 import { resolveAutomaticAnalysis } from "../../analysis/automatic-config.js";
 import { isNonEmpty, planBase, provisionedSubject } from "../../lab/plan-base.js";
 import { cloneTargetValidationReason, desktopMediaValidationReason, taskProtocolValidationReason, } from "../../lab/validation.js";
-// Default surface roster is 1 (desktop only): the defaults-table single-lane row governs;
+// Default surface roster is 1 (desktop only): the defaults-table single-participant row governs;
 // `count: 2` is the declared override that adds the mobile surface.
 const DEFAULT_SURFACE_COUNT = 1;
 /** The app URL a run's evidence names: a provisioned subject's getHost URL is never persisted. */
 export function evidenceAppUrlOf(subject) {
     return subject.kind === "clone" ? "[provisioned-subject]" : subject.appUrl;
 }
+/** Whether a test injected the browser, so a live run needs no host browser. */
+export function injectedBrowser(deps) {
+    return Boolean(deps?.launchBrowser || deps?.browserCommand);
+}
 /**
  * Plan a scripted-browser lab. It is called for any config handed to the scripted runner, not only
  * one routeOf sends here, so a config for another route gets this route's refusal.
@@ -62,7 +66,6 @@ export function planScriptedLab(config, input) {
     const scenarioRef = config.scenario?.ref;
     if (!scenarioRef?.trim())
         return refuse("HUMANISH_SCRIPTED_LAB_SCENARIO_INVALID", "scripted-browser labs require `scenario.ref` — the committed scenario's browser steps are what this actor executes.", { actor, appUrl: evidenceAppUrlOf(subject) });
-    const hooks = input.hooks ?? {};
     const requirements = [];
     if (!input.dryRun && subject.kind === "clone") {
         requirements.push({ kind: "key", name: "E2B_API_KEY" });
@@ -70,7 +73,7 @@ export function planScriptedLab(config, input) {
             requirements.push({ kind: "subject-env", names: subject.env });
     }
     // The browser runs on this machine on both subjects; a clone's is pointed at its getHost URL.
-    if (!input.dryRun && !hooks.launchBrowser && !hooks.browserCommand)
+    if (!input.dryRun && input.injectedBrowser !== true)
         requirements.push({ kind: "host-browser" });
     const persona = config.actors[0]?.persona;
     const timeoutMs = config.execution?.timeoutMs;
@@ -79,7 +82,6 @@ export function planScriptedLab(config, input) {
         plan: {
             ...planBase(config, {
                 dryRun: input.dryRun,
-                ...(input.lab === undefined ? {} : { lab: input.lab }),
                 analysis,
             }),
             route: "scripted",

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

@@ -36,13 +36,16 @@ export interface ScriptedFinishInputs {
 }
 /**
  * The scripted run's execution failures: the session's own error, a live surface that never
- * returned, a surface that ended in a harness error, and an Observer that failed.
+ * returned, a surface that ended in a harness error, a subject sandbox whose release is
+ * unconfirmed, and an Observer that failed.
  */
 export declare function scriptedExecutionFailures(args: {
     dryRun: boolean;
+    runId: string;
     sessionError: string | undefined;
     expected: number;
     sessionResults: readonly Pick<ScriptedBrowserSessionResult, "completionReason" | "reason">[];
+    subject: Pick<ScriptedSubject, "sandboxId" | "killed" | "releaseWarning"> | undefined;
     observer: Pick<ObserverResult, "ok" | "error">;
 }): ExecutionFailure[];
 export declare function finishScriptedRun(inputs: ScriptedFinishInputs): Promise<ScriptedBrowserLabResult>;

package/dist/routes/scripted/result.js

@@ -1,4 +1,4 @@
-import { judgeExecution, judgeScripted, OUTCOME_POLICIES, resultOk, } from "../../run/judge.js";
+import { judgeExecution, sandboxCleanupFailure, judgeScripted, OUTCOME_POLICIES, resultOk, } from "../../run/judge.js";
 import { validatePreparedRunArtifactPaths } from "../../run/paths.js";
 import { resolveSubjectState } from "../computer-use/subject-projection.js";
 import { buildScriptedLabBundle } from "./bundle.js";
@@ -16,7 +16,8 @@ function scriptedSurfaceFacts(result) {
 }
 /**
  * The scripted run's execution failures: the session's own error, a live surface that never
- * returned, a surface that ended in a harness error, and an Observer that failed.
+ * returned, a surface that ended in a harness error, a subject sandbox whose release is
+ * unconfirmed, and an Observer that failed.
  */
 export function scriptedExecutionFailures(args) {
     const { sessionError, sessionResults, observer } = args;
@@ -39,6 +40,9 @@ export function scriptedExecutionFailures(args) {
                 },
             ]
             : []),
+        ...(args.subject?.sandboxId === undefined || args.subject.killed
+            ? []
+            : [sandboxCleanupFailure("subject", args.subject.releaseWarning, args.runId)]),
         ...(observer.ok
             ? []
             : [
@@ -54,7 +58,7 @@ export async function finishScriptedRun(inputs) {
     const { surfaces, sessionResults, sessionError, warnings, clone, redactRepoLabel } = inputs;
     const { subjectEnvNames, scriptedSubject } = inputs;
     const { actor, dryRun } = plan;
-    const { runId, createdAt, paths: runPaths } = run;
+    const { runId, paths: runPaths } = run;
     const subjectCommit = scriptedSubject?.commit;
     const subjectSandboxId = scriptedSubject?.sandboxId;
     const subjectKilled = scriptedSubject?.killed ?? false;
@@ -86,16 +90,14 @@ export async function finishScriptedRun(inputs) {
         surfaces: sessionResults.map(scriptedSurfaceFacts),
     });
     const bundle = buildScriptedLabBundle({
-        ...(plan.lab === undefined ? {} : { lab: plan.lab }),
+        run,
         actorId: actor,
         appUrl: evidenceAppUrl,
-        createdAt,
         dryRun,
         journey,
         labId: plan.labId,
         ...(plan.title ? { labTitle: plan.title } : {}),
         persona,
-        runId,
         scenarioSource: scenario.source,
         scenarioSourceDigest: scenario.sourceDigest,
         screenshotsBySurface,
@@ -122,9 +124,11 @@ export async function finishScriptedRun(inputs) {
     const policy = OUTCOME_POLICIES.scripted;
     const execution = judgeExecution(scriptedExecutionFailures({
         dryRun,
+        runId,
         sessionError,
         expected: surfaces.length,
         sessionResults,
+        subject: scriptedSubject,
         observer,
     }), policy);
     const ok = resultOk({ judgment, execution, scorerFailures: [], policy });

package/dist/routes/scripted/route.js

@@ -24,7 +24,7 @@ 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 { injectedBrowser, planScriptedLab } from "./plan.js";
 import { finishScriptedRun } from "./result.js";
 import { UnsafeScriptedSessionResultError } from "./session-result.js";
 import { prepareScriptedRun } from "./setup.js";
@@ -36,12 +36,11 @@ import { SCRIPTED_BROWSER_LAB_SCHEMA, } from "./types.js";
  * returned at that refusal's stage, and otherwise runs the plan.
  */
 export async function runScriptedBrowserLab(options) {
-    const { config, dryRun, lab, ...input } = options;
+    const { config, dryRun, ...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 }),
+        injectedBrowser: injectedBrowser(input.deps),
     });
     if (planned.ok)
         return runScriptedPlan(planned.plan, input);
@@ -86,7 +85,7 @@ export async function scriptedLabRefusal(options, refusal) {
         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" });
+    return completeAutomaticAnalysis(refused, undefined, analysis.ok ? analysis.config : undefined, options, { 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)
@@ -97,7 +96,6 @@ export function admitScriptedPlan(plan, input) {
         ok: true,
         run: async () => ({
             route: "scripted",
-            backend: "scripted",
             result: await runScriptedPlan(plan, input),
         }),
     };
@@ -112,7 +110,7 @@ export function admitScriptedPlan(plan, input) {
  */
 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, {
+    return completeAutomaticAnalysis(result, finished, plan.analysis?.config, input, {
         ...(plan.analysis === undefined ? {} : { trigger: plan.analysis.trigger }),
         preferLargerOutput: plan.analysis?.preferLargerOutput === true,
     });
@@ -130,7 +128,7 @@ async function runScriptedPlanInScope(plan, input, scope) {
         mode: dryRun ? "dry-run" : "live",
         lab: plan.lab,
         renderReview: renderScriptedReviewMarkdown,
-        observer: { open: input.open === true, render: setup.hooks.renderObserverFn },
+        observer: { open: input.open === true, render: setup.deps.renderObserver },
     });
     if (!started.ok) {
         return setup.failed(started.code, started.message);
@@ -148,7 +146,8 @@ async function runScriptedPlanInScope(plan, input, scope) {
         ? new ScriptedSubject({
             plan,
             clone: setup.clone,
-            hooks: setup.hooks,
+            deps: setup.deps,
+            ...(input.prepareDesktop === undefined ? {} : { prepareDesktop: input.prepareDesktop }),
             env: setup.env,
             e2bApiKey: setup.e2bApiKey,
             runPaths,
@@ -156,7 +155,7 @@ async function runScriptedPlanInScope(plan, input, scope) {
             subjectEnvNames: setup.subjectEnvNames,
             hasGithubToken: setup.hasGithubToken,
             scrubKnownValues: setup.scrubKnownValues,
-            now: setup.hooks.now ?? Date.now,
+            now: setup.deps.now ?? Date.now,
             warnings: setup.warnings,
         })
         : undefined;
@@ -175,7 +174,7 @@ async function runScriptedPlanInScope(plan, input, scope) {
                 artifactRoot,
             }, {
                 surfaces: setup.surfaces,
-                hooks: setup.hooks,
+                deps: setup.deps,
                 browserCommand: setup.browserCommand,
                 runPaths,
             });

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

@@ -9,7 +9,7 @@ interface ResolvedScriptedScenario {
 }
 /**
  * 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
+ * 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.

package/dist/routes/scripted/scenario.js

@@ -11,7 +11,7 @@ import { readContainedRegularFile, } from "../../run/contained-output.js";
 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
+ * 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.

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

@@ -1,12 +1,13 @@
 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";
+import { type ScriptedBrowserLabResult, type ScriptedRunInput } from "./types.js";
+import type { LabDeps } from "../../lab/lab-deps.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;
+    deps: LabDeps;
     warnings: string[];
     failed: (code: NonNullable<ScriptedBrowserLabResult["error"]>["code"], message: string) => ScriptedBrowserLabResult;
     clone: Extract<ScriptedPlan["subject"], {

package/dist/routes/scripted/setup.js

@@ -2,6 +2,7 @@
 // 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 { missingKeys, missingSubjectEnv } from "../../lab/requirements.js";
 import path from "node:path";
 import { resolveBrowserCommand } from "../../actors/scripted-browser/browser-command.js";
 import { describeMissingKeys } from "../../keys/key-resolution.js";
@@ -21,7 +22,7 @@ export async function prepareScriptedRun(plan, input) {
     const cwd = path.resolve(input.cwd);
     const physicalCwd = await realpath(cwd);
     const projectRoot = await prepareSelectedOutputDirectory(path.dirname(physicalCwd), physicalCwd);
-    const hooks = input.hooks ?? {};
+    const deps = input.deps ?? {};
     const warnings = [];
     const clone = plan.subject.kind === "clone" ? plan.subject : undefined;
     const evidenceAppUrl = evidenceAppUrlOf(plan.subject);
@@ -42,7 +43,7 @@ export async function prepareScriptedRun(plan, input) {
         ? { kind: "provisioned-subject", evidenceOrigin: evidenceAppUrl }
         : { kind: "loopback" };
     const subjectEnvNames = [...(clone?.env ?? [])];
-    const env = hooks.env ?? process.env;
+    const env = input.env ?? process.env;
     const e2bApiKey = env.E2B_API_KEY?.trim() ?? "";
     const hasGithubToken = subjectEnvNames.includes("GITHUB_TOKEN");
     const redactRepoLabel = plan.residual.policies?.redactRepos ?? hasGithubToken;
@@ -61,33 +62,33 @@ export async function prepareScriptedRun(plan, input) {
         };
     }
     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(", ")}.`),
-            };
-        }
+    // The plan lists E2B_API_KEY and the subject env only for a live clone.
+    const missing = missingKeys(plan.requirements, env);
+    if (missing.length > 0) {
+        return {
+            ok: false,
+            result: failed("HUMANISH_SCRIPTED_LAB_KEYS_MISSING", `Live clone scripted-browser labs require ${missing.join(" and ")} (dry-run remains $0 and does not provision a subject). ${describeMissingKeys(missing, env)}`),
+        };
+    }
+    const unsetSubjectEnv = missingSubjectEnv(plan.requirements, env);
+    if (unsetSubjectEnv.length > 0) {
+        return {
+            ok: false,
+            result: failed("HUMANISH_SCRIPTED_LAB_SUBJECT_ENV_MISSING", `Subject env values missing for live clone scripted-browser lab: ${unsetSubjectEnv.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
+        // The step manifest is the "prompt" on this route; 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) {
+    // Live runs need a browser before any actuation (unless one is injected).
+    let browserCommand = deps.browserCommand;
+    if (!dryRun && !deps.launchBrowser && !browserCommand) {
         const resolved = await resolveBrowserCommand();
         if (!resolved) {
             return {
@@ -102,7 +103,7 @@ export async function prepareScriptedRun(plan, input) {
         setup: {
             cwd,
             physicalCwd,
-            hooks,
+            deps,
             warnings,
             failed,
             clone,

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

@@ -2,7 +2,8 @@ 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";
+import type { LabDeps } from "../../lab/lab-deps.js";
+import type { RunLabHomes } from "../../lab/run-lab-homes.js";
 type ScriptedCloneSubject = Extract<ScriptedPlan["subject"], {
     readonly kind: "clone";
 }>;
@@ -10,8 +11,10 @@ type ScriptedCloneSubject = Extract<ScriptedPlan["subject"], {
 export interface ScriptedSubjectInputs {
     plan: ScriptedPlan;
     clone: ScriptedCloneSubject;
-    hooks: ScriptedBrowserLabHooks;
-    env: Record<string, string | undefined>;
+    deps: LabDeps;
+    /** Runs after the subject sandbox exists and before provisioning. */
+    prepareDesktop?: NonNullable<RunLabHomes["prepareDesktop"]>;
+    env: Readonly<Record<string, string | undefined>>;
     e2bApiKey: string;
     runPaths: PreparedRunArtifactPaths;
     timeoutMs: number;
@@ -26,6 +29,8 @@ export interface ScriptedSubjectInputs {
 export declare class ScriptedSubject {
     sandboxId: string | undefined;
     killed: boolean;
+    /** The scrubbed release warning when the subject's release is unconfirmed. */
+    releaseWarning: string | undefined;
     commit: string | undefined;
     hostDigest: string | undefined;
     readonly stateStepRecords: RunSubjectStateStepRecord[];

package/dist/routes/scripted/subject.js

@@ -37,6 +37,8 @@ function hostOriginDigest(url) {
 export class ScriptedSubject {
     sandboxId;
     killed = false;
+    /** The scrubbed release warning when the subject's release is unconfirmed. */
+    releaseWarning;
     commit;
     hostDigest;
     stateStepRecords = [];
@@ -50,15 +52,15 @@ export class ScriptedSubject {
     }
     /** Acquires, provisions and serves the subject. Returns the tokenless getHost URL to drive. */
     async provision() {
-        const { plan, clone, hooks, env, e2bApiKey, runPaths, timeoutMs } = this.inputs;
+        const { plan, clone, deps, prepareDesktop, env, e2bApiKey, runPaths, timeoutMs } = this.inputs;
         const { subjectEnvNames, hasGithubToken, scrubKnownValues, now } = this.inputs;
         const requestTimeoutMs = e2bRequestTimeoutMs(env);
-        const timers = hooks.detachedTimers ?? {};
+        const timers = deps.detachedTimers ?? {};
         const subjectSandboxTimeoutMs = timeoutMs +
             SUBJECT_PROVISION_BUDGET_MS +
             (clone.state?.seed ?? []).reduce((sum, step) => sum + (step.timeoutMs ?? DEFAULT_STATE_STEP_TIMEOUT_MS), 0) +
             SANDBOX_TIMEOUT_BUFFER_MS;
-        const subjectModule = await (hooks.loadDesktopModule ?? loadE2BDesktopModule)();
+        const subjectModule = await (deps.desktopModule ?? loadE2BDesktopModule)();
         await validatePreparedRunArtifactPaths(runPaths);
         // The receipt is on disk before any work on the sandbox, so `humanish reclaim` can kill
         // it by exact id when this process dies mid-run; the finally block below only runs while
@@ -92,8 +94,8 @@ export class ScriptedSubject {
         this.sandboxId = subject.allocation.resourceId;
         this.createdAtMs = now();
         this.resources = await observeDesktopResources(subjectDesktop);
-        if (hooks.prepareDesktop) {
-            await hooks.prepareDesktop(subjectDesktop);
+        if (prepareDesktop) {
+            await prepareDesktop(subjectDesktop, { kind: "subject" });
             await validatePreparedRunArtifactPaths(runPaths);
         }
         this.commit = await provisionCloneSubject(e2bShell(subjectDesktop), {
@@ -137,6 +139,8 @@ export class ScriptedSubject {
         this.killed = reading.released;
         if (reading.warning)
             warnings.push(reading.warning);
+        if (!reading.released)
+            this.releaseWarning = reading.warning ?? "Subject sandbox release is unconfirmed.";
         // Without a kill method, or in E2B debug mode, no kill reached E2B, so there is no teardown
         // time to record.
         if (released.status !== "unconfirmed" || released.reason !== "release_unavailable")

package/dist/routes/scripted/surface-records.js

@@ -44,7 +44,7 @@ export function scriptedSurfaceRecords(context, surface, index, result, screensh
         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
+        // 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: {

package/dist/routes/scripted/surface-sessions.d.ts

@@ -1,11 +1,11 @@
 import { type ScriptedBrowserSessionOptions, type ScriptedBrowserSessionResult } from "../../actors/scripted-browser/actor.js";
 import type { ScriptedPlan } from "../../lab/plan-types.js";
 import { type PreparedRunArtifactPaths } from "../../run/paths.js";
-import type { ScriptedBrowserLabHooks } from "./types.js";
+import type { LabDeps } from "../../lab/lab-deps.js";
 /** One session per surface, in parallel. */
 export declare function runScriptedSessions(session: Required<Pick<ScriptedBrowserSessionOptions, "appUrl" | "evidenceAppUrl" | "urlPolicy" | "journey" | "persona" | "timeoutMs" | "artifactRoot">>, run: {
     surfaces: ScriptedPlan["surfaces"];
-    hooks: ScriptedBrowserLabHooks;
+    deps: LabDeps;
     browserCommand: string | undefined;
     runPaths: PreparedRunArtifactPaths;
 }): Promise<ScriptedBrowserSessionResult[]>;

package/dist/routes/scripted/surface-sessions.js

@@ -7,8 +7,8 @@ import { validateScriptedSessionResult } from "./session-result.js";
 /** One session per surface, in parallel. */
 export function runScriptedSessions(session, run) {
     const { appUrl, evidenceAppUrl, urlPolicy, journey, persona, timeoutMs, artifactRoot } = session;
-    const { surfaces, hooks, browserCommand, runPaths } = run;
-    const runSession = hooks.runSession;
+    const { surfaces, deps, browserCommand, runPaths } = run;
+    const runSession = deps.runScriptedSession;
     return Promise.all(surfaces.map((surface) => {
         const sessionOptions = {
             appUrl,
@@ -20,8 +20,8 @@ export function runScriptedSessions(session, run) {
             timeoutMs,
             artifactRoot,
             ...(browserCommand === undefined ? {} : { browserCommand }),
-            ...(hooks.launchBrowser === undefined ? {} : { launchBrowser: hooks.launchBrowser }),
-            ...(hooks.now === undefined ? {} : { now: hooks.now }),
+            ...(deps.launchBrowser === undefined ? {} : { launchBrowser: deps.launchBrowser }),
+            ...(deps.now === undefined ? {} : { now: deps.now }),
         };
         return runSession
             ? runSession(sessionOptions).then(async (result) => {