humanish 0.106.1 → 0.108.0

package/dist/routes/scripted/route.js

@@ -10,7 +10,7 @@
 // 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 provenance: 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.
@@ -24,24 +24,24 @@ 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";
 import { ScriptedSubject } from "./subject.js";
 import { runScriptedSessions, writeSurfaceTraces } from "./surface-sessions.js";
-import { SCRIPTED_BROWSER_LAB_SCHEMA, } from "./types.js";
+import {} from "./types.js";
+import { studyResultIdentity } from "../../run/study-result.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;
+    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);
@@ -57,10 +57,9 @@ export async function scriptedLabRefusal(options, refusal) {
     const actorType = config.actors[0]?.type ?? "";
     if (refusal.beforeScope)
         return {
-            schema: SCRIPTED_BROWSER_LAB_SCHEMA,
+            ...studyResultIdentity("scripted", config.id),
             ok: false,
             cwd,
-            labId: config.id,
             actor: actorType,
             dryRun,
             runId: options.runId ?? "not-created",
@@ -73,10 +72,9 @@ export async function scriptedLabRefusal(options, refusal) {
     const physicalCwd = await realpath(cwd);
     await prepareSelectedOutputDirectory(path.dirname(physicalCwd), physicalCwd);
     const refused = {
-        schema: SCRIPTED_BROWSER_LAB_SCHEMA,
+        ...studyResultIdentity("scripted", config.id),
         ok: false,
         cwd,
-        labId: config.id,
         actor: refusal.actor ?? actorType,
         appUrl: refusal.appUrl ?? config.subject.appUrl ?? "",
         dryRun,
@@ -86,7 +84,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 +95,6 @@ export function admitScriptedPlan(plan, input) {
         ok: true,
         run: async () => ({
             route: "scripted",
-            backend: "scripted",
             result: await runScriptedPlan(plan, input),
         }),
     };
@@ -112,7 +109,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 +127,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 +145,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 +154,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 +173,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.
@@ -26,7 +26,7 @@ export async function resolveScriptedScenario(projectRoot, ref) {
         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.`,
+                message: `scenario.ref must stay inside the project directory, and "${trimmed}" does not: the run records it relative to the project.`,
             };
         }
         source = relative.split(path.sep).join("/");
@@ -80,7 +80,7 @@ export async function resolveScriptedScenario(projectRoot, ref) {
     if (!parsed.journey) {
         return {
             ok: false,
-            message: `${source} declares no executable browser steps — the scripted-browser actor needs a scenario with browser.steps.`,
+            message: `${source} declares no browser steps, and the scripted-browser actor needs a scenario with browser.steps.`,
         };
     }
     return { ok: true, journey: parsed.journey, source, sourceDigest };

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,13 +2,15 @@
 // 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";
 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";
+import {} from "./types.js";
+import { studyResultIdentity } from "../../run/study-result.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;
@@ -21,15 +23,14 @@ 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);
     const failed = (code, message) => ({
-        schema: SCRIPTED_BROWSER_LAB_SCHEMA,
+        ...studyResultIdentity("scripted", plan.labId),
         ok: false,
         cwd,
-        labId: plan.labId,
         actor: plan.actor,
         appUrl: evidenceAppUrl,
         dryRun,
@@ -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;
@@ -57,42 +58,42 @@ export async function prepareScriptedRun(plan, input) {
     if (!scenario.ok) {
         return {
             ok: false,
-            result: failed("HUMANISH_SCRIPTED_LAB_SCENARIO_INVALID", scenario.message),
+            result: failed("HUMANISH_SCRIPTED_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(", ")}.`),
-            };
-        }
+    // 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_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_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 {
                 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."),
+                result: failed("HUMANISH_SCRIPTED_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;
@@ -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
@@ -73,7 +75,7 @@ export class ScriptedSubject {
                     mode: "scripted-browser-lab",
                     tool: "humanish",
                     labId: plan.labId,
-                    role: "subject",
+                    kind: "subject",
                     actor: plan.actor,
                 },
                 ...(subjectEnvNames.length > 0
@@ -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

@@ -18,7 +18,7 @@ export function scriptedSurfaceRecords(context, surface, index, result, screensh
             : "contract_proof_only";
     const reason = result?.reason ??
         context.sessionError ??
-        "Contract bundle only: dry-run pinned the scenario contract without launching a browser or touching the subject app.";
+        "Dry run: the scenario was pinned without launching a browser or touching the subject app.";
     const simulation = participantRecord(ids, index + 1, {
         personaId: context.persona.id,
         scenarioId: context.journey.scenarioId,
@@ -31,20 +31,20 @@ export function scriptedSurfaceRecords(context, surface, index, result, screensh
             ? `Scripted-browser actor (${context.actorId}) replayed ${context.journey.scenarioId} on the ${surface.id} surface; ${result.completionReason}.`
             : context.sessionError !== undefined
                 ? `Scripted lab failed before a terminal session verdict: ${context.sessionError}`
-                : `Contract participant for the scripted-browser actor (${context.actorId}) against ${context.appUrl}.`,
+                : `Scripted-browser actor (${context.actorId}) against ${context.appUrl}; no session ran.`,
         startedAt: context.createdAt,
         updatedAt: result?.capture.capturedAt ?? context.createdAt,
     });
     const stream = participantStream(ids, {
         kind: "browser",
-        label: `${surface.label} — ${context.labId}`,
+        label: `${surface.label} · ${context.labId}`,
         status,
         transport: "snapshot",
         updatedAt: result?.capture.capturedAt ?? context.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
+        // 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) => {

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

@@ -1,48 +1,31 @@
 import type { ActorCompletionReason, ActorStatus } from "../../actors/contract.js";
-import type { ScriptedBrowserSessionOptions, ScriptedBrowserSessionResult } from "../../actors/scripted-browser/actor.js";
-import type { ScriptedBrowserLaunchArgs, ScriptedBrowserLike } from "../../actors/scripted-browser/types.js";
-import type { AutomaticAnalysisHooks, AutomaticAnalysisResult } from "../../analysis/automatic-completion.js";
+import type { LabEvent } from "../../lab/run-lab-events.js";
+import type { AutomaticAnalysisResult } from "../../analysis/automatic-completion.js";
 import type { LabConfig } from "../../lab/types.js";
-import { renderObserver, type ObserverResult } from "../../observer/render.js";
+import type { ObserverResult } from "../../observer/render.js";
 import type { RunSubjectProvenance } from "../../run/bundle.js";
-import type { RunLabProvenance } from "../../run/status.js";
-import type { DetachedTimers } from "../../substrates/detached.js";
-import type { E2BDesktopModule, E2BDesktopSandbox } from "../../substrates/e2b/sdk.js";
-export declare const SCRIPTED_BROWSER_LAB_SCHEMA = "humanish.scripted-lab-result.v1";
-/**
- * Library-level hooks: DI seams so CI drives the full path (real engine, real projection)
- * with a fake browser at zero spend, plus the production browser resolution override.
- */
-export interface ScriptedBrowserLabHooks {
-    runSession?: (options: ScriptedBrowserSessionOptions) => Promise<ScriptedBrowserSessionResult>;
-    /** Injected browser factory — forwarded to every session; skips browser-binary resolution. */
-    launchBrowser?: (args: ScriptedBrowserLaunchArgs) => Promise<ScriptedBrowserLike>;
-    /** Test/library env seam; CLI passes process.env. Values are scrubbed, names only persist. */
-    env?: Record<string, string | undefined>;
-    /** E2B DI seam for clone × e2b-desktop × scripted-browser. */
-    loadDesktopModule?: () => Promise<E2BDesktopModule>;
-    /** Optional adopter hook after subject sandbox creation, before clone provisioning. */
-    prepareDesktop?: (desktop: E2BDesktopSandbox) => Promise<void>;
-    /** Detached-step timers for deterministic tests around clone/seed/start provisioning. */
-    detachedTimers?: DetachedTimers;
-    /** Override the resolved browser binary (tests; operators use HUMANISH_BROWSER_COMMAND). */
-    browserCommand?: string;
-    renderObserverFn?: typeof renderObserver;
-    now?: () => number;
-}
+import type { LabDeps } from "../../lab/lab-deps.js";
+import type { RunLabHomes } from "../../lab/run-lab-homes.js";
+import { type StudyResultIdentity } from "../../run/study-result.js";
 /** What a scripted run takes besides its plan. The plan carries the config, dry run and lab. */
 export type ScriptedRunInput = Omit<RunScriptedBrowserLabOptions, "config" | "dryRun" | "lab">;
 export interface RunScriptedBrowserLabOptions {
-    automaticAnalysis?: AutomaticAnalysisHooks;
-    /** Which manifest produced this run (#455); threaded into the status record + bundle. */
-    lab?: RunLabProvenance;
+    /** Cancels post-run analysis only. */
+    analysisSignal?: AbortSignal;
+    /** Reports the analysis window to onEvent; built by normalizeRunLabOptions. */
+    emit?: (event: LabEvent) => void;
     cwd: string;
     config: LabConfig;
     /** Resolved upstream (scenario.mode + CLI override); defaults safe (dry-run). */
     dryRun: boolean;
     open?: boolean;
     runId?: string;
-    hooks?: ScriptedBrowserLabHooks;
+    /** Keys and subject env for the run. Defaults to process.env. Values are scrubbed; names persist. */
+    env?: Readonly<Record<string, string | undefined>>;
+    /** Runs after a clone subject's sandbox exists and before provisioning. */
+    prepareDesktop?: NonNullable<RunLabHomes["prepareDesktop"]>;
+    /** Test seams: the browser, the session, the E2B module, timers, the renderer and the clock. */
+    deps?: LabDeps;
 }
 interface ScriptedBrowserLabSession {
     surface: string;
@@ -51,14 +34,12 @@ interface ScriptedBrowserLabSession {
     reason: string;
     screenshots: number;
 }
-export interface ScriptedBrowserLabResult extends AutomaticAnalysisResult {
-    schema: typeof SCRIPTED_BROWSER_LAB_SCHEMA;
-    /** True when the bundle verified AND (dry-run, or every session reached a terminal verdict
-     * without a harness error). The subject failing the script is successful EVIDENCE, not a lab
-     * failure. */
+export interface ScriptedBrowserLabResult extends AutomaticAnalysisResult, StudyResultIdentity<"scripted"> {
+    /** True when the bundle verified and (dry-run, or every session reached a terminal verdict
+     * without a harness error). The subject failing the script is successful evidence, and the lab
+     * does not fail for it. */
     ok: boolean;
     cwd: string;
-    labId: string;
     /** The registry-resolved actor id that ran (or would run) the sessions. */
     actor: string;
     appUrl: string;
@@ -81,7 +62,7 @@ export interface ScriptedBrowserLabResult extends AutomaticAnalysisResult {
     observer?: ObserverResult;
     warnings: string[];
     error?: {
-        code: "HUMANISH_LAB_ANALYSIS_INVALID" | "HUMANISH_LAB_TASKS_UNSUPPORTED" | "HUMANISH_LAB_OPTION_CONFLICT" | "HUMANISH_LAB_OPTION_UNSUPPORTED" | "HUMANISH_SCRIPTED_LAB_FAILED" | "HUMANISH_SCRIPTED_LAB_ACTOR_UNSUPPORTED" | "HUMANISH_SCRIPTED_LAB_SCENARIO_INVALID" | "HUMANISH_SCRIPTED_LAB_SUBJECT_UNSAFE" | "HUMANISH_SCRIPTED_LAB_BROWSER_MISSING" | "HUMANISH_SCRIPTED_LAB_KEYS_MISSING" | "HUMANISH_SCRIPTED_LAB_SUBJECT_ENV_MISSING" | "HUMANISH_SCRIPTED_LAB_GETHOST_UNAVAILABLE" | "HUMANISH_RUN_ID_IN_USE";
+        code: "HUMANISH_STUDY_ANALYSIS_INVALID" | "HUMANISH_STUDY_TASKS_UNSUPPORTED" | "HUMANISH_STUDY_OPTION_UNSUPPORTED" | "HUMANISH_SCRIPTED_FAILED" | "HUMANISH_SCRIPTED_ACTOR_UNSUPPORTED" | "HUMANISH_SCRIPTED_SCENARIO_INVALID" | "HUMANISH_SCRIPTED_SUBJECT_UNSAFE" | "HUMANISH_SCRIPTED_BROWSER_MISSING" | "HUMANISH_SCRIPTED_KEYS_MISSING" | "HUMANISH_SCRIPTED_SUBJECT_ENV_MISSING" | "HUMANISH_SCRIPTED_GETHOST_UNAVAILABLE" | "HUMANISH_RUN_ID_IN_USE";
         message: string;
     };
 }

package/dist/routes/scripted/types.js

@@ -1,3 +1,2 @@
-// The scripted-browser lab's schema constant, library hooks, options and result types.
-import { renderObserver } from "../../observer/render.js";
-export const SCRIPTED_BROWSER_LAB_SCHEMA = "humanish.scripted-lab-result.v1";
+// The scripted-browser lab's schema constant, options and result types.
+import {} from "../../run/study-result.js";